Introduction
The OpenGate Applications API is a Web REST based Interface that allows integration of external applications to the services provided by the OpenGate platform. The next figure shows the main features of the API:
The main features provided by the API are:
-
Inventory: Allows you to manage IoT/M2M physical resources as devices(communication devices, machines, sensors, etc.) and logical resources as communications lines (subscribers, subscriptions/lines).
-
Operations: Allows you to launch remote device operations over large amounts of inventory resources.
-
Alarms: Allows you to manage alarms associated to inventory resources.
-
Internet of Things (IoT) Information: Allows you to manage non structured information using the data stream paradigm that abstracts all information retrieved from devices, sensors and machines as independent "signals" that evolve through the time.
-
Catalogs: Allows you to introduce and search the catalogued information used by the platform as Manufacturers, Models, Operations, Alarm Rules, …
-
Admin/Config: Allows you to manage all administrable and configurable resources of the platform.
The main services are:
-
Provision Service: Allows to manage IoT/M2M resources inventory and all administrable resources provided by the platform.
-
Searching Service: Allows to retrieve all of the data managed by the platform using features as paging, filtering, sorting, etc. facilitating the handling of large amounts of information from devices, sensors, machines, etc. Through this API you can be walk through: Inventory resources, operations, alarms, data streams (IoT), etc.
-
Operations Service: Gives access to the operations engine and its scheduler to make easy performing remote operations (Diagnostics, Updating, other) on large amounts of devices, sensors or machines as an easy task.
API keys and authentication
The OpenGate API is enabled by default on all accounts. You don’t have to do anything to turn on this feature. However, API keys are used to control access to the resources via the API.
The OpenGate API allows third-party applications or back-office systems to communicate with OpenGate. All users in your organization may use third-party applications to access your entities data such as iPhone apps, Android apps, or network-based communication built onto your own server.
The API keys is sent using an HTTP header. An example of GET requests may look like either:
curl --request POST \ --data-binary @device.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices \ -H "Content-type: application/json"
Additionally, it is possible to use basic authentication to identify yourself to the API service, however it is recommended to use API keys rather than basic authentication if you are embedding your credentials in an application, otherwise there is a risk to your password.
OpenGate RESTful services and beyond
The OpenGate development team is always concerned about exposing loosely coupled services, with high level of interoperability. How they designed the OpenGate programming interfaces to achieve these targets? Well, they thought in the REST architectonic style plus standardized mime types to reach a high level of interoperability. RESTful services enables the use of nearly any programming language and the use of simple and powerful tools such as the fantastic GNU curl. If you didn’t it earlier, it’s a good time to check out the quick start section, there you can find the easy way with curl.
In the next figure you can see the API URI based tree
Response status and error messages
HTTP status codes
The OpenGate OSS API attempts to return appropriate HTTP status codes for every request.
Code | Text | Description |
---|---|---|
200 |
OK |
GET, PUT and DELETE operation Success! |
201 |
OK |
POST operation Success! |
204 |
No Content |
No elements found for the given URL. |
304 |
Not Modified |
There was no new data to return. |
400 |
Bad Request |
The request was invalid. An accompanying error message will explain why. |
401 |
Unauthorized |
Authentication credentials were missing or incorrect. |
403 |
Forbidden |
The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. |
404 |
Not Found |
The URI requested is invalid or the resource requested, does not exists. An accompanying error message will explain why. |
405 |
Not Allowed |
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. |
406 |
Not Acceptable |
Returned by the API when an invalid format is specified in the request. |
409 |
Conflict |
The request could not be completed due to a conflict with the current state of the resource |
412 |
Precondition Failed |
The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. |
500 |
Internal Server Error |
Something is broken. Please contact with your administrator. |
Error messages
When the OpenGate API returns error messages, it does so in JSON format.
Attribute (* required) | Description |
---|---|
code * |
code of error |
message * |
description of error |
context |
context of the error, attempts to clarify the point where the error occurs |
For example, an error requesting a non existent entity might look like this:
{ "errors":[ { "code":2, "message":"Json is malformed" } ] }
{ "errors":[ { "code":34, "message":"Sorry, that entity does not exist", "context" : [ {"name" : "param1", "value" : "value1"}, {"name" : "param2", "value" : "value2"}] } ] }
List of Errors
If you see an error response which is not listed in the above table, then fall back to the HTTP status code in order to determine the best way to address the error.
These errors are grouped according to the functionality or category to which they belong:
Categories | Subcategories |
---|---|
Generic Errors
Code | Returned HTTP Status | Description |
---|---|---|
0x00 |
HTTP 500 |
Service is unavailable now. Please repeat the last operation or contact with administrator. |
0x01 |
HTTP 400 |
Json is malformed. |
0x02 |
HTTP 400 |
Page out of range. |
0x03 |
HTTP 500 |
An action must be specified. |
0x04 |
HTTP 401 |
Unauthorized user for this operation. |
0x05 |
HTTP 503 |
Service is not reachable. |
0x06 |
HTTP 400 |
Content size limit exceeded. |
0x07 |
HTTP 204 |
No content found. |
0x08 |
HTTP 415 |
Unsupported media type. |
0x09 |
HTTP 409 |
There is conflict between two fields. |
0x0A |
HTTP 400 |
URL with error. |
0x0B |
HTTP 501 |
Not implemented. |
0x0C |
HTTP 400 |
Required part in multipart format not received. |
0x0D |
HTTP 500 |
Service is unavailable now. Please repeat the last operation or contact with administrator. |
Provision Service
Code | Returned HTTP Status | Description |
---|---|---|
0x010000 |
HTTP 400 |
Required field. |
0x010001 |
HTTP 400 |
Element already exists. |
0x010002 |
HTTP 400 |
Element not found. |
0x010003 |
HTTP 400 |
Forbidden field. |
0x010004 |
HTTP 400 |
Invalid format in field. |
0x010005 |
HTTP 400 |
Field cannot be modified. |
0x010006 |
HTTP 400 |
Entity not exists. |
0x010007 |
HTTP 400 |
User not exists. |
0x010008 |
HTTP 400 |
Field that begins like this is reserved. Check documentation. |
0x010009 |
HTTP 400 |
Admin data is incomplete. |
0x01000A |
HTTP 400 |
There cannot be id. |
0x01000B |
HTTP 400 |
Id required for this operation. |
0x01000C |
HTTP 400 |
Empty field. |
0x01000D |
HTTP 400 |
Missing field. |
0x01000E |
HTTP 400 |
Field not supported. |
0x01000F |
HTTP 400 |
Incorrect type in field. |
0x010010 |
HTTP 400 |
Minimum length not reached. |
0x010011 |
HTTP 400 |
Maximum length reached. |
0x010012 |
HTTP 400 |
Duplicated value. |
0x010013 |
HTTP 400 |
Incorrect value in field. |
0x010014 |
HTTP 400 |
Unspecified error. |
0x010015 |
HTTP 400 |
Organization not exists. |
0x010016 |
HTTP 400 |
There cannot be organization. |
0x010017 |
HTTP 400 |
Organization is required. |
0x010018 |
HTTP 400 |
Organization not allowed for this user. |
0x010019 |
HTTP 400 |
Organization cannot be removed. |
0x01001A |
HTTP 400 |
Error while creating inferred domain for organization. |
0x01001B |
HTTP 400 |
Error while creating inferred workgroup for organization. |
0x01001C |
HTTP 400 |
Name is required. |
0x01001D |
HTTP 400 |
There cannot be name. |
0x01001E |
HTTP 400 |
Duplicated name. |
0x01001F |
HTTP 400 |
Name is too long. |
0x010020 |
HTTP 400 |
In update operations, the field name of the json cannot be empty. |
0x010021 |
HTTP 400 |
Version is too long. |
0x010022 |
HTTP 400 |
Version is required. |
0x010023 |
HTTP 400 |
Country is required. |
0x010024 |
HTTP 400 |
There cannot be country. |
0x010025 |
HTTP 400 |
Country not exists. |
0x010026 |
HTTP 400 |
Language is required. |
0x010027 |
HTTP 400 |
There cannot be language. |
0x010028 |
HTTP 400 |
Language not exists. |
0x010029 |
HTTP 400 |
Channel not exists. |
0x01002A |
HTTP 400 |
There cannot be channel. |
0x01002B |
HTTP 400 |
Channel is required. |
0x01002C |
HTTP 400 |
Channel cannot be removed. |
0x01002D |
HTTP 400 |
Channel not allowed for this user. |
0x01002E |
HTTP 400 |
Channel cannot be removed because has entities associated. |
0x01002F |
HTTP 400 |
Channel not related to user’s workgroup. |
0x010030 |
HTTP 400 |
Workgroup not exists. |
0x010031 |
HTTP 400 |
Workgroup is required. |
0x010032 |
HTTP 400 |
Workgroup cannot be removed because it is in use. |
0x010033 |
HTTP 400 |
There cannot be workgroup. |
0x010034 |
HTTP 400 |
Workgroup not allowed for this user. |
0x010035 |
HTTP 400 |
Workgroup key not allowed for this user. |
0x010036 |
HTTP 400 |
Channel must belong to the domain of workgroup or one of its children. |
0x010037 |
HTTP 400 |
Description is too long. |
0x010038 |
HTTP 400 |
There cannot be description. |
0x010039 |
HTTP 400 |
Template conflict with number of parameters. |
0x01003A |
HTTP 400 |
Template conflict: incomplete parameters. |
0x01003B |
HTTP 400 |
Template is required. |
0x01003C |
HTTP 400 |
Template not found. |
0x01003D |
HTTP 400 |
Organization group not exists. |
0x01003E |
HTTP 400 |
Organization group is required. |
0x01003F |
HTTP 400 |
Organization group cannot be removed. |
0x010040 |
HTTP 400 |
Organization group not allowed for this user. |
0x010041 |
HTTP 400 |
Brand not exists. |
0x010042 |
HTTP 400 |
There cannot be brand. |
0x010043 |
HTTP 400 |
Effective date has bad format. Use ISO-8601. |
0x010044 |
HTTP 400 |
Effective date is in invalid range. It must be greater than the minimum time period set in the platform. |
0x010045 |
HTTP 400 |
There is already an effective date pending to update in cache. |
0x010046 |
HTTP 400 |
Relation between organization_group and organization not exists. |
0x010047 |
HTTP 400 |
Relation between workgroup and channel not exists. |
0x010048 |
HTTP 400 |
Empty box. |
0x010049 |
HTTP 400 |
Administrative bad format. |
0x01004A |
HTTP 400 |
There cannot be administrative. |
0x01004B |
HTTP 400 |
Domain is required. |
0x01004C |
HTTP 400 |
Domain not allowed for this user. |
0x01004D |
HTTP 400 |
There cannot be domain. |
0x01004E |
HTTP 400 |
Domain not exists. |
0x01004F |
HTTP 400 |
Domain cannot be removed because has associated users, certificates, organizations or another domains. |
0x010050 |
HTTP 400 |
Parent domain not allowed for this user. |
0x010051 |
HTTP 400 |
Parent domain not exists. |
0x010052 |
HTTP 400 |
Parent domain can not be changed. |
0x010053 |
HTTP 400 |
URL is too long. |
0x010054 |
HTTP 400 |
Notes is too long. |
0x010055 |
HTTP 400 |
Name is null. |
0x010056 |
HTTP 400 |
String is too long. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010100 |
HTTP 400 |
Device to provision already exist. |
0x010101 |
HTTP 400 |
Device to provision already exist in other relation. |
0x010102 |
HTTP 400 |
Subscriber to provision already exist. |
0x010103 |
HTTP 400 |
Subscription to provision already exist. |
0x010104 |
HTTP 400 |
Subscriber to provision already exist in other relation. |
0x010105 |
HTTP 400 |
Subscription to provision already exist in other relation. |
0x010106 |
HTTP 400 |
Device to update not exist. |
0x010107 |
HTTP 400 |
Subscriber to update not exist. |
0x010108 |
HTTP 400 |
Subscription to update not exist. |
0x010109 |
HTTP 400 |
Datastream is not defined in any datamodel or is forbidden to resource. |
0x01010A |
HTTP 400 |
Entity not allowed for this user. |
0x01010B |
HTTP 400 |
Entity/Entities not allowed for update. |
0x01010C |
HTTP 400 |
Triplet model, version, manufacturer not exists. |
0x01010D |
HTTP 400 |
Triplet software, version, type not exists. |
0x01010E |
HTTP 400 |
Datastream not collectable for this resource type. |
0x01010F |
HTTP 400 |
Resource type and json are incoherent. |
0x010110 |
HTTP 400 |
Device type is required. |
0x010111 |
HTTP 400 |
Device type not exists. |
0x010112 |
HTTP 400 |
You can only change gateway to asset and vice versa. |
0x010113 |
HTTP 400 |
Limit of devices reached in the organization. |
0x010114 |
HTTP 400 |
Entity duplicated. |
0x010115 |
HTTP 400 |
Entity cannot be removed. |
0x010116 |
HTTP 400 |
Entity key cannot be changed. |
0x010117 |
HTTP 400 |
Service group not exists. |
0x010118 |
HTTP 400 |
There cannot be service group. |
0x010119 |
HTTP 400 |
Service group is required. |
0x01011A |
HTTP 400 |
Administrative state not exists. |
0x01011B |
HTTP 400 |
There cannot be administrative state. |
0x01011C |
HTTP 400 |
Data bad format. |
0x01011D |
HTTP 400 |
Data not found. |
0x01011E |
HTTP 400 |
Data too long. |
0x01011F |
HTTP 400 |
Data is required. |
0x010120 |
HTTP 400 |
Provision type not exists. |
0x010121 |
HTTP 400 |
Data reset bad format. |
0x010122 |
HTTP 400 |
Provision data does not match the template. |
0x010123 |
HTTP 400 |
Data key contains not allowed characters (please check API documentation). |
0x010124 |
HTTP 400 |
Entity type not exists. |
0x010125 |
HTTP 400 |
Entity link bad formed. |
0x010126 |
HTTP 400 |
Entity link bad resource. |
0x010127 |
HTTP 400 |
Entity link relation not exist. |
0x010128 |
HTTP 400 |
Entity link must be at least between two entities. |
0x010129 |
HTTP 400 |
Entity link relation already exist. |
0x01012A |
HTTP 400 |
Entity link not found. |
0x01012B |
HTTP 400 |
IP bad format. |
0x01012C |
HTTP 409 |
Too many locks, please try it again or contact with administrator. |
0x01012D |
HTTP 400 |
Related device in device provisioning must be an Asset. |
0x01012E |
HTTP 400 |
Provisioned entity specific type does not exist. |
0x01012F |
HTTP 400 |
Provisioned postal code does not exist. |
0x010130 |
HTTP 400 |
Provisioned subscription mobile operator does not exist. |
0x010131 |
HTTP 400 |
Provisioned software, version, type and model do not exists. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010200 |
HTTP 400 |
This datamodel cannot be deleted, only will be deleted when organization is deleted. |
0x010201 |
HTTP 400 |
In this datamodel only can be modified qrating and storage fields. |
0x010202 |
HTTP 400 |
In this datamodel only can be removed qrating and storage fields. |
0x010203 |
HTTP 400 |
Max storage allowed in organization is minor than defined in datastream. |
0x010204 |
HTTP 400 |
Unknown ref type in datastream schema. |
0x010205 |
HTTP 400 |
Forbidden complex array type or external reference in datastream schema. |
0x010206 |
HTTP 400 |
The following datastream ids are in conflict in the same request. |
0x010207 |
HTTP 400 |
This datastream id is in conflict with an existing one. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010300 |
HTTP 400 |
Coordinates do not represent a valid geojson. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010400 |
HTTP 400 |
Cannot read certificate file. |
0x010401 |
HTTP 400 |
Certificate file is required. |
0x010402 |
HTTP 400 |
Certificate format unavailable. |
0x010403 |
HTTP 400 |
Certificate not exists. |
0x010404 |
HTTP 400 |
Child certificate not removable because only is signed by this certificate. |
0x010405 |
HTTP 400 |
Certificate not allowed. |
0x010406 |
HTTP 400 |
Parent certificate not exists. |
0x010407 |
HTTP 400 |
Specified hardware not exists. |
0x010408 |
HTTP 400 |
Some hardwares found with specified fields. |
0x010409 |
HTTP 400 |
Hardware is identified by its UUID or by their model, model version and manufacturer. |
0x01040A |
HTTP 400 |
Some usage is required. |
0x01040B |
HTTP 400 |
Specified usage not exists. |
0x01040C |
HTTP 400 |
Administrative state is required. |
0x01040D |
HTTP 400 |
Administrative state not exists. |
0x01040E |
HTTP 400 |
Signer certificate has not valid usage. |
0x01040F |
HTTP 400 |
Certificate file is forbidden. |
0x010410 |
HTTP 400 |
Certificate parent not allowed. |
0x010411 |
HTTP 400 |
If you put domains in request, they must have some value. |
0x010412 |
HTTP 400 |
Certificate to Provision is duplicated. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010500 |
HTTP 400 |
Manufacturer not exists. |
0x010501 |
HTTP 400 |
Manufacturer not allowed. |
0x010502 |
HTTP 400 |
Manufacturer not removable. |
0x010503 |
HTTP 400 |
Manufacturer duplicated. |
0x010504 |
HTTP 400 |
Unexpected manufacturer provision error. |
0x010505 |
HTTP 400 |
Manufacturer ID is required. |
0x010506 |
HTTP 400 |
Manufacturer ID is forbidden. |
0x010507 |
HTTP 400 |
Manufacturer ID too long. |
0x010508 |
HTTP 400 |
Address is too long. |
0x010509 |
HTTP 400 |
Fax is too long. |
0x01050A |
HTTP 400 |
Telephone is too long. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010600 |
HTTP 400 |
Model not removable. |
0x010601 |
HTTP 400 |
Model not exists. |
0x010602 |
HTTP 400 |
Model duplicated. |
0x010603 |
HTTP 400 |
Unexpected model provision error. |
0x010604 |
HTTP 400 |
Model ID is required. |
0x010605 |
HTTP 400 |
Model NAME is required. |
0x010606 |
HTTP 400 |
Model ID is forbidden. |
0x010607 |
HTTP 400 |
Model ID too long. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010700 |
HTTP 400 |
Media not removable. |
0x010701 |
HTTP 400 |
Media not exists. |
0x010702 |
HTTP 400 |
Media duplicated. |
0x010703 |
HTTP 400 |
Media provision error. |
0x010704 |
HTTP 400 |
File name required to provision. |
0x010705 |
HTTP 400 |
Media type not exists. |
0x010707 |
HTTP 400 |
Media ID too long. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010800 |
HTTP 400 |
Surname is too long. |
0x010801 |
HTTP 400 |
There cannot be surname. |
0x010802 |
HTTP 400 |
Email is required. |
0x010803 |
HTTP 400 |
Email bad format. |
0x010804 |
HTTP 400 |
Email already in use. |
0x010805 |
HTTP 400 |
Email is too long. |
0x010806 |
HTTP 400 |
There cannot be email. |
0x010807 |
HTTP 400 |
Password is required. |
0x010808 |
HTTP 400 |
Password is too long. |
0x010809 |
HTTP 400 |
There cannot be password. |
0x01080A |
HTTP 400 |
Profile is required. |
0x01080B |
HTTP 400 |
Profile not exists. |
0x01080C |
HTTP 400 |
Profile not allowed for this user. |
0x01080D |
HTTP 400 |
There cannot be profile. |
0x01080E |
HTTP 400 |
User not allowed for this user. |
0x01080F |
HTTP 400 |
User cannot be removed. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010900 |
HTTP 400 |
Invalid rule attributes |
0x010901 |
HTTP 400 |
No rule has been found with this id |
0x010902 |
HTTP 400 |
Rule can not be save because it is duplicated |
0x010903 |
HTTP 400 |
Rule can not be update |
0x010904 |
HTTP 400 |
No rule has been deleted because it does not exists |
0x010905 |
HTTP 400 |
Duplicated rule name for this channel |
0x010906 |
HTTP 400 |
Error searching rules with this filter |
0x010907 |
HTTP 400 |
Channel or organization can not be changed |
0x010908 |
HTTP 400 |
Rule identifier can not be changed |
0x010909 |
HTTP 400 |
Invalid rule prefilter |
0x01090A |
HTTP 400 |
Invalid attributes according to EASY/ADVANCED mode |
0x01090B |
HTTP 400 |
Easy rule type must have at least one action |
0x01090C |
HTTP 400 |
OID variables can not be duplicated |
0x01090D |
HTTP 400 |
Recipients are required in trap action |
0x01090E |
HTTP 400 |
Condition and filter is required in easy rule |
0x01090F |
HTTP 400 |
Invalid rule parameters |
0x010910 |
HTTP 400 |
Fields severity and priority are mandatory in open action |
0x010911 |
HTTP 400 |
Fields name, url and method are mandatory in send http action |
0x010912 |
HTTP 400 |
Field url must have a valid url format in send http action |
0x010913 |
HTTP 400 |
Field body is forbidden when method is not POST/PUT in send http action |
0x010914 |
HTTP 400 |
Field body is required when method is POST/PUT in send http action |
0x010915 |
HTTP 400 |
Error getting rules template |
Code | Returned HTTP Status | Description |
---|---|---|
0x010A00 |
HTTP 400 |
Bundle duplicated. |
0x010A01 |
HTTP 400 |
Bundle not exists. |
0x010A02 |
HTTP 400 |
Cannot delete bundle. |
0x010A03 |
HTTP 400 |
Cannot updated bundle. |
0x010A04 |
HTTP 400 |
Bundle model is required. |
0x010A05 |
HTTP 400 |
Bundle model doesn’t exist. |
0x010A06 |
HTTP 400 |
Cannot insert bundle with active parameter, relate deployment element first. |
0x010A07 |
HTTP 400 |
Cannot update bundle to active without related deployment element. |
0x010A08 |
HTTP 400 |
Bundle name is already related to another model, please use another bundle name. |
0x010A09 |
HTTP 400 |
Bundle zip is incorrect. |
0x010A0A |
HTTP 400 |
Duplicated file. |
0x010A0B |
HTTP 400 |
File not exists. |
0x010A0C |
HTTP 409 |
Cannot deleted file. |
0x010A0D |
HTTP 400 |
File not valid. |
0x010A0E |
HTTP 400 |
Cannot insert without deployment file nor downloadUrl. |
0x010A0F |
HTTP 400 |
File validator unknown. |
0x010A10 |
HTTP 400 |
File validator with PLATFORM mode required. |
0x010A11 |
HTTP 400 |
File type must be FIRMWARE if you want use TRUSTED_BOOT validation mode. |
0x010A12 |
HTTP 400 |
A bundle can have only one deployment element with TRUSTED_BOOT validation. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010B00 |
HTTP 400 |
There cannot be Target Remove. |
0x010B01 |
HTTP 400 |
There cannot be Target Action. |
0x010B02 |
HTTP 400 |
Invalid Target Action. |
0x010B03 |
HTTP 400 |
Duplicated Target Insert. |
0x010B04 |
HTTP 400 |
Duplicated Target Remove. |
0x010B05 |
HTTP 400 |
Filter not allowed. |
0x010B06 |
HTTP 400 |
You can’t use a target json object in the delete option. |
0x010B07 |
HTTP 400 |
You can’t use a filter json object in the delete option. |
0x010B08 |
HTTP 400 |
Invalid current owner. |
0x010B09 |
HTTP 400 |
Invalid owner. |
0x010B0A |
HTTP 400 |
Tag cannot be removed. |
0x010B0B |
HTTP 400 |
Tag not exists. |
0x010B0C |
HTTP 400 |
Target bad format. |
0x010B0D |
HTTP 400 |
Tag clone not allowed. |
0x010B0E |
HTTP 400 |
Max elements reached. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010C00 |
HTTP 400 |
Apn not exists. |
0x010C01 |
HTTP 400 |
Apn cannot be removed. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010D00 |
HTTP 400 |
Radius Client not exists. |
0x010D01 |
HTTP 400 |
Radius Client cannot be removed. |
0x010D02 |
HTTP 400 |
Source Address is required. |
0x010D03 |
HTTP 400 |
There cannot be Source Address. |
0x010D04 |
HTTP 400 |
Duplicated Source Address. |
0x010D05 |
HTTP 400 |
There cannot be Radius Secret. |
0x010D06 |
HTTP 400 |
Radius Secret is required. |
Code | Returned HTTP Status | Description |
---|---|---|
0x010E00 |
HTTP 400 |
There cannot be zoom. |
0x010E01 |
HTTP 400 |
There cannot be timezone. |
0x010E02 |
HTTP 400 |
There cannot be longitude. |
0x010E03 |
HTTP 400 |
There cannot be latitude. |
0x010E04 |
HTTP 400 |
Invalid timezone. |
0x010E05 |
HTTP 400 |
Plan not exists. |
0x010E06 |
HTTP 400 |
Plan not allowed. |
0x010E07 |
HTTP 400 |
Plan can not be assigned because its organization has fixed flow rate. |
0x010E08 |
HTTP 400 |
Plan can not be assigned because it is not in all domains assigned to the organization. |
0x010E09 |
HTTP 400 |
Default plan is not the same in all assigned domains to the organization. |
Operation Service: Jobs
Code | Returned HTTP Status | Description |
---|---|---|
0x020000 |
HTTP 400 |
Job name must be specified. |
0x020001 |
HTTP 400 |
Job name unknown. |
0x020002 |
HTTP 400 |
Job must have referenced entities. |
0x020003 |
HTTP 400 |
At least one valid reference to an entity (list of entities or tags) is required. |
0x020004 |
HTTP 400 |
Delay field cannot be specified with this options. |
0x020005 |
HTTP 400 |
Only one type of delay reference is allowed. |
0x020006 |
HTTP 400 |
Bundle not found. |
0x020007 |
HTTP 500 |
Job cannot be executed by overlap. |
0x020008 |
HTTP 400 |
Job cannot be scheduled. Please, repeat the last operation or contact with administrator. |
0x020009 |
HTTP 400 |
Schedule mode is not valid. Please, check your start and stop schedule modes. |
0x02000A |
HTTP 400 |
Job uuid unknown. Required action needs the job identifier. Please, check it. |
0x02000B |
HTTP 400 |
Job cannot be modified. It is already active. |
0x02000C |
HTTP 400 |
JSON target entities size was exceeded. |
0x02000D |
HTTP 400 |
Job state transition error. |
0x02000E |
HTTP 400 |
Filter is not valid. Please, check it. |
0x02000F |
HTTP 400 |
Label is not valid. Please, check it. |
0x020010 |
HTTP 400 |
JSON tag size was exceeded. Only one tag can be specified. |
0x020011 |
HTTP 400 |
Wrong job schedule configuration. Effective timeout is zero. |
0x020012 |
HTTP 400 |
Filter id unknown. Required action needs the filter identifier. Please, check it. |
0x020013 |
HTTP 400 |
Parameter entityType unknown. Required action needs the entityType parameter. Please, check it. |
0x020014 |
HTTP 400 |
Scattering param field value invalid. |
0x020015 |
HTTP 400 |
Scattering param maxSpread or factor value invalid. Value must be between 0 and 100. |
0x020016 |
HTTP 400 |
More than one empty scattering factors have been detected, which indicates data inconsistency, aborting scattering process. |
0x020017 |
HTTP 400 |
Scattering factor and scattering params are both empty. Aborting scattering process. |
0x020018 |
HTTP 400 |
Scattering warning max rate exceeded. |
0x020019 |
HTTP 400 |
The minimum gap between window daily times start and stop cannot be less than required. |
0x02001A |
HTTP 400 |
Wrong window stop time. Window start and stop minutes must match. |
0x02001B |
HTTP 400 |
Wrong window start time. Window start time is too close to Job’s timeout time. |
0x02001C |
HTTP 400 |
Job cannot be executed by overlap on windows. |
0x02001D |
HTTP 400 |
Wrong window time format. |
0x02001E |
HTTP 400 |
Wrong window format. |
0x02001F |
HTTP 400 |
Error executing job. |
Operation Service: Tasks
Code | Returned HTTP Status | Description |
---|---|---|
0x030000 |
HTTP 400 |
Task name must be specified. |
0x030001 |
HTTP 400 |
Task active field must be specified. |
0x030002 |
HTTP 400 |
Task job section must be specified. |
0x030003 |
HTTP 400 |
Task job section cannot be specified. |
0x030004 |
HTTP 400 |
Task schedule section must be specified. |
0x030005 |
HTTP 400 |
Task cannot be schedule because schedule section has wrong values. |
0x030006 |
HTTP 400 |
Task schedule mode must be specified. |
0x030007 |
HTTP 400 |
Only one schedule mode can be specified in a task definition. |
0x030008 |
HTTP 400 |
Time field must be defined in a task schedule section. |
0x030009 |
HTTP 400 |
Only one pattern mode can be specified in a task definition. |
0x03000A |
HTTP 400 |
Day field must be defined in a daily task schedule section. |
0x03000B |
HTTP 400 |
Month field must be defined in a monthly task schedule section. |
0x03000C |
HTTP 400 |
Each field must be defined in a periodic task schedule section. |
0x03000D |
HTTP 400 |
Units field must be defined in a period task schedule section. |
0x03000E |
HTTP 400 |
Only one stop mode section can be specified in a task definition. |
0x03000F |
HTTP 409 |
Task cannot be cancelled because it’s in use. |
0x030010 |
HTTP 409 |
Task cannot be modified because it’s in use. |
0x030011 |
HTTP 400 |
A Task must be deactivated before editing. Please set Task’s state to inactive before editing it. |
0x030012 |
HTTP 409 |
Task is running. |
0x030013 |
HTTP 409 |
Task is finished. |
0x030014 |
HTTP 400 |
Task identifier not found. |
0x030015 |
HTTP 400 |
Task identifier cannot be empty. |
0x030016 |
HTTP 400 |
Error while updating internal entities tag. |
0x030017 |
HTTP 400 |
Task identified cannot be specified. |
0x030018 |
HTTP 400 |
JSON target entities size was exceeded. |
0x030019 |
HTTP 400 |
Error while setting task target. |
0x03001A |
HTTP 400 |
Task id cannot be specified. |
0x03001B |
HTTP 400 |
Task identifier already exists. |
0x03001C |
HTTP 400 |
Task target type cannot be modified. |
0x03001D |
HTTP 400 |
Task data key contains not allowed characters (please check API documentation). |
0x03001E |
HTTP 400 |
Task state transition error. |
Operation Service: Operations
Code | Returned HTTP Status | Description |
---|---|---|
0x040000 |
HTTP 400 |
Param Ack Timeout cannot be higher than param Timeout. |
0x040001 |
HTTP 400 |
The minimum gap between params Ack Timeout and Timeout cannot be less than required. |
0x040002 |
HTTP 400 |
The models of a given entity and bundle do not match. |
0x040003 |
HTTP 400 |
The group of a given entity and bundle does not match or is not active. |
0x040004 |
HTTP 400 |
Neither parameter Ack timeout or timeout can be zero. |
0x040005 |
HTTP 400 |
Operation parameters are invalid. Please, check them. |
Operation Service: Alarms
Code | Returned HTTP Status | Description |
---|---|---|
0x060000 |
HTTP 400 |
Alarm action unknown. |
0x060001 |
HTTP 400 |
Alarms required. |
0x060002 |
HTTP 400 |
Error while setting alarm target (not exist any alarms). |
0x060003 |
HTTP 400 |
Alarm action is required. |
0x060004 |
HTTP 400 |
Alarm description too long. |
0x060005 |
HTTP 400 |
Alarms size too long. |
Search Service
Code | Returned HTTP Status | Description |
---|---|---|
0x050000 |
HTTP 400 |
Size value must be defined between 1 and 1000. |
0x050001 |
HTTP 400 |
Start value must be greater than 1. |
0x050002 |
HTTP 400 |
There is a parameter with incorrect value in the filter. |
0x050003 |
HTTP 400 |
The filter is malformed. |
0x050004 |
HTTP 400 |
There is a parameter too long. |
0x050005 |
HTTP 400 |
There is a numeric parameter too large. |
0x050006 |
HTTP 400 |
Start field must be a number. |
0x050007 |
HTTP 400 |
Size field must be a number. |
0x050008 |
HTTP 400 |
Sort name field must be specified. |
0x050009 |
HTTP 400 |
Sort type field must be specified. |
0x05000A |
HTTP 400 |
Sort field name unknown. |
0x05000B |
HTTP 400 |
Sort field type unknown. |
0x05000C |
HTTP 409 |
Wrong result. |
0x05000D |
HTTP 400 |
Empty field. |
0x05000E |
HTTP 400 |
Missing field. |
0x05000F |
HTTP 400 |
Minimum length not reached. |
0x050010 |
HTTP 400 |
Duplicated value. |
0x050011 |
HTTP 400 |
Incorrect type in field. |
0x050012 |
HTTP 400 |
Filter field has unsupported operator. |
0x050013 |
HTTP 400 |
Datastream not exists. |
0x050014 |
HTTP 400 |
Field in filter unknown. |
0x050015 |
HTTP 400 |
Group limit is not allowed in filter to CSV format. |
0x050016 |
HTTP 400 |
Query return too many results. |
0x050017 |
HTTP 400 |
Search in csv format without select is not allowed. |
0x050018 |
HTTP 400 |
Filter not exists. |
0x050019 |
HTTP 400 |
Invalid default value (true/false). |
0x05001A |
HTTP 400 |
Invalid owner value (workgroup/user). |
0x05001B |
HTTP 400 |
Filter id duplicated. |
0x05001C |
HTTP 400 |
Filter is required. |
0x05001D |
HTTP 400 |
Owner is required. |
0x05001E |
HTTP 400 |
Group sort is not allowed in filter to CSV format. |
0x05001F |
HTTP 400 |
Can not select a field and one or more of its sub-fields together. |
0x050020 |
HTTP 400 |
Datastream is not summarizable. |
0x050021 |
HTTP 400 |
Datastream is in several organizations and have differents attributes. |
Platform Event Process
Code | Returned HTTP Status | Description |
---|---|---|
0x070000 |
HTTP 400 |
Element not exists. |
0x070001 |
HTTP 400 |
Element not identified. |
0x070002 |
HTTP 400 |
Parameter unknown to procces event. |
0x070003 |
HTTP 400 |
Parameter invalid to procces event. |
Code | Returned HTTP Status | Description |
---|---|---|
0x070100 |
HTTP 400 |
Invalid data in leaf. |
0x070101 |
HTTP 400 |
Expired data in leaf. |
0x070102 |
HTTP 400 |
Element not found in list. |
0x070103 |
HTTP 400 |
Value format is invalid. |
0x070104 |
HTTP 400 |
Datastream not gatherable for this resource type. |
Provision
Common objects and attributes
All the entities have several attributes, objects and arrays in common. The attributes associated to these common objects are shown in the following sections.
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "organization": { "_current": { "value": "battery_organization" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } } } } }
Identifiers Attributes
There are different identifiers for entities:
Attribute | Description |
---|---|
id |
Each IoT entity have a unique identifier all over the platform. This identifier is auto generated by the platform (UUID format). |
provision.device.identifier |
It is a customer generated id consisting in a string that identifies a Device in a specific organization HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_1 You must use this identifier as URL suffix when you want to get, update or delete your device. |
provision.device.communicationModules[].identifier |
It is a customer generated id consisting in a string that identifies a Communication Module |
provision.device.communicationModules[].subscription.identifier |
It is a customer generated id consisting in a string that identifies a Subscription |
provision.device.communicationModules[].subscriber.identifier |
It is a customer generated id consisting in a string that identifies a Subscriber |
Administration object attributes
This object and all its attributes are required and must be created using the OpenGate Administration Console prior to use them in provision operations. |
All OpenGate entities must be included into an administration context. The administrative data contains specific data attributes, some of which are required and some of which are optional.
Attribute | Constraints | Description | ||
---|---|---|---|---|
[a-zA-Z0-9_] max 50 chars |
The organization that owns the entity.
|
|||
[a-zA-Z0-9_] max 50 chars |
An administrative grouping method for your entities. |
|||
administrativeState |
||||
[a-zA-Z0-9_-] max 50 chars |
Service configuration: configuration of services, operations available, etc. |
|||
[a-zA-Z0-9_] max 50 chars |
The workgroup is the way to establish the relationships between devices and users. It’s used, for example, when you want to create software bundles. |
|||
[a-zA-Z0-9_] max 50 chars |
An administrative concept that allow limit the number of events sent by the device, this concept only applies with devices |
{ "provision": { "administration": { "channel": { "_current": { "value": "YOUR_CHANNEL_NAME" } }, "organization": { "_current": { "value": "YOUR_ORGANIZATION_NAME" } }, "serviceGroup": { "_current": { "value": "SERVICE_GROUP_FOR_THE_ENTITY" } }, "plan": { "_current": { "value": "FLOW_RATE_100" } } } ... } }
Service Group concept
Please pay special attention to the entity service group, you must select the appropiate service group because there are several ways of behaviour determinated by a service group, the options are:
-
Operations that can be performed
-
How the platform send the scheduled operations over the devices
-
Always, this type is oriented to devices allways connected, in this case the operation will be sent to the device according to the schedule
-
Session connected, this type is oriented to devices that use web socket or mqtt conections. In this case the platform save the operations in its store and when the device open the conection with the platform automatically, the platform will detect this conection and will send the pending operations to the device.
-
On demand, this type is oriented to devices that only open their connections for some seconds in order to save battery, In this case the device will send a special post to the platform for request pending operation.
-
You can use in the case of mqtt connections the option "on Demand" if you want that all the operations will be requested by the device |
-
Trusted boot, all the message received by the platform has mandatory to have a field with the trusted boot value, if not the message will not collected
-
Device security mode, with this option you can select the level of security in the comunications between the device and platform. You can choose between:
-
None, all the comunications won’t be encrypted
-
Level 1, One-way authentication (or platform authentication): Only the platfotm authenticates itself to the client. The platform sends the client a certificate verifying that the platform is authentic.
-
Level 2, Two-way authentication (or bilateral authentication): Both client and server authenticate themselves to each other verifying that the certificate autenticator it’s available in the platform
-
Level 3, Two-way authentication with certificate checking: Both client and server authenticate themselves to each other verifying that the device certificate is available in the platform.
-
Name | Entity Type | Operation Group | Operation on Demand | Security Mode | Trusted Boot |
---|---|---|---|---|---|
emptyServiceGroup |
Asset, Gateway, Communications Module, Subscriber, Subscription |
emptyServiceGroup |
Send Always |
None |
disabled |
emptyServiceGroup onDemand |
Asset, Gateway |
emptyServiceGroup |
Send On Demand |
None |
disabled |
emptyServiceGroup onSession |
Asset, Gateway |
emptyServiceGroup |
Send On Session Connection |
None |
disabled |
level1SecurityServiceGroup |
Asset, Gateway |
emptyServiceGroup |
Send Always |
Level1 |
disabled |
level2SecurityServiceGroup |
Asset, Gateway |
emptyServiceGroup |
Send Always |
Level2 |
disabled |
level3SecurityServiceGroup |
Asset, Gateway |
emptyServiceGroup |
Send Always |
Level3 |
disabled |
noUpdate |
Asset, Gateway, Communications Module |
noUpdate |
Send Always |
None |
disabled |
trustedLevel1SecurityServiceGroup |
Asset, Gateway |
emptyServiceGroup |
Send Always |
Level1 |
enabled |
trustedLevel2SecurityServiceGroup |
Asset, Gateway |
emptyServiceGroup |
Send Always |
Level2 |
enabled |
trustedLevel3SecurityServiceGroup |
Asset, Gateway |
emptyServiceGroup |
Send Always |
Level3 |
enabled |
trustedNoneSecurityServiceGroup |
Asset, Gateway |
emptyServiceGroup |
Send Always |
None |
enabled |
trustedNoneSecurityServiceGroup_onDemand |
Asset, Gateway |
emptyServiceGroup |
Send On Demand |
None |
enabled |
Plan Concept
This concept is very interesting in OpenGate, this is the way to limit the number of events recived by the platform from a concrete organization or sent by an specific device. One organization must have assigned an specific plan where you can fix:
-
Maximum device. The maximun number of devices, gateways or assets, that an organization can have
-
Max storage. The maximun period of time for storing the historical data
-
Flow Rate. The maximum number of event recibed by the platform in a period of time
In the devices of an organization you can specify a diferent plan where you can change only the flow rate
Flattened concept
This concept allows send and receive a datamodel parameters list (see Default Datamodels) with the flattened format in the devices provision and in the responses of the search. In this way is the same that is received and sent by the south api. It is used a boolean parameter, flattened, in the URL to indicate if the file to send/receive is in flattened format.
The format is:
{ "parameter1_id": { "_value": { "_current": { "value": "value1" } } }, "parameter2_id": { "_value": { "_current": { "value": "value2" } } }, ... "parameterN_id": { "_value": { "_current": { "value": "valueN" } } } }
In the following examples, we can see how is transformed a normal json format to flattened json format. There are two types of values, simple and complex:
Simple values
The normal json format is:
{ "provision": { "administration": { "identifier": { "_current": { "value": "device_battery" } } } } }
The flattened json format is:
{ "provision.administration.identifier": { "_value": { "_current": { "value": "device_battery" } } } }
Complex value
We are going to see two different examples to clarify this concept
Example1 The normal json format is:
{ "provision": { "device": { "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } } } }
The flattened json format is:
{ "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } } }
Example2
The normal json format is:
{ "provision": { "device": { "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "name": { "_current": { "value": "commsMod_battery_name" } } } ] } } }
The flattened json format when it is a creative operation is:
{ "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_name" } } } ] }
The flattened json format when it is a reading operation is:
{ "provision.device.communicationModules[].identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.169Z" } } } ] }
Also, we are going to see how is transformed the previous normal/flattened json examples into to CSV format. We are going to join examples above in a unique csv file with three lines one for each examples above (one simple example and two complex examples)
It is easier to transform flattened format into csv format because the content of csv file follows the same guidelines to flattened format. The first line (header) contains the name of datastream separated by ";" and the next lines are the different entities and contains the field value of the datastream separated by ";" in the same order as the first line |
provision.administration.identifier;provision.device.location;provision.device.communicationModules[].identifier;provision.device.communicationModules[].name device_battery;;; ;"{"position":{"type":"Point","coordinates":[-3.7028,40.41675]},"postal":"28013"}";; ;;commsMod_battery_id;commsMod_battery_name
To clarify the csv, when the entity contains an unique communication module, it is possible indicates the name without [] and without the identifier [commsMod_battery_name(commsMod_battery_id)] or commsMod_battery_name,it is the same |
Access Point Names - APNs
APN entity object structure
APN entity store information regarding the access point name of the M2M networks used by the devices to connect to IoT applications
Object / attribute | Type | Description |
---|---|---|
name |
string |
Name of the Access Point Name |
syncCache |
object |
Specific parameters for synchronized cache mechanism. See Synchronized Cache Object below |
description |
string |
Description of the APN provisioned |
Object / attribute | Type | Description |
---|---|---|
effectiveDate |
string |
Datetime when the provision will take effect. If parameter is not passed or value is lower than current date the value will take effect immediately (Platform configured cache policies must be taken into account). Datetime when the coordinates were obtained. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Creating an APN
POST /north/v80/provision/apns
New APNs can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "apn" : { "name": "apn_1", "syncCache" : { "effectiveDate": "2014-05-28T15:20:51Z" }, "description": "description_1" } }
APN entries are cached internally in the every active server running the platform. Several behaviours are allowed that depends on the JSON request: If no syncCache object is present in the JSON attached file the platform will use a normal not synchronized cache strategy to distribute the information to the different active platform servers If syncCache object is present but no effectiveDate is present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers calculating the time when the change will take effect If syncCache object and effectiveDate are present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers setting the passed value as the datetime when the change will take effect |
Using curl to perform the request, you can create an APN sending a POST request using this URL template: http://[your_opengate_address]/north/v80/provision/apns
curl --request POST \ --data-binary @apn.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/apns \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created)
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/apns/apn_1
Reading an APN
GET /north/v80/provision/apns/{id}
You can apply for the APN sending a GET request using the URL above. You must replace {id}
with the name of the entity you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/apns/apn_1
The response body could be something like this:
{ "apn" : { "name": "apn_1", "syncCache" : { "effectiveDate": "2014-05-28T15:20:51Z" }, "description": "description_1" } }
Deleting an APN
DELETE /north/v80/provision/apns/{id}?syncCache&effectiveDate={effectiveDate}
You can delete the APNs of an entity sending a DELETE request using the URL above. You must replace {id}
with the identifier of the APN you want to delete. This is the request using curl.
APN entries are cached internally in the every active server running the platform. Several behaviours are allowed that depends on the JSON request: If no syncCache and no effectiveDate objects are present in the JSON attached file the platform will use a normal not synchronized cache strategy to distribute the information to the different active platform servers If syncCache object is present but no effectiveDate is present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers calculating the time when the change will take effect If syncCache object and effectiveDate are present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers setting the passed value as the datetime when the change will take effect |
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/apns/apn_1?syncCache&effectiveDate=2014-05-28T15:20:51Z
Areas
An area represents a geographic zone determined by a geojson or a devices group. This concept allows to know the devices inside a concrete area.
If you know the geojson, you can create the area with this information and you can or not add the devices group. By other hand, if you do not know the geojson, you can create the area only with the information of devices group without necesity of its location.
Area object structure
Object / attribute | Description |
---|---|
identifier |
Identifier of the area. This field can be included in the creation option and if it is not included it will automatically assign a uuid. |
name |
Name of the area. This field is optional. |
description |
Description of the area. This field is optional. |
geometry |
Geojson. It contains a type and coordenates of the area. The area supports the following geometry types: Point, Polygon and MultiPolygon |
entities |
Array of identifiers of entities that defining an area. |
The geometry type Point is used when you don’t have the GPS coordenates for a device, but you know the place where it is. This place has a coordenate and it would be the value of this geometry type (point) |
Creating an area
POST /north/v80/provision/organizations/{organizationName}/areas
New areas can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
Let’s show firt two types of json in function how is determined the geographic zone by a geojson or a devices group. Next, the possibility to have information both of them (geojson and devices group).
{ "identifier": "Id", "name": "area name", "description": "description", "geometry": {}, "entities": [ "identifier1" ] }
{ "identifier": "id", "name": "area name", "description": "description", "geometry": { "type": "Polygon", "coordinates": [ [ [ 2.173200845718384, 41.36735636905808 ], [ 2.179992198944092, 41.364771670743316 ], [ 2.1802926063537598, 41.36514206995068 ], [ 2.1783506870269775, 41.36581039362086 ], [ 2.175893783569336, 41.36669611320903 ], [ 2.1749818325042725, 41.36675247677479 ], [ 2.174273729324341, 41.36718727978374 ], [ 2.173200845718384, 41.36735636905808 ] ] ] } }
The polygon must have the first point and the last one equal. That’s how it’s closed |
{ "identifier": "Id", "name": "area name", "description": "description", "geometry": { "type": "Polygon", "coordinates": [ [ [ 2.173200845718384, 41.36735636905808 ], [ 2.179992198944092, 41.364771670743316 ], [ 2.1802926063537598, 41.36514206995068 ], [ 2.1783506870269775, 41.36581039362086 ], [ 2.175893783569336, 41.36669611320903 ], [ 2.1749818325042725, 41.36675247677479 ], [ 2.174273729324341, 41.36718727978374 ], [ 2.173200845718384, 41.36735636905808 ] ] ] }, "entities": [ "identifier1" ] }
This is the request using curl:
curl --request POST \ --data-binary @area.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created area. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/area_1
Reading an area
GET /north/v80/provision/organizations/{organizationName}/areas/{identifier}
You can apply for the area sending a GET request using the URL above. You must replace {identifier}
with the identifier of the area you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/{identifier}
The response body could be something like this:
{ "organization": "organization_area", "identifier": "Id", "name": "area name", "description": "description", "geometry": {}, "entities": [ "identifier1" ] }
Updating an area
PUT /north/v80/provision/organizations/{organizationName}/areas/{identifier}
It is allowed updating all the fields except the identifier |
This is the request using curl:
curl --request PUT \ --data-binary @area.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/{identifier} \ -H "Content-type: application/json"
Deleting an area
DELETE /north/v80/provision/organizations/{organizationName}/areas/{identifier}
You can delete areas by sending a DELETE request using the URL above. You must replace {identifier}
with the identifier of the area you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/{identifier}
Assets
It allows you to create entities that are not devices allowing emulate any type of entity you want to create like worker, spool, …
At the same time, a device can be related to Asset. For example, a worker may have a device that measures a series of parameters. These devices can be a bracelet that measures battery, pulsations, temperature, position or a vest measuring another series of parameters.
An asset knows its associated devices through the provision.asset.related datastream. It contains an array with the identifiers of the associated devices.
If you also want to receive all the information of the device in the asset, you must add a datamodel with dual datastreams. From the moment they are both related of this way, the assets will be able to receive all common datastreams from the device. In this way, all datastreams/datapoints collected will be in the cycle of life both of them.
By default, the platform offers the Entity datamodel that contains two dual datastreams: entity.location and entity.areas, see Default Datamodels.
Asset object structure
An asset stores information about the new entity created by the user.
Regarding to provisioned data there are the following attributes:
-
Minium attributes:
-
provision.administration.*
-
provision.asset.identifier
-
resourceType
-
-
Recommended attributes by OpenGate:
-
provision.asset.administrativeState
-
provision.asset.specificType
-
provision.asset.name
-
provision.asset.description
-
-
Extended attributes:
-
provision.asset.location
-
Defined attributes in human datamodel
-
Defined by the user in his new datamodels. For example photo, position
-
The specificType field is used to differentiate the new entities. For example, a worker has as resourceType entity.asset and as specificType WORKER |
All attributes are organized as follows:
Parameter | Description |
---|---|
resourceType |
It indicates to which type of entity is allowed a datamodel. The value must be entity.asset |
provision |
Object / attribute | Description |
---|---|
administration |
|
asset |
The resourceType field defines that the resource is an asset |
Customer provision fields can be defined by the user creating new datamodels that define parameters with using "provision.custom." prefix in the parameter Id |
Creating an asset
POST /north/v80/provision/organizations/{organizationName}/entities
New assets can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
It is not necessary to add a organization field in the json because this field is in the URL |
It is not possible to create the list of devices associated to asset. They must be added from devices |
Here’s how to create an asset with the minium fields
{ "resourceType": { "_current": { "value": "entity.asset" } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "organization": { "_current": { "value": "battery_organization" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "asset": { "identifier": { "_current": { "value": "worker_battery_id" } } } } }
By default the new entity will be associated to the organization indicated by the URL as long as the organization to which the used API_KEY belongs to or to an organization associated to a subdomain. |
Here’s how to create an asset with the recommended fields, including values of human datamodel (see Default Datamodels)
{ "resourceType": { "_current": { "value": "entity.asset" } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "organization": { "_current": { "value": "battery_organization" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "asset": { "identifier": { "_current": { "value": "worker_battery_id" } }, "specificType": { "_current": { "value": "WORKER" } }, "administrativeState": { "_current": { "value": "READY" } }, "name": { "_current": { "value": "Antonio Pérez" } }, "description": { "_current": { "value": "battery worker" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } } } }
Here’s how to create an asset with the extended fields, other possible attributes (provision.asset.location, defined attributes in human datamodel (see Default Datamodels) and defined by the user in his new datamodels (see create datamodels)
{ "resourceType": { "_current": { "value": "entity.asset" } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "organization": { "_current": { "value": "battery_organization" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "asset": { "identifier": { "_current": { "value": "worker_battery_id" } }, "specificType": { "_current": { "value": "WORKER" } }, "administrativeState": { "_current": { "value": "READY" } }, "name": { "_current": { "value": "Antonio Pérez" } }, "description": { "_current": { "value": "battery worker" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "human": { "identifier": { "_current": { "value": "01258542J" } }, "name": { "_current": { "value": "Antonio" } }, "surname": { "_current": { "value": "Pérez" } }, "surname2": { "_current": { "value": "Salgado" } } } } }
This is the request using curl:
curl --request POST \ --data-binary @asset.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created asset. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id
POST /north/v80/provision/organizations/{organizationName}/entities?flattened=true
It is possible to create an asset with a flattened format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to send a flattened json format
{ "resourceType": { "_value": { "_current": { "value": "entity.asset" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.asset.identifier": { "_value": { "_current": { "value": "worker_battery_id" } } } }
Using curl to perform the request:
curl --request POST \ --data-binary @FlattenedAsset.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities?flattened=true \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created asset. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id
Reading an asset
GET /north/v80/provision/organizations/{organizationName}/entities/{identifier}
You can apply for an asset sending a GET request using the URL above. You must replace {identifier}
with the identifier of the asset you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id
The response body could be something like this:
{ "resourceType": { "_value": { "_current": { "value": "entity.asset" } } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "organization": { "_current": { "value": "battery_organization", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "asset": { "identifier": { "_current": { "value": "worker_battery_id", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "specificType": { "_current": { "value": "WORKER", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "administrativeState": { "_current": { "value": "READY", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "name": { "_current": { "value": "Antonio Pérez", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "description": { "_current": { "value": "battery worker", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "human": { "identifier": { "_current": { "value": "01258542J", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "name": { "_current": { "value": "Antonio", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "surname": { "_current": { "value": "Pérez", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } }, "surname2": { "_current": { "value": "Salgado", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } } } }
As said before, the devices can be related to asset. In this case, the response includes the related devices
{ "resourceType": { "_current": { "value": "entity.asset", "provType": "IDENTIFIER", "date": "2018-09-11T08:23:23.430Z" } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2018-09-11T08:23:23.409Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2018-09-11T08:23:23.403Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2018-09-11T08:23:23.397Z" } }, "identifier": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2018-09-11T08:23:23.420Z" } } }, "asset": { "identifier": { "_current": { "value": "worker_battery_id", "provType": "IDENTIFIER", "date": "2018-09-11T08:23:23.430Z" } }, "related": { "_current": { "value": [ "device_battery_id" ], "provType": "MONITORING", "date": "2018-09-11T08:23:49.027Z" } } } } }
GET /north/v80/provision/organizations/{organizationName}/entities/{identifier}?flattened=true
You can apply for an asset with flattened format (see flattened concept) sending a GET request using the URL above. You must replace {identifier}
with the identifier of the asset you want to retrieve. Also, it is sent a boolean parameter, flattened, to allow to receive a flattened json format.
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id?flattened=true
And this is the response body:
{ "resourceType": { "_value": { "_current": { "value": "entity.asset" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "IDENTIFIER", "date": "2017-09-25T09:34:32.208Z" } } }, "provision.asset.identifier": { "_value": { "_current": { "value": "worker_battery_id", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.asset.specificType": { "_value": { "_current": { "value": "WORKER", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.asset.administrativeState": { "_value": { "_current": { "value": "READY", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.asset.name": { "_value": { "_current": { "value": "Antonio Pérez", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.asset.description": { "_value": { "_current": { "value": "battery worker", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.human.identifier": { "_value": { "_current": { "value": "01258542J", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.human.name": { "_value": { "_current": { "value": "Antonio", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.human.surname": { "_value": { "_current": { "value": "Pérez", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } }, "provision.human.surname2": { "_value": { "_current": { "value": "Salgado", "_provType": "IDENTIFIER", "_date": "2017-02-02T09:05:58Z" } } } }
Updating an asset
PUT /north/v80/provision/organizations/{organizationName}/entities/{identifier}
You can update an asset sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the asset you want to update.
It is not possible to update the list of devices associated to asset. They must be updated from devices |
The JSON object passed could be something like this:
{ "resourceType": { "_current": { "value": "entity.asset" } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "organization": { "_current": { "value": "battery_organization" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "asset": { "identifier": { "_current": { "value": "worker_battery_id" } } } } }
This is the request using curl:
curl --request PUT \ --data-binary @asset.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id \ -H "Content-type: application/json"
PUT /north/v80/provision/organizations/{organizationName}/entities/{identifier}?flattened=true
You can update an asset with a flattened format (see flattened concept) sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the asset you want to update. Also, it is sent a boolean parameter, flattened, to allow to send a flattened json format
The JSON object passed could be something like this:
{ "resourceType": { "_value": { "_current": { "value": "entity.asset" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.asset.identifier": { "_value": { "_current": { "value": "worker_battery_id" } } } }
Using curl to perform the request:
curl --request PUT \ --data-binary @asset.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id?flattened=true \ -H "Content-type: application/json"
Patching an asset
PATCH /north/v80/provision/organizations/{organizationName}/entities/{identifier}
You can patch an asset sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the asset you want to patch.
It is not possible to patch the list of devices associated to asset. They must be patched from devices |
ResourceType and Administration Channel values are mandatory in asset patch operation for securization purposes. |
When patching complex object values, non passed object attributes will be patched as non existent, so include previous unchanged values if you don’t want to loose them. |
The JSON object passed could be something like this:
{ "resourceType": { "_current": { "value": "entity.asset" } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } } }, "asset": { "description": { "_current": { "value": "patched_description" } } } } }
This is the request using curl:
curl --request PATCH \ --data-binary @asset.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id \ -H "Content-type: application/json"
PATCH /north/v80/provision/organizations/{organizationName}/entities/{identifier}?flattened=true
You can patch an asset with a flattened format (see flattened concept) sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the asset you want to patch. Also, it is sent a boolean parameter, flattened, to allow to send a flattened json format
The JSON object passed could be something like this:
{ "resourceType": { "_value": { "_current": { "value": "entity.asset" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.asset.identifier": { "_value": { "_current": { "value": "worker_battery_id" } } } }
Using curl to perform the request:
curl --request PATCH \ --data-binary @asset.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id?flattened=true \ -H "Content-type: application/json"
Deleting an asset
DELETE /north/v80/provision/organizations/{organizationName}/entities/{identifier}
You can delete an asset sending a DELETE request using the URL above. You must replace {identifier}
with the identifier of the asset you want to delete. This is the request using curl.
It is not possible to delete the list of devices associated to asset. They must be deleted from devices |
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id
Bulk
The bulk function allows provisioning a list of entities in one shot in sync mode
See below sections to know how this is done
Bulk Object structure
They are supported two different formats for the file to be used in the bulk request and response. It could be selected through the HTTP header (See HTTP Header Options):
-
JSON Format (Default)
-
CSV Format
HTTP header options
Using HTTP header option "Content-Type", the API allows indicating if the request content is going to go in Json or csv format Using HTTP header option "Accept", the API allows indicating if the response content is going to go in Json or csv format
Format | Operation type | Header parameter | Header value |
---|---|---|---|
JSON |
Request |
Content-Type |
The value is "application/json". By default if the header field is not present the value is "application/json" |
CSV |
Request |
Content-Type |
The value is "text/plain" |
JSON |
Response |
Accept |
The value is "application/json". By default if the header field is not present the value is "application/json" |
CSV |
Response |
Accept |
The value is "text/plain" |
It is possible to send a request and receive a response in different formats. For example, send in json format and receive in csv format |
JSON Format
The JSON request object is an array of the entities to be provisioned, updated or deleted
Object / attribute | Description |
---|---|
entities[] |
You can include objects from the different provision entities. See: |
The JSON response object is an array of entities response objects:
Object / attribute | Description |
---|---|
Array of Entity Provision Response Object |
Entity | Constraint |
---|---|
statusCode |
HTTP unitary request error code |
location |
HTTP unitary request Location object |
errors |
Array of error. See Error Messages Section |
CSV Format
The CSV request object is a file with entity fields separated by semicolon with all entities to be provisioned, updated or deleted
Object / attribute | Description |
---|---|
HEADER |
It is the first line of the file. These are the entity fields names separated by ";":
|
VALUES |
They are the fields values separated by ";" in the same order as the header |
The content of csv format file follows the same guidelines to flattened format. The header contains the name of datastream and value contains the field value of the datastream. See Flattened Format Section |
Let’s see the following example of the csv format
provision.administration.organization;provision.administration.channel;provision.administration.serviceGroup;provision.device.identifier;provision.device.name;provision.device.description;provision.device.administrativeState;provision.device.operationalStatus;provision.device.model;provision.device.specificType;provision.device.serialNumber;provision.device.location;provision.device.communicationModules[].identifier;provision.device.communicationModules[].name;provision.device.communicationModules[].description;provision.device.communicationModules[].model;provision.device.communicationModules[].specificType;provision.device.communicationModules[].mobile.imei;provision.device.communicationModules[].subscription.identifier;provision.device.communicationModules[].subscription.name;provision.device.communicationModules[].subscription.description;provision.device.communicationModules[].subscription.administrativeState;provision.device.communicationModules[].subscription.specificType;provision.device.communicationModules[].subscription.address;provision.device.communicationModules[].subscription.mobile.imsi;provision.device.communicationModules[].subscription.mobile.msisdn;provision.device.communicationModules[].subscription.mobile.homeOperator;provision.device.communicationModules[].subscription.mobile.registeredOperator;provision.device.communicationModules[].subscriber.identifier;provision.device.communicationModules[].subscriber.name;provision.device.communicationModules[].subscriber.description;provision.device.communicationModules[].subscriber.administrativeState;provision.device.communicationModules[].subscriber.specificType;provision.device.communicationModules[].subscriber.mobile.icc base_organization;base_channel;emptyServiceGroup;device_1_id;device_1_name;device_1_description;ACTIVE;NORMAL;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";CONCENTRATOR;32333-33334-122-1;;;;;;;;;;;;;;;;;;;;;;; organization_battery;channel_battery;emptyServiceGroup;device_battery_id;device_battery_name;device_battery_description;ACTIVE;NORMAL;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";MODEM;device_battery_sn;"{"position":{"type":"Point","coordinates":[-3.7028,40.41675]},"postal":"28013"}";commsMod_battery_id;commsMod_battery_name;commsMod_battery_description;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";UMTS;commsMod_battery_imei;subscription_battery_id;subscription_battery_name;subscription_battery_description;ACTIVE;MOBILE;"{"type":"IPV4","value":"99.1.1.71","apn":"movistar.es"}";subscription_battery_imsi;34969220026;Telefónica Móviles España, SAU;Telefónica Móviles España, SAU;subscriber_battery_id;subscriber_battery_name;subscriber_battery_description;ACTIVE;SIM;subscriber_battery_icc
The CSV response object is a file with entities response objects:
Object / attribute | Description |
---|---|
HEADER |
It is the first line of the file. These are the entity fields names separated by ";":
|
VALUES |
They are the fields values separated by ";" in the same order as the header |
Let’s see the following example of the csv format
statusCode;location;error.code;error.message;error.context 201;http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id;;; 400;http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id;4101;Entity duplicated;
File size and uploading strategies
If the size of the file to be uploaded during CREATE, UPDATE, DELETE operations is very big, the server will return an error.
By operational issues, the limit by default is set to 2 Megabytes to send json or csv files. Please consult with your administrator to change the limit configured. |
Creating a list of Entities
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=CREATE
A list of sets with related entities can be created by sending a POST request to the above defined. In function of the HTTP header options is supported two different formats: json and csv.
JSON FORMAT
{ "entities": [ { "provision": { "administration": { "organization": { "_current": { "value": "base_organization" } }, "channel": { "_current": { "value": "base_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_1_id" } }, "name": { "_current": { "value": "device_1_name" } }, "description": { "_current": { "value": "device_1_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "manufacturer": "OpenGate", "name": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "CONCENTRATOR" } }, "serialNumber": { "_current": { "value": "32333-33334-122-1" } } } } }, { "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "name": { "_current": { "value": "device_battery_name" } }, "description": { "_current": { "value": "device_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "MODEM" } }, "serialNumber": { "_current": { "value": "device_battery_sn" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "name": { "_current": { "value": "commsMod_battery_name" } }, "description": { "_current": { "value": "commsMod_battery_description" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "UMTS" } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei" } } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "name": { "_current": { "value": "subscription_battery_name" } }, "description": { "_current": { "value": "subscription_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "MOBILE" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi" } }, "msisdn": { "_current": { "value": "34969220026" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "name": { "_current": { "value": "subscriber_battery_name" } }, "description": { "_current": { "value": "subscriber_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "SIM" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc" } } } } } ] } } } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @BulkCreate.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=CREATE \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a JSON object with the response. Let’s look the response.
HTTP/1.1 201 ok
[ { "statusCode": 201, "location": "http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id" }, { "statusCode": 400, "location": "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/devices/device_battery_id", "errors": { "code": 4101, "message": "Entity duplicated", "context": [] } } ]
CSV FORMAT
provision.administration.organization;provision.administration.channel;provision.administration.serviceGroup;provision.device.identifier;provision.device.name;provision.device.description;provision.device.administrativeState;provision.device.operationalStatus;provision.device.model;provision.device.specificType;provision.device.serialNumber;provision.device.location;provision.device.communicationModules[].identifier;provision.device.communicationModules[].name;provision.device.communicationModules[].description;provision.device.communicationModules[].model;provision.device.communicationModules[].specificType;provision.device.communicationModules[].mobile.imei;provision.device.communicationModules[].subscription.identifier;provision.device.communicationModules[].subscription.name;provision.device.communicationModules[].subscription.description;provision.device.communicationModules[].subscription.administrativeState;provision.device.communicationModules[].subscription.specificType;provision.device.communicationModules[].subscription.address;provision.device.communicationModules[].subscription.mobile.imsi;provision.device.communicationModules[].subscription.mobile.msisdn;provision.device.communicationModules[].subscription.mobile.homeOperator;provision.device.communicationModules[].subscription.mobile.registeredOperator;provision.device.communicationModules[].subscriber.identifier;provision.device.communicationModules[].subscriber.name;provision.device.communicationModules[].subscriber.description;provision.device.communicationModules[].subscriber.administrativeState;provision.device.communicationModules[].subscriber.specificType;provision.device.communicationModules[].subscriber.mobile.icc base_organization;base_channel;emptyServiceGroup;device_1_id;device_1_name;device_1_description;ACTIVE;NORMAL;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";CONCENTRATOR;32333-33334-122-1;;;;;;;;;;;;;;;;;;;;;;; organization_battery;channel_battery;emptyServiceGroup;device_battery_id;device_battery_name;device_battery_description;ACTIVE;NORMAL;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";MODEM;device_battery_sn;"{"position":{"type":"Point","coordinates":[-3.7028,40.41675]},"postal":"28013"}";commsMod_battery_id;commsMod_battery_name;commsMod_battery_description;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";UMTS;commsMod_battery_imei;subscription_battery_id;subscription_battery_name;subscription_battery_description;ACTIVE;MOBILE;"{"type":"IPV4","value":"99.1.1.71","apn":"movistar.es"}";subscription_battery_imsi;34969220026;Telefónica Móviles España, SAU;Telefónica Móviles España, SAU;subscriber_battery_id;subscriber_battery_name;subscriber_battery_description;ACTIVE;SIM;subscriber_battery_icc
Using curl to perform the request:
curl --request POST \ --data-binary @file.csv \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=CREATE \ -H "Content-type: text/plain" -H "accept: text/plain"
In the response we should see a status code of 201 (created) and a CSV file with the response. Let’s look the response.
HTTP/1.1 201 ok
statusCode;location;error.code;error.message;error.context 201;http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id;;; 400;http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id;4101;Entity duplicated;
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=CREATE&flattened=true
It is possible to manage a flattened format of the entities (a list of datamodel parameters). In this case, it is sent a boolean parameter to allow to send a flattened json format. See Flattened Format Section
{ "entities": [ { "provision.administration.organization": { "_value": { "_current": { "value": "base_organization" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "base_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_1_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_1_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_1_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "CONCENTRATOR" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "32333-33334-122-1" } } } }, { "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_name" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_description" } } } ], "provision.device.communicationModules[].model": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } } ], "provision.device.communicationModules[].specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "UMTS" } } } ], "provision.device.communicationModules[].mobile.imei": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_imei" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_name" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_description" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "MOBILE" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_imsi" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "34969220026" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_id" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_name" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_description" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "SIM" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_icc" } } } ] } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @BulkFlattenedCreate.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=CREATE&flattened=true \ -H "Content-type: application/json"
Let’s look the response
HTTP/1.1 201 Created
[ { "statusCode": 201, "location": "http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id" }, { "statusCode": 400, "location": "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/devices/device_battery_id", "errors": { "code": 4101, "message": "Entity duplicated", "context": [] } } ]
Updating a list of Entities
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=UPDATE
A list of sets with related entities can be updated by sending a POST request to the above defined. In function of the HTTP header options is supported two different formats: json and csv.
JSON FORMAT
{ "entities": [ { "provision": { "administration": { "organization": { "_current": { "value": "base_organization" } }, "channel": { "_current": { "value": "base_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_1_id" } }, "name": { "_current": { "value": "device_1_name" } }, "description": { "_current": { "value": "device_1_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "manufacturer": "OpenGate", "name": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "CONCENTRATOR" } }, "serialNumber": { "_current": { "value": "32333-33334-122-1" } } } } }, { "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "name": { "_current": { "value": "device_battery_name" } }, "description": { "_current": { "value": "device_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "MODEM" } }, "serialNumber": { "_current": { "value": "device_battery_sn" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "name": { "_current": { "value": "commsMod_battery_name" } }, "description": { "_current": { "value": "commsMod_battery_description" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "UMTS" } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei" } } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "name": { "_current": { "value": "subscription_battery_name" } }, "description": { "_current": { "value": "subscription_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "MOBILE" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi" } }, "msisdn": { "_current": { "value": "34969220026" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "name": { "_current": { "value": "subscriber_battery_name" } }, "description": { "_current": { "value": "subscriber_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "SIM" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc" } } } } } ] } } } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @BulkCreate.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=UPDATE \ -H "Content-type: application/json"
CSV FORMAT .Bulk Request as CSV document
provision.administration.organization;provision.administration.channel;provision.administration.serviceGroup;provision.device.identifier;provision.device.name;provision.device.description;provision.device.administrativeState;provision.device.operationalStatus;provision.device.model;provision.device.specificType;provision.device.serialNumber;provision.device.location;provision.device.communicationModules[].identifier;provision.device.communicationModules[].name;provision.device.communicationModules[].description;provision.device.communicationModules[].model;provision.device.communicationModules[].specificType;provision.device.communicationModules[].mobile.imei;provision.device.communicationModules[].subscription.identifier;provision.device.communicationModules[].subscription.name;provision.device.communicationModules[].subscription.description;provision.device.communicationModules[].subscription.administrativeState;provision.device.communicationModules[].subscription.specificType;provision.device.communicationModules[].subscription.address;provision.device.communicationModules[].subscription.mobile.imsi;provision.device.communicationModules[].subscription.mobile.msisdn;provision.device.communicationModules[].subscription.mobile.homeOperator;provision.device.communicationModules[].subscription.mobile.registeredOperator;provision.device.communicationModules[].subscriber.identifier;provision.device.communicationModules[].subscriber.name;provision.device.communicationModules[].subscriber.description;provision.device.communicationModules[].subscriber.administrativeState;provision.device.communicationModules[].subscriber.specificType;provision.device.communicationModules[].subscriber.mobile.icc base_organization;base_channel;emptyServiceGroup;device_1_id;device_1_name;device_1_description;ACTIVE;NORMAL;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";CONCENTRATOR;32333-33334-122-1;;;;;;;;;;;;;;;;;;;;;;; organization_battery;channel_battery;emptyServiceGroup;device_battery_id;device_battery_name;device_battery_description;ACTIVE;NORMAL;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";MODEM;device_battery_sn;"{"position":{"type":"Point","coordinates":[-3.7028,40.41675]},"postal":"28013"}";commsMod_battery_id;commsMod_battery_name;commsMod_battery_description;"{"name":"OpenGate","manufacturer":"OpenGate","version":"1.0"}";UMTS;commsMod_battery_imei;subscription_battery_id;subscription_battery_name;subscription_battery_description;ACTIVE;MOBILE;"{"type":"IPV4","value":"99.1.1.71","apn":"movistar.es"}";subscription_battery_imsi;34969220026;Telefónica Móviles España, SAU;Telefónica Móviles España, SAU;subscriber_battery_id;subscriber_battery_name;subscriber_battery_description;ACTIVE;SIM;subscriber_battery_icc
Using curl to perform the request:
curl --request POST \ --data-binary @file.csv \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=UPDATE \ -H "Content-type: text/plain"
Let’s look the response
HTTP/1.1 200 ok
[ { "statusCode": 201, "location": "http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id" }, { "statusCode": 400, "location": "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/devices/device_battery_id", "errors": { "code": 4101, "message": "Entity duplicated", "context": [] } } ]
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=UPDATE&flattened=true
It is possible to manage a flattened format of the entities (a list of datamodel parameters). In this case, it is sent a boolean parameter to allow to send a flattened json format. See Flattened Format Section
{ "entities": [ { "provision.administration.organization": { "_value": { "_current": { "value": "base_organization" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "base_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_1_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_1_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_1_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "CONCENTRATOR" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "32333-33334-122-1" } } } }, { "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_name" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_description" } } } ], "provision.device.communicationModules[].model": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } } ], "provision.device.communicationModules[].specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "UMTS" } } } ], "provision.device.communicationModules[].mobile.imei": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_imei" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_name" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_description" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "MOBILE" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_imsi" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "34969220026" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_id" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_name" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_description" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "SIM" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_icc" } } } ] } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @BulkFlattenedCreate.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=UPDATE&flattened=true \ -H "Content-type: application/json"
Let’s look the response
HTTP/1.1 200 ok
[ { "statusCode": 201, "location": "http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id" }, { "statusCode": 400, "location": "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/devices/device_battery_id", "errors": { "code": 4101, "message": "Entity duplicated", "context": [] } } ]
Patching a list of Entities
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=PATCH
A list of sets with related entities can be patched by sending a POST request to the above defined. In function of the HTTP header options is supported two different formats: json and csv.
JSON FORMAT
{ "entities": [ { "provision": { "administration": { "channel": { "_current": { "value": "base_channel" } } }, "device": { "identifier": { "_current": { "value": "device_1_id" } }, "description": { "_current": { "value": "device_1_description bulk patched" } } } } }, { "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "description": { "_current": { "value": "device_battery_description bulk patched" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "description": { "_current": { "value": "commsMod_battery_description bulk patched" } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "description": { "_current": { "value": "subscription_battery_description bulk patched" } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "description": { "_current": { "value": "subscriber_battery_description bulk patched" } } } } ] } } } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @BulkCreate.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=PATCH \ -H "Content-type: application/json"
CSV FORMAT .Bulk Request as CSV document
provision.administration.channel;provision.device.identifier;provision.device.description;provision.device.communicationModules[].identifier;provision.device.communicationModules[].description;provision.device.communicationModules[].subscription.identifier;provision.device.communicationModules[].subscription.description;provision.device.communicationModules[].subscriber.identifier;provision.device.communicationModules[].subscriber.description base_channel;device_1_id;device_1_description patched csv;;;;;; channel_battery;device_battery_id;device_battery_description patched csv;commsMod_battery_id;commsMod_battery_description patched csv;subscription_battery_id;subscription_battery_description patched csv;subscriber_battery_id;subscriber_battery_description
Using curl to perform the request:
curl --request POST \ --data-binary @file.csv \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=PATCH \ -H "Content-type: text/plain"
Let’s look the response
HTTP/1.1 200 ok
[ { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id" }, "device" : { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/devices/device_battery_id" }, { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/subscriptions/subscription_battery_id" }, { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/subscribers/subscriber_battery_id" } ]
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=PATCH&flattened=true
It is possible to manage a flattened format of the entities (a list of datamodel parameters). In this case, it is sent a boolean parameter to allow sending a flattened json format. See Flattened Format Section
{ "entities": [ { "provision.administration.channel": { "_value": { "_current": { "value": "base_channel" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_1_id" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_1_description patched" } } } }, { "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description patched" } } }, "provision.device.communicationModules[].identifier": [ { "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].description": [ { "_value": { "_current": { "value": "commsMod_battery_description patched" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_value": { "_current": { "value": "subscription_battery_description patched" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_value": { "_current": { "value": "subscriber_battery" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_value": { "_current": { "value": "subscriber_battery_description patched" } } } ] } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @BulkFlattenedCreate.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=PATCH&flattened=true \ -H "Content-type: application/json"
Let’s look the response
HTTP/1.1 200 ok
[ { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/base_organization/devices/device_1_id" }, "device" : { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/devices/device_battery_id" }, { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/subscriptions/subscription_battery_id" }, { "statusCode" : 201, "location" : "http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/subscribers/subscriber_battery_id" } ]
Deleting a list of Entities
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE
A list of sets with related entities can be deleted by sending a POST request to the above defined, including a correctly formatted JSON or csv document in the body.
{ "entities": [ { "provision": { "administration": { "identifier": { "_current": { "value": "device_id" } }, "organization": { "_current": { "value": "base_organization" } } }, "device": { "identifier": { "_current": { "value": "device_ 1_id" } } } } }, { "provision": { "administration": { "identifier": { "_current": { "value": "device_battery" } }, "organization": { "_current": { "value": "base_organization" } } }, "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "value": "subscription_1" } } } } ] } } } ] }
This is the request using curl in json format:
curl --request POST \ --data-binary @file.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE \ -H "Content-type: application/json"
Let’s see the following example of the csv format
provision.administration.organization;provision.device.identifier;provision.device.communicationModules[].identifier;provision.device.communicationModules[].subscription.identifier base_organization;device_1;; base_organization;;commsMod_1;subscription_1
This is the request using curl in csv format:
curl --request POST \ --data-binary @file.csv \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE \ -H "Content-type: text/plain"
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE&flattened=true
It is possible to delete a flattened format of the entities (a list of datamodel parameters). In this case, it is sent a boolean parameter to allow to send a flattened json format
{ "entities": [ { "provision.administration.organization": { "_value": { "_current": { "value": "base_organization" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_1" } } } }, { "provision.administration.organization": { "_value": { "_current": { "value": "base_organization" } } }, "provision.device.communicationModules[].identifier": [ { "_value": { "_current": { "value": "commsMod_1" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_value": { "_current": { "value": "subscription_1" } } } ] } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @BulkFlattenedCreate.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE&flattened=true \ -H "Content-type: application/json"
POST /north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE&full=true
It is possible to delete the complete device with subscriptions and subscribers adding the parameter full=true in the POST request to the above defined in the three before cases: json format, csv format and flattened json format.
The default value of field full is false. In this case, if it exists a device with a subscription or subscriber, if the device is deleted, only it will be removed device, not the subscription and not the subscriber. |
This is the request using curl in json format:
curl --request POST \ --data-binary @file.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE&full=true \ -H "Content-type: application/json"
This is the request using curl in csv format:
curl --request POST \ --data-binary @file.csv \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE&full=true \ -H "Content-type: text/plain"
This is the request using curl in flattened json format:
curl --request POST \ --data-binary @file.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/bulk/entities?action=DELETE&flattened=true&full=true \ -H "Content-type: application/json"
Bundles software
Software, firmware, configuration. You can rely on OpenGate to update the software, the firmware or the configuration files of your remote devices. The updates can be executed using the operations API, but first of all, OpenGate must know the structure of your update bundles. The following sections show you how to feed OpenGate with your software, firmware an configuration files.
Bundle object structure
A bundle is a group of deployment elements you want to deploy in a remote device. A bundle can contain four file types:
-
SOFTWARE
-
FIRMWARE
-
CONFIGURATION
-
PARAMETERS
attribute (* required) | Description |
---|---|
name * |
[a-zA-Z0-9-_., ] max 50 chars |
version * |
[a-zA-Z0-9-_., ] max 50 chars |
description |
[a-zA-Z0-9-_., ] max 250 chars |
userNotes |
[a-zA-Z0-9-_., ] max 250 chars |
workgroup * |
See admin data section from common objects. The workgroup attribute is required in this case. |
active |
boolean: true, false. you can create a bundle with active=true, you must create a bundle with the field active to false and after create its deployment element with a PUT action change the value of the field active to true. |
creationDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime. This field is only available in reading option, you can’t modify it |
preaction[] |
Valid values:
|
postaction[] |
Valid values:
|
hardware * |
Reference to target hardware from OpenGate hardware catalog. |
Bundle management work flow
We want to make sure you understand the bundle management work flow, because the update operations will use your bundles. Let’s see the following flow chart:
First of all, you must POST a bundle.
Then you must upload, i.e. POST, as many deployment elements as the bundle should have.
Finally, you must setup the state bundle attribute to ACTIVE.
Creating a bundle
POST /north/v80/provision/bundles
New bundles can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
There are two different ways for creating a bundle:
-
Step by step creating in the first step the bundle and after that creating the different deployment elements included in the bundle
-
Introducing in the post request a zip file with the complete structure of the bundle.
The zip file will have the next content:
-
A file called "manifest.txt" where the content of the bundle is explained
-
The files that will become deployment elements within the bundle..
Example of the manifest file, in this file you have to introduce the structure of the different deployment elements files:
{ "contentVersion": "1.0", "downloadUrl": "http://10.10.10.10/fwfiles/filename", "fileContent": { "firmwareFiles": [ { "fileName": "WNC_4-123-2-255.bin", "fileArchivePath": "./directory1/", "fileType": [ "FIRMWARE" ], "fileVersion": "0x0541024105440141", "validators": [ { "type": "SHA-256", "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, { "type": "MD5", "value": "ae410d951c2b04ccb93fd4934215c65b" } ] }, { "fileName": "WNC_4-123-2-366.bin", "fileArchivePath": "./directory1/", "fileType": [ "FIRMWARE" ], "fileVersion": "0x0541024105440141", "validators": [ { "type": "SHA-256", "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, { "type": "MD5", "value": "ae410d951c2b04ccb93fd4934215c65b" } ] } ] } }
An example of a json for creating a bundle
{ "bundle": { "name": "bundle_1", "version": "2-SNAPSHOT", "description": "My Fancy Bundle", "userNotes": "comment 1", "workgroup": "My_workgroup", "active": "false", "preaction": [ "COMMS_DOWN" ], "postaction": [ "HARDWARE_RESET" ], "hardware": "0f1fd82b-959c-44af-a97a-edb765387c4a" } }
Using curl to perform the request:
curl --request POST \ --data-binary @bundle.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/bundles \ -H "Content-type: application/json"
In the case of create a bundle with a zip file, the curl request must be like:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ -Fmeta=@bundle.json \ -Ffile=@bundle.zip \ --verbose http://[your_opengate_address]/north/v80/provision/bundles \
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created bundle. Lets look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/bundles/bundle_1/versions/2-SNAPSHOT
If you create or update a bundle with the field active to false you will not be able to execute an operation of update with that bundle |
Reading a bundle
GET /north/v80/provision/bundles/{bundle_name}/versions/{version_name}
You can apply for a bundle sending a GET request using the URL above. You must replace {bundle_name} with the identifier of the bundles you want to retrieve and {version_name} with the selected version to be read. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/bundles/bundle_1/versions/2-SNAPSHOT \ -H "Content-type: application/json"
The response body could be something like this:
{ "bundle": { "id": "76796426-ec3e-11e1-aff1-0800200c9a66", "name": "bundle_1", "version": "2-SNAPSHOT", "description": "My Fancy Bundle", "userNotes": "comment 1", "workgroup": "My_workgroup", "active": "true", "creationDate":"2010-12-11T10:10:00Z", "preaction": [ "COMMS_DOWN" ], "postaction": [ "HARDWARE_RESET" ], "hardware": "0f1fd82b-959c-44af-a97a-edb765387c4a" } }
Updating a bundle
PUT /north/v80/provision/bundles/{bundle_name}/versions/{version_name}
You can update a bundle sending a PUT request using the URL above. You must replace {bundle_name} with the identifier of the bundle you want to update and {version_name} with the selected version to be updated.
You can’t update a bundle using the file option available in the create option |
You can not update all the fields of a bundle, the following fields are allowed:
-
description
-
preaction
-
postaction
-
userNotes
-
active
-
some fields of the deployments elements
This is the request using curl:
{ "bundle": { "description": "My Fancy Bundle", "preaction": [ "COMMS_DOWN" ], "postaction": [ "HARDWARE_RESET" ] } }
This is the request using curl:
curl --request PUT \ --data-binary @bundle.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/bundles/bundle_1/versions/2-SNAPSHOT \ -H "Content-type: application/json"
If a bundle has been used in an update operation, you can only update the fields:
|
Deleting bundle
DELETE /north/v80/bundles/{bundle_name}/versions/{version_name}
You can delete a bundle sending a DELETE request using the URL above. You must replace {bundle_name}
and {version_name} with the identifiers of the bundle and version you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/bundles/bundle_1/versions/2-SNAPSHOT
If a bundle has been used in an update operation, It can’t be deleted. |
Deployment element
What is a deployment element, a bundle is formed by deployment elements, each of these elements can have files associated or not depending on the operation associated to the deployment element. In a bundle through the deployment elements you can define different actions that you want to perform in the device, install software, update it …
The operations allowed for a deployment element are:
Operation | Description |
---|---|
Install |
With this operation you are trying to include a new deployment ( of any type) in the device. |
Uninstall |
With this operation you are trying to uninstall a deployment element in the device |
Upgrade |
With this operation you are trying to change the version of a deployment element |
The structure of a deployment element is:
attribute | Description | ||
---|---|---|---|
id |
See common objects |
||
name (required) |
[a-zA-Z0-9-_., ] max 50 chars |
||
version (required) |
[a-zA-Z0-9-_.] max 50 chars |
||
type (required) |
string with valid values:
|
||
path (required) |
string. This field indicate the folder where the device has to download the deployment element |
||
order (required) |
identify the position in the bundle structure of the deployment element |
||
operation (required) |
see operation options over |
||
option |
valid values:
This field is obligatory in the operation options "UNINSTALL" and "INSTALL" it’s not allowed in the operation option "UPGRADE" |
||
size |
deployment element’s Size, only available in read options, it’s an non updatable field |
||
oldName |
string This field is obligatory in the operation option "UPGRADE" |
||
oldVersion |
string This field is obligatory in the operation option "UPGRADE" |
||
oldPath |
string This field is obligatory in the operation option "UPGRADE" |
||
validators |
See file validators object below. Allows indicate an array of file validation mechanisms to check file integrity |
||
downloadUrl |
string (Optional). Must contain a valid URL value where the device can download the file.
|
||
fileName |
string (Optional). Must the name of the file to be uploaded.
|
attribute | Description |
---|---|
type |
string. Indicates the type of validation to be performed. Other proprietary values are allowed but when it is required that platform performs file validation (through fileValidationRequired=true URL parameter) only next values are valid:
|
value |
string. |
mode |
string, This field indicates who is responsible for the validation required, there are two reserved values however the field value can be free to use in different projects:
|
Create a deployment element
POST /north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements?fileValidationRequired=<true/false>
You can attach deployment elements to a bundle sending a POST request using the URL above. You must replace {bundle_name} and {version_name} with the identifiers of the bundle and version you want to attach deployment element to. Because you have to upload deployment elements, this POST request is different to others in the OpenGate API. A deployment element upload request comprises a list of items that are encoded according to RFC[RFC 1867, "Form-based File Upload in HTML". OpenGate can parse such a request and "attach" the deployment element to the bundle.
In the option of create a deployment element you can use three options for attaching a file:
-
Filling only the field downloadUrl, in this case the file related to the deployment element will be in the path included in the downloadUrl field.
-
Attaching a file in the create option, and without filling the downloadUrl field, in this case automatically the downloadUrl field will be filled with the configured URL of the OpenGate internal file repository.
-
Attaching a file and filling the downloadUrl field. This case is the combination of the previous once, the file will be loaded on the default path and the device will download the file of the path defined in the downloadUrl path.
Don’t forget upload your deployment element! At least one deployment element must be uploaded, otherwise your bundle cannot be activated. |
FileValidationRequired is an optional parameter that is only used to force to the platform to check integrity of the uploaded file. It is only valid when a valid validator parameter is passed in the attached JSON file |
The deployment element file has a maximum size. This limit can be configured administratively and by default the limit is set to 22020096 bytes. |
In the POST action is mandatory to include the parameter downloadUrl or the file associated with the deployment element, or both of them |
{ "deploymentElement": { "name": "bundle_1-file_1", "version": "1-SNAPSHOT", "type": "FIRMWARE", "path": "./", "order": "1", "operation": "INSTALL", "option": "MANDATORY", "validators" : [ { "type" : "SHA-256", "value" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename", "filename": "filename.ext" } }
{ "deploymentElement": { "name": "bundle_1-file_1", "version": "1-SNAPSHOT", "type": "SOFTWARE", "path": "./", "order": "2", "operation": "UNINSTALL", "option": "MANDATORY" } }
{ "deploymentElement": { "name": "bundle_1-file_1", "version": "1-SNAPSHOT", "type": "FIRMWARE", "path": "./", "order": "1", "operation": "UPGRADE", "oldName": "FANCY-BUNDLE-FILE", "oldVersion": "1.1.0", "oldPath": "./system/data", "validators" : [ { "type" : "SHA-256", "value" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename", "filename": "bundle_template.bin" } }
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ -Fmeta=@deploymentElement.json \ -Ffile=@bundle_template.bin \ --verbose http://[your_opengate_address]/north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements
The Uninstall request doesn’t requires the -Ffile option. |
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the new deployment element. Lets look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElement/bundle_1-file_1/version/1-SNAPSHOT
Reading bundle deployment elements
GET /north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements
You can get the bundle deployment element list sending a GET request using the URL above. You must replace {bundle_name} with the bundle identifier of the bundle and {version_name} with the version you want to get the deployment element list. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements
The response body could be something like this:
{ "deploymentElement": [ { "id": "8fc4d616-0081-4ee8-a82d-99d448b58d40", "name": "fileToInstall", "version": "1.1", "type": "SOFTWARE", "path": "/usr/files", "order": "1", "operation": "INSTALL", "option": "MANDATORY", "size": "512", "validators" : [ { "type" : "SHA-256", "value" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename", "filename": "bundle_template.bin" }, { "id": "3a11ff22-97b6-44a8-800e-97c73d23962f", "name": "fileToUninstall", "version": "1.2", "type": "CONFIGURATION", "path": "/usr/files/config", "order": "2", "operation": "UNINSTALL", "option": "OPTIONAL", "size": "512", "validators" : [ { "type" : "SHA-256", "value" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename", "filename": "bundle_template.bin" }, { "id": "4e5a6e9f-e66f-4a0a-aafe-91dcb18dbef9", "name": "fileToUpgrade", "version": "1.3", "type": "PARAMETERS", "path": "/usr/files/config", "order": "3", "operation": "UPGRADE", "option": "OPTIONAL", "oldName": "fileToUpgradeOld", "oldVersion": "1.3_alpha", "oldPath": "/usr/files/config/old", "validators" : [ { "type" : "SHA-256", "value" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename", "filename": "bundle_template.bin" }, { "id": "98013256-02c6-4cb9-9307-53694e15fb4b", "name": "bundle_1-file_2", "version": "1.2.3-SNAPSHOT", "type": "FIRMWARE", "path": "./", "order": "4", "operation": "INSTALL", "option": "OPTIONAL", "size": "512", "validators" : [ { "type" : "SHA-256", "value" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename", "filename": "bundle_template.bin" } ] }
Reading single deployment element meta-information
GET /north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements/{deploymentElement_name}/version/{deploymentElement_version_name}
You can apply for a single deploymentElement meta-information sending a GET request using the URL above. You must replace {bundle_name}, {version_name}, {deploymentElement_name} and {deploymentElement_version_name} with the bundle, version, deployment element name and deployment element version of the deployment element you want to get. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements/{deploymentElement_name}/version/{deploymentElement_version_name}
The response body could be something deploymentElement this:
{ "deploymentElement": [ { "id": "4e5a6e9f-e66f-4a0a-aafe-91dcb18dbef9", "name": "fileToUpgrade", "version": "1.3", "type": "PARAMETERS", "path": "/usr/files/config", "order": "3", "operation": "UPGRADE", "size": "512", "oldName": "fileToUpgradeOld", "oldVersion": "1.3_alpha", "oldPath": "/usr/files/config/old", "validators" : [ { "type" : "SHA-256", "value" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename", "filename": "bundle_template.bin" } ] }
Reading single deployment element payload
GET /north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements/{deploymentElement_name}/version/{deploymentElement_version_name}?format=raw
You can easily download a previously uploaded deployment element. You only have to send the same GET request used to extract deployment element meta-information, adding a format parameter equals to raw. You can do that using the URL above. You must replace {bundle_name}, {version_name}, {deploymentElement_name} and {deploymentElement_version_name} with the bundle, version, deployment element and deployment element version of the deployment element you want to get. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ "http://[your_opengate_address]/north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements/{deploymentElement_name}/version/{deploymentElement_version_name}?format=raw"
The response body will be the previously uploaded file.
This is an easy way to retrieve the file, even using your desktop web browser.
Updating bundle deployment elements
Sorry this option is not allowed, if you want to change a deployment element you must erase it and create it again with your changes.
Deleting bundle deployment elements
DELETE /north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements/{deploymentElement_name}/version/{deploymentElement_version_name}
You can delete a deployment element sending a DELETE request using the URL above. You must replace {bundle_name}, {version_name}, {deploymentElement_name} and {deploymentElement_version_name} with the bundle, version, deployment element and deployment element version identifier of the deployment element you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/bundles/{bundle_name}/versions/{version_name}/deploymentElements/{deploymentElement_name}/version/{deploymentElement_version_name}
You can’t delete deployment element if your bundle has been used in an update operation. If you try to delete such deployment element, you’ll get an error response. |
Certificates
This API allows manage Security Certificates. Certificates will have different usages: File signing validation, Communications encryption, access control,…
Objects structure
Attribute | Description |
---|---|
id(optional) |
string |
name(optional) |
string |
description (optional) |
string |
administrativeState |
Valid values:
|
usages[] |
Array of strings. Valid values:
|
hardware[](optional) |
Array of objects. See Hardware Object |
tags[](optional) |
Array of strings to allow filtering |
domains(optional) |
Array of strings |
If you don’t fill the Identifier field, one automatic (UUID Format) will be generated |
If you don’t fill the domains field, In Post option user’s domain will be automatically assigned |
Attribute | Description |
---|---|
manufacturer |
string |
model |
string |
modelVersion |
string |
hardwareId |
String. UUID in the opengate hardware catalog. If it is used the others fields must not be present in the JSON |
Attribute | Description | ||
---|---|---|---|
id |
string |
||
name |
string |
||
description |
string |
||
administrativeState |
String. Valid values:
|
||
usages |
Array of Strings. Valid values:
|
||
hardware[](optional) |
Array of objects. See Hardware Object |
||
tags[] |
Array of strings to allow filtering |
||
version |
string |
||
serialNumber |
number |
||
trustChains[[]] |
array of arrays of strings. The second array (of string) contains the path of identifiers for the parent certificates. Example: [ "PathA", "Path B"] = [ ["A1", "A2"], [ "B1", "B2" ] ] |
||
parents[[]] (optional) |
array of arrays of certificates. Contains the JSON object of the parent Certificate
|
||
valid |
|||
subject |
string, it defines the certificate, formed by the next parts, where at least one of them must be filled
|
||
issuer |
string, it defines the parent certificate, formed by the next parts, where at least one of them must be filled
|
||
publicKey |
|||
domains(optional) |
Array of strings |
Attribute | Description |
---|---|
from |
Datetime from when the certificate is valid. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
until |
Datetime until the certificate is valid. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Attribute | Description |
---|---|
algorithm |
string |
size |
number |
format |
string |
Supported File Types
type | mime-type | file extension |
---|---|---|
PEM |
x-pem-file |
.pem |
How trustChains parameter works
The trustChains parameter represents an array of trust chains. Each element of the first array is an string array, readed from the left to the right, representing the path of a certificate of the parents from the root or self-signed certificate until the direct parent of the certificate.
For example if we have a certificate C signed by a certificate B that is signed by a certificate A, the path will be A→B→C and the trustChain will contain the identifier of certificate A in the first position of the array and then the Identifier of the certificate B in the second position of the array. Se the example below assuming that:
-
Identifier of A: 1427353136
-
Identifier of B: 1427353426
"trustChains" : [ [ "1427353136", "1427353426" ] ]
In the same example if you have also the same C certificate but with an alternative trust chain A→B2→C:
-
Identifier of B2: 1427353447
"trustChains" : [ [ "1427353136", "1427353426" ], [ "1427353136", "1427353447" ] ]
Adding a new Certificate
POST /north/v80/provision/security/certificates
You have to upload the files (Json request & Certificate) with the Content-type header as multipart/form-data. See Supported file Types section to know supported types |
Previously to create new certificates it is neccesary to know the next tips:
-
An user can upload in the platform a certificate in her domain and in the domains with low hierarchy managed by the user
-
A certificate can only be signed by a certificate uploaded in the platform with usage CERT_SIGN and this certificate must be in the same domain or in a domain with visible upper hierarchy
-
You can upload the same certificate to the platform a lot of times but always with different identificator
-
If you change the domain of a certificate, the trust chain will be updated keeping in this, only those certificates belonging to visible domains for the new domain
{ "certificate" : { "name": "certificate1_name", "description" : "certificate1_description", "administrativeState" : "ACTIVE", "usages" : [ "FILE_VALIDATION", "DEVICE_COMMUNICATIONS" ], "hardwares" : [ { "manufacturer" : "Manufacturer_1", "model":"MODEL_1", "modelVersion" : "1A" }, { "hardwareId" : "767ac3c8-ec3e-11e1-aff1-0800200c9a66"} ], "tags" : [ "my_tag_1" ] } }
Using curl to perform the request:
curl --request POST \ "-Fjson=@certificate_request.json;type=application/json" \ "-Fcertificate=@certificate.pem;type=application/x-pem-file" \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/security/certificates \
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly added Certificate. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/security/certificates/9d55e8ac-e695-11e5-9730-9a79f06e9478
Reading an IoT Certificate Information
GET /north/v80/provision/security/certificates/{id}
You can apply for an IoT Certificate sending a GET request using the URL above. You must replace {id}
with the identifier of the certificate that you want to get. The user only can access the certificates he has the ownership. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/security/certificates/9d55e8ac-e695-11e5-9730-9a79f06e9478
And this is the response body:
{ "certificate" : { "id" : "9d55e8ac-e695-11e5-9730-9a79f06e9478", "usages" : [ "FILE_VALIDATION", "DEVICE_COMMUNICATIONS" ], "hardwares" : [ { "manufacturer" : "Manufacturer_1", "model":"MODEL_1", "modelVersion" : "1A"}, { "hardwareId" : "767ac3c8-ec3e-11e1-aff1-0800200c9a66"} ], "name": "My Certificate", "description" : "", "administrativeState" : "ACTIVE", "tags" : [ "my_tag_1" ], "version": "", "trustChains": [ ["1427353677"] ], "subject": "CN=MY_CA,OU=O100", "issuer": "CN=MY_CA,OU=O100", "serialNumber" : 1427353677, "valid" : { "from": "2015-03-26T08:07:59Z", "until": "2016-03-26T08:07:59Z" }, "publicKey" : { "algorithm": "RSA", "size" : 2048, "format": "X.509" }, "domains": ["domain_certificates_search"] } }
Reading an IoT Certificate File
GET /north/v80/provision/security/certificates/{id}?format=<file-mime-type>
You can easily download a previously uploaded certificate file. You only have to send the same GET request used to obtain the certificate information, adding a format parameter equals to raw. You must replace {id}
with the identifier of the certificate that you want to get. The user only can access the certificates he has the ownership. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/security/certificates/9d55e8ac-e695-11e5-9730-9a79f06e9478?format=x-pem-file
The response body will be the file containing the required certificate.
This is an easy way to retrieve the file, even using your desktop web browser.
Specific URL parameters
See mime-type column in the Supported file Types section
Modifying an existing Certificate
PUT /north/v80/provision/security/certificates/{id}
Only administrative information can be updated. If you need to change the certificate file, you have to delete the existing and add a new one. |
{ "certificate" : { "name": "My Certificate", "description" : "", "administrativeState" : "ACTIVE", "usages" : [ "FILE_VALIDATION", "DEVICE_COMMUNICATIONS" ], "hardware" : [ { "manufacturer" : "Manufacturer_1", "model":"MODEL_1", "modelVersion" : "1A" } ], "tags" : [ "my_tag_1" ] } }
Using curl to perform the request:
curl --request PUT \ "-Fjson=@certificate_request.json;type=application/json" \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/security/certificates/9d55e8ac-e695-11e5-9730-9a79f06e9478 \
Deleting a Certificate
DELETE /north/v80/provision/security/certificates/{id}
You can delete a Certificate sending a DELETE request using the URL above. You must replace {id}
with the identifier of the certificate that you want to delete . The user only can remove the certificates he has the ownership. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/security/certificates/9d55e8ac-e695-11e5-9730-9a79f06e9478
Channels
Channel entity object structure
A Channel is the way to grouping devices owned by the same organization according to the different IoT solutions managed by this organization
Object / attribute | Description |
---|---|
name |
Name of the Channel |
description |
Description of the Channel, optional |
certificates |
certificates array, optional |
Creating a Channel
POST /north/v80/provision/organizations/{organizationName}/channels
New channels can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "channel": { "name": "battery_channel", "description": "channel description", "certificates": [ "certificate1_id", "certificate2_id" ] } }
This is the request using curl:
curl --request POST \ --data-binary @channel.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/channels \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created channel. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/channels/battery_channel
Reading a Channel
GET /north/v80/provision/organizations/{organizationName}/channels/{channel_name}
You can apply for the channel sending a GET request using the URL above. You must replace {channel_name}
with the name of the entity you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/channels/battery_channel
The response body could be something like this:
{ "channel": { "name": "battery_channel", "description": "channel description", "certificates": [ "certificate1_id", "certificate2_id" ] } }
Updating a Channel
PUT /north/v80/provision/organizations/{organizationName}/channels/{channel_name}
Existing channels can be updated by sending a PUT request using the URL above, including a correctly formatted JSON document in the PUT body.
The channel name field can’t be updated |
{ "channel": { "description": "channel description", "certificates": [ "certificate1_id", "certificate2_id" ] } }
This is the request using curl:
curl --request PUT \ --data-binary @channel.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/channels/{channel_name} \ -H "Content-type: application/json"
Deleting a Channel
DELETE /north/v80/provision/organizations/{organizationName}/channels/{channel_name}
You can delete the Channels by sending a DELETE request using the URL above. You must replace {channel_name}
with the identifier of the Channel you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/channels/battery_channel
Datamodels
This API allows manage Datamodel templates. You can learn more about Datamodels in IoT Concepts
The DMM datamodels are already provisioned by default in the platform. It exists special conditions for them:
If the conditions are skipped the platform will throw an error |
By default the platform automatically generates several DMM datastreams through which it can be retrieved the history of different Monitoring & Management parameters. See also Datamodels to know the list of datastreams. |
Object structure
See Datamodel Object
Adding a new Datamodel
POST /v80/provision/organizations/{organization_id}/datamodels
{ "identifier": "health", "name": "health name", "description": "health description", "version": "1.2", "allowedResourceTypes":[ "entity.device" ], "categories": [ { "identifier": "heart", "name": "heart name", "datastreams": [ { "identifier": "health.heart.rate", "name": "health.heart.rate name", "description": "health.heart.rate description", "period": "INSTANT", "schema": { "type": "string" }, "unit": { "type": "SI", "label": "beats/second", "symbol": "bpm" }, "access": "READ", "storage": { "period": "DAYS", "total": 30 }, "tags": [ "health", "heart" ], "modifiable": true, "required": false } ] } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @datamodel.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/v80/provision/organizations/battery_organization/datamodels \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly added Datamodel. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/v80/provision/organizations/battery_organization/datamodels/health
Adding a new Datamodel with dual datastreams
It allows to associate device information to the related asset.
A use case could be to monitor the occupation the parking spaces of the parking. The device would be a sensor in each space and the asset would be the parking space. The sensor would send a busy or free state. The datapoint with the state would be stored for both the device and the asset.
it is mandatory that the datamodel allows a entity.device and entity.asset like resourceType.
POST /v80/provision/organizations/{organization_id}/datamodels
{ "identifier": "CollectionParking", "name": "Parking", "description": "Parking management", "version": "1.0", "allowedResourceTypes": [ "entity.asset", "entity.device" ], "categories": [ { "identifier": "ParkingSpaces", "datastreams": [ { "identifier": "parking.busy", "name": "Busy parking", "description": "Busy parking space", "period": "INSTANT", "schema": { "type": "boolean" }, "unit": { "symbol": "", "label": "", "type": "basicSI" } } ] } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @datamodel.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/v80/provision/organizations/parking_organization/datamodels \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly added Datamodel. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/v80/provision/organizations/parking_organization/datamodels/CollectionParking
Reading a Datamodel
GET /v80/provision/organizations/{organization_id}/datamodels/{id}
You can apply for a Datamodel sending a GET request using the URL above. You must replace {id}
with the identifier of the Datamodel that you want to get and {organization_id} with the identification of the organization owner of the Datamodel. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/v80/provision/organizations/battery_organization/datamodels/health
And this is the response body:
{ "identifier": "health", "organizationName": "battery_organization", "name": "health name", "version": "1.2", "categories": [ { "identifier": "heart", "name": "heart", "datastreams": [ { "schema": { "type": "string" }, "identifier": "health.heart.rate", "period": "INSTANT", "unit": { "type": "SI", "label": "beats/second", "symbol": "bpm" }, "access": "READ", "name": "health.heart.rate name", "storage": { "period": "DAYS", "total": 30 }, "tags": [ "health", "heart" ], "modifiable": true, "required": false } ] } ] }
This is an example with qRating values
{ "identifier": "health", "organizationName": "battery_organization", "name": "health name", "version": "1.2", "categories": [ { "identifier": "heart", "name": "heart name", "version": "1.2", "datastreams": [ { "schema": { "type": "string" }, "identifier": "health.heart.rate", "period": "INSTANT", "unit": { "type": "SI", "label": "beats/second", "symbol": "bpm" }, "access": "READ", "name": "health.heart.rate name", "storage": { "period": "DAYS", "total": 30 }, "tags": [ "health", "heart" ], "qrating": { "version": "1.0.0", "min_required": { "value": -5, "label": "FROZEN" }, "min_desired": { "value": 5, "label": "COLD" }, "ideal": { "value": 25, "label": "NORMAL/IDEAL" }, "max_desired": { "value": 35, "label": "HIGH" }, "max_allowed": { "value": 60, "label": "HOT" }, "max_score": 1000, "conversionMatrix": { "NORMAL": 100, "SAFE_MODE": 75, "TAMPER": 50, "TEST": 30, "DOWN": 15, "ALARM": 10, "UNKNOWN": 0 }, "cumulative_period_divisor" : 60 }, "modifiable": true, "required": false } ] } ] }
Modifying an existing Datamodel
PUT /v80/provision/organizations/{organization_id}/datamodels/{id}
Regarding the datastream (templates), the behavior of this request is:
|
{ "id": "health", "name": "health name", "version": "1.2", "description": "", "categories": [ { "name": "heart", "datastreams": [ { "id": "health.heart.rate", "name": "<new name>", "description": "<new description>", "unit": { "type": "SI", "label": "beats/second", "symbol": "bpm" }, "period": "INSTANT", "tags": [ "health", "heart", "<new_tag>" ] }, { "id": "health.heart.rrInterval", "name": "Health Heart RrInterval", "description": "Represents the time between two R-Wave detections", "unit": { "type": "SI", "label": "seconds", "symbol": "s" }, "period": "INSTANT", "tags": [ "health", "heart" ] } ] } ] }
Using curl to perform the request:
curl --request PUT \ --data-binary @datamodel.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/v80/provision/organizations/battery_organization/datamodels/health \ -H "Content-type: application/json"
Deleting a Datamodel
DELETE /v80/provision/organizations/{organization_id}/datamodels/{id}
You can delete a Datamodel sending a DELETE request using the URL above. You must replace {id}
with the identifier of the datamodel that you want to delete and {organization_id} with the identification of the organization owner of the datamodel. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/v80/provision/organizations/battery_organization/datamodels/health
You can’t delete a datastream if it has datapoints previously collected |
Devices
A device can be related to Asset through the provision.device.related datastream. It must contain the identifier of the asset.
Device object structure
A device represents a hardware unit and contains the following attributes:
Parameter | Description |
---|---|
resourceType |
It indicates to which type of entity is allowed a datamodel. It is a reading parameter. The user do not need to add this value, the platform assigns internally the value entity.device |
provision |
Object / attribute | Description |
---|---|
administration |
|
device |
The resourceType field defines that the resource is a device. This field is internal, it is returned in the reading request, but it shouldn’t be showed. This field is useful when the user wants all the entities (devices, subscriptions, subscribers and assets) and needs to know the type. It is added by compatibility with the entity functionality. |
Customer provision fields can be defined by the user creating new datamodels that define parameters with using "provision.custom." prefix in the parameter Id. |
Creating a device
POST /north/v80/provision/organizations/{organizationName}/devices
New devices can be created by sending a POST request to the above defined, including a correctly formatted JSON document in the POST body.
A device can contain or not subscriptions and subscribers. Also, these can exist independently (see create subscriptions or create subscribers). In the device, the subscription or subscriber must be inside a communication modules. For this reason, it exists different uses case to manage the devices relations in fuction if exist or not a subscriptions o subscribers:
-
Create a device with subscriptions or subscribers that does not exist in the platform
-
Create a device with subscriptions or subscribers that exist in the platform. In this case, you must do the next steps:
-
Create a device (see Create a device without subscriptions or subscribers)
-
Update a device with the subscriptions or subscriber that exist in the platform (see Associate a subscription or subscriber to the device)
-
Also, a device can be related to asset (see Associate device to asset)
We are going to see the different json in function of these alternatives
Create a device without subscriptions or subscribers
Here’s how to create a device with the minium and recommeded fields
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } } } } }
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "name": { "_current": { "value": "device_battery_name" } }, "description": { "_current": { "value": "device_battery_description" } }, "certificates": { "_current": { "value": [ "certificate1_id" ] } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "MODEM" } }, "serialNumber": { "_current": { "value": "device_battery_sn" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } } } }
It is not necessary to add a organization field in the json because this field is in the URL |
The certificate that you can assign to a device must be in its domain or in domain visible with up hierarchy. |
By default the new entity will be associated to the organization indicated by the URL as long as the organization to which the used API_KEY belongs to or to an organization associated to a subdomain. |
If when you create or update a device introduce a trusted Boot field, this action has consequence in the collection actions, I mean, when you collect an event from one device with the trustedBoot field, if the event has trusted boot the platform will compare the collected value with the provisioned value and you can define an alarm rule for automatically change the administrative status to banned if both values are different. |
Create a device with subscriptions or subscribers that does not exist in the platform
Here’s how to create a device with subscriptions or subscribers that does not exist in the platform
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "name": { "_current": { "value": "device_battery_name" } }, "description": { "_current": { "value": "device_battery_description" } }, "certificates": { "_current": { "value": [ "certificate1_id" ] } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "MODEM" } }, "serialNumber": { "_current": { "value": "device_battery_sn" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "name": { "_current": { "value": "commsMod_battery_name" } }, "description": { "_current": { "value": "commsMod_battery_description" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "UMTS" } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei" } } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "name": { "_current": { "value": "subscription_battery_name" } }, "description": { "_current": { "value": "subscription_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "MOBILE" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi" } }, "msisdn": { "_current": { "value": "34969220026" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "name": { "_current": { "value": "subscriber_battery_name" } }, "description": { "_current": { "value": "subscriber_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "SIM" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc" } } } } } ] } } }
In all above cases, it is used curl to perform the request:
curl --request POST \ --data-binary @device.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created device. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id
POST /north/v80/provision/organizations/{organizationName}/devices?flattened=true
It is possible to create a device with a flattened format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to send a flattened json format.
Here’s how to create a device without subscriptions or subscribers with flattened format
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "provision.device.certificates": { "_value": { "_current": { "value": [ "certificate1_id" ] } } } }
Here’s how to create a device with subscriptions or subscribers that not exist in the platform
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "provision.device.certificates": { "_value": { "_current": { "value": [ "certificate1_id" ] } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_name" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_description" } } } ], "provision.device.communicationModules[].model": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } } ], "provision.device.communicationModules[].specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "UMTS" } } } ], "provision.device.communicationModules[].mobile.imei": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_imei" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_name" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_description" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "MOBILE" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_imsi" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "34969220026" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_id" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_name" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_description" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "SIM" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_icc" } } } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @FlattenedDevice.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices?flattened=true \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created device. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id
Here’s how to create a device with a related asset
{ "resourceType": { "_current": { "value": "entity.device" } }, "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "organization": { "_current": { "value": "battery_organization" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "model": { "_current": { "value": { "manufacturer": "OpenGate", "name": "OpenGate", "version": 1 } } }, "related": { "_current": { "value": "worker_battery_id" } } } } }
Reading a device
GET /north/v80/provision/organizations/{organizationName}/devices/{identifier}
You can apply for a device sending a GET request using the URL above. You must replace {identifier}
with the identifier of the device you want to retrieve.
The date field is transformed by applying the TimeZone of the user who made the request. The format is YYYY-MM-DDThh:mm:ssTZD. If you want obtain the date in UTC, you must add in the url the parameter utc, see reading device in UTC |
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id
And this is the response body:
{ "resourceType": { "_current": { "value": "entity.device" } }, "provision": { "administration": { "identifier": { "_current": { "value": "device_battery", "provType": "MONITORING", "date": "2017-09-25T09:34:32.219Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-09-25T09:34:32.216Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-09-25T09:34:32.211Z" } }, "plan": { "_current": { "value": "FLOW_RATE_100", "provType": "MONITORING", "date": "2017-10-04T12:18:18.402Z" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.173Z" } }, "name": { "_current": { "value": "device_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:31.879Z" } }, "description": { "_current": { "value": "device_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:31.976Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:31.966Z" } }, "operationalStatus": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2017-09-25T09:34:32.189Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-09-25T09:34:31.915Z" } }, "specificType": { "_current": { "value": "MODEM", "provType": "MONITORING", "date": "2017-09-25T09:34:31.865Z" } }, "serialNumber": { "_current": { "value": "device_battery_sn", "provType": "IDENTIFIER", "date": "2017-09-25T09:34:31.845Z" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-09-25T09:34:31.954Z" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } }, "name": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.169Z" } }, "description": { "_current": { "value": "commsMod_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" }, "provType": "MONITORING", "date": "2017-09-25T09:34:32.097Z" } }, "specificType": { "_current": { "value": "UMTS", "provType": "MONITORING", "date": "2017-09-25T09:34:32.115Z" } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei", "provType": "MONITORING", "date": "2017-09-25T09:34:32.103Z" } } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.083Z" } }, "name": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.079Z" } }, "description": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32.073Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.031Z" } }, "specificType": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.013Z" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-09-25T09:34:32.041Z" } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-09-25T09:34:32.059Z" } }, "msisdn": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-09-25T09:34:32.049Z" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-09-25T09:34:32.055Z" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-09-25T09:34:32.052Z" } } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.151Z" } }, "name": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.158Z" } }, "description": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32.162Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.131Z" } }, "specificType": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-09-25T09:34:32.143Z" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-09-25T09:34:32.148Z" } } } } } ] } } }
The trusted Boot and other security related parameters can’t be showed in a get process |
GET /north/v80/provision/organizations/{organizationName}/devices/{identifier}?flattened=true
You can apply for a device with flattened format (see flattened concept) sending a GET request using the URL above. In this case, it is sent a boolean parameter, flattened, to allow to receive a flattened json format. You must replace {identifier}
with the identifier of the device you want to retrieve.
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id?flattened=true
And this is the response body:
{ "resourceType": { "_value": { "_current": { "value": "entity.device" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "device_battery", "provType": "MONITORING", "date": "2017-09-25T09:34:32.219Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-09-25T09:34:32.216Z" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-09-25T09:34:32.211Z" } } }, "provision.administration.plan": { "_value": { "_current": { "value": "FLOW_RATE_100", "provType": "MONITORING", "date": "2017-10-04T12:18:18.402Z" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.173Z" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:31.879Z" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:31.976Z" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:31.966Z" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2017-09-25T09:34:32.189Z" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" }, "provType": "MONITORING", "date": "2017-09-25T09:34:31.915Z" } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM", "provType": "MONITORING", "date": "2017-09-25T09:34:31.865Z" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn", "provType": "IDENTIFIER", "date": "2017-09-25T09:34:31.845Z" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-09-25T09:34:31.954Z" } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.169Z" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "commsMod_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32Z" } } } ], "provision.device.communicationModules[].model": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-09-25T09:34:32.097Z" } } } ], "provision.device.communicationModules[].specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "UMTS", "provType": "MONITORING", "date": "2017-09-25T09:34:32.115Z" } } } ], "provision.device.communicationModules[].mobile.imei": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "commsMod_battery_imei", "provType": "MONITORING", "date": "2017-09-25T09:34:32.103Z" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.083Z" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.079Z" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32.073Z" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.031Z" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.013Z" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-09-25T09:34:32.041Z" } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-09-25T09:34:32.059Z" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-09-25T09:34:32.049Z" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-09-25T09:34:32.055Z" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-09-25T09:34:32.052Z" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.151Z" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.158Z" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32.162Z" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.131Z" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-09-25T09:34:32.143Z" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } }, "_value": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-09-25T09:34:32.148Z" } } } ] }
GET /north/v80/provision/organizations/{organizationName}/devices/{identifier}?utc=true
You can apply for a device with the date in UTC sending a GET request using the URL above with the boolean parameter utc. You must replace {identifier}
with the identifier of the device you want to retrieve.
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id?utc=true
And this is the response body:
{ "resourceType": { "_current": { "value": "entity.device" } }, "provision": { "administration": { "identifier": { "_current": { "value": "device_battery", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "plan": { "_current": { "value": "FLOW_RATE_100", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "name": { "_current": { "value": "device_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "description": { "_current": { "value": "device_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "operationalStatus": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "MODEM", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "serialNumber": { "_current": { "value": "device_battery_sn", "provType": "IDENTIFIER", "date": "2018-06-20T12:59:58.463Z" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "name": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "description": { "_current": { "value": "commsMod_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" }, "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "UMTS", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "name": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "description": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2018-06-20T12:59:58.463Z" } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2018-06-20T12:59:58.463Z" } }, "msisdn": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "name": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "description": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } } } } ] } } }
Updating a device
PUT /north/v80/provision/organizations/{organizationName}/devices/{identifier}
You can update a device sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the device you want to update.
You can update:
The JSON object passed will be different in function the desire update
Updating only the device data
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "name": { "_current": { "value": "device_battery_name" } }, "description": { "_current": { "value": "device_battery_description" } }, "certificates": { "_current": { "value": [ "certificate1_id" ] } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "MODEM" } }, "serialNumber": { "_current": { "value": "device_battery_sn" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "name": { "_current": { "value": "commsMod_battery_name" } }, "description": { "_current": { "value": "commsMod_battery_description" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "UMTS" } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei" } } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "name": { "_current": { "value": "subscription_battery_name" } }, "description": { "_current": { "value": "subscription_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "MOBILE" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi" } }, "msisdn": { "_current": { "value": "34969220026" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "name": { "_current": { "value": "subscriber_battery_name" } }, "description": { "_current": { "value": "subscriber_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "SIM" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc" } } } } } ] } } }
Associate a subscription or subscriber to the device
Here’s how to create a device with subscriptions or subscribers that exist in the platform.
The subscription or subscriber must be created previosly (see create subscriptions or create subscribers). |
If the subscription or subscriber are on another device. First, they must be disassociate of the device (see Desassociate a subscription or subscriber of the device). |
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "name": { "_current": { "value": "device_battery_name" } }, "description": { "_current": { "value": "device_battery_description" } }, "certificates": { "_current": { "value": [ "certificate1_id" ] } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "MODEM" } }, "serialNumber": { "_current": { "value": "device_battery_sn" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "name": { "_current": { "value": "commsMod_battery_name" } }, "description": { "_current": { "value": "commsMod_battery_description" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "UMTS" } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei" } } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } } } } ] } } }
Desassociate a subscription or subscriber of the device
It allow to delete a subscriptions or subscribers inside the device. The subscriptions or subscribers exist again independently.
The JSON object passed you must remove the subscription or subscriber that you want delete
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "value": "device_battery_id" } }, "name": { "_current": { "value": "device_battery_name" } }, "description": { "_current": { "value": "device_battery_description" } }, "certificates": { "_current": { "value": [ "certificate1_id" ] } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "operationalStatus": { "_current": { "value": "NORMAL" } }, "model": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } }, "specificType": { "_current": { "value": "MODEM" } }, "serialNumber": { "_current": { "value": "device_battery_sn" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } } } }
In all cases, this is the request using curl:
curl --request PUT \ --data-binary @device.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id \ -H "Content-type: application/json"
PUT /north/v80/provision/organizations/{organizationName}/devices/{identifier}?flattened=true
You can update a device with flattened format (see flattened concept) sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the device you want to update. Also it is sent a boolean parameter, flattened, to allow to send a flattened json format.
Just like before, you can update:
-
Only the device data.
-
Associate a subscription or subscriber to the device.
-
Desassociate a subscription or subscriber of the device.
The JSON object passed will be different in function the desire update
Updating only the device data
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "provision.device.certificates": { "_value": { "_current": { "value": [ "certificate1_id" ] } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_name" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_description" } } } ], "provision.device.communicationModules[].model": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } } ], "provision.device.communicationModules[].specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "UMTS" } } } ], "provision.device.communicationModules[].mobile.imei": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_imei" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_name" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_description" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "MOBILE" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_imsi" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "34969220026" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_id" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_name" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_description" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "SIM" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_icc" } } } ] }
Associate a subscription or subscriber to the device
Here’s how to create a device with subscriptions or subscribers that exist in the platform.
The subscription or subscriber must be created previosly (see create subscriptions or create subscribers) |
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "provision.device.certificates": { "_value": { "_current": { "value": [ "certificate1_id" ] } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_name" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_description" } } } ], "provision.device.communicationModules[].model": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } } ], "provision.device.communicationModules[].specificType": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "UMTS" } } } ], "provision.device.communicationModules[].mobile.imei": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_imei" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_id" } } } ] }
Desassociate a subscription or subscriber of the device
It allow to delete a subscriptions or subscribers inside the device. The subscriptions or subscribers exist again independently.
The JSON object passed you must remove the subscription or subscriber that you want delete
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "manufacturer": "OpenGate", "version": "1.0" } } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" } } } }, "provision.device.certificates": { "_value": { "_current": { "value": [ "certificate1_id" ] } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ] }
In all cases, this is the request using curl:
curl --request PUT \ --data-binary @device.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id?flattened=true \ -H "Content-type: application/json"
Patching a device
PATCH /north/v80/provision/organizations/{organizationName}/devices/{identifier}
You can patch a device sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the device you want to patch.
You can patch:
The JSON object passed will be different in function of the desired patch
Patching only the device data
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } } }, "device": { "description": { "_current": { "value": "device_battery_description patched" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "description": { "_current": { "value": "commsMod_battery_description patched" } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "description": { "_current": { "value": "subscription_battery_description patched" } }, }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "description": { "_current": { "value": "subscriber_battery_description patched" } } } } ] } } }
Associate a subscription or subscriber to the device
Here’s how to patch a device with subscriptions or subscribers that exist in the platform.
The subscription or subscriber must be created previosly (see create subscriptions or create subscribers). |
If the subscription or subscriber are on another device, first, they must be disassociate of the device (see Desassociate a subscription or subscriber of the device). |
Administration channel value is mandatory in patch operation for securization purposes. |
When patching complex object values, non passed object attributes will be patched as non existent, so include previous unchanged values if you don’t want to loose them. |
When patching a device with a subentity that previously existed, providing the identifier will recover all its data an attach it to the device. |
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } } }, "device": { "description": { "_current": { "value": "device_battery_description patched" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id" } }, "description": { "_current": { "value": "commsMod_battery_description patched" } } } ] } } }
In all cases, this is the request using curl:
curl --request PATCH \ --data-binary @device.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id \ -H "Content-type: application/json"
PATCH /north/v80/provision/organizations/{organizationName}/devices/{identifier}?flattened=true
You can patch a device with flattened format (see flattened concept) sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the device you want to patch. Also it is sent a boolean parameter, flattened, to allow to send a flattened json format.
Just like before, you can patch:
-
Only the device data.
-
Associate a subscription or subscriber to the device.
The JSON object passed will be different in function of the desired patch
Patching only the device data
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description patched" } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_description patched" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscription_battery_description patched" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_id" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "subscriber_battery_description patched" } } } ] }
Associate a subscription or subscriber to the device
Here’s how to patch a device with subscriptions or subscribers that exist in the platform.
The subscription or subscriber must be created previosly (see create subscriptions or create subscribers) |
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.device.description": { "_value": { "_current": { "value": "device_battery_description patched" } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_id" } } } ], "provision.device.communicationModules[].description": [ { "_index": { "value": "commsMod_battery_id" }, "_value": { "_current": { "value": "commsMod_battery_description patched" } } } ] }
In all cases, this is the request using curl:
curl --request PATCH \ --data-binary @device.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id?flattened=true \ -H "Content-type: application/json"
Deleting a device
DELETE /north/v80/provision/organizations/{organizationName}/devices/{identifier}
You can delete a device sending a DELETE request using the URL above. You must replace {identifier}
with the identifier of the device you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id
DELETE /north/v80/provision/organizations/{organizationName}/devices/{identifier}?full=true
You can delete a complete device with subscriptions and subscribers sending a DELETE request using the URL above. It is sent a boolean parameter, full, to allow to delete a complete device. You must replace {identifier}
with the identifier of the device you want to delete.
The default value of field full is false. In this case, if it exists a device with a subscription or subscriber, if the device is deleted, only it will be removed device, nor the subscription nor the subscriber. After this moment, they will exist in the platform independently, without be associated to device. |
This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_battery_id?full=true
Domains
A domain represent the concept that allow to the users manage organizations and the devices of that organizations
Domain object structure
Object / attribute | Description |
---|---|
name |
Name of the Domain. This field is mandatory |
description |
Description of the domain. This field is optional |
parentDomain |
Domain with upper hierarchy. This field is optional. If this field is not filled the new domain is assigned to the user creator domain |
Creating a Domain
POST /north/v80/provision/domains
New domains can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "domain": { "name": "Domain_2", "description": "Domain description", "parentDomain": "Domain_1" } }
This is the request using curl:
curl --request POST \ --data-binary @domain.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created domain. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/domain/Domain_2
When you create a domain, automatically is created all the plans associated to the parent domain with the check "defaultAssigned" true |
Reading a Domain
It is possible to obtain the domains tree through hierarchy parameter. This parameter is boolean, if the value is true, the response contains the domains tree, else only domain.
By default the value of hierarchy parameter is false |
GET /north/v80/provision/domains/{domain_name}
You can apply for the domain sending a GET request using the URLs above. You must replace {domain_name}
with the name of the domain you want to retrieve. This is the request using curl without hierarchy parameter:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/Domain_2
The response body could be something like this:
{ "domain": { "name": "Domain_2", "description": "Domain description", "parentDomain": "Domain_1" } }
GET /north/v80/provision/domains/{domain_name}?hierarchy=true
You can apply for the domains tree sending a GET request using the hierarchy parameter. You must replace {domain_name}
with the name of the parent domain you want to retrieve.
By default if the parameter hierarchy is missing the behavior is the same than the value is hierarchy=false |
This is the request using curl with hierarchy parameter:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/Domain_2?hierarchy=true
{ "domain": { "name": "Domain_2", "description": "Domain description", "parentDomain": "Domain_1", "domains": [ { "name": "Domain_2_1", "description": "Domain description", "parentDomain": "Domain_2", "domains": [ { "name": "Domain_2_1_1", "description": "Domain description", "parentDomain": "Domain_2_1" } ] } ] } }
Updating a Domain
PUT /north/v80/provision/domains/{domain_name}
Existing domains can be updated by sending a PUT request using the URL above, including a correctly formatted JSON document in the PUT body.
The domain name field can’t be updated |
{ "domain": { "description": "Domain description", "parentDomain": "Domain_1" } }
This is the request using curl:
curl --request PUT \ --data-binary @domain.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/{domain_name} \ -H "Content-type: application/json"
Deleting a Domain
DELETE /north/v80/provision/domains/{domain_name}
You can delete domains by sending a DELETE request using the URL above. You must replace {domain_name}
with the name of the domain you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/domain_2
Entities
An entity is all monitoring element inside IoT world.
The platform offers four types of entities: asset, device, subscription, subscriber and distinguishes between them, thanks to the resourceType attribute. In the following table you can see how is provisioned each entity type:
Entity | ResourceType attribute | Description | Provision |
---|---|---|---|
Asset |
entity.asset |
It allows to create new entities by the user differents to the environment of the device |
|
Device |
entitiy.device |
It represents a hardware unit |
|
Subscription |
entity.subscription |
It stores information regarding the contracts with your communication operators |
|
Subscriber |
entity.subscriber |
It stores information regarding a specific communication channel |
Manufacturers
This API allows the provision of hardware manufacturers used to associate to the entities. You can associate images to the manufacturers as logos or documentation.
Manufacturer Object structure
This object has all the relevant information about a manufacturer
attribute (* required) | Description |
---|---|
id * |
[a-zA-Z0-9-_., ] max 50 chars and unique within an OpenGate installation. |
name * |
max 1020 chars |
telephone |
max 1020 chars |
address |
max 1020 chars |
fax |
max 1020 chars |
url |
max 1020 chars |
notes |
max 1020 chars |
description |
max 1020 chars |
Creating a manufacturer
POST /north/v80/provision/manufacturers
New manufacturers can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
An example of a json for creating a manufacturer
{ "manufacturer": { "Id": "0c3e849a-4c55-4fe8-983a-be557be67945", "name": "opengate", "telephone": "34911126747", "email": "opengate@amplia.es", "address": "Golfo de Salonica 27 1", "fax": "34911126747", "url": "www.amplia-iiot.com", "notes": "Manufacturer", "description": "Default manufacturer" } }
Using curl to perform the request:
curl --request POST \ --data-binary @manufacturer.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/manufacturers \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created manufacturer. Lets look at the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/manufacturers/0c3e849a-4c55-4fe8-983a-be557be67945
Reading a manufacturer
GET /north/v80/provision/manufacturers/{manufacturerId}
You can request manufacturer info by sending a GET request using the URL above. You must replace {manufacturerId} with the identifier of the manufacturer you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/manufacturers/0c3e849a-4c55-4fe8-983a-be557be67945 \ -H "Content-type: application/json"
The response body could be something like this:
{ "manufacturer": { "Id": "0c3e849a-4c55-4fe8-983a-be557be67945", "name": "opengate", "telephone": "34911126747", "email": "opengate@amplia.es", "address": "Golfo de Salonica 27 1", "fax": "34911126747", "url": "www.amplia-iiot.com", "notes": "Manufacturer", "description": "Default manufacturer" } }
Updating a manufacturer
PUT /north/v80/provision/manufacturers/{manufacturerId}
You can update a manufacturer by sending a PUT request using the URL above. You must replace {manufacturerId} with the identifier of the manufacturer you want to update.
You can update all manufacturer fields except for the Idenfier field
This is the request using curl:
curl --request PUT \ --data-binary @manufacturer.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/manufacturers/0c3e849a-4c55-4fe8-983a-be557be67945 \ -H "Content-type: application/json"
Deleting a manufacturer
DELETE /north/v80/provision/manufacturers/{manufacturerId}
You can delete a manufacturer by sending a DELETE request using the URL above. You must replace {manufacturerId} with the identifier of the manufacturer you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/manufacturers/0c3e849a-4c55-4fe8-983a-be557be67945
If a manufacturer currently has models provisioned in OpenGate, it can’t be deleted. |
Manufacturer Media Files
Media files are files that you want to asociate to the manufacturer, i.e. the manufacturer logo. You can add as many files as you want without a limit .
The structure of a media object is:
attribute (* required) | Description |
---|---|
id * |
[a-zA-Z0-9-_., ] max 50 chars and unique in a platform |
name * |
max 1020 chars |
filename * |
[a-zA-Z0-9-_.] max 50 chars |
size |
number. It is read only, in post and put operation it will be calculated. |
type * |
string with valid values:
|
dimension |
string. It is read only, in post and put operation it will be calculated. See Dimensions object below. |
Creating a manufacturer media file
POST /north/v80/provision/manufacturers/{manufacturerId}/media
You can attach media file elements to a manufacturer sending a POST request using the URL above. You must replace {manufacturerId} with the manufacturer identifier that you want to attach a media file to.
This is a json example
{ "media": { "id": "opengateLogo", "name": "Logo", "filename": "LogoOpenGate.jpg", "type": "image/png", } }
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ -Fmeta=@meida.json \ -Ffile=@logo.png \ --verbose http://[your_opengate_address]/north/v80/provision/manufacturers/{manufacturerId}/media
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the new media file. Lets look at the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/manufacturers/{manufacturerId}/media/opengateLogo
Listing media files
GET /north/v80/provision/manufacturers/{manufacturerId}/media
You can get the media file element list by sending a GET request using the URL above. You must replace {manufacturerId} with the manufacturer identifier of the manufacturer. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/manufacturers/{manufacturerId}/media
The response body could be something like this:
{ "media": [ { "id": "opengateLogo", "name": "Logo", "filename": "LogoOpenGate.jpg", "type": "image/png", "size": 256, "dimension": { "width": 572, "height": 572 } }, { "id": "opengateLogo2", "name": "Logo2", "filename": "LogoOpenGate2.jpg", "type": "image/png", "size": 256, "dimension": { "width": 572, "height": 572 } } ] }
Reading a single media file element
GET /north/v80/provision/manufacturers/{manufacturerId}/media/{mediaId}?format=raw
You can easily download a previously uploaded media file. You only have to send the same GET request used to extract the media file meta-information, adding a format parameter equals to raw. You can do that using the URL above. You must replace {manufacturerId}, {mediaId} with the manufacturer identifier and the media file identifier that you want to get. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ "http://[your_opengate_address]/north/v80/provision/manufacturers/{manufacturerId}/media/{mediaId}?format=raw
The response body will be the previously uploaded file.
This is an easy way to retrieve the file, even using your desktop web browser.
Updating media file elements
Oops, sorry, this option is not allowed. If you need to modify a media file you must delete it and create it again with your changes.
Deleting a media file element
DELETE /north/v80/provision/manufacturers/{manufacturerId}/media/{mediaId}
You can delete a media file element by sending a DELETE request using the URL above. You must replace {manufacturerId}, {mediaId} with the manufacturer identifier and the media file identifier that you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/manufacturers/{manufacturerId}/media/{mediaId}
Models
This API allows the provision of hardware models used to associate to the entities. You can associate files to the models as logos or pictures of a device model.
Object structure
This object has all the relevant information about a hardware model.
attribute (* required) | Description |
---|---|
id * |
[a-zA-Z0-9-_., ] max 50 chars and unique within an OpenGate installation. |
name * |
max 1020 chars |
version |
max 1020 chars |
url |
max 1020 chars |
notes |
max 1020 chars |
description |
max 1020 chars |
manufacturer |
attribute (* required) | Description |
---|---|
id * |
[a-zA-Z0-9-_., ] max 50 chars and unique within an OpenGate instance |
name * |
max 1020 chars |
Creating a model
POST /north/v80/provision/models
New models can be provisioned by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
An json example that can be used to create a model:
{ "model": { "id": "OpenGate", "name": "OpenGate", "version": "1.0", "url": "www.opengatemodel-connect.com", "notes": "Notes for Opengate Hardware", "description": "Description for Opengate Hardware", "manufacturer": { "id": "0c3e849a-4c55-4fe8-983a-be557be67948", "name": "ManufacturerName_1" } } }
If no manufacturer is included, the model will be assigned to an "unknown" manufacturer. |
Using curl to perform the request:
curl --request POST \ --data-binary @model.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/models \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created model. Lets look at the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/models/OpenGate
Reading a Model
GET /north/v80/provision/models/{modelId}
You can request model info by sending a GET request using the URL above. You must replace {modelId} with the identifier of the model you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/models/0c3e849a-4c55-4fe8-983a-be557be67945 \ -H "Content-type: application/json"
The response body could be something like this:
{ "model": { "id": "OpenGate", "name": "OpenGate", "version": "1.0", "url": "www.opengatemodel-connect.com", "notes": "Notes for Opengate Hardware", "description": "Description for Opengate Hardware", "manufacturer": { "id": "0c3e849a-4c55-4fe8-983a-be557be67948", "name": "ManufacturerName_1" } } }
Updating a Model
PUT /north/v80/provision/models/{modelId}
You can update a model by sending a PUT request using the URL above. You must replace {modelId} with the identifier of the model you want to update.
You can update all model fields except for the Idenfier field.
This is the request using curl:
curl --request PUT \ --data-binary @model.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/models/0c3e849a-4c55-4fe8-983a-be557be67945 \ -H "Content-type: application/json"
Deleting a model
DELETE /north/v80/provision/models/{modelId}
You can delete a manufacturer sending a DELETE request using the URL above. You must replace {modelId} with the identifier of the model you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/models/0c3e849a-4c55-4fe8-983a-be557be67945
Model Media Files
Media files are files that you want to asociate to the model, i.e. the model picture. You can add all the files you need without a limit. the The structure of a media object is:
attribute (* required) | Description |
---|---|
id * |
[a-zA-Z0-9-_., ] max 50 chars and unique for the OpenGate instance |
name * |
max 1020 chars |
filename * |
[a-zA-Z0-9-_.] max 50 chars |
size |
number. It appears only in read option, in post and put is not writeable, it’s calculated |
type * |
string with valid values:
|
dimension |
string. Read only, in post and put operations this value is calculated. See Dimensions object below. |
Creating a Hardware media file
POST /north/v80/provision/models/{modelId}/media
You can attach media files elements to a model by sending a POST request using the URL above. You must replace {modelId} with the identifier of the model you want to attach a media file to.
This is a json example
{ "media": { "id": "opengateLogo", "name": "Logo", "filename": "LogoOpenGate.jpg", "type": "image/png", } }
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ -Fmeta=@meida.json \ -Ffile=@logo.png \ --verbose http://[your_opengate_address]/north/v80/provision/models/{modelId}/media
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the new media file. Lets look at the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/models/{modelId}/media/opengateLogo
Listing media files
GET /north/v80/provision/models/{modelId}/media
You can get the media file element list by sending a GET request using the URL above. You must replace {modelId} with the identifier of the model. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/models/{modelId}/media
The response body could be something like this:
{ "media": [ { "id": "opengateLogo", "name": "Logo", "filename": "LogoOpenGate.jpg", "type": "image/png", "size": 256, "dimension": { "width": 572, "height": 572 } }, { "id": "opengateLogo2", "name": "Logo2", "filename": "LogoOpenGate2.jpg", "type": "image/png", "size": 256, "dimension": { "width": 572, "height": 572 } } ] }
Reading a single media file element
**GET /north/v80/provision/models/{modelId}/media/{mediaId}?format=raw
You can easily download a previously uploaded media file. You only have to send the same GET request used to extract media file meta-information, adding a format parameter equals to raw. You can do that using the URL above. You must replace {modelId} and {mediaId} with the model identifier and the media file identifier that you want to get. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ "http://[your_opengate_address]/north/v80/provision/models/{modelId}/media/{mediaId}?format=raw
The response body will be the previously uploaded file.
This is an easy way to retrieve the file, even using your desktop web browser.
Updating media file elements
Oops, sorry, this option is not allowed. If you need to modify a media file you must delete it and create it again with your changes.
Deleting a media file element
DELETE /north/v80/provision/models/{modelId}/media/{mediaId}
You can delete a media file element by sending a DELETE request using the URL above. You must replace {modelId} and {mediaId} with the model identifier and the media file identifier that you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/models/{modelId}/media/{mediaId}
Organizations
Organization entity object structure
Organization entity represents an organization that owns one or more different IoT solutions
Object / attribute | Description |
---|---|
name |
Name of the Organization |
description |
Description of the Organization. this field is optional |
countryCode |
Country of the Organization. The content must be in upper case. The codes are ISO CODES defined in https://countrycode.org. This field is optional and if you don’t specify a particular countryCode, one specific will be assigned |
langCode |
Language Code. This field is optional and if you don’t specify a particular langCode, one specific will be assigned |
timezone |
Time Zone is the uniform naming convention, for example "Europe/Paris". See Available time zone. This field is optional and if you don’t specify a particular timezone, one specific will be assigned |
domain |
Domain of witch depend on an organization. This field is optional and if you don’t select a specific domain, the new organization and it’s default domain will be created under your own domain. |
mapDefault |
Default parameters to locate the map for all the users in the organization. See Map Default Object. this field is optional and if you don’t specify a particular position, one specific will be assigned. |
plan |
Plan asigned to the organization, only one plan can be assigned to the organization. This plan must be allowed to the organization domain. You can search possible plans using organization search plans URLs. This field is optional and it’s default value is Trial |
onlyAssignedDomainCertificates |
Boolean, if true implies that you only can use for it’s own channels and devices the certificates assigned to its domains. you can’t use certificates from domains with upper hierarchy. This field is optional and it’s default value is false. |
Object / attribute | Description |
---|---|
zoom |
Numeric Zoom level to be applied by default in the map panel |
location |
Default coordinates to center the map. See Map Location Object |
Object / attribute | Description |
---|---|
latitude |
Latitude expressed in decimal degrees |
longitude |
Longitude expressed in decimal degrees |
Creating an Organization
POST /north/v80/provision/organizations
New organizations can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "organization": { "name": "battery_organization", "description": "Organization description", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Andorra", "domain": "domain1", "mapDefault": { "zoom": 10, "location": { "latitude": 43.5398, "longitude": -5.66194 } }, "plan": "BASIC", "onlyAssignedDomainCertificates": false } }
The request using curl is:
curl --request POST \ --data-binary @organization.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created organization. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/battery_organization
When you create an organization automatically, is created:
If on organization creation you specify a domain, the resulting organization and it’s default domain will be created under the specified domain. |
Reading an Organization
GET /north/v80/provision/organizations/{organization_name}
You can apply for an existing organization by sending a GET request using the URL above. You must replace {organization_name}
with the name of the organization you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization
The response body could be something like this:
{ "organization": { "name": "battery_organization", "description": "Organization description", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Andorra", "domain": "domain1", "mapDefault": { "zoom": 10, "location": { "latitude": 43.5398, "longitude": -5.66194 } }, "plan": "BASIC", "onlyAssignedDomainCertificates": false } }
Updating an Organization
PUT /north/v80/provision/organizations/{organization_name}
You can update an existing organization sending a PUT request using the URL above. You must replace {organization_name}
with the name of the organization you want to retrieve. This is the request using curl:
curl --request PUT \ --data-binary @organization.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization \ -H "Content-type: application/json"
The JSON object passed could be something like this:
{ "organization": { "name": "battery_organization", "description": "Organization description", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Andorra", "domain": "domain1", "mapDefault": { "zoom": 10, "location": { "latitude": 43.5398, "longitude": -5.66194 } }, "plan": "BASIC", "onlyAssignedDomainCertificates": false } }
Deleting an Organization
DELETE /north/v80/provision/organizations/{organization_name}
You can delete the Organizations by sending a DELETE request using the URL above. You must replace {organization_name}
with the identifier of the organization you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization
Radius Clients
The OpenGate platform could receive information about M2M communications networks operational status from the Remote Access Servers or delegated Radius Servers. These different type of nodes can forward radius information to the platform, specifically Radius Accounting packets
Radius Client entity object structure
The Radius Client entity stores information regarding the Network Access endpoint that provide devices access to a IP network
Object / attribute | Description |
---|---|
name |
Name of Radius Client |
description |
Description of the Radius Client |
sourceAddress |
IP address used by the Radius Client to connect with the OpenGate Platform |
radiusSecret |
Secret used in to the radius accounting communications |
syncCache |
Specific parameters for synchronized cache mechanism |
Object / attribute | Type | Description |
---|---|---|
effectiveDate |
string |
Datetime when the provision will take effect. If parameter is not passed or value is lower than current date the value will take effect immediately (Platform configured cache policies must be taken into account). Datetime when the coordinates were obtained. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Creating a Radius Client
POST /north/v80/provision/radiusClients
New Radius Clients can be added by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "radiusClient" : { "name": "radiusClient_1", "description": "description of the Radius client endpoint. Example a GGSN", "sourceAddress": "X.X.X.X", "radiusSecret": "XXXXXXXX", "syncCache" : { "effectiveDate": "2014-05-28T15:20:51Z" } } }
APN entries are cached internally in the every active server running the platform. Several behaviours are allowed that depends on the JSON request: If no syncCache object is present in the JSON attached file the platform will use a normal not synchronized cache strategy to distribute the information to the different active platform servers If syncCache object is present but no effectiveDate is present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers calculating the time when the change will take effect If syncCache object and effectiveDate are present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers setting the passed value as the datetime when the change will take effect |
Using curl to perform the request, you can add an Radius Client sending a POST request using this URL template: http://[your_opengate_address]/north/v80/provision/radiusClients
curl --request POST \ --data-binary @radiusClient.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/radiusClients \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created)
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/radiusClients/radiusClient_1
Reading a Radius Client
GET /north/v80/provision/radiusClients/{id}
You can apply for the Radius Client sending a GET request using the URL above. You must replace {id}
with the name of the entity you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/radiusClients/radiusClient_1
The response body could be something like this:
{ "radiusClient" : { "name": "radiusClient_1", "description": "description of the Radius client endpoint. Example a GGSN", "sourceAddress": "X.X.X.X", "radiusSecret": "XXXXXXXX", "syncCache" : { "effectiveDate": "2014-05-28T15:20:51Z" } } }
Updating a Radius Client
PUT /north/v80/provision/radiusClients/{id}
You can update a Radius Client by sending a PUT request using the URL above. You must replace {id}
with the name of the Radius Client you want to update. This is de request using curl:
See the synchronized cache note described in the create operation |
curl --request PUT \ --data-binary @radiusClient.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/radiusClients/radiusClient_1 \ -H "Content-type: application/json"
Deleting a Radius Client
DELETE /north/v80/provision/radiusClients/{id}?syncCache&effectiveDate={effectiveDate}
You can delete the Radius Clients of an entity sending a DELETE request using the URL above. You must replace {id}
with the identifier of the Radius Client you want to delete. This is the request using curl.
APN entries are cached internally in the every active server running the platform. Several behaviours are allowed that depends on the JSON request: If no syncCache object is present in the JSON attached file the platform will use a normal not synchronized cache strategy to distribute the information to the different active platform servers If syncCache object is present but no effectiveDate is present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers calculating the time when the change will take effect If syncCache object and effectiveDate are present the platform will use a synchronized cache strategy to distribute the information to the different active platform servers setting the passed value as the datetime when the change will take effect |
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/radiusClients/radiusClient_1?syncCache&effectiveDate=2014-05-28T15:20:51Z
Rules
A rule is mainly composed of conditions and actions. When you defined a rule, you can define a rule type, which determines the structure of the rule. There are three types of rules:
-
DATASTREAM: This type of rule would be evaluated if you collected data in the South API
-
OPERATION: This type of rule would be evaluated if an operation were execute in Opengate platform.
-
EVENT: This type of rule would be evaluated if an event were sent to Opengate platform.
You can see the default list of rules in the Rules Catalog section |
Configure datastream and parameters in rule
Datastreams and parameters value can be used inside rule configuration, for example in condition and some attributes in rule actions, following the same way:
-
datastream: $datastream:<id_datastream>
-
parameter: $parameter:<id_parameter>
Example:
-
datastream: $datastream:device.identifier._current.value
-
parameter: $parameter:threshold
You can see more examples in several objects below
Rule object structure
Object / attribute(* required) | Description |
---|---|
identifier |
An identifier which will be generated by the platform. |
organizationId |
Organization where rule belongs. |
channelId |
Channel where rule belongs. |
name* |
Name which will be unique for every channel. It could be changed. |
mode* |
Declare EASY for easy conditions and actions. Declare ADVANCED if you need an specific configuration for the rule. |
description |
Description of the rule. This field is optional. |
type* |
|
active |
Optional boolean value which define if a rule have to be evaluated or not. False by default. |
parameters |
|
condition |
Mandatory for EASY mode and not applicable for ADVANCED mode. JSON filter which follows the same filter structure of the Opengate platform. It can contain rule parameters. |
actions |
|
actionsDelay |
Optional value in miliseconds to evaluate the rule after this time. |
javascript |
Mandatory for ADVANCED rules. If not empty in EASY rule, its contain will be ignored. |
Rule type object structure
Object / attribute(* required) | Description |
---|---|
name* |
DATASTREAM/OPERATION/EVENT |
datastreams |
Object with datastreams and its value, only for DATASTREAM name type. |
operationName |
Name of the operation which you want the rule to evaluate |
eventName |
Name of the event which you want the rule to evaluate |
Parameters object structure
Object / attribute(* required) | Description |
---|---|
name* |
Name of the param. |
value* |
Value of the param. |
schema* |
Type of the param. |
description |
Optional description for the param |
Rule Actions object structure
If rule mode is easy, you must defined at least one action.
Object / attribute(* required) | Description |
---|---|
open |
|
close |
|
sendTrap |
|
sendEmail |
|
sendHttp |
|
operation |
|
cancelDelay |
Rule Open Action object structure
Object / attribute(* required) | Description |
---|---|
enabled |
Defined true if you want the action to be enabled. False by default. |
name |
Mandatory only if attribute enable is true. Name of the alarm to be opened. |
severity |
Mandatory only if attribute enable is true. INFORMATIVE/URGENT/CRITICAL. |
priority |
Mandatory only if attribute enable is true. LOW/MEDIUM/HIGH. |
description |
Optional description for the alarm. |
subEntityDatastreamId |
Optional value if you want to open an alarm for a sub-entity or other entity(subscription/subscriber/asset). Here you can use datastream values as explained above. e.g. "$datastream:provision.device.communicationModules[].subscriber.identifier._current.value" |
Rule Close Action object structure
Object / attribute | Description |
---|---|
enabled |
Defined true if you want the action to be enabled. False by default. |
alarmToClose |
Close alarm by alarm name. |
ruleToClose |
Close alarm by rule name. |
subEntityDatastreamId |
Optional value if you want to close an alarm for a sub-entity or other entity(subscription/subscriber/asset). Here you can use datastream values as explained above. e.g. "$datastream:provision.device.communicationModules[].subscriber.identifier._current.value" |
alarmToClose and ruleToClose are both optional values, but at least one of them must be defined. |
Rule Send Trap Action object structure
Object / attribute(* required) | Description |
---|---|
enabled |
Defined true if you want the action to be enabled. False by default. |
name* |
Name of the trap. |
trapOID* |
TrapOID for the trap. |
enterpriseOID* |
EnterpriseOID for the trap. |
recipients* |
Array with object which contains ip and port of the recipients. |
variables |
Optional variables for sending the trap. It can contain rule parameters. Here you can use datastream values as explained above. e.g. "variables": [{"1.1.1": "$datastream: provision.administration.organization._current.value"}] |
Rule Send Email Action object structure
Object / attribute(* required) | Description |
---|---|
enabled |
Defined true if you want the action to be enabled. False by default. |
name* |
Name of the email. |
subject |
Subject of the email |
template |
Template for the email. It can contain rule parameters. Here you can use datastream values as explained above. e.g. <b>EntityID:</b>{{$datastream:provision.device.identifier._current.value}} |
recipients* |
Array of string with valid emails. |
Rule Send Http Action object structure
Object / attribute(* required) | Description |
---|---|
enabled |
Defined true if you want the action to be enabled. False by default. |
name |
Mandatory only if attribute enable is true. Name of the notification. |
url |
Mandatory only if attribute enable is true. Must have a valid url format. |
method |
Mandatory only if attribute enable is true. Value must be GET/POST/PUT/DELETE. |
headers |
Optional map with key and value. e.g. {"Connection":"keep-alive"} |
queryParams |
Optional map with key and value. e.g. {"flattened":"true"} |
body |
Mandatory when method is POST/PUT. Forbidden when GET/DELETE. |
Rule Operation Action object structure
Object / attribute(* required) | Description |
---|---|
enabled |
Defined true if you want the action to be enabled. False by default. |
name* |
Name of the operation. |
timeout |
Timeout for the operation in miliseconds. 60000ms by default |
parameters |
Specific parameters for each operation. |
jobUser |
User Api-Key. If empty, this value will be filled with user’s Api-Key who creates the rule. |
retries |
Retries for the operation. |
ackTimeout |
Acktimeout for the operation in miliseconds. |
retriesDelay |
Delay between retries. |
Currently, operation name is not been validating with operation catalog. This validation is in our ROAD MAP and would be included soon. Until then, please review operation catalog in order to configure rules properly. An operation with a bad configuration will not be executed by the platform. |
Rule Cancel Delay Action object structure
Object / attribute(* required) | Description |
---|---|
name* |
Name of the rule which will be cancel before its delay. |
Creating a rule
POST /north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}
New rules can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "name": "rule_name", "mode": "EASY", "description": "rule description", "active": true, "type": { "name": "DATASTREAM", "datastreams": [ { "name": "<datastream_name>", "fields": [ { "field": "value", "alias": "description for the field" } ], "prefilter": true } ] }, "condition": { "filter": { "and": [ { "lte": { "<datastream_name>._current.value": "$parameter:threshold" } }, { "gt": { "<datastream_name>._previous.value": "$parameter:threshold" } } ] } }, "parameters": [ { "name": "threshold", "value": 5, "schema": "integer" } ], "actionsDelay": 18000, "actions": { "open": [ { "enabled": true, "name": "rule_name", "severity": "URGENT", "priority": "MEDIUM", "description": "description for open action" } ] } }
{ "mode": "EASY", "name": "rule_name", "description": "rule description", "type": { "name": "OPERATION", "operationName": "REFRESH_INFO" }, "active": true, "condition": { "filter": { "and": [ { "eq": { "operation.error": true } } ] } }, "actions": { "open": [ { "enabled": true, "name": "rule_name", "severity": "URGENT", "priority": "HIGH", "description": "open action description" } ], "close": [ { "enabled": true, "ruleToClose": "rule_name" } ], "sendTrap": [ { "enabled": true, "name": "send trap action", "trapOID": "1.100.6", "recipients": [ { "ip": "172.19.18.95", "port": 8080 } ], "variables": [ { "1.1.1": "$datastream: operation.state" }, { "1.1.2": "$datastream: operation.name" }, { "1.1.3": "$datastream: operation.result" }, { "1.1.4": "$datastream: provision.administration.identifier._current.value" } ] } ] } }
{ "mode": "EASY", "name": "rule_name", "description": "rule description", "active": true, "type": { "name": "EVENT", "eventName": "event_name" }, "condition": { "filter": { "and": [ { "eq": { "event.name": "event_name" } } ] } }, "actions": { "open": [ { "enabled": true, "name": "alarm_name", "severity": "URGENT", "priority": "MEDIUM", "description": "alarm description" } ], "close": [ { "enabled": true, "ruleToClose": "rule_name" } ] } }
This is the request using curl:
curl --request POST \ --data-binary @rule.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/rules/provision/organizations/{organizationName}/channels/{channelName} \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created rule. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/rules/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{rule_uuid}
Reading a rule
GET /north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier}
You can apply for the rule sending a GET request using the URL above. You must replace {identifier}
with the identifier of the rule you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier}
The response body could be something like this:
{ "mode": "EASY", "name": "rule_name", "organizationId": "organizationName", "channelId": "channelName", "identifier": "{rule_identifier}", "description": "rule description", "active": true, "type": { "name": "EVENT", "eventName": "event_name" }, "condition": { "filter": { "and": [ { "eq": { "event.name": "event_name" } } ] } }, "actions": { "open": [ { "enabled": true, "name": "alarm_name", "severity": "URGENT", "priority": "MEDIUM", "description": "alarm description" } ], "close": [ { "enabled": true, "ruleToClose": "rule_name" } ] } }
Updating a rule
PUT /north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier}
It is allowed updating all the fields, following same validations as POST request, except identifier, organization and channel. Besides, an ADVANCED rule can not be changed to EASY mode. |
This is the request using curl:
curl --request PUT \ --data-binary @rules.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier} \ -H "Content-type: application/json"
Updating parameters of a rule
PUT /north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier}/parameters
You can update only rules parameters by sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the rule you want to delete.
[ { "name": "threshold", "value": 5, "schema": "integer" } ]
This is the request using curl:
curl --request PUT \ --data-binary @rules.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier}/parameters \ -H "Content-type: application/json"
Deleting a rule
DELETE /north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier}
You can delete rules by sending a DELETE request using the URL above. You must replace {identifier}
with the identifier of the rule you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/rules/provision/organizations/{organizationName}/channels/{channelName}/{identifier}
Subscribers
Subscriber object structure
Subscriber entity store information regarding a specific communication channel. It can exist in asolation or inside the device. It contains the following attributes:
Parameter | Description |
---|---|
resourceType |
It indicates to which type of entity is allowed a datamodel. It is a reading parameter. The user do not need to add this value, the platform assigns internally the value subscriber |
provision |
Object / attribute | Description |
---|---|
administration |
|
device |
The resourceType field defines that the resource is a subscriber. This field is internal, it is returned in the reading request, but it shouldn’t be showed. This field is useful when the user wants all the entities (devices, subscriptions, subscribers and assets) and needs to know the type. It is added by compatibility with the entity functionality. |
Customer provision fields can be defined by the user creating new datamodels that define parameters with using "provision.custom." prefix in the parameter Id. |
Creating a subscriber
POST /north/v80/provision/organizations/{organizationName}/subscribers
New subscribers can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
It is not necessary to add a organization field in the json because this field is in the URL |
Here’s how to create a subscriber with the minium and recommeded fields
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "communicationModules": [ { "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } } } } ] } } }
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "communicationModules": [ { "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "name": { "_current": { "value": "subscriber_battery_name" } }, "description": { "_current": { "value": "subscriber_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "SIM" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc" } } } } } ] } } }
By default the new entity will be associated to the organization indicated by the URL as long as the organization to which the used API_KEY belongs to or to an organization associated to a subdomain. |
Using curl to perform the request:
curl --request POST \ --data-binary @subscriber.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created subscriber. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id
POST /north/v80/provision/organizations/{organizationName}/subscribers?flattened=true
It is possible to create a subscriber with a flattened format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to send a flattened json format
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.communicationModules[].subscriber.identifier": [ { "_value": { "_current": { "value": "subscriber_battery" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_value": { "_current": { "value": "subscriber_battery_name" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_value": { "_current": { "value": "subscriber_battery_description" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_value": { "_current": { "value": "SIM" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_value": { "_current": { "value": "subscriber_battery_icc" } } } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @FlattenedSubscriber.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers?flattened=true \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created subscriber. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id
Reading a subscriber
GET /north/v80/provision/organizations/{organizationName}/subscribers/{identifier}
You can apply for a subscriber sending a GET request using the URL above. You must replace {identifier}
with the identifier of the subscriber you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/subscribers/subscriber_battery_id
The response body could be something like this:
{ "resourceType": { "_current": { "value": "entity.subscriber" } }, "provision": { "administration": { "identifier": { "_current": { "value": "device_battery", "provType": "MONITORING", "date": "2017-09-25T09:34:32.219Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-09-25T09:34:32.216Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-09-25T09:34:32.211Z" } } }, "device": { "communicationModules": [ { "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.151Z" } } } } ] } } }
GET /north/v80/provision/organizations/{organizationName}/subscribers/{identifier}?flattened=true
You can apply for a subscriber with flattened format(see flattened concept) sending a GET request using the URL above. You must replace {identifier}
with the identifier of the subscriber you want to retrieve. Also,it is sent a boolean parameter, flattened, to allow to receive a flattened json format
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id?flattened=true
And this is the response body:
{ "resourceType": { "_value": { "_current": { "value": "entity.subscriber" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "device_battery", "provType": "MONITORING", "date": "2017-09-25T09:34:32.219Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-09-25T09:34:32.216Z" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-09-25T09:34:32.211Z" } } }, "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.151Z" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.158Z" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32.162Z" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.131Z" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-09-25T09:34:32.143Z" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-09-25T09:34:32.148Z" } } } ] }
Updating a subscriber
PUT /north/v80/provision/organizations/{organizationName}/subscribers/{identifier}
You can update a subscriber sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the subscriber you want to update.
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "communicationModules": [ { "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id" } }, "name": { "_current": { "value": "subscriber_battery_name" } }, "description": { "_current": { "value": "subscriber_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "SIM" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc" } } } } } ] } } }
This is the request using curl:
curl --request PUT \ --data-binary @subscribers.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id \ -H "Content-type: application/json"
PUT /north/v80/provision/organizations/{organizationName}/subscribers/{identifier}?flattened=true
You can update a subscriber with a flattened format (see flattened concept) sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to update. Also, it is sent a boolean parameter, flattened, to allow to send a flattened json format
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.communicationModules[].subscriber.identifier": [ { "_value": { "_current": { "value": "subscriber_battery" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_value": { "_current": { "value": "subscriber_battery_name" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_value": { "_current": { "value": "subscriber_battery_description" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_value": { "_current": { "value": "SIM" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_value": { "_current": { "value": "subscriber_battery_icc" } } } ] }
Using curl to perform the request:
curl --request PUT \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id?flattened=true \ -H "Content-type: application/json"
Patching a subscriber
PATCH /north/v80/provision/organizations/{organizationName}/subscribers/{identifier}
You can patch a subscriber sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the subscriber you want to update.
Administration channel value is mandatory in patch operation for securization purposes. |
When patching complex object values, non passed object attributes will be patched as non existent, so include previous unchanged values if you don’t want to loose them. |
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } } }, "device": { "communicationModules": [ { "subscriber": { "description": { "_current": { "value": "subscriber_battery_description patched" } } } } ] } } }
This is the request using curl:
curl --request PATCH \ --data-binary @subscribers.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id \ -H "Content-type: application/json"
PATCH /north/v80/provision/organizations/{organizationName}/subscribers/{identifier}?flattened=true
You can patch a subscriber with a flattened format (see flattened concept) sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to patch. Also, it is sent a boolean parameter, flattened, to allow sending with a flattened json format
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.device.communicationModules[].subscriber.description": [ { "_value": { "_current": { "value": "subscriber_battery_description patched" } } } ] }
Using curl to perform the request:
curl --request PATCH \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id?flattened=true \ -H "Content-type: application/json"
Deleting a subscriber
DELETE /north/v80/provision/organizations/{organizationName}/subscribers/{identifier}
You can delete a subscriber sending a DELETE request using the URL above. You must replace {identifier}
with the identifier of the subscriber you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscribers/subscriber_battery_id
Subscriptions
Subscription object structure
A subscription stores information regarding the contracts with your communication operators. It can exist in asolation or inside the device. It contains the following attributes:
Parameter | Description |
---|---|
resourceType |
It indicates to which type of entity is allowed a datamodel. It is a reading parameter. The user do not need to add this value, the platform assigns internally the value subscription |
provision |
Object / attribute | Description |
---|---|
administration |
|
device |
The resourceType field defines that the resource is a subscription. This field is internal, it is returned in the reading request, but it shouldn’t be showed. This field is useful when the user wants all the entities (devices, subscriptions, subscribers and assets) and needs to know the type. It is added by compatibility with the entity functionality. |
Customer provision fields can be defined by the user creating new datamodels that define parameters with using "provision.custom." prefix in the parameter Id. |
Creating a subscription
POST /north/v80/provision/organizations/{organizationName}/subscriptions
New subscriptions can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
It is not necessary to add a organization field in the json because this field is in the URL |
Here’s how to create a subscription with the minium and recommeded fields
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } } } } ] } } }
{ "provision": { "administration": { "channel": { "_current": { "value": "Channel_battery" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "name": { "_current": { "value": "subscription_battery_name" } }, "description": { "_current": { "value": "subscription_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "MOBILE" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi" } }, "msisdn": { "_current": { "value": "34969220026" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } } } } } ] } } }
By default the new entity will be associated to the organization indicated by the URL as long as the organization to which the used API_KEY belongs to or to an organization associated to a subdomain. |
Only can be used value of "apn" previously provisioned in the platform |
Only can be used value of "Operator" previously provisioned in the platform |
This is the request using curl:
curl --request POST \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created subscription. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id
POST /north/v80/provision/organizations/{organizationName}/subscriptions?flattened=true
It is possible to create a subscription with a flattened format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to send a flattened json format
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.communicationModules[].subscription.identifier": [ { "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_value": { "_current": { "value": "subscription_battery_name" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_value": { "_current": { "value": "subscription_battery_description" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_value": { "_current": { "value": "MOBILE" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_value": { "_current": { "value": "subscription_battery_imsi" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_value": { "_current": { "value": "34969220026" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ] }
Using curl to perform the request:
curl --request POST \ --data-binary @FlattenedSubscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions?flattened=true \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created subscription. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id
Reading a subscription
GET /north/v80/provision/organizations/{organizationName}/subscriptions/{identifier}
You can apply for a subscription sending a GET request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id
The response body could be something like this:
{ "resourceType": { "_current": { "value": "entity.subscription" } }, "provision": { "administration": { "identifier": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.219Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-09-25T09:34:32.216Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-09-25T09:34:32.211Z" } } }, "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.083Z" } } } } ] } } }
GET /north/v80/provision/organizations/{organizationName}/subscriptions/{identifier}?flattened=true
You can apply for a subscription with flattened format (see flattened concept) sending a GET request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to retrieve. Also,it is sent a boolean parameter, flattened, to allow to receive a flattened json format.
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id?flattened=true
And this is the response body:
{ "resourceType": { "_value": { "_current": { "value": "entity.subscription" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "device_battery", "provType": "MONITORING", "date": "2017-09-25T09:34:32.219Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-09-25T09:34:32.216Z" } } }, "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-09-25T09:34:32.208Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-09-25T09:34:32.211Z" } } }, "provision.device.communicationModules[].identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.119Z" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-09-25T09:34:32.083Z" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-09-25T09:34:32.079Z" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-09-25T09:34:32.073Z" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.031Z" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-09-25T09:34:32.013Z" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-09-25T09:34:32.041Z" } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-09-25T09:34:32.059Z" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-09-25T09:34:32.049Z" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-09-25T09:34:32.055Z" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-09-25T09:34:32.052Z" } } } ] }
Updating a subscription
PUT /north/v80/provision/organizations/{organizationName}/subscriptions/{identifier}
You can update a subscription sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to update.
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "Channel_battery" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup" } } }, "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "value": "subscription_battery_id" } }, "name": { "_current": { "value": "subscription_battery_name" } }, "description": { "_current": { "value": "subscription_battery_description" } }, "administrativeState": { "_current": { "value": "ACTIVE" } }, "specificType": { "_current": { "value": "MOBILE" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi" } }, "msisdn": { "_current": { "value": "34969220026" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU" } } } } } ] } } }
This is the request using curl:
curl --request PUT \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id \ -H "Content-type: application/json"
PUT /north/v80/provision/organizations/{organizationName}/subscriptions/{identifier}?flattened=true
You can update a subscription with a flattened format (see flattened concept) sending a PUT request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to update. Also, it is sent a boolean parameter, flattened, to allow to send a flattened json format
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup" } } }, "provision.device.communicationModules[].subscription.identifier": [ { "_value": { "_current": { "value": "subscription_battery_id" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_value": { "_current": { "value": "subscription_battery_name" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_value": { "_current": { "value": "subscription_battery_description" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_value": { "_current": { "value": "ACTIVE" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_value": { "_current": { "value": "MOBILE" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" } } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_value": { "_current": { "value": "subscription_battery_imsi" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_value": { "_current": { "value": "34969220026" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_value": { "_current": { "value": "Telefónica Móviles España, SAU" } } } ] }
Using curl to perform the request:
curl --request PUT \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id?flattened=true \ -H "Content-type: application/json"
Patching a subscription
PATCH /north/v80/provision/organizations/{organizationName}/subscriptions/{identifier}
You can patch a subscription sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to update.
Administration channel value is mandatory in patch operation for securization purposes. |
When patching complex object values, non passed object attributes will be patched as non existent, so include previous unchanged values if you don’t want to loose them. |
The JSON object passed could be something like this:
{ "provision": { "administration": { "channel": { "_current": { "value": "battery_channel" } } }, "device": { "communicationModules": [ { "subscription": { "description": { "_current": { "value": "subscription_battery_description patched" } } } } ] } } }
This is the request using curl:
curl --request PATCH \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id \ -H "Content-type: application/json"
PATCH /north/v80/provision/organizations/{organizationName}/subscriptions/{identifier}?flattened=true
You can patch a subscription with a flattened format (see flattened concept) sending a PATCH request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to patch. Also, it is sent a boolean parameter, flattened, to allow sending with a flattened json format
The JSON object passed could be something like this:
{ "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.device.communicationModules[].subscription.description": [ { "_value": { "_current": { "value": "subscription_battery_description patched" } } } ] }
Using curl to perform the request:
curl --request PATCH \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id?flattened=true \ -H "Content-type: application/json"
Deleting a subscription
DELETE /north/v80/provision/organizations/{organizationName}/subscriptions/{identifier}
You can delete a subscription sending a DELETE request using the URL above. You must replace {identifier}
with the identifier of the subscription you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/subscriptions/subscription_battery_id
Tags (Entity tagging)
Some times you want to execute the same operation on thousand of devices at the same time. But, how you can select all the target devices? Tags are the answer to that question.
You can tag all the devices, and other entities, you want and then execute an operation using the tag as target. Let’s see how to create tags and how to stick them over the OpenGate entities using the provisioning API.
You can learn about the use of tags in the operations section.
Tag objects
Tag structure
Tags are powerful, but they are very simple entities. A tag consists of a name only and the entity id.
attribute (* required) | Description |
---|---|
name |
string with the name you want as a label for your entities. |
owner |
Select one of these choices:
|
target |
See Tag Target Object |
attribute (* required) | Description |
---|---|
append |
|
remove |
|
filter |
A filter object can be used (See search filter section). When this option is applied, the previous list of entities included in the tag are removed and the tag is filled with the result of the filter. |
attribute (* required) | Description |
---|---|
entities |
Contains the array of entities to be appended or deleted |
tags |
Contains the array of tags to be appended or deleted, see tag clone target object |
attribute (* required) | Description |
---|---|
name |
Name of the tag that you can clone |
owner |
Name of the owner of the tag |
filter object cannot be used at the same time that append & remove objects. |
append & remove objects can be used simultaneously in the same request and you can mix entities and tags |
If a specific type of entities needs to be included in the tag, it can be used entityType filter field. |
Tag response structure
attribute (* required) | Description |
---|---|
name |
string with the name you want as a label for your entities. |
result |
see result object below |
attribute (* required) | Description |
---|---|
count |
number of processed entities |
successful |
number of entities that have been processed with success |
error |
see error object below |
attribute (* required) | Description |
---|---|
notExist |
see error summary below |
attribute (* required) | Description |
---|---|
count |
number of occurrences of this error |
list |
string array of the entity identifiers that have produced the error |
attribute (* required) | Description |
---|---|
count |
number of occurrences of this error |
tag |
Contains the list of erroneous tags, see tag clone target object |
Tag ownership
Regarding to the API user, the platform implements different ownership of a tag:
-
User ownership: The tag can only be viewed and managed by the user who created it
-
Workgroup ownership: The tag can be viewed and managed by all user in the same workgroup that the user who created it
Creating a tag
POST /north/v80/provision/tags
New tags can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
There are three alternatives to include entities a tag:
-
Choose a specific list of entities
-
Using a filter to select the entities. The creation operation takes an snapshot in the moment of the execution
There is an optional parameter for this alternative "?entityType". This parameter restrict the filter to an specific type of entity, If you include this parameter in the Uri of the request only the entities belonging to the selected type will be considered. The available values for this parameter are (in uppercase):
|
-
Using a previous created tag.
By operational issues, the service incorporates a limit in the array size of the JSON file. This limit can be configured administratively and by default the limit is set to 5.000 elements in the array. Please consult with your administrator to know the limit configured. |
Is you need to launch a operation over a large list of entities you can use updating operation (PUT) to append new entities to the target considering the mentioned limit. |
A user will not be able to include in the created label, the entities that are not in the "workgroup" that the user belongs |
{ "tag" : { "name" : "tag_1", "owner" : "user", "target": { "append" : { "entities" : [ "device_1", "device_2" ] } } } }
{ "tag" : { "name" : "tag_1", "owner" : "workgroup", "target": { "append" : { "entities" : [ "device_1", "device_2" ] } } } }
{ "tag" : { "name" : "tag_1", "owner" : "user", "target" : { "filter": { "and": [ { "like": { "collected.entityName": "device_name" } }, { "or": [ { "like": { "collected.serialNumber": "82A75D494B0EBF7A95587285AE78E83F" } }, { "like": { "collected.serialNumber": "08D83B1864A1F9CFED76DAF426EB04D7" } } ] } ] } } } }
{ "tag": { "name": "tag_1", "owner": "user", "target": { "append": { "entities": [], "tags": [ { "name": "label_1", "owner": "user" } ] }, "remove": { "entities": [] } } } }
In the creation process owner is the "owner" of the tags that you want to clone. |
curl --request POST \ --data-binary @tag.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/tags \ -H "Content-type: application/json"
Example or requests with parameter entityType
curl --request POST \ --data-binary @tag.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/tags?entityType=GATEWAY \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) a location header which tells us the location (including the assigned id) of the newly created tag and a JSON file with the response to the operation. Lets look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/tags/tag_1
{ "tag" : { "name" : "tag_1", "result": { "count": 3, "successful": 1, "error": { "notExist" : { "count": 2, "list": [ "device_1", "device_2" ] } } } } }
{ "tag": { "name": "tag_clone_5bis", "result": { "count": 2, "successful": 0, "error": { "notExist": { "count": 2, "tags": [ { "name": "tag_clone_3", "owner": "workgroup" }, { "name": "tag_clone_3", "owner": "user" } ] } } } } }
Reading a tag
GET /north/v80/provision/tags/{id}?owner={owner}You can apply for a tag sending a GET request using the URL above. You must replace {id}
with the identifier of the tag and the owner URL parameter you want to retrieve. This is the request using curl:
If owner parameter is not passed, owner takes by default the value "user" |
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/tags/tag_1?owner=user
The response body could be something like this:
{ "tag" : { "name" : "tag_1", "owner" : "user" } }
Reading Entities in a tag
GET /north/v80/provision/tags/{id}/entities?owner={owner}&start={start}&size={size}
You can retrieve a paginated result list with the entities, simply sending a GET request using the URL above. You must replace {id}
with the identifier of the tag and the owner URL parameter you want to retrieve. The result list have an array of operation objects
If owner parameter is not passed, owner takes by default the value "user" |
Attributes | Constraints | Description |
---|---|---|
page |
See Page Object |
Paging fields |
entities[] |
array of string |
List of entities in the tag |
{ "page": { "number": 1, "of": 50 }, "entities" : [ "device_1", "device_2", "device_3", "device_4", "device_n" ] }
Updating a tag
PUT /north/v80/provision/tags/{id}?owner={owner}
You can update a tag by sending a PUT request using the URL above. You must replace {id}
with the identifier of the tag and the owner URL parameter you want to update. This is the request using curl:
If owner parameter is not passed, owner takes by default the value "user" |
curl --request PUT \ --data-binary @tag.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/tags/tag_1?owner=user \ -H "Content-type: application/json"
{ "tag" : { "name" : "tag_1", "owner" : "workgroup", "target": { "append" : { "entities" : [ "device_1", "device_2" ] }, "remove" : { "entities" : [ "device_3" ] } } } }
In the response we should see a status code of 200 (created) and a JSON file with the response to the operation (Same than creating operation)
Deleting a tag
DELETE /north/v80/provision/tags/{id}?owner={owner}
You can delete a tag sending a DELETE request using the URL above. You must replace {id}
with the identifier of the tag and the owner URL parameter you want to delete. This is the request using curl.
If owner parameter is not passed, owner takes by default the value "user" |
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/tags/tag_1?owner=user
Tickets
A ticket is a resource type of the platform. It allows you to register and track on Field Deployments, incidents or requests (required needs).
Ticket object structure
The ticket contains the following attributes:
Object / attribute | Type | Mandatory | Description |
---|---|---|---|
identifier |
No |
Identifier of the ticket. It is generated by the platform |
|
name |
string |
Yes |
Name of the ticket |
description |
string |
No |
Description of the ticket |
label |
No |
Labels possibles to assign to ticket |
|
reporter |
Yes |
Entity that reports a ticket |
|
owner |
string |
No |
Platform user that create the ticket. It is assigned by the platform |
assignee |
No |
Entity that is assigned a ticket |
|
section |
string |
No |
Component on which the installation or work order is being made |
entity |
No |
Entity that is associated a ticket |
|
type |
Yes |
Type of the ticket |
|
severity |
Yes |
Severity of the ticket |
|
priority |
Yes |
Priority of the ticket |
|
status |
Yes |
Actual status of the ticket |
|
specificType |
No |
Concrete type of the ticket |
|
reporterDate |
Yes |
Date a ticket is reported |
|
creationDate |
No |
Date a ticket is created. It is generated by the platform with the system date when is created |
|
assignedDate |
No |
Date a ticket is assigned. It is generated by the platform with the system date when the ticket changes its status to assigned |
|
answeredDate |
No |
Date a ticket is answered. It is generated by the platform with the system date when the ticket changes its status to answered |
|
updatedDate |
No |
Date a ticket is updated. It is generated by the platform with the system date when the ticket changes its status to updated |
|
restorationDate |
No |
Date a ticket is restoration. It is generated by the platform with the system date when the ticket changes its status to restored |
|
resolutionDate |
No |
Date a ticket is resolution. It is generated by the platform with the system date when the ticket changes its status to resolved |
|
closedDate |
No |
Date a ticket is closed. It is generated by the platform with the system date when the ticket changes its status to closed |
Creating a ticket
POST /north/v80/provision/organizations/{organizationName}/tickets
New tickets can be created by sending a POST request to the above defined, including a correctly formatted JSON document in the POST body.
Here’s how to create a ticket with the minimum and recommended fields
{ "provision": { "administration": { "organization": { "_current": { "value": "YOUR_ORGANIZATION_NAME" } } }, "ticket": { "name": { "_current": { "value": "ticket1" } }, "type": { "_current": { "value": "WORKORDER" } }, "severity": { "_current": { "value": "CRITICAL" } }, "priority": { "_current": { "value": "MAJOR" } }, "reporter": { "_current": { "value": "entity_1" } }, "status": { "_current": { "value": "CREATED" } }, "reporterDate": { "_current": { "value": "2017-12-15T11:06:29.179Z" } } } } }
{ "provision": { "administration": { "organization": { "_current": { "value": "YOUR_ORGANIZATION_NAME" } } }, "ticket": { "name": { "_current": { "value": "ticket1" } }, "description": { "_current": { "value": "ticket1 description" } }, "label": { "_current": { "value": [ "tag1", "tag2" ] } }, "type": { "_current": { "value": "WORKORDER" } }, "severity": { "_current": { "value": "CRITICAL" } }, "priority": { "_current": { "value": "MAJOR" } }, "reporter": { "_current": { "value": "entity_1" } }, "assignee": { "_current": { "value": "entity_2" } }, "status": { "_current": { "value": "CREATED" } }, "specificType": { "_current": { "value": "INSTALLATION" } }, "section": { "_current": { "value": "component1" } }, "entity": { "_current": { "value": "deviceId_1" } }, "reporterDate": { "_current": { "value": "2017-12-15T11:06:29.179Z" } } } } }
Internally, the platform assign the following fields and they can’t be modifiable:
|
You must replace {organizationName}
with the name of the organization where you want to create the ticket. This is the request using curl:
curl --request POST \ --data-binary @ticket.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/tickets \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created ticket. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/tickets/c96d0905-4a6e-4b21-97ce-1e89dd8f60c2
POST /north/v80/provision/organizations/{organizationName}/tickets?flattened=true
It is possible to create a ticket with a flattened format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to send a flattened json format.
Here’s how to create a ticket with flattened format
{ "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization" } } }, "provision.ticket.name": { "_value": { "_current": { "value": "ticket2" } } }, "provision.ticket.type": { "_value": { "_current": { "value": "WORKORDER" } } }, "provision.ticket.severity": { "_value": { "_current": { "value": "CRITICAL" } } }, "provision.ticket.priority": { "_value": { "_current": { "value": "MAJOR" } } }, "provision.ticket.reporter": { "_value": { "_current": { "value": "10000003J" } } }, "provision.ticket.status": { "_value": { "_current": { "value": "CREATED" } } }, "provision.ticket.reporterDate": { "_value": { "_current": { "value": "2017-12-15T11:06:29.179Z" } } } }
Reading a ticket
GET /north/v80/provision/organizations/{organizationName}/tickets/{ticketIdentifier}
You can apply for the ticket sending a GET request using the URL above. You must replace {organizationName}
with the name of the organization where you have created the ticket and {ticketIdentifier}
with the identifier of the ticket you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/tickets/78e278ac-8150-40df-8e7e-f42a5841c54f
The response body could be something like this:
{ "resourceType": { "_current": { "value": "ticket", "provType": "IDENTIFIER", "date": "2018-04-09T14:18:58.282Z" } }, "provision": { "ticket": { "identifier": { "_current": { "value": "78e278ac-8150-40df-8e7e-f42a5841c54f", "provType": "MONITORING", "date": "2018-04-09T16:21:00.714Z" } }, "entity": { "_current": { "value": "1039018", "provType": "MONITORING", "date": "2018-04-09T16:21:00.722Z" } }, "updatedDate": { "_current": { "value": "2018-04-09T16:21:00.845Z", "provType": "MONITORING", "date": "2018-04-09T16:21:00.845Z" } }, "severity": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2018-04-09T16:21:00.711Z" } }, "assignee": { "_current": { "value": "10000001J", "provType": "MONITORING", "date": "2018-04-09T16:21:00.702Z" } }, "specificType": { "_current": { "value": "INSTALLATION", "provType": "MONITORING", "date": "2018-04-09T16:21:00.713Z" } }, "description": { "_current": { "value": "Deployment", "provType": "MONITORING", "date": "2018-04-09T16:21:00.715Z" } }, "reporter": { "_current": { "value": "10000001J", "provType": "MONITORING", "date": "2018-04-09T16:21:00.709Z" } }, "owner": { "_current": { "value": "admin@enel.com", "provType": "MONITORING", "date": "2018-04-09T16:21:00.845Z" } }, "creationDate": { "_current": { "value": "2018-04-09T14:18:58.282Z", "provType": "MONITORING", "date": "2018-04-09T14:18:58.282Z" } }, "name": { "_current": { "value": "On field deployment", "provType": "MONITORING", "date": "2018-04-09T16:21:00.724Z" } }, "status": { "_current": { "value": "CREATED", "provType": "MONITORING", "date": "2018-04-09T16:21:00.725Z" } }, "priority": { "_current": { "value": "MAJOR", "provType": "MONITORING", "date": "2018-04-09T16:21:00.710Z" } }, "type": { "_current": { "value": "WORKORDER", "provType": "MONITORING", "date": "2018-04-09T16:21:00.712Z" } }, "label": { "_current": { "provType": "MONITORING", "date": "2018-04-09T16:21:00.723Z" } } }, "administration": { "identifier": { "_current": { "value": "78e278ac-8150-40df-8e7e-f42a5841c54f", "provType": "MONITORING", "date": "2018-04-09T16:21:00.727Z" } }, "organization": { "_current": { "value": "spain", "provType": "MONITORING", "date": "2018-04-09T16:21:00.726Z" } } } } }
Updating a Ticket
PUT /north/v80/provision/organizations/{organizationName}/tickets/{ticketIdentifier}
Existing tickets can be updated by sending a PUT request using the URL above, including a correctly formatted JSON document in the PUT body. You must replace {organizationName}
with the name of the organization where you have created the ticket and {ticketIdentifier}
with the identifier of the ticket you want to retrieve
The following fields can’t be modifiable:
|
The dates will be updated internally by the platform depending on the status of the ticket and they can’t be modifiable:
|
Patching a Ticket
PATCH /north/v80/provision/organizations/{organizationName}/tickets/{ticketIdentifier}
Existing tickets can be patched by sending a PATCH request using the URL above, including a correctly formatted JSON document in the PATCH body containing only the field you want to modify. You must replace {organizationName}
with the name of the organization where you have created the ticket and {ticketIdentifier}
with the identifier of the ticket you want to retrieve
{ "provision": { "ticket": { "description": { "_current": { "value": "ticket1 description patched" } } } } }
The following fields can’t be modifiable:
|
The dates will be patched internally by the platform if the status of the ticket has been patched, and they can’t be modifiable:
|
Deleting a Ticket
DELETE /north/v80/provision/organizations/{organizationName}/tickets/{ticketIdentifier}
You can delete the tickets by sending a DELETE request using the URL above. You must replace {organizationName}
with the name of the organization where you have created the ticket and {ticketIdentifier}
with the identifier of the ticket you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/tickets/78e278ac-8150-40df-8e7e-f42a5841c54f
Users
User entity object structure
User entity represents the users that can access to the platform through Web Interface and this API
Object / attribute | Description |
---|---|
Email and login of the User |
|
password |
Password of the user |
description |
User description |
workgroup |
Workgroup indicating management scope assigned to this user. That is mean the list of entities that the user can manage through the Web and API interfaces |
profile |
User Profile to be applied to the user |
domain |
Administration domain associated to the user |
name |
Name of the User |
surname |
Surname of the User |
countryCode |
Country of the Organization. The content must be in upper case. The codes are ISO CODES defined in https://countrycode.org. This field is optional and if you don’t specify a particular countryCode, one specific will be assigned |
langCode |
Language Code. This field is optional and if you don’t specify a particular langCode, one specific will be assigned |
timezone |
Time zone of the user executing the request. Time Zone is the uniform naming convention, for example "Europe/Paris". See Available time zone. This field is optional and if you don’t specify a particular timezone, one specific will be assigned |
Creating an User
POST /north/v80/provision/users
New users can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "user": { "email": "example2@email.com", "password": "password", "description": "description", "workgroup": "workgroup_1", "domain": "domain_1", "profile": "admin", "name": "user name", "surname": "user surname", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Madrid" } }
Using curl to perform the request, you can create a user sending a POST request using this URL template: https://[your_opengate_address]/north/v80/provision/users
curl --request POST \ --data-binary @user.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/provision/users \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created user. Let’s look the response.
HTTP/1.1 201 Created Location: https://[your_opengate_address]/north/v80/provision/users/example2@email.com
Reading an User
GET /north/v80/provision/users/{id}
You can apply for the entity by sending a GET request using the URL above. You must replace {id}
with the email of the user you want to retrieve.
In function of the header, the response body can be different.
If the apiKey is in the header of the request:
curl --request GET \ --header "X-Apikey: YOUR_API_KEY_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/provision/users/example2@email.com
The response body could be something like this:
{ "user": { "email": "example2@email.com", "description": "description", "workgroup": "workgroup_1", "domain": "domain_1", "profile": "admin", "name": "user name", "surname": "user surname", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Madrid" } }
If the password is in the header of the request:
curl --request GET \ --header "X-ApiPass: YOUR_PASSWORD_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/provision/users/example2@email.com
The response body includes the apikey field and it could be something like this:
{ "user": { "email": "example2@email.com", "description": "description", "apikey": "7974b78a-4f06-42dc-bd89-6eba7e8cbb19", "workgroup": "workgroup_1", "domain": "domain_1", "profile": "admin", "name": "user name", "surname": "user surname", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Madrid" } }
Updating an User
PUT /north/v80/provision/users/{id}
Existing users can be updated by sending a PUT request using the URL above. You must replace {id} with the email of the user you want to update. It is possible to modify the basic user data or change the user password.
If you want to modify only the basic data, this is the request using curl:
curl --request PUT \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/provision/users/example2@email.com
The PUT body could be something like this:
{ "user": { "email": "example2@email.com", "description": "description", "workgroup": "workgroup_1", "domain": "domain_1", "profile": "admin", "name": "user name", "surname": "user surname", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Madrid" } }
If you want to change the user password, this is the request using curl:
curl --request PUT \ --header "X-ApiPass: YOUR_OLD_PASSWORD_HERE" "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/provision/users/example2@email.com
The PUT body could be something like this:
{ "user" : { "password" : "newPassword" } }
This is the request using curl:
curl --request PUT \ --data-binary @user.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/provision/users/{id} \ -H "Content-type: application/json"
Deleting an User
DELETE /north/v80/provision/users/{id}
You can delete the users by sending a DELETE request using the URL above. You must replace {id}
with the the email of the user to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/provision/users/example2@email.com
Workgroups
Workgroup entity object structure
Workgroup entity allows to group different channels to give management permissions to different user roles
Object / attribute | Description |
---|---|
name |
Name of the Workgroup |
description |
Description of the Workgroup |
administrative |
Boolean, if true implies that automatically all the new channel created in the domain’s organizations are assigned to the workgroup, default value is false |
Per each created organization, a domain with the same name is also created automatically by the platform. This organization domain is created to allow to distribute permissions over the resources of this organization. |
Creating a Workgroup
POST /north/v80/provision/domains/{domain_id}/workgroups
New workgroups can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "workgroup": { "name": "workgroup_1", "description": "workgroup description", "administrative": true } }
Using curl to perform the request, you can create a workgroup sending a POST request using this URL template: http://[your_opengate_address]/north/v80/provision/workgroups
curl --request POST \ --data-binary @workgroup.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created entity. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups/workgroup_1
Reading a Workgroup
GET /north/v80/provision/domains/{domain_id}/workgroups/{id}
You can apply for the APN sending a GET request using the URL above. You must replace {id}
with the name of the entity you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups/workgroup_1
The response body could be something like this:
{ "workgroup": { "name": "workgroup_1", "description": "workgroup description", "administrative": true } }
Updating a Workgroup
PUT /north/v80/provision/domains/{domain_id}/workgroups/{id}
You can update a workgroup sending a PUT request using the url above. You must replace {id} with the identifier of the workgroup that you want to update, you can update the fields description or administrative. This is the request using curl:
curl --request PUT \ --data-binary @workgroup.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups/workgroup_1
Deleting a Workgroup
DELETE /north/v80/provision/domains/{domain_id}/workgroups/{id}
You can delete the Organizations by sending a DELETE request using the URL above. You must replace {id}
with the identifier of the entity you want to delete. This is the request using curl.
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups/workgroup_1
Workgroup relations element
What is a Workgroup relations elementEach Workgroup have a list of ids of already provisioned channels. The structure of a Workgroup relations element is:
attribute (*required) | Description |
---|---|
channels* |
list of ids (names) of already provisioned channels |
Adding channels to the Workgroup
POST /north/v80/provision/domains/{domain_id}/workgroups/{workgroup_id}/relations?action=CREATE
You can add channels to an Organization Group by sending a POST request using the URL above. You must replace {workgroup_id}
with the name of the workgroup.
{ "workgroupRelation" : { "channels" : [ { "organization" : "battery_organization", "channel" : "battery_channel" }, { "organization" : "battery_organization", "channel" : "channel_2" } ] } }
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --data-binary @workgroupChannel.json \ --verbose [your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups/{workgroup_id}/relations?action=CREATE \ -H "Content-type: application/json"
In the response we should see a status code of 201 (added). Lets look the response.
HTTP/1.1 201 Added
Reading channels linked to a Workgroup
GET /north/v80/provision/domains/{domain_id}/workgroups/{workgroup_id}/relations
You can get the list of channels linked with an Workgroup by sending a GET request using the URL above. You must replace {organizationName}
and {channel_id}
with the respective identifiers. This is the request using curl.
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups/{workgroup_id}/relations
The response body could be something like this:
{ "workgroupRelation" : { "channels" : [ { "organization" : "battery_organization", "channel" : "battery_channel" }, { "organization" : "battery_organization", "channel" : "channel_2" } ] } }
Removing channels from Workgroup elements
POST /north/v80/provision/domains/{domain_id}/workgroups/{workgroup_id}/relations?action=DELETE
You can delete channels linked to an WorkgGroup by sending a POST request using the URL above. This is the request using curl.
Sending the same request but without attached JSON file the API will delete all relations in this workgroup |
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --data-binary @workgroupChannel.json \ --verbose [your_opengate_address]/north/v80/provision/domains/{domain_id}/workgroups/{workgroup_id}/relations?action=DELETE \ -H "Content-type: application/json"
{ "workgroupRelation" : { "channels" : [ { "organization" : "battery_organization", "channel" : "battery_channel" } ] } }
Search
http://[your_opengate_address]/north/v80/search
The searching API lets you retrieve all provisioned and collected information from the different entities managed and cataloged by the platform
If your business depends on thousands of remote assets which are deployed over a wide area and are connected to networks provided by mobile or other technology operators, then you live in IoT’s hell.
OpenGate comes to rescue you, cooling your production environment and making a lot of work for you refereed to
-
Your business assets like inventory management or automatic collection of valuable information: current location, IP addresses, software version, radio signal strength, etc.
-
Your business information like sensors and machines collected information
Using search API, you can manage many situations in which you need to get information, gathered by OpenGate, about your remote devices:
-
Where is my lost truck?
-
Is connected to Internet my vending machine?
-
What is the software version of this meter gateway which is rebooting all the time?
-
How is the signal strength of this weather station which is off-line most of the time?
-
What is the latests operations and its current status launched over different devices
-
What is the latests raised alarms associated to my in field resources?
-
What is the latest value and history of different sensors and machine parameters?
Search Features
Searchable Objects
The searching API lets you retrieve both provisioned and collected information. When you query for provisioned information, you’ll obtain JSON documents with arrays of entities in the same format explained in the provision sections. So, all you already know about provisioning entities is helpful for you.
When you’re using the Web graphical interface, you can setup the attributes you want to see for each entity. This configuration applies to the API too. Therefore , all the queries you execute through the API retrieve only the attributes you setup in the Web console. |
Entity Type | Search Service |
---|---|
Assets |
See Assets Search |
Devices |
See Devices Search |
Subscriptions |
|
Subscribers |
Querying over | URI |
---|---|
Operations |
Querying over | URI |
---|---|
Jobs |
See Jobs Search |
Querying over | URI |
---|---|
Alarms |
See Alarms Search |
Querying over | URI |
---|---|
Hardware |
Querying over | URI |
---|---|
Software |
See Software Search |
Querying over | URI |
---|---|
Operation Types |
Querying over | URI |
---|---|
Operation Types |
Querying over | URI |
---|---|
Bundles |
See Bundles Search |
Querying over | URI |
---|---|
Datamodels |
Querying over | URI |
---|---|
Certificates |
Querying over | URI |
---|---|
Plan |
See Plans Search |
Querying over | URI |
---|---|
Datastreams associated to devices |
/north/v80/search/datastreams |
Datapoints associated to a datastream |
/north/v80/search/datapoints |
Feeds associated to datastreans and datapoints |
/north/v80/search/feeds |
Datamodels availables for the user who had made the searching |
/north/v80/search/datamodels |
Searching Features
Where is the "FROM
" and "WHERE
"?
Well, if you’re still thinking in SQL, then you’ll expect to find the word "FROM
" anywhere. Remember, OpenGate exposes its API through a REST interface, so in this case the word "FROM
" is in the URL suffix. See the valid searching URL table
In all response cases, you must POST a valid JSON query and you’ll get an array with the matched specific resources. The "query" could have next main objects:
-
"filter": Allows to select the resources that meets with desired information, see Filtering
-
"limit": Allows paginating the response, see Pagination
-
"sort": Allows sorting the results, see Sorting
-
"select": Allows selecting only the parameters you need, see Selecting
-
"group": Allows grouping the results, see Grouping
{ "filter": { ... }, "limit": { ... }, "sort": { ... }, "select": { ... }, "group": { ... } }
Procedure
Searching in OpenGate platform is pretty easy. You have to send a HTTP request to the API using the POST method, the prefix always is /north/v80/search. Optionally you can attach a JSON file (in the HTTP body) if you need to use paging, sorting, selecting, grouping or filtering features,
You can use the URL above for searching information. So for the impatient, let’s suppose you’re trying to search over your previously provisioned device list, and you’re thinking in a SQL WHERE
clause like that:
name like 'device_name' AND ( serialNumber like '82A75D494B0EBF7A95587285AE78E83F' OR serialNumber like '08D83B1864A1F9CFED76DAF426EB04D7')
in this case you must use http://[your_opengate_address]/north/v80/search/devices URL and POST a JSON like that:
{ "filter": { "and": [ { "like": { "device.name": "device_name" } }, { "or": [ { "like": { "device.serialNumber": "82A75D494B0EBF7A95587285AE78E83F" } }, { "like": { "device.serialNumber": "08D83B1864A1F9CFED76DAF426EB04D7" } } ] } ] }, "limit": { "start": 26, "size": 50 } }
Requesting with curl:
curl --request POST \ --data-binary @search-query.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices \ -H "Content-type: application/json"
Then you’ll receive the device list matching with your query, the response body should be something like that.
{ "devices" : [ { ... }, { ... }, { ... }, { ... }, ... { ... } ] }
Pagination
The API allows you obtaining the response to a search in blocks with predefined number of results.
Page JSON object
Parameter | Description |
---|---|
limit |
See Limit Object |
Parameter | Description |
---|---|
start |
Page number you request. The count starts with number 1 |
size |
Number of entities that you can see in the page |
Parameter | Description |
---|---|
number |
Number of the page where is positioned. The count starts with number 1 |
By default, the array’s size or page size is limited to 50 items, but you probably have thousands of devices. How do you walk through all your devices?. Well, let’s suppose you have exactly 2500 devices matching your query. Obviously your result exceeds the default limit. In this case, you’ll find a page object in your response. |
Pagination examples
{ "page" : { "number" : 1 }, "<resources>" : [ { ... }, { ... }, { ... }, { ... }, ... { ... } ] }
<resources> can be any of the reserved words for the searched resources: entities, devices, subscriptions, datamodels, bundles, datastreams, datapoints, etc. |
The "number" attribute is the page number is the current number of pages based in the limit setup. |
What can you do to get the following page? It’s easy, you only have to include a "limit" object in your query.
{ "limit" : { "start" : 2 } }
And then you’ll receive:
{ "page" : { "number" : 2 }, "<resources>" : [ { ... }, { ... }, { ... }, { ... }, ... { ... } ] }
<resources> can be any of the reserved words for the searched resources: entities, devices, subscriptions, datamodels, bundles, datastreams, datapoints, etc. |
In fact, you can change the page limit from the beginning. Supposing you want to retrieve 50 items per query, then you must setup the limit object with a starting point and the page size you want to get.
Remember, now you’re learning by example, your supposed query match 2.500 devices. |
{ "limit" : { "start" : 2, "size" : 50 } }
The top margin for the page size in the limit object is 1000. If you setup a size attribute over this limit, you’ll receive a server error response. |
The response must be something like that:
{ "page" : { "number" : 2}, "<resources>" : [ { ... }, { ... }, { ... }, { ... }, ... { ... } ] }
<resources> can be any of the reserved words for the searched resources: entities, devices, subscriptions, datamodels, bundles, datastreams, datapoints, etc. |
Filtering
The search API uses the following filtering options to facilitate the search and allow to perform a wide range of consultations.
There are several techniques to solve the filtering issue when you’re querying over a RESTful interface. For example, standard HTTP parameters can be used to add filtering capabilities to your query, it’s pretty simple, but doesn’t cover complex needs. We require a SQL like approach, with typical operators like AND, OR, EQUAL, NOT EQUAL, etc. OpenGate allows you to filter your queries by sending a POST request to a specific URI. In the POST request you must send a JSON document with a very fashionable DSL structure. It is a command pattern approach in contrast with the entity/collection pattern used in the provision API.
In the next sections are described filtering features.
Filter JSON object
Parameter | Description |
---|---|
filter |
See Operator Object |
Filtering operators
The following list shows the filtering operators supported by the search API.
Operation | Description |
---|---|
eq |
Equals |
neq |
Not equals |
like |
Regex pattern like |
gt |
Greater than |
lt |
Lower than |
gte |
Greater than or equals |
lte |
Lower than or equals |
in[] |
Included in a concrete group |
nin[] |
Not included in a concrete group |
exists |
|
within |
Included in an areas.geometry GeoJson (exclusive for Area search) |
Operation | Description |
---|---|
and[] |
And |
or[] |
Or |
Route | DatastreamId |
---|---|
asset |
identifier |
channel |
identifier |
device |
identifier, serialNumber |
device.communicationModules[] |
identifier, mobile.imei |
device.communicationModules[].subscriber |
identifier |
device.communicationModules[].subscription |
identifier, address, mobile.imsi, mobile.msisdn, mobile.icc, presence.ipRtt, presence.unifiedPresence |
entity |
areas, location |
organization |
identifier |
provision.asset |
identifier, location |
provision.device |
identifier, location |
provision.device.communicationModules[] |
identifier |
provision.device.communicationModules[].subscriber |
identifier |
provision.device.communicationModules[].subscription |
identifier, address, mobile.imsi, mobile.msisdn, mobile.icc |
provision.organization |
identifier, plan |
provision.ticket |
identifier, location, owner, assignee, specificType, section, entity, assignedDate, answeredDate, updatedDate, restorationDate, resolutionDate, closedDate, parentTicket |
Available Filter fields
To include in the "WHERE" clause. They are all parameters defined in the Default Datamodels
Next example builds a filter using the datastreams: device.operationalStatus and device.communicationModules[].mobile.imei
{ "filter": { "and": [ { "like": { "provision.device.administrativeState": "NORMAL" } }, { "like": { "provision.device.communicationModules[].mobile.imei": "351873000102290" } } ] } }
The WHERE sentence internally built will be
SELECT * FROM device WHERE device.operationalStatus LIKE 'NORMAL' AND device.communicationModules[].mobile.imei LIKE '351873000102290'
The result will contain all devices with collected operational Status that contains NORMAL and are related with communications modules with collected imei containing 351873000102290
Filtering examples
Some examples of use of filtering
{ "filter": { "and": [ { "like": { ... } }, { "neq": { ... } } ] }, "limit": { "start": 26, "size": 50 } }
if you are searching for devices /north/v80/search/devices, but you want the devices whose subscriptions have a concrete postal code you must to use the next filter
{ "filter": { "eq": { "device.communicationModules[].mobile.imei": "351873000102290" } } }
{ "filter": { "and": [ { "in": { "device.name": [ "device_1", "device_2" ] } }, { "nin": { "device.description": [ "device default description" ] } } ] }, "limit": { "start": 26, "size": 50 } }
{ "filter": { "eq": { "tag": "my_sticky_tag" } }, "limit": { "start": 26, "size": 50 } }
{ "filter": { "and": [ { "like": { "device.model": "EF5" } }, { "exists": { "device.identifier": true } } ] }, "limit": { "start": 1, "size": 10 } }
{ "filter": { "and": [ { "like": { "device.software": "1.0" } } ] }, "limit": { "start": 1, "size": 10 } }
{ "filter":{ "and":[ { "in":{ "operationEntityType":[ "SUBSCRIPTION", "ASSET" ] } } ] }, "limit":{ "start":1, "size":10 } }
{ "filter": { "in": { "device.name": [ "DEVICE22" ] } }, "limit":{ "start":1, "size":10 } }
{ "filter": { "and": [ { "like": { "provision.device.location._current.value.postal": "41015" } } ] } }
Some SQL to JSON filtering queries
OpenGate Search API queries are expressed as JSON objects. The following chart shows examples as both SQL (from MySQL for the shake of simplicity) and in OpenGate Search API Query Language syntax.
SQL | OpenGate search API JSON queries |
---|---|
SELECT * FROM device WHERE serialNumber <> '82A75D494B0EBF7A95587285AE78E83F' |
/north/v80/search/devices { "filter": { "and": [ { "neq": { "device.serialNumber": "82A75D494B0EBF7A95587285AE78E83F" } } ] }, "limit": { "start": 2 } } |
SELECT * FROM device WHERE serialNumber LIKE '82A75D494B0EBF7A95587285AE78E83F' AND imei > '123456786543210' AND imei < '123456786544210' |
/north/v80/search/devices { "filter": { "and": [ { "like": { "device.serialNumber": "82A75D494B0EBF7A95587285AE78E83F" } }, { "gt": { "device.communicationModules[].mobile.imei": "123456786543210" } }, { "lt": { "device.communicationModules[].mobile.imei": "123456786544210" } } ] }, "limit": { "start": 26, "size": 50 } } |
Sorting
The API allows to decide how to order of the results. To do that it is necessary to include in the JSON request the "order" object.
Sort JSON object
Let’s see the available parameters for ordering the searchable objects:
Parameter | Description |
---|---|
parameters[] |
Array of ordering parameters |
the name of the parameters is the same that filter name parameters. See Available fields section |
Parameter | Description |
---|---|
name |
Name of parameter defined in the Default Datamodels |
type |
Enumeration string with ordering type. Valid values are:
|
Selecting
You can select only the parameters you like to retrieve in the response. By default (if is not included the select object in the request) the response to a request include all fields for each searched object.
When it is necessary to retrieve specific fields included in the searched object (i.e: device), the JSON select object can be included in the search request, see Select Object.
The select clause only can be used for entity searching and must not be empty.
This clause must be included, if you want to retrieve the response in csv format.
If the size of csv file exceed 18 MB, you must use the following parameters in the HTTP header:
|
If is not the select clause in the filter, the behaviour is the following:
-
In Json format, the response are all the elements you are searching
-
In csv format, the response is an error and it is asked the select clause.
As described above, any datastream of the Default Datamodels or datamodels defined by the user can be used as select fields.
The order to apply the filters is securization and next the following fields whenever there are resourceType, sort, filter, select (the fields to show) |
Select JSON object
Entity | Description |
---|---|
select[] |
Array of parameters to be selected. See Select Parameter Object |
Entity | Description |
---|---|
name |
String. Name of the datastream in the Default Datamodels or datamodels defined by the user |
fields[] |
Array of strings with the name of the fields to be retrieved. The possible values are: (See current object attributes table for field description): * "value" * "date" * "at" * "from" * "tags" * "feedId" * "scoring.performance" * "scoring.qrating" * "provType" * "value.<simplexAttribute>": where <simplexAttribute> is an attribute of the complex object. For example, the provision.device.location is a complex datastream. If you need only de postal code, the value would be value.postal |
alias |
String. Shortname to replace the full name of the parameter when a CSV format is required. Example: * Using "alias"="imei" * The "device.communicationModules[].mobile.imei" becomes "imei" in the CSV header If this field doesn’t exist, it will appear the full datastream name in the csv header In the csv format this field is shown, but in json format is ignored. |
Select examples
Here’s how to search devices with a filter with select clause
This is the request using curl:
curl --request POST \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices \ -H "Content-type: application/json"
In the body of the request you include the filter with the select clause
{ "select": [ { "name": "provision.device.identifier", "fields": [ { "field": "value", "alias": "id" }, { "field": "date", "alias": "date" } ] } ] }
{ "select": [ { "name": "provision.device.location", "fields": [ { "field": "value.postal", "alias": "Postal code" } ] } ] }
Depending on the parameter header, the response can be in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
{ "devices": [ { "id" : "bca8cbbb-b151-442b-8b0d-96ed77789c45", "device": { "operationalStatus" : { "current" : { "value" : "NORMAL", "date" : "2017-02-02T09:05:58Z", "performance": 75 } }, "communicationsModules" : [ { "identifier": "351873000102290", "mobile": { "imei" : { "current" : { "value" : "351873000102290", "date" : "2017-02-02T09:05:58Z" } } } } ] }, "health": { "heart":{ "rate":{ "current" : { "value": 60, "date": "2017-02-02T09:05:58Z", "performance": 78 } } } } } ] }
device.operationalStatus.current.value;device.operationalStatus.current.updated;device.operationalStatus.current.performance;imei.current.value;imei.current.updated;imei.current.performance;rate.current.value;rate.current.updated;rate.current.performance; "NORMAL";"2017-02-02T09:05:58Z";75;"351873000102290";"2017-02-02T09:05:58Z";;60;"2017-02-02T09:05:58Z";78
Summary
Responses to all search requests include a summary object with different counters regarding the results obtained. It is closely relationed to the Grouping
By default the summary always shows the total counter and the organizations grouping counter and channel grouping counter
Summary JSON object
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
summaryGroup [] |
Array of type of Summarized Specific Object Structure |
Entity | Constraint |
---|---|
SpecificObjectParameterDatamodel |
Object inside the Parameter of the Default Datamodels. See Summarized Element Structure |
Entity | Constraint |
---|---|
count |
number of these specific elements found |
list |
Array of each type of Summarized Element List |
Entity | Constraint |
---|---|
count |
number of these specific elements found |
name |
value of the parameter of the Default Datamodels |
Here’s how to search devices with summary without group clause
This is the request using curl:
curl --request POST \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices/summary \ -H "Content-type: application/json"
The response would be something like this
{ "summary": { "count": 6, "summaryGroup": [ { "provision.administration.organization": { "count": 6, "list": [ { "count": 6, "name": "organization1" } ] } }, { "provision.administration.channel": { "count": 6, "list": [ { "count": 6, "name": "channel1" } ] } } ] } }
Here’s how to search devices with summary with filter with the group clause
This is the request using curl:
curl --request POST \ --data-binary @subscription.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices/summary \ -H "Content-type: application/json"
In the body of the request you include the filter with the select clause
{ "filter": { "and": [ { "like": { "provision.administration.organization": "battery_organization" } } ] }, "group": { "parameters": [ { "name": "provision.device.model" } ] } }
The response would be something like this
{ "summary": { "count": 6, "summaryGroup": [ { "provision.administration.organization": { "count": 6, "list": [ { "count": 6, "name": "battery_organization" } ] } }, { "provision.administration.channel": { "count": 6, "list": [ { "count": 6, "name": "battery_channel" } ] } }, { "provision.device.model.name": { "count": 6, "list": [ { "count": 1, "name": "model_name-7" }, { "count": 2, "name": "model_name-4" }, { "count": 1, "name": "model_name-10" }, { "count": 1, "name": "model_name-5" }, { "count": 1, "name": "model_name-11" } ] } } ] } }
Grouping
It is possible to make groupings by some parameters of the Default Datamodels, thanks to group clause in the filter. This clause is optional
Group JSON object
Let’s see the available parameters for grouping the searchable objects:
Parameter | Description |
---|---|
parameters[] |
Array of grouping parameters, see group parameter object |
Parameter | Description |
---|---|
name |
Name of the parameter in the Default Datamodels |
The summarizables parameters list are:
|
Group examples
An example for grouping into a request could be:
{ "filter": { "and": [ { "like": { "provision.administration.organization": "battery_organization" } } ] }, "group": { "parameters": [ { "name": "provision.device.model" } ] } }
The response would be something like this
{ "summary": { "count": 6, "summaryGroup": [ { "provision.administration.organization": { "count": 6, "list": [ { "count": 6, "name": "battery_organization" } ] } }, { "provision.administration.channel": { "count": 6, "list": [ { "count": 6, "name": "battery_channel" } ] } }, { "provision.device.model.name": { "count": 6, "list": [ { "count": 1, "name": "model_name-7" }, { "count": 2, "name": "model_name-4" }, { "count": 1, "name": "model_name-10" }, { "count": 1, "name": "model_name-5" }, { "count": 1, "name": "model_name-11" } ] } } ] } }
Alarms
The OpenGate API query allows to retrieve all raised alarms during the operation.
This API allows retrieveing the list of alarms providing a lot of options for:
-
Filter (See Specific Filter Fields)
-
Order (see Sorting)
-
Select Required Fields (see Selecting)
-
Summary (see Summary)
It is possible to obtain the results in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
URL
Type of Information | URL |
---|---|
Currently performed Alarms of all entities |
/north/v80/search/entities/alarms |
Currently performed summary of alarms of all entities |
/north/v80/search/entities/alarms/summary |
Currently performed Alarms on the devices |
/north/v80/search/entities/devices/alarms |
Currently performed summary of alarms on the devices |
/north/v80/search/entities/devices/alarms/summary |
Currently performed Alarms on the subscriptions |
/north/v80/search/entities/subscriptions/alarms |
Currently performed summary of alarms on the subscriptions |
/north/v80/search/entities/subscriptions/alarms/summary |
Here, you can see some Searching alarms examples
Alarms summary information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
summaryGroup |
See Summarized Elements Structure. You can also see the specific objects in the section to each searching of entity |
Entity | Constraint |
---|---|
status |
See Summarized Specific Object Operations Structure, see specific values in Alarm Object bellow status field |
severity |
See Summarized Specific Object Operations Structure, see specific values in Alarm Object bellow severity field |
rule |
Entity | Constraint |
---|---|
count |
number of occurrences found of this specific element |
list |
Array of each type of Summarized Element Structure |
Entity | Constraint |
---|---|
count |
number of these specific elements found |
name |
name of the summarized element |
This summary is valid for all type of entities |
There is not included the field "type" of the summarized element |
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
identifier |
alarm.identifier |
string |
entityIdentifier |
alarm.entityIdentifier |
string |
subEntityIdentifier |
alarm.subEntityIdentifier |
string |
resourceType |
alarm.resourceType |
string |
channel |
alarm.channel |
string |
organization |
alarm.organization |
string |
rule |
alarm.rule |
string |
name |
alarm.name |
string |
severity |
alarm.severity |
string |
priority |
alarm.priority |
string |
description |
alarm.description |
string |
status |
alarm.status |
string |
openingDate |
alarm.openingDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
attentionDate |
alarm.attentionDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
attentionNote |
alarm.attentionNote |
string |
attentionUser |
alarm.attentionUser |
string |
closureDate |
alarm.closureDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
closureNote |
alarm.closureNote |
string |
closureUser |
alarm.closureUser |
string |
Response Format
Using HTTP header option "Accept", the API allows obtaining the result in different formats:
Format | Accept Header Value |
---|---|
JSON |
By default if "Accept" header field is not present or "Accept" field has "application/json" value |
CSV |
If "Accept" has "text/plain" value |
Response structure
Entity | Constraint |
---|---|
page |
See page object |
summary |
See summary object in this section |
alarms[] |
Entity | Constraint | Description |
---|---|---|
identifier |
UUID format. string |
Unique identification of the alarm instance |
resourceType |
string |
|
entityIdentifier |
string |
Entity identifier |
subEntityIdentifier |
string |
Sub-entity identifier |
severity |
String enumeration with the next values:
|
Severity of the raised alarm |
status |
String enumeration with the next values:
|
Status of the raised alarm |
priority |
String enumeration with the next values:
|
Priority of the raised alarm |
name |
string |
Alarm name |
rule |
string |
Rule name |
description |
string |
Alarm description |
organization |
string |
Organization name |
channel |
string |
Channel name |
openingDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date and time when the alarm is opened |
attentionDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date and time when the alarm is attended |
attentionUser |
string |
User who attend the alarm |
attentionNote |
string |
Notes included by the operator as part of the alarm attending process |
closureDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date and time when the alarm is closed |
closureUser |
string |
User who closed the alarm |
closureNote |
string |
Notes included by the operator as part of the alarm closing process |
Alarms Search examples
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
JSON format
This is the request using curl for an example without summary:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities/devices/alarms
And this is the response body:
{ "alarms": [ { "severity": "CRITICAL", "identifier": "6c6c3bcb-633e-4418-ae6d-ed69a1db7e96", "channel": "chn_ogmapiXXX9", "subEntityIdentifier": "device_ogmapiXXX9", "rule": "rule_open1_XXX9", "description": "alarmForDevice description", "attentionNote": "notes - attended alarm", "priority": "HIGH", "entityIdentifier": "device_ogmapiXXX9", "attentionUser": "admin_domain_ogmapiXXX9@amplia.es", "organization": "org_ogmapiXXX9", "name": "alarmForDevice", "closureDate": "2020-08-21T10:42:54.186Z", "attentionDate": "2020-08-21T10:42:48.653Z", "closureNote": "notes - closed alarm", "openingDate": "2020-08-21T10:42:35.507Z", "resourceType": "entity.device", "status": "CLOSED", "closureUser": "admin_domain_ogmapiXXX9@amplia.es" }, { "severity": "CRITICAL", "identifier": "d045caf9-ea40-4232-a451-41aec677d983", "channel": "chn_ogmapiXXX9", "subEntityIdentifier": "device_ogmapiXXX9", "rule": "rule_open2_XXX9", "description": "alarmForDevice description", "attentionNote": "notes - attended alarm", "priority": "HIGH", "entityIdentifier": "device_ogmapiXXX9", "attentionUser": "admin_domain_ogmapiXXX9@amplia.es", "organization": "org_ogmapiXXX9", "name": "alarmForDevice", "attentionDate": "2020-08-21T10:42:48.656Z", "openingDate": "2020-08-21T10:42:38.285Z", "resourceType": "entity.device", "status": "ATTEND" } ], "page": { "number": 1 } }
This is the request using curl for an example with summary:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities/devices/alarms/summary
And this is the response body:
{ "summary": { "date": "2020-08-14T11:06:26.04Z", "count": 3, "summaryGroup": [ { "severity": { "count": 3, "list": [ { "count": 2, "name": "CRITICAL" }, { "count": 1, "name": "INFORMATIVE" } ] } }, { "rule": { "count": 3, "list": [ { "count": 1, "name": "alarmForSubsInDevice" }, { "count": 1, "name": "alarmForDevice" }, { "count": 1, "name": "alarmForSubscription" } ] } }, { "status": { "count": 3, "list": [ { "count": 3, "name": "OPEN" } ] } } ] } }
you can view the special fields for searching alarms in the table Filter fields for searching raised alarms |
CSV Format
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/entities/devices/alarms
identifier;entityIdentifier;subEntityIdentifier;severity;status;priority;rule;name;description;openingDate;attentionDate;attentionUser;attentionNote;closureDate;closureUser;closureNote;channel;resourceType;organization <!null>;device_ogmapixxx1;device_ogmapixxx1;CRITICAL;OPEN;HIGH;rule_open_dev;alarmForDevice;alarmForDevice description;contains("Z");;;;;;;chn_ogmapixxx1;entity.device;org_ogmapixxx1 <!null>;device_ogmapixxx2;214070001210002;URGENT;OPEN;MEDIUM;rule_subs2;alarmForSubsInDevice;alarmForSubsInDevice description;contains("Z");;;;;;;chn_ogmapixxx1;entity.device;org_ogmapixxx1 <!null>;device_ogmapixxx3;8965069699131210003;INFORMATIVE;OPEN;LOW;rule_open_sber;alarmForSberInDevice;alarmForSberInDevice description;contains("Z");;;;;;;chn_ogmapixxx1;entity.device;org_ogmapixxx1 <!null>;asset_ogmapixxx5;asset_ogmapixxx5;CRITICAL;OPEN;HIGH;rule_open_asset;alarmForAsset;alarmForAsset description;contains("Z");;;;;;;chn_ogmapixxx1;entity.asset;org_ogmapixxx1 <!null>;device_ogmapixxx6;device_ogmapixxx6;CRITICAL;CLOSED;HIGH;rule_open_dev;alarmForDevice;alarmForDevice description;contains("Z");contains("Z");user_ogmapixxx1@amplia.es;notes - attended alarm;contains("Z");user_ogmapixxx1@amplia.es;notes - closed alarm;chn_ogmapixxx1;entity.device;org_ogmapixxx1 <!null>;214070001250007;214070001250007;INFORMATIVE;OPEN;LOW;presenceGPRS;alarmForSubscription;alarmForSubscription description;contains("Z");;;;;;;chn_ogmapixxx1;entity.subscription;org_ogmapixxx1
Filter entities by alarmed devices
This is the request using curl:
curl --location --request POST 'http://[your_opengate_address]/north/v80/search/entities' \ --header 'X-ApiKey: YOUR_API_KEY_HERE' \ --header 'Content-Type: application/json' \ --data-raw '{ "filter": { "in": { "entity.alarms": [ "alarm1ForDevice" ] } } }'
{ "entities": [ { "provision": { "administration": { "identifier": { "_current": { "date": "2020-08-21T09:05:34.086Z", "at": "2020-08-21T09:05:34.086Z", "provType": "MONITORING", "value": "device_ogmapixxx2" } }, "organization": { "_current": { "date": "2020-08-21T09:05:34.087Z", "at": "2020-08-21T09:05:34.087Z", "provType": "MONITORING", "value": "org_ogmapixxx1" } }, "channel": { "_current": { "date": "2020-08-21T09:05:34.083Z", "at": "2020-08-21T09:05:34.083Z", "provType": "MONITORING", "value": "chn_ogmapixxx1" } }, "serviceGroup": { "_current": { "date": "2020-08-21T09:05:34.084Z", "at": "2020-08-21T09:05:34.084Z", "provType": "MONITORING", "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "date": "2020-08-21T09:05:34.09Z", "at": "2020-08-21T09:05:34.09Z", "provType": "IDENTIFIER", "value": "device_ogmapixxx2" } }, "administrativeState": { "_current": { "date": "2020-08-21T09:05:34.092Z", "at": "2020-08-21T09:05:34.092Z", "provType": "MONITORING", "value": "ACTIVE" } }, "location": { "_current": { "date": "2020-08-21T09:05:34.089Z", "at": "2020-08-21T09:05:34.089Z", "provType": "MONITORING", "value": { "province": "Madrid" } } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T09:05:34.097Z", "at": "2020-08-21T09:05:34.097Z", "provType": "IDENTIFIER", "value": "commsModxxx2" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T09:05:34.097Z", "at": "2020-08-21T09:05:34.097Z", "provType": "IDENTIFIER", "value": "subsxxx2" } }, "mobile": { "registeredOperator": { "_current": { "date": "2020-08-21T09:05:34.094Z", "at": "2020-08-21T09:05:34.094Z", "provType": "MONITORING", "value": "MOVISTAR" } }, "imsi": { "_current": { "date": "2020-08-21T09:05:34.093Z", "at": "2020-08-21T09:05:34.093Z", "provType": "IDENTIFIER", "value": "21407000121xxx2" } }, "homeOperator": { "_current": { "date": "2020-08-21T09:05:34.095Z", "at": "2020-08-21T09:05:34.095Z", "provType": "MONITORING", "value": "MOVISTAR" } } } } } ] } }, "devOpenAlarm1": { "_current": { "date": "2020-08-21T09:05:48.563Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:48.563Z", "source": "DEVICE_OPENGATE_HTTP", "value": 10 } }, "device": { "identifier": { "_current": { "date": "2020-08-21T09:05:48.539Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:48.539Z", "source": "DEVICE_OPENGATE_HTTP", "value": "device_ogmapixxx2" } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T09:05:48.598Z", "at": "2020-08-21T09:05:48.598Z", "value": "commsModxxx2" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T09:05:48.598Z", "at": "2020-08-21T09:05:48.598Z", "value": "subsxxx2" } }, "address": { "_current": { "date": "2020-08-21T09:05:48.564Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:48.564Z", "source": "DEVICE_OPENGATE_HTTP", "value": { "type": "IPV4", "value": "10.10.10.106" } } }, "presence": { "unifiedPresence": { "_current": { "date": "2020-08-21T09:05:48.626Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:48.626Z", "source": "DEVICE_OPENGATE_HTTP", "value": "IP" } }, "ip": { "_current": { "date": "2020-08-21T09:05:48.564Z", "scoring": { "performance": 100, "qrating": { "ideal": { "label": "OK", "value": 100 }, "max_score": 1000, "max_allowed": { "label": "OK", "value": 100 }, "min_desired": { "label": "NOK", "value": 0 }, "max_desired": { "label": "OK", "value": 100 }, "min_required": { "label": "NOK", "value": 0 }, "conversion_matrix": { "NOK": 0, "OK": 100 }, "version": "1.0.0" } }, "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:48.564Z", "source": "DEVICE_OPENGATE_HTTP", "value": "OK" } } } } } ] }, "entity": { "alarms": { "_current": { "date": "2020-08-21T09:05:48.701Z", "at": "2020-08-21T09:05:48.701Z", "source": "ALARMS", "value": [ "alarm1ForDevice" ] } } }, "resourceType": { "_current": { "date": "2020-08-21T09:05:34.098Z", "at": "2020-08-21T09:05:34.098Z", "provType": "IDENTIFIER", "value": "entity.device" } } }, { "provision": { "administration": { "identifier": { "_current": { "date": "2020-08-21T09:05:33.833Z", "at": "2020-08-21T09:05:33.833Z", "provType": "MONITORING", "value": "device_ogmapixxx1" } }, "organization": { "_current": { "date": "2020-08-21T09:05:33.835Z", "at": "2020-08-21T09:05:33.835Z", "provType": "MONITORING", "value": "org_ogmapixxx1" } }, "channel": { "_current": { "date": "2020-08-21T09:05:33.832Z", "at": "2020-08-21T09:05:33.832Z", "provType": "MONITORING", "value": "chn_ogmapixxx1" } }, "serviceGroup": { "_current": { "date": "2020-08-21T09:05:33.834Z", "at": "2020-08-21T09:05:33.834Z", "provType": "MONITORING", "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "date": "2020-08-21T09:05:33.831Z", "at": "2020-08-21T09:05:33.831Z", "provType": "IDENTIFIER", "value": "device_ogmapixxx1" } }, "administrativeState": { "_current": { "date": "2020-08-21T09:05:33.829Z", "at": "2020-08-21T09:05:33.829Z", "provType": "MONITORING", "value": "ACTIVE" } }, "location": { "_current": { "date": "2020-08-21T09:05:33.827Z", "at": "2020-08-21T09:05:33.827Z", "provType": "MONITORING", "value": { "province": "Segovia" } } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T09:05:33.825Z", "at": "2020-08-21T09:05:33.825Z", "provType": "IDENTIFIER", "value": "commsModxxx1" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T09:05:33.807Z", "at": "2020-08-21T09:05:33.807Z", "provType": "IDENTIFIER", "value": "subsxxx1" } }, "mobile": { "registeredOperator": { "_current": { "date": "2020-08-21T09:05:33.822Z", "at": "2020-08-21T09:05:33.822Z", "provType": "MONITORING", "value": "MOVISTAR" } }, "imsi": { "_current": { "date": "2020-08-21T09:05:33.808Z", "at": "2020-08-21T09:05:33.808Z", "provType": "IDENTIFIER", "value": "21407000121xxx1" } }, "homeOperator": { "_current": { "date": "2020-08-21T09:05:33.824Z", "at": "2020-08-21T09:05:33.824Z", "provType": "MONITORING", "value": "MOVISTAR" } } } } } ] } }, "devOpenAlarm1": { "_current": { "date": "2020-08-21T09:05:37.255Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:37.255Z", "source": "DEVICE_OPENGATE_HTTP", "value": 10 } }, "devOpenAlarm2": { "_current": { "date": "2020-08-21T09:05:43.422Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:43.422Z", "source": "DEVICE_OPENGATE_HTTP", "value": 10 } }, "device": { "identifier": { "_current": { "date": "2020-08-21T09:05:42.296Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:42.296Z", "source": "DEVICE_OPENGATE_HTTP", "value": "device_ogmapixxx1" } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T09:05:43.562Z", "at": "2020-08-21T09:05:43.562Z", "value": "commsModxxx1" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T09:05:43.562Z", "at": "2020-08-21T09:05:43.562Z", "value": "subsxxx1" } }, "address": { "_current": { "date": "2020-08-21T09:05:43.423Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:43.423Z", "source": "DEVICE_OPENGATE_HTTP", "value": { "type": "IPV4", "value": "10.10.10.106" } } }, "presence": { "unifiedPresence": { "_current": { "date": "2020-08-21T09:05:43.69Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:43.69Z", "source": "DEVICE_OPENGATE_HTTP", "value": "IP" } }, "ip": { "_current": { "date": "2020-08-21T09:05:43.423Z", "scoring": { "performance": 100, "qrating": { "ideal": { "label": "OK", "value": 100 }, "max_score": 1000, "max_allowed": { "label": "OK", "value": 100 }, "min_desired": { "label": "NOK", "value": 0 }, "max_desired": { "label": "OK", "value": 100 }, "min_required": { "label": "NOK", "value": 0 }, "conversion_matrix": { "NOK": 0, "OK": 100 }, "version": "1.0.0" } }, "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T09:05:43.423Z", "source": "DEVICE_OPENGATE_HTTP", "value": "OK" } } } } } ] }, "entity": { "alarms": { "_current": { "date": "2020-08-21T09:05:43.909Z", "at": "2020-08-21T09:05:43.909Z", "source": "ALARMS", "value": [ "alarm1ForDevice", "alarm2ForDevice" ] } } }, "resourceType": { "_current": { "date": "2020-08-21T09:05:33.836Z", "at": "2020-08-21T09:05:33.836Z", "provType": "IDENTIFIER", "value": "entity.device" } } } ], "page": { "number": 1 } }
Filter entities by alarmed subscriptions
This is the request using curl:
curl --location --request POST 'http://[your_opengate_address]/north/v80/search/entities' \ --header 'X-ApiKey: YOUR_API_KEY_HERE' \ --header 'Content-Type: application/json' \ --data-raw '{ "filter": { "in": { "device.communicationModules[].subscription.alarms": ["alarm1ForSubs"] } } }'
{ "entities": [ { "provision": { "administration": { "identifier": { "_current": { "date": "2020-08-21T11:03:05.022Z", "at": "2020-08-21T11:03:05.022Z", "provType": "MONITORING", "value": "subsxxx4" } }, "organization": { "_current": { "date": "2020-08-21T11:03:05.024Z", "at": "2020-08-21T11:03:05.024Z", "provType": "MONITORING", "value": "org_ogmapixxx1" } }, "channel": { "_current": { "date": "2020-08-21T11:03:05.02Z", "at": "2020-08-21T11:03:05.02Z", "provType": "MONITORING", "value": "chn_ogmapixxx1" } }, "serviceGroup": { "_current": { "date": "2020-08-21T11:03:05.023Z", "at": "2020-08-21T11:03:05.023Z", "provType": "MONITORING", "value": "emptyServiceGroup" } } }, "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "date": "2020-08-21T11:03:05.04Z", "at": "2020-08-21T11:03:05.04Z", "provType": "IDENTIFIER", "value": "subsxxx4" } }, "address": { "_current": { "date": "2020-08-21T11:03:05.032Z", "at": "2020-08-21T11:03:05.032Z", "provType": "REFERENCE", "value": { "type": "IPV4", "value": "172.19.17.1", "apn": "movistar.es" } } }, "administrativeState": { "_current": { "date": "2020-08-21T11:03:05.046Z", "at": "2020-08-21T11:03:05.046Z", "provType": "MONITORING", "value": "ACTIVE" } }, "specificType": { "_current": { "date": "2020-08-21T11:03:05.044Z", "at": "2020-08-21T11:03:05.044Z", "provType": "MONITORING", "value": "MOBILE" } }, "mobile": { "registeredOperator": { "_current": { "date": "2020-08-21T11:03:05.035Z", "at": "2020-08-21T11:03:05.035Z", "provType": "MONITORING", "value": "MOVISTAR" } }, "imsi": { "_current": { "date": "2020-08-21T11:03:05.037Z", "at": "2020-08-21T11:03:05.037Z", "provType": "IDENTIFIER", "value": "313169710010004" } }, "msisdn": { "_current": { "date": "2020-08-21T11:03:05.034Z", "at": "2020-08-21T11:03:05.034Z", "provType": "REFERENCE", "value": "346490000004" } }, "homeOperator": { "_current": { "date": "2020-08-21T11:03:05.036Z", "at": "2020-08-21T11:03:05.036Z", "provType": "MONITORING", "value": "MOVISTAR" } } }, "name": { "_current": { "date": "2020-08-21T11:03:05.047Z", "at": "2020-08-21T11:03:05.047Z", "provType": "MONITORING", "value": "cucumber_subscription" } }, "description": { "_current": { "date": "2020-08-21T11:03:05.038Z", "at": "2020-08-21T11:03:05.038Z", "provType": "MONITORING", "value": "subsxxx4" } } } } ] } }, "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "date": "2020-08-21T11:03:25.911Z", "at": "2020-08-21T11:03:25.911Z", "value": "subsxxx4" } }, "address": { "_current": { "date": "2020-08-21T11:03:24.517Z", "sourceInfo": "Receiving Message Type START", "at": "2020-08-21T11:03:24.517Z", "source": "OPERATOR_RADIUS", "value": { "type": "IPV4", "value": "172.19.17.1", "apn": "movistar.es" } } }, "session": { "_current": { "date": "2020-08-21T11:03:24.518Z", "sourceInfo": "Receiving Message Type START", "at": "2020-08-21T11:03:24.518Z", "source": "OPERATOR_RADIUS", "value": { "address": { "type": "IPV4", "value": "172.19.17.1", "apn": "movistar.es" }, "id": "123", "nasIp": { "type": "IPV4", "value": "1.1.1.1", "apn": "movistar.es" }, "radiusClientIp": { "type": "IPV4", "value": "10.10.10.106", "apn": "movistar.es" } } } }, "alarms": { "_current": { "date": "2020-08-21T11:03:26.036Z", "at": "2020-08-21T11:03:26.036Z", "source": "ALARMS", "value": [ "alarm1ForSubs" ] } }, "mobile": { "imsi": { "_current": { "date": "2020-08-21T11:03:24.518Z", "sourceInfo": "Receiving Message Type START", "at": "2020-08-21T11:03:24.518Z", "source": "OPERATOR_RADIUS", "value": "313169710010004" } }, "msisdn": { "_current": { "date": "2020-08-21T11:03:24.518Z", "sourceInfo": "Receiving Message Type START", "at": "2020-08-21T11:03:24.518Z", "source": "OPERATOR_RADIUS", "value": "34649000004" } }, "presence": { "gprs": { "_current": { "date": "2020-08-21T11:03:24.517Z", "scoring": { "performance": 100, "qrating": { "ideal": { "label": "OK", "value": 100 }, "max_score": 1000, "max_allowed": { "label": "OK", "value": 100 }, "min_desired": { "label": "OFF", "value": 50 }, "max_desired": { "label": "OK", "value": 100 }, "min_required": { "label": "NOK", "value": 0 }, "conversion_matrix": { "STOP": 100, "INTERIM_UPDATE": 100, "START": 100, "NOK": 0, "OFF": 50, "ON": 75 }, "version": "1.0.0" } }, "sourceInfo": "Receiving Message Type START", "at": "2020-08-21T11:03:24.517Z", "source": "OPERATOR_RADIUS", "value": "START" } } } }, "presence": { "unifiedPresence": { "_current": { "date": "2020-08-21T11:03:25.95Z", "sourceInfo": "Receiving Message Type START", "at": "2020-08-21T11:03:25.95Z", "source": "OPERATOR_RADIUS", "value": "GPRS" } } } } } ] }, "resourceType": { "_current": { "date": "2020-08-21T11:03:05.047Z", "at": "2020-08-21T11:03:05.047Z", "provType": "IDENTIFIER", "value": "entity.subscription" } } }, { "provision": { "administration": { "identifier": { "_current": { "date": "2020-08-21T11:03:04.633Z", "at": "2020-08-21T11:03:04.633Z", "provType": "MONITORING", "value": "device_ogmapixxx2" } }, "organization": { "_current": { "date": "2020-08-21T11:03:04.634Z", "at": "2020-08-21T11:03:04.634Z", "provType": "MONITORING", "value": "org_ogmapixxx1" } }, "channel": { "_current": { "date": "2020-08-21T11:03:04.631Z", "at": "2020-08-21T11:03:04.631Z", "provType": "MONITORING", "value": "chn_ogmapixxx1" } }, "serviceGroup": { "_current": { "date": "2020-08-21T11:03:04.632Z", "at": "2020-08-21T11:03:04.632Z", "provType": "MONITORING", "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "date": "2020-08-21T11:03:04.638Z", "at": "2020-08-21T11:03:04.638Z", "provType": "IDENTIFIER", "value": "device_ogmapixxx2" } }, "administrativeState": { "_current": { "date": "2020-08-21T11:03:04.64Z", "at": "2020-08-21T11:03:04.64Z", "provType": "MONITORING", "value": "ACTIVE" } }, "location": { "_current": { "date": "2020-08-21T11:03:04.636Z", "at": "2020-08-21T11:03:04.636Z", "provType": "MONITORING", "value": { "province": "Madrid" } } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T11:03:04.646Z", "at": "2020-08-21T11:03:04.646Z", "provType": "IDENTIFIER", "value": "commsModxxx2" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T11:03:04.645Z", "at": "2020-08-21T11:03:04.645Z", "provType": "IDENTIFIER", "value": "subsxxx2" } }, "mobile": { "registeredOperator": { "_current": { "date": "2020-08-21T11:03:04.642Z", "at": "2020-08-21T11:03:04.642Z", "provType": "MONITORING", "value": "MOVISTAR" } }, "imsi": { "_current": { "date": "2020-08-21T11:03:04.641Z", "at": "2020-08-21T11:03:04.641Z", "provType": "IDENTIFIER", "value": "21407000121xxx2" } }, "homeOperator": { "_current": { "date": "2020-08-21T11:03:04.643Z", "at": "2020-08-21T11:03:04.643Z", "provType": "MONITORING", "value": "MOVISTAR" } } } } } ] } }, "device": { "identifier": { "_current": { "date": "2020-08-21T11:03:19.407Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:19.407Z", "source": "DEVICE_OPENGATE_HTTP", "value": "device_ogmapixxx2" } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T11:03:19.484Z", "at": "2020-08-21T11:03:19.484Z", "value": "commsModxxx2" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T11:03:19.443Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:19.443Z", "source": "DEVICE_OPENGATE_HTTP", "value": "subsxxx2" } }, "address": { "_current": { "date": "2020-08-21T11:03:19.445Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:19.445Z", "source": "DEVICE_OPENGATE_HTTP", "value": { "type": "IPV4", "value": "10.10.10.106" } } }, "alarms": { "_current": { "date": "2020-08-21T11:03:19.616Z", "at": "2020-08-21T11:03:19.616Z", "source": "ALARMS", "value": [ "alarm1ForSubs" ] } }, "presence": { "unifiedPresence": { "_current": { "date": "2020-08-21T11:03:19.53Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:19.53Z", "source": "DEVICE_OPENGATE_HTTP", "value": "IP" } }, "ip": { "_current": { "date": "2020-08-21T11:03:19.445Z", "scoring": { "performance": 100, "qrating": { "ideal": { "label": "OK", "value": 100 }, "max_score": 1000, "max_allowed": { "label": "OK", "value": 100 }, "min_desired": { "label": "NOK", "value": 0 }, "max_desired": { "label": "OK", "value": 100 }, "min_required": { "label": "NOK", "value": 0 }, "conversion_matrix": { "NOK": 0, "OK": 100 }, "version": "1.0.0" } }, "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:19.445Z", "source": "DEVICE_OPENGATE_HTTP", "value": "OK" } } } } } ] }, "subs2OpenAlarm1": { "_current": { "date": "2020-08-21T11:03:19.443Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:19.443Z", "source": "DEVICE_OPENGATE_HTTP", "value": "10" } }, "resourceType": { "_current": { "date": "2020-08-21T11:03:04.646Z", "at": "2020-08-21T11:03:04.646Z", "provType": "IDENTIFIER", "value": "entity.device" } } }, { "provision": { "administration": { "identifier": { "_current": { "date": "2020-08-21T11:03:04.356Z", "at": "2020-08-21T11:03:04.356Z", "provType": "MONITORING", "value": "device_ogmapixxx1" } }, "organization": { "_current": { "date": "2020-08-21T11:03:04.358Z", "at": "2020-08-21T11:03:04.358Z", "provType": "MONITORING", "value": "org_ogmapixxx1" } }, "channel": { "_current": { "date": "2020-08-21T11:03:04.354Z", "at": "2020-08-21T11:03:04.354Z", "provType": "MONITORING", "value": "chn_ogmapixxx1" } }, "serviceGroup": { "_current": { "date": "2020-08-21T11:03:04.357Z", "at": "2020-08-21T11:03:04.357Z", "provType": "MONITORING", "value": "emptyServiceGroup" } } }, "device": { "identifier": { "_current": { "date": "2020-08-21T11:03:04.353Z", "at": "2020-08-21T11:03:04.353Z", "provType": "IDENTIFIER", "value": "device_ogmapixxx1" } }, "administrativeState": { "_current": { "date": "2020-08-21T11:03:04.351Z", "at": "2020-08-21T11:03:04.351Z", "provType": "MONITORING", "value": "ACTIVE" } }, "location": { "_current": { "date": "2020-08-21T11:03:04.348Z", "at": "2020-08-21T11:03:04.348Z", "provType": "MONITORING", "value": { "province": "Segovia" } } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T11:03:04.346Z", "at": "2020-08-21T11:03:04.346Z", "provType": "IDENTIFIER", "value": "commsModxxx1" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T11:03:04.319Z", "at": "2020-08-21T11:03:04.319Z", "provType": "IDENTIFIER", "value": "subsxxx1" } }, "mobile": { "registeredOperator": { "_current": { "date": "2020-08-21T11:03:04.343Z", "at": "2020-08-21T11:03:04.343Z", "provType": "MONITORING", "value": "MOVISTAR" } }, "imsi": { "_current": { "date": "2020-08-21T11:03:04.32Z", "at": "2020-08-21T11:03:04.32Z", "provType": "IDENTIFIER", "value": "21407000121xxx1" } }, "homeOperator": { "_current": { "date": "2020-08-21T11:03:04.345Z", "at": "2020-08-21T11:03:04.345Z", "provType": "MONITORING", "value": "MOVISTAR" } } } } } ] } }, "subs1OpenAlarm2": { "_current": { "date": "2020-08-21T11:03:14.352Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:14.352Z", "source": "DEVICE_OPENGATE_HTTP", "value": "10" } }, "subs1OpenAlarm1": { "_current": { "date": "2020-08-21T11:03:09.231Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:09.231Z", "source": "DEVICE_OPENGATE_HTTP", "value": "10" } }, "device": { "identifier": { "_current": { "date": "2020-08-21T11:03:14.311Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:14.311Z", "source": "DEVICE_OPENGATE_HTTP", "value": "device_ogmapixxx1" } }, "communicationModules": [ { "identifier": { "_current": { "date": "2020-08-21T11:03:14.423Z", "at": "2020-08-21T11:03:14.423Z", "value": "commsModxxx1" } }, "subscription": { "identifier": { "_current": { "date": "2020-08-21T11:03:14.352Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:14.352Z", "source": "DEVICE_OPENGATE_HTTP", "value": "subsxxx1" } }, "address": { "_current": { "date": "2020-08-21T11:03:14.358Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:14.358Z", "source": "DEVICE_OPENGATE_HTTP", "value": { "type": "IPV4", "value": "10.10.10.106" } } }, "alarms": { "_current": { "date": "2020-08-21T11:03:14.862Z", "at": "2020-08-21T11:03:14.862Z", "source": "ALARMS", "value": [ "alarm1ForSubs", "alarm2ForSubs" ] } }, "presence": { "unifiedPresence": { "_current": { "date": "2020-08-21T11:03:14.468Z", "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:14.468Z", "source": "DEVICE_OPENGATE_HTTP", "value": "IP" } }, "ip": { "_current": { "date": "2020-08-21T11:03:14.358Z", "scoring": { "performance": 100, "qrating": { "ideal": { "label": "OK", "value": 100 }, "max_score": 1000, "max_allowed": { "label": "OK", "value": 100 }, "min_desired": { "label": "NOK", "value": 0 }, "max_desired": { "label": "OK", "value": 100 }, "min_required": { "label": "NOK", "value": 0 }, "conversion_matrix": { "NOK": 0, "OK": 100 }, "version": "1.0.0" } }, "sourceInfo": "IoT Data Message Received", "at": "2020-08-21T11:03:14.358Z", "source": "DEVICE_OPENGATE_HTTP", "value": "OK" } } } } } ] }, "resourceType": { "_current": { "date": "2020-08-21T11:03:04.359Z", "at": "2020-08-21T11:03:04.359Z", "provType": "IDENTIFIER", "value": "entity.device" } } } ], "page": { "number": 1 } }
Areas
The OpenGate API query allows to obtain different platform areas. They will be only those on which the user who performs the query has visualization capacity for his domain / organization.
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
areas.identifier |
identifier of the area |
string |
areas.name |
name of the area |
string |
areas.description |
description of the area |
string |
areas.organization |
organization of the area |
string |
areas.entities |
entities of the area |
string |
areas.geometry |
it allows to find the area with a concrete coordenate (see example geometry filter) |
string |
Areas Object
An example of response could be something like this
[ { "organization": "organization_area", "identifier": "area_id", "name": "Warehouse", "description": "Warehouse of machinery", "geometry": {}, "entities": [ "identifier1" ] }, { "organization": "organization_area", "identifier": "area_id2", "name": "Workshop", "description": "Tools workshop", "geometry": { "type": "Polygon", "coordinates": [ [ [ 2.173200845718384, 41.36735636905808 ], [ 2.179992198944092, 41.364771670743316 ], [ 2.1802926063537598, 41.36514206995068 ] ] ] }, "entities": [] } ]
Assets
This API allows retrieveing the list of assets providing a lot of options for:
-
Filter (See Specific Filter Fields)
-
Order (see Sorting)
-
Select Required Fields (see Selecting)
-
Summary (see Summary)
It is possible to obtain the results in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
By the other hand, you can obtain the result in flattened format thanks to flattened parameter (see asset parameters)
URL parameters
-
flattened: It is possible to receive the asset data with a flattened json format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to receive a flattened json format
Specific Filter Fields
Any parameter of the list included in the asset Default Datamodels can be used as filters fields in API search filters, including the custom datastreams.
{ "filter": { "and": [ { "like": { "provision.asset.administrativeState": "ACTIVE" } }, { "like": { "provision.asset.specificType": "WORKER" } } ] } }
Specific Select Fields
See predefined profiles section Default Datamodels to know the fields you can use with the select feature.
Summary Information
It is possible to summarize the request, see Summary usage
Assets Search examples
Below, different examples are shown with the its request and its associated response
POST /north/v80/search/entities
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
JSON format
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities
if you want only return assets, the filter used is
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } } ] } }
And this is the response body:
{ "page": { "number": 1 }, "entities": [ { "resourceType": { "_current": { "value": "entity.asset", "provType": "IDENTIFIER", "date": "2017-12-01T08:47:44.843Z" } }, "provision": { "asset": { "identifier": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.843Z" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-12-01T08:47:44.833Z" } }, "name": { "_current": { "value": "Antonio Pérez", "provType": "MONITORING", "date": "2017-12-01T08:47:44.839Z" } }, "administrativeState": { "_current": { "value": "READY", "provType": "MONITORING", "date": "2017-12-01T08:47:44.835Z" } }, "description": { "_current": { "value": "battery worker", "provType": "MONITORING", "date": "2017-12-01T08:47:44.84Z" } }, "specificType": { "_current": { "value": "WORKER", "provType": "MONITORING", "date": "2017-12-01T08:47:44.837Z" } } }, "administration": { "identifier": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.83Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-01T08:47:44.826Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-01T08:47:44.827Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-01T08:47:44.824Z" } } } } } ] }
CSV Format
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/entities
if you want only return assets, the used filter must contain entity.asset as resourceType (see Filtering) and also the select clause because is obligatory for the csv format, see Selecting
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } } ] }, "select": [ { "name": "provision.asset.identifier", "fields": [ { "field": "value", "alias": "id" } ] }, { "name": "provision.asset.location", "fields": [ { "field": "value", "alias": "location" } ] } ] }
id;location worker_battery_id;"{"position":{"type":"Point","coordinates":[-3.7028, 40.41675]},"postal":"28013"}"
if you want return a determinated asset with related devices, the filter used is
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } }, { "like": { "provision.asset.identifier": "worker_battery_id" } } ] } }
And this is the response body:
{ "page": { "number": 1 }, "entities": [ { "resourceType": { "_current": { "value": "entity.asset", "provType": "IDENTIFIER", "date": "2018-09-11T08:23:23.430Z" } }, "provision": { "asset": { "identifier": { "_current": { "value": "worker_battery_id", "provType": "IDENTIFIER", "date": "2018-09-11T08:23:23.430Z" } }, "related": { "_current": { "value": [ "device_battery_id" ], "provType": "MONITORING", "date": "2018-09-11T08:23:49.027Z" } } }, "administration": { "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2018-09-11T08:23:23.409Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2018-09-11T08:23:23.397Z" } }, "identifier": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2018-09-11T08:23:23.420Z" } }, "organization": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2018-09-11T08:23:23.403Z" } } } } } ] }
By the other hand, if you want return the asset with a determinated related device, the filter used is
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } }, { "like": { "provision.asset.related": "device_battery_id" } } ] } }
And this is the response body:
{ "page": { "number": 1 }, "entities": [ { "resourceType": { "_current": { "value": "entity.asset", "provType": "IDENTIFIER", "date": "2018-09-11T08:23:23.430Z" } }, "provision": { "asset": { "identifier": { "_current": { "value": "worker_battery_id", "provType": "IDENTIFIER", "date": "2018-09-11T08:23:23.430Z" } }, "related": { "_current": { "value": [ "device_battery_id" ], "provType": "MONITORING", "date": "2018-09-11T08:23:49.027Z" } } }, "administration": { "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2018-09-11T08:23:23.409Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2018-09-11T08:23:23.397Z" } }, "identifier": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2018-09-11T08:23:23.420Z" } }, "organization": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2018-09-11T08:23:23.403Z" } } } } } ] }
POST /north/v80/search/entities?flattened=true
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities?flattened=true
if you want only return assets, the filter used is
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } } ] } }
And this is the response body:
{ "entities": [ { "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-01T08:47:44.826Z" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.83Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-01T08:47:44.827Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-01T08:47:44.824Z" } } }, "provision.asset.administrativeState": { "_value": { "_current": { "value": "READY", "provType": "MONITORING", "date": "2017-12-01T08:47:44.835Z" } } }, "provision.asset.description": { "_value": { "_current": { "value": "battery worker", "provType": "MONITORING", "date": "2017-12-01T08:47:44.84Z" } } }, "provision.asset.identifier": { "_value": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.843Z" } } }, "provision.asset.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-12-01T08:47:44.833Z" } } }, "provision.asset.name": { "_value": { "_current": { "value": "Antonio Pérez", "provType": "MONITORING", "date": "2017-12-01T08:47:44.839Z" } } }, "provision.asset.specificType": { "_value": { "_current": { "value": "WORKER", "provType": "MONITORING", "date": "2017-12-01T08:47:44.837Z" } } }, "resourceType": { "_value": { "_current": { "value": "entity.asset", "provType": "IDENTIFIER", "date": "2017-12-01T08:47:44.843Z" } } } } ], "page": { "number": 1 } }
POST /north/v80/search/entities/summary
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities/summary
if you want only return assets, the filter used is
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } } ] } }
The response body could be something like this:
{ "summary": { "count": 2, "summaryGroup": [ { "provision.administration.channel": { "count": 2, "list": [ { "count": 2, "name": "battery_channel" } ] } }, { "provision.administration.organization": { "count": 2, "list": [ { "count": 2, "name": "battery_organization" } ] } } ] } }
Bundles
The OpenGate API allows to search into the already provisioned updating (software, firmware, configuration, …) bundles.
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
bundleId |
bundle.id |
string |
bundelName |
bundle.Name |
string |
bundleVersion |
bundle.Version |
string |
bundleWorkgroup |
bundle.Workgroup |
string |
bundleDescription |
bundle.Description |
string |
bundleActive |
bundle.Active |
boolean, valid values: * True * False |
bundleUserNotes |
bundle.UserNotes |
string |
bundleHardware |
bundle.Hardware |
string |
bundleCreationDate |
bundle.CreationDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
bundleDeploymentId |
bundle.Deployment.Element.Id |
string |
bundleDeploymentElementName |
bundle.Deployment.Element.Name |
string |
bundleDeploymentElementVersion |
bundle.Deployment.Element.Version |
string |
bundleDeploymentElementType |
bundle.Deployment.Element.Type |
string |
bundleDeploymentElementSize |
bundle.Deployment.Element.size |
number |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
Response structure
The JSON response has the same format
Entity | Constraint |
---|---|
bundles[] |
see Bundle structure below |
Attributes | Description |
---|---|
id |
Bundle identifier. |
name |
Name of the bundle |
version |
Version of the bundle |
description |
Field used mainly by the user for writing a description of the bundle |
userNotes |
field used mainly by the users of the bundle for introduce notes about it |
workgroup |
Workgroup where the bundle will be available |
active |
Field used for indicate that a bundle is available for an operation update. |
creationDate |
creation date of the bundle. |
preaction |
array of actions that the device must execute before the installation of the bundle |
postaction |
array of actions that the device must execute after the installation of the bundle |
hardware |
Reference to target hardware from OpenGate hardware catalog. |
deploymentElements |
Attributes | Description |
---|---|
id |
Deployment element identifier. |
name |
Name of the deployment element |
version |
Version of the deployment element |
type |
type of the deployment element
|
path |
path where the device must install the deployment element |
order |
Identify the position in the bundle structure of the deployment element |
operation |
Operation that the device must realize with the deployment element
|
option |
Valid values
|
oldName |
Deployment element old name |
oldVersion |
Deployment element old version |
oldPath |
Deployment element old path |
validators |
Indicates the array of type of validation to be performed. |
downloadUrl |
URL value where the device can download the file. |
{ "bundles": [ { "id": "76796426-ec3e-11e1-aff1-0800200c9a66", "name": "bundle_1", "version": "2-SNAPSHOT", "description": "My Fancy Bundle", "userNotes": "comment 1", "workgroup": "My_workgroup", "active": true, "creationDate": "2010-12-11T10:10:00Z", "preaction": [ "COMMS_DOWN" ], "postaction": [ "HARDWARE_RESET" ], "hardware": "0f1fd82b-959c-44af-a97a-edb765387c4a", "deploymentElements": [ { "id": "8fc4d616-0081-4ee8-a82d-99d448b58d40", "name": "fileToInstall", "version": "1.1", "type": "SOFTWARE", "path": "/usr/files", "order": "1", "operation": "INSTALL", "option": "MANDATORY", "validators": [ { "type": "SHA-256", "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename" }, { "id": "3a11ff22-97b6-44a8-800e-97c73d23962f", "name": "fileToUninstall", "version": "1.2", "type": "CONFIGURATION", "path": "/usr/files/config", "order": "2", "operation": "UNINSTALL", "option": "OPTIONAL", "validators": [ { "type": "SHA-256", "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename" }, { "id": "4e5a6e9f-e66f-4a0a-aafe-91dcb18dbef9", "name": "fileToUpgrade", "version": "1.3", "type": "PARAMETERS", "path": "/usr/files/config", "order": "3", "operation": "UPGRADE", "oldName": "fileToUpgradeOld", "oldVersion": "1.3_alpha", "oldPath": "/usr/files/config/old", "validators": [ { "type": "SHA-256", "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename" }, { "id": "98013256-02c6-4cb9-9307-53694e15fb4b", "name": "bundle_1-file_2", "version": "1.2.3-SNAPSHOT", "type": "FIRMWARE", "path": "./", "order": "4", "operation": "INSTALL", "option": "OPTIONAL", "validators": [ { "type": "SHA-256", "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "downloadUrl": "http://10.10.10.10/fwfiles/filename" } ] } ] }
you can view the special fields for searching available bundles in the table Filter fields for searching bundles |
The option with summary will be available in future versions |
Certificates
The OpenGate API allows to search certificate.
URL
Type of Information | URL |
---|---|
Available Certificates provisioned in the platform |
/north/v80/search/certificates |
URL parameters
Fetch parameter
Different response objects can be obtained using fetch parameter in the URL request, "/north/v80/search/certificates?fetch=<value>" where <value> can be:
-
0: This is the default value when parameter is not present. The result is the described in Certificate object structure section
{ "certificates" : [ { "id" : "9d55e8ac-e695-11e5-9730-9a79f06e9478", ... "trustChains": [ [1427353136] ], ... }, { "id" : "19221918-0f0f-460a-8111-ff118decae7d", ... "trustChains": [ [1427353136] ], ... } ] }
-
1: Complete information of the certificates showed in the "trustChains" object (including "entities" object)
{ "certificates" : [ { "id" : "9d55e8ac-e695-11e5-9730-9a79f06e9478", ... "parents": [ { "id" : "9d55e8ac-e695-11e5-9730-9a79f06e9478", "name": "My Parent Certificate", "description" : "", "parents": [ { "id" : "502aa5fa-7ca5-415a-885e-661ac7926eb4", "name": "My parent Certificate", "description" : "", ... } ], ... } ], ... }, { "id" : "19221918-0f0f-460a-8111-ff118decae7d", ... "parents": [ [ { "id" : "9d55e8ac-e695-11e5-9730-9a79f06e9478", "name": "My Certificate 2", "description" : "", "parents": [ ], ... } ] ], ... } ] }
visibility parameter
Different response objects can be obtained using visibility parameter in the URL request, "/north/v80/search/certificates?visibility=<value>" where <value> can be:
-
assignable: In this case you’ll receive the certificates that you can assign to domains, channels and devices. These certificates belong to the user’s domain or domains with visible upper hierarchy.
-
administrable: This is the default value when parameter is not present, in this case you’ll receive the certificates that you can administrate, I mean, the certificates that you can manage: update, delete… This certificates belong to the user’s domain who does the searching request or in the domains with low hierarchy managed by the user.
The option with summary will be available in future versions |
Specific Filter Fields
Parameter | Description |
---|---|
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
Number |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
Filtering by trustChain field
See how the trustChain works section if you like to learn about this field usage.
Some Examples:
{ "filter": { "and": [ { "like": { "certificate.trustChain": "1427353136" } } ] } }
{ "filter": { "and": [ { "like": { "certificate.trustChain": "1427353136,1427353426" } } ] } }
{ "filter": { "and": [ { "like": { "certificate.trustChain": "1427353136%1427353426" } } ] } }
{ "filter": { "or": [ { "like": { "certificate.trustChain": "1427353136" } }, { "like": { "certificate.trustChain": "1427353426" } } ] } }
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
Response structure
By default (See Fetch Parameter section) the JSON response has the format described below
Entity | Constraint |
---|---|
certificate[] |
Array of certificate. See Certificate object structure section |
{ ... "certificates" : [ { "id" : "9d55e8ac-e695-11e5-9730-9a79f06e9478", "usages" : [ "FILE_VALIDATION", "COMMUNICATIONS" ], "name": "My Certificate", "description" : "", "administrativeState" : "ACTIVE", "hardware" : [ { "manufacturer" : "Manufacturer_1", "model":"MODEL_1", "modelVersion" : "1A" } ], "tags" : [ "my_tag_1" ], "version": "", "trustChains": [ ["1427353677"] ], "subject": "CN=MY_CA,OU=O100", "issuer": "CN=MY_CA,OU=O100", "serialNumber" : 1427353677, "valid" : { "from": "2015-03-26T08:07:59Z", "until": "2016-03-26T08:07:59Z" }, "publicKey" : { "algorithm": "RSA", "size" : 2048, "format": "X.509" }, "domains": ["domain_certificates_search"] }, { "id" : "19221918-0f0f-460a-8111-ff118decae7d", "usages" : [ "FILE_VALIDATION", "COMMUNICATIONS" ], "name": "My other Certificate", "description" : "", "administrativeState" : "ACTIVE", "hardware" : [ { "manufacturer" : "Manufacturer_1", "model":"MODEL_1", "modelVersion" : "1A" } ], "tags" : [ "my_tag_1" ], "version": "", "trustChains": [ ["1427353679"] ], "subject": "CN=MY_CA,OU=O100", "issuer": "CN=MY_CA,OU=O100", "serialNumber" : 1427353679, "valid" : { "from": "2015-03-26T08:07:59Z", "until": "2016-03-26T08:07:59Z" }, "publicKey" : { "algorithm": "EC", "size" : 256, "format": "X.509" }, "domains": ["domain_certificates_search"] } ] }
Channels
The OpenGate API query allows to obtain the available channels provisioned under the domain of the user that sends the request.
URL
Type of Information | URL |
---|---|
Channels provisioned in the platform |
/north/v80/search/channels |
Summary of the Channels provisioned in the platform |
/north/v80/search/channels/summary |
URL parameters
Using summary parameter in the URL request, "/north/v80/search/channels?summary=<value>" where <value> can be:
-
true: The response includes the summary object.
-
false (default): The same behavior when the parameter is not present. The summary object is not included in the response
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
name |
name of the channel |
string |
description |
description of the channel |
string |
organizationName |
Organization the channel belongs to |
string |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
Examples
An example of response could be something like this
{ "channels": [ { "name": "Channel_1", "description": "Channel description", "organization" : "battery_organization", "certificates" : ["certificate1_id","certificate2_id"] }, { "name": "Channel_2", "description": "Channel description", "organization" : "battery_organization", "certificates" : ["certificate1_id","certificate2_id"] } ] }
{ "page":{ "number":1, "of":1 }, "summary": { "count": 2 }, "channels": [ { "name": "Channel_1", "description": "Channel description", "organization" : "battery_organization", "certificates" : ["certificate1_id","certificate2_id"] }, { "name": "Channel_2", "description": "Channel description", "organization" : "battery_organization", "certificates" : ["certificate1_id","certificate2_id"] } ] }
{ "summary": { "count": 2 } }
Datamodels
With this option you can filter between the different datamodels that you have in your organization. For more information about it, please see IoT concepts section
Attribute | Description |
---|---|
|
See page |
|
Contains the array of datamodels to be appended or deleted, see Datamodel description |
Specific Filter Fields
Parameter |
Type |
Description |
|
String |
Identifier of the datamodel |
|
String |
Name of the datamodel |
|
String |
Version of the datamodel |
|
String |
Description of the datamodel |
|
String |
Organization of the datamodel |
|
Array of String |
Array of resourceType allowed, see entities |
|
String |
Category identifier of the datamodel |
|
String |
Category name of the datamodel |
|
String |
Identifier of the datastream |
|
String |
Name of the datastream |
|
String |
Description of the datastream |
|
String enumeration |
One of: |
|
String |
Only used when you want to determinate if a datastream is writeable. The access field can take three values * READ. This is the default value * WRITE * READ,WRITE |
|
String |
Specify the units of time that OpenGate have to consider for deleting historical datapoints, the available values are: * * * * |
|
Amount of period units for considering in the deleting process |
|
|
String |
See tags |
|
String |
The label you want for your unit, see unit object attributes |
|
String |
The symbol you want for your unit, see unit object attributes |
|
String |
The type you want for your unit, see unit object attributes |
|
String |
Used for asociate an icon in the web datastream visualitation, See IoT Datastream Icon Object |
|
Boolean |
It indicates if it is modifiable this datastream |
|
Boolean |
it indicates if it is required for this datastream |
|
Minimum required value |
|
|
String |
Minimum required label |
|
Minimum desired value |
|
|
String |
Minimum desired label |
|
Ideal value |
|
|
String |
Ideal label |
|
Maximum desired value |
|
|
String |
Maximum desired label |
|
Maximum allowed value |
|
|
String |
Maximum allowed value |
|
String |
Version of Qrating |
|
Maximum score |
|
|
Cumulative period divisor. It is used to calculate the performance. The datastream period must be CUMULATIVE. The performance is the difference from the last accumulated measure and the previous one taking this parameter as divisor |
Using curl to perform the request:
curl --request POST \ --data-binary @search-query.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/datamodels \ -H "Content-type: application/json"
Please, take care of the |
{ "filter": { "like": { "datamodels.identifier": "teliot" } } }
{ "datamodels": [ { "identifier": "teliot", "organizationName": "battery_organization", "name": "teliot", "version": "1.0", "description": "Specific Datamodel for battery monitoring", "allowedResourceTypes": [ "entity.device" ], "categories": [ { "identifier": "teliot", "datastreams": [ { "identifier": "batteryPercentage", "name": "batteryPercentage", "description": "Battery percentage number", "period": "INSTANT", "access": "READ", "schema": { "type": "number" }, "storage": { "period": "DAYS", "total": 30 }, "qrating": { "version": "1.0.0", "ideal": { "value": 100 }, "max_allowed": { "value": 100 }, "max_desired": { "value": 100 }, "min_desired": { "value": 15 }, "min_required": { "value": 0 }, "max_score": 1000 }, "tags": [ "inetcounters", "c50", "seat" ], "unit": { "label": "%", "symbol": "%", "type": "basicSI" }, "views": { "edit": [], "show": [] }, "modifiable": true, "calculated": false, "required": false } ] } ] } ], "page": { "number": 1 } }
The option with summary will be available in future versions |
Datapoints
Through OpenGate API it is possible to retrieve the history data associated to a datastream. For more information about it, please see IoT concepts section
URL
Querying over | URI |
---|---|
Datapoints Info |
POST - /north/v80/search/datapoints |
Here, you can see some Searching datapoints examples with filters
Response Format
Using HTTP header option "Accept", the API allows obtaining the result in different formats:
Format | Accept Header Value | ||||
---|---|---|---|---|---|
JSON |
By default if "Accept" header field is not present or "Accept" field has "application/json" value |
||||
CSV |
If "Accept" has "text/plain" value.
|
POST /contacts HTTP/1.1 Accept: application/json HTTP/1.1 200 OK Content-Type: application/json ...
POST /contacts HTTP/1.1 Accept: text/plain HTTP/1.1 200 OK Content-Type: application/json ...
Datapoint objects description
Response is in JSON format including:
Attribute | Description |
---|---|
|
See Page Object |
|
Array of datapoint objects. See Datapoint object definition |
Attribute | Description |
---|---|
channel |
Channel name |
organization |
Organization name |
datastreamId |
Datastream identifier |
entityIdentifier |
Entity identifier |
subEntityIdentifier |
Subentity identifier. It is the identifier of subscriptions or subscribers that are inside the device |
entityRelated |
Identifier of the related asset |
ttl |
Date as string in ISO 8601 format |
_current |
See current object |
Attribute | Description | ||
---|---|---|---|
value |
It is a polyvalent field that supports JSON data types:
"value" : 10
"value" : "string value"
"value" : true
"value" : [ "text1", "text2" ]
"value" : { "field1": "text", "field2": 12 }
"value" : null |
||
date |
Date as string in ISO 8601 format. This field indicates the date of the measurement when arrived at the platform |
||
provType |
Type of provision. Values possibles are MONITORING, IDENTIFIER and REFERENCE. |
||
scoring |
It shows the result of the datapoint qRating calculations, see scoring object |
||
tags(optional) |
Array of tags (in string format) associated to a datapoint. |
||
at |
Date as string in ISO 8601 format. This field indicates the date of the measurement or the date of the finish period of measurement if it exists "from" attribute. |
||
from (optional) |
Date as string in ISO 8601 format. This field indicates the date of the start period of measurement
|
||
feedId |
Feed Identifier see IoT concepts section to learn about its use |
If the datapoint is from the provision then inside the "current object" only has the attributes: value, date and provType |
Attribute | Description |
---|---|
performance |
Number, It shows in percentage value the quality of the data collected |
qrating |
It shows the different values calculated by Qrating algorithm, see qrating object |
Specific Filter Fields
Parameter | Type | Description |
---|---|---|
|
String |
Identifier of the organization |
|
String |
Identifier of the channel |
|
String |
Identifier of datastream, see Defaault Datamodels |
|
String |
Identifier of the entity |
|
String |
Identifier of the related asset |
|
String |
Subidentifier of the entity. It is the identifier of subscriptions or subscribers that are inside the device |
|
Current value |
|
|
String |
Tag of the datastream |
|
String |
Date of storage in the platform of the data collected |
|
String |
Identifier of the feed |
|
String |
This field indicates the date of the measurement (Date on which the data was collected on the device) or the date of the finish period of measurement if it exists "from" attribute. |
|
String |
This field indicates the date of the start period of measurement |
|
Number |
Minimum required value of any device’s datastreams |
|
String |
Minimum required label |
|
Minimum desired value of any device’s datastreams |
|
|
String |
Minimum desired label |
|
Ideal value of any device’s datastreams. |
|
|
String |
Ideal label |
|
Maximum desired value of any device’s datastreams |
|
|
String |
Maximum desired label |
|
Maximum allowed value of any device’s datastreams |
|
|
String |
Maximum allowed label |
|
String |
Version of the Qrating configurated |
|
Maximum score value of any device’s datastreams |
|
|
Cumulative period divisor (calculation of the median velocity of collection against the previous value collected taking this parameter as divisor) |
|
|
Performance of any device’s datastreams. |
Searching datapoints examples
Lets see how to search over your datapoints collection using some of these possible filters
POST /north/v80/search/datapoints
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options).
In both of examples, the filter used is:
{ "filter": { "and": [ { "like": { "datapoints.datastreamId": "batteryPercentage." } }, { "eq": { "datapoints.entityIdentifier": "worker_battery_id" } } ] } }
JSON format
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/datapoints
And this is the response body:
{ "datapoints": [ { "channel": "battery_channel", "organization": "battery_organization", "datastreamId": "batteryPercentage", "entityIdentifier": "device_1ADA8F", "subEntityIdentifier": "device_1ADA8F", "entityRelated": "worker_battery_id", "_current": { "value": 82, "date": "2018-06-04T12:18:11.147+02:00", "scoring": { "qrating": { "version": "1.0.0", "ideal": { "value": 100 }, "max_allowed": { "value": 100 }, "max_desired": { "value": 100 }, "min_desired": { "value": 15 }, "min_required": { "value": 0 }, "max_score": 1000 }, "performance": 89.41176470588235 }, "source": "DEVICE_SIGFOX", "at": "2018-06-04T12:18:10+02:00" } } ], "page": { "number": 1 } }
What about if the response contains thousands of data points? In this case you have to walk through the following pages, see pagination section for further details.
CSV Format
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/datapoints
And this is the response body:
entity;entityRelated;datastream;feed;from;at;value device_1ADA8F;worker_battery_id;batteryPercentage;;;2018-04-13T08:16:05Z;65
Datastreams
Through OpenGate API it is possible to retrieve information associated to a datastream. For more information about it, please see IoT concepts section
Attribute | Description |
---|---|
|
See page |
|
Contains the array of datastreams, see Datastream description |
Attribute | Description |
---|---|
entityIdentifier |
Identifier of the entity of any device’s or feed datastream. Example: device_battery_id |
subEntityIdentifier |
Identifier of the subscription or subscriber that exists inside a device (complete box). Example: subscription_battery_id |
datastreamId |
Identifier of the datastream. Example: health.heart.rate |
name |
Name of the datastream of any device’s datastreams. Example: device_battery_name |
unit |
See unit object attributes |
period |
Period of datastream. Values possible: PULSE, CUMULATIVE, INSTANT |
categoryId |
Identifier of the category. Example: heart |
datamodelId |
Identifier of the datastream. Example: health.heart.rate |
access |
Only used when you want to determinate if a datastream is writeable. The access field can take three values: READ; WRITE; READ,WRITE |
channel |
Channel of the datastream |
organization |
Organization of the datastream |
_current |
See current object |
Attribute | Description |
---|---|
value |
It is a polyvalent field that supports JSON data types:
"value" : 10
"value" : "string value"
"value" : true
"value" : [ "text1", "text2" ]
"value" : { "field1": "text", "field2": 12 }
"value" : null |
date |
Date as string in ISO 8601 format. This field indicates the date of the measurement when arrived in the platform |
provType |
Type of provision. Values possibles are MONITORING, IDENTIFIER and REFERENCE. |
scoring |
It shows the result of the datapoint qRating calculations, see scoring object |
tags(optional) |
Array of tags (in string format) associated to a datapoint. |
at |
Date as string in ISO 8601 format. This field indicates the date of the measurement or the date of the finish period of measurement if it exists "from" attribute. |
from (optional) |
Date as string in ISO 8601 format. This field indicates the date of the start period of measurement |
URL
Querying over | URI |
---|---|
Datastreams Info |
POST - /north/v80/search/datastreams |
Here, you can see some Searching datastreams examples with filters
Specific Filter Fields
Parameter | Type | Description |
---|---|---|
|
String |
Identifier of the entity of any device’s or feed datastream. Example: |
|
String |
Identifier of the subscription or subscriber that exists inside a device (complete box). Example: |
|
String |
Identifier of the feed of any datastream. Example: |
|
String |
Name of the datastream of any device’s datastreams. Example: |
|
String |
Description of the datastream. Example: |
|
Date of the last update of the datastream. |
|
|
String |
Type of unit of any device’s datastream. Example: |
|
String |
Label of unit. Example: |
|
String |
Symbol of unit. Example: |
|
String |
Period of datastream. Values possible: |
|
String |
Tag of any device’s datastreams. Example: |
|
Value of any device’s datastream. Example: |
|
|
String |
Identifier of the datamodel. Example: |
|
String |
Identifier of the category. Example: |
|
String |
Identifier of the datastream. Example: |
|
String |
Version of the datastream. Example: |
|
Minimum required value of any device’s datastreams. Example: |
|
|
String |
Minimum required label. Example: |
|
Minimum desired value of any device’s datastreams. Example: |
|
|
String |
Minimum desired label. Example: |
|
Ideal value of any device’s datastreams. Example: |
|
|
String |
Ideal label. Example: |
|
Maximum desired value of any device’s datastreams. Example: |
|
|
String |
Maximum desired label. Example: |
|
Maximum allowed value of any device’s datastreams. Example: |
|
|
String |
Maximum allowed label. Example: |
|
String |
Version of the Qrating configurated |
|
Maximum score value of any device’s datastreams. Example: |
|
|
Cumulative period divisor (calculation of the median velocity of collection against the previous value collected taking this parameter as divisor) |
|
|
Performance of any device’s datastreams. Example: |
|
|
String |
Channel of the datastream |
|
String |
Organization of the datastream |
Searching datastreams example
Below, an example is shown with the its request using some of these possible filters and its associated response
Using curl to perform the request:
curl --request POST \ --data-binary @search-query.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/datastreams \ -H "Content-type: application/json"
Please, take care of the |
{ "filter": { "eq": { "datastreams.datastreamId": "batteryPercentage" } } }
{ "page": { "number": 1 }, "datastreams": [ { "entityIdentifier": "device_battery_id", "subEntityIdentifier": "subscription_battery_id", "datastreamId": "batteryPercentage", "name": "batteryPercentage", "unit": { "label": "%", "symbol": "%", "type": "basicSI" }, "period": "INSTANT", "categoryId": "teliot", "datamodelId": "teliot", "access": "READ", "channel": "battery_channel", "organization": "battery_organization", "_current": { "value": 100, "date": "2019-04-15T09:18:43.926Z", "scoring": { "qrating": { "version": "1.0.0", "ideal": { "value": 100 }, "max_allowed": { "value": 100 }, "max_desired": { "value": 100 }, "min_desired": { "value": 15 }, "min_required": { "value": 0 }, "max_score": 1000 }, "performance": 100 }, "at": "2019-04-15T09:18:43.926Z" } } ] }
Devices
This API allows retrieveing the list of devices providing a lot of options for:
-
Filter (See Specific Filter Fields)
-
Order (see Sorting)
-
Select Required Fields (see Selecting)
-
Summary (see Summary)
It is possible to obtain the results in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
By the other hand, you can obtain the result in flattened format thanks to flattened parameter (see device parameters)
URL
Querying over | URI |
---|---|
Devices Info (Provisioned and Collected) |
/v80/search/devices |
Devices Summary Info (Provisioned and Collected) |
/v80/search/devices/summary |
Here, you can see some Searching devices examples
URL parameters
-
flattened: It is possible to receive the device data with a flattened json format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to receive a flattened json format
-
utc: It is possible to receive the device data with the date in UTC. In this case, it is sent a boolean parameter, utc, with the value true (utc=true)
Response Format
Using HTTP header option "Accept", the API allows obtaining the result in different formats:
Format | Accept Header Value |
---|---|
JSON |
By default if "Accept" header field is not present or "Accept" field has "application/json" value |
CSV |
If "Accept" has "text/plain" value |
POST /contacts HTTP/1.1 Accept: application/json HTTP/1.1 200 OK Content-Type: application/json ...
POST /contacts HTTP/1.1 Accept: text/plain HTTP/1.1 200 OK Content-Type: application/json ...
Specific Filter Fields
Any parameter of the list included in the device Default Datamodels can be used as filters fields in API search filters, including the custom datastreams.
{ "filter": { "and": [ { "like": { "provision.device.administrativeState": "NORMAL" } }, { "like": { "provision.device.communicationModules[].mobile.imei": "351873000102290" } } ] } }
Specific Select Fields
See predefined profiles section Default Datamodels to know the fields you can use with the select feature.
Summary Information
It is possible to summarize the request, see Summary usage
Devices Search examples
POST /v80/search/devices
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
The date field is transformed by applying the TimeZone of the user who made the request. The format is YYYY-MM-DDThh:mm:ssTZD. If you want obtain the date in UTC, you must add in the url the parameter utc, see example of searching device in UTC |
JSON format This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices
And this is the response body:
{ "page": { "number": 1 }, "devices": [ { "resourceType": { "_current": { "value": "entity.device", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.643Z" } }, "provision": { "device": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.636Z" } }, "serialNumber": { "_current": { "value": "device_battery_sn", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.628Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.643Z" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.64Z" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } }, "specificType": { "_current": { "value": "UMTS", "provType": "MONITORING", "date": "2017-12-01T08:52:37.599Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.597Z" } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.626Z" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-12-01T08:52:37.624Z" } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.615Z" } }, "msisdn": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-12-01T08:52:37.61Z" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-01T08:52:37.611Z" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-01T08:52:37.613Z" } } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.621Z" } }, "description": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.618Z" } }, "specificType": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.607Z" } }, "name": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.616Z" } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.586Z" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-12-01T08:52:37.59Z" } } }, "name": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.583Z" } }, "description": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.582Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.589Z" } }, "specificType": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-12-01T08:52:37.58Z" } } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei", "provType": "MONITORING", "date": "2017-12-01T08:52:37.594Z" } } }, "name": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.592Z" } }, "description": { "_current": { "value": "commsMod_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.604Z" } } } ], "description": { "_current": { "value": "device_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.571Z" } }, "operationalStatus": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2017-12-01T08:52:37.576Z" } }, "specificType": { "_current": { "value": "MODEM", "provType": "MONITORING", "date": "2017-12-01T08:52:37.633Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.631Z" } }, "name": { "_current": { "value": "device_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.573Z" } } }, "administration": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.57Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-01T08:52:37.563Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-01T08:52:37.566Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-01T08:52:37.561Z" } }, "plan": { "_current": { "value": "FLOW_RATE_100", "provType": "MONITORING", "date": "2017-12-01T08:52:37.565Z" } } } } } ] }
CSV Format
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/devices
It must be used a filter with the select clause because is obligatory for the csv format, see Selecting
{ "select": [ { "name": "provision.device.identifier", "fields": [ { "field": "value", "alias": "id" } ] }, { "name": "provision.device.location", "fields": [ { "field": "value", "alias": "location" } ] } ] }
provision.administration.channel.value;provision.administration.identifier.value;provision.administration.organization.value;id.value;location.value battery_channel;device_battery_id;battery_organization;device_battery_id;{position={coordinates=[-3.7028, 40.41675], type=Point}, postal=28013}
POST /north/v80/search/devices?utc=true
It allows to obtain the date in UTC. It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
The date field is transformed by applying the TimeZone of the user who made the request. |
JSON format
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices
And this is the response body:
{ "page": { "number": 1 }, "devices": [ { "resourceType": { "_current": { "value": "entity.device", "provType": "IDENTIFIER", "date": "2018-06-20T12:59:58.463Z" } }, "provision": { "device": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "serialNumber": { "_current": { "value": "device_battery_sn", "provType": "IDENTIFIER", "date": "2018-06-20T12:59:58.463Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "UMTS", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2018-06-20T12:59:58.463Z" } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2018-06-20T12:59:58.463Z" } }, "msisdn": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "description": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "name": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "name": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "description": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "name": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "description": { "_current": { "value": "commsMod_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } } ], "description": { "_current": { "value": "device_battery_description", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "operationalStatus": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "specificType": { "_current": { "value": "MODEM", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "name": { "_current": { "value": "device_battery_name", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } }, "administration": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } }, "plan": { "_current": { "value": "FLOW_RATE_100", "provType": "MONITORING", "date": "2018-06-20T12:59:58.463Z" } } } } } ] }
CSV Format
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/devices
if you want only return devices, the used filter must contain entity.device as resourceType (see Filtering) and also the select clause because is obligatory for the csv format, see <<search_select, Selecting
{ "filter": { "and": [ { "like": { "resourceType": "entity.device" } } ] }, "select": [ { "name": "provision.device.identifier", "fields": [ { "field": "value" } ] }, { "name": "provision.device.location", "fields": [ { "field": "date", "alias": "locationDate" } ] } ] }
provision.device.identifier.value;locationDate device_battery_id;2018-03-22T19:30:26.329+01:00
POST /north/v80/search/devices?flattened=true
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices?flattened=true
And this is the response body:
{ "devices": [ { "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "coordinates": [ -3.7028, 40.41675 ], "type": "Point" }, "postal": "28013" } } } } } ], "page": { "number": 1 } }
POST /v80/search/devices/summary
By default the summary always shows the total counter and the organizations grouping counter and channel grouping counter, see Grouping
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/devices/summary
The response body could be something like this:
{ "summary": { "count": 1, "summaryGroup": [ { "provision.administration.channel": { "count": 1, "list": [ { "count": 1, "name": "battery_channel" } ] } }, { "provision.administration.organization": { "count": 1, "list": [ { "count": 1, "name": "battery_organization" } ] } } ] } }
Domains
The OpenGate API query allows to obtain the available domains provisioned under the domain of the user that sends the request.
URL
Type of Information | URL |
---|---|
Domains provisioned in the platform |
/north/v80/search/domains |
Summary of the Domains provisioned in the platform |
/north/v80/search/domains/summary |
URL parameters
Using summary parameter in the URL request, "/north/v80/search/domains?summary=<value>" where <value> can be:
-
true: The response includes the summary object.
-
false (default): The same behavior when the parameter is not present. The summary object is not included in the response
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
name |
name of the domain |
string |
description |
description of the domain |
string |
parentDomain |
parentDomain name of the domain |
string |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
Examples
An example of response could be something like this
{ "domains": [ { "name": "Domain_1_1", "description": "Domain description" }, { "name": "Domain_1_1_2", "description": "Domain description" } ] }
{ "page":{ "number":1, "of":1 }, "summary": { "count": 2 }, "domains": [ { "name": "Domain_1_1", "description": "Domain description" }, { "name": "Domain_1_1_2", "description": "Domain description" } ] }
{ "summary": { "count": 2 } }
Entities
An entity is all monitoring element inside IoT world.
The platform offers four types of entities (asset, device, subscription and subscriber) and distinguishes between them, thanks to the resourceType attribute.
You can search through the generic url for each entity (see entity generic urls) or through the particular url for a determined entity (device, subscription and subscriber). In the following table you can see how is searched for this last case.
Entity | ResourceType attribute | Description | Search |
---|---|---|---|
Device |
entitiy.device |
It represents a hardware unit |
|
Subscription |
entity.subscription |
It stores information regarding the contracts with your communication operators |
|
Subscriber |
entity.subscriber |
It stores information regarding a specific communication channel |
The asset entity uses the generic url (see search of assets), for this reason is not included in the above table |
This search entities API allows retrieveing the list of entities providing a lot of options for:
-
Filter (See Specific Filter Fields)
-
Order (see Sorting)
-
Select Required Fields (see Selecting)
-
Summary (see Summary)
If you want to use the generic url to obtain data for each entity type (asset, device, subscription, subscriber), you must add the resource type in the filter
{ "filter": { "and": [ { "like": { "resourceType": "entity.device" } } ] } }
It is possible to obtain the results in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
By the other hand, you can obtain the result in flattened format thanks to flattened parameter (see entity parameters)
URL
Querying over | URI |
---|---|
Entity Info |
/v80/search/entities |
Entity Summary Info |
/v80/search/entities/summary |
Here, you can see some Searching entities examples
URL parameters
-
flattened: It is possible to receive the entity data with a flattened json format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to receive a flattened json format
Response Format
Using HTTP header option "Accept", the API allows obtaining the result in different formats:
Format | Accept Header Value |
---|---|
JSON |
By default if "Accept" header field is not present or "Accept" field has "application/json" value |
CSV |
If "Accept" has "text/plain" value |
POST /contacts HTTP/1.1 Accept: application/json HTTP/1.1 200 OK Content-Type: application/json ...
POST /contacts HTTP/1.1 Accept: text/plain HTTP/1.1 200 OK Content-Type: application/json ...
Specific Filter Fields
Any parameter of the list included in the Default Datamodels can be used as filters fields in API search filters, including the custom datastreams.
Here’s a possible filter for entities .filtering by entity
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } }, { "like": { "provision.asset.administrativeState": "READY" } } ] } }
Specific Select Fields
It is possible to select some determined fields, see Searching Select usage
Summary Information
It is possible to summarize the request, see Summary usage
Entities Search examples
Below are shown different examples with the its request and associated response for each use case
POST /north/v80/search/entities
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
JSON format
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities
And this is the response body:
{ "page": { "number": 1 }, "entities": [ { "resourceType": { "_current": { "value": "entity.asset", "provType": "IDENTIFIER", "date": "2017-12-01T08:47:44.843Z" } }, "provision": { "asset": { "identifier": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.843Z" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-12-01T08:47:44.833Z" } }, "name": { "_current": { "value": "Antonio Pérez", "provType": "MONITORING", "date": "2017-12-01T08:47:44.839Z" } }, "administrativeState": { "_current": { "value": "READY", "provType": "MONITORING", "date": "2017-12-01T08:47:44.835Z" } }, "description": { "_current": { "value": "battery worker", "provType": "MONITORING", "date": "2017-12-01T08:47:44.84Z" } }, "specificType": { "_current": { "value": "WORKER", "provType": "MONITORING", "date": "2017-12-01T08:47:44.837Z" } } }, "administration": { "identifier": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.83Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-01T08:47:44.826Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-01T08:47:44.827Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-01T08:47:44.824Z" } } } } }, { "resourceType": { "_current": { "value": "entity.device", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.643Z" } }, "provision": { "device": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.636Z" } }, "serialNumber": { "_current": { "value": "device_battery_sn", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.628Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.643Z" } }, "location": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.64Z" } }, "communicationModules": [ { "identifier": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } }, "specificType": { "_current": { "value": "UMTS", "provType": "MONITORING", "date": "2017-12-01T08:52:37.599Z" } }, "model": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.597Z" } }, "subscription": { "identifier": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.626Z" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-12-01T08:52:37.624Z" } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.615Z" } }, "msisdn": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-12-01T08:52:37.61Z" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-01T08:52:37.611Z" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-01T08:52:37.613Z" } } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.621Z" } }, "description": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.618Z" } }, "specificType": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.607Z" } }, "name": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.616Z" } } }, "subscriber": { "identifier": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.586Z" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-12-01T08:52:37.59Z" } } }, "name": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.583Z" } }, "description": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.582Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.589Z" } }, "specificType": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-12-01T08:52:37.58Z" } } }, "mobile": { "imei": { "_current": { "value": "commsMod_battery_imei", "provType": "MONITORING", "date": "2017-12-01T08:52:37.594Z" } } }, "name": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.592Z" } }, "description": { "_current": { "value": "commsMod_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.604Z" } } } ], "description": { "_current": { "value": "device_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.571Z" } }, "operationalStatus": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2017-12-01T08:52:37.576Z" } }, "specificType": { "_current": { "value": "MODEM", "provType": "MONITORING", "date": "2017-12-01T08:52:37.633Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.631Z" } }, "name": { "_current": { "value": "device_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.573Z" } } }, "administration": { "identifier": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.57Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-01T08:52:37.563Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-01T08:52:37.566Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-01T08:52:37.561Z" } }, "plan": { "_current": { "value": "FLOW_RATE_100", "provType": "MONITORING", "date": "2017-12-01T08:52:37.565Z" } } } } } ] }
CSV Format
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/entities
On the csv format, the filter always must contain the select clause, see Selecting
if you want only return entities, the filter used should be something like
{ "filter": { "and": [ { "like": { "resourceType": "entity.asset" } } ] }, "select": [ { "name": "provision.administration.identifier", "fields": [ { "field": "value", "alias": "adm_id" } ] }, { "name": "provision.asset.identifier", "fields": [ { "field": "value", "alias": "asset_id" } ] }, { "name": "provision.asset.location", "fields": [ { "field": "value", "alias": "location" } ] } ] }
provision.administration.channel.value;adm_id.value;provision.administration.organization.value;asset_id.value;location.value battery_channel;worker_battery_id;battery_organization;worker_battery_id;{position={type=Point, coordinates=[-3.7028, 40.41675]}, postal=28013}
POST /north/v80/search/entities?flattened=true
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities?flattened=true
The response body could be something like this:
{ "entities": [ { "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-01T08:47:44.826Z" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.83Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-01T08:47:44.827Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-01T08:47:44.824Z" } } }, "provision.asset.administrativeState": { "_value": { "_current": { "value": "READY", "provType": "MONITORING", "date": "2017-12-01T08:47:44.835Z" } } }, "provision.asset.description": { "_value": { "_current": { "value": "battery worker", "provType": "MONITORING", "date": "2017-12-01T08:47:44.84Z" } } }, "provision.asset.identifier": { "_value": { "_current": { "value": "worker_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:47:44.843Z" } } }, "provision.asset.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-12-01T08:47:44.833Z" } } }, "provision.asset.name": { "_value": { "_current": { "value": "Antonio Pérez", "provType": "MONITORING", "date": "2017-12-01T08:47:44.839Z" } } }, "provision.asset.specificType": { "_value": { "_current": { "value": "WORKER", "provType": "MONITORING", "date": "2017-12-01T08:47:44.837Z" } } }, "resourceType": { "_value": { "_current": { "value": "entity.asset", "provType": "IDENTIFIER", "date": "2017-12-01T08:47:44.843Z" } } } }, { "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-01T08:52:37.563Z" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.57Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-01T08:52:37.566Z" } } }, "provision.administration.plan": { "_value": { "_current": { "value": "FLOW_RATE_100", "provType": "MONITORING", "date": "2017-12-01T08:52:37.565Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-01T08:52:37.561Z" } } }, "provision.device.administrativeState": { "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.631Z" } } }, "provision.device.communicationModules[].description": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "commsMod_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.604Z" } } } ], "provision.device.communicationModules[].identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } } ], "provision.device.communicationModules[].mobile.imei": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "commsMod_battery_imei", "provType": "MONITORING", "date": "2017-12-01T08:52:37.594Z" } } } ], "provision.device.communicationModules[].model": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.597Z" } } } ], "provision.device.communicationModules[].name": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "commsMod_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.592Z" } } } ], "provision.device.communicationModules[].specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "UMTS", "provType": "MONITORING", "date": "2017-12-01T08:52:37.599Z" } } } ], "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.589Z" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.582Z" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscriber_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.586Z" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-12-01T08:52:37.59Z" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.583Z" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-12-01T08:52:37.58Z" } } } ], "provision.device.communicationModules[].subscription.address": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-12-01T08:52:37.624Z" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.621Z" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.618Z" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscription_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.626Z" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-01T08:52:37.613Z" } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.615Z" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-12-01T08:52:37.61Z" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-01T08:52:37.611Z" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.616Z" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier", "value": { "_current": { "value": "commsMod_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.577Z" } } }, "_value": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-12-01T08:52:37.607Z" } } } ], "provision.device.description": { "_value": { "_current": { "value": "device_battery_description", "provType": "MONITORING", "date": "2017-12-01T08:52:37.571Z" } } }, "provision.device.identifier": { "_value": { "_current": { "value": "device_battery_id", "provType": "MONITORING", "date": "2017-12-01T08:52:37.636Z" } } }, "provision.device.location": { "_value": { "_current": { "value": { "position": { "type": "Point", "coordinates": [ -3.7028, 40.41675 ] }, "postal": "28013" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.64Z" } } }, "provision.device.model": { "_value": { "_current": { "value": { "name": "OpenGate", "version": "1.0", "manufacturer": "OpenGate" }, "provType": "MONITORING", "date": "2017-12-01T08:52:37.643Z" } } }, "provision.device.name": { "_value": { "_current": { "value": "device_battery_name", "provType": "MONITORING", "date": "2017-12-01T08:52:37.573Z" } } }, "provision.device.operationalStatus": { "_value": { "_current": { "value": "NORMAL", "provType": "MONITORING", "date": "2017-12-01T08:52:37.576Z" } } }, "provision.device.serialNumber": { "_value": { "_current": { "value": "device_battery_sn", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.628Z" } } }, "provision.device.specificType": { "_value": { "_current": { "value": "MODEM", "provType": "MONITORING", "date": "2017-12-01T08:52:37.633Z" } } }, "resourceType": { "_value": { "_current": { "value": "entity.device", "provType": "IDENTIFIER", "date": "2017-12-01T08:52:37.643Z" } } } } ], "page": { "number": 1 } }
POST /north/v80/search/entities/summary
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/entities/summary
The response body could be something like this:
{ "summary": { "count": 2, "summaryGroup": [ { "provision.administration.channel": { "count": 2, "list": [ { "count": 2, "name": "battery_channel" } ] } }, { "provision.administration.organization": { "count": 2, "list": [ { "count": 2, "name": "battery_organization" } ] } } ] } }
Feeds
A feed is defined like the diferent user of a device, you can create a feed when you want to use the same device for making different measures that you want to have grouped. For more information about it, please see IoT concepts section
Attribute | Description |
---|---|
|
Page Object As described in above |
|
Number with the count of feeds retrieved |
|
An array of feeds objects. See Feed object definition |
Feed object description
Attribute | Description |
---|---|
id |
String, unique within the organization, alphanumeric identifier following unreserved URI characters defined in RFC-3986: ALPHA / DIGIT / "-" / "." / "$$_$$" / "\~" |
device |
Device Identifier see IoT concepts section to learn about its use |
Specific Filter Fields
Parameter | Description |
---|---|
|
String. Filter list result by |
|
String. Filter list result by |
Retrieve feeds filtering
Lets see how to retrieve a single feed identified by its id
attribute. In the example below we’re going to use feed_1
as value of the id
attribute.
Using curl to perform the request:
curl --request POST \ --data-binary @search-query.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/feeds \ -H "Content-type: application/json"
Please, take care of the |
{ "filter": { } }
{ "filter": { "eq": { "feed.id": "feed_1" } } }
{ "feeds": [ { "id" : "Feed_1", "device" : "Device_1" } ] }
If you request a non existing feed you’ll obtain an error. See error codes section |
Attending to the feed and device identifiers, it can be retrieved several feeds with the same feed.id value. They are corresponding with the way the values are collected. See examples in the in the IoT concepts section. |
Lets see how to search over your feed data collection using device identifier.
Example: retrieve filtered feed collected from device_1
The JSON filter object will be:
{ "filter": { "and": [ { "eq": { "feed.deviceId": "device_1" } } ] } }
and the CURL base request:
curl --request POST \ --data-binary @search-query.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/datastreams \ -H "Content-type: application/json"
{ "feeds": [ { "id" : "Feed_1", "device" : "Device_1" } ] }
The option with summary will be available in future versions |
Hardware (Manufacturer and Model)
The OpenGate API query allows to obtain the data stored in the database relating to both the manufacturer and each related models.
As in the case of entities, there is a specific option for consulting Manufacturer an model.
URL
Type of Information | URL |
---|---|
Model and their Manufacturers catalogued in the platform |
/north/v80/search/catalog/hardwares |
Model and their Manufacturers summary catalogued in the platform |
/north/v80/search/catalog/hardwares/summary |
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
manufacturerName |
manufacturerName |
string |
manufacturerIdentifier |
manufacturerIdentifier |
string |
manufacturerTelephone |
manufacturerTelephone |
string |
manufacturerMail |
manufacturerMail |
string |
manufacturerAddress |
manufacturerAddress |
string |
manufacturerFax |
manufacturerFax |
string |
manufacturerUrl |
manufacturerUrl |
string |
manufacturerNotes |
manufacturerNotes |
string |
manufacturerDescription |
manufacturerDescription |
string |
manufacturerMediaIdentifier |
manufacturerMediaIdentifier |
string |
manufacturerMediaName |
manufacturerMediaName |
string |
manufacturerMediaName |
manufacturerMediaName |
string |
manufacturerMediaFileName |
manufacturerMediaFileName |
string |
manufacturerMediaTypeName |
manufacturerMediaTypeName |
string |
manufacturerMediaSize |
manufacturerMediaSize |
string |
manufacturerMediaWidth |
manufacturerMediaWidth |
string |
manufacturerMediaHeight |
manufacturerMediaHeight |
string |
modelIdentifier |
modelIdentifier |
string |
modelName |
modelName |
string |
modelVersion |
modelVersion |
string |
modelNotes |
modelNotes |
string |
modelDescription |
modelDescription |
string |
modelUrl |
modelUrl |
string |
modelMediaIdentifier |
modelMediaIdentifier |
string |
modelMediaName |
modelMediaName |
string |
modelMediaName |
modelMediaName |
string |
modelMediaFileName |
modelMediaFileName |
string |
modelMediaTypeName |
modelMediaTypeName |
string |
modelMediaSize |
modelMediaSize |
string |
modelMediaWidth |
modelMediaWidth |
string |
modelMediaHeight |
modelMediaHeight |
string |
For searching hardware, you only can use the fields defined in the section "Available fields to include in the "WHERE" clause" |
Summary Information
Entity | Constraint |
---|---|
manufacturer |
|
model |
Hardware Structure
For getting the manufacturer and model structure of the platform the JSON response has the next format
Entity | Constraint |
---|---|
manufacturer |
see object collection bellow |
model |
see object collection bellow |
Entity | Constraint |
---|---|
name |
String |
url |
String |
notes |
String |
description |
String |
telephone |
String |
String |
|
address |
String |
fax |
String |
media |
string. See media object below |
model |
string. See media object below |
Entity | Constraint |
---|---|
name |
string |
version |
string |
notes |
string |
description |
string |
url |
string |
media |
string. See media object below |
Entity | Constraint |
---|---|
name |
string |
id |
string |
filename |
string |
type |
string |
size |
string |
type |
string |
dimension |
string. See dimension object below |
Entity | Constraint |
---|---|
width |
number |
height |
number |
An example could be something like this
{ "manufacturer": [ { "name": "OpenGate", "url": "www.amplia-iiot.com/", "notes": "Notes for OpenGate manufacturer", "description": "Description for OpenGate manufacturer", "telephone": "+0034911126747", "email": "info@amplia.es", "address": "Golfo de Salonica 27, 1ª 28033 Madrid Spain", "media": [ { "name": "image1", "type": "image/png", "filename": "LogoOpenGate.jpg", "size": 256, "dimension": { "width": 572, "height": 572 } } ], "models": [ { "name": "OpenGate", "id": "OpenGate", "version": "1.0", "url": "www.opengatemodel-connect.com", "notes": "Notes for OpenGate Model", "description": "Description for OpenGate Model", "media": [ { "name": "image2", "type": "image/png", "filename": "LogoOpenGate.jpg", "size": 256, "dimension": { "width": 572, "height": 572 } } ] } ] } ] }
you can view the special fields for searching hardware in the table Filter fields for searching hardware |
{ "summary": { "count": 2, "model": { "count": 3, "list": [ { "name": "OpenGateWebSocket", "count": 1 }, { "name": "OpenGateSecure", "count": 1 }, { "name": "OpenGate", "count": 1 } ] }, "manufacturer": { "count": 2, "list": [ { "name": "GENERICO", "count": 1 }, { "name": "OpenGate", "count": 1 } ] } } }
Jobs
The OpenGate searching API also allows recover the jobs that have been launched.
It is important to note that this API query returns: All Jobs not jet finished, and all finished Jobs within the maximum history period configured in the platform (by default 30 days. Please consult to your platform administrator to know this period value) |
URL
Type of Information | URL |
---|---|
Jobs Information |
/north/v80/search/jobs |
Jobs Summary |
/north/v80/search/jobs/summary |
URL parameters
There are not specific parameters applicable to this URLs
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
jobId |
job.id |
string |
operationName |
operation.name |
string |
jobStatus |
job.status |
string. See Job Status Enumeration |
jobUser |
job.user |
string |
jobErrorCode |
job.errorCode |
string |
jobErrorDescription |
job.errorDescription |
string |
jobUserNotes |
job.userNotes |
string |
jobCallback |
job.Callback |
string |
jobActivatedDate |
job.activatedDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
jobStartedDate |
job.startedDate |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
jobFinishedDate |
job.finishedDate |
The format is YYYY-MjM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Field name | field name in where clause | type |
---|---|---|
jobFInishedSuccessfull |
job.finished.successful |
integer |
jobFInishedError |
job.finished.error |
integer |
jobFInishedCancelledTotal |
job.finished.cancelled.total |
integer |
jobFInishedByEngine |
job.finished.cancelled.byEngine |
integer. Allows filtering Jobs that have a number of Operations cancelled by the platform |
jobFInishedByUser |
job.finished.cancelled.byUser |
integer. Allows filtering Jobs that have a number of Operations cancelled by an user |
jobFInishedByTimeout |
job.finished.cancelled.byTimeout |
integer. Allows filtering Jobs that have a number of Operations cancelled by a platform Timeout |
jobFInishedByExternalTimeout |
job.finished.cancelled.byExternalTimeout |
integer. Allows filtering Jobs that have a number of Operations cancelled by an external timeout (example: device timeout) |
jobFInishedByExternal |
job.finished.cancelled.byExternal |
integer. Allows filtering Jobs that have a number of Operations cancelled by an external cause (example: by a device cancellation) |
For Jobs, you only can use the fields defined in the section "Available fields to include in the "WHERE" clause" |
Only finished Jobs allow filtering by JobFinishedStatus |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
["SpecificObjectName"]. Entity specific JSON objects list |
See Summarized Elements Structure. You can also see the specific objects in the section to each searching of entity |
Entity | Constraint |
---|---|
name |
|
status |
See Summarized Specific Object Operations StructureSee also Job Status Enumeration |
Entity | Constraint |
---|---|
count |
number of occurrences found of this specific element |
list |
Array of each type of Summarized Element Structure |
Entity | Constraint |
---|---|
count |
number of these specific elements found |
name |
name of the summarized element |
Response structure
The JSON response has the same format
Entity | Constraint |
---|---|
jobs[] |
see Job structure below |
Attributes | Description |
---|---|
id |
Job identifier. |
task_id |
Identifier of the task, this field can be null if the job doesn’t belong to a task |
request |
|
report |
In both cases request and report objects there is not included target structure |
The complete report object summary (with report.summary.finished object) will be only returned when the Job is in finished status |
An example for device could be something like this, the result of the API will be the different operations for two devices
{ "page":{ "number":3, "of":7 }, "summary": { "count": 90, "name": { "count": 101, "list": [ { "count": 24, "name": "REFRESH_LOCATION" }, { "count": 19, "name": "REFRESH_INFO" }, { "count": 58, "name": "REBOOT_EQUIPMENT" } ] }, "status": { "count": 101, "list": [ { "count": 21, "name": "FINISHED" }, { "count": 22, "name": "SCHEDULED" }, { "count": 58, "name": "TIMEOUT_CANCELLED" } ] } }, "jobs":[ { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "task_id":"task_1", "request" : { "name" : "REBOOT_EQUIPMENT", "parameters": { "TYPE" : "HARDWARE" }, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "started": 0 }, "finished": { "total": 2, "successful": 1, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 1, "successful": 1, "error": 0 } } } }, { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "request" : { "name" : "REFRESH_INFO", "parameters": { "TYPE" : "HARDWARE" }, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "started": 0 }, "finished": { "successful": 1, "total": 2, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 1, "successful": 1, "error": 0 } } } }, { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "request" : { "name" : "REFRESH_INFO", "parameters": {}, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "" }, "summary": { "status": "IN_PROGRESS", "total": 3 } } }, { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "request" : { "name" : "REFRESH_INFO", "parameters": {}, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "" }, "summary": { "status": "IN_PROGRESS", "total": 3 } } } ] }
{ "jobs":[ { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "task_id":"task_1", "request" : { "name" : "REBOOT_EQUIPMENT", "parameters": { "TYPE" : "HARDWARE" }, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "started": 0 }, "finished": { "total": 2, "successful": 1, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 1, "successful": 1, "error": 0 } } } }, { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "request" : { "name" : "REFRESH_INFO", "parameters": { "TYPE" : "HARDWARE" }, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "started": 0 }, "finished": { "successful": 1, "total": 2, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 1, "successful": 1, "error": 0 } } } }, { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "request" : { "name" : "REFRESH_INFO", "parameters": {}, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "" }, "summary": { "status": "IN_PROGRESS", "total": 3 } } }, { "id":"397dae95-8cbe-41c6-b98e-17b875f817e2", "request" : { "name" : "REFRESH_INFO", "parameters": {}, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "" }, "summary": { "status": "IN_PROGRESS", "total": 3 } } } ] }
An example for summary of jobs could be something like this
{ "summary": { "count": 90, "name": { "count": 101, "list": [ { "count": 24, "name": "REFRESH_LOCATION" }, { "count": 19, "name": "REFRESH_INFO" }, { "count": 58, "name": "REBOOT_EQUIPMENT" } ] }, "status": { "count": 101, "list": [ { "count": 21, "name": "FINISHED" }, { "count": 22, "name": "SCHEDULED" }, { "count": 58, "name": "TIMEOUT_CANCELLED" } ] } } }
you can view the special fields for searching jobs in the table Filter fields for searching jobs |
Operations
The OpenGate searching API also allows recover the operations that have been made to a particular entity, by the power offered by the search options it’s possible to recover all the operations that have been performed e.g. for a particular manufacturer over an entity determined.
As in the case of entities, there is a specific option for consulting operations for each of the types of entities, in all four cases the response is similar as the format operation is common for all of them.
Is important to note that this API query returns: All operations not jet finished, and all finished operations within the maximum history period configured in the platform (by default 30 days. Please consult to your platform administrator to know this period value) |
URLs
Type of Information | URL |
---|---|
Currently performed Operations on the devices |
/north/v80/search/entities/devices/operations |
Currently performed summary of operations on the devices |
/north/v80/search/entities/devices/operations/summary |
Currently performed Operations on the subscribers |
/north/v80/search/entities/subscribers/operations |
Currently performed summary of operations on the subscribers |
/north/v80/search/entities/subscribers/operations/summary |
Currently performed Operations on the subscriptions |
/north/v80/search/entities/subscriptions/operations |
Currently performed summary or operations on the subscriptions |
/north/v80/search/entities/subscriptions/operations/summary |
Currently performed Operations on the Communication Modules |
/north/v80/search/entities/communicationsModules/operations |
Currently performed summary of operations on the Communication Modules |
/north/v80/search/entities/communicationsModules/operations/summary |
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
operationId (single operation_identifier) |
operationId |
string |
name (operation type) |
operation.name |
string |
status (operation state) |
operation.status |
string |
operationStepName |
operation.stepName |
string |
operationStepResult |
operation.stepResult |
string |
operationStepDescription |
operation.stepDescription |
string |
result |
operation.result |
string |
notify |
operation.notify |
string |
operationDate |
operation.date |
The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
jobId |
operation.jobId |
string |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
["SpecificObjectName"]. Entity specific JSON objects list |
See Summarized Elements Structure. You can also see the specific objects in the section to each searching of entity |
Entity | Constraint |
---|---|
name |
See Summarized Specific Object Operations Structure. Visit the Available Operation Types section for getting more information about the different operation types. |
result |
See Summarized Specific Object Operations Structure and see Operation Result Enumeration |
status |
See Summarized Specific Object Operations Structure and see Operation Status Enumeration |
Entity | Constraint |
---|---|
count |
number of occurrences found of this specific element |
list |
Array of each type of Summarized Element Structure |
Entity | Constraint |
---|---|
count |
number of these specific elements found |
name |
name of the summarized element |
This summary is valid for all type of entities |
There is not included the field "type" of the summarized element |
Response structure
For device, subscription, subscriber and communication module operations the JSON response has the same format
Entity | Constraint |
---|---|
operations[] |
see object collection bellow |
Attributes | Description |
---|---|
jobId |
Operation group identifier. |
entityId |
Entity identifier |
entityType |
|
operationId |
Single operation identifier. |
name |
Operation name. |
parameters |
Operation parameters. See Parameter Object |
attemps |
Number of retries execution of an operation. See Attempts Object |
notify |
Notification settings, valid values: * true * false |
execution |
see Execution Object |
user |
Identifies the user that has launched the operation |
status |
|
result |
|
description |
string. Completed by some device connectors to describe the result of the operation |
steps[] |
Attributes | Constraints | Description |
---|---|---|
activatedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when operation is activated |
startedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when operation execution is started |
finishedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when operation is finished |
Attributes | Description |
---|---|
total |
Total number of attempts programmed. |
current |
Attempt number in witch the operation had been executed. |
An example for device could be something like this, the result of the API will be the different operations for two devices
{ "page":{ "number":3, "of":7 }, "summary": { "count": 90, "name": { "count": 101, "list": [ { "count": 24, "name": "REFRESH_LOCATION" }, { "count": 19, "name": "REFRESH_INFO" }, { "count": 58, "name": "REBOOT_EQUIPMENT" } ] }, "result": { "count": 79, "list": [ { "count": 21, "name": "SUCCESSFUL" }, { "count": 58, "name": "ERROR_TIMEOUT" } ] }, "status": { "count": 101, "list": [ { "count": 21, "name": "FINISHED" }, { "count": 22, "name": "PENDING" }, { "count": 58, "name": "TIMEOUT_CANCELLED" } ] } }, "operations":[ { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_1", "entityType" : "GATEWAY", "operationId":"6ab1697e-c9ae-46f7-881b-e23ecc67ae10", "name":"RESET_EQUIPMENT", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"2012-09-11T13:02:41Z" }, "attempts": { "total": 1, "current": 1 }, "notify":false, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "result":"SUCCESSFUL", "description": "successful operation", "step":[ { "name":"EQUIPMENT_DIAGNOSTICS", "result":"SUCCESSFUL", "description":"test ws step1" } ] }, { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_1", "entityType" : "GATEWAY", "operationId":"d0d8cfee-9e81-4293-acd5-96b05d6c3443", "name":"REFRESH_LOCATION", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"2012-09-11T13:02:41Z" }, "attempts": { "total": 1, "current": 1 }, "notify":true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "description": "successful operation" } { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_2", "entityType" : "GATEWAY", "operationId":"1c4f2dc3-07fe-4f97-a517-362e8ab5385a", "name":"RESET_EQUIPMENT", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"2012-09-11T13:02:41Z" }, "attempts": { "total": 1, "current": 1 }, "notify":false, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "result":"SUCCESSFUL", "description": "successful operation", "step":[ { "name":"EQUIPMENT_DIAGNOSTICS", "result":"SUCCESSFUL", "description":"test ws step1" } ] }, { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_2", "entityType" : "GATEWAY", "operationId":"ad4b4414-a4fe-40a9-9b44-4a981c707292", "name":"REFRESH_LOCATION", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"2012-09-11T13:02:41Z" }, "attempts": { "total": 1, "current": 1 }, "notify":true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "description": "successful operation" } ] }
{ "operations":[ { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_1", "entityType" : "GATEWAY", "operationId":"6ab1697e-c9ae-46f7-881b-e23ecc67ae10", "name":"RESET_EQUIPMENT", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"2012-09-11T13:02:41Z" }, "attempts": { "total": 1, "current": 1 }, "notify":false, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "result":"SUCCESSFUL", "description": "successful operation", "step":[ { "name":"EQUIPMENT_DIAGNOSTICS", "result":"SUCCESSFUL", "description":"test ws step1" } ] }, { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_1", "entityType" : "GATEWAY", "operationId":"d0d8cfee-9e81-4293-acd5-96b05d6c3443", "name":"REFRESH_LOCATION", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"" }, "attempts": { "total": 1, "current": 1 }, "notify":true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "description": "successful operation" } { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_2", "entityType" : "GATEWAY", "operationId":"1c4f2dc3-07fe-4f97-a517-362e8ab5385a", "name":"RESET_EQUIPMENT", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"2012-09-11T13:02:41Z" }, "attempts": { "total": 1, "current": 1 }, "notify":false, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "result":"SUCCESSFUL", "description": "successful operation", "step":[ { "name":"EQUIPMENT_DIAGNOSTICS", "result":"SUCCESSFUL", "description":"test ws step1" } ] }, { "jobId":"397dae95-8cbe-41c6-b98e-17b875f817e2", "entityId":"device_2", "entityType" : "GATEWAY", "operationId":"ad4b4414-a4fe-40a9-9b44-4a981c707292", "name":"REFRESH_LOCATION", "parameters":{ "equipmentType":"Hardware", "equipmentDate":"2012-09-11T13:02:41Z" }, "attempts": { "total": 1, "current": 1 }, "notify":true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status":"FINISHED", "description": "successful operation" } ] }
An example for summary of device operations could be something like this
{ "page":{ "number":3, "of":7 }, "summary": { "count": 90, "name": { "count": 101, "list": [ { "count": 24, "name": "REFRESH_LOCATION" }, { "count": 19, "name": "REFRESH_INFO" }, { "count": 58, "name": "REBOOT_EQUIPMENT" } ] }, "result": { "count": 79, "list": [ { "count": 21, "name": "SUCCESSFUL" }, { "count": 58, "name": "ERROR_TIMEOUT" } ] }, "status": { "count": 101, "list": [ { "count": 21, "name": "FINISHED" }, { "count": 22, "name": "SCHEDULED" }, { "count": 58, "name": "TIMEOUT_CANCELLED" } ] } } }
you can view the special fields for searching executed operations in the table Filter fields for searching executed operations |
Operation Types
The OpenGate API query allows to obtain the available operations to be executed through the Operation API.
URL
Type of Information | URL |
---|---|
Available Operations configured in the platform |
/north/v80/search/catalog/operations |
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
operationName |
operationName |
string |
operationDetails |
operationDetails |
string |
operationEntityType |
operationEntityType |
string. Type of entity to which it applies (applicableTo) |
For searching catalogued operations, you only can use the fields defined in the section "Available fields to include in the "WHERE" clause" |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
Operation Object
Entity | Constraint | Description |
---|---|---|
name |
string |
Unique name of the operation |
title |
string |
Displayable name of the operation |
description |
string |
Textual description |
applicableTo[] |
array of strings |
List of entiTypes to which applies the operation. For values see Entity Type Enumeration. |
categoryPath |
string |
Path of the classification of the operation. Example: "/diagnostics" |
parameters |
Json schema for the parameters accepted by the operation |
Parameters Definition |
steps[] |
Array of Steps definitions. See Operation steps Objects. |
Steps Definition List |
Available Operations Examples
An example of response could be something like this
{ "operations": [ { "name": "operation_1", "title":"Operation 1", "description": "Description of the operation", "applicableTo": ["DEVICE"], "categoryPath" : "/diagnostics", "parameters": { "type": "object", "properties": { "param1": { "type": "string", "title": "Parameter 1", "maxLength": 255, "pattern": "[Regular Expression]" }, "param2": { "type": "string", "title": "Parameter 2", "description": "The format is described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime (f.e: 2018-11-13T20:20:39+00:00)", "format": "date-time" }, "param3": { "type": "string", "title": "Parameter 3", "description": "The format is described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime (f.e: 2018-11-13)", "format": "date" }, "param4": { "type": "string", "title": "Parameter 4", "description": "The format is described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime (f.e: 20:20:39+00:00)", "format": "time" }, "param5": { "type": "string", "title": "Parameter 5", "description": "The format of an ipv4 address (f.e: 172.19.18.1)", "format": "ipv4" }, "param6": { "type": "string", "title": "Parameter 6", "description": "The format of an ipv6 address (f.e: 2001:0db8:85a3:08d3:1319:8a2e:0370:7334)", "format": "ipv6" }, "param7": { "type": "boolean", "title": "Parameter 7" }, "param8": { "type": "integer", "title": "Parameter 8", "minimum": 10, "maximum": 20 }, "param9": { "type": "number", "title": "Parameter 9", "minimum": 10.0, "maximum": 100.5 }, "param10": { "type": "string", "title": "Parameter 10", "enum": ["ENUM_1", "ENUM_2", "ENUM_3"] }, "param11": { "type": "array", "title": "Parameter 11", "items": { "type": "string" } }, "param12": { "type": "object", "title": "Parameter 12", "properties": { "prop1": { "type": "string", "maxLength": 255 }, "prop2": { "type": "integer" } } }, "required": ["param5", "param6", "param9"] }, "additionalProperties": false }, "steps": [ { "name":"REBOOT", "title":"Reboot Action", "description": "", "response": [ { "name":"variable1" "title":"Variable 1", "description": "", "type":"string", "required" : false } ] } ] }, { "name": "operation_2", "title":"Operation 2", "description": "Description of the operation", "applicableTo": ["DEVICE", "SUBSCRIBER"], "categoryPath" : "/generic", "parameters" : {} } ] }
you can view the special fields for searching available operations in the table Filter fields for searching available operations |
The option with summary will be available in future versions |
Operators
The OpenGate API query allows to obtain the data stored in the database relating to operators.
It is important to note that this API searching does not have pagination |
Plans
The OpenGate API query allows to obtain the available plans provisioned under the domain of the user that sends the request.
URL
Type of Information | URL |
---|---|
Plans provisioned in the platform for organization use |
/north/v80/search/catalog/plans/organization?domainName** |
Plans provisioned in the platform for device use |
/north/v80/search/catalog/plans/device?domainName** |
URL parameters
Using plans searching is mandatory the specification of a domain name, pe, in the case of searching of organization plans you have to indicate the domain Name in the URL request, where <value> is the domain Name where you are searching plans
If a domain is not specify, automaticaly the user’s domain who is doing the searching will be selected. An user can specify it’s domain or one with a minor hierarchy.
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
plan.identifier |
plan identifier |
String |
plan.name |
plan name |
String |
plan.flowRate.value |
max number of event per unit of time |
Number |
plan.flowRate.unit |
unit of time per flow rate |
String |
plan.maxDeviceAmount |
max number of devices |
string |
plan.maxStorageLifeTime.period |
period of time for maximum storage |
String |
plan.maxStorageLifeTime.total |
Number of period for maximum storage |
Number |
plan.defaultAssigned |
Field name for indicating if the plan must be available in a domain with below hierarchy |
boolean |
plan.defaultProvision |
Field name for indicating the default asigned plan for new domain creations |
boolean |
Plan Object
This is the plan object
Object / attribute | Description |
---|---|
identifier |
plan identifier, mandatory |
name |
plan name, mandatory |
flowRate |
measures per unit of time, see table below, Mandatory |
maxDeviceAmount |
max number of devices, Mandatory for organization plans, empty in the case of device plans |
maxStorageLifeTime |
max time of data storage, see table below. Mandatory for organization plans, empty in the case of device plans |
defaultAssigned |
Field name for indicating if the plan must be available in a domain with below hierarchy. Mandatory |
defaultProvision |
Field name for indicating the default asigned plan for new domain creations. Mandatory |
value | max number of event per unit of time. Mandatory |
---|---|
unit |
unit of time per flow rate. Mandatory |
total | Number of period for maximum storage | Number |
---|---|---|
period |
period of time for maximum storage |
String |
Examples of searching
An example of response could be something like this
{ "plans": [ { "identifier": "BASIC", "name": "BASIC", "flowRate": {}, "maxDeviceAmount": 1000, "maxStorageLifeTime": { "total": 90, "period": "DAYS" }, "defaultAssigned": true, "defaultProvision": false }, { "identifier": "TRIAL", "name": "TRIAL", "flowRate": { "value": 100, "unit": "DAYS" }, "maxDeviceAmount": 10, "maxStorageLifeTime": { "total": 30, "period": "DAYS" }, "defaultAssigned": true, "defaultProvision": true } ] }
{ "plans": [{ "identifier": "TRIAL", "name": "TRIAL", "flowRate": { "value": 100, "unit": "DAYS" }, "defaultAssigned": true, "defaultProvision": true }] }
Rules
The OpenGate API query allows to obtain different platform rules. They will be only those on which the user who performs the query has visualization capacity for his domain / organization.
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
rule.organization |
organization of the rule |
string |
rule.channel |
channel of the rule |
string |
rule.mode |
rule mode |
string |
rule.name |
name of the rule |
string |
rule.description |
rule description |
string |
rule.active |
rule active or not |
boolean |
rule.type.name |
rule type name |
string |
Software
The OpenGate API query allows to obtain the data stored in the database relating to both the software and software version.
In the case of software and software version information is delivered in a common way
URL
Type of Information | URL |
---|---|
Software version and their Manufacturers catalogued in the platform |
/north/v80/search/catalog/softwares |
Software version and their Manufacturers summary catalogued in the platform |
/north/v80/search/catalog/softwares/summary |
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
softwareVersion |
softwareVersion |
string |
softwareName |
softwareName |
string |
softwareId |
softwareId |
string |
softwareType |
softwareType |
string |
For searching software, you only can use the fields defined in the section "Available fields to include in the "WHERE" clause" |
Summary Information
Entity | Constraint |
---|---|
firmware |
|
manufacturer |
Software structure
For get the software of the platform the JSON response has the next format:
Entity | Constraint |
---|---|
id |
string |
name |
string |
version |
string |
type |
string. See Software Type Enumeration values |
An example could be something like this
{ "software": [ { "id": "7af5bc31-7b2b-49f8-9bab-adc04d2625da", "name": "b208g2", "type": "FIRMWARE", "version": "v1.5" }, { "id": "a974ab2e-6fa4-4cf5-beef-548e079e8714", "name": "CIRWATT C 410-UT5C-10C.", "type": "FIRMWARE", "version": "4. 1. 2." } ] }
you can view the special fields for searching software in the table Filter fields for searching software |
{ "summary": { "count": 11, "firmware": { "count": 2, "list": [ { "count": 1, "name": "firmware_test_internal" }, { "count": 1, "name": "CIRWATT C 410-UT5C-10C." } ] }, "manufacturer": { "count": 9, "list": [ { "count": 3, "name": "MOTOROLA" }, { "count": 4, "name": "ACE6000" }, { "count": 1, "name": "SIEMENS" }, { "count": 1, "name": "WAVECOM" } ] } } }
Subscribers
This API allows retrieveing the list of subscribers, even the subscribers that are not associated to any other device, providing a lot of options for:
-
Filter (See Specific Filter Fields)
-
Order (see Sorting)
-
Select Required Fields (see Selecting)
-
Summary (see Summary)
It is possible to obtain the results in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
By the other hand, you can obtain the result in flattened format thanks to flattened parameter (see subscriber parameters)
URL
Querying over | URI |
---|---|
Subscribers Info (Provisioned and Collected) |
/v80/search/subscribers |
Subscribers Summary Info (Provisioned and Collected) |
/v80/search/subscribers/summary |
Here, you can see some Searching subscribers examples
URL parameters
-
flattened: It is possible to receive the subscribers data with a flattened json format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to receive a flattened json format
Response Format
Using HTTP header option "Accept", the API allows obtaining the result in different formats:
Format | Accept Header Value |
---|---|
JSON |
By default if "Accept" header field is not present or "Accept" field has "application/json" value |
CSV |
If "Accept" has "text/plain" value |
POST /contacts HTTP/1.1 Accept: application/json HTTP/1.1 200 OK Content-Type: application/json ...
POST /contacts HTTP/1.1 Accept: text/plain HTTP/1.1 200 OK Content-Type: application/json ...
Specific Filter Fields
Any parameter of the list included in the subscribers Default Datamodels can be used as filters fields in API search filters, including the custom datastreams.
{ "filter": { "and": [ { "like": { "provision.device.communicationModules[].subscriber.mobile.icc": "subscriber_battery_icc" } } ] } }
Specific Select Fields
See predefined profiles section Default Datamodels to know the fields you can use with the select feature.
Summary Information
It is possible to summarize the request, see Summary usage
Subscribers Search examples
POST /v80/search/subscribers
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
JSON format This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/subscribers
And this is the response body:
{ "page": { "number": 1 }, "subscribers": [ { "resourceType": { "_current": { "value": "entity.subscriber", "provType": "IDENTIFIER", "date": "2017-12-04T23:20:01.614Z" } }, "provision": { "device": { "communicationModules": [ { "subscriber": { "identifier": { "_current": { "value": "subscriber_battery", "provType": "MONITORING", "date": "2017-12-04T23:20:01.603Z" } }, "mobile": { "icc": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-12-04T23:20:01.59Z" } } }, "specificType": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-12-04T23:20:01.597Z" } }, "name": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-12-04T23:20:01.599Z" } }, "description": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-12-04T23:20:01.588Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-04T23:20:01.594Z" } } } } ] }, "administration": { "identifier": { "_current": { "value": "subscriber_battery", "provType": "MONITORING", "date": "2017-12-04T23:20:01.608Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-04T23:20:01.612Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-04T23:20:01.613Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-04T23:20:01.605Z" } } } } } ] }
CSV Format
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/subscribers
It must be used a filter with the select clause because is obligatory for the csv format, see Selecting
{ "select": [ { "name": "provision.device.communicationModules[].subscriber.identifier", "fields": [ { "field": "value", "alias": "id" } ] }, { "name": "provision.device.communicationModules[].subscriber.specificType", "fields": [ { "field": "value", "alias": "specificType" } ] } ] }
POST /north/v80/search/subscribers?flattened=true
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/subscribers?flattened=true
And this is the response body:
{ "subscribers": [ { "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-04T23:20:01.612Z" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "subscriber_battery", "provType": "MONITORING", "date": "2017-12-04T23:20:01.608Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-04T23:20:01.613Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-04T23:20:01.605Z" } } }, "provision.device.communicationModules[].subscriber.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-04T23:20:01.594Z" } } } ], "provision.device.communicationModules[].subscriber.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery_description", "provType": "MONITORING", "date": "2017-12-04T23:20:01.588Z" } } } ], "provision.device.communicationModules[].subscriber.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery", "provType": "MONITORING", "date": "2017-12-04T23:20:01.603Z" } } } ], "provision.device.communicationModules[].subscriber.mobile.icc": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery_icc", "provType": "MONITORING", "date": "2017-12-04T23:20:01.59Z" } } } ], "provision.device.communicationModules[].subscriber.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscriber_battery_name", "provType": "MONITORING", "date": "2017-12-04T23:20:01.599Z" } } } ], "provision.device.communicationModules[].subscriber.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "SIM", "provType": "MONITORING", "date": "2017-12-04T23:20:01.597Z" } } } ], "resourceType": { "_value": { "_current": { "value": "entity.subscriber", "provType": "IDENTIFIER", "date": "2017-12-04T23:20:01.614Z" } } } } ], "page": { "number": 1 } }
POST /v80/search/subscribers/summary
By default the summary always shows the total counter and the organizations grouping counter and channel grouping counter, see Grouping
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/subscribers/summary
The response body could be something like this:
{ "summary": { "count": 1, "summaryGroup": [ { "provision.administration.channel": { "count": 1, "list": [ { "count": 1, "name": "battery_channel" } ] } }, { "provision.administration.organization": { "count": 1, "list": [ { "count": 1, "name": "battery_organization" } ] } } ] } }
Subscriptions
This API allows retrieveing the list of subscriptions, even the subscriptions that are not associated to any other device, providing a lot of options for:
-
Filter (See Specific Filter Fields)
-
Order (see Sorting)
-
Select Required Fields (see Selecting)
-
Summary (see Summary)
It is possible to obtain the results in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
By the other hand, you can obtain the result in flattened format thanks to flattened parameter (see subscription parameters)
URL
Querying over | URI |
---|---|
Subscriptions Info (Provisioned and Collected) |
/v80/search/subscriptions |
Subscriptions Summary Info (Provisioned and Collected) |
/v80/search/subscriptions/summary |
Here, you can see some Searching subscriptions examples
URL parameters
-
flattened: It is possible to receive the subscriptions data with a flattened json format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to receive a flattened json format
Response Format
Using HTTP header option "Accept", the API allows obtaining the result in different formats:
Format | Accept Header Value |
---|---|
JSON |
By default if "Accept" header field is not present or "Accept" field has "application/json" value |
CSV |
If "Accept" has "text/plain" value |
POST /contacts HTTP/1.1 Accept: application/json HTTP/1.1 200 OK Content-Type: application/json ...
POST /contacts HTTP/1.1 Accept: text/plain HTTP/1.1 200 OK Content-Type: application/json ...
Specific Filter Fields
Any parameter of the list included in the subscriptions Default Datamodels can be used as filters fields in API search filters, including the custom datastreams.
{ "filter": { "and": [ { "like": { "provision.device.communicationModules[].subscription.mobile.imsi": "subscription_battery_imsi" } } ] } }
Specific Select Fields
See predefined profiles section Default Datamodels to know the fields you can use with the select feature.
Summary Information
It is possible to summarize the request, see Summary usage
Subscriptions Search examples
POST /v80/search/subscriptions
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
JSON format
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/subscriptions
And this is the response body:
{ "page": { "number": 1 }, "subscriptions": [ { "resourceType": { "_current": { "value": "entity.subscription", "provType": "IDENTIFIER", "date": "2017-12-04T20:42:10.353Z" } }, "provision": { "device": { "communicationModules": [ { "subscription": { "identifier": { "_current": { "value": "subscription_battery_id2", "provType": "MONITORING", "date": "2017-12-04T20:42:10.325Z" } }, "address": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-12-04T20:42:10.328Z" } }, "mobile": { "imsi": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-12-04T20:42:10.333Z" } }, "registeredOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-04T20:42:10.336Z" } }, "msisdn": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-12-04T20:42:10.339Z" } }, "homeOperator": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-04T20:42:10.341Z" } } }, "specificType": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-12-04T20:42:10.322Z" } }, "administrativeState": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-04T20:42:10.332Z" } }, "name": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-12-04T20:42:10.318Z" } }, "description": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-12-04T20:42:10.316Z" } } } } ] }, "administration": { "identifier": { "_current": { "value": "subscription_battery_id2", "provType": "MONITORING", "date": "2017-12-04T20:42:10.346Z" } }, "channel": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-04T20:42:10.347Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-04T20:42:10.349Z" } }, "serviceGroup": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-04T20:42:10.342Z" } } } } } ] }
CSV Format
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/subscriptions
It must be used a filter with the select clause because is obligatory for the csv format, see Selecting
{ "select": [ { "name": "provision.device.communicationModules[].subscription.identifier", "fields": [ { "field": "value", "alias": "id" } ] }, { "name": "provision.device.communicationModules[].subscription.specificType", "fields": [ { "field": "value", "alias": "specificType" } ] } ] }
POST /north/v80/search/subscriptions?flattened=true
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/subscriptions?flattened=true
And this is the response body:
{ "subscriptions": [ { "provision.administration.channel": { "_value": { "_current": { "value": "battery_channel", "provType": "MONITORING", "date": "2017-12-04T20:42:10.347Z" } } }, "provision.administration.identifier": { "_value": { "_current": { "value": "subscription_battery_id2", "provType": "MONITORING", "date": "2017-12-04T20:42:10.346Z" } } }, "provision.administration.organization": { "_value": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2017-12-04T20:42:10.349Z" } } }, "provision.administration.serviceGroup": { "_value": { "_current": { "value": "emptyServiceGroup", "provType": "MONITORING", "date": "2017-12-04T20:42:10.342Z" } } }, "provision.device.communicationModules[].subscription.address": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": { "type": "IPV4", "value": "99.1.1.71", "apn": "movistar.es" }, "provType": "REFERENCE", "date": "2017-12-04T20:42:10.328Z" } } } ], "provision.device.communicationModules[].subscription.administrativeState": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "ACTIVE", "provType": "MONITORING", "date": "2017-12-04T20:42:10.332Z" } } } ], "provision.device.communicationModules[].subscription.description": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_description", "provType": "MONITORING", "date": "2017-12-04T20:42:10.316Z" } } } ], "provision.device.communicationModules[].subscription.identifier": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_id2", "provType": "MONITORING", "date": "2017-12-04T20:42:10.325Z" } } } ], "provision.device.communicationModules[].subscription.mobile.homeOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-04T20:42:10.341Z" } } } ], "provision.device.communicationModules[].subscription.mobile.imsi": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_imsi", "provType": "IDENTIFIER", "date": "2017-12-04T20:42:10.333Z" } } } ], "provision.device.communicationModules[].subscription.mobile.msisdn": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "34969220026", "provType": "MONITORING", "date": "2017-12-04T20:42:10.339Z" } } } ], "provision.device.communicationModules[].subscription.mobile.registeredOperator": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "Telefónica Móviles España, SAU", "provType": "MONITORING", "date": "2017-12-04T20:42:10.336Z" } } } ], "provision.device.communicationModules[].subscription.name": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "subscription_battery_name", "provType": "MONITORING", "date": "2017-12-04T20:42:10.318Z" } } } ], "provision.device.communicationModules[].subscription.specificType": [ { "_index": { "path": "provision.device.communicationModules[].identifier" }, "_value": { "_current": { "value": "MOBILE", "provType": "MONITORING", "date": "2017-12-04T20:42:10.322Z" } } } ], "resourceType": { "_value": { "_current": { "value": "entity.subscription", "provType": "IDENTIFIER", "date": "2017-12-04T20:42:10.353Z" } } } } ], "page": { "number": 1 } }
POST /v80/search/subscriptions/summary
By default the summary always shows the total counter and the organizations grouping counter and channel grouping counter, see Grouping
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/subscriptions/summary
The response body could be something like this:
{ "summary": { "count": 1, "summaryGroup": [ { "provision.administration.channel": { "count": 1, "list": [ { "count": 1, "name": "battery_channel" } ] } }, { "provision.administration.organization": { "count": 1, "list": [ { "count": 1, "name": "battery_organization" } ] } } ] } }
Tickets
The OpenGate API query allows retrieveing the list of tickets.
It is possible to obtain the results in two different formats, see HTTP Header Options:
-
JSON Format (Default)
-
CSV Format
By the other hand, you can obtain the result in flattened format thanks to flattened parameter (see ticket parameters)
URL
Querying over | URI |
---|---|
Tickets Info |
/v80/search/tickets |
Flattened Tickets Info |
/v80/search/tickets?flattened=true |
Tickets Summary Info |
/v80/search/tickets/summary |
Here, you can see some Searching tickets examples
URL parameters
-
flattened: It is possible to receive the ticket data with a flattened json format (see flattened concept). In this case, it is sent a boolean parameter, flattened, to allow to receive a flattened json format.
Response Format
Using HTTP header option "Accept", the API allows obtaining the result in different formats:
Format | Accept Header Value |
---|---|
JSON |
By default if "Accept" header field is not present or "Accept" field has "application/json" value |
CSV |
If "Accept" has "text/plain" value |
POST /contacts HTTP/1.1 Accept: application/json HTTP/1.1 200 OK Content-Type: application/json ...
POST /contacts HTTP/1.1 Accept: text/plain HTTP/1.1 200 OK Content-Type: application/json ...
Specific Filter Fields
Any parameter of the list included in the ticket Default Datamodels can be used as filters fields in API search filters, including the custom datastreams.
{ "filter": { "and": [ { "like": { "provision.ticket.type": "WORKORDER" } }, { "like": { "provision.ticket.severity": "CRITICAL" } } ] } }
Specific Select Fields
See predefined profiles section Default Datamodels to know the fields you can use with the select feature.
Summary Information
It is possible to summarize the request, see Summary usage
Tickets Search examples
POST /v80/search/tickets
It is possible to obtain the results of this request in two different formats, JSON or CSV (see HTTP Header Options)
JSON format This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/tickets
And this is the response body:
{ "page": { "number": 1 }, "tickets": [ { "resourceType": { "_current": { "value": "ticket", "provType": "IDENTIFIER", "date": "2018-04-08T10:11:09.05Z" } }, "provision": { "ticket": { "identifier": { "_current": { "value": "96ef81a2-7ddb-404a-b7a6-1b4d47f550c7", "provType": "MONITORING", "date": "2018-04-09T14:51:58.751Z" } }, "label": { "_current": { "value": [], "provType": "MONITORING", "date": "2018-04-09T14:51:58.763Z" } }, "status": { "_current": { "value": "CREATED", "provType": "MONITORING", "date": "2018-04-09T14:51:58.771Z" } }, "assignee": { "_current": { "value": "10000003J", "provType": "MONITORING", "date": "2018-04-09T14:51:58.759Z" } }, "specificType": { "_current": { "value": "INSTALLATION", "provType": "MONITORING", "date": "2018-04-09T14:51:58.773Z" } }, "owner": { "_current": { "value": "admin@enel.com", "provType": "MONITORING", "date": "2018-04-09T14:51:58.888Z" } }, "reporter": { "_current": { "value": "10000004J", "provType": "MONITORING", "date": "2018-04-09T14:51:58.77Z" } }, "updatedDate": { "_current": { "value": "2018-04-09T14:51:58.888Z", "provType": "MONITORING", "date": "2018-04-09T14:51:58.888Z" } }, "creationDate": { "_current": { "value": "2018-04-08T10:11:09.05Z", "provType": "MONITORING", "date": "2018-04-08T10:11:09.05Z" } }, "type": { "_current": { "value": "WORKORDER", "provType": "MONITORING", "date": "2018-04-09T14:51:58.772Z" } }, "severity": { "_current": { "value": "CRITICAL", "provType": "MONITORING", "date": "2018-04-09T14:51:58.76Z" } }, "name": { "_current": { "value": "onfield deployment Madrid", "provType": "MONITORING", "date": "2018-04-09T14:51:58.761Z" } }, "priority": { "_current": { "value": "MAJOR", "provType": "MONITORING", "date": "2018-04-09T14:51:58.762Z" } } }, "administration": { "identifier": { "_current": { "value": "96ef81a2-7ddb-404a-b7a6-1b4d47f550c7", "provType": "MONITORING", "date": "2018-04-09T14:51:58.775Z" } }, "organization": { "_current": { "value": "battery_organization", "provType": "MONITORING", "date": "2018-04-09T14:51:58.774Z" } } } } } ] }
CSV Format
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --Accept: text/plain --verbose \ http://[your_opengate_address]/north/v80/search/tickets
It must be used a filter with the select clause because is obligatory for the csv format, see Selecting
{ "filter": { "eq": { "provision.ticket.type": "WORKORDER" } }, "select": [ { "name": "provision.ticket.name", "fields": [ { "field": "value", "alias": "Name" } ] }, { "name": "provision.ticket.status", "fields": [ { "field": "value", "alias": "Status" } ] } ] }
Name;Status Despliegue en campo;CREATED Onfield deployment;CREATED Work order 2;ASSIGNED Work order 3;CREATED onfield deployment Madrid;CREATED
POST /north/v80/search/tickets?flattened=true
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/tickets?flattened=true
And this is the response body using the previous filter:
{ "tickets": [ { "provision.ticket.name": { "_value": { "_current": { "value": "Onfield deployment" } } }, "provision.ticket.status": { "_value": { "_current": { "value": "CREATED" } } } }, { "provision.ticket.name": { "_value": { "_current": { "value": "Work order 2" } } }, "provision.ticket.status": { "_value": { "_current": { "value": "ASSIGNED" } } } } ], "page": { "number": 1 } }
POST /v80/search/tickets/summary
By default the summary always shows the total counter and the organizations grouping counter and channel grouping counter, see Grouping
This is the request using curl:
curl --request POST \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/search/tickets/summary
The response body could be something like this:
{ "summary": { "count": 5, "summaryGroup": [ { "provision.administration.organization": { "count": 5, "list": [ { "count": 4, "name": "battery_organization" }, { "count": 1, "name": "battery_organization_2" } ] } } ] } }
Users
The OpenGate API query allows to obtain the provisioned users in the current domain and the child domains of this.
URL
Type of Information | URL |
---|---|
Users Provisioned in the platform |
/north/v80/search/users |
Summary of users Provisioned in the platform |
/north/v80/search/users/summary |
Applicable Filter Fields
Parameter | Description |
---|---|
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
User Object
For security reasons, the field password will not returned as part of the structure |
Please find information about default available user profiles |
Examples
Using this curl to perform the request, you can obtain the provisioned users
curl --request POST \ --header "X-Apikey: YOUR_API_KEY_HERE" \ --verbose \ https://[your_opengate_address]/north/v80/search/users
An example of response could be something like this
{ "users": [ { "user": { "email": "example2@email.com", "description": "description", "workgroup": "workgroup_1", "domain": "domain_1", "profile": "admin", "name": "user name", "surname": "user surname", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Madrid" } } ] }
{ "page": { "number": 1, "of": 7 }, "summary": { "count": 90 }, "users": [ { "user": { "email": "example2@email.com", "description": "description", "workgroup": "workgroup_1", "domain": "domain_1", "profile": "admin", "name": "user name", "surname": "user surname", "countryCode": "ES", "langCode": "es", "timezone": "Europe/Madrid" } } ] }
{ "summary": { "count": 90 } }
Workgroups
The OpenGate API query allows to obtain the available workgroups provisioned under the domain of the user that sends the request.
URL
Type of Information | URL |
---|---|
Workgroups provisioned in the platform |
/north/v80/search/workgroups |
Summary of the Workgroups provisioned in the platform |
/north/v80/search/workgroups/summary |
URL parameters
Using summary parameter in the URL request, "/north/v80/search/workgroups?summary=<value>" where <value> can be:
-
true: The response includes the summary object.
-
false (default): The same behavior when the parameter is not present. The summary object is not included in the response
Applicable Filter Fields
Field name | field name in where clause | type |
---|---|---|
name |
name of the workgroup |
string |
description |
description of the workgroup |
string |
domain |
domain whith belongs the workgroup |
string |
administrative |
indicates if the workgroup will contain all the new channels created automatically |
boolean |
Summary Information
Entity | Constraint |
---|---|
count (field) |
number of occurrences found in the whole search |
Examples
An example of response could be something like this
{ "workgroups": [ { "name": "Workgroup_1", "description": "Workgroup description", "domain" : "domain_1", "administrative" : true }, { "name": "Workgroup_2", "description": "Workgroup description", "domain" : "domain_1", "administrative" : true } ] }
{ "page":{ "number":1, "of":1 }, "summary": { "count": 2 }, "workgroups": [ { "name": "Workgroup_1", "description": "Workgroup description", "domain" : "domain_1", "administrative" : true }, { "name": "Workgroup_2", "description": "Workgroup description", "domain" : "domain_1", "administrative" : true } ] }
{ "summary": { "count": 2 } }
Operation
Introduction
Why do you need an operations service?
If you’re reading this document, then you’re interested in device monitoring and management, maybe you’re involved in the operations department in your company. If so, then you usually execute operations on your remote devices, like reboot or send an ICMP ping it to check its availability. OpenGate comes to help you with your massive field operations. The operations service API is the programmatic way to perform your operations using OpenGate.
Existing Operationes
The platform implements by default a set of device operation types that are ussually implemented by the device. Find the list in the Default Operations Catalog
New operations
The operations engine is a powerful and extensible tool, so new operations can be created to cover new needs on demand. The OpenGate operations API is very flexible, you can configure each operation with the operation name and the parameter list to be used. Using this interface you can invoke new operations without change the programmatic interface.
Rich operations
The underlying OpenGate engine supports multi step operations, therefore when you invoke the execution of an operation, you must expect a list containing the result of each single step.
Executing operations
The operations API is not an exception, it fits the REST architectural style. While the provision service makes an extensive use of entity/collection pattern, the operation service implements the command pattern. How does it? Easy, OpenGate manages operations as entities, so when you want to execute an operation you only have to send a POST request with an operation object.
Yes, this use of REST could inflame some religious war, but we are in the operation world, so please take it easy, it simply works fine.
A single operation could be executed on a few entities or on thousand of entities if you use a tag instead a target array. So please, use it with caution. |
The list of the operation types are defined in the section Default Operations Catalog |
Jobs
Job object
A job define the operation configuration and selected remote devices to send request with the following attributes:
Attributes | Constraints | Description |
---|---|---|
id[1] |
UUID format |
Job identifier |
taskId |
UUID format |
Task to which the job belongs |
request |
includes all the information about the Job request |
|
report |
Job execution report |
Attributes | Constraints | Description |
---|---|---|
string |
It’s the operation name you want to be invoked. Please, see built in operations. |
|
parameters |
Job Parameters |
The parameters of the operation. If it isn’t present, no parameters will be assumed. |
notify (default value false) |
true/false |
|
user |
string |
Identifies the user that has launched the operation. Not used for Job create and update operations |
userNotes |
string |
Job instance associated notes filled through the API |
active (default value true) |
true/false |
If false the Job will be created but it will not started (neither its scheduling) until the value has changed to active. This feature can be used to allow (using PUT operation) appending new targets to an already created Job and then starting it (changing to true) when all targets are added.This parameter can only be modified before the job execution is started. |
callback |
URI format defined in RFC 3986. Only HTTP transport supported |
Allows to enable Notifications to be sent to an application (See operation push service description). An empty value in this field disables callback notification. The platform will add to this URI the name of the specific callback (See callback description section). |
schedule |
see Schedule Object |
Allows to configure all scheduling parameters to launch the operation |
operationParameters |
Allows to configure specific parameters of the operation to be sent to each target |
|
target |
Indicates the Ids of the entities to be applied to apply the operation. Only one of them can be included at the same JSON object. Also it is required in creation and update operations and missing in reading operations |
Attributes | Constraints | Description |
---|---|---|
start |
Allows to configure the scheduled start of the operation. |
|
stop |
Allows to configure the scheduled stop of the operation. |
|
window |
Allows to include a specific execution period of time |
|
scattering |
Allows dispersing the atomic operations regarding a particular parameter, this is an optional block |
Attributes | Constraints | Description |
---|---|---|
ackTimeout |
Number. Must be expressed in milliseconds and must be greater than 0 |
If the operation has not be accepted by the device at the end of the timeout, it will be cancelled |
timeout (default 60000, one minute) |
Number. Must be expressed in milliseconds |
If the operation is not finished at the end of the timeout, it will be cancelled. By default OpenGate is configured with minimum internal timeout of 40 seconds, thus this timeout plus ackTimeout must be greater than this internal timeout. The default 60 secons is a good starting point. |
retries (default 0) |
Number |
If the requested operation has not ack in ackTimeout or in operationTimeout the request is retried |
retriesDelay |
Number. Must be expressed in milliseconds |
Delay between retries |
Attributes | Constraints | Description |
---|---|---|
append |
Allows to append entities to the job |
|
remove |
Allows to append entities to the job |
Attributes | Constraints | Description |
---|---|---|
entities[] |
array of entity ID strings |
There is a limit in the array size of 100 entities by default. To know it please consult with your platform administrator |
entitiesWithParameters[] |
array of entities with special parameters. See entitiesWithParameters Object |
There is a limit in the array size of 100 entities by default. To know it please consult with your platform administrator |
tags[] |
Tag identifier |
At the current version only one tag name can be passed in the array |
filter |
filter of entities |
you can use a filter for select the entities to include in the job |
Attributes | Constraints | Description |
---|---|---|
id |
Entity identifier |
Identifier of entities with special parameters |
parameters |
Job Parameters |
Each entity from this section replace the common parameters of the job with his concrete parameters |
Attributes | Constraints | Description |
---|---|---|
execution |
See Execution Object |
Execution info |
summary |
See Summary Object |
Counters summarizing the Job execution |
target |
List entities related with the job report, only used in response to create or update operations |
Attributes | Constraints | Description |
---|---|---|
activatedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when Job is activated |
startedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when Job execution is started |
finishedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when Job is finished |
Attributes | Constraints | Description |
---|---|---|
total |
Number |
Total of operations tried |
status |
Job status |
|
errorCode |
string |
Code of error produced in the execution of the job. This field appears only in the event that the job completed with errors, status field = FINISHED_WITH_ERRORS |
errorDescription |
string |
Error description produced in the execution of the job. This field appears only in the event that the job completed with errors, status field = FINISHED_WITH_ERRORS |
inProgress |
Summary of in progress operations states |
|
finished |
Summary of finished operations states |
Attributes | Constraints | Description |
---|---|---|
total |
Number |
Total of in progress operations |
scheduled |
Number |
Number of Scheduled operations |
pendingExecution |
Number |
Number of operations pending of execution (queued) |
waitingForConnection |
Number |
Number of operations pending of device demand |
started |
Number |
Number of already started operations |
Attributes | Constraints | Description |
---|---|---|
total |
Number |
Total of finished operations |
successful |
Number |
Number of finished with success operations |
error |
Number |
Number of finished with error operations. |
cancelled |
Cancelled single operations summary |
Attributes | Constraints | Description |
---|---|---|
total |
Number |
Total of cancelled operations |
byEngine |
Number |
Number of automatically cancelled operations |
byUser |
Number |
Number of user cancelled operations. |
byTimeout |
Number |
Number of cancelled operations by platform timeout |
byExternalTimeout |
Number |
Number of cancelled operations by external (example: device) timeout |
byExternal |
Number |
Number of cancelled operations by external system (example: API) |
Attributes | Constraints | Description |
---|---|---|
notProvisioned[] |
Array of strings |
List of passed entities IDs that are not provisioned in the platform |
notAllowed[] |
Array of strings |
List of passed entities IDs on which there are not allowed to execute an operation |
duplicated[] |
Array of strings |
List of passed duplicated entities IDs |
Creating a job (Executing a job)
POST /north/v80/operation/jobs
To execute a job you only have to send a POST request with a job object in the body pointing to the desired entities. There are three ways to reference the job target entities:
-
Adding a target of entities references array.
You can distinguish between two types of target:
-
entities
-
entitieswithParameters
The difference between the two types is that in the first case, the parameters of the job that will be applied to entities that group are the generals of the job and in the second case the parameters that accompany each entity shall apply
The target array of entities IDs is the easy way to select multiple devices and apply an operation on them. There is a limit in the number of entities in the array, by default the value is 100 . Please consult with your administrator to know the limit configured. |
By operational issues, the service incorporates a limit in the size of the JSON file. This limit can be configured administratively and by default the limit is set at 300 KBytes. Please consult with your administrator to know the limit configured. |
If you need to launch a operation over a large list of entities you can create a Job (POST) setting the "active" parameter to false and using updating operation (PUT) to append new entities to the target considering the mentioned limit. |
Both options, entities and entitiesWithParameters can by applied simultaneously. |
-
Using a previously created tag.
You can’t mix target references or filter references with tag references |
If you create a job using tags, there is a previous state, "INITIATING", this time is used to create the internal structure of the job, when the platform has finished this internal work, the state of the job will be idle if the tob is not active or scheduled if the job is active |
-
Using filters
You can’t mix filter references with target references or tag references |
You can’t use a previously created filter |
There is an optional parameter for this alternative ?entityType. This parameter restrict the filter to an specific type of entity, If you include this parameter in the Uri of the request only the entities belonging to the selected type will be considered. The available values for this parameter are (in uppercase):
|
Special scheduling
There are two special scheduling for a job, both of them are optional.
-
scattering
-
window
The scattering section is oriented for a job scheduling with protection of a mobile cell, if you introduce this section in a job scheduling you have to indicate a operations spread for the job and a strategy factor. This is oriented for using the most time of de planned time of the job trying that the operations don’t fall down a mobile cell
the window section is oriented for a job scheduling where you want specify a concrete group of days of the week when you want that the job can execute operations and the specific time of the day where you want that de job can execute operations
The time periods of the window must be multiples of one hour, no interim periods allowed.
|
Some JSON request examples:
{ "job" : { "request" : { "name" : "RESET_EQUIPMENT", "parameters": { "type":"HARDWARE" }, "active" : true, "notify" : true, "callback" : "http://[your_application_address]/[your_URI]", "userNotes" : "My notes", "schedule" : { "start" : { "date" : "2010-12-11T10:10:00Z" }, "stop" : { "delayed" : 300000 }, "scattering": { "maxSpread": 10, "strategy": { "factor": 75, "field": "subscription.collected.cellInfo", "warningMaxRate": 3 } } }, "operationParameters" : { "ackTimeout" : 5000, "timeout": 60000, "retries" : 0, "retriesDelay" : 1000 }, "target" : { "append" : { "entities" : [ "device_1", "device_2" ] } } } } }
{ "job": { "request": { "name": "REBOOT_EQUIPMENT", "parameters": { "type": "HARDWARE", "applications": [] }, "active": true, "notify": true, "user": "user@mail.com", "callback": "http://[your_application_address]/[your_URI]", "userNotes": "My notes", "schedule": { "start": { "date": "2010-12-11T10:10:00Z" }, "stop": { "delayed": 300000 }, "scattering": { "maxSpread": 10, "strategy": { "factor": 75, "field": "subscription.collected.cellInfo", "warningMaxRate": 3 } } }, "operationParameters": { "ackTimeout": 5000, "timeout": 60000, "retries": 0, "retriesDelay": 1000 }, "target": { "append": { "entities": [ "device_1", "device_2" ], "entitiesWithParameters": [ { "id": "device_3", "parameters": { "type": "SOFTWARE" } }, { "id": "device_4", "parameters": { "type": "APPLICATION", "applications": [ "application_1", "application_2" ] } } ] } } } } }
When you need to apply the same operation over thousand of devices, you can use the tag attribute. The operation will be applied to all the tagged entities.
{ "job" : { "request" : { "name" : "RESET_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "active" : true, "notify" : true, "callback" : "http://[your_application_address]/[your_URI]", "userNotes" : "My notes", "schedule" : { "start" : { "date" : "2010-12-11T10:10:00Z" }, "stop" : { "delayed" : 300000 }, "scattering": { "maxSpread": 10, "strategy": { "factor": 75, "field": "subscription.collected.cellInfo", "warningMaxRate": 3 } } }, "operationParameters" : { "ackTimeout" : 5000, "timeout": 60000, "retries" : 0, "retriesDelay" : 1000 }, "target" : { "append" : { "tags" : [ "tag_1" ] } } } } }
A single job could be executed on thousand of entities when you use a tag instead a target array. So please, use tags in operations with caution. |
{ "job" : { "request" : { "name" : "RESET_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "active" : true, "notify" : true, "callback" : "http://[your_application_address]/[your_URI]", "userNotes" : "My notes", "schedule" : { "start" : { "date" : "2010-12-11T10:10:00Z" }, "stop" : { "delayed" : 300000 } }, "operationParameters" : { "ackTimeout" : 5000, "timeout": 60000, "retries" : 0, "retriesDelay" : 1000 }, "target" : { "filter" : { "and" : [ {"like" : { "collected.serialNumber" : "SN" }} ] } } } } }
A single job could be executed on thousand of entities when you use a filter instead a target array. So please, use filters in operations with caution. |
{ "job": { "request": { "name": "RESET_EQUIPMENT", "parameters": { "TYPE": "HARDWARE" }, "active": true, "notify": true, "callback": "http://[your_application_address]/[your_URI]", "userNotes": "My notes", "schedule": { "start": { "date": "2010-12-11T10:10:00Z" }, "stop": { "delayed": 300000 }, "window": { "weekly": [ { "days": [ "MON", "WED", "FRI" ], "daily": { "start": "09:00:00Z", "stop": "15:00:00Z" } }, { "days": [ "MON" ], "daily": { "start": "22:00:00Z", "stop": "23:00:00Z" } }, { "days": [ "SAT", "SUN" ], "daily": { "start": "08:00:00Z", "stop": "20:00:00Z" } } ] }, "scattering": { "maxSpread": 10, "strategy": { "factor": 75, "field": "subscription.collected.cellInfo", "warningMaxRate": 3 } } }, "operationParameters": { "ackTimeout": 5000, "timeout": 60000, "retries": 0, "retriesDelay": 1000 }, "target": { "append": { "entities": [ "device_1", "device_2" ] } } } } }
Once you have the operation configured in JSON, you must send it as a POST request. This is an example using curl:
curl --request POST \ --data-binary @job.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ -H "Content-type: application/json" \ http://[your_opengate_address]/north/v80/operation/jobs
Example or requests with parameter entityType
curl --request POST \ --data-binary @job.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ -H "Content-type: application/json" \ http://[your_opengate_address]/north/v80/operation/jobs?entityType=GATEWAY \
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created order. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/operation/jobs/ffc4ae39-8126-4ab7-8e79-cbfa3dc45b1c
If you create an active job using the option of target of entities and no one of the entities exists, the response will be a 400 status code. If the job is not active you can create without entities. |
The response body could be something like this:
{ "id": "a38f7735-dcef-4f5a-9ca4-b6a8f7517522", "request": { "name" : "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "active": true, "notify": false, "user" : "user@mail.com", "userNotes" : "My notes", "schedule": { "stop" : { "delayed" : 300000 } }, "operationParameters": { "timeout": 60000, "retries": 0 } }, "report": { "execution": {}, "target": { "notProvisioned": [ "device_1", "device_2" ], "notAllowed" : [ "device_3" ], "duplicated" : [ "device_7" ] } } }
In the target section of the response you can see the entities with problems, those entities haven’t be associated to the job.
-
The "notProvisioned" entities list are not found (either because they do not exists or they aren’t in the same workgroup)
-
The "NotAllowed" list are the list of companies where you can not perform the operation
-
The "duplicated" list are the list of duplicate entities.
What happens when you execute a job?
An execution involves as many entities as you reference in the JSON document. Therefore, you must expect one execution result per each entity you referenced. In other words, an execution explodes in many results.
The operations API lets you get both the operation summary and each individual result.
Reading a job report
GET /north/v80/operation/jobs/{jobid}
You can apply for a job report sending a GET request using the URL above . You must replace {jobid} with the identifier of the job you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/jobs/a38f7735-dcef-4f5a-9ca4-b6a8f7517522
The response body could be something like this:
{ "id": "a38f7735-dcef-4f5a-9ca4-b6a8f7517522", "taskId": "4e494872-8075-47a5-bccc-bb9e5f5be5f1", "request": { "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE": "HARDWARE" }, "active": true, "notify": false, "user": "user@mail.com", "userNotes": "My notes", "schedule": { "stop": { "delayed": "100000" }, "scattering": { "maxSpread": 80, "strategy": { "factor": 75, "field": "subscription.collected.cellInfo" } }, "window": { "weekly": [ { "days": [ "FRI", "WED", "MON" ], "daily": { "start": "09:00:00", "stop": "15:00:00" } }, { "daily": {} } ] } } }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "waitingForConnection": 0, "started": 0 }, "finished": { "total": 2, "successful": 1, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 1, "successful": 1, "error": 0 } } } }
As you can see, in addition to all the already defined attributes for the job object, you can find a summary object when you retrieve a job.
If the job is in state initiating you can use this reading option for knowing the situation of the job, the number of operations that have been created in a concrete moment. The response body for a job in this case could be something like this:
{ "id": "adb3ef93-c123-4d74-897e-9842939721f1", "request": { "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE": "HARDWARE" }, "active": true, "notify": false, "user": "user@mail.com", "schedule": { "start": { "delayed": "300000" }, "stop": { "delayed": "6000000" }, "scattering": { "strategy": {} }, "window": { "weekly": [ { "daily": {} } ] } } }, "report": { "execution": { "activatedDate": "", "startedDate": "", "finishedDate": "" }, "summary": { "status": "IN_PROGRESS", "total": 10000, "inProgress": { "total": 2300, "scheduled": 0, "pendingExecution": 2300, "waitingForConnection": 0, "started": 0 }, "finished": { "total": 0, "successful": 0, "error": 0, "cancelled": { "total": 0, "byEngine": 0, "byUser": 0, "byTimeout": 0, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 0, "successful": 0, "error": 0 } } } }
Reading operations of a job
GET /north/v80/operation/jobs/{jobId}/operations
Operation list and operation object and attributes
A job could be executed on a few entities or on thousand of entities if you use a tag. You can retrieve a paginated result list with the operation for each entity, simply sending a GET request using the URL above. The result list have an array of operation objects.
Attributes | Constraints | Description |
---|---|---|
page |
Current page info |
|
operation [ ] |
Operation array |
Attributes | Constraints | Description |
---|---|---|
number |
Number |
Current page number |
of |
Number |
Number of pages |
Attributes | Constraints | Description |
---|---|---|
operationId |
UUID format |
Operation identifier |
entityId |
string |
Entity Identifier |
entityType |
string See Entity Type Enumeration |
Entity Type |
name |
string |
Operation name |
attemps |
Number of retries execution of an operation. See Attempts Object |
Attempts info |
parameters |
parameters |
Operation parameter values |
notify |
true / false |
Notification settings |
execution |
See Execution Object |
Execution info |
user |
string |
Identifies the user that has launched the operation |
status |
Operation status |
|
result |
Result of de operation |
|
description |
string |
Used by some device connectors to describe the result of the operation |
steps[] |
Operation step array |
Attributes | Constraints | Description |
---|---|---|
activatedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when operation is activated |
startedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when operation execution is started |
finishedDate |
The format is YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.00+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Date when operation is finished |
Attributes | Constraints | Description |
---|---|---|
total |
Number |
Total number of attempts programmed. |
current |
Number |
Attempt number in witch the operation had been executed. |
Reading operation list
GET /north/v80/operation/jobs/{jobId}/operations?start={start}&size={size} You can apply for the operation results list sending a GET request using the URL above. You must replace {jobId} with the identifier of the operation you want to retrieve and the pagination settings using {start} and {size} parameters.
Limit parameter | Constraints | Description |
---|---|---|
start[2] |
Number |
Page number you want to retrieve. |
size[2] |
Number |
Page size. The top margin for the page size in the limit object is 1000. If you setup a size attribute over this limit, you’ll receive a server error response. |
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ "http://[your_opengate_address]/north/v80/operation/jobs/0f519aca-e27d-4a4f-9a75-ee50604d6c1b/operations?start=2&size=2"
The response body could be something like this:
{ "page": { "number": 2, "of": 50 }, "operations": [ { "operationId": "86dd3409-6fcd-49d4-be6b-b2fa497207ec", "entityId": "device_1", "entityType": "GATEWAY", "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "attempts": { "total": 1, "current": 1 }, "notify": true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status": "FINISHED", "result": "SUCCESSFUL", "description": "successful operation", "steps": [ { "name": "REBOOT", "result": "SUCCESSFUL", "description": "Reset ok", "timestamp": "2012-09-27T16:46:02.10Z" } ] }, { "operationId": "29891afd-5f4f-4b23-800e-586bd4ecb0eb", "entityId": "device_2", "entityType": "GATEWAY", "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "attempts": { "total": 1, "current": 1 }, "notify": true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status": "FINISHED", "result": "SUCCESSFUL", "description": "successful operation", "steps": [ { "name": "REBOOT", "result": "SUCCESSFUL", "description": "Reset ok", "timestamp": "2012-09-27T16:46:02.10Z" } ] } ] }
Reading an operation result
GET /north/v80/operation/jobs/{jobId}/operations/{id}
You can read an operation results sending a GET request using the URL above. You must replace {jobId} with the identifier of the operation you want to retrieve and the {id} with an specific operation id.
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/jobs/0f519aca-e27d-4a4f-9a75-ee50604d6c1b/operations/86dd3409-6fcd-49d4-be6b-b2fa497207ec
The response body could be something like this:
{ "operationId": "86dd3409-6fcd-49d4-be6b-b2fa497207ec", "entityId": "device_1", "entityType": "GATEWAY", "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "attempts": { "total": 1, "current": 1 }, "notify": true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status": "FINISHED", "result": "SUCCESSFUL", "description": "successful operation", "steps": [ { "name": "REBOOT", "result": "SUCCESSFUL", "description": "Reboot ok", "timestamp": "2012-09-27T16:46:02.10Z" } ] }
Pause & Resume a Job
A Job execution can be paused and resumed using the Update operation modifying the "active" parameter:
-
Pause: Setting "active" to false when Job is already running. The Job passes to the PAUSE status
-
Resume: Setting "active" to true when Job is already paused. The Job passes to the IN_PROGRESS status
See Updating Job operation section.
Updating a job
PUT /north/v80/operation/jobs/{jobid}
Once the Job is created you can update the job to:
-
Modify Job request parameters. You only can mofiy the next parameters
-
active
-
notify
-
callback
-
userNotes
-
schedule.start
-
schedule.stop
-
-
To change (append or remove) entities target list.
A previously created Job can only be updated when this job "active" parameter is set to false and the job has not started. |
When you finish the modification, in the latest PUT call, you have to change "active" parameter to true to enable the execution is started |
As in the POST operation the platform establishes a limit in the JSON size. See creating a Job section for more information about it. |
If Job is already started (IN_PROGRESS status) you have to change "active" parameter to false to pause the execution, in this state you can’t modify the features of the job |
If Job is already paused you have to change "active" parameter to true to resume the execution |
you can’t update the target section of a job based in a filter, for that you have to change "active" parameter to false and create a new job with the new filter |
You can update an already created job sending a PUT request using the URL above. You must replace {jobid} with the identifier of the job you want to update. This is the request using curl:
Using this operation, you can update all sections of a job.
curl --request PUT \ --data-binary @job.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/jobs/33eb9dfa-7a87-41f7-9bad-7b5a26712fec -H "Content-type: application/json"
The attached JSON file could be something like this:
{ "job" : { "request" : { "name" : "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "active" : true, "notify" : true, "callback" : "http://[your_application_address]/[your_URI]", "userNotes" : "My notes", "schedule" : { "start" : { "date" : "2010-12-11T10:10:00Z" }, "stop" : { "delayed" : 300000 } }, "operationParameters" : { "ackTimeout" : 5000, "timeout": 60000, "retries" : 0, "retriesDelay" : 1000 }, "target" : { "append" : { "entities" : [ "device_1", "device_2" ], }, "remove" : { "entities" : [ "device_3" ] } } } } }
You can use this operation to append or remove targets into a previously created Job. See examples below:
{ "job" : { "request" : { "target" : { "append" : { "entities" : [ "device_1", "device_2" "device_3" ] } } } } }
{ "job" : { "request" : { "target" : { "append" : { "tags" : ["tag_1"] } } } } }
{ "job" : { "request" : { "target" : { "remove" : { "entities" : [ "device_1", "device_2" "device_3" ] } } } } }
{ "job" : { "request" : { "target" : { "remove" : { "entities" : [] } } } } }
{ "job" : { "request" : { "target" : { "remove" : { "tags" : ["tag_1"] } } } } }
{ "job" : { "request" : { "active" : true } } }
{ "job" : { "request" : { "active" : false } } }
{ "job" : { "request" : { "active" : true } } }
In the response we should see a status code of 200 (updated) and a location header which tells us the location (including the assigned id). Let’s look the response.
HTTP/1.1 200 Updated Location: http://[your_opengate_address]/north/v80/operation/jobs/ffc4ae39-8126-4ab7-8e79-cbfa3dc45b1c
The response body could be something like this:
{ "job" : { "jobid" : "33eb9dfa-7a87-41f7-9bad-7b5a26712fec", "request" : { "name" : "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "report" : { "execution" : { "activatedDate" : "", "startedDate" : "", "finishedDate" : "" }, "target" : { "notProvisioned" : [ "device_1", "device_2", "device_3", "device_4" ], "notAllowed" : [ "device_5" ], "duplicated" : [ "device_7" ] } } } }
Deleting (Cancelling) an Job
DELETE /north/v80/operation/jobs/{jobId}
With this action you will be able of cancel a job created / executed previously.
Please, pay special attention to the fact that cancelling a job does not imply any roll-back in the already executed steps. So please, be extremely careful when you execute operations. |
When you cancel a job, in a first moment the job state will be "cancelling". This state will become "Cancelled" when all of its operations are cancelled |
You can cancel a job sending a DELETE request using the URL above. The request using CURL is:
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/jobs/76796427-ec3e-11e1-aff1-0800200c9a66
Job Callbacks (Push service)
If "callback" parameter is well configured when Job is created, the OpenGate platform will perform different callbacks (See figure below):
The callbacks executed are:
Job Initiated Callback
The callback will be called when the initiated process has finished
Joined to the callback will be attached a JSON object including a Job object including:
-
"id": With the JobId
-
"request"
-
"report" object with the next objects:
-
"execution"
-
"summary"
-
{ "id": "a38f7735-dcef-4f5a-9ca4-b6a8f7517522", "request": { "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE": "HARDWARE" }, "active": true, "notify": false, "user": "user@mail.com", "userNotes": "My notes" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "", "finishedDate": "" }, "summary": { "status": "SCHEDULED", "total": 300, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "waitingForConnection": 0, "started": 0 }, "finished": { "total": 0, "successful": 0, "error": 0, "cancelled": { "total": 0, "byEngine": 0, "byUser": 0, "byTimeout": 0, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 0, "successful": 0, "error": 0 } } } }
Job Started Callback
The callback will be called after the Job execution is started
The callback will be called when the Job is executed. If it is scheduled the Job execution starts when the scheduling parameters indicate.
Joined to the callback will be attached a JSON object including a Job object including:
-
"id": With the JobId
-
"request" object
-
"report" object with the objects:
-
"execution"
-
{ "job" : { "id" : "33eb9dfa-7a87-41f7-9bad-7b5a26712fec", "request" : { "name" : "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "notify" : true, "user" : "user@mail.com" }, "report" : { "execution" : { "activatedDate" : "2010-12-20T10:10:00.00Z", "startedDate" : "2010-12-20T10:10:00.00Z", "finishedDate" : "" } } } }
Job Finished Callback
The callback will be called after the Job execution is finished including the options
-
When scheduling info indicates the job has terminated
-
When the Job is cancelled
-
When all the operations execution are completed
Joined to the callback will be attached a JSON object including:
-
"id": With the JobId
-
"request"
-
"report" object with the next objects:
-
"execution"
-
"summary"
-
-
"result": including the first page of operations result list with the objects
-
"page" object
-
"operations" array of "operation" objects
-
{ "job" : { "id" : "33eb9dfa-7a87-41f7-9bad-7b5a26712fec", "request" : { "name" : "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "notify" : true, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "waitingForConnection": 0, "started": 0 }, "finished": { "total": 2, "successful": 1, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } }, "finishedOutOfTime": { "total": 1, "successful": 1, "error": 0 } } }, "result" : { "page": { "number": 1, "of": 50 }, "operations": [ { "operationId": "86dd3409-6fcd-49d4-be6b-b2fa497207ec", "entityId": "device_1", "entityType": "GATEWAY", "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "notify": true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status": "FINISHED", "result": "SUCCESSFUL", "description": "successful operation", "steps": [ { "name": "RESET", "result": "SUCCESSFUL", "description": "Reset ok", "timestamp": "2012-09-27T16:46:02.10Z" } ] }, { "operationId": "29891afd-5f4f-4b23-800e-586bd4ecb0eb", "entityId": "device_2", "entityType": "GATEWAY", "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE":"HARDWARE" }, "notify": true, "execution": { "activatedDate": "2014-10-01T09:03:42Z", "startedDate": "2014-10-01T09:03:45Z", "finishedDate": "2014-10-01T09:04:45Z" }, "user" : "user@mail.com", "status": "FINISHED", "result": "SUCCESSFUL", "description": "successful operation", "steps": [ { "name": "RESET", "result": "SUCCESSFUL", "description": "Reset ok", "timestamp": "2012-09-27T16:46:02.10Z" } ] } ] } } }
the http method for push service is a POST |
Tasks
The operations service API provides the option of scheduling orders, either for a single execution at a given date or to schedule a task to run repeatedly over time you deem appropriate.
Task object
Attributes | Constraints | Description |
---|---|---|
id |
string |
Task ID used to identify tasks through API. If the value is passed when task is being created it must be unique. It the value is not passed in creating operation the platform will generate an UUID. |
string |
Task name |
|
description |
string |
task description |
active[task_obj_req_foot] |
true/false |
When is false jobs are not launched |
state |
string |
allowed values
|
schedule[task_obj_req_foot] |
Schedule jobs definition |
|
job[task_obj_req_foot] |
Job configuration to launch |
Attributes | Constraints | Description |
---|---|---|
request |
Job.Request configuration to launch |
Attributes | Constraints | Description |
---|---|---|
start |
First date execution, if you don’t specify the start field, the default value is NOW. |
|
stop |
See Task Stop Object |
Last execution configuration. If not present it means forever. |
repeating |
See Repeating Object |
Repeating strategy |
Attributes | Constraints | Description |
---|---|---|
period[3] |
Repeating in fix time periods. |
|
pattern[3] |
Repeating date patterns |
Attributes | Constraints | Description |
---|---|---|
Number |
Number of time units between two executions |
|
unit[repeatPeriod_obj_tool] |
Values:
|
Time unit |
Attributes | Constraints | Description |
---|---|---|
time |
The format is hh:mm:ssTZD (eg 19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Time of day |
See Weekly Object |
Weekly pattern. See weekly use |
|
monthly[repeating_pattern_foot] |
See Monthly Object |
Monthly pattern. See monthly use |
yearly[repeating_pattern_foot] |
See Yearly Object |
Yearly pattern. See yearly use |
Attributes | Constraints | Description |
---|---|---|
Values: * MON * TUE * WED * THU * FRI * SAT * SUN |
Weekday list |
Attributes | Constraints | Description |
---|---|---|
Number between 1 and 31 |
Day of month |
|
Values:
|
Month list |
Attributes | Constraints | Description |
---|---|---|
Number between 1 and 31 |
Day of month |
|
month[yearly_obj_foot] |
Values:
|
Month |
Schedule options
OpenGate gives you some ways to schedule operations
Start date of a task execution
If you need to delay the first execution of the task, you can define the field startTimestamp. If this field is not defined, the task will start immediately.
{ "task" : { ... "schedule":{ "start" : { "date" : "2012-09-10T12:33:43Z" }, ... }, ... } }
Stop date of a task execution
A task is running until:
-
A specific date (stopTimestamp)
-
A specific number of times (executions)
-
Forever (stop block undefined)
To end task in specific date you can define stopTimestamp task object :
{ "task" : { ... "schedule":{ "stop" : { "date" : "2012-09-10T12:33:43Z" }, ... } ... } }
Instead, if you want to define the number of executions carried you must define executions field:
{ "task" : { ... "stop" : { "mode" : "EXECUTIONS", "value" : 10 } ... } }
Task is executed 10 times
Finally, if you do not want to define the end date, with not defining the stop block is sufficient.
Schedule repeating
To schedule when you want the task launch a job you can define:
-
The time between two executions (period block)
-
A weekly pattern (datePattern - weekly block)
-
A monthly pattern (datePattern - monthly block)
-
A yearly pattern (datePattern - yearly block)
To define a fix time between two executions you must use period block:
{ "task":{ ... "schedule": { ... "repeating" : { "period": { <co id="scheduleOpt_note4"/> "each":10, "unit":"HOUR" } } } ... } }
This task launch a job each 10 hours
-
weekly use
Another option is to define a weekly pattern implementation. With this pattern the task launches a job at a specific time every weekday defined at field days:
{ "task":{ ... "schedule": { ... "repeating" : { "pattern": { "time"10:30:00Z", "weekly":{ "days":[ "MON", "WED" ] } } } } ... } }
This task launches a job every Monday and Wednesday at 10:30 am
-
monthly use
The third option is to define a monthly pattern implementation. With this option the task launch a job on the day materialized on time each month defined at field month:
{ "task": { ... "schedule":{ "repeating" : { "pattern": { "time":"10:30:00Z", "monthly":{ "day":12, "months":[ "JAN", "JUN" ] } } } } } }
This task launches a job every 12th of January and 12th of June at 10:30am
-
Yearly use
The last option is to define a yearly pattern implementation. With this option the task launches the job on a specific date each year.
{ "task":{ ... "schedule": { "repeating" : { "pattern" : { "time":"10:30:00Z", "yearly":{ "day":12, "month":"JAN" } } } } ... } }
This task launches a job every 12th of January at 10:30 am
Creating a task
POST /north/v80/operation/tasks
To create a task you can send a POST request using the URL above, including a correctly formatted JSON document in the POST body.
-
Adding a target references array.
The target array of entities IDs is the easy way to select multiple devices and apply an operation on them. |
By operational issues, the service incorporates a limit in the size of the JSON file. This limit can be configured administratively and by default the limit is set at 300 KBytes. Please consult with your administrator to know the limit configured. |
If you need to launch a operation over a large list of entities you can create a Task using POST operation and after using updating operation (PUT) to append new entities to the target considering the mentioned limit. All these changes will take effect for the next executions of the Tasks (not for the currently being executed Job). |
-
Using a previously created tag.
You can’t mix target references with tag or filter references. |
-
Using filters
You can’t mix target references with tag or filter references. |
You can’t use a previously created filter |
There is an optional parameter for this alternative ?entityType. This parameter restrict the filter to an specific type of entity, If you include this parameter in the Uri of the request only the entities belonging to the selected type will be considered. The available values for this parameter are (in uppercase):
|
{ "task":{ "id":"task_1", "name":"task_1_name", "description":"example task request", "active":true, "schedule":{ "start" : { "date" : "2010-12-11T10:10:00Z" }, "stop":{ "executions": 10 }, "repeating":{ "period" : { "each":7, "unit":"DAYS" }, "pattern" : { "time": "10:30:00Z", "weekly":{ "days":[ "MON", "WED" ] } } } }, "job":{ "request" : { "name":"REBOOT_EQUIPMENT", "parameters":{ "TYPE":"HARDWARE" }, "schedule" : { "stop" : { "delayed" : 300000 } }, "notify":true, "callback" : "http://[your_application_address]/[your_URI]", "operationParameters" : { "ackTimeout" : 5000, "timeout": 60000, "retries" : 0, "retriesDelay" : 1000 }, "target":{ "append" : { "entities" : [ "device_1", "device_2" ], }, "remove" : { "entities" : [ "device_3" ] } } } } } }
Once you have the task configured in JSON, you must send it as a POST request. This is an example using curl:
curl --request POST \ --data-binary @task.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/tasks \ -H "Content-type: application/json"
Example or requests with parameter entityType
curl --request POST \ --data-binary @task.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/tasks?entityType=GATEWAY \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned id) of the newly created order. Let’s look the response.
HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/operation/tasks/task_1
Reading a task
GET /north/v80/operation/tasks/{taskId}
You can apply for a task sending a GET request using the URL above with the identifier of the task you want to retrieve. This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/tasks/task_1
The response body could be something like this:
{ "task":{ "id":"task_1", "name":"task_1_name", "description":"example task request", "active":true, "state":ACTIVE, "schedule":{ "start" : { "date" : "2010-12-11T10:10:00Z" }, "stop":{ "executions": 10 }, "repeating":{ "period" : { "each":7, "unit":"DAYS" }, "pattern" : { "time": "10:30:00Z", "weekly":{ "days":[ "MON", "WED" ] } } } }, "job":{ "request" : { "name":"REBOOT_EQUIPMENT", "parameters":{ "TYPE":"HARDWARE" }, "schedule" : { "stop" : { "delayed" : 300000 } }, "notify":true, "user" : "user@mail.com", "callback" : "http://[your_application_address]/[your_URI]", "operationParameters" : { "ackTimeout" : 5000, "timeout": 60000, "retries" : 0, "retriesDelay" : 1000 } } } } }
Reading launched jobs in a task
GET /north/v80/operation/tasks/{taskId}/jobs?start={start}&size={size}
You can apply for the job executions list sending a GET request using the URL above. You must replace {taskId} with the identifier of the task you want to retrieve and the pagination settings using {start} and {size} parameters.
Limit parameter | Constraints | Description |
---|---|---|
start[4] |
Number |
Page number you want to retrieve. |
size[4] |
Number |
Page size. The top margin for the page size in the limit object is 1000. If you setup a size attribute over this limit, you’ll receive a server error response. |
This is the request using curl:
curl --request GET \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ "http://[your_opengate_address]/north/v80/operation/tasks/task_1/jobs?start=1&size=2"
The response body could be something like this:
{ "page":{ "number":1, "of":5 }, "jobs":[ { "id": "38a303e4-8dca-46e1-9977-b9a0b8231f71", "request": { "name": "EQUIPMENT_DIAGNOSTIC", "parameters": { "TYPE" : "HARDWARE" }, "active": true, "notify": false, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "waitingForConnection": 0, "started": 0 }, "finished": { "total": 3, "successful": 2, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } } } } }, { "id": "2569ac5e-55e4-519d-fd58-67e9d1a24dd1", "request": { "name": "REBOOT_EQUIPMENT", "parameters": { "TYPE" : "HARDWARE" }, "active": true, "notify": false, "user" : "user@mail.com" }, "report": { "execution": { "activatedDate": "2014-03-12T11:43:35Z", "startedDate": "2014-03-12T11:43:35Z", "finishedDate": "2014-03-12T11:44:52Z" }, "summary": { "status": "FINISHED", "total": 3, "inProgress": { "total": 0, "scheduled": 0, "pendingExecution": 0, "waitingForConnection": 0, "started": 0 }, "finished": { "total": 3, "successful": 2, "error": 0, "cancelled": { "total": 1, "byEngine": 0, "byUser": 0, "byTimeout": 1, "byExternalTimeout": 0, "byExternal": 0 } } } } } ] }
Updating a task
PUT /north/v80/operation/tasks/{taskId} You can update a task sending a PUT request using the URL above. You must replace {taskId} with the identifier of the task you want to update. This is the request using curl:
Changes are only applied to the next executions of the task nor the current Job being executed |
curl --request PUT \ --data-binary @task.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/tasks/task_1 \ -H "Content-type: application/json"
Adding entities on a task
You can add entities on a task, using "target" JSON object and taking into account the limits established in the creating section.
you can’t update the target section of a task based in a filter, for that you have to change "active" parameter to false and create a new task with the new filter |
{ "task":{ "name":"task_1", ... "job":{ "request" : { ... "target":{ "append" : { "entities" : [ "device_1", "device_2" ], } } } } } }
Deleting entities on a task
You can remove entities on a task, using "target" JSON object and taking into account the limits established in the creating section.
{ "task":{ "name":"task_1", ... "job":{ "request" : { ... "target":{ "remove" : { "entities" : [ "device_3" ] } } } } } }
Deleting a task
DELETE /north/v80/operation/tasks/{taskId}
With this action you will be able of cancel a task created / executed previously.
Please, pay special attention to the fact that cancelling a task does not imply any roll-back in the already executed steps. So please, be extremely careful when you execute operations. |
When you cancel a task the new state of the task is "cancelled" but there is a exception, if just in the moment when you cancel the task there is a job of this task in state executing the task will be in state "cancelling" until the job finish all of its operations, in than moment the task will move its state to "cancelled" |
You can cancel a task sending a DELETE request to your OpenGate OSS API interface, using the URL above. The request using CURL is:
curl --request DELETE \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/operation/tasks/task_1
Alarm operations
You can attend or close your opened alarms through the OpenGate operations API.
Alarm Operation Objects
Alarm state change operation structure
Entity | Constraint | Description |
---|---|---|
id |
UUID format. string |
Unique identification of the alarm instance |
action |
String enumeration with the next values:
|
Severity of the raised alarm |
Alarm operation response structure
attribute (* required) | Description |
---|---|
result |
see result object below |
attribute (* required) | Description |
---|---|
count |
number of processed instances |
successful |
number of instances that have been processed with success |
error |
see error object below |
attribute (* required) | Description |
---|---|
notExist |
see error summary below |
attribute (* required) | Description |
---|---|
count |
number of occurrences of this error |
list |
string array of the alarm instance identifiers that have produced the error |
Change the alarm state: attend or close
POST /north/v80/alarms
Alarm state change can be executed by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.
{ "action" : "CLOSE", "alarms" : [ "50dca9ab-f552-4805-9cff-019090d5b92b", "50dca9ab-f552-4805-9cff-019090d5b92c" ], "notes" : "notes of the reason" }
{ "action" : "ATTEND", "alarms" : [ "50dca9ab-f552-4805-9cff-019090d5b92b", "50dca9ab-f552-4805-9cff-019090d5b92c" ], "notes" : "notes of the reason" }
By operational issues, the service incorporates a limit in the array size of the JSON file. This limit can be configured administratively and by default the limit is set to 5.000 elements in the array. Please consult with your administrator to know the limit configured. |
Using curl to perform any of the previous requests:
curl --request POST \ --data-binary @operation_alarm.json \ --header "X-ApiKey: YOUR_API_KEY_HERE" \ --verbose \ http://[your_opengate_address]/north/v80/alarms \ -H "Content-type: application/json"
In the response we should see a status code of 201 (created) and a JSON with the response of the operation. Let’s look the response.
HTTP/1.1 201 Created
{ "result": { "count": 2, "succesfull": 1, "error": { "count": 1, "notExist" : { "count": 1, "list": [ "50dca9ab-f552-4805-9cff-019090d5b92c" ] } } } }
If the value obtained in the successful section is 0, ie, all the alarms on which wanted to operate are wrong, code 400 is returned, and more specifically a 6003, because the action could not be performed |
Annexes
Common Information
Structures
Entity Type Enumeration
Type of entity
GATEWAY |
M2M device like concentrator or smart router, modem or gateway, etc. |
ASSET |
Machine or sensor |
COMMUNICATIONS_MODULE |
Internal modem or interface for communications |
SUBSCRIPTION |
Logical identifier for a communication channel as a GMS line |
SUBSCRIBER |
Physical device associated to a Logical subscription |
available time zone
This is the time zone available
Name |
---|
ACT |
AET |
Africa/Abidjan |
Africa/Accra |
Africa/Addis_Ababa |
Africa/Algiers |
Africa/Asmara |
Africa/Asmera |
Africa/Bamako |
Africa/Bangui |
Africa/Banjul |
Africa/Bissau |
Africa/Blantyre |
Africa/Brazzaville |
Africa/Bujumbura |
Africa/Cairo |
Africa/Casablanca |
Africa/Ceuta |
Africa/Conakry |
Africa/Dakar |
Africa/Dar_es_Salaam |
Africa/Djibouti |
Africa/Douala |
Africa/El_Aaiun |
Africa/Freetown |
Africa/Gaborone |
Africa/Harare |
Africa/Johannesburg |
Africa/Juba |
Africa/Kampala |
Africa/Khartoum |
Africa/Kigali |
Africa/Kinshasa |
Africa/Lagos |
Africa/Libreville |
Africa/Lome |
Africa/Luanda |
Africa/Lubumbashi |
Africa/Lusaka |
Africa/Malabo |
Africa/Maputo |
Africa/Maseru |
Africa/Mbabane |
Africa/Mogadishu |
Africa/Monrovia |
Africa/Nairobi |
Africa/Ndjamena |
Africa/Niamey |
Africa/Nouakchott |
Africa/Ouagadougou |
Africa/Porto-Novo |
Africa/Sao_Tome |
Africa/Timbuktu |
Africa/Tripoli |
Africa/Tunis |
Africa/Windhoek |
AGT |
America/Adak |
America/Anchorage |
America/Anguilla |
America/Antigua |
America/Araguaina |
America/Argentina/Buenos_Aires |
America/Argentina/Catamarca |
America/Argentina/ComodRivadavia |
America/Argentina/Cordoba |
America/Argentina/Jujuy |
America/Argentina/La_Rioja |
America/Argentina/Mendoza |
America/Argentina/Rio_Gallegos |
America/Argentina/Salta |
America/Argentina/San_Juan |
America/Argentina/San_Luis |
America/Argentina/Tucuman |
America/Argentina/Ushuaia |
America/Aruba |
America/Asuncion |
America/Atikokan |
America/Atka |
America/Bahia |
America/Bahia_Banderas |
America/Barbados |
America/Belem |
America/Belize |
America/Blanc-Sablon |
America/Boa_Vista |
America/Bogota |
America/Boise |
America/Buenos_Aires |
America/Cambridge_Bay |
America/Campo_Grande |
America/Cancun |
America/Caracas |
America/Catamarca |
America/Cayenne |
America/Cayman |
America/Chicago |
America/Chihuahua |
America/Coral_Harbour |
America/Cordoba |
America/Costa_Rica |
America/Creston |
America/Cuiaba |
America/Curacao |
America/Danmarkshavn |
America/Dawson |
America/Dawson_Creek |
America/Denver |
America/Detroit |
America/Dominica |
America/Edmonton |
America/Eirunepe |
America/El_Salvador |
America/Ensenada |
America/Fort_Nelson |
America/Fort_Wayne |
America/Fortaleza |
America/Glace_Bay |
America/Godthab |
America/Goose_Bay |
America/Grand_Turk |
America/Grenada |
America/Guadeloupe |
America/Guatemala |
America/Guayaquil |
America/Guyana |
America/Halifax |
America/Havana |
America/Hermosillo |
America/Indiana/Indianapolis |
America/Indiana/Knox |
America/Indiana/Marengo |
America/Indiana/Petersburg |
America/Indiana/Tell_City |
America/Indiana/Vevay |
America/Indiana/Vincennes |
America/Indiana/Winamac |
America/Indianapolis |
America/Inuvik |
America/Iqaluit |
America/Jamaica |
America/Jujuy |
America/Juneau |
America/Kentucky/Louisville |
America/Kentucky/Monticello |
America/Knox_IN |
America/Kralendijk |
America/La_Paz |
America/Lima |
America/Los_Angeles |
America/Louisville |
America/Lower_Princes |
America/Maceio |
America/Managua |
America/Manaus |
America/Marigot |
America/Martinique |
America/Matamoros |
America/Mazatlan |
America/Mendoza |
America/Menominee |
America/Merida |
America/Metlakatla |
America/Mexico_City |
America/Miquelon |
America/Moncton |
America/Monterrey |
America/Montevideo |
America/Montreal |
America/Montserrat |
America/Nassau |
America/New_York |
America/Nipigon |
America/Nome |
America/Noronha |
America/North_Dakota/Beulah |
America/North_Dakota/Center |
America/North_Dakota/New_Salem |
America/Ojinaga |
America/Panama |
America/Pangnirtung |
America/Paramaribo |
America/Phoenix |
America/Port_of_Spain |
America/Port-au-Prince |
America/Porto_Acre |
America/Porto_Velho |
America/Puerto_Rico |
America/Rainy_River |
America/Rankin_Inlet |
America/Recife |
America/Regina |
America/Resolute |
America/Rio_Branco |
America/Rosario |
America/Santa_Isabel |
America/Santarem |
America/Santiago |
America/Santo_Domingo |
America/Sao_Paulo |
America/Scoresbysund |
America/Shiprock |
America/Sitka |
America/St_Barthelemy |
America/St_Johns |
America/St_Kitts |
America/St_Lucia |
America/St_Thomas |
America/St_Vincent |
America/Swift_Current |
America/Tegucigalpa |
America/Thule |
America/Thunder_Bay |
America/Tijuana |
America/Toronto |
America/Tortola |
America/Vancouver |
America/Virgin |
America/Whitehorse |
America/Winnipeg |
America/Yakutat |
America/Yellowknife |
Antarctica/Casey |
Antarctica/Davis |
Antarctica/DumontDUrville |
Antarctica/Macquarie |
Antarctica/Mawson |
Antarctica/McMurdo |
Antarctica/Palmer |
Antarctica/Rothera |
Antarctica/South_Pole |
Antarctica/Syowa |
Antarctica/Troll |
Antarctica/Vostok |
Arctic/Longyearbyen |
ART |
Asia/Aden |
Asia/Almaty |
Asia/Amman |
Asia/Anadyr |
Asia/Aqtau |
Asia/Aqtobe |
Asia/Ashgabat |
Asia/Ashkhabad |
Asia/Baghdad |
Asia/Bahrain |
Asia/Baku |
Asia/Bangkok |
Asia/Barnaul |
Asia/Beirut |
Asia/Bishkek |
Asia/Brunei |
Asia/Calcutta |
Asia/Chita |
Asia/Choibalsan |
Asia/Chongqing |
Asia/Chungking |
Asia/Colombo |
Asia/Dacca |
Asia/Damascus |
Asia/Dhaka |
Asia/Dili |
Asia/Dubai |
Asia/Dushanbe |
Asia/Gaza |
Asia/Harbin |
Asia/Hebron |
Asia/Ho_Chi_Minh |
Asia/Hong_Kong |
Asia/Hovd |
Asia/Irkutsk |
Asia/Istanbul |
Asia/Jakarta |
Asia/Jayapura |
Asia/Jerusalem |
Asia/Kabul |
Asia/Kamchatka |
Asia/Karachi |
Asia/Kashgar |
Asia/Kathmandu |
Asia/Katmandu |
Asia/Khandyga |
Asia/Kolkata |
Asia/Krasnoyarsk |
Asia/Kuala_Lumpur |
Asia/Kuching |
Asia/Kuwait |
Asia/Macao |
Asia/Macau |
Asia/Magadan |
Asia/Makassar |
Asia/Manila |
Asia/Muscat |
Asia/Nicosia |
Asia/Novokuznetsk |
Asia/Novosibirsk |
Asia/Omsk |
Asia/Oral |
Asia/Phnom_Penh |
Asia/Pontianak |
Asia/Pyongyang |
Asia/Qatar |
Asia/Qyzylorda |
Asia/Rangoon |
Asia/Riyadh |
Asia/Saigon |
Asia/Sakhalin |
Asia/Samarkand |
Asia/Seoul |
Asia/Shanghai |
Asia/Singapore |
Asia/Srednekolymsk |
Asia/Taipei |
Asia/Tashkent |
Asia/Tbilisi |
Asia/Tehran |
Asia/Tel_Aviv |
Asia/Thimbu |
Asia/Thimphu |
Asia/Tokyo |
Asia/Tomsk |
Asia/Ujung_Pandang |
Asia/Ulaanbaatar |
Asia/Ulan_Bator |
Asia/Urumqi |
Asia/Ust-Nera |
Asia/Vientiane |
Asia/Vladivostok |
Asia/Yakutsk |
Asia/Yekaterinburg |
Asia/Yerevan |
AST |
Atlantic/Azores |
Atlantic/Bermuda |
Atlantic/Canary |
Atlantic/Cape_Verde |
Atlantic/Faeroe |
Atlantic/Faroe |
Atlantic/Jan_Mayen |
Atlantic/Madeira |
Atlantic/Reykjavik |
Atlantic/South_Georgia |
Atlantic/St_Helena |
Atlantic/Stanley |
Australia/ACT |
Australia/Adelaide |
Australia/Brisbane |
Australia/Broken_Hill |
Australia/Canberra |
Australia/Currie |
Australia/Darwin |
Australia/Eucla |
Australia/Hobart |
Australia/LHI |
Australia/Lindeman |
Australia/Lord_Howe |
Australia/Melbourne |
Australia/North |
Australia/NSW |
Australia/Perth |
Australia/Queensland |
Australia/South |
Australia/Sydney |
Australia/Tasmania |
Australia/Victoria |
Australia/West |
Australia/Yancowinna |
BET |
Brazil/Acre |
Brazil/DeNoronha |
Brazil/East |
Brazil/West |
BST |
Canada/Atlantic |
Canada/Central |
Canada/East-Saskatchewan |
Canada/Eastern |
Canada/Mountain |
Canada/Newfoundland |
Canada/Pacific |
Canada/Saskatchewan |
Canada/Yukon |
CAT |
CET |
Chile/Continental |
Chile/EasterIsland |
CNT |
CST |
CST6CDT |
CTT |
Cuba |
EAT |
ECT |
EET |
Egypt |
Eire |
EST |
EST5EDT |
Etc/GMT |
Etc/GMT-0 |
Etc/GMT-1 |
Etc/GMT-10 |
Etc/GMT-11 |
Etc/GMT-12 |
Etc/GMT-13 |
Etc/GMT-14 |
Etc/GMT-2 |
Etc/GMT-3 |
Etc/GMT-4 |
Etc/GMT-5 |
Etc/GMT-6 |
Etc/GMT-7 |
Etc/GMT-8 |
Etc/GMT-9 |
Etc/GMT+0 |
Etc/GMT+1 |
Etc/GMT+10 |
Etc/GMT+11 |
Etc/GMT+12 |
Etc/GMT+2 |
Etc/GMT+3 |
Etc/GMT+4 |
Etc/GMT+5 |
Etc/GMT+6 |
Etc/GMT+7 |
Etc/GMT+8 |
Etc/GMT+9 |
Etc/GMT0 |
Etc/Greenwich |
Etc/UCT |
Etc/Universal |
Etc/UTC |
Etc/Zulu |
Europe/Amsterdam |
Europe/Andorra |
Europe/Astrakhan |
Europe/Athens |
Europe/Belfast |
Europe/Belgrade |
Europe/Berlin |
Europe/Bratislava |
Europe/Brussels |
Europe/Bucharest |
Europe/Budapest |
Europe/Busingen |
Europe/Chisinau |
Europe/Copenhagen |
Europe/Dublin |
Europe/Gibraltar |
Europe/Guernsey |
Europe/Helsinki |
Europe/Isle_of_Man |
Europe/Istanbul |
Europe/Jersey |
Europe/Kaliningrad |
Europe/Kiev |
Europe/Kirov |
Europe/Lisbon |
Europe/Ljubljana |
Europe/London |
Europe/Luxembourg |
Europe/Madrid |
Europe/Malta |
Europe/Mariehamn |
Europe/Minsk |
Europe/Monaco |
Europe/Moscow |
Europe/Nicosia |
Europe/Oslo |
Europe/Paris |
Europe/Podgorica |
Europe/Prague |
Europe/Riga |
Europe/Rome |
Europe/Samara |
Europe/San_Marino |
Europe/Sarajevo |
Europe/Simferopol |
Europe/Skopje |
Europe/Sofia |
Europe/Stockholm |
Europe/Tallinn |
Europe/Tirane |
Europe/Tiraspol |
Europe/Ulyanovsk |
Europe/Uzhgorod |
Europe/Vaduz |
Europe/Vatican |
Europe/Vienna |
Europe/Vilnius |
Europe/Volgograd |
Europe/Warsaw |
Europe/Zagreb |
Europe/Zaporozhye |
Europe/Zurich |
GB |
GB-Eire |
GMT |
GMT0 |
Greenwich |
Hongkong |
HST |
Iceland |
IET |
Indian/Antananarivo |
Indian/Chagos |
Indian/Christmas |
Indian/Cocos |
Indian/Comoro |
Indian/Kerguelen |
Indian/Mahe |
Indian/Maldives |
Indian/Mauritius |
Indian/Mayotte |
Indian/Reunion |
Iran |
Israel |
IST |
Jamaica |
Japan |
JST |
Kwajalein |
Libya |
MET |
Mexico/BajaNorte |
Mexico/BajaSur |
Mexico/General |
MIT |
MST |
MST7MDT |
Navajo |
NET |
NST |
NZ |
NZ-CHAT |
Pacific/Apia |
Pacific/Auckland |
Pacific/Bougainville |
Pacific/Chatham |
Pacific/Chuuk |
Pacific/Easter |
Pacific/Efate |
Pacific/Enderbury |
Pacific/Fakaofo |
Pacific/Fiji |
Pacific/Funafuti |
Pacific/Galapagos |
Pacific/Gambier |
Pacific/Guadalcanal |
Pacific/Guam |
Pacific/Honolulu |
Pacific/Johnston |
Pacific/Kiritimati |
Pacific/Kosrae |
Pacific/Kwajalein |
Pacific/Majuro |
Pacific/Marquesas |
Pacific/Midway |
Pacific/Nauru |
Pacific/Niue |
Pacific/Norfolk |
Pacific/Noumea |
Pacific/Pago_Pago |
Pacific/Palau |
Pacific/Pitcairn |
Pacific/Pohnpei |
Pacific/Ponape |
Pacific/Port_Moresby |
Pacific/Rarotonga |
Pacific/Saipan |
Pacific/Samoa |
Pacific/Tahiti |
Pacific/Tarawa |
Pacific/Tongatapu |
Pacific/Truk |
Pacific/Wake |
Pacific/Wallis |
Pacific/Yap |
PLT |
PNT |
Poland |
Portugal |
PRC |
PRT |
PST |
PST8PDT |
ROK |
Singapore |
SST |
SystemV/AST4 |
SystemV/AST4ADT |
SystemV/CST6 |
SystemV/CST6CDT |
SystemV/EST5 |
SystemV/EST5EDT |
SystemV/HST10 |
SystemV/MST7 |
SystemV/MST7MDT |
SystemV/PST8 |
SystemV/PST8PDT |
SystemV/YST9 |
SystemV/YST9YDT |
Turkey |
UCT |
Universal |
US/Alaska |
US/Aleutian |
US/Arizona |
US/Central |
US/East-Indiana |
US/Eastern |
US/Hawaii |
US/Indiana-Starke |
US/Michigan |
US/Mountain |
US/Pacific |
US/Pacific-New |
US/Samoa |
UTC |
VST |
W-SU |
WET |
Zulu |
Operation Definition
Operation Parameters
Field | JSON type | Description | Used in |
---|---|---|---|
name |
string |
Name of the parameter used internally by the platform to identify the operation |
|
title |
string |
Displayable title of the parameter. This field supports all set of displayable characters including tags to be used with a multi language support. |
|
access |
string |
Parameter access type |
|
description |
string |
Displayable description of the parameter. This field supports all set of displayable characters including tags to be used with a multi language support. |
|
type |
string enumeration. See values in Type & Subtype table |
Indicates the data type for the values to be applied to the parameter |
|
subtype |
string enumeration. See values in Type & Subtype table |
Depends on the data type |
|
required |
boolean |
Indicates if parameter is required or not when a operation is called through the Jobs API |
|
attributes |
object. See Attributes Object |
This field allow to define some characteristics of the parameter when it is displayed. Also allow restrict the possible values |
|
properties[] |
array of Parameters Objects |
Only used when type is object |
|
value |
object. See Value Object |
Contains: * The default value when it is used in the operation catalog searching * The value set to the parameter when it is used in Job Requests |
|
protocols |
see protocol structure below |
only used with datamodels to know the protocol for use the parameter |
|
Attributes | Description |
---|---|
name |
Protocol name |
type |
data type for DLMS values |
alias |
Protocol alias |
version |
Version of the message document |
id |
Specific ID for the protocol OID (SNMP), OBIs code (DLMS), etc. unique property identifier |
Field | JSON type | Description | Used With types/subtypes |
---|---|---|---|
maxLength |
number |
Max length allowed |
|
validator |
string |
Regular expression to validate the value |
|
gt |
number |
Greater than |
|
lt |
number |
Lower than |
|
list[] |
array |
Fixed set of choices |
|
url |
string |
Dynamic set of choices |
|
Field | JSON type | Description | Used with type/subtype |
---|---|---|---|
string[operationParameterValueFootnote] |
string |
Contains the value |
|
boolean[operationParameterValueFootnote] |
boolean |
Contains the value |
|
number[operationParameterValueFootnote] |
number |
Contains the value |
|
object[operationParameterValueFootnote] |
object |
Contains the value |
|
array[][operationParameterValueFootnote] |
array |
Contains the value |
|
[5]
Operation Steps
Field | JSON type | Description | Used in |
---|---|---|---|
name |
string |
Unique name of the step used internally by the platform to identify the operation |
|
title |
string |
Displayable title of the step. This field supports all set of displayable characters including tags to be used with a multi language support. |
|
description |
string |
Displayable description of the step. This field supports all set of displayable characters including tags to be used with a multi language support. |
|
result |
Valid values:
|
Result of the step |
|
timestamp |
string |
Step execution timestamp. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
|
response[] |
array |
Array of parameter definition list required by the operation. See Parameters Object. |
|
Job Status Enumerations
IDLE |
The Job has been created and not started yet (Not activated) |
SCHEDULED |
The has been activated and scheduled |
IN_PROGRESS |
The Job has been started yet |
TIMEOUT_CANCELLED |
The Job has been cancelled because maximum timeout defined is expired |
OVERLAP_CANCELLED |
The Job has been cancelled because maximum timeout defined is expired |
FINISHED |
All operations in the Job have been finished |
FINISHED_WITH_ERRORS |
The job has finished with errors, could have some operations finished successfully and others cancelled or all of them cancelled |
PAUSED |
The Job has been paused |
CANCELLING |
The Job has been cancelled but is still finishing the cancelling of its operations |
CANCELLED |
The Job has been cancelled |
Operation Enumerations
PENDING |
The operation is pending to be started |
IN_PROGRESS |
The operation is started and waiting for completion |
FINISHED |
The operation has been completed |
TIMEOUT_CANCELLED |
The operation has been cancelled because maximum timeout defined is expired |
WAITING_FOR_ACK |
The operation is waiting for an Ack to be started |
WAITING_FOR_CONNECTION |
The operation is waiting for being started when the device is connected (when this option is enabled) |
FINISHED_OUT_OF_TIME |
The operation has finished and the result has been collected but out of time |
NOT_ALLOWED |
The operation can’t be executed over this device |
QUEUED |
The operation has been launched but still has not arrive to the device |
CANCELLED |
The operation has been cancelled |
SUCCESSFUL |
The operation has been completed with success |
OPERATION_PENDING |
The operation is queued to be executed |
ERROR_IN_PARAM |
The operation cannot be executed because there is an error in parameters passed |
NOT_ALLOWED |
The operation execution is not allowed for this entity |
NOT_SUPPORTED |
The operations is not supported by the entity |
ALREADY_IN_PROGRESS |
The operation is being executed |
ERROR_PROCESSING |
The operation has finished with an unknown error |
ERROR_TIMEOUT |
The operation could not be completed because a timeout in the device response |
TIMEOUT_CANCELLED |
The operation has been cancelled because maximum timeout defined is expired |
CANCELLED |
The operation has been cancelled by an user or through the API |
CANCELLED_INTERNAL |
The operation has been cancelled by internal engine. Please consult to your platform administrator |
Operation Schedule Objects
Attributes | Constraints | Description |
---|---|---|
delayed |
number |
Time in milliseconds. Only used when it is necessary to define a delay. This is the only valid option when you are scheduling the job of a task. |
date |
string |
Only used when it is necessary to define a exact date. The value contains a date. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime. You can’t use this option when you are scheduling the job of a task |
Attributes | Constraints | Description |
---|---|---|
delayed |
number |
Time in milliseconds. Only used when it is necessary to define a delay |
date |
string |
Only used when it is necessary to define a exact date. The value contains a date. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Attributes | Constraints | Description |
---|---|---|
delayed |
number |
Time in milliseconds. Only used when it is necessary to define a delay |
date |
string |
Only used when it is necessary to define a exact date. The value contains a date. The format is YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
executions |
number |
Only used in Tasks when it is necessary to define an exact number of repetitions |
Attributes | Constraints | Description |
---|---|---|
weekly |
Allows to configure the specific time of execution of a week |
Attributes | Constraints | Description |
---|---|---|
days |
string, valid values MON, TUE, WED, THU, FRI, SAT, SUN |
Allows to specify de available days of execution for the window |
daily |
Allows to specify de available time of execution for a specific day |
Attributes | Constraints | Description |
---|---|---|
start |
string |
Only used when it is necessary to define a exact date. The value contains a date. The format is hh:mm:ssTZD (eg 19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
stop |
string |
Only used when it is necessary to define a exact date. The value contains a date. The format is hh:mm:ssTZD (eg 19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime |
Attributes | Constraints | Description |
---|---|---|
maxSpread |
number |
Indicates the percentage of the effective time of the transaction in which the operations will spread, will be a value between 0 and 100 where 0 is the minimum time, ie operations run as fast as possible and 100 is the maximum time ie, operations will spread throughout the time available to run the job, the job time out, the default value is 0 |
Strategy |
In this block you can define how the dispersion is made for a particular parameter |
Attributes | Constraints | Description |
---|---|---|
factor |
number |
indicates the rate or level of dispersion that will be applied to each block of operation with entities that have a common "field", varies between 0 and 100. 0 is minimal dispersion or what is the same, maximum clustering, ie all operations running on entities with the same "field" grouped to the fullest. And 100 is maximum scattering or minimum dispersion clustering, ie all operations groups whose entities have common "field" are scattered throughout the effective time. The default value is 0 |
field |
string |
Indicates the element of the entity, either provisioned or collected, by which they will launch operations group. At this moment only the field "subscription.collected.cellInfo" is available |
warningMaxRate |
number |
Speed control parameter for sending operations to verify that the resulting speed does not exceed the speed result of the maxSpread parameter, its units are operations per second |
JSON as interchange format
OpenGate Data Collector uses JSON as interchange format in its RESTful interface. Following sections show you how data is formatted.
Numbers
A number can be an integer or double-precision float. Here are some examples:
-
"time": 1356695180301
-
"value": 299.99
-
"maxValue": 1.23e11
-
"minValue": -10.5
The property name (i.e., maxValue
, etc.)
is a string surrounded by double quotes, but the value does not have
quotes. A number can be prefixed by a minus sign. The exponent
portion (denoted by e or E) comes after the number value, and can
have an optional plus or minus sign. Neither leading zeroed, octal,
nor hexadecimal values are allowed.
Dates
Within OpenGate Data Collector REST API dates parameters are represented by strings with ISO 8601:2004 standard. This standard is related to data elements and interchange formats – Information interchange – Representation of dates and times specifies date and times representation providing unambiguous notation and facilitates data migration between different systems.
What | Format | Sample |
---|---|---|
Year |
|
(eg 2015) |
Year and month |
|
(eg 2015-10) |
Complete date |
|
(eg 2015-10-06) |
Complete date plus hours and minutes |
|
(eg 2015-10-06T17:35) |
Complete date plus hours, minutes and seconds |
|
(eg 2015-10-06T17:35:21) |
Complete date plus hours, minutes, seconds and a decimal fraction of a second |
|
(eg 2015-10-06T17:35:21.45) |
-
YYYY
= four-digit year -
MM
= two-digit month (01=January, etc.) -
DD
= two-digit day of month (01 through 31) -
hh
= two digits of hour (00 through 23) (am/pm NOT allowed) -
mm
= two digits of minute (00 through 59) -
ss
= two digits of second (00 through 59) -
s
= one or more digits representing a decimal fraction of a second
UTC (Coordinated Universal Time) is the time standard used for all dates. |
Open resource of documentation at wikipedia.
IoT Concepts
Based in the "bigdata" paradigm, the OpenGate platform allows collecting non structured information from devices (sensors, machines, etc.) using South API (connectors) using the datastream concept. Next figure shows the main concepts of the IoT API:
Understanding the usage of this API requires understand first the main resources involved. They are:
-
Device: Represents the physical element (communications devices, concentrators, machines, sensors, etc.) which information is being collected.
-
Feed: Represents the logical elements (users, multiple instances of the same datastream in a device, etc.) which information is being collected.
-
Datamodel: It defines all the variables associated to a device or type of entity for its management and monitoring. These variables are defined like datastreams template and they represent the information about an individual "measure" that evolves over time, that is, define the main features of a datastream, see DataStream Template.
To know all the necessary attributes of the datamodel, see Datamodel description |
To know all datastreams that offers the OpenGate platform, see Default Datamodels |
To find information about how to provision new datamodels See Datamodels Provision in the provision API |
-
Datastream (Instance of Datastream): It is the current value of a datastream. Every datastream instance must have a unique (within the device) alphanumeric Identifier. If the name of the datastream instance matches with the datastream template name the instance inherits main features of the datamodel as units, period, tags, etc.
-
Datapoint: It represents a single value of a datastream at a specific point in time. See datapoint attribute to know all the necessary attributes. The instance of datastream will be a datapoint in the time.
The |
The set of datapoints is the historical data of the measure |
Device Datamodel Concept
The device datamodel is formed by the set of parameters defined in one or several profiles.
The name or identifier of each parameter can have the character . to separate the different parts of the datamodel. Then the entire list can be viewed as a parameters tree. See following parameter list:
-
provision.device.administrativeState
-
provision.device.operationalStatus
-
provision.customerParameter
-
device.operationalStatus
-
health.heart.rate
Can be viewed as:
Understanding OpenGate IoT resources usage
To clearly understand usage of the concepts described above it is necessary to explain two differents IoT scenarios Smart metering scenario and eHealth scenario to know how resources can be used to support the requirements:
Smart metering scenario
This example describes a scenario involving two basic parameters that are collected periodically from a device:
-
energy consumption
-
power consumption
Basic use case
The simplest design is showed in the next figure:
It will be implemented using:
-
Two datastreams of information
-
electricity.consumption
-
electricity.power
-
-
The device will be associated to the smart meter using as device identifier the unique number of the meter
-
Feed resource is not used because all measures can be collected and retrieved using device identifier only.
Enhanced use case
In a more realistic scenario the device meter can be changed (due to a maintenance issue or other) but the new measures need to be associated to the same measurement point.
In this case it will be implemented using:
-
Two datastreams of information
-
electricity.consumption
-
electricity.power
-
-
The device will be associated to the smart meter using as device identifier the unique number of the meter
-
The feed resource is used to:
-
To identify the user
-
To group around it the measures of each datastream but taken from different devices as a same collection of datapoints
-
To group all the datastreams of the different sensor types
-
-
The measure-device association can be traced because for the collection of datapoints of a same datastream
eHealth scenario
This example describes a scenario involving two basic parameters that are collected periodically from a device:
-
Weight
-
Heart Rate
To be more realistic, the user can take the measures in different medical centres
In this case it will be implemented using:
-
Two datastreams of information
-
health.weight
-
health.heart.rate
-
-
The device will be associated to the different health sensors using as device identifier (serial number or other) the unique number of each device
-
The feed resource is used to:
-
To identify the user
-
To group around it the measures of each datastream but taken from different devices as a same collection of datapoints
-
To group all the datastreams of the different sensor types
-
-
The measure-device association can be traced because for the collection of datapoints of a same datastream to know from which device was recovered each measure
Datamodel Description
A datamodel is a set of datastream templates. The JSON format of a datamodel is:
Attribute | Mandatory | Description |
---|---|---|
|
Yes |
Datamodel Identifier. It must be unique. |
|
Yes |
Name of the organization |
|
Yes |
Name of the datamodel |
|
No |
Description of the datamodel |
|
Yes |
Version of the datamodel |
|
Yes |
Array of resourceType allowed, see entities |
|
No |
Set of categories that group the templates. If it does not exist a defined category, the list can be empty. See Datamodel Category Object |
Attribute | Mandatory | Description |
---|---|---|
|
Yes |
Identifier of the category |
|
No |
Name of the category |
|
No |
Set of templates grouped. If it does not exist a defined datastream in the category, the list can be empty. See IoT Datastream template Object |
Datastream Template Description
Attribute | Mandatory | Description |
---|---|---|
|
Yes |
Identifier of the template. It is unique by organization (not by datamodel). It can not start with device or provision.device. It can not contain the character "underline". |
|
Yes |
Name of the template |
|
Yes |
Description of the template |
|
No |
String enumeration, one of: - - - |
|
No |
Only used when you want to determinate if a datastream is writeable. The access field can take three values - READ. This is the default value - WRITE - READ,WRITE All the datastreams are by default read, I mean, all datastreams can be readen, the devices or third parties can send the value of a datastream and this value processed by the platform, read. But, If you want to send a datastream value to a specific device, e.g. you want to change the value of a specific configuration parameter in one device, you can do it with a set operation and only datastreams with access type WRITE can be part of a set operation, so if you want use datastreams for changing values in configuration parameters you have to set the access value to WRITE. |
|
Yes |
Used for defining the format of the datastream value. It must have a correct jsonSchema format. See see schema object |
|
No |
Only used when you want to determinate the time to life of the collected datastream values. See IoT Datastream Storage Object, The default value is the organization’s plan storage value. |
|
No |
See unit object attributes |
|
No |
Boolean value to indicate if it is modifiable this datastream. The default value is true |
|
No |
Boolean value to indicate if it is a datastream internally calculated by the platform. The default value is false |
|
No |
Boolean value to indicate if it is required for this datastream. The default value is false |
|
No |
Only used when you want to quantify the collected datapoints and datastreams. If it exists, it must be complete. See IoT Datastream Qrating Object |
|
No |
Array of strings used to tag the datastream, 50 characters max. per tag |
|
No |
To be used in the future |
|
No |
Used for asociate an icon in the web datastream visualitation, See IoT Datastream Icon Object. |
Attribute | Description |
---|---|
|
String describing the type of unit you want |
|
String with the label you want for your unit |
|
String with the symbol you want for your unit |
This fields are not mandatory and its default value is empty |
{ "identifier": "health", "name": "health name", "description": "health description", "version": "1.2", "allowedResourceTypes":[ "entity.device" ], "categories": [ { "identifier": "heart", "name": "heart name", "datastreams": [ { "identifier": "health.heart.rate", "name": "health.heart.rate name", "description": "health.heart.rate description", "period": "INSTANT", "schema": { "type": "string" }, "unit": { "type": "SI", "label": "beats/second", "symbol": "bpm" }, "access": "READ", "storage": { "period": "DAYS", "total": 30 }, "tags": [ "health", "heart" ], "modifiable": true, "required": false } ] } ] }
Datastream Schema field description
It allows to define a valid schema json. There are some predefined types than can be used.
Datastream Qrating field description
QRating ponders all the data streams giving more importance to some over others based on their results giving a more reliable picture of the value collected and device status.
QRating show for each data point / datastream based on the configuration provided for each datastream the next outputs:
-
Scoring
-
Performance
-
Data quality.
The set of all qRating parameters values allow calculate the overall performance of the device.
Attribute | Mandatory | Type | Description |
---|---|---|---|
|
Yes |
String |
Version of the configurated Qrating |
|
Yes |
Number |
Datastream weight within the datastream |
|
Yes |
Number |
The best value that can be collected for the datastream |
|
Yes |
Number |
Minimum value accepted by the datastream (indicates when a data point collected is critical below the ideal) |
|
Yes |
Number |
Datastream desired minimum value (the datapoint collected is not critical but is below the ideal) |
|
Yes |
Number |
Datastream desired maximum value (the datapoint collected is not critical but is above the ideal) |
|
Yes |
Number |
Maximum value accepted by the datastream (indicates when a data point collected is critical above ideal) |
|
No |
Object |
It only applies if the collected datapoints are text typed, give a number for each allowed text value for calculate the qRating. See Conversion Matrix object attributes |
|
No |
Number, Seconds |
Allows calculate the median velocity of collection against the previous value collected taking this parameter as divisor |
It`s an array of value pairs
Attribute | Value of the attribute |
---|---|
|
Value translated for the expected value |
{ "identifier": "datamodel", "name": "datamodel.health", "version": "1.2", "categories": [ { "identifier": "category", "name": "heart", "datastreams": [ { "schema": { "type": "string" }, "identifier": "health.heart.rate", "period": "INSTANT", "unit": { "type": "SI", "label": "beats/second", "symbol": "bpm" }, "access": "READ", "name": "health.heart.rate", "storage": { "period": "DAYS", "total": 30 }, "tags": [ "health", "heart" ], "qrating": { "version": "1.0.0", "min_required": { "value": -5, "label": "FROZEN" }, "min_desired": { "value": 5, "label": "COLD" }, "ideal": { "value": 25, "label": "NORMAL/IDEAL" }, "max_desired": { "value": 35, "label": "HIGH" }, "max_allowed": { "value": 60, "label": "HOT" }, "max_score": 1000, "conversion_matrix": { "FROZEN": -5, "COLD": 5, "NORMAL": 36, "IDEAL": 36, "HIGH": 38, "HOT": 40 } }, "modifiable": true, "required": false } ] } ] }
Pay attention to the conversion matrix field, with this option when for example the datapoint collect a value of Frozen, the value is changed by -100 for allowing the qRating calculation. |
Pay attention to the cumulative period divisor field, without this option you receive a calculation of the datastream qrating comparing the last collected datapoint with the last one. With this option, qrating algorithm considers this value as a period divisor calculating the increment or decreasing median speed of the datastream cumulative value. For example, if you collect a total connection value of 60 in 1 hour and previous value was 0, the qrating value calculated is the increment (final value): 1 per minute (60 seconds divisor configured). Final value = (Difference since last datapoint * Time Divisor) / (Total time in seconds between datapoints) |
Datastream Storage field description
This field is oriented to save just only the datastream’s datapoints collected since a specific period of time, allowing the platform for deleting automatically the older datapoints.
In other words, the time a data point will be stored into OpenGate depends on the conjunction of this complex field period plus total and the value of the date field of the data point.
Attribute | Description |
---|---|
|
Specify the units of time that OpenGate have to consider for deleting historical datapoints, the available values are: - - - - |
|
Amount of period units for considering in the deleting process. |
It is impossible to have total without period If the period is NEVER, the total field is empty The storage can not be greater than the one defined in the organization |
Datastream Icon field description
This field is oriented to asociate an icon in the web datastream visualitation
Attribute | Description |
---|---|
|
Specify the class to represent icon’s name |
{ "icon": { "class": "fas fa-hourglass-end" } }
The name of the icon class is defined in https://fontawesome.com/icons?d=gallery |
Default Datamodels
This chapter describes the default built-in OpenGate datamodels through which the platform can provide already impleented added value services
This approach doesn’t prevent if you need that you can use other template format to implement the same scenario. New templates can be added using the right provision API to create datastream templates. |
SIM Management Specific Datamodels
IoT Energy Datamodels (Not preloaded)
This chapter describes how different flavour sensor signals can be modelled using the OpenGate datastream concept.
You can use provision these datamodels in your organization using the righ API |
Datamodel Basic Types
Type: address
Attribute | Value |
---|---|
type |
object |
description |
{ "properties": { "apn": { "title": "APN", "type": "string" }, "type": { "enum": [ "IPV4", "IPV6", "MAC48", "UNKNOWN", "SIGFOX", "HOSTNAME" ], "javaEnumNames": [ "IPV4", "IPV6", "MAC48", "UNKNOWN", "SIGFOX", "HOSTNAME" ], "title": "Type", "type": "string" }, "value": { "description": "value of the parameter", "title": "Value", "type": "string" } }, "public": true, "type": "object" }
Type: administrativeState
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "description": "", "enum": [ "ACTIVE", "BANNED", "DELETED", "INVALID", "READY", "REPAIR", "REQUESTED", "RETIRED", "SUSPENDED", "TESTED", "TESTING", "UNKNOWN" ], "javaEnumNames": [ "ACTIVE", "BANNED", "DELETED", "INVALID", "READY", "REPAIR", "REQUESTED", "RETIRED", "SUSPENDED", "TESTED", "TESTING", "UNKNOWN" ], "title": "Administrative State", "type": "string" }
Type: antennaStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "NORMAL", "OPEN", "SHORT_CIRCUIT", "UNKNOWN" ], "javaEnumNames": [ "NORMAL", "OPEN", "SHORT_CIRCUIT", "UNKNOWN" ], "type": "string" }
Type: area
Attribute | Value |
---|---|
type |
object |
description |
{ "properties": { "description": { "type": "string" }, "identifier": { "type": "string" }, "name": { "type": "string" }, "order": { "type": "integer" } }, "type": "object" }
Type: areas
Attribute | Value |
---|---|
type |
array |
description |
{ "items": { "$ref": "#/definitions/area" }, "type": "array" }
Type: arrayIdentifier
Attribute | Value |
---|---|
type |
array |
description |
{ "items": { "$ref": "#/definitions/ogIdentifier" }, "type": "array" }
Type: arrayString
Attribute | Value |
---|---|
type |
array |
description |
{ "items": { "type": "string" }, "type": "array" }
Type: assetAdministrativeState
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "description": "", "enum": [ "BANNED", "DELETED", "IN_MAINTENANCE", "IN_STOCK", "IN_TRANSIT", "IN_USE", "MISSING", "ORDERED", "READY", "RETIRED" ], "javaEnumNames": [ "BANNED", "DELETED", "IN_MAINTENANCE", "IN_STOCK", "IN_TRANSIT", "IN_USE", "MISSING", "ORDERED", "READY", "RETIRED" ], "title": "Asset Administrative State", "type": "string" }
Type: assetSpecificType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "BOX", "BUILDING", "CONTROL_HOUSE", "CRANE", "FOUNTAIN", "ENGINE", "HOUSE", "MACHINE", "OTHER", "PALLET", "PIPELINE", "SPOOL", "TOWER", "VEHICLE", "WIRE", "WORKER", "SUPPLY_POINT", "CONTRACTOR", "ORGANIZATION", "OPERATOR", "CHANNEL", "ZONE", "PROVINCE", "BTS", "POSTAL_CODE" ], "javaEnumNames": [ "BOX", "BUILDING", "CONTROL_HOUSE", "CRANE", "FOUNTAIN", "ENGINE", "HOUSE", "MACHINE", "OTHER", "PALLET", "PIPELINE", "SPOOL", "TOWER", "VEHICLE", "WIRE", "WORKER", "SUPPLY_POINT", "CONTRACTOR", "ORGANIZATION", "OPERATOR", "CHANNEL", "ZONE", "PROVINCE", "BTS", "POSTAL_CODE" ], "type": "string" }
Type: batteryStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "CHARGING", "CHARGED", "UNPLUGGED", "ERROR", "UNKNOWN" ], "javaEnumNames": [ "CHARGING", "CHARGED", "UNPLUGGED", "ERROR", "UNKNOWN" ], "type": "string" }
Type: certificateList
Attribute | Value |
---|---|
type |
array |
description |
{ "items": { "type": "string" }, "type": "array" }
Type: clock
Attribute | Value |
---|---|
type |
object |
description |
{ "description": "", "properties": { "datetime": { "$ref": "#/definitions/timestamp" }, "dst": { "properties": { "begin": { "$ref": "#/definitions/timestamp" }, "deviation": { "type": "number" }, "enabled": { "type": "boolean" }, "end": { "$ref": "#/definitions/timestamp" } }, "type": "object" }, "timezone": { "type": "number" } }, "public": true, "title": "Clock", "type": "object" }
Type: commsModuleOperationalStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "description": "", "enum": [ "STOPPED", "STOPPING", "STARTING", "RUNNING", "DISABLED", "ERROR" ], "javaEnumNames": [ "STOPPED", "STOPPING", "STARTING", "RUNNING", "DISABLED", "ERROR" ], "title": "Operational Status", "type": "string" }
Type: commsModuleSpecificType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "ADSL", "CAN", "ETH", "GENERIC", "GSM", "HAN", "I2C", "LOWPAN", "MESH", "MOBILE", "MULTIMOBILE", "PLC", "RS232", "RS422", "RS485", "SIGFOX", "UMTS", "WIFI", "ZIGBEE", "ZWAVE", "NARROWBAND", "LTE_M" ], "javaEnumNames": [ "ADSL", "CAN", "ETH", "GENERIC", "GSM", "HAN", "I2C", "LOWPAN", "MESH", "MOBILE", "MULTIMOBILE", "PLC", "RS232", "RS422", "RS485", "SIGFOX", "UMTS", "WIFI", "ZIGBEE", "ZWAVE", "NARROWBAND", "LTE_M" ], "type": "string" }
Type: coordinates
Attribute | Value |
---|---|
type |
array |
description |
A geographical coordinates |
{ "description": "A geographical coordinates", "items": { "type": "number" }, "maxItems": 2, "public": true, "type": "array" }
Type: cpuStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "IDLE", "IDLE/WORKING", "WORKING", "STRESSED", "OVERLOAD" ], "javaEnumNames": [ "IDLE", "IDLE_WORKING", "WORKING", "STRESSED", "OVERLOAD" ], "type": "string" }
Type: datamodelParamName
Attribute | Value |
---|---|
type |
string |
description |
Id of the parameter |
{ "description": "Id of the parameter", "title": "Id", "type": "string" }
Type: datamodelParamNameValue
Attribute | Value |
---|---|
type |
object |
description |
{ "properties": { "name": { "$ref": "#/definitions/datamodelParamName" }, "value": { "description": "Value of the parameter", "title": "Value", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }
Type: datamodelResponse
Attribute | Value |
---|---|
type |
object |
description |
{ "properties": { "name": { "description": "Id of the parameter", "title": "Id", "type": "string" }, "resultCode": { "$ref": "#/definitions/datamodelResultCode" }, "resultDescription": { "description": "Result description of Get Operation", "title": "Result Description", "type": "string" }, "value": { "description": "value of the parameter", "title": "type", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }
Type: datamodelResultCode
Attribute | Value |
---|---|
type |
string |
description |
Result code of Get Operation |
values |
|
{ "description": "Result code of Get Operation", "enum": [ "SUCCESS", "PARAM_NOT_SUPPORTED", "INVALID_FORMAT", "WRONG_VALUE", "UNKNOWN" ], "javaEnumNames": [ "SUCCESS", "PARAM_NOT_SUPPORTED", "INVALID_FORMAT", "WRONG_VALUE", "UNKNOWN" ], "title": "Result Code", "type": "string" }
Type: date
Attribute | Value |
---|---|
type |
string |
description |
date in ISO 8601 |
{ "description": "date in ISO 8601", "format": "date", "pattern": "^([0-9]{4})-?(1[0-2]|0[1-9])-?(3[01]|0[1-9]|[12][0-9])$", "public": true, "title": "date", "type": "string" }
Type: datetime
Attribute | Value |
---|---|
type |
object |
description |
{ "properties": { "date": { "$ref": "#/definitions/date" }, "dst": { "$ref": "#/definitions/dst" }, "time": { "description": "time in ISO 8601", "format": "time", "pattern": "^(2[0-3]|[01][0-9]):?([0-5][0-9]):?([0-5][0-9])$", "title": "time", "type": "string" }, "timezone": { "$ref": "#/definitions/timezone" } }, "required": [ "date", "time", "timezone", "dst" ], "type": "object" }
Type: deviceOperationalStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "description": "", "enum": [ "NORMAL", "SAFE_MODE", "TAMPER", "TEST", "DOWN", "ALARM", "UNKNOWN" ], "javaEnumNames": [ "NORMAL", "SAFE_MODE", "TAMPER", "TEST", "DOWN", "ALARM", "UNKNOWN" ], "title": "Operational Status", "type": "string" }
Type: deviceSpecificType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "BLOODPRESSURE_SENSOR", "COMHUB", "CONCENTRATOR", "CONTAINER", "COORDINATOR", "GATEWAY", "GENERIC", "GLUCOMETER_SENSOR", "METER", "MODEM", "ROUTER", "SENSOR", "TPV", "VEHICLE", "VENDING", "WEIGHT_SENSOR" ], "javaEnumNames": [ "BLOODPRESSURE_SENSOR", "COMHUB", "CONCENTRATOR", "CONTAINER", "COORDINATOR", "GATEWAY", "GENERIC", "GLUCOMETER_SENSOR", "METER", "MODEM", "ROUTER", "SENSOR", "TPV", "VEHICLE", "VENDING", "WEIGHT_SENSOR" ], "type": "string" }
Type: dst
Attribute | Value |
---|---|
type |
integer |
description |
{ "default": 0, "minimum": 0, "title": "DST", "type": "integer" }
Type: entityType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "description": "", "enum": [ "GATEWAY", "ASSET", "COMMUNICATIONS_MODULE", "SUBSCRIPTION", "SUBSCRIBER" ], "javaEnumNames": [ "GATEWAY", "ASSET", "COMMUNICATIONS_MODULE", "SUBSCRIPTION", "SUBSCRIBER" ], "title": "Entity Type", "type": "string" }
Type: ipStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "description": "", "enum": [ "OK", "NOK" ], "javaEnumNames": [ "OK", "NOK" ], "title": "IP Reachability Status", "type": "string" }
Type: ipv4
Attribute | Value |
---|---|
type |
string |
description |
IPV4 format |
{ "description": "IPV4 format", "format": "ipv4", "pattern": "((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])", "public": true, "title": "ipv4", "type": "string" }
Type: ipv6
Attribute | Value |
---|---|
type |
string |
description |
IPV6 format |
{ "description": "IPV6 format", "format": "ipv6", "pattern": "(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))", "public": true, "title": "ipv6", "type": "string" }
Type: location
Attribute | Value |
---|---|
type |
object |
description |
A geojson enriched for OpenGate |
{ "description": "A geojson enriched for OpenGate", "properties": { "accuracy": { "description": "position accuracy in meters", "type": "number" }, "address": { "type": "string" }, "country": { "type": "string" }, "position": { "description": "compatible with geojson format", "properties": { "coordinates": { "additionalItems": false, "description": "Format [longitude, latitude]", "items": { "type": "number" }, "minItems": 2, "type": "array" }, "type": { "default": "Point", "type": "string" } }, "required": [ "coordinates" ], "type": "object" }, "postal": { "type": "string" }, "province": { "type": "string" }, "region": { "type": "string" }, "source": { "enum": [ "MOBILE", "GPS", "GLONASS", "RTK", "RFID", "WIFI", "ZIGBEE", "LORA", "SIGFOX-BASIC", "SIGFOX-SPOTIT", "UNKNOWN" ], "javaEnumNames": [ "MOBILE", "GPS", "GLONASS", "RTK", "RFID", "WIFI", "ZIGBEE", "LORA", "SIGFOX_BASIC", "SIGFOX_SPOTIT", "UNKNOWN" ], "type": "string" }, "town": { "type": "string" }, "zoom": { "description": "zoom for the web map", "type": "number" } }, "public": true, "type": "object" }
Type: mac48
Attribute | Value |
---|---|
type |
string |
description |
MAC48 format |
{ "description": "MAC48 format", "pattern": "(([0-9A-Fa-f]{2}[-:]){5}[0-9A-Fa-f]{2})|(([0-9A-Fa-f]{4}){2}[0-9A-Fa-f]{4})", "public": true, "title": "mac48", "type": "string" }
Type: model
Attribute | Value |
---|---|
type |
object |
description |
{ "description": "", "properties": { "manufacturer": { "type": "string" }, "manufacturerOUI": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } }, "public": true, "title": "Model", "type": "object" }
Type: msisdn
Attribute | Value |
---|---|
type |
string |
description |
{ "maxLength": 15, "minLength": 7, "public": true, "type": "string" }
Type: ogIdentifier
Attribute | Value |
---|---|
type |
string |
description |
{ "pattern": "^[a-zA-Z0-9_@.-]*$", "public": true, "type": "string" }
Type: ogIdentifierUnreferenced
Attribute | Value |
---|---|
type |
string |
description |
{ "pattern": "^[a-zA-Z0-9_@.-]*$", "public": true, "type": "string" }
Type: ogImage
Attribute | Value |
---|---|
type |
string |
description |
{ "type": "string" }
Type: outage
Attribute | Value |
---|---|
type |
object |
description |
{ "properties": { "duration": { "type": "number" }, "started": { "$ref": "#/definitions/timestamp" } }, "type": "object" }
Type: percentage
Attribute | Value |
---|---|
type |
number |
description |
{ "maximum": 100, "minimum": 0, "public": true, "type": "number" }
Type: powerSupplySource
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "BATTERY", "DIESEL_GENERATOR", "NETWORK_PLUGGED", "SOLAR", "OTHER" ], "javaEnumNames": [ "BATTERY", "DIESEL_GENERATOR", "NETWORK_PLUGGED", "SOLAR", "OTHER" ], "type": "string" }
Type: powerSupplyStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "PLUGGED_CHARGING", "PLUGGED_CHARGED", "OUTAGE", "UNPLUGGED", "UNKNOWN" ], "javaEnumNames": [ "PLUGGED_CHARGING", "PLUGGED_CHARGED", "OUTAGE", "UNPLUGGED", "UNKNOWN" ], "type": "string" }
Type: presenceGprs
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "START", "STOP", "INTERIM_UPDATE", "ON", "OFF", "NOK" ], "javaEnumNames": [ "START", "STOP", "INTERIM_UPDATE", "ON", "OFF", "NOK" ], "type": "string" }
Type: presenceGsm
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "OK", "NOK", "UNCONFIG", "UNKNOWN" ], "javaEnumNames": [ "OK", "NOK", "UNCONFIG", "UNKNOWN" ], "type": "string" }
Type: presenceIp
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "OK", "NOK" ], "javaEnumNames": [ "OK", "NOK" ], "type": "string" }
Type: signalQualityStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "LOW_CRITICAL", "LOW_WARNING", "NORMAL", "EXCELENT" ], "javaEnumNames": [ "LOW_CRITICAL", "LOW_WARNING", "NORMAL", "EXCELENT" ], "type": "string" }
Type: signalStrengthStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "LOW_CRITICAL", "LOW_WARNING", "NORMAL", "EXCELENT" ], "javaEnumNames": [ "LOW_CRITICAL", "LOW_WARNING", "NORMAL", "EXCELENT" ], "type": "string" }
Type: software
Attribute | Value |
---|---|
type |
object |
description |
{ "description": "", "properties": { "name": { "type": "string" }, "type": { "enum": [ "SOFTWARE", "FIRMWARE" ], "javaEnumNames": [ "SOFTWARE", "FIRMWARE" ], "type": "string" }, "version": { "type": "string" } }, "public": true, "title": "Software", "type": "object" }
Type: softwareList
Attribute | Value |
---|---|
type |
array |
description |
{ "items": { "$ref": "#/definitions/software" }, "type": "array" }
Type: subscriberSpecificType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "ADSL", "CAN", "ETH", "GENERIC", "GSM", "HAN", "I2C", "LOWPAN", "MESH", "MOBILE", "PLC", "RS232", "RS422", "RS485", "SIM", "UMTS", "WIFI", "ZIGBEE", "ZWAVE", "NARROWBAND", "LTE_M" ], "javaEnumNames": [ "ADSL", "CAN", "ETH", "GENERIC", "GSM", "HAN", "I2C", "LOWPAN", "MESH", "MOBILE", "PLC", "RS232", "RS422", "RS485", "SIM", "UMTS", "WIFI", "ZIGBEE", "ZWAVE", "NARROWBAND", "LTE_M" ], "type": "string" }
Type: subscriptionSpecificType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "ADSL", "CAN", "ETH", "GENERIC", "GSM", "HAN", "I2C", "LOWPAN", "MESH", "MOBILE", "PLC", "RS232", "RS422", "RS485", "SIGFOX", "UMTS", "WIFI", "ZIGBEE", "ZWAVE", "NARROWBAND", "LTE_M" ], "javaEnumNames": [ "ADSL", "CAN", "ETH", "GENERIC", "GSM", "HAN", "I2C", "LOWPAN", "MESH", "MOBILE", "PLC", "RS232", "RS422", "RS485", "SIGFOX", "UMTS", "WIFI", "ZIGBEE", "ZWAVE", "NARROWBAND", "LTE_M" ], "type": "string" }
Type: temperatureStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "LOW_CRITICAL", "LOW_WARNING", "NORMAL", "HIGH_WARNING", "HIGH_CRITICAL" ], "javaEnumNames": [ "LOW_CRITICAL", "LOW_WARNING", "NORMAL", "HIGH_WARNING", "HIGH_CRITICAL" ], "type": "string" }
Type: text
Attribute | Value |
---|---|
type |
string |
description |
{ "type": "string" }
Type: ticketIdentifier
Attribute | Value |
---|---|
type |
string |
description |
{ "pattern": "^[a-zA-Z0-9_@.-]*$", "public": true, "type": "string" }
Type: ticketPriority
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "MAJOR", "MINOR", "CRITICAL", "BLOCKER" ], "javaEnumNames": [ "MAJOR", "MINOR", "CRITICAL", "BLOCKER" ], "title": "Priority", "type": "string" }
Type: ticketSeverity
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "CRITICAL", "URGENT", "WARNING", "NORMAL" ], "javaEnumNames": [ "CRITICAL", "URGENT", "WARNING", "NORMAL" ], "title": "Severity", "type": "string" }
Type: ticketSpecificType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "WORKORDER", "INCIDENT", "REQUEST", "FORM" ], "javaEnumNames": [ "WORKORDER", "INCIDENT", "REQUEST", "FORM" ], "title": "Specific Type", "type": "string" }
Type: ticketStatus
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "CREATED", "ASSIGNED", "ANSWERED", "RESTORED", "RESOLVED", "CLOSED" ], "javaEnumNames": [ "CREATED", "ASSIGNED", "ANSWERED", "RESTORED", "RESOLVED", "CLOSED" ], "title": "Status", "type": "string" }
Type: ticketType
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "INSTALLATION", "TEST", "TECHNICAL_TASK", "UNINSTALLATION", "MODIFICATION", "BALANCES_AT_MT_TELEMEDIDA" ], "javaEnumNames": [ "INSTALLATION", "TEST", "TECHNICAL_TASK", "UNINSTALLATION", "MODIFICATION", "BALANCES_AT_MT_TELEMEDIDA" ], "title": "Type", "type": "string" }
Type: time
Attribute | Value |
---|---|
type |
string |
description |
time in ISO 8601 |
{ "description": "time in ISO 8601", "format": "time", "pattern": "^(2[0-3]|[01][0-9]):?([0-5][0-9]):?([0-5][0-9])(\\.([0-9]{3}))?([Z]|(\\+|-)(2[0-3]|[01][0-9]):?([0-5][0-9]))$", "public": true, "title": "time", "type": "string" }
Type: timestamp
Attribute | Value |
---|---|
type |
string |
description |
date & time in ISO 8601 |
{ "description": "date & time in ISO 8601", "format": "date-time", "pattern": "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):?([0-5][0-9]):?([0-5][0-9])(\\.([0-9]{1,3}))?([Z]|(\\+|-)(2[0-3]|[01][0-9]):?([0-5][0-9]))$", "public": true, "title": "timestamp", "type": "string" }
Type: timezone
Attribute | Value |
---|---|
type |
string |
description |
{ "title": "timezone", "type": "string" }
Type: topologyPath
Attribute | Value |
---|---|
type |
array |
description |
{ "items": { "type": "string" }, "type": "array" }
Type: trafficSession
Attribute | Value |
---|---|
type |
object |
description |
{ "properties": { "address": { "$ref": "#/definitions/address" }, "duration": { "type": "number" }, "id": { "type": "string" }, "nasIp": { "$ref": "#/definitions/address" }, "radiusClientIp": { "$ref": "#/definitions/address" }, "receivedBytes": { "type": "number" }, "receivedPackets": { "type": "number" }, "sentBytes": { "type": "number" }, "sentPackets": { "type": "number" }, "status": { "enum": [ "TERMINATED", "IN_PROGRESS", "UNKNOWN" ], "javaEnumNames": [ "TERMINATED", "IN_PROGRESS", "UNKNOWN" ], "type": "string" }, "terminateCause": { "type": "string" } }, "public": true, "type": "object" }
Type: unifiedPresence
Attribute | Value |
---|---|
type |
string |
description |
|
values |
|
{ "enum": [ "IP", "GPRS", "GSM", "NOT_REGISTERED", "UNKNOWN" ], "javaEnumNames": [ "IP", "GPRS", "GSM", "NOT_REGISTERED", "UNKNOWN" ], "type": "string" }
Administrative Status Enumeration
State | Description |
---|---|
REQUESTED |
Entity requested to the supplier |
READY |
Entity ready for installation |
REPAIR |
Entity under repair |
TESTING |
Entity in tests |
ACTIVE |
Field deployed entity |
SUSPENDED |
Suspended its operation |
DELETED |
Entity removed from available stock |
RETIRED |
Field entity withdrawal |
BANNED |
Entity banned, It means that received information of this entity is not going to be collected |
For the BANNED administrative state there is a default alarm (See Rules Catalog, this alarm is launched when an event is collected with information of this entity. On the other hand you can program job or task over entities whit banned administrative state |
Operational Status Enumeration
Name | Description |
---|---|
UNKNOWN |
Not known |
NORMAL |
Normal Operation |
ALARM |
The device has active alarms |
DOWN |
The device is not operative. Could be running but it is not performing its operation |
SAFE_MODE |
The device is in Safe Mode (Sleeping, etc.) |
TAMPER |
The device was tampered |
TEST |
The device is working in test mode |
Name | Description |
---|---|
UNKNOWN |
Not known |
STOPPED |
The module is not working |
STARTING |
The module is booting |
RUNNING |
The module is working |
STOPPING |
The is shutting down |
ERROR |
The module has an error |
Common Objects Definition
Attribute | Description |
---|---|
type |
String Identifying the type of address |
value |
String. Address associated to the subscription |
apn |
String. Access Point Name used to establish mobile data session |
attribute | Description |
---|---|
width |
number |
heigth |
number |
Fields Definition
This section describes how fields can be defined. It is used in several JSON objects of the platform like Operations Catalog, Device Datamodels, IoT Datastream templates, etc.
Next tables describes the different elements of this definition.
Type | Subtype | Description |
---|---|---|
string |
|
Text based value |
boolean |
Boolean based value. Exmaples: true or false |
|
calendar |
|
Format is described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime. Examples: * datetime: "1997-07-16T19:20:30+01:00" * date: "1997-07-16" * time: "19:20:30+01:00" |
address |
|
Network address value |
number |
|
Numeric value |
enumeration |
|
Choice list values |
array |
|
Array of values |
coordinates |
|
Object indicating coordinates and timestamp in geotime subtype. Example: geo ([<longitude>,<latitude>])
[-3.700345, 40.416691] geotime
{ "timestamp": "1997-07-16T19:20:30+01:00", "latitude": 40.416691, "longitude": -3.700345 } geojson (described in the RFC 7946. Visit https://tools.ietf.org/html/rfc7946)
{ "type": "Feature", "geometry": { "type": "Point", "coordinates": [-3.700345, 40.416691] }, "properties": { "name": "Madrid-Spain" } } |
topology |
|
Object indicating relations. See following examples path
[ "granparent_1", "parent_1"] |
object |
None |
Not yet supported. For future uses only |
Type | Description |
---|---|
list[] |
It is an array with the values available when "type": "enumeration" |
visible |
Takes values as true or false and indicates that the field must be visible or not |
editable |
Takes values as true or false and indicates that the field must be editable or not |
gte |
Greater and Equal Than. Used when type or subtype is "number". Indicates the value range the field can take |
lte |
Lower and Equal Than. Used when type or subtype is "number". Indicates the value range the field can take |
gt |
Greater Than. Used when type or subtype is "number". Indicates the value range the field can take |
lt |
Lower Than. Used when type or subtype is "number". Indicates the value range the field can take |
Default Operations Catalog
OpenGate implements a default set of operations which is listed below:
Available operations through north api catalog searching is only indicative because the type of operations visibility can be enabled or disabled by the platform administrator to an specific user |
New adhoc Operations can be added to adapt to specific needs |
Applicable To | Name | North Api parameters | South Api parameters |
---|---|---|---|
Device |
UPDATE (See Device update) |
|
|
Device |
SET_CLOCK_EQUIPMENT |
If you don’t include parameters the time sent to the device will be the actual in the moment of operation execution. |
|
Device |
POWER_ON_EQUIPMENT |
||
Device |
POWER_OFF_EQUIPMENT |
||
Device |
REBOOT_EQUIPMENT |
|
Same |
Device |
REFRESH_LOCATION |
||
Device |
REFRESH_INFO |
||
Device |
REFRESH_PRESENCE |
||
Device |
STATUS_DIAGNOSTIC |
ADMINISTRATIVE_STATUS |
|
Device |
EQUIPMENT_DIAGNOSTIC |
|
Same |
Device |
WAKE_UP_COMMUNICATIONS |
|
|
Device |
RESET_COMMUNICATIONS |
PROFILE |
|
Device, Subscription, Subscriber |
ADMINISTRATIVE_STATUS_CHANGE |
STATUS |
|
Device |
SHUT_DOWN_COMMUNICATIONS |
PROFILE |
|
Subscription |
SERVICE_CONFIGURATION |
|
|
Subscription |
RATE_PLAN_CHANGE |
|
|
Subscription |
APN_ALLOWED |
|
|
Subscription |
SIM_REPLACEMENT |
ICCid |
|
Device |
FACTORY_RESET |
The SMS capability is possible onpremise solution. It is required integration with a external service provider |
Device Operations details
Device operations flows
Normally all the operations in the catalog has at least a minimun workflow to be fulfilled. Nevertheless there are operations that can have different flows depending on the devices behaviour. They are showed in the South Operations API.
Device operations parameters
As is stated above operations can have parameters as a list of different simple or complex fields with the necessary data for the operation execution.
Normally the specific parameters of a operation will be the same for the both APIs (North and South). Nevertheless there are operations that can have different list of parameters for North and South APIs. They are showed below. In this section it is described how the parameters in operations has to be interpreted in both API sides.
Tho understand this we take the next operation example:
-
Operation: REBOOT_EQUIPMENT
-
Parameters:
-
type (String. Enumeration indicating the type of the hardware)
-
applications (String array with the list of applications to be rebooted)
-
North API invocation
The next example shows how the parameters has to be filled in the North API call
"parameters": [ { "name":"TYPE", "value":{ "string":"HARDWARE" } }, { "name":"applications", "value":{ "array":[ "application1", "application2"] } } ]
South API invocation
The next example shows how the parameters will be received by the device through the Soutth API call
"parameters": [ { "name":"TYPE", "type":"string", "value":{ "string":"HARDWARE" } }, { "name":"applications", "type":"array", "subtype":"string", "value":{ "array":[ "application1", "application2"] } } ]
Device Operations: Update Operation
Flow diagram
This is an special operation for the platform. OpenGate suggest the implementation of a complete flow that allow cover all the possible stages of a device update.
In the real world the device can implement only part of the suggested stages or steps. Also it is supported any number and kind of steps your device implements |
The next figure shows this flow:
In bold format are marked the operations of the minimun flow required |
North API invocation
Device update operations are invoked by Backoffice applications through the OpenGate North API Operations section. So you can use all you learned about this API, you only have to pay attention to the specific operation name and parameters involved in device updates:
Parameter (*required) | Constraints | Description |
---|---|---|
bundleName* |
String |
Name of the bundle. |
bundleVersion * |
String |
Version of the bundle |
{ "job" : { "request" : { "name" : "UPDATE", "parameters": [ { "name" : "bundleName", "type":"string", "value" : { "string" : "bundle_1" } }, { "name" : "bundleVersion", "type":"string", "value" : { "string" : "1.0" } } ], "active" : true, "notify" : true, "callback" : "http://[your_application_address]/[your_URI]", "schedule" : { "start" : { "date" : "2012-09-10T12:33:43Z" }, "stop" : { "delayed" : 300000 } }, "operationParameters" : { "ackTimeout" : 5000, "timeout" : 6000, "retries" : 0, "retriesDelay" : 1000 }, "target" : { "append" : { "entities" : [ "device_1", "device_2" ] } } } } }
South API invocation
Device update operations are invoked by the OpenGate platform to the device through the OpenGate (see South API Operations section). So you can use all you learned about this API, you only have to pay attention to the specific operation name and parameters involved in device updates:
Parameter | Constraints | Description |
---|---|---|
bundleName |
String |
Name of the bundle. |
bundleVersion |
String |
Version of the bundle |
deploymentElements |
String |
Array of elements to be updated. See <South API Deployment Element Object |
Parameter | Constraints | Description |
---|---|---|
Name |
string |
deployment element name |
version |
string |
deployment element version |
type |
string |
Type of the deployment element |
downloadUrl |
string |
Version of the bundle |
path |
string |
Path in the device to install the element |
operation |
string |
Indicates the action to be done with the element |
option |
String |
Information additional if the element is optional or mandatory |
order |
String |
Order of the different deployment element into the bundle |
validators |
array |
To verify downloaded file. See <South API Deployment Element Object |
Parameter | Constraints | Description |
---|---|---|
type |
string |
Type of the validation algorithm |
value |
string |
string to perform the validation |
{ "operation": { "request": { "timestamp": 1453822201099, "name": "UPDATE", "parameters": [ { "name": "bundleName", "value": { "string": "bundle_1" } }, { "name": "bundleVersion", "value": { "string": "version_1" } }, { "name": "deploymentElements", "value": { "array": [ { "type": "FIRMWARE", "downloadUrl": "http://[your_opengate_address]/bundles/74427c0c-a28c-4765-92ef-30010adb733d/1002/firmware-1_1.1.bin", "path": "/home", "order": 1, "operation": "INSTALL", "option": "OPTIONAL", "validators": [ { "type": "SHA-256", "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "size": 18 } ] } } ], "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327" } } }
Rules Catalog
OpenGate implements a default set of rules which is listed below:
GET /north/v80/rules/catalog
In the next table is shown the list of the rules catalog incorporated to the platform by default
"Rule type" column indicates if the rule conditon is evaluated because you collected data in the South API (DATASTREAM), an operation were execute in Opengate platform (OPERATION), or an event were sent to Opengate platform (See device default allowed events in the Events examples section in the South API, and default operations in the Operations Catalog) |
Rule type | Name | Description | Configurable Parameters |
---|---|---|---|
DATASTREAM |
activityForbiddenDatastream |
Activity detected for an entity with administrative state disabled |
|
OPERATION |
activityForbiddenOperation |
Activity detected for an entity with administrative state disabled |
|
DATASTREAM |
areaInputWithParameter |
Checks if an entity has entered in a geofence |
|
DATASTREAM |
areaOutputWithParameter |
Checks if an entity has exitted of a geofence |
|
DATASTREAM |
batteryThreshold |
Current value of datastream has an unusual value |
|
DATASTREAM |
cancelBatteryThreshold |
Current value of datastream has is returned to usual value |
|
DATASTREAM |
changeCommsModuleOperationalStatusByNokPing |
Put selected operational status to communication module if consecutive NOK Ping reach selected value. Needs countPings rule enabled |
|
DATASTREAM |
changeCommsModuleOperationalStatusByOkPing |
Put selected operational status to communication module if OK Ping received |
|
DATASTREAM |
checkDistance |
Checks if entity is farther than a defined distance |
|
DATASTREAM |
collectAreas |
Calculate entity.area datastream (and its derivatives) based on entity.location datastream |
|
DATASTREAM |
countAccountingStart |
Count accounting start in subscription |
|
DATASTREAM |
countPings |
Count number of ping [OK/NOK/NOK consecutives] to get information in mobile net |
|
OPERATION |
diagnosticFailed |
Diagnostic with error in some operation |
|
EVENT |
messageFlowRateExceeded |
Message flow rate exceeded, not process message |
|
DATASTREAM |
mobileICCMismatch |
Collected ICC does not match with provisioned |
|
DATASTREAM |
mobileICCValueChanged |
Compare current with previous values of one datastream |
|
DATASTREAM |
presenceReachableAllInterfaces |
Verify if, at least one communication interface is reachable |
|
DATASTREAM |
presenceUnreachableAllInterfaces |
Verify if the device is unreacheable through all its communication interfaces |
|
DATASTREAM |
receivedBanned |
Received data for a banned entity |
|
EVENT |
securityConfigMismatch |
Security error validate, device validation failedSecurity error validate, device validation failed |
|
DATASTREAM |
subscriptionActivation |
Check if subscription is administrativeState = ACTIVE for a configured operator |
|
DATASTREAM |
subscriptionSuspension |
Check if subscription is administrativeState = SUSPENSION for a configured operator |
|
DATASTREAM |
sumSessionBytes |
Sum traffic bytes can get information in mobile net |
|
Notifications
The platform can send notifications using SNMP protocol using the OpenGate MIB
Legal information
Contact
Conditions and disclaimers
The information contained in this document is copyrighted and all rights are reserved by Amplia soluciones s.l.. Amplia soluciones s.l. reserves the right to make periodic modifications to the document without obligation to notify any person or entity of such revision. Copying, duplicating, selling, or otherwise distributing any part of the software or documentation without prior written consent of an authorized representative of microstrategy, inc. are prohibited.
Documentation is provided as a reference sample on an "as is'' basis, without warranty of any kind, either expressed or implied, including, without limitation, warranties that the documentation is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality, accuracy, and performance of the documentation is with you. Should any documentation prove defective in any respect, you (not the initial writer or any other contributor) assume the cost of any necessary servicing, repair or correction. This disclaimer of warranty constitutes an essential part of this license. No use of any documentation is authorized hereunder except under this disclaimer.
Under no circumstances and under no legal theory, whether in tort (including negligence), contract, or otherwise, shall the initial writer, any other contributor, or any distributor of documentation, or any supplier of any of such parties, be liable to any person for any direct, indirect, special, incidental, or consequential damages of any character including, without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other damages or losses arising out of or relating to the use of the documentation, even if such party shall have been informed of the possibility of such damages.
OpenGate and amplia))) are trademarks or registered trademarks of Amplia soluciones s.l.. All other company and product names may be trademarks of the respective companies with which they are associated. Specifications subject to change without notice. Amplia soluciones s.l.. is not responsible for errors or omissions.
Amplia soluciones s.l. makes no warranties or commitments concerning the availability of future products or versions that may be planned or under development whether they were notified or not in any format.
Default User Profiles
OpenGate by default incorporates a set of user profiles which is listed below:
New adhoc User Profiles can be added to adapt to specific needs |
Profile | Permissions |
---|---|
root |
|
admin_domain |
|
admin |
|
advanced |
|
viewer |
|