API

Mervis SCADA offers open REST-like API based on JSON and XML data formats. For full description please contact our technical support.

Important: Only officially supported response format is XML!

FunctionDescription
api/checkCredentials
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

api/checkCredentials

Request

  • URL: /api/checkCredentials?format=xml
  • Method: POST
{"cred":{"n":"demo","p":"demo"}}

Response

<?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" />
  • 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
        }
    }
}

[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

<?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">
  <!--
  @Interval - ISO interval of trend values defined by the database client.
  @historyState - to be copied into the next request
  @nextValOfs - to be copied into the next request until value -1 is reached.
  If ts of value in not within the interval time span after the previous value's gt - some data is missing.
 
  -->
  <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1">
    <errMsg/>
    <vals>
      <!--ts - time stamp, gt - good through, value is valid in the whole time span between these two-->
      <hv ts="2018-11-02T21:26:08.7936747Z" gt="2018-11-03T20:35:08.8060769Z">
        <n1:v>12754</n1:v>
      </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>

api/set/history

Request

  • URL: /api/set/history?format=xml
  • Method: POST
  • Content-Type: text/xml

Attribute i sets interval (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.

<?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>

Response

  • 200 OK

api/set/executeActions

Request

  • URL: /api/set/executeActions?format=xml
  • Method: POST
  • Content-Type: text/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-props" 
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">
    <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="ZAP" dpId="34306c80-73f1-4465-ab51-2b2c1e85ab70">
      </actionDefItem>
    </actions>
  </actionDefs>
</executeActionsRequest>

Response

<?xml version="1.0" encoding="utf-8"?>
<executeActionsResponse xmlns:r="http://dev.rcware.eu/serialization/references" code="Ok" message="OK" xmlns="http://dev.rcware.eu/scada/error-reporting" />

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

<?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>

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

<?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>

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

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 = {'/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1','/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1 zpátečka','/Plynová kotelna/ÚT1 - SEVER/Poloha ventilu'}; 
from = now - 4; 
to = now; 
timeSpan = 300; %sec 
 
[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan); 
 
plot(time,data);  
legend(chartLegend); 
datetick;

ScadaClient

ScadaClient(url, username, password)

Constructor of Mervis API wrapper.

findAllDPsWithReqTags

findAllDPsWithReqTags(projIds, tags)

Returns list of datapoints based on tags query. Example of tags definition: {'label','indoor_air_temperature';'room_type','office'}

saveData

saveData(projID, dpID, time, data)

Saves data into the Mervis database.

deleteVariable

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!

setDataPointValue

setDataPointValue(projGuid, dpGuid, value, buttonName)

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.

Example:

dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f'; 
projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa'; 
buttonName = 'INIT' %see action ("button") name in Mervis SCADA GUI
newValue = 1;
 
scada = ScadaClient('https://scada.mervis.info/','username','password'); 
scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)

getData

[data, time, dataInCell, info] = getData(projID,dpsIds,from,to,span,zone,doublesInterpolationMethod, interpolate_gaps_shorter_than)

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

getDpTags(projectId, DpId) 

Returns tags of the particular datapoint.

getAllProjectDPs

getAllProjectDPs(projectGuid)

Returns project IDs and names that are accessible to logged user.