OnRampSDK/onramp-sdk
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Changed readme

Browse Source
This commit is contained in:
ccurran
2026-03-08 09:48:58 -04:00
parent 398d35229c
commit e3c0d75b33
3 changed files with 141 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -7,3 +7,4 @@
/prjOnRampAPI/prjOnRampAPI/obj /prjOnRampAPI/prjOnRampAPI/obj
/prjOnRampAPI/obj /prjOnRampAPI/obj
/prjOnRampAPI/bin/Debug/net8.0 /prjOnRampAPI/bin/Debug/net8.0
/prjOnRampAPI/.vs/ProjectEvaluation

221
README
View File

@@ -1,98 +1,131 @@
# OnRamp SDK # 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: Current capabilities include:
* Accessing the **OnRamp API** - Access to the **OnRamp API**
* Receiving **real-time Shop Monitor events** via WebSockets - Real-time **Shop Monitor events** via WebSockets
* Running **registered OnRamp API queries** - 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 # Installation
Add the OnRamp SDK NuGet repository: Add the OnRamp SDK NuGet feed:
```bash ```bash
dotnet nuget add source https://git.onramp-solutions.com/api/packages/OnRampSDK/nuget/index.json --name onrampsdk 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 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** 1. Connect to the OnRamp API
2. Connect to the **OnRamp WebSocket service** 2. Establish a WebSocket connection
3. Register a **Socket ID** 3. Register a Socket ID
4. Receive **Shop Monitor events** 4. Receive Shop Monitor events
5. Execute **API queries** to retrieve or process related data 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 Private api As OnRampAPI
* Work Order Logout Private socketClient As ORSocketClient
* Cycle Start Private quitEvent As ManualResetEvent = New ManualResetEvent(False)
* Cycle Complete
* Device button events
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: Shop Monitor devices send events through a configured **Socket ID**.
* 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**.
To configure a device: To configure a device:
1. Open **S1280 Device Shop Monitor** 1. Open **S1280 Device Shop Monitor**
2. Set the **Process ID / Socket ID** to the value expected by the application 2. Set the **Process ID / Socket ID**
3. The application registers with this same 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
API queries must be registered in: Queries must be registered in:
``` ```
S5011 API Queries S5011 API Queries
@@ -100,8 +133,8 @@ S5011 API Queries
Supported query types: Supported query types:
* `SELECT` - `SELECT`
* `UPDATE` - `UPDATE`
In most integrations, **SELECT queries are sufficient**. UPDATE queries should be used cautiously. 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}}' 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 Query Execution
Example code for executing a query through the API:
```vb ```vb
' Get all operations for a work order Dim args As New Dictionary(Of String, String)
Dim allOpsArgs As New Dictionary(Of String, String) args.Add("wonum", woNum)
allOpsArgs.Add("wonum", woNum)
' QL-10000006 Dim rstDataAllOps = api.runQuery("Q-GET-WO-OPS", args)
Dim rstDataAllOps = api.runQuery("QL-10000006", allOpsArgs)
If rstDataAllOps.RecordCount > 0 Then If rstDataAllOps.RecordCount > 0 Then
Do Until rstDataAllOps.EOF 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() rstDataAllOps.MoveNext()
Loop Loop
End If 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` - `RecordCount`
* `EOF` - `EOF`
* `MoveNext()` - `MoveNext()`
* Column access via field name - column access by name
--- ---
# Query Performance Recommendations # Query Performance Guidelines
For optimal performance: For best performance:
* Avoid returning very large datasets - Avoid returning large datasets
* Do not use `SELECT *` - Do not use `SELECT *`
* Specify explicit column names - Specify explicit columns
* Limit queries to only the data required by the application - Limit queries to only the required data
Example (recommended): Recommended:
```sql ```sql
SELECT pt_part, pt_desc SELECT pt_part, pt_desc
FROM pt_mstr FROM pt_mstr
``` ```
Example (not recommended): Avoid:
```sql ```sql
SELECT * 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 - console applications
* Production event processing - background services
* Device integrations - device integration processes
* External analytics services
* Integration with external systems The application:
* Cloud-hosted integrations where database access is unavailable
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 # 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 - additional event channels
* Extended API functionality - expanded API functionality
* Additional integration services - additional integration services
---
# License
Refer to the repository license for usage terms.

7
prjOnRampAPI.sln
View File

@@ -1,10 +1,15 @@
Microsoft Visual Studio Solution File, Format Version 12.00 Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17 # Visual Studio Version 17
VisualStudioVersion = 17.12.35707.178 d17.12 VisualStudioVersion = 17.12.35707.178
MinimumVisualStudioVersion = 10.0.40219.1 MinimumVisualStudioVersion = 10.0.40219.1
Project("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "prjOnRampAPI", "prjOnRampAPI\prjOnRampAPI.vbproj", "{392D651B-778A-4082-80D9-05FFFD1916A1}" Project("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "prjOnRampAPI", "prjOnRampAPI\prjOnRampAPI.vbproj", "{392D651B-778A-4082-80D9-05FFFD1916A1}"
EndProject EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{A95BA3CB-1B3C-4D31-8C3E-6AD39F4319EF}"
ProjectSection(SolutionItems) = preProject
README = README
EndProjectSection
EndProject
Global Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU Debug|Any CPU = Debug|Any CPU