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

221
README
View File

@@ -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.