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