Mervis SCADA API

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 technical support.

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.

Below is the complete list of available API endpoints and their definitions.

Request:

• URL: /api/v2/get/authenticate?format=json
• Method: POST

Standard login:

{"data":{"cred":{"n":"demo","p":"demo"}}}

Domain-specific login:

{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}}

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.
• notifyNearingPwdExpirationIn (TimeSpan or null) - Indicates how long before the password expires a notification should be displayed.

{
    "data": {
        "ChangePwdBefore": null,
        "ClientType": 2,
        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1",
        "DomainName": "GlobalDomain",
        "FullName": "GlobalDomain\\demo",
        "Login": "demo",
        "NotifyNearingPwdExpirationIn": null,
        "Token": "3:93d3c832-0f1b-4cde-a0eb-1fd346f5a9c0",
        "TokenValidFor": "P1D",
        "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e",
        "Username": ""
    },
    "result": { "code": 0, "codeTxt": null, "dataType": null, "desc": null }
}

Note: Use api/v2/get/authenticate instead.

Request:

• URL: /api/checkCredentials?format=xml
• Method: POST

{"cred":{"n":"demo","p":"demo"}}
// or with full name:
{"cred":{"n":"GlobalDomain\\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.

The right way to retrieve current values of data points (property “Output”) from one or multiple projects.

Request:

• URL: /api/get/values?format=xml
• Method: POST

{
 "cred": { "t": "xxxxxx" },
 "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>
   </dps>
  </v>
 </vals>
</values>

Downloading one or multiple trends with a single API call.

Rules:

• Always use “token” instead of “name” and “password”. Non-token calls are slower.
• “seriesParameters” [optional] - use only if requesting different parameters than “commonSeriesParameters”.
• “clientReference” [optional] - use for your own identification of the series.
• Items “segmentation”, “requestState”, and “serverState” should always copy the values from the last server response. The first call should use an empty “segmentation”.

Request:

• URL: /api/v3/get/history?format=json
• Method: POST

{
    "credentials": { "token":"guid" },
    "request": {
        "commonSeriesParameters": {
            "from": "2018-12-01T00:00:00Z", 
            "to": "2018-12-01T10:00:00Z"
        },
        "series": [
            {
                "clientReference": "myId1a",
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
                    }
                }
            }
        ]
    },
    "dataSpecification": {
        "limits": { "count": 1000 }
    },
    "segmentation": {
        "requestState": "", 
        "serverState": "" 
    }
}

Response Details:

• v - value
• ts - timestamp (start of validity period)
• gt - goodthrough (end of validity period)
• i - interval (only present if it differs from Meta section)
• meta.interval - expected interval between stored records. Useful to identify missing data.

Request:

• URL: /api/get/history/specific?format=json
• Method: POST
• dataSpec: Defines the specific point to fetch:
  • 0 = MinTimestamp
  • 1 = MaxTimestamp
  • 2 = FirstLessThanReferenceDateTime
  • 3 = FirstLessThanOrEqualThanReferenceTime
  • 4 = FirstGreaterThanReferenceDateTime
  • 5 = FirstGreaterThanOrEqualThanReferenceTime
  • 6 = MaxGoodThroughTime
• refTime: Reference time required for dataSpecs 2 through 5.

{
 "cred": { "t": "xxxxxx" },
 "projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed",
 "offset": 0,
 "count": 1000,
 "dataSpec": 2, 
 "refTime": "\/Date(1692788459000)\/",
 "dpIds": ["58426e69-46ba-4925-9a5c-d7d65efb9886"]
}

Request:

• URL: /api/get/history?format=xml
• Method: POST

{  
   "cred":{ "n":"demo", "p":"demo" },
   "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
   "dpId":"62cf4083-31ed-4bc1-be25-044ba837a9f0", 
   "from":"/Date(1541199600000)/", 
   "to":"/Date(1541496190357)/",  
   "offset":0,
   "count":5000,
   "historyState":"" 
}

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">
  <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1">
    <errMsg/>
    <vals>
      <hv ts="2018-11-02T21:26:08.7936747Z" gt="2018-11-03T20:35:08.8060769Z">
        <n1:v>12754</n1:v>
      </hv>
    </vals>
  </hist>
</getHistoryResult>

Request:

• URL: /api/set/values?format=xml
• Method: POST

<?xml version="1.0" encoding="UTF-8"?>
<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 t="xxxxxx"/>
        <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>

Request:

• URL: /api/set/executeActions?format=xml
• Method: POST

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

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

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

Request:

• URL: /api/get/projects?format=xml
• Method: POST

{
 "cred": { "t": "xxxxxx" },
 "offset": 0,
 "count": 250
}

To get the visual tree and 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
}

• 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(url, username, password)

Constructor of the Mervis API wrapper.

findAllDPsWithReqTags(projIds, tags)

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

getDpTags(projectId, DpId)

Returns tags of the particular datapoint.

getAllProjectDPs(projectGuid)

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

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

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'.
• doublesInterpolationMethod: applied to double values (e.g., interp1); other types use 'previous'.
• interpolate_gaps_shorter_than: interpolates missing value periods shorter than this parameter (in seconds).
• Returns: data (NaN used for missing values), time, dataInCell (useful for strings), and info.

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 = {'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;

saveData(projID, dpID, time, data)

Saves data into the Mervis database.

setDataPointValue(projGuid, dpGuid, value, buttonName)

Sets a datapoint value using a button (primarily the INIT button). Only numerical values are supported. Parameter buttonName is not mandatory; 'INIT' is used if undefined.

Example:

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

deleteVariable(projGuid, dpGuid, from, to)

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!