====== Mervis SCADA public API ====== Mervis SCADA offers open REST-like API based on JSON and XML data formats. For full description please contact our [[en:contact:00-start|technical support]]. **Important:** Only officially supported response format is XML! The API endpoint URL is **https://scada.unipi.technology/api-scada/** ===== List of basic API methods ===== ^Function^Description| ^api/checkCredentials|| ^api/logout|| ^api/get/projects|| ^api/get/projectData|| ^api/get/projectByParts|| ^api/get/history|| ^api/get/history/specific|| ^api/set/history|| ^api/replace/history|| ^api/get/values|| ^api/get/alarms|| ^api/get/alarmHistory|| ^api/get/eventHistory|| ^api/get/changes|| ^api/set/executeActions|| ^api/set/values|| ^api/set/executeAlarmOps|| ^api/set/projectPriorityRefresh|| ^api/get/schema|| ^api/get/schema/datapoints|| ^api/get/schema/values|| ^api/get/schema/image|| ===== Examples ===== ====api/checkCredentials==== **Request** * URL: /api/checkCredentials?format=xml * Method: POST {"cred":{"n":"demo","p":"demo"}} **Response** * You **should** use the received token **t** in subsequent API calls. ==== api/v3/get/history ==== **Request** * URL: /api/v3/get/history?format=json * Method: POST * Downloading of one or multiple trends with single API call * You should always use "token" instead of simple "name" a "password". Non-token call is slower. * "seriesParameters" [optional] - use only if you request different parameters than "commonSeriesParameters" * "clientReference" [optional] - use for your own identification of the series * Items: "segmenation", "requestState" and "serverState" should always copy the values from the last server response. First call should use empty "segmentation". { "credentials": { "token":"guid" //string }, "request": { "commonSeriesParameters": { "from": "2018-12-01T00:00:00Z", //UTC dateTime "to": "2018-12-01T10:00:00Z"//UTC dateTime }, "series": [ { "seriesParameters": { "from": "2017-11-28T14:26:16.5029619Z",//UTC dateTime "to": "2018-11-28T14:26:16.5029619Z" //UTC dateTime }, "clientReference": "myId2a", //string "provider": { "parameters": { "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //guid "dataPointId": "2a9c26c9-2ce3-49c4-909d-9ac1143121f1" //guid } } }, { "clientReference": "myId1a", "provider": { "parameters": { "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0" } } } ] }, "dataSpecification": { "limits": { "count": 1000 //int } }, "segmentation": { "requestState": ";;2;;0", //string "serverState": "xyz" //string } } **Response** * Empty "segmentation" ("requestState") marks response containing last data of the requested series * "requestState" and "serverState" must be copied to the next API call * Values * v - value * ts - timestamp - start of the value validity period * gt - goodthrough - end of the value validity period * i - interval, only present if it differs from the interval in Meta section * Meta * type - value type - double, string, datetime * unit - unit * interval - expected interval between the stored records. Useful to identify missing data. { "result": { "code": 0, //int "subCode": 0, //int "message": "" //string }, "data": { "count": 3, //int "historyData": [ { "clientReference": "myId2a", //string "provider": { "id": "689e32fa-24a2-448e-9374-6158e6e6cb15", //guid "parameters": { "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //guid "dataPointId": "2a9c26c9-2ce3-49c4-909d-9ac1143121f1" //guid } }, "meta": { "type": "string", //string "unit": "", //string "interval": "PT3M" //string - ISO8601 Timespan }, "values": [ { "v": "AUT", //string "ts": "2018-11-26T12:22:15.25795Z", //dateTime "gt": "2018-11-26T13:22:15.5784067Z" //dateTime } ] }, { "clientReference": "myId1a", "provider": { "parameters": { "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0" } }, "meta": { "type": "double", "unit": "hod", "interval": "PT3M" }, "values": [ { "v": 12939,//double "ts": "2018-11-30T23:58:15.2394603Z", "gt": "2018-12-01T01:37:15.4869553Z" }, { "v": 12946, "ts": "2018-12-01T09:22:16.2049051Z", "gt": "2018-12-01T10:37:15.4023519Z", "i": "PT4M" } ] } ] }, "segmentation": { "requestState": "xyz", //string "serverState": "xyz" //string } } **Demo** { "credentials": { "name": "demo", "password": "demo" }, "request": { "commonSeriesParameters": { "from": "2018-12-01T00:00:00Z", "to": "2018-12-01T00:11:00Z" }, "series": [ { "clientReference": "myId1", "provider": { "parameters": { "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", "dataPointId": "acad79f3-3358-42dd-9b74-98733e63d771" } } }, { "clientReference": "myId2", "provider": { "parameters": { "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", "dataPointId": "14cf0dbb-b050-43aa-a6f0-22886c33ed8e" } } } ] }, "dataSpecification": { "limits": { "count": 1000 } } } ==== api/get/history/specific ==== **Request** * URL: /api/get/history/specific?format=json * Method: POST * You should always use token ("t") instead of simple name and password ("n" and "p"). Non-token call is slower. * "dataSpec" - data specification * MinTimestamp = 0, * MaxTimestamp = 1, * FirstLessThanReferenceDateTime = 2, * FirstLessThanOrEqualThanReferenceTime = 3, * FirstGreaterThanReferenceDateTime = 4, * FirstGreaterThanOrEqualThanReferenceTime = 5, * MaxGoodThroughTime = 6 * "refTime" [optional] - reference time for dataSpec values 2 to 5 { "cred": { "n":"test", "p":"test" }, "projId":"b4d96a6d-2b3d-48eb-af30-d11e875ba7ed", "offset":0, "count":1000, "dataSpec":2, "refTime":"\/Date(1692788459000)\/", "dpIds":["58426e69-46ba-4925-9a5c-d7d65efb9886","f4501a2e-62ed-430e-9346-5e155e730fe3","28e7d087-917a-456a-9d02-96882f572286"] } **Response** * Values * v - value * ts - timestamp - start of the value validity period * gt - goodthrough - end of the value validity period * i - interval { "ns": { "r": "http://dev.rcware.eu/serialization/references", "n1": "http://dev.rcware.eu/scada/history", "n2": "http://dev.rcware.eu/scada/datapoints", "n3": "http://dev.rcware.eu/scada/basic-props" }, "doc": { "n1:getHistorySpecificResult": { "n2:pl": [ { "n2:p": { "n1:hist": { "@": { "n1:projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed", "n1:dpId": "58426e69-46ba-4925-9a5c-d7d65efb9886", "n1:propName": "Output", "n1:interval": "00:00:00", "n1:historyState": "", "n1:nextValOfs": 0 }, "n1:errMsg": "", "n1:vals": [ { "n1:hv": { "@": { "n1:ts": "2023-08-23T11:00:57.7010708Z", "n1:i": "1.00:00:00" }, "n3:v": 12.48 } } ] }, "@": { "r:type": "b133774d-21ce-42b6-add3-57c012079c55" } } }, { "n2:p": { "n1:hist": { "@": { "n1:projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed", "n1:dpId": "f4501a2e-62ed-430e-9346-5e155e730fe3", "n1:propName": "Output", "n1:interval": "00:00:00", "n1:historyState": "", "n1:nextValOfs": 0 }, "n1:errMsg": "", "n1:vals": [ { "n1:hv": { "@": { "n1:ts": "2023-08-23T10:38:43.784Z", "n1:gt": "2023-08-23T11:18:00.207Z", "n1:i": "00:00:30" }, "n3:v": 5.0 } } ] }, "@": { "r:type": "b133774d-21ce-42b6-add3-57c012079c55" } } }, { "n2:p": { "n1:hist": { "@": { "n1:projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed", "n1:dpId": "28e7d087-917a-456a-9d02-96882f572286", "n1:propName": "Output", "n1:interval": "00:00:00", "n1:historyState": "", "n1:nextValOfs": 0 }, "n1:errMsg": "", "n1:vals": [ { "n1:hv": { "@": { "n1:ts": "2023-08-23T10:38:43.786Z", "n1:gt": "2023-08-23T11:18:00.207Z", "n1:i": "00:00:30" }, "n3:v": "ZAP" } } ] }, "@": { "r:type": "177e726a-3180-4152-bef2-6254e7055e1f" } } } ], "@": { "r:type": "1c4c1ddc-463f-443d-883a-19489cd2e53a" } } } } ==== [Depricated] api/get/history==== **Request** * URL: /api/get/history?format=xml * Method: POST { "cred":{ "n":"demo", //username "p":"demo" //password }, "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //project ID "dpId":"62cf4083-31ed-4bc1-be25-044ba837a9f0", //single datapoint ID "from":"/Date(1541199600000)/", //UTC in ms "to":"/Date(1541496190357)/", //UTC in ms "offset":0, "count":5000, "historyState":"" //client has to send historyState value from the last response with the following request } **Response** 12754 12754 12754 12755 12756 12757 12758 12759 12760 12761 12761 12761 ====api/set/history==== **Request** * URL: /api/set/history?format=xml * Method: POST * Content-Type: text/xml Attribute **i** sets **interval** ([[https://en.wikipedia.org/wiki/ISO_8601#Time_intervals|ISO 8601]]) in which the next value should be expected to be saved into a database. Even though there could be used name and password in **cred** - you should always use **token** to get the best performance. All date and time values are supposed to be in UTC. 2.7 3.0 2.0 2.3 **Response** * 200 OK ====api/replace/history==== **Request** * URL: /api/replace/history?format=xml * Method: POST * Content-Type: text/xml Attribute **i** sets **interval** ([[https://en.wikipedia.org/wiki/ISO_8601#Time_intervals|ISO 8601]]) in which the next value should be expected to be saved into a database. Even though there could be used name and password in **cred** - you should always use **token** to get the best performance. All date and time values are supposed to be in UTC. 2.7 3.0 2.0 2.3 **Response** * 200 OK ====api/set/executeActions==== **Request** * URL: /api/set/executeActions?format=xml * Method: POST * Content-Type: text/xml 16 **Response** ====api/set/values==== **Request** * URL: /api/set/values?format=xml * Method: POST * Content-Type: text/xml

23

**Response** ====api/get/values==== The right way how to retrieve current values of data points (property "Output" which is usually what you want) from one or multiple projects. **Request** * URL: /api/get/values?format=xml * Method: POST { "cred": { "t": "xxxxxx" //token }, "propNamesToSerialize": ["Output"], "offset": 0, "count": 1000, "serverState": null, "dps": [{ "projId": "ba1a92f7-f213-4a72-90e4-f7142b50274b", "dpIds": ["e089dde2-a097-4e0d-8012-c8cf3dc62694", "1089dde2-a097-4e0d-8012-c8cf3dc62696"] } ] } **Response**

ON

0

====api/get/projectByParts==== To get the list of datapoints. **Request** * URL: /api/get/projectByParts?format=xml * Method: POST { "cred": { "t": "xxxxxx" }, "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", "treeId": "Visual tree", "partType": 0, "offset": 0, "count": 250 } **Response**

1

OK

Output OK 0 ALARM 1

0

OK

Output OK 0 ALARM 1