# 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