Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
en:mervis-scada:50-api [2018/11/21 15:54]
j.siroky [Matlab]
en:mervis-scada:50-api [2026/07/17 12:41] (current)
z.moustis
Line 1: Line 1:
-====== API ======+====== Mervis SCADA API ======
  
-Mervis SCADA offers open REST-like API based on JSON and XML data formats. For full description please contact our [[:en:help:support|technical support]].+Mervis SCADA offers an openREST-like API based on JSON and XML data formats for seamless integration with third-party applications. For full description of advanced features, please contact our [[:en:help:20-support|technical support]].
  
-===== List of basic API methods =====+**Important Note on Formatting:** While JSON is heavily utilized in newer endpoints, the only officially supported backward-compatible response format across the entire legacy API is XML. 
  
-^Function^Description|+===== Supported API Methods =====
  
-^api/checkCredentials|| +Below is the consolidated list of recommended API endpoints. Note: Only methods with fully documented and verified examples are listed below.
-^api/logout|| +
-^api/get/projects|| +
-^api/get/projectData|| +
-^api/get/projectByParts|| +
-^api/get/history|| +
-^api/get/history/specific|| +
-^api/set/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||+
  
 +^ Function ^ Description |
 +| **Authentication** | |
 +| ''api/v2/get/authenticate'' | Authenticates a user and returns a session token for subsequent API calls. |
 +| **Project & Data Structure** | |
 +| ''api/get/projects'' | Retrieves a list of all projects accessible to the logged-in user. |
 +| ''api/get/projectByParts'' | Retrieves the visual tree structure and the list of datapoints within a specific project. |
 +| **Reading Data** | |
 +| ''api/get/values'' | Retrieves the current, real-time values of specified datapoints. |
 +| ''api/v3/get/history'' | Downloads historical trend data for one or multiple series in a single, paginated call. |
 +| ''api/get/history/specific'' | Retrieves specific historical datapoints relative to a provided reference time. |
 +| **Writing & Execution** | |
 +| ''api/set/values'' | Writes new values to specified datapoints. |
 +| ''api/set/executeActions'' | Executes predefined actions or buttons (e.g., INIT, ZAP commands) on datapoints. |
 +| ''api/set/history'' | Inserts new historical data values into the database. |
 +| ''api/replace/history'' | Completely replaces existing historical data within a specified time range. |
  
 +**Note on Credentials:** You can test these API calls using the credentials `n: demo` and `p: demo`. For production applications, it is required to exchange these credentials for a token using `api/v2/get/authenticate` and use the resulting token (`t: [token_string]`) in subsequent calls to ensure optimal performance.
  
 +===== Authentication =====
  
-===== Example =====+==== api/v2/get/authenticate ==== 
 +**Request:** 
 +  * **URL:** ''/api/v2/get/authenticate?format=json'' 
 +  * **Method:** POST
  
-====api/get/history====+Standard login: 
 +<code javascript> 
 +{"data":{"cred":{"n":"demo","p":"demo"}}} 
 +</code>
  
-**Request**+Domain-specific login: 
 +<code javascript> 
 +{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}} 
 +</code>
  
-   URL/api/get/history?format=xml +**Response Properties:** 
-   Method: POST+  * **token** (string) - Authentication token for calling other API methods. 
 +  * **tokenValidFor** (TimeSpan) - The duration for which the provided token is valid (e.g., "P1D" 1 day). 
 +  **changePwdBefore** (DateTime or null) - Specifies the date and time by which the current password must be changed.
  
 <code javascript> <code javascript>
-  +
-   "cred":  +    "data": { 
-      "n":"demo", //username +        "ChangePwdBefore": null, 
-      "p":"demo" //password +        "ClientType": 2, 
-   }+        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1", 
-   "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //project ID +        "DomainName": "GlobalDomain", 
-   "dpId":"62cf4083-31ed-4bc1-be25-044ba837a9f0",  //single datapoint ID +        "FullName": "GlobalDomain\\demo", 
-   "from":"/Date(1541199600000)/", //UTC in ms +        "Login": "demo", 
-   "to":"/Date(1541496190357)/",  //UTC in ms +        "NotifyNearingPwdExpirationIn": null
-   "offset":0, +        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f", 
-   "count":5000, +        "TokenValidFor": "P1D", 
-   "historyState":"" //client has to send historyState value from the last response with the following request+        "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e", 
 +        "Username": "" 
 +    }
 +    "result": { "code": 0, "codeTxt": null, "dataType": null, "desc": null }
 } }
 </code> </code>
  
-**Response**+===== Reading Data =====
  
 +==== api/get/values ====
 +Retrieves current values of data points (property "Output") from one or multiple projects.
 +
 +**Request:**
 +  * **URL:** ''/api/get/values?format=xml''
 +  * **Method:** POST
 +
 +<code javascript>
 +{
 + "cred": {
 +  "n": "demo",
 +  "p": "demo" 
 + },
 + "propNamesToSerialize": ["Output"],
 + "offset": 0,
 + "count": 1000,
 + "serverState": null,
 + "dps": [{
 +   "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
 +   "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
 +  }]
 +}
 +</code>
 +
 +**Response:**
 <code xml> <code xml>
 <?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?>
-<getHistoryResult xmlns:r="http://dev.rcware.eu/serialization/references" r:type="b133774d-21ce-42b6-add3-57c012079c55" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/history"> +<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2026-07-17T10:29:17Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints"
-  <!-- + <vals
-  @Interval ISO interval of trend values defined by the database client+  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z"> 
-  @historyState - to be copied into the next request +   <dps> 
-  @nextValOfs to be copied into the next request until value -1 is reached. +    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true"> 
-  If ts of value in not within the interval time span after the previous value'gt - some data is missing. +     <props> 
-   +      <p n="Output" t="2026-07-17T10:29:17Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55"> 
-  --> +       <n1:v>13851.42</n1:v> 
-  <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1"> +      </p> 
-    <errMsg/> +     </props> 
-    <vals+    </d> 
-      <!--ts time stamp, gt good throughvalue is valid in the whole time span between these two--> +   </dps> 
-      <hv ts="2018-11-02T21:26:08.7936747Zgt="2018-11-03T20:35:08.8060769Z"> +  </v> 
-        <n1:v>12754</n1:v+ </vals> 
-      </hv+</values
-      <hv ts="2018-11-03T20:41:09.0100479Zgt="2018-11-05T11:35:08.7415158Z"> +</code> 
-        <n1:v>12754</n1:v> + 
-      </hv+==== api/v3/get/history ==== 
-      <hv ts="2018-11-05T11:40:04.0077949Zgt="2018-11-05T17:25:03.4285643Z"> +Downloading one or multiple trends with a single API call. 
-        <n1:v>12754</n1:v+ 
-      </hv+**Rules:** 
-      <hv ts="2018-11-05T17:28:03.4133447Zgt="2018-11-05T19:40:03.0246122Z"> +  * Items "segmentation", "requestState", and "serverState" should always copy the values from the last server response for pagination. The first call should use an empty "segmentation". 
-        <n1:v>12755</n1:v+ 
-      </hv+**Request:** 
-      <hv ts="2018-11-05T19:43:03.6499981Zgt="2018-11-05T22:01:03.2620552Z"> +  * **URL:** ''/api/v3/get/history?format=json'' 
-        <n1:v>12756</n1:v+  * **Method:** POST 
-      </hv+ 
-      <hv ts="2018-11-05T22:04:03.1530787Zgt="2018-11-06T02:37:03.454926Z"> +<code javascript> 
-        <n1:v>12757</n1:v+
-      </hv+    "credentials":
-      <hv ts="2018-11-06T02:40:03.61157Zgt="2018-11-06T04:52:03.1759539Z"> +        "name": "demo", 
-        <n1:v>12758</n1:v> +        "password": "demo" 
-      </hv> +    }, 
-      <hv ts="2018-11-06T04:55:03.14511Zgt="2018-11-06T06:40:03.8621601Z"> +    "request":
-        <n1:v>12759</n1:v> +        "commonSeriesParameters":
-      </hv> +            "from": "2026-06-20T00:00:00Z",  
-      <hv ts="2018-11-06T06:43:03.2063072Zgt="2018-11-06T08:55:03.3019409Z"> +            "to": "2026-07-17T00:00:00Z" 
-        <n1:v>12760</n1:v+        }, 
-      </hv+        "series":
-      <hv ts="2018-11-06T08:58:03.083875Zgt="2018-11-06T09:10:03.0695797Z"> +            { 
-        <n1:v>12761</n1:v+                "clientReference": "test1", 
-      </hv+                "provider":
-      <hv ts="2018-11-06T09:13:03.5389214Zgt="2018-11-06T09:19:03.5238805Z"> +                    "parameters":
-        <n1:v>12761</n1:v+                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
-      </hv+                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0" 
-      <!-- value without gt - ts and gt are equal--+                    } 
-      <hv ts="2018-11-06T09:22:03.9461503Z"> +                } 
-        <n1:v>12761</n1:v+            } 
-      </hv+        ] 
-    </vals+    }, 
-  </hist+    "dataSpecification":
-</getHistoryResult>+        "limits": { "count": 1000 } 
 +    }, 
 +    "segmentation":
 +        "requestState": "",  
 +        "serverState": ""  
 +    } 
 +
 +</code> 
 + 
 +**Response Details:** 
 +  * **v** - value 
 +  * **ts** - timestamp (start of validity period) 
 +  * **gt** goodthrough (end of validity period) 
 +  * **meta.interval** - expected interval between stored records. Useful to identify missing data
 + 
 +<code javascript> 
 +
 +    "result": { "code": 0, "subCode": 0, "message": "" }, 
 +    "data":
 +        "count": 1, 
 +        "historyData":
 +            { 
 +                "clientReference": "test1", 
 +                "provider":
 +                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15", 
 +                    "parameters":
 +                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0"
 +                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0" 
 +                    } 
 +                }, 
 +                "meta": { "type": "double", "unit": "h", "interval": "PT3M" }, 
 +                "values": [ 
 +                    { "v": 13851.4, "ts": "2026-06-25T12:00:00.000Z
 +                ] 
 +            } 
 +        ] 
 +    }, 
 +    "segmentation": { "requestState": "", "serverState": ""
 +
 +</code
 + 
 +==== api/get/history/specific ==== 
 +**Request:** 
 +  * **URL:** ''/api/get/history/specific?format=json'' 
 +  * **Method:** POST 
 +  * **dataSpec:** Defines the specific point to fetch (e.g., 2 = First value less than reference time). 
 +  * **refTime:** Reference time required for specific temporal searches. 
 + 
 +<code javascript
 +
 + "cred":
 +  "n": "demo", 
 +  "p": "demo" 
 + }, 
 + "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
 + "offset": 0, 
 + "count": 1000, 
 + "dataSpec": 2,  
 + "refTime": "\/Date(1692788459000)\/", 
 + "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"
 +
 +</code
 + 
 +===== Writing Data & Execution ===== 
 + 
 +==== api/set/values ==== 
 +**Request:** 
 +  * **URL:** ''/api/set/values?format=xml'' 
 +  * **Method:** POST 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<setValuesRequest xmlns:r="http://dev.rcware.eu/serialization/referencesxmlns="http://dev.rcware.eu/scada/datapoints" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/comm-props" > 
 +   <n2:cred n="demo" p="demo"/> 
 +        <values projId="1b2623be-eaa4-4e29-8596-c66dd85d5643"
 +            <dps
 +                <d id="07d538d9-9f4b-46ca-ba4d-13b13b5302ff"
 +                    <props> 
 +                        <p n="Source" t="2024-02-23T09:58:00Z" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09"> 
 +                            <n1:v>23</n1:v> 
 +                        </p
 +                    </props> 
 +                </d> 
 +            </dps> 
 +        </values> 
 +</setValuesRequest> 
 +</code> 
 + 
 +==== api/set/executeActions ==== 
 +**Request:** 
 +  * **URL:** ''/api/set/executeActions?format=xml'' 
 +  * **Method:** POST 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs" xmlns:n2="http://dev.rcware.eu/scada/basic-propsxmlns:n1="http://dev.rcware.eu/auth" xmlns:r="http://dev.rcware.eu/serialization/references"> 
 +  <n1:cred n="demo" p="demo"/> 
 +  <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0"
 +    <actions
 +      <actionDefItem propName="INIT" dpId="afc22e18-f8e4-4e08-899c-fb9e4759df3d"
 +        <execParam r:type="495c9644-eed1-4b94-933b-3fae702a9aca"> 
 +          <n2:value>16</n2:value> 
 +        </execParam
 +      </actionDefItem
 +      <actionDefItem propName="ZAPdpId="34306c80-73f1-4465-ab51-2b2c1e85ab70"> 
 +      </actionDefItem> 
 +    </actions
 +  </actionDefs
 +</executeActionsRequest> 
 +</code> 
 + 
 +==== api/set/history & api/replace/history ==== 
 +Attribute **i** sets **interval** (ISO 8601) in which the next value should be expected. All date/time values must be in UTC. 
 + 
 +**Replace History Request Example:** 
 +  * **URL:** ''/api/replace/history?format=xml'' 
 +  * **Method:** POST 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<replaceHistoryRequest xmlns="http://dev.rcware.eu/scada/history" xmlns:n2="http://dev.rcware.eu/authxmlns:n1="http://dev.rcware.eu/scada/basic-props" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="e86dba6d-1250-4e7f-aafb-84fd28324710" from="2020-03-15T11:00:00+00:00" to="2020-03-18T11:00:00+00:00"> 
 +  <n2:cred n="demo" p="demo"/> 
 +  <vals
 +    <hv ts="2020-03-15T11:00:00+00:00i="P1D"> 
 +      <n1:v>2.7</n1:v> 
 +    </hv> 
 +    <hv ts="2020-03-16T11:00:00+00:00i="P1D"> 
 +      <n1:v>3.0</n1:v> 
 +    </hv> 
 +  </vals> 
 +</replaceHistoryRequest> 
 +</code> 
 + 
 +===== Projects Management ===== 
 + 
 +==== api/get/projects ==== 
 +**Request:** 
 +  * **URL:** ''/api/get/projects?format=xml'' 
 +  * **Method:** POST 
 + 
 +<code javascript> 
 +
 + "cred": 
 +  "n": "demo", 
 +  "p": "demo" 
 + }, 
 + "offset"0, 
 + "count": 250 
 +} 
 +</code
 + 
 +**Response:** 
 +<code xml
 +<?xml version="1.0" encoding="utf-8"?> 
 +<getProjectsResult xmlns:r="http://dev.rcware.eu/serialization/referencesxmlns="http://dev.rcware.eu/scada/projects"> 
 +    <projects> 
 +        <project id="2a7f1615-..." name="Weather" /> 
 +        <project id="1b2623be-eaa4-4e29-8596-c66dd85d5643" name="SIMPLE_DEMO" /> 
 +        <project id="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0name="PLYNOVA_KOTELNA" /> 
 +        <project id="b9ad5380-...name="CVUT_HERBERTOV" /
 +        <project id="843855a2-..." name="PRVNI_KROKY" /> 
 +    </projects
 +</getProjectsResult
 +</code
 + 
 +==== api/get/projectByParts ==== 
 +To get the visual tree and list of datapoints. 
 + 
 +**Request:** 
 +  * **URL:** ''/api/get/projectByParts?format=xml'' 
 +  * **Method:** POST 
 + 
 +<code javascript> 
 +
 + "cred": { 
 +  "n": "demo", 
 +  "p": "demo" 
 + }, 
 + "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
 + "treeId""Visual tree", 
 + "partType"0, 
 + "offset": 0, 
 + "count": 250 
 +
 +</code
 + 
 +===== Matlab Client ===== 
 + 
 +==== General Notes ==== 
 +  * Parameter names **ID** and **Guid** are used interchangeably in the Matlab client; it is always a universally unique identifier referring to a project or datapoint. 
 +  * When plural is used, an array of guids is expected (ie. ''{'guid1', 'guid2'}'' ), otherwise just one guid is expected. 
 + 
 +==== ScadaClient ==== 
 +<code matlab>ScadaClient(url, username, password)</code> 
 +Constructor of the Mervis API wrapper. 
 + 
 +==== findAllDPsWithReqTags ==== 
 +<code matlab>findAllDPsWithReqTags(projIds, tags)</code> 
 +Returns list of datapoints based on tags query. Example of tags definition''{'label','indoor_air_temperature';'room_type','office'}''  
 + 
 +==== getDpTags ==== 
 +<code matlab>getDpTags(projectId, DpId)</code
 +Returns tags of the particular datapoint. 
 + 
 +==== getAllProjectDPs ==== 
 +<code matlab>getAllProjectDPs(projectGuid)</code
 +Returns project IDs and names that are accessible to the logged-in user. 
 + 
 +==== getData ==== 
 +<code matlab>[data, time, dataInCell, info] = getData(projID, dpsIds, from, to, span, zone, doublesInterpolationMethod, interpolate_gaps_shorter_than)</code> 
 +Downloads data. 
 +  * **span:** sampling interval in seconds, default is 300 sec. 
 +  * **zone:** time zone ('local' or 'utc') applied to parameters and output, default is 'local'
 +  * **Returns:** ''data'' (NaN used for missing values), ''time'', ''dataInCell'' (useful for strings), and ''info''
 + 
 +**Data Download Example:** 
 +<code matlab> 
 +scada = ScadaClient('https://scada.mervis.info/','demo','demo');  
 + 
 +dataPointIDs = {'acad79f3-3358-42dd-9b74-98733e63d771','1afa7d9b-1183-4ab1-a6b1-18e464ae2d4d','e496bb8c-14ce-4c2c-b53b-3b71daeabca6'};  
 +projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0';  
 +chartLegend = {'Temp UT1','Temp UT1 Return','Valve Position'};  
 +from = now - 4;  
 +to = now;  
 +timeSpan = 300; %sec  
 + 
 +[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan);  
 + 
 +plot(time,data);   
 +legend(chartLegend);  
 +datetick; 
 +</code> 
 + 
 +==== saveData ==== 
 +<code matlab>saveData(projID, dpID, time, data)</code> 
 +Saves data into the Mervis database. 
 + 
 +==== setDataPointValue ==== 
 +<code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code> 
 +Sets a datapoint value using a button. Only numerical values are supported. Parameter ''buttonName'' is not mandatory; 'INIT' is used if undefined.
  
 +**Example:**
 +<code matlab>
 +dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f'; 
 +projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa'; 
 +buttonName = 'INIT';
 +newValue = 1;
  
 +scada = ScadaClient('https://scada.mervis.info/','demo','demo'); 
 +scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)
 </code> </code>
  
-==== Matlab ==== +==== deleteVariable ==== 
-^ Function                                                                                                                                  ^ Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ^ +<code matlab>deleteVariable(projGuid, dpGuid, from, to)</code> 
-| ScadaClient(url, username, password)                                                                                                      | Constructor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | +**Warning:** Deletes data of one variable based on from-to interval. If from-to is not defined, ALL data are deleted. Use carefully, there is no undo!
-| findAllDPsWithReqTags(projIds, tags)                                                                                                      | Returns list of datapoints based on tags query. Example of tags definition: {'label','indoor_air_temperature';'room_type','office'                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | +
-| saveData(projID, dpID, time, data)                                                                                                        | Saves data into the Mervis database.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | +
-deleteVariable(projGuid, dpGuid, from, to)                                                                                                Deletes data of one variable based on from - to interval. If from - to is not defined, all data are deleted. Use carefully, there is no undo!                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | +
-| [data, time, dataInCell, info] = getData(this,projID,dpsIds,from,to,span,zone,doublesInterpolationMethod, interpolate_gaps_shorter_than)  | Surprisingly, it downloads data. Span is a sampling interval in seconds, default is 300 sec. Zone is time zone 'local' or 'utc' is applied to from/to parameters as well as to output time, default is 'local'. DoubleInterpolationMethod is same as e.g. interp1, applied to double values only the other types use method 'previous'. Interpolate_gaps_shorter_than - interpolates missing values periodes that are not shorer than this parameter (in seconds). Return parameters: data - downloaded data resampled, NaN is used for missing values; time - datenum time axis according to selected zone; dataInCell - usefull for strings; info - summary info about the request. |                                                                                                                                           | getDpTags(projectId, DpId)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Returns tags of the particular datapoint. +
-|+
  • © Energocentrum Plus, s.r.o. 2017 - 2026