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