onramp-sdk/README.md

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:

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:

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

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:

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

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:

SELECT pt_part, pt_desc
FROM pt_mstr

Avoid:

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.