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 [2023/09/26 14:41]
v.kohout [api/get/history/specific] 		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 open, REST-like API based on JSON and XML data formats for seamless integration with third-party applications. For a full description of advanced features, please contact our [[:en:help:20-support|technical support]].
  
-**Important:** Only officially supported response format is XML! +**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. 
-===== List of basic API methods =====+
  
-^Function^Description| +===== Supported API Methods =====
-^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||+
  
 +Below is the consolidated list of recommended API endpoints. Note: Only methods with fully documented and verified examples are listed below.
  
 +^ 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.
  
-===== Examples =====+===== Authentication =====
  
-====api/checkCredentials====+==== api/v2/get/authenticate ==== 
 +**Request:** 
 +  * **URL:** ''/api/v2/get/authenticate?format=json'' 
 +  * **Method:** POST
  
-**Request**+Standard login: 
 +<code javascript> 
 +{"data":{"cred":{"n":"demo","p":"demo"}}} 
 +</code>
  
-   * URL: /api/checkCredentials?format=xml +Domain-specific login: 
-   * Method: POST+<code javascript> 
 +{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}} 
 +</code> 
 + 
 +**Response Properties:** 
 +  * **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":{"n":"demo","p":"demo"}}+{ 
 +    "data": { 
 +        "ChangePwdBefore": null, 
 +        "ClientType": 2, 
 +        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1", 
 +        "DomainName": "GlobalDomain", 
 +        "FullName": "GlobalDomain\\demo", 
 +        "Login": "demo", 
 +        "NotifyNearingPwdExpirationIn": null, 
 +        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f", 
 +        "TokenValidFor": "P1D", 
 +        "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"?>
-<checkCredentialsResult xmlns:r="http://dev.rcware.eu/serialization/references" d="GlobalDomain" l="demo" t="2:85be00d3-5875-4dec-a9b4-c98e2ff2acbe" xmlns="http://dev.rcware.eu/auth" />+<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> 
 +  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z"> 
 +   <dps> 
 +    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true"> 
 +     <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> 
 +      </p> 
 +     </props> 
 +    </d> 
 +   </dps> 
 +  </v> 
 + </vals> 
 +</values>
 </code> </code>
- 
-  * You **should** use the received token **t** in subsequent API calls. 
- 
- 
  
 ==== api/v3/get/history ==== ==== api/v3/get/history ====
 +Downloading one or multiple trends with a single API call.
  
-**Request** +**Rules:** 
- +  * 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".
-   * 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".+
  
 +**Request:**
 +  * **URL:** ''/api/v3/get/history?format=json''
 +  * **Method:** POST
  
 <code javascript> <code javascript>
 { {
     "credentials": {     "credentials": {
-        "token":"guid" //string+        "name": "demo", 
 +        "password": "demo"
     },     },
     "request": {     "request": {
         "commonSeriesParameters": {         "commonSeriesParameters": {
-            "from": "2018-12-01T00:00:00Z", //UTC dateTime +            "from": "2026-06-20T00:00:00Z",  
-            "to": "2018-12-01T10:00:00Z"//UTC dateTime+            "to": "2026-07-17T00:00:00Z"
         },         },
         "series": [         "series": [
             {             {
-                "seriesParameters": { +                "clientReference": "test1",
-                    "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": {                 "provider": {
                     "parameters": {                     "parameters": {
Line 106: Line 148:
     },     },
     "dataSpecification": {     "dataSpecification": {
-        "limits": { +        "limits": { "count": 1000 }
-            "count": 1000 //int +
-        }+
     },     },
     "segmentation": {     "segmentation": {
-        "requestState": ";;2;;0", //string +        "requestState": "",  
-        "serverState": "xyz" //string+        "serverState": "" 
     }     }
 } }
 </code> </code>
  
-**Response** +**Response Details:** 
- +  * **v** - value 
-   * Empty "segmentation" ("requestState") marks response containing last data of the requested series +  * **ts** - timestamp (start of validity period) 
-   * "requestState" and "serverState" must be copied to the next API call +  * **gt** - goodthrough (end of validity period) 
-   * Values +  * **meta.interval** - expected interval between stored records. Useful to identify missing data.
-     * 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.+
  
 <code javascript> <code javascript>
 { {
-"result": { +    "result": { "code": 0, "subCode": 0, "message": "" },
-        "code": 0, //int +
-        "subCode": 0, //int +
-        "message": "" //string +
-    },+
     "data": {     "data": {
-        "count": 3, //int+        "count": 1,
         "historyData": [         "historyData": [
             {             {
-                "clientReference": "myId2a", //string +                "clientReference": "test1",
-                "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": {                 "provider": {
 +                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15",
                     "parameters": {                     "parameters": {
                         "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",                         "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
Line 171: Line 178:
                     }                     }
                 },                 },
-                "meta": { +                "meta": { "type": "double", "unit": "h", "interval": "PT3M" },
-                    "type": "double", +
-                    "unit": "hod", +
-                    "interval": "PT3M" +
-                },+
                 "values": [                 "values": [
-                    { +                    { "v": 13851.4, "ts": "2026-06-25T12:00:00.000Z" }
-                        "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": { +    "segmentation": { "requestState": "", "serverState": "" }
-        "requestState": "xyz", //string +
-        "serverState": "xyz" //string +
-    }+
 } }
- 
- 
-</code> 
- 
-**Demo** 
-<code javascript> 
-{ 
-    "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 
-        } 
-    } 
-} 
- 
 </code> </code>
  
 ==== api/get/history/specific ==== ==== api/get/history/specific ====
- +**Request:** 
-**Request** +  * **URL:** ''/api/get/history/specific?format=json'' 
- +  * **Method:** POST 
-   * URL: /api/get/history/specific?format=json +  * **dataSpec:** Defines the specific point to fetch (e.g., 2 = First value less than reference time). 
-   * Method: POST +  * **refTime:** Reference time required for specific temporal searches.
-   * 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 +
  
 <code javascript> <code javascript>
 { {
- "cred": + "cred": { 
- { +  "n": "demo", 
-  "n":"test", +  "p": "demo"
-  "p":"test"+
  },  },
-  "projId":"b4d96a6d-2b3d-48eb-af30-d11e875ba7ed", + "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
-  "offset":0, + "offset": 0, 
-  "count":1000, + "count": 1000, 
-  "dataSpec":2,  + "dataSpec": 2,  
-  "refTime":"\/Date(123)\/", + "refTime": "\/Date(1692788459000)\/", 
-  "dpIds":["58426e69-46ba-4925-9a5c-d7d65efb9886","f4501a2e-62ed-430e-9346-5e155e730fe3","28e7d087-917a-456a-9d02-96882f572286"]+ "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
 } }
 </code> </code>
  
-**Response** +===== Writing Data & Execution =====
- +
-   * Values +
-     * v - value +
-     * ts - timestamp - start of the value validity period +
-     * gt - goodthrough - end of the value validity period +
-     * i - interval +
- +
-<code javascript> +
-{ +
-    "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" +
-            } +
-        } +
-    } +
-} +
- +
-</code> +
- +
-==== [Depricated] api/get/history==== +
- +
-**Request** +
- +
-   * URL: /api/get/history?format=xml +
-   * Method: POST +
- +
-<code javascript> +
-{   +
-   "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 +
-} +
-</code>+
  
-**Response**+==== api/set/values ==== 
 +**Request:** 
 +  * **URL:** ''/api/set/values?format=xml'' 
 +  * **Method:** POST
  
 <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"> +<setValuesRequest xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="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"/> 
-  @Interval - ISO interval of trend values defined by the database client. +        <values projId="1b2623be-eaa4-4e29-8596-c66dd85d5643"> 
-  @historyState - to be copied into the next request +            <dps> 
-  @nextValOfs - to be copied into the next request until value -1 is reached. +                <d id="07d538d9-9f4b-46ca-ba4d-13b13b5302ff"> 
-  If ts of value in not within the interval time span after the previous value's gt - some data is missing. +                    <props> 
-   +                        <p n="Source" t="2024-02-23T09:58:00Z" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09"> 
-  --> +                            <n1:v>23</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 through, value is valid in the whole time span between these two--> +            </dps> 
-      <hv ts="2018-11-02T21:26:08.7936747Z" gt="2018-11-03T20:35:08.8060769Z"> +        </values> 
-        <n1:v>12754</n1:v> +</setValuesRequest>
-      </hv> +
-      <hv ts="2018-11-03T20:41:09.0100479Z" gt="2018-11-05T11:35:08.7415158Z"> +
-        <n1:v>12754</n1:v> +
-      </hv> +
-      <hv ts="2018-11-05T11:40:04.0077949Z" gt="2018-11-05T17:25:03.4285643Z"> +
-        <n1:v>12754</n1:v> +
-      </hv> +
-      <hv ts="2018-11-05T17:28:03.4133447Z" gt="2018-11-05T19:40:03.0246122Z"> +
-        <n1:v>12755</n1:v> +
-      </hv> +
-      <hv ts="2018-11-05T19:43:03.6499981Z" gt="2018-11-05T22:01:03.2620552Z"> +
-        <n1:v>12756</n1:v> +
-      </hv> +
-      <hv ts="2018-11-05T22:04:03.1530787Z" gt="2018-11-06T02:37:03.454926Z"> +
-        <n1:v>12757</n1:v> +
-      </hv> +
-      <hv ts="2018-11-06T02:40:03.61157Z" gt="2018-11-06T04:52:03.1759539Z"> +
-        <n1:v>12758</n1:v> +
-      </hv> +
-      <hv ts="2018-11-06T04:55:03.14511Z" gt="2018-11-06T06:40:03.8621601Z"> +
-        <n1:v>12759</n1:v> +
-      </hv> +
-      <hv ts="2018-11-06T06:43:03.2063072Z" gt="2018-11-06T08:55:03.3019409Z"> +
-        <n1:v>12760</n1:v> +
-      </hv> +
-      <hv ts="2018-11-06T08:58:03.083875Z" gt="2018-11-06T09:10:03.0695797Z"> +
-        <n1:v>12761</n1:v> +
-      </hv> +
-      <hv ts="2018-11-06T09:13:03.5389214Z" gt="2018-11-06T09:19:03.5238805Z"> +
-        <n1:v>12761</n1:v> +
-      </hv> +
-      <!-- value without gt - ts and gt are equal--> +
-      <hv ts="2018-11-06T09:22:03.9461503Z"> +
-        <n1:v>12761</n1:v> +
-      </hv> +
-    </vals> +
-  </hist> +
-</getHistoryResult> +
- +
 </code> </code>
  
- +==== api/set/executeActions ==== 
-====api/set/history==== +**Request:** 
- +  * **URL:** ''/api/set/executeActions?format=xml'' 
-**Request** +  * **Method:** POST
- +
-   * 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. +
- +
-<code xml> +
-<?xml version="1.0" encoding="UTF-8"?> +
-<setHistoryRequest xmlns="http://dev.rcware.eu/scada/history"  +
-xmlns:n2="http://dev.rcware.eu/auth"  +
-xmlns:n1="http://dev.rcware.eu/scada/basic-props"  +
-projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0"  +
-dpId="e86dba6d-1250-4e7f-aafb-84fd28324710"> +
-  <n2:cred t="xxxxx"/><!-- token should be used here --> +
-  <vals> +
-    <hv ts="2020-03-15T11:00:00+00:00" i="P1D"> +
-      <n1:v>2.7</n1:v> +
-    </hv> +
-    <hv ts="2020-03-16T11:00:00+00:00" i="P1D"> +
-      <n1:v>3.0</n1:v> +
-    </hv> +
-    <hv ts="2020-03-17T11:00:00+00:00" i="P1D"> +
-      <n1:v>2.0</n1:v> +
-    </hv> +
-    <hv ts="2020-03-18T11:00:00+00:00" i="P1D"> +
-      <n1:v>2.3</n1:v> +
-    </hv> +
-  </vals> +
-</setHistoryRequest></code> +
- +
-**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. +
- +
-<code xml> +
-<?xml version="1.0" encoding="UTF-8"?> +
-<replaceHistoryRequest xmlns="http://dev.rcware.eu/scada/history"  +
-xmlns:n2="http://dev.rcware.eu/auth"  +
-xmlns: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 t="xxxxx"/><!-- token should be used here --> +
-  <vals> +
-    <hv ts="2020-03-15T11:00:00+00:00" i="P1D"> +
-      <n1:v>2.7</n1:v> +
-    </hv> +
-    <hv ts="2020-03-16T11:00:00+00:00" i="P1D"> +
-      <n1:v>3.0</n1:v> +
-    </hv> +
-    <hv ts="2020-03-17T11:00:00+00:00" i="P1D"> +
-      <n1:v>2.0</n1:v> +
-    </hv> +
-    <hv ts="2020-03-18T11:00:00+00:00" i="P1D"> +
-      <n1:v>2.3</n1:v> +
-    </hv> +
-  </vals> +
-</replaceHistoryRequest></code> +
- +
-**Response** +
- +
-   * 200 OK +
- +
-====api/set/executeActions==== +
- +
-**Request** +
- +
-   * URL: /api/set/executeActions?format=xml +
-   * Method: POST +
-   * Content-Type: text/xml+
  
 <code xml> <code xml>
 <?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
-<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs"  +<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs" xmlns:n2="http://dev.rcware.eu/scada/basic-props" xmlns:n1="http://dev.rcware.eu/auth" xmlns:r="http://dev.rcware.eu/serialization/references"> 
-xmlns:n2="http://dev.rcware.eu/scada/basic-props"  +  <n1:cred n="demo" p="demo"/>
-xmlns:n1="http://dev.rcware.eu/auth"  +
-xmlns:r="http://dev.rcware.eu/serialization/references"> +
-  <n1:cred t="xxxxxx"/>+
   <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0">   <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0">
     <actions>     <actions>
Line 591: Line 256:
     </actions>     </actions>
   </actionDefs>   </actionDefs>
-</executeActionsRequest></code>+</executeActionsRequest> 
 +</code>
  
-**Response**+==== 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.
  
-<code xml><?xml version="1.0" encoding="utf-8"?> +**Replace History Request Example:** 
-<executeActionsResponse xmlns:r="http://dev.rcware.eu/serialization/references" code="Ok" message="OK" xmlns="http://dev.rcware.eu/scada/error-reporting" /></code>+  * **URL:** ''/api/replace/history?format=xml'' 
 +  * **Method:** POST
  
-====api/get/values====+<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<replaceHistoryRequest xmlns="http://dev.rcware.eu/scada/history" xmlns:n2="http://dev.rcware.eu/auth" xmlns: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:00" i="P1D"> 
 +      <n1:v>2.7</n1:v> 
 +    </hv> 
 +    <hv ts="2020-03-16T11:00:00+00:00" i="P1D"> 
 +      <n1:v>3.0</n1:v> 
 +    </hv> 
 +  </vals> 
 +</replaceHistoryRequest> 
 +</code>
  
-The right way how to retrieve current values of data points (property "Output" which is usually what you want) from one or multiple projects.+===== Projects Management =====
  
-**Request** +==== api/get/projects ==== 
- +**Request:** 
-   * URL: /api/get/values?format=xml +  * **URL:** ''/api/get/projects?format=xml'' 
-   * Method: POST+  * **Method:** POST
  
 <code javascript> <code javascript>
 { {
  "cred": {  "cred": {
-  "t": "xxxxxx" //token+  "n": "demo", 
 +  "p": "demo"
  },  },
- "propNamesToSerialize": ["Output"], 
  "offset": 0,  "offset": 0,
- "count": 1000, + "count": 250
- "serverState": null, +
- "dps": [{ +
-   "projId": "ba1a92f7-f213-4a72-90e4-f7142b50274b", +
-   "dpIds": ["e089dde2-a097-4e0d-8012-c8cf3dc62694", "1089dde2-a097-4e0d-8012-c8cf3dc62696"] +
-  } +
- ]+
 } }
 +</code>
  
 +**Response:**
 +<code xml>
 +<?xml version="1.0" encoding="utf-8"?>
 +<getProjectsResult xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="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-7ebe87a12fd0" name="PLYNOVA_KOTELNA" />
 +        <project id="b9ad5380-..." name="CVUT_HERBERTOV" />
 +        <project id="843855a2-..." name="PRVNI_KROKY" />
 +    </projects>
 +</getProjectsResult>
 </code> </code>
  
-**Response** +==== api/get/projectByParts ==== 
- +To get the visual tree and list of datapoints.
-<code xml><?xml version="1.0" encoding="utf-8"?> +
-<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2020-04-07T07:46:34.850422Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints"> +
- <vals> +
-  <v projId="ba1a92f7-f213-4a72-90e4-f7142b50274b" dataVersion="637217783110000000" serverTime="2020-04-07T07:46:34.850422Z"> +
-   <dps> +
-    <d id="e089dde2-a097-4e0d-8012-c8cf3dc62694" serAlr="true"> +
-     <props> +
-      <p n="Output" t="2020-04-07T07:43:42.1000676Z" q="Bad" r:type="177e726a-3180-4152-bef2-6254e7055e1f"> +
-       <n1:v>ON</n1:v> +
-      </p> +
-     </props> +
-    </d> +
-    <d id="1089dde2-a097-4e0d-8012-c8cf3dc62696" serAlr="true"> +
-     <props> +
-      <p n="Output" t="2020-04-07T07:45:00.2408399Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55"> +
-       <n1:v>0</n1:v> +
-      </p> +
-     </props> +
-    </d> +
-   </dps> +
-  </v> +
- </vals> +
-</values></code> +
- +
-====api/get/projectByParts==== +
- +
-To get the list of datapoints. +
- +
-**Request**+
  
-   * URL: /api/get/projectByParts?format=xml +**Request:** 
-   * Method: POST+  * **URL:** ''/api/get/projectByParts?format=xml'' 
 +  * **Method:** POST
  
 <code javascript> <code javascript>
 { {
  "cred": {  "cred": {
-  "t": "xxxxxx"+  "n": "demo", 
 +  "p": "demo"
  },  },
  "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",  "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
Line 673: Line 334:
 </code> </code>
  
-**Response** 
- 
-<code xml><?xml version="1.0" encoding="utf-8"?> 
-<getProjectByPartsResult xmlns:r="http://dev.rcware.eu/serialization/references" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dataVersion="637305748282414171" totalCount="79" nextOffset="-1" xmlns:n1="http://dev.rcware.eu/scada/comm-props" xmlns:n2="http://dev.rcware.eu/rt2com" xmlns:n3="http://dev.rcware.eu/scada/basic-props" xmlns:n4="http://dev.rcware.eu/scada/legacy-props" xmlns="http://dev.rcware.eu/scada/datapoints"> 
- <dps> 
-  <dp id="393df7b4-bb8d-4e8f-92a7-bf785508894a" n="Provozni podminky OK" canAct="true" canAlr="true"> 
-   <v> 
-    <props> 
-     <p n="Source" t="2020-10-05T07:17:11.601879Z" q="Good" n1:dateTimeKind="UTC" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09"> 
-      <n1:r n2:rp="PT0S" r:type="7b047602-40da-4095-9093-062ba30fd15e"> 
-       <n2:a id="3b1e3b8b-2186-4dcf-b157-8032c768d1e1" n="SW.Provozni podminky OK"/> 
-      </n1:r> 
-      <n1:w r:type="5ddc9dbf-a6bd-458b-a6ab-f661db0e3a64"> 
-       <n2:a id="3b1e3b8b-2186-4dcf-b157-8032c768d1e1" n="SW.Provozni podminky OK"/> 
-      </n1:w> 
-      <n1:v>1</n1:v> 
-     </p> 
-     <p n="Output" t="2020-10-05T07:16:58.751431Z" q="Good" r:type="177e726a-3180-4152-bef2-6254e7055e1f"> 
-      <n3:v>OK</n3:v> 
-     </p> 
-     <p n="StdVis_V1" t="2015-06-03T13:17:13.5190205Z" q="Good" r:type="b0db7bd7-0375-4830-90f2-6d918bac41ee"> 
-      <n3:v> 
-       <n3:props> 
-        <n3:p> 
-         <n3:pn>Output</n3:pn> 
-         <n3:props> 
-          <n3:p r:type="256a44f6-32e4-4a75-b7c2-08eed38f151d"> 
-           <n3:ordMap> 
-            <n3:grOrd> 
-             <n3:t>OK</n3:t> 
-             <n3:o>0</n3:o> 
-            </n3:grOrd> 
-            <n3:grOrd> 
-             <n3:t>ALARM</n3:t> 
-             <n3:o>1</n3:o> 
-            </n3:grOrd> 
-           </n3:ordMap> 
-          </n3:p> 
-         </n3:props> 
-        </n3:p> 
-       </n3:props> 
-      </n3:v> 
-     </p> 
-    </props> 
-   </v> 
-   <core r:type="2f04d90c-ee95-4cb6-b945-146e33021945"/> 
-  </dp> 
-  <dp id="3e5c0b88-45fd-4e3f-b1b2-1a365327ec90" n="Zaplavení" canAct="true" canAlr="true"> 
-   <v> 
-    <props> 
-     <p n="Source" t="2020-08-17T10:21:46.470472Z" q="Good" n1:dateTimeKind="UTC" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09"> 
-      <n1:r n2:rp="PT0S" r:type="7b047602-40da-4095-9093-062ba30fd15e"> 
-       <n2:a id="45c31fe4-00b0-4498-b9f6-adfe6a2fe34b" n="SW.Zaplavení mem"/> 
-      </n1:r> 
-      <n1:w r:type="5ddc9dbf-a6bd-458b-a6ab-f661db0e3a64"> 
-       <n2:a id="45c31fe4-00b0-4498-b9f6-adfe6a2fe34b" n="SW.Zaplavení mem"/> 
-      </n1:w> 
-      <n1:v>0</n1:v> 
-     </p> 
-     <p n="Output" t="2020-08-17T10:21:46.470472Z" q="Good" r:type="177e726a-3180-4152-bef2-6254e7055e1f"> 
-      <n3:v>OK</n3:v> 
-     </p> 
-     <p n="StdVis_V1" t="2015-06-03T13:17:13.5190205Z" q="Good" r:type="b0db7bd7-0375-4830-90f2-6d918bac41ee"> 
-      <n3:v> 
-       <n3:props> 
-        <n3:p> 
-         <n3:pn>Output</n3:pn> 
-         <n3:props> 
-          <n3:p r:type="256a44f6-32e4-4a75-b7c2-08eed38f151d"> 
-           <n3:ordMap> 
-            <n3:grOrd> 
-             <n3:t>OK</n3:t> 
-             <n3:o>0</n3:o> 
-            </n3:grOrd> 
-            <n3:grOrd> 
-             <n3:t>ALARM</n3:t> 
-             <n3:o>1</n3:o> 
-            </n3:grOrd> 
-           </n3:ordMap> 
-          </n3:p> 
-         </n3:props> 
-        </n3:p> 
-       </n3:props> 
-      </n3:v> 
-     </p> 
-    </props> 
-   </v> 
-   <core r:type="2f04d90c-ee95-4cb6-b945-146e33021945"/> 
-   <alr> 
-    <def enabled="true" delay="PT1M"/> 
-    <galrs/> 
-    <status user="SYSTEM" incidentId="88ba7198-de57-4854-8130-60c240a09522" lastChangeTime="2020-08-11T12:37:04.8002341Z"/> 
-   </alr> 
-  </dp> 
- </dps> 
-</getProjectByPartsResult></code> 
 ===== Matlab Client ===== ===== Matlab Client =====
-==== General notes client function parameters ==== 
-  * parameter names ID and Guid are used interchangeably in the Matlab client, it is always a universally unique identifier referring to project or a particular datapoint 
-  * when plural is used, array of guids is expected (ie. {'guid1', 'guid2'}), otherwise just one guid is expected (ie. 'guid1') 
  
-==== Data download example ====+==== 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.
  
-<code matlab>scada = ScadaClient('https://scada.mervis.info/','demo','demo'); +==== 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'};  dataPointIDs = {'acad79f3-3358-42dd-9b74-98733e63d771','1afa7d9b-1183-4ab1-a6b1-18e464ae2d4d','e496bb8c-14ce-4c2c-b53b-3b71daeabca6'}; 
 projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0';  projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0'; 
-chartLegend = {'/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1','/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1 zpátečka','/Plynová kotelna/ÚT1 - SEVER/Poloha ventilu'}; +chartLegend = {'Temp UT1','Temp UT1 Return','Valve Position'}; 
 from = now - 4;  from = now - 4; 
 to = now;  to = now; 
Line 789: Line 378:
 plot(time,data);   plot(time,data);  
 legend(chartLegend);  legend(chartLegend); 
-datetick;</code> +datetick; 
- +</code>
- +
-==== ScadaClient ==== +
- +
-<code matlab>ScadaClient(url, username, password)</code> +
- +
-Constructor of 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'}   +
  
-==== saveData====+==== saveData ====
 <code matlab>saveData(projID, dpID, time, data)</code> <code matlab>saveData(projID, dpID, time, data)</code>
 Saves data into the Mervis database. Saves data into the Mervis database.
- 
-==== deleteVariable ==== 
-<code matlab>deleteVariable(projGuid, dpGuid, from, to)</code> 
-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! 
  
 ==== setDataPointValue ==== ==== setDataPointValue ====
 <code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code> <code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code>
-Sets data point value using a button (primary the INIT button). Only numerical values are supported. Parameter buttonName is not mandatory. Value 'INIT' is used if buttonName is not defined. +Sets a datapoint value using a button. Only numerical values are supported. Parameter ''buttonName'' is not mandatory; 'INIT' is used if undefined.
- +
-{{ :en:mervis-scada:init.png?direct&800 |}}+
  
 **Example:** **Example:**
Line 822: Line 393:
 dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f';  dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f'; 
 projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa';  projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa'; 
-buttonName = 'INIT' %see action ("button") name in Mervis SCADA GUI+buttonName = 'INIT';
 newValue = 1; newValue = 1;
  
-scada = ScadaClient('https://scada.mervis.info/','username','password'); +scada = ScadaClient('https://scada.mervis.info/','demo','demo'); 
 scada.setDataPointValue(projectId, dpGuid, newValue, buttonName) scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)
- 
 </code> </code>
-==== getData==== 
-<code matlab>[data, time, dataInCell, info] = getData(projID,dpsIds,from,to,span,zone,doublesInterpolationMethod, interpolate_gaps_shorter_than)</code> 
-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==== +==== deleteVariable ==== 
-<code matlab>getDpTags(projectId, DpId) </code> +<code matlab>deleteVariable(projGuid, dpGuid, from, to)</code> 
-Returns tags of the particular datapoint. +**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!
- +
- +
-==== getAllProjectDPs==== +
-<code matlab>getAllProjectDPs(projectGuid)</code> +
-Returns project IDs and names that are accessible to logged user.+
  • © Energocentrum Plus, s.r.o. 2017 - 2026