Category: Knowledge Base

/gettoken

Used to get an identity token from the server, which will then be used on every subsequent request to read or write data.

message

{
  "un":"<username>",
  "pw":"<password>"
}

response

Unless an error occurs, the gettoken response will always contain a token in the response with a status of “OK“. The token should then be included in every subsequent call to the API, identifying the user context for each request.

If the credentials are not valid, a token will still be created, but depending on the OPCSystems Service configuration, that token may not allow the user to gain access to read or write data.

{
  "message":"<token>",
  "status":"<OK | ERROR>"
}

/getdata

Used to get the most recent tag data from the server for real time data display.

message

The message should contain an array of “tags“, each representing a server tag. Each tag should contain an array of “props“, each representing a distinct property that you would like to retrieve from the server for that tag. For example, if you want to get the value for “Pump.Value“, the tag name would be “Pump“, and it would contain a single property with a name of “Value“.

If you wanted to retrieve both “Pump.Value” and “Pump.Description“, you would send a single tag with two elements in the props collection for “Value” and “Description“, respectively.

{
  "tags":[
    {
      "name":"<tag name>",
      "props":[
        {"name":"<tag property>"},
        ...
      ]
    },
    ...
  ],
  "status":"",
  "message":"",
  "token":"<token>"
}

response

The response follows the same structure as the request, with additional data populated in the property structure. A “datatype” is returned to assist with client-side data formatting, a boolean “quality” field is returned to indicate whether the data quality from the source is good or bad, and the raw value is populated in the “val” field. The value will always be populated as a string no matter which datatype the source is. Use the datatype to do any native client conversions.

{
  "message":"<blank if no error>",
  "status":"<OK | ERROR>",
  "tags":[
    {
      "name":"<tag name>",
      "props":[
        {
          "datatype":"<boolean|string|float|int>",
          "name":"<tag property>",
          "quality":<true | false>,
          "val":"<property value>"
        }
      ]
    },
    ...
  ],
  "token":"<token passed in request>"
}

/setdata

Used to set a tag value on the server, and ultimately on the data source itself. The message is similar to that used in the /getdata operation, with the addition of the “val” field on the property indicating the new value to set on the server.

message

{
  "tags":[
    {
      "name":"<tag name>",
      "props":[
        {
          "name":"<tag property>",
          "val":"<new property value>"
        }
      ]
    }
  ],
  "status":"",
  "message":"",
  "token":"<token>"
}

response

{
  "status":"<OK | ERROR>",
  "message":"",
}

/gettrenddata

Used to retrieve real time and historical alarm data points for rendering graphs and charts on a client.

message

The “requesttype” field determines the type and amount of data returned. For an full load of datapoints, pass an empty string. For only new data received since the last request, pass “NewData”. For historical data, first issue a request with using “HistoryRequest”, and pass in “HistoryData” for subsequent requests for data values.

Only use the “starthistorydate” and “endhistorydate” fields when requesting historical data. Omit these fields for all other requests. Also, these values are based on the Javascript Date format and represent the number of ticks since January 1, 1970, and other client ticks may need conversion.

The “chartinstanceguid” field is used to synchronize between client and server requests. When an initial data set is requested, pass in an empty string, and the server will assign a chartinstanceguid value in the response. For all subsequent messages within the context of that trend data, use the same chartinstanceguid and “NewData” in the requesttype field to reduce the amount of data transferred to the client on each request.

The “samplerate” and “timeframe” fields are used to determine the frequency of samples in seconds, and the timeframe for the full data set.

The “tagnames” array lists each individual tag that will be polled for trend data. These names are simple strings representing the each tag (e.g. “Random.Value”), and the order in which the data will be returned from the server.

The “historytagnames” field is a parallel array to the “tagnames” list. Include a blank entry for each entry in the tagnames array, unless the historical data for any tag is in a separate datalogging group. In that case, use the format datalogginggroupname.fieldname for each entry.

The “historystatprocessing” field is also a parallel array associated with the “tagnames” list. These entries indicate the method used to calculate the historical datapoints returned for each tag. In most cases, use “avg” for an average value of the data samples. You can also use “min” and “max” to get the minimum and maximum values for that data sample timeframe, or “lastsample” to use the most recent sample in that timeframe.

By default, when data is returned, only the raw data values are included in the result, without any timestamp information. When using the averaging method, this makes plotting very straightforward since the timestamp can be inferred from the start time, end time, and number of samples.

It also greatly reduces the amount of data transferred from the server by having the client perform the calculations for display. However, if you wish to include the actual timestamp with each sample, set the “returnalldatawithtimes” value to true.

{
  "token":"<token>",
  "requesttype":"<blank | NewData | HistoryRequest | HistoryData>",
  "chartinstanceguid":"",
  "samplerate":1,
  "timeframe":50,
  "tagnames":[
    "<tag.value>",
    ...
  ],
  "historytagnames":[
    "<datalogginggroupname.fieldname>",
    ...
  ],
  "historystatprocessing":[
    "<avg | min | max | lastsample>",
    ...
  ],
  "starthistorydate" : <ticks>,
  "endhistorydate" : <ticks>,
  "returnalldatawithtimes":false
}

response

The “chartinstanceguid” field is returned to help you coordinate data sets if you are displaying multiple sets with different parameters. The “firsttime” and “lasttime” fields are tick values indicating the timestamp of the first datapoint and last datapoint in the result, respectively, and combined with the “numberofvalues” can be used to generate timestamps for each datapoint.

If the “returnalldatawithtime” field was utilized in the request, then the “timesforreturnalldata” field in the response will contain actual timestamps for each individual datapoint.

The “penvalues” field will contain the raw datapoints. These are arranged in an array for each individual tag requested in the request message’s “tagnames” field. The penvalues are returned in the same order as tags requested.

{
  "chartinstanceguid":"<guid>",
  "firsttime":<ticks>,
  "lasttime":<ticks>,
  "numberofvalues":<int>,
  "penvalues":[
    [ <array of data points> ],
    ...
  ],
  "timesforreturnalldata":[
    [<array of ticks>],
    ...
  ]
  "status":"<OK | ERROR>",
  "message":"",
}

/getalarmdata

Used to retrieve real time and historical alarm data, optionally filtered by group, type, and status.

message

Similar the the gettrenddata request, there is a concept of an instance guid, referenced by the “alarminstanceguid” field. On an initial request using the “requesttype” of “RefreshAllData“, use a blank alarminstanceguid. The response will contain a guid assigned by the server to be used in all subsequent requests to synchronize data and modes between client and server.

The “requesttype” field is used to switch between modes. “RefreshAllData” will pull all current real time alarm data available in a single dataset. This is used to refresh data or get a full update after displaying historical data. Subsequent requests for real time alarms should use “NewData” as it will reduce bandwidth and only provide updated alarms since the last request.

To display historical alarms, send an initial message with a requesttype of “HistoryRequest” along the “starthistorydate” and “endhistorydate” fields containing ticks to define the timeframe for historical data. Then subsequent requests should be issued with the “HistoryData” requesttype to receive the dataset.

The “networknodes” is an array of network node strings used for determining the source of the data. Leave empty to assume “localhost” relative to the OPCSystems Service being contacted.

The “alarmfilter” field is used to determine the criteria for which alarms to include in the resulting dataset.

{
  "alarminstanceguid":"",
  "token":"<token>",
  "requesttype":"<RefreshAllData | NewData | HistoryRequest | HistoryData>",
  "networknodes":[],
  "alarmfilter":{
    "includealarmactive":<true|false>,
    "includealarmactiveacked":<true|false>,
    "includealarmnotactive":<true|false>,
    "includealarmnotactivenotacked":<true|false>,
    "maxpriority":<int>,
    "minpriority":<int>,
    "alarmgroups":[],
    "alarmtypes":[
      "Digital",
      "High",
      "High High",
      "Low",
      "Low Low",
      "ROC",
      "System"
    ]
  },
  "starthistorydate":<ticks>,
  "endhistorydate":<ticks>
}

response

The response for any request for alarms will contain the matching alarminstanceguid, along with an array of “alarmvalues“. Each alarm value itself is an array containing the values for the individual alarms. Use the AlarmID field when referencing any individual alarm for performing an Ack or Delete operation.

{
  "alarminstanceguid":"<guid>",
  "alarmvalues":[
    [
      "<NetworkNode>"
      "<AlarmID>"
      "<AlarmType>"
      "<Group>"
      "<Priority>"
      "<Text>"
      "<Active>"
      "<Acked>"
      "<TimeDelay>"
      "<AlarmValue>"
      "<AlarmLimit>"
      "<ClearedValue>"
      "<AlarmDateTime>"
      "<ClearedDateTime>"
      "<AckedDateTime>"
      "<AckedUser>"
      "<Units>"
      "<Document>"
      "<Comment>"
      "<OKToDelete>"
      "<OKToComment>"
    ],
    ...
  ],
  "message":"",
  "status":"<OK | ERROR>"
}

/updatealarm

Used to update an alarm, marking it as acknowledged or marking it for deletion.

message

Passing in a “requesttype” of “Ack” will mark the alarm identified with “alarmid” as acknowledged, and passing in “Delete” will mark the alarm for deletion.

{
  "token":"<token>",
  "alarmid":"<alarmid>",
  "networknode":"<networknode>",
  "requesttype":"<Ack | Delete>"
}

response

{
  "alarminstanceguid":"<guid>",
  "message":"",
  "status":"<OK | ERROR>"
}