Access the State of a Machine

    The tapio (core) State API is part of the tapio core system and provides information about the digital device twin of a machine inside tapio. You can retrieve the current state of a machine trough the State API. You won't receive realtime events, when the current state of a machine changes.

    It can be used to get the current state of tapio machines.

    Query Machine State

    To be able to make requests to the State API, you first need to register a tapio application and assign machines to the application. You won't receive data for machines that are not assigned to your application.
    Authentication for State API is done via Azure AD B2C. See our guide on authentication for more details.

    You can retrieve the latest state of a machine using the following request:

    POST https://core.tapio.one/api/machines/state

    Use for the token request the ResourceId https://tapiousers.onmicrosoft.com/CoreApi otherwise you get an Unauthorized.

    You may wonder, why we are using an HTTP POST request to query data. We're using HTTP POST because, we're passing the actual query (containing machine id's etc.) in the request body. State API is even capable of processing multiple queries in one request. This means, our request body will contain an array of JSON object, each representing a query:

    NOTE: Use Content-Type: application/json;charset=UTF-8 in your request headers

    Basic structure of request body is a JSON array of machine queries:

    [
        {
            "tmid": "0000000001aabb",
            "ks": [],
            "excond": true
        },
        {
            "tmid": "0000000002aabb",
            "ks": [],
            "excond": false,
            "exitd": false
        },
        ...
    ]

    Each machine query has the following properties:

    Property Description
    tmid string: The tapio machine id
    ks array of strings: List of item data keys to return, returns ALL item data when empty
    excond optional bool: return also condition states in response
    exitd optional bool: do not return any data item information in response, overrules ks

    Example request:

    [
        {
            "tmid": "0000000001aabb",
            "ks": [
                "State.CurrentStateGroup",
                "State.CurrentStateDescription",
                "DigitalTwin!AliveState",
                "RemainingTime.RemainingTimeInSec",
                "RemainingTime.TimePaused",
                "RemainingTime.TotalTimeInSec"
            ],
            "excond": true
        },
        {
            "tmid": "0000000002aabb",
            "ks": [
                "State.CurrentStateGroup",
                "State.CurrentStateDescription",
                "DigitalTwin!AliveState",
                "Energy!ElectricPower"
            ],
            "excond": true
        }
    ]

    The State API will then return an array of the requested machine states.

    Basic structure of response body is a JSON array of machine queries:

    Each machine query has the following properties:

    Property Description
    tmid string: The tapio machine id
    itds array of item date: List of item data.
    conds array of condition: List of condition.
    [
        {
            "tmid": "0000000002aabb",
            "itds": [],
            "conds": []
        }
    ]

    The struct of itds and conds are described.

    [
        {
            "tmid": "0000000002aabb",
            "itds": [
                {
                    "v": 0,
                    "k": "LeftPanelStates.000.State",
                    "vt": "i",
                    "u": null,
                    "q": "g",
                    "sts": "2018-09-03T13:51:32.099116+02:00",
                    "rts": "2018-09-03T13:51:35.3033155+02:00"
                },
                {
                    "v": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAG9SURBVFhH7ZY9SANBEEbvTCIWapXCMlYBqyiks0ghWIqokMpesBNSaClCrIQU2ghaBEFsgtgY7QJiZ28jVgoRsRIVyfnmbhAhhtvF5CIkDz5mdnZnd3bvh3X69Dxuo9HYcF13RNvGeJ4XI29L/V3Mq/iWxKSAGybKaMCWcbV3aq2g8Ee/APwERZwF4XBIzDB+Fve7AGIX2GrQNGIBpRwpANWCmBksVkRCSuUxx752G8H4CnoY0HbXkALk6M79liFs+Aod4L6gJ7SNTpENZWR1av8XTiPJ80xrM3pYfA/dowLFxDUcHSw8j+S9kK+hiqa0KxRXbRPMNYQZC1rh6M5XkHzfg6jMv2IdfeLbwy7ysqO/wBw1TE6n/JVO/wcSalvStkcgkLOKWUSjSB5BAb1JX0fhqLPoUo/9GjOjXdHAokfoGZX05KKFhdOR77ptUP0akhfHGHY7LXnYYTly/Dya0G4jGJ8ld0mcOqpo3AgSm+4DUNRuIxh/yLrdvw/IlayOvUUnfsSMHN/3HPbnlewYa3OSy2jSL4DJkkHMmrZcSnco4F1jxpAsF9lN3Dh+Cf8j6DGHvJZ/4j69guN8AW62ZXUM0zjWAAAAAElFTkSuQmCC",
                    "k": "LeftPanelStates.000.Image",
                    "vt": "b",
                    "u": null,
                    "q": "g",
                    "sts": "2018-09-03T13:51:32.099116+02:00",
                    "rts": "2018-09-03T13:51:35.3033155+02:00"
                },
                {
                    "v": {
                        "de": "Ein",
                        "en": "Off"
                    },
                    "k": "LeftPanelStates.000.Text",
                    "vt": "dss",
                    "u": null,
                    "q": "g",
                    "sts": "2018-09-03T13:51:32.099116+02:00",
                    "rts": "2018-09-03T13:51:35.3033155+02:00"
                },
                {
                    "k": "LeftPanelStates.000.Value",
                    "vt": "n",
                    "u": null,
                    "q": "b",
                    "sts": "2018-09-03T13:51:32.099116+02:00",
                    "rts": "2018-09-03T13:51:35.3033155+02:00"
                },
                {
                    "v": 0,
                    "k": "LeftPanelStates.000.IsVisible",
                    "vt": "i",
                    "u": null,
                    "q": "g",
                    "sts": "2018-09-03T13:51:32.099116+02:00",
                    "rts": "2018-09-03T13:51:35.3033155+02:00"
                }
            ],
            "conds": [
                {
                    "p": "AlarmsAndErrors",
                    "k": "ns=2;s=Simu.0000000002AaBb.0002-ConditionError01",
                    "s": "ns=2;s=Simu.0000000002AaBb",
                    "as": 1,
                    "sv": 1000,
                    "ls": null,
                    "lm": {
                        "de": "Dies ist ein Fehler",
                        "en": "This is an error"
                    },
                    "vls": {
                        "SourceNode": {
                            "t": "n"
                        },
                        "AckedState/Id": {
                            "v": 0,
                            "t": "i"
                        }
                    },
                    "sts": "2018-09-03T13:53:08.1804467+02:00",
                    "rts": "2018-09-03T13:53:08.4125751+02:00"
                },
                {
                    "p": "AlarmsAndErrors",
                    "k": "ns=2;s=Simu.0000000002AaBb.0002-ConditionMaintenance01",
                    "s": "ns=2;s=Simu.0000000002AaBb",
                    "as": 1,
                    "sv": 200,
                    "ls": null,
                    "lm": {
                        "de": "Dies ist eine Wartung",
                        "en": "This is a maintenance"
                    },
                    "vls": {
                        "SourceNode": {
                            "t": "n"
                        },
                        "AckedState/Id": {
                            "v": 0,
                            "t": "i"
                        }
                    },
                    "sts": "2018-09-03T13:53:08.8505748+02:00",
                    "rts": "2018-09-03T13:53:09.4075737+02:00"
                }
            ]
        }
    ]

    Query Machine State V2

    POST https://core.tapio.one/api/v2/machines/state

    The main advantage of new version of api is that caller receives proper information about machine state, especially online/offline via "isOnline" property. In old route, in case that machine is offline, the client received just an empty response, which is quite confusing. An other advantage is that new route returns back a reponse, which consists of valid data and invalid data. Invalid data contains information about which requests where failed and what was a reason. It helps client to diagnose and better understand an issue.

    Basic structure of request body is a JSON array of machine queries:

    [
        {
            "tmid": "0000000001aabb",
            "ks": [],
            "excond": true
        },
        {
            "tmid": "0000000002aabb",
            "ks": [],
            "excond": false,
            "exitd": false
        },
        ...
    ]

    Each machine query has the following properties:

    Property Description
    tmid string: The tapio machine id
    ks array of strings: List of item data keys to return, returns ALL item data when empty
    excond optional bool: return also condition states in response
    exitd optional bool: do not return any data item information in response, overrules ks

    Example request:

    [
        {
            "tmid": "0000000001aabb",
            "ks": [
                "State.CurrentStateGroup",
                "State.CurrentStateDescription",
                "DigitalTwin!AliveState",
                "RemainingTime.RemainingTimeInSec",
                "RemainingTime.TimePaused",
                "RemainingTime.TotalTimeInSec"
            ],
            "excond": true
        },
        {
            "tmid": "0000000002aabb",
            "ks": [
                "State.CurrentStateGroup",
                "State.CurrentStateDescription",
                "DigitalTwin!AliveState",
                "Energy!ElectricPower"
            ],
            "excond": true
        }
    ]

    The State API will then return a structure, which consists of an array of the requested machine states and an array of invalid requests.

    Basic structure of response body is a JSON object:

    {
        "lastKnownStateResponses": [ // an array of valid last know state responses
            {
                "tmid": "1122334455",
                "itds": [],
                "conds": [],
                "isOnline": false // machine is offline
            },
            {
                "tmid": "1122334455",
                "itds": [...],
                "conds": [...],
                "isOnline": true // machine is online
            }
        ],
        "invalidRequests": [ // an array of invalid requests
            {
                "request": { // failed request
                    "tmid": "tdmtest223344556677",
                    "ks": [],
                    "excond": false,
                    "exitd": false
                },
                "code": "403", // error code
                "message": "The application with clientId '24af0cc6-89a2-402c-ade7-cd4dfc25a62e' is not allowed to read the state of the machine 'tdmtest223344556677'.", // error message
                "details": [] // error details
            }
        ]
    }

    You will find a detailed description on the response object within our documentation about Data Categories - Last known state.

    Read historical data