An Industrial IOT Platform

OPScript Custom Web APIs

Introduction to Custom Web APIs

An OPScript can be triggered via Web APIs by enabling the Web API Trigger in the Open-Plant Client. From the Open-Plant Client, click on analytics then select a script. The following should appear. Ensure the Web Api Trigger check box enable is checked and the script is enabled.

Once enabled, the OPScript can be triggered via Web APIs from the trigger URL shown
Alternatively, it can also be triggered via a custom URL. In the example below the Web API can be called via 'http://localhost:33171/calculateaverage' and 'https://localhost:33171/calculateaverage'.

Returning a Custom JSON Object

Anything returned from OPScript triggered via Web API will be converted into a JSON object. Take example the following OPScript which list tag Ids as a list of string.
The script when after run returns the following JSON object:
[
  "FIC103.Value",
  "Random1.Value",
  "LIC101.value",
  "fic105.value",
  "FIC101.value",
  "MyPlant\Tag.Value",
  "Random2.Value",
  "fic102.value"
]
A custom object can also be returned by using nested dynamic constructors. Below is an example:
This returns the following JSON object:
{
  "data": {
    "subdata1": {
      "subdata1a": "My Age is",
      "subdata1b": 39
    },
    "subdata2": 0.321
  }
}

Accepting User Input in Web API URL

OPScripts triggered via Web APIs are able to accept user input from the URL address itself. Take example the following web api:

http://localhost:33171/calculateaverage

A caller can include an input parameter in the URL as follows:

http://localhost:33171/calculateaverage?tagid=fic101.value

Note that this Web API call will still be captured via the OPScript's alternative trigger, despite having additional parameters. Open-Plant does not process any URL portions after the question mark '?' as this denotes the query parameter section. 
A caller can add more than one query parameters by adding the separator '&' character between parameters. Below is an example where two parameters'tagid' and 'duration' is inseted in the URL Call:

http://localhost:33171/calculateaverage?tagid=fic101.value&duration=30

The query parameter also works on the main trigger url as follows. 

http://localhost:33171/api/runscript?id=df54b71c-ca60-4c6d-90d8-2a7c8e4050ea&tagid=fic101.value&duration=30
 

Reading User Input in the actual script

In order to read a User Input, the OPScript's 'main' function needs to be modified. To access the 'main' function, click on 'show advance code' in the Open-Plant client's analytics page. A lengthier script will be shown as follows:
In this example, two input is required which is 'TagId' and 'Duration'. TagId is a string, while Duration is an integer. To accept these two parameters, the 'Main()' method needs to be replaced with 'Main(string TagId, string Duration)'. Input parameters will always enter as a string. However, since 'Duration' requires to be an integer, it's conversion can be done via the '.ToInt()' function. 

The entire modified script is as follows.

The Order of the URL query matters

As shown above, to accept a user input, the number of Input parameters must match the number of string input variables in the 'Main()' function. However, take note that the order of the URL query parameter is important, for example:

http://localhost:33171/calculateaverage?tagid=fic101.value&duration=30

The above URL query is correct as it accepts TagId="fic101.value" and Duration="30", both being strings. However, the following is incorrect:

http://localhost:33171/calculateaverage?duration=30&tagid=fic101.value

The above will be incorrectly recognized as TagId="30" and Duration="fic101.value"

OPScript will accept the input parameters based on the input variables in the modified 'Main()' function.

Accepting input from a Request Body

OPScripts triggered via Web APIs can also accept input entered in the request body. Unlike URL input, reading a request body does not require any modification to the 'Main()' function of OPScript. Obtaining the request body can be simply done using the following function

OP.GetWebRequestBody()

The example below returns a JSON object of the request body:
{
  "data": "Hello! I came from the Web Request Body"
}

Reading a JSON Input

If the request body contains a JSON input, the JSON input can be converted into an object using the '.ToObject(definition)' function. The function requires one to specify a definition of the expected JSON object.

OPScript JSON Definitions

OPScript JSON definition tells OPScript how to read a JSON string and convert it to an Object. For those familiar with C#, JSON definitions are C# dynamic objects. 

Defining a definition is usually done by self analyzing a JSON string and determining the nesting of propeties and whether each property is an array or single variable. If a property is an array, it must be defined with "new[]".

Take example the following JSON property
{
  "employees":[
      {"firstName":"John", "lastName":"Doe"},
      {"firstName":"Anna", "lastName":"Smith"},
      {"firstName":"Peter", "lastName":"Jones"}
  ]
}
For the example above, the definition of this object is:

var definition = new { employees = new[] { new { firstName = "", lastName = "" } }}


In OPScript Web APIs, this is implemented as follows:
JSON Definitions are also used when reading OPScript Parameters via the OP.GetParameter function. 
IMPORTANT
JSON definitions are case sensitive. In the above example, if 'firstName' is spelled as 'FirstName', OPScript will still create the object. However, the object will have a property 'FirstName' instead of 'firstName' and this value will be null. 
Open-Plant is a revolutionary Industrial IOT Platform software, used to create and deploy Industrial IT apps/solutions. It is an all-encompassing solution offering both back-end and front-end components i.e. the full stack. From our user's experience, creating and deploying Industrial IT apps became 10x faster and 10x less cost. We serve the mining, energy, oil & gas, construction and manufacturing industry. 

Vlix

We are based in 
Perth, Australia

EMAIL

Sales / General Enquiry:

info@vlix.me
homedownloadenvelope