# OnRamp SDK

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:

- Access to the **OnRamp API**
- Real-time **Shop Monitor events** via WebSockets
- Execution of **registered API queries**
- Event-driven application integrations

Typical integration scenarios include:

- Shop Monitor automation
- Production event processing
- Device integrations
- External analytics
- Cloud-hosted services

---

# Installation

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 appear under:

```
Package Source: onrampsdk
```

Packages can then be installed using standard NuGet workflows.

Example:

```bash
dotnet add package ORPublicApiRefCore
dotnet add package ORSocketsCore
```

---

# Quick Start Example

The following console example demonstrates a basic integration pattern:

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

```vb
Imports System.Threading
Imports ORPublicApiRefCore
Imports ORSocketsCore

Module Program

    Private api As OnRampAPI
    Private socketClient As ORSocketClient
    Private quitEvent As ManualResetEvent = New ManualResetEvent(False)

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

---

# Shop Monitor Events

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**
3. Use the same ID in the application

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

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 provided by the client application.

---

# Example Query Execution

```vb
Dim args As New Dictionary(Of String, String)
args.Add("wonum", woNum)

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"))
        rstDataAllOps.MoveNext()
    Loop
End If
```

The returned result set exposes a **recordset-style interface** with:

- `RecordCount`
- `EOF`
- `MoveNext()`
- column access by name

---

# Query Performance Guidelines

For best performance:

- Avoid returning large datasets
- Do not use `SELECT *`
- Specify explicit columns
- Limit queries to only the required data

Recommended:

```sql
SELECT pt_part, pt_desc
FROM pt_mstr
```

Avoid:

```sql
SELECT *
FROM pt_mstr
```

---

# Example Architecture

Typical integrations run as:

- 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 integration capabilities including:

- additional event channels
- expanded API functionality
- additional integration services

---

# License

Refer to the repository license for usage terms.