Getting Started

This section explains how to send JSON-formatted messages to the ScaleOut Digital Twins™ service using REST APIs.

Note

All API methods require an API key for authentication. To use this REST API, please first see API Keys.

Configuration

Set Database Connection String

Modify the configuration file to set the database connection string used to connect to ScaleOut Active Caching databases. First, copy the “DatabaseConfiguration” section from your WebService.Api configuration file.

Windows: "C:\Program Files\ScaleOut_Software\StateServer\ActiveCachingWebUI\WebService.Api\appsettings.windows.json".
Linux: /usr/lib/soss-ac/soss-ac-web/appsettings.linux.json.

Next, modify the “DatabaseConfiguration” section in the messaging API configuration file to paste in the database configuration from your WebService.Api configuration file:

Windows: "C:\Program Files\ScaleOut_Software\StateServer\ActiveCachingWebUI\Messaging.Api\appsettings.windows.json".
Linux: /usr/lib/soss-ac/soss-ac-msg/appsettings.linux.json.

Enable the REST service

The REST Messaging service is installed by default on all ScaleOut StateServer hosts. It is not started by default, so run the following commands to start it:

net start soss-ac-msg

sudo systemctl start soss-ac-msg

The REST Messaging service will start listening on port 8801.

Note

if you enable the REST Messaging service on all hosts, you can use a load balancer to distribute incoming messages across all hosts.

Sending a Message

Once your real-time digital twin model is deployed and your API key has been created, an HTTP client can be used to send messages to specific real-time digital twin instances. For example, to send a temperature reading from a wind turbine to a real-time digital twin instance identified as “turbine1” of a model called “windTurbine”, you could use curl from a bash shell as follows:

curl -X POST "https://realtimetwinapi.scaleoutsoftware.com/api/v1/Messages/windTurbine/turbine1?apiKey=1234567890ABCDEF" -H "Content-Type: application/json" -d "[{ 'temp': 65, 'timestamp': $(date +%s) }]"

Here is an example of using Python to make the same request:

import requests
import time
requests.post('https://realtimetwinapi.scaleoutsoftware.com/api/v1/Messages/windTurbine/turbine1?apiKey=1234567890ABCDEF', json={"temp": "65", "timestamp": time.time()})

Important

The JSON messages you send to the REST API must match the message type(s) that you defined in your Java/C# message-processing project. If your message-handling code on relies on special JSON features (like C#’s JsonSubTypes library), be sure that your JSON payload includes the supporting properties required by those features.

Receiving Messages

While processing a message, a real-time digital twin instance may send a message back to its real-world counterpart (“data source”), for example, to instruct a wind turbine to shut down if it enters a dangerous, alerted state. Any HTTP client can be used to retrieve event messages. For example, to retrieve device messages for wind turbine ‘turbine1’, you could use curl from a bash shell as follows:

curl -X GET "https://realtimetwinapi.scaleoutsoftware.com/api/v1/Messages/windTurbine/turbine1?apiKey=1234567890ABCDEF"

The HTTP response from this GET call returns an array of JSON-formatted messages, where each element in the array contains the following information:

The unique real-time digital twin instance ID
The JSON-formatted payload generated from the digital twin instance
The timestamp the payload was sent

Here is an example of a message sent by a real-time digital twin instance back to its data source:

[
   {
     "instanceId": "turbine1",
     "payload": {
       "desiredRPM": 3500
     },
     "timestamp": "2020-01-07T21:53:25Z"
   }
]

Here is an example using Python that retrieves all source messages for dispatching to either another messaging queue or directly to the real-world entity:

#!/usr/bin/env python

import requests
request = requests.get('https://realtimetwinapi.scaleoutsoftware.com/api/v1/Messages/windTurbine/turbine1?apiKey=1234567890ABCDEF')

messages = request.json()

for message in messages:
    instanceId = message['instanceId']
    payload = message['payload']
    timestamp = message['timestamp']
    
    print instanceId, timestamp, payload
    # forward message to a message queue or device
    # ...