248 lines
4.6 KiB
Markdown
248 lines
4.6 KiB
Markdown
# 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.
|