209 lines
4.7 KiB
Plaintext
209 lines
4.7 KiB
Plaintext
# OnRamp SDK
|
||
|
||
The **OnRamp SDK** provides supported libraries for integrating external applications with the OnRamp platform.
|
||
|
||
Current capabilities include:
|
||
|
||
* Accessing the **OnRamp API**
|
||
* Receiving **real-time Shop Monitor events** via WebSockets
|
||
* Running **registered OnRamp API queries**
|
||
|
||
The SDK is distributed via **NuGet** to allow deterministic versioning and updateable integrations.
|
||
|
||
This approach enables applications to interact with OnRamp **without requiring direct database access**, which is particularly important for hosted or cloud environments.
|
||
|
||
---
|
||
|
||
# Installation
|
||
|
||
Add the OnRamp SDK NuGet repository:
|
||
|
||
```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:
|
||
|
||
```
|
||
Package Source: onrampsdk
|
||
```
|
||
|
||
Packages can then be installed using standard NuGet workflows in Visual Studio or via the .NET CLI.
|
||
|
||
---
|
||
|
||
# Overview
|
||
|
||
Applications integrating with OnRamp typically perform the following steps:
|
||
|
||
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
|
||
|
||
Incoming WebSocket messages function similarly to **interrupt events**. They are delivered with minimal latency when Shop Monitor activity occurs.
|
||
|
||
Example event types include:
|
||
|
||
* Work Order Login
|
||
* Work Order Logout
|
||
* Cycle Start
|
||
* Cycle Complete
|
||
* Device button events
|
||
|
||
Applications can respond to these events by retrieving additional information through the OnRamp API.
|
||
|
||
---
|
||
|
||
# Example Architecture
|
||
|
||
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**.
|
||
|
||
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
|
||
|
||
Any application listening with that Socket ID will receive the event messages.
|
||
|
||
---
|
||
|
||
# API Queries
|
||
|
||
API queries must be registered in:
|
||
|
||
```
|
||
S5011 – API Queries
|
||
```
|
||
|
||
Supported query types:
|
||
|
||
* `SELECT`
|
||
* `UPDATE`
|
||
|
||
In most integrations, **SELECT queries are sufficient**. UPDATE queries should be used cautiously.
|
||
|
||
---
|
||
|
||
# Query Parameters
|
||
|
||
Queries use **Handlebars-style parameters**.
|
||
|
||
Example:
|
||
|
||
```sql
|
||
SELECT woo_oper, woo_qty_rep
|
||
FROM wo_oper
|
||
WHERE woo_nbr = '{{p:wonum}}'
|
||
```
|
||
|
||
`p:wonum` is a parameter passed 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)
|
||
|
||
' QL-10000006
|
||
Dim rstDataAllOps = api.runQuery("QL-10000006", allOpsArgs)
|
||
|
||
If rstDataAllOps.RecordCount > 0 Then
|
||
Do Until rstDataAllOps.EOF
|
||
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:
|
||
|
||
* `RecordCount`
|
||
* `EOF`
|
||
* `MoveNext()`
|
||
* Column access via field name
|
||
|
||
---
|
||
|
||
# Query Performance Recommendations
|
||
|
||
For optimal performance:
|
||
|
||
* Avoid returning very large datasets
|
||
* Do not use `SELECT *`
|
||
* Specify explicit column names
|
||
* Limit queries to only the data required by the application
|
||
|
||
Example (recommended):
|
||
|
||
```sql
|
||
SELECT pt_part, pt_desc
|
||
FROM pt_mstr
|
||
```
|
||
|
||
Example (not recommended):
|
||
|
||
```sql
|
||
SELECT *
|
||
FROM pt_mstr
|
||
```
|
||
|
||
---
|
||
|
||
# Use Cases
|
||
|
||
Common uses for the SDK include:
|
||
|
||
* Shop Monitor automation
|
||
* Production event processing
|
||
* Device integrations
|
||
* External analytics services
|
||
* Integration with external systems
|
||
* Cloud-hosted integrations where database access is unavailable
|
||
|
||
---
|
||
|
||
# Future Expansion
|
||
|
||
The SDK is designed to support additional OnRamp platform integration capabilities over time, including:
|
||
|
||
* Additional event channels
|
||
* Extended API functionality
|
||
* Additional integration services
|
||
|
||
---
|
||
|
||
If you'd like, I can also help you add two sections that **good SDK repos almost always include but people forget**:
|
||
|
||
* **Minimal working example (full program)**
|
||
* **Event message structure / enum definitions**
|
||
|
||
Those make the repo dramatically easier for developers to adopt.
|