Tag: Getting Started

Step 1

To read and write data between a native iOS app and OAS, you can use the OAS REST API. As a first step, register the HTTP listener with the OAS Service Control Manager under the section labeled “HTML HMI Registration”.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. If you are unsure of which node name to use, localhost will work in most cases.

NOTE: Before clicking “Register”, be sure to stop all services. If services are running, the Service Control app will prompt you to stop them.

Step 2

Start up all services, and be sure to include the Framework 4.5 Service as this houses the listener specific to the REST API.

Step 3

Test your API Service from your iOS device.

You will now ensure that your iPhone or iPad can communicate with OAS via the REST API. In this example, the OAS host is located at 192.168.0.101 on the local network, but you will have to replace this with the OAS host node on your network. The base URL you will use to connect to the REST API is http://{{node}}:{{port}}/OASREST/v2. Each operation performed against the REST API will use the specific operation name prepended with the base {{url}}. The first operation to complete is authentication. All sessions with the REST API must be authenticated. You can adjust the {{url}} in the following snippet and test authentication. In Xcode, create a new single-view iOS application, and choose Swift as the language. Add the following code to MainViewController.swift:

Authenticate Session (Swift):

import requests
import json

### base url is http://{{node}}:{{port}}/OASREST/v2/
url = 'http://192.168.0.101:58725/OASREST/v2'  # {{url}}
op = '/authenticate'                           # {{operation}}
data = '''{"username":"", "password":""}'''
headers = {'Content-Type':'application/json'}

### Authentication is completed via a POST request
response = requests.request("POST", url+op, data=data,
                             headers=headers)

print(response.text)

### Upon success, store your clientid and token for the remainder of the session
json_data = json.loads(response.text)
clientid = json_data["data"]["clientid"]
token = json_data["data"]["token"]

If this code is executed without error, the response will include a clientid and token. These will be included in the header for all other operations.

{
  "status":"OK",
  "data":{"clientid":"531041fa-e601-49d7-a02a-cf13f12eae28",
          "token":"919a303c-4537-4658-b4bf-242fc44e6493"},
  "messages":["Default credential provided"]
}

Here are some Python examples of basic HTTP requests you might wish to make via the REST API after having completed authentication. For additional information, see our REST API documentation.

Create a Tag (Python 3):

### code continues from above
### Create a Tag
headers.update({"clientid":clientid})
headers.update({"token":token})
operation = '/tags'
data = '''
{
   "path":"SomeDummyTag",
   "parameters": {
        "Value": {
            "DataType":"Double",
            "ParameterSource":"Value",
            "Value":"262.262"
        }
    }
}   
'''
response = requests.request('POST', url+operation, data=data, headers=headers)
print(response.text)

Successful tag creation results in the following response from the OAS server:

{"status":"OK","messages":["CREATE COMPLETE"]}

Read a Tag (Python 3):

Reading a tag is accomplished with a GET request, using a simple query including the path to the Tag.

### Read a Tag
### operation = '/tags'
querystring= {'path':'SomeDummyTag'}
response = requests.request('GET', url+operation, params=querystring, headers=headers)
print(response.text)

A possible response from the OAS server:

[{"path":"SomeDummyTag","value":"262.262","quality":true,"type":"Float","timestamp":1521742596474}]

Update a Tag (Python 3):

Updating a tag is accomplished with a PUT request, using a payload including the path to the Tag, and the parameter(s) to be updated.

### Update a tag
### operation = '/tags'
data = '''
{
    "path":"SomeDummyTag",
    "parameters": {
        "Value": {
            "Value":"54.59"
        }
    }
}
'''
response = requests.request('PUT', url+operation, data=data, headers=headers)
print(response.text)

Update confirmation from the OAS server:

{"status":"OK","messages":["UPDATE COMPLETE"]}

Step 4

Write tag data from Raspberry Pi to OAS.
Now that you’ve established connectivity with the REST API, you can complete a Python script to write data from your device. Here is an example script which detects when a button is pushed, and forwards that data into OAS as a discrete tag value. An LED on the breadboard (see figure) indicates the current value, and the OAS server is polled at a frequency of 1 Hz to reflect the current state.

import RPi.GPIO as GPIO
import time
import requests
import json

### Define a function to toggle the state of PiBit
### (You will likely prefer to inject all dependencies in production code)
def toggleBit(state):
    data = '''{"path":"PiBit",
               "parameters":{
                   "Value":{
                       "Value":"'''+str(not state)+'''"
    }}}'''
    requests.request('PUT', url+operation, data=data, headers=headers)
    return not state

### read state of Boolean Tag
def readBooleanTag(tagName):
    querystring = {'path':tagName}
    response = requests.request('GET', url+operation, params=querystring, headers=headers)
    json_response = json.loads(response.text)
    test = json_response[0]["value"]
    return test == "True"

### Write a callback function to execute on event detection
def callback(input_pin):
    print("Input on pin",input_pin)
    current_state = GPIO.input(40)
    toggleBit(current_state)
    GPIO.output(40, not current_state)

### Authenticate session
url = 'http://192.168.0.101:58725/OASREST/v2'
operation = '/authenticate'
data = '''
{
    "username":"",
    "password":""
}
'''
headers = {"Content-Type":"application/json"}
response = requests.request('POST', url+operation, data=data, headers=headers)

### Update headers with clientid and token
json_data = json.loads(response.text)
clientid = json_data["data"]["clientid"]
token = json_data["data"]["token"]
headers.update({"clientid":clientid})
headers.update({"token":token})


### Create a tag to store a boolean
operation = '/tags'
data = '''
{
    "path":"PiBit",
    "parameters": {
         "Value": {
             "DataType":"Discrete",
             "ParameterSource":"Value",
             "Value":"False"
         }
    }
}
'''
response = requests.request('POST', url+operation, data=data, headers=headers)

### Setup Raspberry Pi IO board
GPIO.setmode(GPIO.BOARD)
GPIO.setup(36, GPIO.IN, pull_up_down=GPIO.PUD_UP)
GPIO.setup(40, GPIO.OUT)
GPIO.output(40, False)

### Detect when input voltage drops, and poll server for current state
GPIO.add_event_detect(36, GPIO.FALLING, callback=cb, bouncetime=100)
try:
    while True:
        time.sleep(1)
        print(readBooleanTag("PiBit"))
except KeyboardInterrupt:
    print("\nExiting\n")
    GPIO.cleanup()

For further help with the REST API, navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

Step 1

To write data into OAS from a Raspberry Pi, you will use the OAS REST API. As a first step, register the HTTP listener with the OAS Service Control Manager under the section labeled “HTML HMI Registration”.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. If you are unsure of which node name to use, localhost will work in most cases.

NOTE: Before clicking “Register”, be sure to stop all services. If services are running, the Service Control app will prompt you to stop them.

Step 2

Start up all services, and be sure to include the Framework 4.5 Service as this houses the listener specific to the REST API.

Step 3

Test your API Service from your Raspberry Pi.

You will now ensure that the Raspberry Pi can communicate with OAS via the REST API. In this example, the OAS host is located at 192.168.0.101 on the local network, but you will have to replace this with the OAS host node on your network. The base URL you will use to connect to the REST API is http://{{node}}:{{port}}/OASREST/v2. Each operation performed against the REST API will use the specific operation name prepended with the base {{url}}. The first operation to complete is authentication. All sessions with the REST API must be authenticated. You can adjust the {{url}} in the following snippet and test authentication.

Authenticate Session (Python 3):

import requests
import json

### base url is http://{{node}}:{{port}}/OASREST/v2/
url = 'http://192.168.0.101:58725/OASREST/v2'  # {{url}}
op = '/authenticate'                           # {{operation}}
data = '''{"username":"", "password":""}'''
headers = {'Content-Type':'application/json'}

### Authentication is completed via a POST request
response = requests.request("POST", url+op, data=data,
                             headers=headers)

print(response.text)

### Upon success, store your clientid and token for the remainder of the session
json_data = json.loads(response.text)
clientid = json_data["data"]["clientid"]
token = json_data["data"]["token"]

If this code is executed without error, the response will include a clientid and token. These will be included in the header for all other operations.

{
  "status":"OK",
  "data":{"clientid":"531041fa-e601-49d7-a02a-cf13f12eae28",
          "token":"919a303c-4537-4658-b4bf-242fc44e6493"},
  "messages":["Default credential provided"]
}

Here are some Python examples of basic HTTP requests you might wish to make via the REST API after having completed authentication. For additional information, see our REST API documentation.

Create a Tag (Python 3):

### code continues from above
### Create a Tag
headers.update({"clientid":clientid})
headers.update({"token":token})
operation = '/tags'
data = '''
{
   "path":"SomeDummyTag",
   "parameters": {
        "Value": {
            "DataType":"Double",
            "ParameterSource":"Value",
            "Value":"262.262"
        }
    }
}   
'''
response = requests.request('POST', url+operation, data=data, headers=headers)
print(response.text)

Successful tag creation results in the following response from the OAS server:

{"status":"OK","messages":["CREATE COMPLETE"]}

Read a Tag (Python 3):

Reading a tag is accomplished with a GET request, using a simple query including the path to the Tag.

### Read a Tag
### operation = '/tags'
querystring= {'path':'SomeDummyTag'}
response = requests.request('GET', url+operation, params=querystring, headers=headers)
print(response.text)

A possible response from the OAS server:

[{"path":"SomeDummyTag","value":"262.262","quality":true,"type":"Float","timestamp":1521742596474}]

Update a Tag (Python 3):

Updating a tag is accomplished with a PUT request, using a payload including the path to the Tag, and the parameter(s) to be updated.

### Update a tag
### operation = '/tags'
data = '''
{
    "path":"SomeDummyTag",
    "parameters": {
        "Value": {
            "Value":"54.59"
        }
    }
}
'''
response = requests.request('PUT', url+operation, data=data, headers=headers)
print(response.text)

Update confirmation from the OAS server:

{"status":"OK","messages":["UPDATE COMPLETE"]}

Step 4

Write tag data from Raspberry Pi to OAS.
Now that you’ve established connectivity with the REST API, you can complete a Python script to write data from your device. Here is an example script which detects when a button is pushed, and forwards that data into OAS as a discrete tag value. An LED on the breadboard indicates the current value, and the OAS server is polled at a frequency of 1 Hz to reflect the current state.

import RPi.GPIO as GPIO
import time
import requests
import json

### Define a function to toggle the state of PiBit
### (You will likely prefer to inject all dependencies in production code)
def toggleBit(state):
    data = '''{"path":"PiBit",
               "parameters":{
                   "Value":{
                       "Value":"'''+str(not state)+'''"
    }}}'''
    requests.request('PUT', url+operation, data=data, headers=headers)
    return not state

### read state of Boolean Tag
def readBooleanTag(tagName):
    querystring = {'path':tagName}
    response = requests.request('GET', url+operation, params=querystring, headers=headers)
    json_response = json.loads(response.text)
    test = json_response[0]["value"]
    return test == "True"

### Write a callback function to execute on event detection
def callback(input_pin):
    print("Input on pin",input_pin)
    current_state = GPIO.input(40)
    toggleBit(current_state)
    GPIO.output(40, not current_state)

### Authenticate session
url = 'http://192.168.0.101:58725/OASREST/v2'
operation = '/authenticate'
data = '''
{
    "username":"",
    "password":""
}
'''
headers = {"Content-Type":"application/json"}
response = requests.request('POST', url+operation, data=data, headers=headers)

### Update headers with clientid and token
json_data = json.loads(response.text)
clientid = json_data["data"]["clientid"]
token = json_data["data"]["token"]
headers.update({"clientid":clientid})
headers.update({"token":token})


### Create a tag to store a boolean
operation = '/tags'
data = '''
{
    "path":"PiBit",
    "parameters": {
         "Value": {
             "DataType":"Discrete",
             "ParameterSource":"Value",
             "Value":"False"
         }
    }
}
'''
response = requests.request('POST', url+operation, data=data, headers=headers)

### Setup Raspberry Pi IO board
GPIO.setmode(GPIO.BOARD)
GPIO.setup(36, GPIO.IN, pull_up_down=GPIO.PUD_UP)
GPIO.setup(40, GPIO.OUT)
GPIO.output(40, False)

### Detect when input voltage drops, and poll server for current state
GPIO.add_event_detect(36, GPIO.FALLING, callback=callback, bouncetime=100)
try:
    while True:
        time.sleep(1)
        print(readBooleanTag("PiBit"))
except KeyboardInterrupt:
    print("\nExiting\n")
    GPIO.cleanup()

For further help with the REST API, navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

The following guide demonstrates how to connect to the OAS REST API.

To see how to use the OAS Platform with an external REST API view the Moving Data to an External REST API Use Case.

• 00:00 – Introduction
• 00:12 – What is REST API?
• 00:48 – What CRUD stands for?
• 00:52 – Database Terms for CRUD
• 01:00 – HTTP Parallel Methods
• 01:11 – Examples – Resources URLs
• 03:29 – What JSON stands for?
• 04:01 – Example – Difference between XML – JSON
• 04:22 – When to use OAS REST API
• 05:21 – REST Client Example Code
• 06:03 – Before using REST API
• 08:55 – REST Client Sample Code
• 10:03 – JavaScript
• 11:10 – Set HTTP Status
• 11:35 – Add Virtual Directory
• 12:12 – Sample Rest API Client
• 13:14 – Create a Tag List to Monitor
• 15:30 – Visual Studio
• 17:45 – Postman Application
• 21:08 – More Information

---

Step 1

To use the OAS REST API you must make sure that the OAS HTTP service is listening on the correct port. This is done within the OAS Configuration application.

Open the OAS Configuration application and select Configure > Options, then select the network node (localhost if working on the local machine) and click Select.

Under the Networking tab, locate the field for REST API/WebHMI Port Number. The default is 58725 but can be changed. If you are accessing the server from a remote client, you will also need to make sure your machine and/or company firewalls allow TCP traffic on the selected port.

Using SSL with REST API is fully supported.
Read more about Configuring OAS to use SSL for Web and REST API products.

NOTE: Making any changes to the port numbers in this section of the configuration app will temporarily restart server processes and may cause a brief interruption in data processing.

---

Step 2

Install Postman

Navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

This documentation illustrates all of the operations available to any REST API client and can be tested using the Postman application client.  In the upper right corner of the documentation, you will see a button to Run in Postman, which will install the API documentation into the Postman client for direct execution against any OAS server.  Additionally, the documentation can be configured to display code samples in multiple languages including cURL, jQuery, and NodeJS. Feel free to browse the documentation at any time and to refer back to it while developing your applications.

Clicking Run in Postman will pop up a dialog box to import the REST API into an existing installation of Postman, or you can choose to install the app for the first time. Postman is available for Windows and Mac desktops as well as in a Chrome extension.

---

Step 3

Test your API installation

Once installed and the API has been downloaded into the app, you will see the following interface, with all operations on the left, organized identically to the online documentation:

The first operation to execute is the Authenticate call, which will generate a REST API session and returns a clientid and token to be used in all subsequent calls to the OAS server.

In the list of operations, expand and select Authenticate and you will see the following on the right side of the app:

This shows that the Authenticate operation is executed as an HTTP POST against the /authenticate URL appended to the base {{url}}. This base URL is defined in your Environment here. Select Manage Environments to add new fields:

Add your server to the Environments list

Click ADD to create a new Environment which will hold environment variables:

Add a name for your environment, then add a key of url with a value of http://localhost:58725/OASREST/v2 and click ADD to create the new environment. You can also use your OAS server’s IP address instead of localhost, if you are connecting to it from a remote workstation.

Next, return to execute the the Authenticate operation.

Now under the Environments dropdown, select your new Environment. You should see the {{url}} turn orange, indicating that the environment variable is being used.

You can now click SEND to execute the post against your server. If successful, you should see a response body similar to the one below, containing the clientid and token fields.

You can then use these fields in the header of all other operations using the Postman app to test your server.

---

Step 4

Accessing Tag Values

Once authenticated, you are now able to use the clientid and token in HTTP headers to make calls to configure Tags, access real time and historical Tag data, and even real time and historical Alarm and Trend data. When referencing Tags in any call, you it is assumed that you are accessing them on the OAS server being called in the REST API. However, you can also access remote Tags on any OAS server networked with the target server. Read more about the proper syntax for accessing Tags and Tag Variables.

---

Remote Access

OAS servers can communicate with each other and pass along tag data. This allows for distributed network load as well as placing OAS servers behind firewalls so they cannot be accessed directly. This allows you to securely issue REST API calls against one server and read/write data within a remote OAS server that cannot be reached directly from the REST API client. This same concept applies whether you are calling the OAS REST API or using the .NET Data Connector for programmatic Tag access and configuration.

• Main OAS Engine : the server handling the REST API calls
• Remote OAS Engine : the server housing the tag data or configuration you would like to access

REST API URL

Set the url to OAS Engine that the REST API will be hosted from. This is the URL to the Main OAS Engine whether you are accessing tag data on the Main OAS Engine or on a Remote OAS Engine.

Localhost URL : will only work when accessing the Main OAS Engine on the same machine as the client.

http://localhost:58725/OASREST/v2

Explicit URL : use the IP Address or domain name of the Main OAS Engine, allowing you to access it from a remote client. This will also work on the same machine and is the best option for code flexibility.

http://192.168.0.1:58725/OASREST/v2

Tag Access

Main OAS Engine Tag – accessing tag data on the Main OAS Engine only requires referencing the tag path.

{
    "tags": [
      {"path":"TagName.Value"}
    ]
}

Remote OAS Engine Tag – To monitor real time data from Remote OAS Engines reference the tag path in the form \\<Remote OAS address>\<Tag Path>. Note in the example below that backslash characters are escaped within strings, changing \ to \\ and \\ to \\\\.

Basic Networking – Static IP or domain name

{
    "tags": [
      {"path":"\\\\192.168.0.2\\TagName.Value"},
      {"path":"\\\\192.168.0.3\\TagName.Value"},
      {"path":"\\\\myserver.com\\TagName.Value"}
    ]
}

Live Data Cloud Networking – Dynamic IP
Once you have registered named Live Data Cloud nodes on an OAS server, you can reference them in the form RemoteSCADAHosting.<Node Name>.<Tag Path>.

{
    "tags": [
      {"path":"RemoteSCADAHosting.LiveDataCloudNode01.TagName.Value"},
      {"path":"RemoteSCADAHosting.LiveDataCloudNode02.TagName.Value"},
      {"path":"RemoteSCADAHosting.LiveDataCloudNode03.TagName.Value"}
    ]
}

Remote Configuration Calls

To execute REST API Tag Configuration calls against Remote OAS Engines, you can use the networknode parameter to reference a static IP or domain name, or the ldc parameter to reference a Live Data Cloud node name. The example below demonstrates calls to the CSV Tag configuration calls using each of these methods.

Basic Networking – Static IP or domain name

http://192.168.0.1:58725/OASREST/v2/csvtags?columns=Tag,Value - Data Type,Value - Value,Last Column&networknode=192.168.0.2

Live Data Cloud Networking – Dynamic IP

http://192.168.0.1:58725/OASREST/v2/csvtags?columns=Tag,Value - Data Type,Value - Value,Last Column&ldc=LiveDataCloudNode01

Remote Security

Because your authentication call is always against the Main OAS Engine, that same credential will be passed to any networked OAS Engine when referencing remote Tags. So it is critical to make sure the same credential (username/password) exists on all networked OAS Engines and has been granted the appropriate access level for the command being executed.