Dynamics Mobile exposes REST API via https allowing third parties to receive IoT events

API Version: 1.0
Documentation Version 1.0

API root

Dynamics Mobile exposes REST HTTP API based on exchange of JSON messages. There are certain API resources which support xml payloads as well. The API can be accessed on the following address:

https://api.cloud.dynamicsmobile.com

API Version

There might be multiple versions of the API , so clients must specify the version of the API to use by providing the version as part of the address.

Version Date Description
v1 2016-Dec-01 Version #1 of the API. We might add more version in the future

https://api.cloud.dynamicsmobile.com/v1

IоТ

The Internet of Things API is placed under the iot resource

https://api.cloud.dynamicsmobile.com/v1/iot

Application Area

The application area is a short name , usually abbreviation of the organization’s name , defined when the organization’s primary Dynamics Mobile account is created.

All requests must include the application area:

https://api.cloud.dynamicsmobile.com/v1/iot/apparea/{appArea}

Let’s assume that the application area is demo. The requests url have to start in the following way:

https://api.cloud.dynamicsmobile.com/v1/iot/apparea/demo

Authentication

All requests to Dynamics Mobile API requires the client application to authenticate by providing correct API key in the headers of the request.
The API key can be managed in the Dynamics Mobile control panel by the administrator user.
The API key is passed in the HTTP Header x-api-key

Errors

The API will respond with HTTP Status 200 on successful request. The API will respond with HTTP Error status ( 4x, 5x) on failed requests. The body of the response contains description of the error.

method: Get Pending IoT Events

All IoT devices sent events to Dynamics Mobile Cloud and the events are stored locally and made available for receiving via the API. It is supposed that the client application will poll the method on a predefined interval. The recommended interval is between 30 and 60 seconds.
Client application may receive the list of the pending events by using the following HTTP REST call:

METHOD: GET
HEADERS: x-api-key: {your api key}, Content-Type:application/json
URL: https://api.cloud.dynamicsmobile.com/{version}/iot/apparea/{appArea}/synclog

Parameters

Parameter Type Description
limit integer

The minimum value is 1 and the maximum value is 10. The default value is 10, if the parameter is skipped.

 Defines the maximum number of pending events to return in the result
format string

Accepts the following values, only:

  • json:  the result of the pending events will be returned in JSON
  • xml:  the result of the pending events will be returned in XML
 Defines the format of the result. If the parameter is skipped, the default format is json

 

Request Examples:

Obtaining 1 pending event in JSON format:
Request To: https://api.cloud.dynamicsmobile.com/v1/iot/apparea/demo/synclog?limit=1&format=json
------------------------------------------------------------------------------------------------
GET v1/iot/apparea/demo/synclog?limit=1&format=json HTTP/1.1
Host: api.cloud.dynamicsmobile.com
x-api-key: C2PFG567DSFJFRKxx8j8udnsssds5psdrmMqaMM6TurivhwdsfK9
Cache-Control: no-cache
strong>Obtaining 10 pending events in XML format
Request To: https://api.cloud.dynamicsmobile.com/v1/iot/apparea/demo/synclog?limit=10&format=xml
------------------------------------------------------------------------------------------------
GET v1/iot/apparea/demo/synclog?limit=10&format=xml HTTP/1.1
Host: api.cloud.dynamicsmobile.com
x-api-key: C2PFG567DSFJFRKxx8j8udnsssds5psdrmMqaMM6TurivhwdsfK9
Cache-Control: no-cache

https://api.cloud.dynamicsmobile.com/v1/iot/apparea/demo/synclog?limit=10&format=xml

The actual format of the returned response depends on the format parameter provided in the request

Response

NOTE: the response may contain more fields than specified here, because it contains all fields sent by the IoT hardware together with fields “added” by Dynamics Mobile to the event.

The document contains the fields ,which are always contained in the response.

The order of the field in the response may be different.

Parameter Type Description
_deviceId string the unique serial number of the IoT device
_datetime long the javascript timestamp when the event was received in the cloud
_appArea string the name of the application area
_groupName string the name of group where the IoT device is assigned
_client string unique identifier of the client or other related entity ( vendor for example)
_clientName string the name of the client or other related entity ( vendor for example)
_title string the name of the client or other related entity ( vendor for example)
_location string the unique identifier of the location of the of the client(vendor, etc.) where the event occured. You may think if it like Client address
_longitude double longitute fragment of the GPS position of the IoT hardware
_latitude double latitude fragment of the GPS position of the IoT hardware
_geohash string geohash representation of the reported gps location of the IoT hardware
_voltage double level of the voltage reported by the hardware. The actual value depends on the hardware.
_eventId string type of the event occured in the IoT hardware as reported from the hardware. The actual value depends on the hardware.
_subAppArea string The subApArea is depends on the IoT device group where the subAppArea is configured. Usually this represents a company or sub-division or another characteristic of the group where the IoT hardware belongs
receiptHandle string Unique identifier of the event within Dynamics Mobile. Shall be used in Purge method to delete the received message
id string Unique identifier of the event within Dynamics Mobile. Shall be used in Purge method to delete the received message

 

JSON response – example:

you provide json in the format parameter of the request. The response will contain the list of the pending events in JSON format if the format parmeter is json

Request:

GET https://api.cloud.dynamicsmobile.com/v1/iot/apparea/demo/synclog?limit=2&format=json

Response:

[
{
"_deviceId": "TEST03",
"_deviceType": "aws-btn",
"_datetime": 1481109533545,
"_appArea": "demo",
"_groupName": "Warehouse",
"_client": "CUST001",
"_clientName": "N.A.",
"_title": "N.A.",
"_location": "GABROVO",
"_longitude": 0,
"_latitude": 0,
"_geohash": "",
"_eventId": "2",
"_voltage": 2000,
"_subAppArea": "Cronus",
"receiptHandle": "AQEBxO2i0SWz/HUxkT5Q4G..",
"id": "69c7bdef-9883-42d2-9479-18ff54f94f66"
},
{
"_deviceId": "TEST03",
"_deviceType": "aws-btn",
"_datetime": 1481109689108,
"_appArea": "demo",
"_groupName": "Warehouse",
"_client": "CUST001",
"_clientName": "N.A.",
"_title": "N.A.",
"_location": "GABROVO",
"_longitude": 0,
"_latitude": 0,
"_geohash": "",
"_eventId": "2",
"_voltage": 2000,
"_subAppArea": "Cronus",
"receiptHandle": "AQEBTVq5HsoEUghF9O3d7tMBxFxDB...",
"id": "18d08c7e-f8a6-40d2-99c6-15254535f297"
}
]

 

XML response – example:

Request:

GET https://api.cloud.dynamicsmobile.com/v1/iot/apparea/demo/synclog?limit=2&format=xml

Response:

<messages>
<message>
<_deviceid>TEST03</_deviceid>
<_devicetype>aws-btn</_devicetype>
<_datetime>1481109533545</_datetime>
<_apparea>demo</_apparea>
<_groupname>Warehouse</_groupname>
<_client>CUST001</_client>
<_clientname>N.A.</_clientname>
<_title>N.A.</_title>
<_location>GABROVO</_location>
<_longitude>0</_longitude>
<_latitude>0</_latitude>
<_geohash></_geohash>
<_eventid>2</_eventid>
<_voltage>2000</_voltage>
<_subapparea>Cronus</_subapparea>
<receipthandle>AQEBw3+fA7dGPklAhBx68loWhL6JLC3T42oiCgA//oB....</receipthandle>
<id>69c7bdef-9883-42d2-9479-18ff54f94f66</id>
</message>
<message>
<_deviceid>TEST03</_deviceid>
<_devicetype>aws-btn</_devicetype>
<_datetime>1481109689108</_datetime>
<_apparea>demo</_apparea>
<_groupname>Warehouse</_groupname>
<_client>CUST001</_client>
<_clientname>N.A.</_clientname>
<_title>N.A.</_title>
<_location>GABROVO</_location>
<_longitude>0</_longitude>
<_latitude>0</_latitude>
<_geohash></_geohash>
<_eventid>2</_eventid>
<_voltage>2000</_voltage>
<_subapparea>Cronus</_subapparea>
<receipthandle>AQEB8vfjDHwkSCJSrlOClWP+pSvFHcVwH/QbWUvfTQ...</receipthandle>
<id>18d08c7e-f8a6-40d2-99c6-15254535f297</id>
</message>
</messages>

method: Purge Pending IoT Events

Client application must call the PURGE method in order to confirm that the events processing is completed, after the events are received with the Get-Pending-Events method. This will effectively delete the list events defined in the request payload from the cloud storage and will make sure they will not be received again.

Note that if PURGE method is not called within 30 seconds after the event is received, the old events may be received again on a subsequent calls to the Get-Pending-Events method.

METHOD: POST
HEADERS: x-api-key: {your api key}, Content-Type:application/json
URL: https://api.cloud.dynamicsmobile.com/{version}/iot/apparea/{appArea}/synclog/purge

Parameters

Parameter Type Description
format string

Accepts the following values, only:

  • json:  instructs the server that format of the POST payload is JSON.
  • xml:  instucts the server that the format of the POST payload is XML
 Defines the format of POST payload sent to the server from the client. If skipped, the payload will be considered as JSONn

 

The request method is POST and requires payload. If the format of the request is specified as json in the format parameter of the request, the client must provide the list of the pending events as they are received from the SynLog/Get method ,described above. This will delete all events found within the paload from the server and will make them unavailable for receiving again.

Examples

Request:

Purge 2 events in JSON format:
Request To: https://api.cloud.dynamicsmobile.com/v1/iot/apparea/demo/synclog/purge?format=json
------------------------------------------------------------------------------------------------
POST v1/iot/apparea/demo/synclog/purge?format=json HTTP/1.1
Host: api.cloud.dynamicsmobile.com
x-api-key: C2PFG567DSFJFRKxx8j8udnsssds5psdrmMqaMM6TurivhwdsfK9
Cache-Control: no-cache
[
{
"serialNumber": "TEST03",
"clickType": "2",
"batteryVoltage": "2000 mV",
"_deviceId": "TEST03",
"_deviceType": "aws-btn",
"_datetime": 1481109533545,
"_appArea": "demo",
"_groupName": "Warehouse",
"_client": "CUST001",
"_clientName": "N.A.",
"_title": "N.A.",
"_location": "GABROVO",
"_longitude": 0,
"_latitude": 0,
"_geohash": "",
"_eventId": "2",
"_voltage": 2000,
"_subAppArea": "Cronus",
"receiptHandle": "AQEBxO2i0SWz/HUxkT5Q4G..",
"id": "69c7bdef-9883-42d2-9479-18ff54f94f66"
},
{
"serialNumber": "TEST03",
"clickType": "2",
"batteryVoltage": "2000 mV",
"_deviceId": "TEST03",
"_deviceType": "aws-btn",
"_datetime": 1481109689108,
"_appArea": "demo",
"_groupName": "Warehouse",
"_client": "CUST001",
"_clientName": "N.A.",
"_title": "N.A.",
"_location": "GABROVO",
"_longitude": 0,
"_latitude": 0,
"_geohash": "",
"_eventId": "2",
"_voltage": 2000,
"_subAppArea": "Cronus"',
"receiptHandle": "AWERSDVSHsoEUghwrO3d7tMBxqweqB...",
"id": "18d08c7e-f8a6-40d2-99c6-15254535f297"
}
]

Last Updated: Dec 1, 2015

Support lifecycle

We provide public releases of our products once a year or more and commit to 12 months support for all public releases. We also provide releases to support the new versions of Microsoft Dynamics NAV and Microsoft Dynamics AX within 12 months after a new version of the ERP is released.

Service Level Agreement

We envision the support as a major component of our effort to provide our customers with mission critical software solutions. We provide support services to customers in order to guarantee their business continuity. Our customer shall report issues or other cases, which requires support. The reporting is performed by authorized personnel from the Customer’s side via the standard support channels described below.

The support is provided in order to:

  • Solve current problems reported by authorized representatives of the Customer on occasion and in connection with Dynamics Mobile
  • Diagnose problems in connection with the standard system functionality
  • Diagnose problems in connection with the functionality customized by Dynamics Mobile team
  • Analyze and eliminate of any “defect” – a mistake in the program code of functionality, whcih affects the Client’s operations

The support services are only provided in response to a support request submitted by authorized personnel from the Customer’s side via any of the support channels:

  • -e-mail: support@dynamcsmobile.com
  • -phone: 00359 2 817 33 63

We provide different response times to support requests based on the request priority as follows:

Priority Reaction time Description
Critical to 2 hour Causes business process block.
Medium up to 8 hours Affects the business process as there are no work around actions.
Low up to 2 business days Low impact issues and requests, which does not affect the system.