|
Reporting Service |
  
|
Reporting Service
|
Reporting Service |
|
Overview
The "Reporting Service" is an MCL-Mobility Platform service designed to provide specific data to authorized back-end systems (ex: lists of sites, applications, operators, operator groups, devices, device operators, etc., as well as current information on a device or operator - status, power mode, battery status, login status, etc.).
The Back-ends module manages the back-end profiles you create for the back-end systems that are authorized to communicate/request data from your MCL-Mobility Platform account and it is where you will find more technical documentation on back-end requests that rely on the "Reporting" service (a back-end profile's "Back-end Details" page - "Services" tab).
Back-end Requests via the Reporting Service
The data exchange between the back-end and your MCL-Mobility Platform account consists of data requests/corresponding answers.
There are two types of data the back-end can retrieve regarding the account's entities- Topology data and Dynamic data.
Topology Data - refers to generic information that does NOT change due to account activity. It is a type of data normally used for inventory purposes.
For instance, a site's topology data would consist of the name, the associated subscription code, timezone, the total of associated devices, etc..
In the case of a device, it would be the model, the manufacturer, the device group it is included in, its configuration, etc..
There are specific endpoints to retrieve an account entity's topology data (ex: "masterdata/sitelist", "masterdata/sitedetails", "masterdata/devicegrouplist", masterdata/operators", etc.).
Dynamic Data - refers to information that is affected by account activity, meaning, it is current data that is constantly being updated. This type of data is used for monitoring purposes.
For example the dynamic data of a device would be the last contact, battery level, power mode, gps coordinates, network info, etc., and for an operator it would be the login status.
There are specific endpoints to request dynamic data from your account/subscription (ex: "devicestatus/devicedetails", "devicestatus/lowbattery")
Reporting Service Limits
There are some limitations to the data exchange between back-end and MCL-Mobility Platform:
•There is a limit of 50 back-end requests per minute for each back-end profile. So, if a back-end requests a specific report more than 50 times within the same minute, it will get the corresponding "HTTP 429 error" responses until the next minute is reached.
•Always consider the entity and the type of information you want to retrieve when defining a back-end request. For instance, not all account entities provide dynamic data (ex: sites).
•The result to a back-end request is limited to 1000 records. To avoid exceeding this limit, we recommend:
a. you use a specific endpoint for each entity and define specific parameters.
Ex: Instead of defining 1 request for the total number of devices within the account, define a request of devices per site (use the endpoint for a site + identify the site) or even define a request per site and per device group (use the endpoint for the site + identify the site and add the "devicegroup" parameter to identify/specify the group of devices to be returned).
b. you use a series of requests with an "offset" parameter to retrieve a complete list of the intended data.
Possible Queries
Below are examples of the information on account/subscription entities you can retrieve, if you use specific endpoints and parameters in a back-end request:
Queries on Sites
•Site List - Returns a list with all the sites of your account/subscription.
•Site Details - Returns topology data on the specified site. It requires identifying the intended site (a parameter with the site's Id).
Queries on Device Groups
•Device Group List - Returns a list with all the device groups of your account/subscription.
If you want a device group list from a specific site, the back-end request must include a parameter to identify the intended site (a parameter with the site's Id).
•Device Group Details - Returns topology data on the specified device group.
It requires identifying the intended device group (a parameter with the device group's Id).
Queries on Devices
•Device List - Returns a list of all the devices associated to your account/subscription.
If you want to limit the request's range to the devices of a specific site, identify the site (with a parameter with the site's Id).
If you only want to retrieve the devices of a specific device group, use a parameter with the device group's id.
•Device Details - Depending on the endpoint and parameters used in the back-end request, it returns the specified device's topology data (ex: the manufacturer, the model, the device group it belongs to, etc.) and/or specific dynamic data (ex: the device's current location, its current power mode, last time it contacted the account, etc.).
Queries on Operator Groups
•Operator Group List - Returns a list with all the operator groups of your account/subscription.
If you want an operator group list from a specific site, the back-end request must include a parameter to identify the intended site (a parameter with the site's Id).
•Operator Group Details - Returns topology data on the specified operator group.
It requires identifying the intended operator group (a parameter with the operator group's Id).
Queries on Operators
•Operator List - Returns a list of all the operators associated to your account/subscription.
Identify a specific site (use a parameter with the site's id) in the back-end request, if you want to limit the response to the operators of the specified site.
If you only want to retrieve the operators of a specific operator group, identify the operator group in the back-end request (with a parameter with the operator group's Id).
•Operator Details - Depending on the endpoint and parameters used in the back-end request, it returns the specified operator's topology data (ex: the login ID, the operator's name, the operator group it belongs to, etc.) and/or specific dynamic data (ex: the operator's login status).
For more detailed and technical information on back-end requests, check the available documentation for download:
•"reporting-doc.txt"
Available in your account - in a back-end profile's "Back-end Details" page. (See "Services" tab.)
•"Reporting - JAVA API for the MCL-Mobility Platform Reporting Service. pdf"
•Zip file with jar files (mcl-reporting-javadoc.jar + mcl-reporting-sources.jar + mcl-reporting.jar)
Both are available in our MCL Support's knowledge base. You must register/log in to access these documents.