diff --git a/.gitignore b/.gitignore index cab3eb6..5d6a5cd 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ /prjOnRampAPI/prjOnRampAPI/obj /prjOnRampAPI/obj /prjOnRampAPI/bin/Debug/net8.0 +/prjOnRampAPI/.vs/ProjectEvaluation diff --git a/README b/README index 1a837bd..95e6a6d 100644 --- a/README +++ b/README @@ -1,98 +1,131 @@ # OnRamp SDK -The **OnRamp SDK** provides supported libraries for integrating external applications with the OnRamp platform. +The **OnRamp SDK** provides supported libraries for integrating external applications with the **OnRamp platform**. + +The SDK allows applications to interact with OnRamp **without requiring direct database access**, enabling integrations for: + +- hosted environments +- cloud deployments +- external services +- device integrations + +The SDK is distributed via **NuGet** to provide deterministic versioning and controlled upgrades. + +--- + +# Features Current capabilities include: -* Accessing the **OnRamp API** -* Receiving **real-time Shop Monitor events** via WebSockets -* Running **registered OnRamp API queries** +- Access to the **OnRamp API** +- Real-time **Shop Monitor events** via WebSockets +- Execution of **registered API queries** +- Event-driven application integrations -The SDK is distributed via **NuGet** to allow deterministic versioning and updateable integrations. +Typical integration scenarios include: -This approach enables applications to interact with OnRamp **without requiring direct database access**, which is particularly important for hosted or cloud environments. +- Shop Monitor automation +- Production event processing +- Device integrations +- External analytics +- Cloud-hosted services --- # Installation -Add the OnRamp SDK NuGet repository: +Add the OnRamp SDK NuGet feed: ```bash dotnet nuget add source https://git.onramp-solutions.com/api/packages/OnRampSDK/nuget/index.json --name onrampsdk ``` -After adding the source, packages will be available under: +After adding the source, packages will appear under: ``` Package Source: onrampsdk ``` -Packages can then be installed using standard NuGet workflows in Visual Studio or via the .NET CLI. +Packages can then be installed using standard NuGet workflows. + +Example: + +```bash +dotnet add package ORPublicApiRefCore +dotnet add package ORSocketsCore +``` --- -# Overview +# Quick Start Example -Applications integrating with OnRamp typically perform the following steps: +The following console example demonstrates a basic integration pattern: -1. Connect to the **OnRamp API** -2. Connect to the **OnRamp WebSocket service** -3. Register a **Socket ID** -4. Receive **Shop Monitor events** -5. Execute **API queries** to retrieve or process related data +1. Connect to the OnRamp API +2. Establish a WebSocket connection +3. Register a Socket ID +4. Receive Shop Monitor events +5. Execute API queries -Incoming WebSocket messages function similarly to **interrupt events**. They are delivered with minimal latency when Shop Monitor activity occurs. +```vb +Imports System.Threading +Imports ORPublicApiRefCore +Imports ORSocketsCore -Example event types include: +Module Program -* Work Order Login -* Work Order Logout -* Cycle Start -* Cycle Complete -* Device button events + Private api As OnRampAPI + Private socketClient As ORSocketClient + Private quitEvent As ManualResetEvent = New ManualResetEvent(False) -Applications can respond to these events by retrieving additional information through the OnRamp API. + Sub Main(args As String()) + + ' OnRamp root endpoint + Dim envUrl As String = "https://onramp.site.com/PROD" + + ' Register for Shop Monitor events + socketClient = New ORSocketClient(envUrl, "SHOPMONITORCLIENT", "SITE1001") + + AddHandler socketClient.OnMessageReceived, AddressOf SocketMessageRec + AddHandler socketClient.OnLog, AddressOf SocketLog + + api = New OnRampAPI(envUrl) + + ' API authentication + api.APILogin("api_user", "api_password") + + WaitForConsoleExit() + + End Sub +``` --- -# Example Architecture +# Shop Monitor Events -A typical implementation: - -* Launches an application (console app, service, or background process) -* Connects to the OnRamp API -* Establishes a WebSocket connection -* Registers a **Socket ID** -* Waits indefinitely for incoming Shop Monitor events - -The application remains active and processes events until it is terminated. - -Multiple deployment models are possible: - -* A **single application handling all devices** -* Applications **per device** -* Applications **per event type** - ---- - -# Shop Monitor Integration - -Shop Monitor devices trigger events through a configured **Socket ID**. +Shop Monitor devices send events through a configured **Socket ID**. To configure a device: -1. Open **S1280 Device Shop Monitor** -2. Set the **Process ID / Socket ID** to the value expected by the application -3. The application registers with this same Socket ID +1. Open **S1280 Device Shop Monitor** +2. Set the **Process ID / Socket ID** +3. Use the same ID in the application -Any application listening with that Socket ID will receive the event messages. +Example event types include: + +- Work Order Login +- Work Order Logout +- Cycle Start +- Cycle Complete +- Device button events + +Incoming WebSocket messages behave similarly to **interrupt events**, allowing applications to respond immediately to shop floor activity. --- # API Queries -API queries must be registered in: +Queries must be registered in: ``` S5011 API Queries @@ -100,8 +133,8 @@ S5011 API Queries Supported query types: -* `SELECT` -* `UPDATE` +- `SELECT` +- `UPDATE` In most integrations, **SELECT queries are sufficient**. UPDATE queries should be used cautiously. @@ -119,56 +152,54 @@ FROM wo_oper WHERE woo_nbr = '{{p:wonum}}' ``` -`p:wonum` is a parameter passed by the client application. +`p:wonum` is provided by the client application. --- # Example Query Execution -Example code for executing a query through the API: - ```vb -' Get all operations for a work order -Dim allOpsArgs As New Dictionary(Of String, String) -allOpsArgs.Add("wonum", woNum) +Dim args As New Dictionary(Of String, String) +args.Add("wonum", woNum) -' QL-10000006 -Dim rstDataAllOps = api.runQuery("QL-10000006", allOpsArgs) +Dim rstDataAllOps = api.runQuery("Q-GET-WO-OPS", args) If rstDataAllOps.RecordCount > 0 Then Do Until rstDataAllOps.EOF - Console.WriteLine(rstDataAllOps("woo_oper") + " - QtyRep:" & rstDataAllOps("woo_qty_rep")) + Console.WriteLine(rstDataAllOps("woo_oper") & + " - QtyRep:" & + rstDataAllOps("woo_qty_rep")) rstDataAllOps.MoveNext() Loop End If ``` -The returned result set exposes a familiar **recordset-style interface**, allowing iteration using: +The returned result set exposes a **recordset-style interface** with: -* `RecordCount` -* `EOF` -* `MoveNext()` -* Column access via field name +- `RecordCount` +- `EOF` +- `MoveNext()` +- column access by name --- -# Query Performance Recommendations +# Query Performance Guidelines -For optimal performance: +For best performance: -* Avoid returning very large datasets -* Do not use `SELECT *` -* Specify explicit column names -* Limit queries to only the data required by the application +- Avoid returning large datasets +- Do not use `SELECT *` +- Specify explicit columns +- Limit queries to only the required data -Example (recommended): +Recommended: ```sql SELECT pt_part, pt_desc FROM pt_mstr ``` -Example (not recommended): +Avoid: ```sql SELECT * @@ -177,24 +208,40 @@ FROM pt_mstr --- -# Use Cases +# Example Architecture -Common uses for the SDK include: +Typical integrations run as: -* Shop Monitor automation -* Production event processing -* Device integrations -* External analytics services -* Integration with external systems -* Cloud-hosted integrations where database access is unavailable +- console applications +- background services +- device integration processes + +The application: + +1. Starts +2. Connects to OnRamp +3. Registers a socket +4. Waits for events +5. Processes events until shutdown + +Deployment models include: + +- one service handling all devices +- device-specific applications +- event-specific services --- # Future Expansion -The SDK is designed to support additional OnRamp platform integration capabilities over time, including: +The SDK is designed to support additional integration capabilities including: -* Additional event channels -* Extended API functionality -* Additional integration services +- additional event channels +- expanded API functionality +- additional integration services +--- + +# License + +Refer to the repository license for usage terms. diff --git a/prjOnRampAPI.sln b/prjOnRampAPI.sln index d5e78f5..4c68191 100644 --- a/prjOnRampAPI.sln +++ b/prjOnRampAPI.sln @@ -1,10 +1,15 @@  Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio Version 17 -VisualStudioVersion = 17.12.35707.178 d17.12 +VisualStudioVersion = 17.12.35707.178 MinimumVisualStudioVersion = 10.0.40219.1 Project("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "prjOnRampAPI", "prjOnRampAPI\prjOnRampAPI.vbproj", "{392D651B-778A-4082-80D9-05FFFD1916A1}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{A95BA3CB-1B3C-4D31-8C3E-6AD39F4319EF}" + ProjectSection(SolutionItems) = preProject + README = README + EndProjectSection +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU