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:

ws api intro
Figure 1. OpenGate Web API main features

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

navigable tree
Figure 2. Navigable tree through URI

Response status and error messages

HTTP status codes

The OpenGate OSS API attempts to return appropriate HTTP status codes for every request.

Table 1. HTTP status codes
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.

Table 2. Error message object attributes
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:

Error Message Example1 in JSON format
{
    "errors":[
        {
            "code":2,
            "message":"Json is malformed"
        }
    ]
}
Error Message Example2 in JSON format
{
    "errors":[
        {
             "code":34,
             "message":"Sorry, that entity does not exist",
             "context" : [ {"name" : "param1", "value" : "value1"}, {"name" : "param2", "value" : "value2"}]
        }
    ]
}

Generic Errors

Table 4. 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

Table 5. Provision Generic
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.

Table 6. Provision Entity
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.

Table 7. Provision Datamodel
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.

Table 8. Provision Area
Code Returned HTTP Status Description

0x010300

HTTP 400

Coordinates do not represent a valid geojson.

Table 9. Provision Certificates
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.

Table 10. Provision Manufacturers
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.

Table 11. Provision Models
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.

Table 12. Provision Medias
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.

Table 13. Provision User
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.

Table 14. Provision Rule
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

Table 15. Provision Bundle
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.

Table 16. Provision Tag
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.

Table 17. Provision APN
Code Returned HTTP Status Description

0x010C00

HTTP 400

Apn not exists.

0x010C01

HTTP 400

Apn cannot be removed.

Table 18. Provision Radius Client
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.

Table 19. Provision Organization
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

Table 20. Job Generic
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

Table 21. Task Generic
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

Table 22. Operation Generic
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

Table 23. Alarm Generic
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

Table 24. Search Generic
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

Table 25. Event Generic
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.

Table 26. Event Gathering
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.

Flowcontrol

Table 27. Flowcontrol Generic
Code Returned HTTP Status Description

0x080000

HTTP 503

Redis server no available.

0x080001

HTTP 409

There is not configuration to the device.

0x080002

HTTP 409

Message size limit is overtake.

Provision

http://[your_opengate_address]/north/v80/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.

Common objects and attributes
{
  "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:

Table 28. Administrative data attributes
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.

Table 29. Administrative data attributes
Attribute Constraints Description

organization [1][2]


1 Forbidden in entity update operation
2 Required in entity insert operation

[a-zA-Z0-9_] max 50 chars

The organization that owns the entity.

In entity POST & PUT operations this field will be ignored because the used organization value is taken from the URL. It is included to maintain compatibility with the objects returned in search operations.

channel [1]


1 Required in entity insert operation

[a-zA-Z0-9_] max 50 chars

An administrative grouping method for your entities.

administrativeState

serviceGroup [1]


1 Forbidden in bundle operations

[a-zA-Z0-9_-] max 50 chars

Service configuration: configuration of services, operations available, etc.

workgroup [1]


1 Forbidden in entity operations

[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.

plan [1][2] optional


1 Forbidden in bundle operations
2 Optional in entity insert and update operation

[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

Administrative data as JSON document into a device entity
{
  "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.

Table 30. Service Groups available on OpenGate Cloud instance
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:

example normal json format with simple value
{
  "provision": {
    "administration": {
      "identifier": {
        "_current": {
          "value": "device_battery"
        }
      }
    }
  }
}

The flattened json format is:

example flattened json format with simple value
{
  "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:

example1 normal json format with complex value
{
  "provision": {
    "device": {
      "location": {
        "_current": {
          "value": {
            "position": {
              "type": "Point",
              "coordinates": [
                -3.7028,
                40.41675
              ]
            },
            "postal": "28013"
          }
        }
      }
    }
  }
}

The flattened json format is:

example1 flattened json format with complex value
{
  "provision.device.location": {
    "_value": {
      "_current": {
        "value": {
          "position": {
            "type": "Point",
            "coordinates": [
              -3.7028,
              40.41675
            ]
          },
          "postal": "28013"
        }
      }
    }
  }
}

Example2

The normal json format is:

example2 normal json format with complex value
{
  "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:

example2 flattened json format with complex value in creative operation
{
  "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:

example2 flattened json format with complex value in reading operation
{
  "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

csv format example
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

Table 31. APN Object
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

Table 32. Synchronized Cache Object
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.

Example 1. APN as JSON object
{
  "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:

Example 2. Read an APN as JSON document
{
  "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

Table 33. area objects and attributes
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).

Area determinated by a devices group as JSON object
{
  "identifier": "Id",
  "name": "area name",
  "description": "description",
  "geometry": {},
  "entities": [
    "identifier1"
  ]
}
Area determinated by a geojson as JSON object
{
  "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

Area determinated by a geojson and a devices group as JSON object
{
  "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:

Response of area
{
  "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

Table 34. Asset provision attributes
Object / attribute Description

administration

See Default Datamodels

asset

See Default Datamodels

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

Minimum asset JSON document for creating an asset
{
  "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)

Recommended asset JSON document for creating an asset
{
  "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)

Extended asset JSON document for creating an asset
{
  "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

Creating an asset with flattened 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:

Read asset as JSON document
{
  "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

Read asset with 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:

Updating an asset as JSON document
{
  "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:

Updating an asset as JSON document
{
  "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:

Patching an asset as JSON document
{
  "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:

Patching an asset as JSON document
{
  "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

Table 35. Bulk Object
Object / attribute Description

entities[]

The JSON response object is an array of entities response objects:

Table 36. JSON Entity Response Object
Object / attribute Description
Table 37. JSON 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

Table 38. CSV Provision Request Object
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

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

The CSV response object is a file with entities response objects:

Table 39. CSV Provision Response Object
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

Bulk Response as CSV document
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

Bulk Request as JSON document
{
  "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
Bulk Response as JSON document
[
  {
    "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

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=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
Bulk Response as CSV document
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

flattened bulk request as JSON document
{
  "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
Bulk Response as JSON document
[
  {
    "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

Bulk Request as JSON document
{
  "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
Bulk Response as JSON document
[
  {
    "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

Bulk flatted request as JSON document
{
  "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
Bulk Response as JSON document
[
  {
    "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

Bulk Request as JSON document
{
  "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
Bulk Response as JSON document
[
    {
        "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

Bulk flatted request as JSON document
{
  "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
Bulk Response as JSON document
[
    {
        "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.

Bulk Delete Request as JSON document
{
  "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

Bulk Delete Request as CSV document
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

Bulk flatted request as JSON document
{
  "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:

  1. SOFTWARE

  2. FIRMWARE

  3. CONFIGURATION

  4. PARAMETERS

Table 40. Bundle object and attributes
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:

  • HARDWARE_RESET

  • SOFTWARE_RESET

  • COMMS_DOWN

  • COMMS_UP

  • COMMS_RESET

postaction[]

Valid values:

  • HARDWARE_RESET

  • SOFTWARE_RESET

  • COMMS_DOWN

  • COMMS_UP

  • COMMS_RESET

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:

bundle workflow
Figure 3. Bundle management work flow

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

Example 3. Bundle as JSON document, ready for creation
{
    "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:

Example 4. Read bundle as JSON document
{
    "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:

Example 5. Bundle as JSON document, ready for update
{
    "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:

  • description

  • userNotes

  • active

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:

Table 41. operation allowed for a deployment element
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:

Table 42. Deployment element object
attribute Description

id

name (required)

[a-zA-Z0-9-_., ] max 50 chars

version (required)

[a-zA-Z0-9-_.] max 50 chars

type (required)

string with valid values:

  • SOFTWARE

  • FIRMWARE

  • CONFIGURATION

  • PARAMETERS

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:

  • Mandatory

  • Optional

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.

If the value is not filled the platform introduce the configured URL of the OpenGate internal file repository,

fileName

string (Optional). Must the name of the file to be uploaded.

If present the value is used by the platform to know the name of source file to . If the value is not filled the platform will obtain the filename from the HTTP request using the attribute Content-Disposition: form-data; name="file"; filename="filename.ext" in the HTTP Header.

Table 43. Deployment element. Validators object array
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:

  • MD2

  • MD5

  • SHA-1

  • SHA-256

  • SHA-384

  • SHA-512

  • CERTIFICATE_SIGN (Support for ECDSA-256, RSA-1024, RSA-2048, …​ algorithms)

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:

  • PLATFORM, this value is used if you want that the platform execute this validation

  • TRUSTED_BOOT, in this case you are indicating that is required a validation type trusted_boot, it’s not necessary introduce the field value

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

Example 6. DeploymentElement.json Install example
{
    "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"
    }
}
Example 7. DeploymentElement.json Uninstall example
{
    "deploymentElement": {
        "name": "bundle_1-file_1",
        "version": "1-SNAPSHOT",
        "type": "SOFTWARE",
        "path": "./",
        "order": "2",
        "operation": "UNINSTALL",
        "option": "MANDATORY"
    }
}
Example 8. DeploymentElement.json Upgrade example
{
    "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:

Example 9. Read bundle deployment element list as JSON document
{
    "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:

Example 10. Read deployment element meta-information as JSON document
{
    "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

Table 44. Certificate Request object attributes used in POST and PUT options
Attribute Description

id(optional)

string

name(optional)

string

description (optional)

string

administrativeState

Valid values:

  • NOT_ACTIVE

  • ACTIVE

  • REVOKED

usages[]

Array of strings. Valid values:

  • FILE_VALIDATION

  • DEVICE_COMMUNICATIONS

  • DEVICE_ACCESS

  • CERT_SIGN

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

Table 45. Certificate Hardware object attributes
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

Table 46. Certificate object attributes for GET option
Attribute Description

id

string

name

string

description

string

administrativeState

String. Valid values:

  • NOT_ACTIVE

  • ACTIVE

  • REVOKED

  • EXPIRED

usages

Array of Strings. Valid values:

  • FILE_VALIDATION

  • DEVICE_COMMUNICATIONS

  • DEVICE_ACCESS

  • CERT_SIGN

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

Only used in search operations with parameter fetch set to 1

valid

subject

string, it defines the certificate, formed by the next parts, where at least one of them must be filled

  • CN, commons name

  • OU, Organization Unit

  • O, Organization name

  • L, Locality name

  • ST, State name

  • C, Country

  • E, Email

issuer

string, it defines the parent certificate, formed by the next parts, where at least one of them must be filled

  • CN, commons name

  • OU, Organization Unit

  • O, Organization name

  • L, Locality name

  • ST, State name

  • C, Country

  • E, Email

publicKey

domains(optional)

Array of strings

Table 47. Certificate Valid Field object attributes
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

Table 48. Certificate Public Key Field object attributes
Attribute Description

algorithm

string

size

number

format

string

Supported File Types

Table 49. Certificates 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 parameter single path example
"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 parameter multiple path example
"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 provision request in JSON format
{
   "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:

Reading certificate in JSON format
{
   "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 modified provision request in JSON format
{
   "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

Table 50. channel objects and attributes
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 as JSON object
{
  "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:

Read a Channel as JSON document
{
  "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

Update a channel as JSON object
{
  "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:

  • It is not possible remove them

  • Categories can not be add or remove

  • Datastream of category can not be add or remove

  • It is not possible change the following fields:

    • datamodel.name

    • datamodel.version

    • datamodel.category.datastream.name

    • datamodel.category.datastream.period

    • datamodel.category.datastream.schema

    • datamodel.category.datastream.access

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

Adding a new Datamodel

POST /v80/provision/organizations/{organization_id}/datamodels

Datamodel provision in JSON format
{
  "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

Datamodel provision with dual datastreams in JSON format
{
  "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:

Reading Datamodel in JSON format
{
  "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

Reading a datamodel in JSON format 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:

  • All new datastreams are added to the existing datamodel

  • For all already provisioned datastreams, that are in the JSON in the request, all fields can be modified except the identifier

  • All datastreams already provisioned, that are not present in the JSON’s request, are removed only if they have not datapoint instances previously collected. An error is returned for the entire request if there is at least one datastream with datapoints previously collected and not present in the put option.

Datamodel modified provision in JSON format
{
  "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

Table 51. Device provision attributes
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:

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

Minimum Device JSON document for creating a device
{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "battery_channel"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "emptyServiceGroup"
        }
      }
    },
    "device": {
      "identifier": {
        "_current": {
          "value": "device_battery_id"
        }
      }
    }
  }
}
Recomendable Device JSON document for creating a device without subscribers or subscriptions
{
  "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

Recomendable Device JSON document for creating a device with subscribers or subscriptions that 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

Recomendable Device JSON document for creating a device without subscribers or subscriptions
{
  "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

Recomendable Device JSON document with flattened format for creating a device with subscribers or subscriptions that does 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

Create a device with a related asset

Here’s how to create a device with a related asset

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:

Updating a device as JSON document with subscribers or subscriptions
{
  "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:

Associate a subscription or subscriber to the device
{
  "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

Desassociate a subscription or subscriber of the device
{
  "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:

Updating a device with flattened format as JSON document with subscribers or subscriptions
{
  "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:

Associate a subscription or subscriber to the device 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"
        ]
      }
    }
  },
  "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

Desassociate a subscription or subscriber of the device
{
  "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:

Patching a device as JSON document with subscribers or subscriptions
{
  "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:

Associate a subscription or subscriber to the device
{
  "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:

Patching a device with flattened format as JSON document with subscribers or subscriptions
{
  "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:

Associate a subscription or subscriber to the device with flattened format
{
  "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

Table 52. domain objects and attributes
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 as JSON object
{
  "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:

Read a Domain as JSON document (without parameter hierarchy or hierarchy=false)
{
  "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
Read a Domain as JSON document (with parameter hierarchy or 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

Update a Domain as JSON object
{
    "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

Table 53. Manufacturer object and attributes
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 as JSON document, ready for creation
{
  "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:

Read manufacturer as JSON document
{
  "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:

Table 54. Manufacturer media object
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:

  • image/png

  • image/x-icon

  • image/jpeg

  • image/svg+xml

  • image/tiff

  • image/webp

  • application/pdf

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

Example 11. media.png 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:

Example 12. Read media files element list as JSON document
{
    "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.

Table 55. Model object and attributes
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

Table 56. Associated Manufacturer object and attributes
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 as JSON document, ready for creation
{
  "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:

Read Model as JSON document
{
  "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:

Table 57. Model media object
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:

  • image/png

  • image/x-icon

  • image/jpeg

  • image/svg+xml

  • image/tiff

  • image/webp

  • application/pdf

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

Example 13. media.png 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:

Example 14. Read media files element list as JSON document
{
    "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

Table 58. Organization Object
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.

Table 59. Map Default Object
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

Table 60. 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 as JSON object
{
  "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:

  • A domain

  • A workgroup

  • A channel

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:

Read an Organization as JSON document
{
  "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:

Updating an Organization as JSON document
{
  "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

Table 61. Radius Client Object
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

Table 62. Synchronized Cache Object
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.

Example 15. Radius Client as JSON object
{
  "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:

Example 16. Read a Radius Client as JSON document
{
  "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

Table 63. Rule objects and attributes
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*

See Rule type attributes

active

Optional boolean value which define if a rule have to be evaluated or not. False by default.

parameters

See Parameters attributes

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

See Rule actions attributes

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

Table 64. Rule Type objects and attributes
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

Table 65. Rule Parameters objects and attributes
Object / attribute(* required) Description

name*

Name of the param.

value*

Value of the param.

schema*

Type of the param. string/integer/number/boolean as possible types.

description

Optional description for the param

Rule Actions object structure

If rule mode is easy, you must defined at least one action.

Table 66. Rule Actions objects and attributes
Object / attribute(* required) Description

open

See Open Action attributes

close

See Close Action attributes

sendTrap

See Send Trap Action attributes

sendEmail

See Send Email Action attributes

sendHttp

See Send Http Action attributes

operation

See Operation Action attributes

cancelDelay

See Cancel Delay Action attributes

Rule Open Action object structure

Table 67. Rule Open Action objects and attributes
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

Table 68. Rule Close Action objects and attributes
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

Table 69. Rule Send Trap Action objects and attributes
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

Table 70. Rule Send Email Action objects and attributes
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

Table 71. Rule Send Http Action objects and attributes
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

Table 72. Rule Operation Action objects and attributes
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

Table 73. Rule Cancel Delay Action objects and attributes
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.

Rule in easy mode of datastream type and open action as JSON object
{
  "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"
      }
    ]
  }
}
Rule in easy mode of operation type and some actions as JSON object
{
  "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"
          }
        ]
      }
    ]
  }
}
Rule in easy mode of event type as JSON object
{
  "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:

Response of rule
{
  "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.

Rule in easy mode of datastream type and open action as JSON object
[
    {
      "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

Table 74. Subscribers provision attributes
Object / attribute Description

administration

See Default Datamodels

device

See Default Datamodels

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

Minimum subscriber JSON document for creating a subscriber
{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "battery_channel"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "emptyServiceGroup"
        }
      }
    },
    "device": {
      "communicationModules": [
        {
          "subscriber": {
            "identifier": {
              "_current": {
                "value": "subscriber_battery_id"
              }
            }
          }
        }
      ]
    }
  }
}
Recomendable subscriber JSON document for creating a subscriber
{
  "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

Creating a subscriber with flattened 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:

Read subscriber as JSON document
{
  "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:

Updating a Subscriber as JSON document
{
  "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:

Updating a subscriber as JSON document
{
  "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:

Patching a subscriber as JSON document
{
  "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:

Patching a subscriber as JSON flattened document
{
  "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

Table 75. Subscriptions provision attributes
Object / attribute Description

administration

See Default Datamodels

device

See Default Datamodels

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

Minimum subscription JSON document for creating a subscription
{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "battery_channel"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "emptyServiceGroup"
        }
      }
    },
    "device": {
      "communicationModules": [
        {
          "subscription": {
            "identifier": {
              "_current": {
                "value": "subscription_battery_id"
              }
            }
          }
        }
      ]
    }
  }
}
Recomendable subscription JSON document for creating a subscription
{
  "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

Creating a subscription with flattened 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:

Read subscription as JSON document
{
  "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:

Updating a subscription as JSON document
{
  "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:

Updating a subscription as JSON document
{
  "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:

Patching a subscription as JSON document
{
  "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:

Patching a subscription as JSON flattened document
{
  "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.

Table 76. Tag Object
attribute (* required) Description

name

string with the name you want as a label for your entities.

owner

Select one of these choices:

  • "user": The tag will be owned only by the user

  • "workgroup": The tag will be available for management by all users in the same workgroup

target

See Tag Target Object

Table 77. Tag Target Object
attribute (* required) Description

append

See Append/Remove target object

remove

See Append/Remove target object

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.

Table 78. Append/Remove Target Object
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

Table 79. 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

Table 80. Tag Operation Response Object
attribute (* required) Description

name

string with the name you want as a label for your entities.

result

see result object below

Table 81. Tag Operation Response Result Object
attribute (* required) Description

count

number of processed entities

successful

number of entities that have been processed with success

error

see error object below

Table 82. Tag Operation Respo4nse Result Error Object
attribute (* required) Description

notExist

see error summary below

Table 83. Tag Operation Response Result Error Summary Object with error in entities
attribute (* required) Description

count

number of occurrences of this error

list

string array of the entity identifiers that have produced the error

Table 84. Tag Operation Response Result Error Summary Object with error in cloned tags
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):

  • GATEWAY, if you want to take into account only gateways

  • ASSET, if you want to take into account only assets

  • COMMUNICATIONS_MODULE, if you want to take into account only communication modules

  • SUBSCRIPTION, if you want to take into account only subscriptions

  • SUBSCRIBER, if you want to take into account only subscriber

  • 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

Example 17. Tag object as JSON document, ready for creation owned by the user
{
   "tag" : {
        "name" : "tag_1",
        "owner" : "user",
        "target": {
            "append" : {
                "entities" : [ "device_1", "device_2" ]
            }
        }
    }
}
Example 18. Tag object as JSON document, ready for creation owned by the workgroup
{
   "tag" : {
        "name" : "tag_1",
        "owner" : "workgroup",
        "target": {
            "append" : {
                "entities" : [ "device_1", "device_2" ]
            }
        }
    }
}
Example 19. Tag object as JSON document created using a filter
{
   "tag" : {
        "name" : "tag_1",
        "owner" : "user",
        "target" : {
            "filter": {
                "and": [
                    {
                        "like": {
                            "collected.entityName": "device_name"
                        }
                    },
                    {
                        "or": [
                            {
                                "like": {
                                    "collected.serialNumber": "82A75D494B0EBF7A95587285AE78E83F"
                                }
                            },
                            {
                                "like": {
                                    "collected.serialNumber": "08D83B1864A1F9CFED76DAF426EB04D7"
                                }
                            }
                        ]
                    }
                ]
            }
        }
    }
}
Example 20. Tag object as JSON document created using existing tags
{
    "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
Example 21. Tag operation response as JSON document
{
   "tag" : {
        "name" : "tag_1",
        "result": {
            "count": 3,
            "successful": 1,
            "error": {
                "notExist" : {
                    "count": 2,
                    "list": [ "device_1", "device_2" ]
                }
            }
        }
    }
}
Example 22. Tag operation response as JSON document including not existing tags
{
    "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:

Example 23. Read tag object as JSON document
{
   "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"

Table 85. Tag entities list Object
Attributes Constraints Description

page

See Page Object

Paging fields

entities[]

array of string

List of entities in the tag

Example 24. Entities in a 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"
Example 25. Tag object as JSON document, ready for updating
{
   "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:

Table 86. ticket objects and attributes
Object / attribute Type Mandatory Description

identifier

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

arrayString

No

Labels possibles to assign to ticket

reporter

identifier

Yes

Entity that reports a ticket

owner

string

No

Platform user that create the ticket. It is assigned by the platform

assignee

identifier

No

Entity that is assigned a ticket

section

string

No

Component on which the installation or work order is being made

entity

identifier

No

Entity that is associated a ticket

type

see possible values

Yes

Type of the ticket

severity

see possible values

Yes

Severity of the ticket

priority

see possible values

Yes

Priority of the ticket

status

see possible values

Yes

Actual status of the ticket

specificType

see possible values

No

Concrete type of the ticket

reporterDate

timestamp

Yes

Date a ticket is reported

creationDate

timestamp

No

Date a ticket is created. It is generated by the platform with the system date when is created

assignedDate

timestamp

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

timestamp

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

timestamp

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

timestamp

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

timestamp

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

timestamp

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

Minimum ticket JSON document for creating a ticket
{
  "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"
        }
      }
    }
  }
}
Recommended ticket JSON document for creating a ticket
{
  "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:

  • owner

  • creationDate

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

Minimum ticket JSON document for creating a ticket
{
  "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:

Read a Ticket as JSON document
{
  "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:

  • identifier

  • type

  • reporter

  • entity: If the ticket doesn’t contain the entity then it can be updated

The dates will be updated internally by the platform depending on the status of the ticket and they can’t be modifiable:

  • creationDate

  • assignedDate

  • answeredDate

  • updatedDate

  • restorationDate

  • resolutionDate

  • closedDate

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

Patching a ticket as a JSON document
{
  "provision": {
    "ticket": {
      "description": {
        "_current": {
          "value": "ticket1 description patched"
        }
      }
    }
  }
}

The following fields can’t be modifiable:

  • identifier

  • type

  • reporter

  • entity: If the ticket doesn’t contain an entity, then it can be patched

The dates will be patched internally by the platform if the status of the ticket has been patched, and they can’t be modifiable:

  • creationDate

  • assignedDate

  • answeredDate

  • updatedDate

  • restorationDate

  • resolutionDate

  • closedDate

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

Table 87. user objects and attributes
Object / attribute Description

email

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 as JSON object
{
  "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:

Read a User with apiKey (X-ApiKey) in the header
{
  "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:

Read a User with password (X-ApiPass) in the header
{
  "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:

Update basic user data as JSON document
{
  "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:

Change the user password as JSON document
{
   "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

Table 88. Workgroup Objects
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.

Example 26. workgroup as JSON object
{
  "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:

Example 27. Read a Workgroup as JSON document
{
  "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:

Table 89. Workgroup relations element object and attributes
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.

Example 28. Workgroup relations element example
{
  "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:

Example 29. Read Workgroup relations element list as JSON document
{
  "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"
Example 30. Deleting Workgroup relations element list as JSON document
{
  "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.

Table 90. Inventory of Entities
Entity Type Search Service

Assets

See Assets Search

Devices

See Devices Search

Subscriptions

See Subscriptions Search

Subscribers

See Subscribers Search

Table 91. Operations on Entities
Querying over URI

Operations

See Operations Search

Table 92. Jobs Resources
Querying over URI

Jobs

See Jobs Search

Table 93. Alarms raised on Entities
Querying over URI

Alarms

See Alarms Search

Table 94. Hardware Resources
Querying over URI

Hardware

See Manufacturer & Models Search

Table 95. Software Resources
Querying over URI

Software

See Software Search

Table 96. Operation Types
Querying over URI

Operation Types

See Operation Types Search

Table 97. Operators Catalog
Querying over URI

Operation Types

See Operators Catalog Search

Table 98. Bundles Resources
Querying over URI

Bundles

See Bundles Search

Table 99. Device Datamodels Resources
Querying over URI

Datamodels

See Datamodels Search

Table 100. Certificates Resources
Querying over URI

Certificates

See Certificates Search

Table 101. Plans Resources
Querying over URI

Plan

See Plans Search

Table 102. Internet of Thing Resources
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

Example 31. Request example
{
    "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:

Example 32. Json for searching request: search-query.json
{
    "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

Table 103. Pagine JSON object
Parameter Description

limit

See Limit Object

Table 104. Paging parameters in the Request: "limit" JSON 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

Table 105. Paging parameters in the Response: "page" JSON object
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

Paginated example response
{
    "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.

Pagination example request
{
     "limit" : {
        "start" : 2
     }
}

And then you’ll receive:

Paginated example generic response
{
   "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.

Paginated example request. Changing the starting page and the limit
{
   "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:

Paginated example response. With the starting page and the limit changed
{
    "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

Table 106. Filter JSON object
Parameter Description

filter

See Operator Object

Filtering operators

The following list shows the filtering operators supported by the search API.

Table 107. Comparison operators supported by 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

Exists

within

Included in an areas.geometry GeoJson (exclusive for Area search)

Table 108. Logical operators supported by search API
Operation Description

and[]

And

or[]

Or

Table 109. Supported identifiers for exists filter
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

Filtering devices
{
  "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

Example 33. Searching basic operators
{
    "filter": {
        "and": [
            {
               "like": {
                   ...
               }
            },
            {
               "neq": {
                   ...
               }
            }
        ]
    },
    "limit": {
        "start": 26,
        "size": 50
    }
}
Searching using fields from other entities

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"
        }
    }
}
Example 34. Searching using "in" and "nin" operators like aggregation of id’s
{
    "filter": {
        "and": [
            {
                "in": {
                    "device.name": [
                        "device_1",
                        "device_2"
                    ]
                }
            },
            {
                "nin": {
                    "device.description": [
                        "device default description"
                    ]
                }
            }
        ]
    },
    "limit": {
        "start": 26,
        "size": 50
    }
}
Example 35. Searching using a tag
{
    "filter": {
       "eq": {
            "tag": "my_sticky_tag"
        }
    },
    "limit": {
        "start": 26,
        "size": 50
     }
}
Example 36. Searching for collected hardware fields
{
    "filter": {
        "and": [
           {
              "like": {
                  "device.model": "EF5"
              }
           },
           {
              "exists": {
                  "device.identifier": true
              }
           }
        ]
    },
    "limit": {
        "start": 1,
        "size": 10
    }
}
Example 37. Searching for software field (device whose software has this regex chain)
{
    "filter": {
        "and": [
            {
                "like": {
                    "device.software": "1.0"
                }
            }
        ]
    },
    "limit": {
        "start": 1,
        "size": 10
    }
}
Example 38. Searching for catalogued operations: Retrieve all catalogued operations applicable to the Subscription & Asset entities
{
   "filter":{
      "and":[
         {
            "in":{
               "operationEntityType":[
                  "SUBSCRIPTION",
                  "ASSET"
               ]
            }
         }
      ]
   },
   "limit":{
      "start":1,
      "size":10
   }
}
Example 39. Searching for device alarms, /north/v80/search/entities/devices/alarms
{
    "filter": {
        "in": {
            "device.name": [
                "DEVICE22"
            ]
        }
    },
   "limit":{
      "start":1,
      "size":10
   }
}
Example 40. Searching for a particular data of a complex value
{
  "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.

Table 110. SQL to JSON queries mapping chart
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:

Table 111. Sort JSON object
Parameter Description

parameters[]

Array of ordering parameters

the name of the parameters is the same that filter name parameters. See Available fields section

Table 112. Parameter JSON object
Parameter Description

name

Name of parameter defined in the Default Datamodels

type

Enumeration string with ordering type. Valid values are:

  • ASCENDING

  • DESCENDING

Sort examples

An example for ordering into a request could be:

Example 41. Sorted Search Request example
{
    "filter": {
        ...
    },
    "limit": {
        ...
    },
    "sort": {
        "parameters": [
            {
               "name" : "provision.administration.identifier",
               "type" : "ASCENDING"
            }
        ]
    }
}

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:

  • page: It indicates the csv page you want.

  • size: It indicates the number of register you want in the csv

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

Table 113. Search Select Object
Entity Description

select[]

Array of parameters to be selected. See Select Parameter Object

Table 114. Search Select 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

Filter using device predefined fields
{
  "select": [
    {
      "name": "provision.device.identifier",
      "fields": [
        {
          "field": "value",
          "alias": "id"
        },
        {
          "field": "date",
          "alias": "date"
        }
      ]
    }
  ]
}
Filter obtaining a field of a complex value
{
  "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

Response to the Filter in JSON format example
{
    "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
                        }
                    }
                }
            }
        }
    ]
}
Response to the Filter in CSV format example
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

Table 115. Summary common structure
Entity Constraint

count (field)

number of occurrences found in the whole search

summaryGroup []

Array of type of Summarized Specific Object Structure

Table 116. Summarized Specific Object structure
Entity Constraint

SpecificObjectParameterDatamodel

Object inside the Parameter of the Default Datamodels. See Summarized Element Structure

Table 117. Summarized Element structure
Entity Constraint

count

number of these specific elements found

list

Array of each type of Summarized Element List

Table 118. Summarized Element structure 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

Response summary without grouping
{
  "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

Example Filter using group clause
{
  "filter": {
    "and": [
      {
        "like": {
          "provision.administration.organization": "battery_organization"
        }
      }
    ]
  },
  "group": {
    "parameters": [
      {
        "name": "provision.device.model"
      }
    ]
  }
}

The response would be something like this

Response summary with group clause
{
  "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:

Table 119. Group JSON object
Parameter Description

parameters[]

Array of grouping parameters, see group parameter object

Table 120. Group Parameter JSON object
Parameter Description

name

Name of the parameter in the Default Datamodels

The summarizables parameters list are:

  • Every enum values

  • device.model

  • device.software

  • device.communicationModules[].model

  • device.communicationModules[].software

  • device.communicationModules[].subscriber.model

  • device.communicationModules[].subscriber.software

  • device.communicationModules[].subscription.mobile.homePlmn

  • device.communicationModules[].subscription.mobile.homeOperator

  • device.communicationModules[].subscription.mobile.vlr.plmn

  • device.communicationModules[].subscription.mobile.vlr.operatorName

  • device.communicationModules[].subscription.mobile.vlr.countryName

  • device.communicationModules[].subscription.mobile.vlr.countryCode

  • device.communicationModules[].subscription.mobile.msc.plmn

  • device.communicationModules[].subscription.mobile.msc.operatorName

  • device.communicationModules[].subscription.mobile.msc.countryName

  • device.communicationModules[].subscription.mobile.msc.countryCode

  • device.communicationModules[].subscription.mobile.sgsn.plmn

  • device.communicationModules[].subscription.mobile.sgsn.operatorName

  • device.communicationModules[].subscription.mobile.sgsn.countryName

  • device.communicationModules[].subscription.mobile.sgsn.countryCode

  • device.communicationModules[].subscription.mobile.ggsn.plmn

  • device.communicationModules[].subscription.mobile.ggsn.operatorName

  • device.communicationModules[].subscription.mobile.ggsn.countryName

  • device.communicationModules[].subscription.mobile.ggsn.countryCode

  • device.communicationModules[].subscription.mobile.registeredPlmn

  • device.communicationModules[].subscription.mobile.registeredOperator

  • provision.device.model

  • provision.device.software

  • provision.device.communicationModules[].model

  • provision.device.communicationModules[].software

  • provision.device.communicationModules[].subscriber.model

  • provision.device.communicationModules[].subscriber.software

  • provision.device.communicationModules[].subscription.mobile.homeOperator

  • provision.device.communicationModules[].subscription.mobile.registeredOperator

  • provision.administration.channel

  • provision.administration.organization

  • provision.administration.serviceGroup

  • provision.administration.plan

Group examples

An example for grouping into a request could be:

Group Search Request example
{
  "filter": {
    "and": [
      {
        "like": {
          "provision.administration.organization": "battery_organization"
        }
      }
    ]
  },
  "group": {
    "parameters": [
      {
        "name": "provision.device.model"
      }
    ]
  }
}

The response would be something like this

Response with group clause
{
  "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:

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

URL parameters

There are not specific parameters applicable to this URLs

Alarms summary information

Table 121. Summary common structure
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

Table 122. Summary group: Summarized Elements
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

See Summarized Specific Object Operations Structure

Table 123. Summarized Specific Object Operations Structure
Entity Constraint

count

number of occurrences found of this specific element

list

Array of each type of Summarized Element Structure

Table 124. 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

Table 125. Filter fields for searching raised alarms
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

Table 126. Entities with alarms. Response structure
Entity Constraint

page

See page object

summary

See summary object in this section

alarms[]

See Alarm Object bellow

Table 127. Alarm Object
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:

  • INFORMATIVE: The event is only informative

  • URGENT: The event is urgent to be attended

  • CRITICAL: The event indicates a critical issue for the service operation

Severity of the raised alarm

status

String enumeration with the next values:

  • OPEN: The alarm is active

  • ATTENDED: The alarm is being attended by an operator

  • CLOSED: The event is closed

Status of the raised alarm

priority

String enumeration with the next values:

  • LOW

  • MEDIUM

  • HIGH

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:

Retrieving all device alarms with json format without summary
{
  "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:

Example 42. Searching summary of device alarms
{
  "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
Retrieving all device alarms with csv format
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"
         ]
      }
   }
}'
Retrieving all entities with alarms
{
  "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"]
      }
   }
}'
Retrieving all subscriptions with alarms
{
  "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.

URL

Type of Information URL

Areas provisioned in the platform

/north/v80/search/areas

Applicable Filter Fields

Table 128. Filter fields for searching Catalogued domains
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

Area geometry filter

If you can search by geometry exists the within option to indicate every areas that contains this coordenate.

Example geometry filter
{
  "filter": {
    "within": {
      "areas.geometry": [
        2.173200845718384,
        41.36735636905808
      ]
    }
  }
}

Areas Object

An example of response could be something like this

Response example as JSON object
[
  {
    "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:

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

It is used the generic entities URLs.

Here, you can see some Searching assets examples

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.

Example Filter using asset predefined fields
{
  "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 to obtain all assets
{
  "filter": {
    "and": [
      {
        "like": {
          "resourceType": "entity.asset"
        }
      }
    ]
  }
}

And this is the response body:

Retrieving all assets with json format
{
    "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 to obtain all assets with select clause
{
  "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"
        }
      ]
    }
  ]
}
Retrieving all assets with the above filter in csv format
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 to obtain a determinated asset with related devices
{
  "filter": {
    "and": [
      {
        "like": {
          "resourceType": "entity.asset"
        }
      },
      {
        "like": {
          "provision.asset.identifier": "worker_battery_id"
        }
      }
    ]
  }
}

And this is the response body:

Retrieving a determinated asset with related devices
{
  "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 to obtain the asset with a determinated related device
{
  "filter": {
    "and": [
      {
        "like": {
          "resourceType": "entity.asset"
        }
      },
      {
        "like": {
          "provision.asset.related": "device_battery_id"
        }
      }
    ]
  }
}

And this is the response body:

Retrieving an asset with determinated related device
{
  "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 to obtain all assets
{
  "filter": {
    "and": [
      {
        "like": {
          "resourceType": "entity.asset"
        }
      }
    ]
  }
}

And this is the response body:

Retrieving all assets as flattened format
{
    "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 to obtain all assets
{
  "filter": {
    "and": [
      {
        "like": {
          "resourceType": "entity.asset"
        }
      }
    ]
  }
}

The response body could be something like this:

Retrieving the summary
{
  "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.

URL

Type of Information URL

Available bundles in the platform

/north/v80/search/bundles

URL parameters

There are not specific parameters applicable to this URLs

Applicable Filter Fields

Table 129. Filter fields for searching created bundles
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

Table 130. Summary common structure
Entity Constraint

count (field)

number of occurrences found in the whole search

Response structure

The JSON response has the same format

Table 131. Bundle. Response structure
Entity Constraint

bundles[]

see Bundle structure below

Table 132. Bundle structure
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

See deploymentElement object structure

Table 133. deploymentElement object structure
Attributes Description

id

Deployment element identifier.

name

Name of the deployment element

version

Version of the deployment element

type

type of the deployment element

  • SOFTWARE

  • FIRMWARE

  • CONFIGURATION

  • PARAMETERS

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

  • INSTALL

  • UNINSTALL

  • UPGRADE

option

Valid values

  • MANDATORY

  • OPTIONAL

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.

Example 43. Searching bundles: Response example without summary - /north/v80/search/bundles
{
    "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:

Search Certificate Example: fetch=0
{
    "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)

Search Certificate Example: fetch=1
{
    "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

Table 134. Filter Fields for searching Certificates
Parameter Description

certificate.id

String

certificate.usage

String

certificate.tag

String

certificate.manufacturer

String

certificate.model

String

certificate.model.version

String

certificate.name

String

certificate.description

String

certificate.administrativeState

String

certificate.version

String

certificate.trustChain (*See usage examples)

String

certificate.subject

String

certificate.issuer

String

certificate.serialNumber

Number

certificate.valid.from

String

certificate.valid.until

String

certificate.publicKey.algorithm

String

certificate.publicKey.format

String

certificate.publicKey.size

String

certificate.domain

String

Filtering by trustChain field

See how the trustChain works section if you like to learn about this field usage.

Some Examples:

Search all certificates whose trustChain contains [ "1427353136" ]
{
    "filter": {
        "and": [
            {
                "like": {
                    "certificate.trustChain": "1427353136"
                }
            }
        ]
    }
}
Search all certificates whose trustChain contains exactly the sub-chain [ 1427353136, 1427353426 ] (using , as separator)
{
    "filter": {
        "and": [
            {
                "like": {
                    "certificate.trustChain": "1427353136,1427353426"
                }
            }
        ]
    }
}
Search all certificates whose trustChain contains both of the certificates [ "1427353136", "1427353426" ] in the order specified (using % as separator)
{
    "filter": {
        "and": [
            {
                "like": {
                    "certificate.trustChain": "1427353136%1427353426"
                }
            }
        ]
    }
}
Search all certificates whose trustChain contains any of the certificates [ "1427353136", "1427353426" ] in any order
{
    "filter": {
        "or": [
            {
                "like": {
                    "certificate.trustChain": "1427353136"
                }
            },
            {
                "like": {
                    "certificate.trustChain": "1427353426"
                }
            }
        ]
    }
}

Summary Information

Table 135. Summary common structure
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

Table 136. Certificate Response structure
Entity Constraint

certificate[]

Array of certificate. See Certificate object structure section

Searching certificate: Response example - /north/v80/search/certificates
{

...

    "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

Table 137. Filter fields for searching Catalogued channel
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

Table 138. Summary common structure
Entity Constraint

count (field)

number of occurrences found in the whole search

Channel Object

Examples

An example of response could be something like this

Example 44. Operation Info as JSON (/north/v80/search/channels without summary parameter)
{
    "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"]
        }
    ]
}
Example 45. Operation Info as JSON (/north/v80/search/channels?summary=true)
{
    "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"]
        }
    ]
}
Example 46. Operation Info as JSON (/north/v80/search/channels/summary)
{
    "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

Table 139. Datamodel response objects
Attribute Description

page

See page

datamodels[]

Contains the array of datamodels to be appended or deleted, see Datamodel description

URL

Table 140. URLs
Querying over URI

Datamodel Info

POST - /north/v80/search/datamodels

URL parameters

There are not specific parameters applicable to these URLs

Specific Filter Fields

Table 141. Filter Fields for searching Datamodels

Parameter

Type

Description

datamodels.identifier

String

Identifier of the datamodel

datamodels.name

String

Name of the datamodel

datamodels.version

String

Version of the datamodel

datamodels.description

String

Description of the datamodel

datamodels.organizationName

String

Organization of the datamodel

datamodels.allowedResourceTypes[]

Array of String

Array of resourceType allowed, see entities

datamodels.categories.identifier

String

Category identifier of the datamodel

datamodels.categories.name

String

Category name of the datamodel

datamodels.categories.datastreams.identifier

String

Identifier of the datastream

datamodels.categories.datastreams.name

String

Name of the datastream

datamodels.categories.datastreams.description

String

Description of the datastream

datamodels.categories.datastreams.period

String enumeration

One of: PULSE, CUMULATIVE, INSTANT (This is the default value)

datamodels.categories.datastreams.access

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

datamodels.categories.datastreams.storage.period

String

Specify the units of time that OpenGate have to consider for deleting historical datapoints, the available values are:

* DAYS

* MONTHS

* YEARS

* NEVER, if you select this value, no one datapoint will be storaged, the information of the last one could be got in datastream’s search

datamodels.categories.datastreams.storage.total

Number

Amount of period units for considering in the deleting process

datamodels.categories.datastreams.tags

String

See tags

datamodels.categories.datastreams.unit.label

String

The label you want for your unit, see unit object attributes

datamodels.categories.datastreams.unit.symbol

String

The symbol you want for your unit, see unit object attributes

datamodels.categories.datastreams.unit.type

String

The type you want for your unit, see unit object attributes

datamodels.categories.datastreams.icon

String

Used for asociate an icon in the web datastream visualitation, See IoT Datastream Icon Object

datamodels.categories.datastreams.modifiable

Boolean

It indicates if it is modifiable this datastream

datamodels.categories.datastreams.required

Boolean

it indicates if it is required for this datastream

datamodels.categories.datastreams.qrating.min_required.value

Number

Minimum required value

datamodels.categories.datastreams.qrating.min_required.label

String

Minimum required label

datamodels.categories.datastreams.qrating.min_desired.value

Number

Minimum desired value

datamodels.categories.datastreams.qrating.min_desired.label

String

Minimum desired label

datamodels.categories.datastreams.qrating.ideal.value

Number

Ideal value

datamodels.categories.datastreams.qrating.ideal.label

String

Ideal label

datamodels.categories.datastreams.qrating.max_desired.value

Number

Maximum desired value

datamodels.categories.datastreams.qrating.max_desired.label

String

Maximum desired label

datamodels.categories.datastreams.qrating.max_allowed.value

Number

Maximum allowed value

datamodels.categories.datastreams.qrating.max_allowed.label

String

Maximum allowed value

datamodels.categories.datastreams.qrating.version

String

Version of Qrating

datamodels.categories.datastreams.qrating.max_score

Number

Maximum score

datamodels.categories.datastreams.qrating.cumulative_period_divisor

Number

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 \ character used to split the URI for readability.

Example 47. Request JSON
Filter to select a specific datastream
{
    "filter": {
        "like": {
            "datamodels.identifier": "teliot"
        }
    }
}
Response JSON
{
  "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

Table 142. URLs
Querying over URI

Datapoints Info

POST - /north/v80/search/datapoints

URL parameters

There are not specific parameters applicable to this URL

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.

The response returns all the values in the solicited "filter" in the request. Not pagination is allowed so the "limit" and "select" object is not supported when CSV format is required

An internal maximum limit is established by default in a Million of result rows. Please consult to the administrator of the platform to know the specific limit defined in your platform.

Request for json format (default if not Accept header is included)
POST /contacts HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

...
Request for csv format
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:

Table 143. Datapoint response objects
Attribute Description

page

See Page Object

datapoints[]

Array of datapoint objects. See Datapoint object definition

Table 144. Datapoint object attributes
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

Table 145. current datapoint object attributes
Attribute Description

value

It is a polyvalent field that supports JSON data types:

"value" : 10
  • String delimited with double-quotation marks. Example:

"value" : "string value"
  • Boolean either of the values true or false. Example:

"value" : true
  • Array of JSON data types. Example:

"value" : [ "text1", "text2" ]
  • Object with JSON format. Example:

"value" : {
    "field1": "text",
    "field2": 12
}
  • Null. Example:

"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

This field is necessary if you are using datastream period = pulse, if this field is not incorporated the default value is the same than the value of the field "at". If the value of the field from is greater than the value of the field at, the value of the field from will be changed by the value of the field at, and both of them will have the same value.

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

Table 146. Scoring Datapoint object attributes
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

Table 147. Datapoint specific filtering parameters
Parameter Type Description

datapoints.organization

String

Identifier of the organization

datapoints.channel

String

Identifier of the channel

datapoints.datastreamId

String

Identifier of datastream, see Defaault Datamodels

datapoints.entityIdentifier

String

Identifier of the entity

datapoints.entityRelated

String

Identifier of the related asset

datapoints.subEntityIdentifier

String

Subidentifier of the entity. It is the identifier of subscriptions or subscribers that are inside the device

datapoints._current.value

Number

Current value

datapoints._current.tags

String

Tag of the datastream

datapoints._current.date

String

Date of storage in the platform of the data collected

datapoints._current.feedId

String

Identifier of the feed

datapoints._current.at

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.

datapoints._current.from

String

This field indicates the date of the start period of measurement

datapoints._current.scoring.qrating.min_required.value

Number

Minimum required value of any device’s datastreams

datapoints._current.scoring.qrating.min_required.label

String

Minimum required label

datapoints._current.scoring.qrating.min_desired.value

Number

Minimum desired value of any device’s datastreams

datapoints._current.scoring.qrating.min_desired.label

String

Minimum desired label

datapoints._current.scoring.qrating.ideal.value

Number

Ideal value of any device’s datastreams.

datapoints._current.scoring.qrating.ideal.label

String

Ideal label

datapoints._current.scoring.qrating.max_desired.value

Number

Maximum desired value of any device’s datastreams

datapoints._current.scoring.qrating.max_desired.label

String

Maximum desired label

datapoints._current.scoring.qrating.max_allowed.value

Number

Maximum allowed value of any device’s datastreams

datapoints._current.scoring.qrating.max_allowed.label

String

Maximum allowed label

datapoints._current.scoring.qrating.version

String

Version of the Qrating configurated

datapoints._current.scoring.qrating.max_score

Number

Maximum score value of any device’s datastreams

datapoints._current.scoring.qrating.cumulative_period_divisor

Number

Cumulative period divisor (calculation of the median velocity of collection against the previous value collected taking this parameter as divisor)

datapoints._current.scoring.performance

Number

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 to retrieve all datapoints of one device
{
  "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:

Retrieving all datapoints with the above filter and json format
{
  "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:

Retrieving all datapoints with the above filter and csv format
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

Table 148. Datastream response objects
Attribute Description

page

See page

datastreams[]

Contains the array of datastreams, see Datastream description

Table 149. Datastream object attributes
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

Table 150. current object attributes
Attribute Description

value

It is a polyvalent field that supports JSON data types:

"value" : 10
  • String delimited with double-quotation marks. Example:

"value" : "string value"
  • Boolean either of the values true or false. Example:

"value" : true
  • Array of JSON data types. Example:

"value" : [ "text1", "text2" ]
  • Object with JSON format. Example:

"value" : {
    "field1": "text",
    "field2": 12
}
  • Null. Example:

"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

Table 151. URLs
Querying over URI

Datastreams Info

POST - /north/v80/search/datastreams

URL parameters

There are not specific parameters applicable to this URL

Specific Filter Fields

Table 152. Filter Fields for searching Datastreams
Parameter Type Description

datastreams.entityIdentifier

String

Identifier of the entity of any device’s or feed datastream. Example: device_battery_id

datastreams._id.subEntityIdentifier

String

Identifier of the subscription or subscriber that exists inside a device (complete box). Example: subscription_battery_id

datastreams._current.feedId

String

Identifier of the feed of any datastream. Example: feed_1

datastreams.name

String

Name of the datastream of any device’s datastreams. Example: device_battery_name

datastreams.description

String

Description of the datastream. Example: description text to be search

datastreams._current.date

Date

Date of the last update of the datastream.

datastreams.unit.type

String

Type of unit of any device’s datastream. Example: SI

datastreams.unit.label

String

Label of unit. Example: m3

datastreams.unit.symbol

String

Symbol of unit. Example: m3

datastreams.period

String

Period of datastream. Values possible: PULSE, CUMULATIVE, INSTANT

datastreams._current.tags

String

Tag of any device’s datastreams. Example: water

datastreams._current.value

Number

Value of any device’s datastream. Example: 10

datastreams.datamodelId

String

Identifier of the datamodel. Example: Health

datastreams.categoryId

String

Identifier of the category. Example: heart

datastreams.datastreamId

String

Identifier of the datastream. Example: health.heart.rate

datastreams.version

String

Version of the datastream. Example: 1.0.0

datastreams._current.scoring.qrating.min_required.value

Number

Minimum required value of any device’s datastreams. Example: 0

datastreams._current.scoring.qrating.min_required.label

String

Minimum required label. Example: FREE

datastreams._current.scoring.qrating.min_desired.value

Number

Minimum desired value of any device’s datastreams. Example: 0

datastreams._current.scoring.qrating.min_desired.label

String

Minimum desired label. Example: MEDIUM

datastreams._current.scoring.qrating.ideal.value

Number

Ideal value of any device’s datastreams. Example: 5

datastreams._current.scoring.qrating.ideal.label

String

Ideal label. Example: FREE

datastreams._current.scoring.qrating.max_desired.value

Number

Maximum desired value of any device’s datastreams. Example: 70

datastreams._current.scoring.qrating.max_desired.label

String

Maximum desired label. Example: MEDIUM

datastreams._current.scoring.qrating.max_allowed.value

Number

Maximum allowed value of any device’s datastreams. Example: 100

datastreams._current.scoring.qrating.max_allowed.label

String

Maximum allowed label. Example: FULL

datastreams._current.scoring.qrating.version

String

Version of the Qrating configurated

datastreams._current.scoring.qrating.max_score

Number

Maximum score value of any device’s datastreams. Example: 5

datastreams._current.scoring.qrating.cumulative_period_divisor

Number

Cumulative period divisor (calculation of the median velocity of collection against the previous value collected taking this parameter as divisor)

datastreams._current.scoring.scoringPerformance

Number

Performance of any device’s datastreams. Example: 100

datastreams.channel

String

Channel of the datastream

datastreams.organization

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 \ character used to split the URI for readability.

Example 48. Request JSON
Filter to select a specific datastream
{
    "filter": {
        "eq": {
            "datastreams.datastreamId": "batteryPercentage"
        }
    }
}
Response JSON
{
  "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:

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

Table 153. URLs
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

Request for json format (default if not Accept header is included)
POST /contacts HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

...
Request for csv format
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.

Example Filter using device predefined fields
{
  "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:

Retrieving all devices with json format
{
  "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

Filter to obtain all devices with select clause
{
  "select": [
    {
      "name": "provision.device.identifier",
      "fields": [
        {
          "field": "value",
          "alias": "id"
        }
      ]
    },
    {
      "name": "provision.device.location",
      "fields": [
        {
          "field": "value",
          "alias": "location"
        }
      ]
    }
  ]
}
Retrieving all devices with the above filter and csv format
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:

Retrieving all devices with json format with the date in UTC
{
  "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 to obtain all devices with select clause
{
  "filter": {
    "and": [
      {
        "like": {
          "resourceType": "entity.device"
        }
      }
    ]
  },
  "select": [
    {
      "name": "provision.device.identifier",
      "fields": [
        {
          "field": "value"
        }
      ]
    },
    {
      "name": "provision.device.location",
      "fields": [
        {
          "field": "date",
          "alias": "locationDate"
        }
      ]
    }
  ]
}
Retrieving all devices with the above filter in csv format
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:

Retrieving all devices as flattened format
{
  "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:

Retrieving the summary
{
    "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

Table 154. Filter fields for searching Catalogued domains
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

Table 155. Summary common structure
Entity Constraint

count (field)

number of occurrences found in the whole search

Domain Object

The parameter parentDomain is not returned in the response of the search

Examples

An example of response could be something like this

Example 49. Operation Info as JSON (/north/v80/search/domains without summary parameter)
{
    "domains": [
        {
            "name": "Domain_1_1",
            "description": "Domain description"
        },
        {
            "name": "Domain_1_1_2",
            "description": "Domain description"
        }
    ]
}
Example 50. Operation Info as JSON (/north/v80/search/domains?summary=true)
{
    "page":{
        "number":1,
        "of":1
    },
    "summary": {
        "count": 2
    },
    "domains": [
        {
            "name": "Domain_1_1",
            "description": "Domain description"
        },
        {
            "name": "Domain_1_1_2",
            "description": "Domain description"
        }
    ]
}
Example 51. Operation Info as JSON (/north/v80/search/domains/summary)
{
    "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:

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 for retrieving all devices through the generic url
{
  "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

Table 156. URLs
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

Request for json format (default if not Accept header is included)
POST /contacts HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

...
Request for csv format
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:

Retrieving all entities with json format
{
    "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 to obtain all entities with select clause
{
  "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"
        }
      ]
    }
  ]
}
Retrieving all entities with the above filter in csv format
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:

Retrieving all entities as flattened format
{
    "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:

Retrieving the summary
{
  "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

Table 157. Feeds response objects
Attribute Description

page

Page Object As described in above

summary

Number with the count of feeds retrieved

feeds[]

An array of feeds objects. See Feed object definition

Feed object description

Table 158. Feed object attributes
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

URL

Table 159. URLs
Querying over URI

Feeds Info

POST - /north/v80/search/feeds

URL parameters

Specific Filter Fields

Table 160. Feeds specific filtering parameters
Parameter Description

feed.feedId

String. Filter list result by Feed identifier. Example: feed_1

feed.deviceId

String. Filter list result by Device identifier. Example: device_1

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 \ character used to split the URI for readability.

Example 52. Request JSON
Empty filter. Must return all feeds available
{
    "filter": {
    }
}
Filter to select an specific feed
{
    "filter": {
        "eq": {
            "feed.id": "feed_1"
        }
    }
}
Response JSON
{
    "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:

Search datastreams filter: search-query.json
{
    "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"
Response 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

URL parameters

There are not specific parameters applicable to this URLs

Applicable Filter Fields

Table 161. Filter fields for searching Catalogued Hardware, manufacturer and model
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

Table 162. Hardware Catalog Search: Summarized Elements
Entity Constraint

manufacturer

See Summarized Specific Object Operations Structure

model

See Summarized Specific Object Operations Structure

Hardware Structure

For getting the manufacturer and model structure of the platform the JSON response has the next format

Table 163. Hardware Object
Entity Constraint

manufacturer

see object collection bellow

model

see object collection bellow

Table 164. Manufacturer Object
Entity Constraint

name

String

url

String

notes

String

description

String

telephone

String

email

String

address

String

fax

String

media

string. See media object below

model

string. See media object below

Table 165. Model Object
Entity Constraint

name

string

version

string

notes

string

description

string

url

string

media

string. See media object below

Table 166. Media Object
Entity Constraint

name

string

id

string

filename

string

type

string

size

string

type

string

dimension

string. See dimension object below

Table 167. Dimension Object
Entity Constraint

width

number

height

number

An example could be something like this

Example 53. Hardware Info as JSON
{
    "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

Example 54. Hardware summary info as JSON with summary - /[version]/search/catalog/hardwares/summary
{
    "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

Table 168. Filter fields for searching Jobs
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

Table 169. Filter fields for searching Finished only Jobs by operations summary
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

Table 170. Summary common structure
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

Table 171. Entity operations Search: Summarized Elements
Entity Constraint

name

See Summarized Specific Object Operations Structure

status

See Summarized Specific Object Operations StructureSee also Job Status Enumeration

Table 172. Summarized Specific Object Operations Structure
Entity Constraint

count

number of occurrences found of this specific element

list

Array of each type of Summarized Element Structure

Table 173. 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

Table 174. Jobs. Response structure
Entity Constraint

jobs[]

see Job structure below

Table 175. Job structure
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

See Job Request Object Structure

report

See Job Report Object Structure

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

Example 55. Searching Jobs: Response example - /north/v80/search/jobs?summary=true
{
    "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
                }
            }
        }
    ]
}
Example 56. Searching Jobs: Response example without summary - /north/v80/search/jobs
{
    "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

Example 57. Searching jobs summary: Response example - /north/v80/search/jobs/summary
{
    "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

URL parameters

There are not specific parameters applicable to these URLs

Applicable Filter Fields

Table 176. Filter fields for searching executed operations
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

Table 177. Summary common structure
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

Table 178. Entity operations Search: Summarized Elements
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

Table 179. Summarized Specific Object Operations Structure
Entity Constraint

count

number of occurrences found of this specific element

list

Array of each type of Summarized Element Structure

Table 180. 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

Table 181. Entities with operations. Response structure
Entity Constraint

operations[]

see object collection bellow

Table 182. Operation structure
Attributes Description

jobId

Operation group identifier.

entityId

Entity identifier

entityType

See Entity Type Enumeration

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

See Operation Status Enumeration

result

See Operation Result Enumeration

description

string. Completed by some device connectors to describe the result of the operation

steps[]

See Operation Step Object.

Table 183. Operation Execution Object attributes
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

Table 184. Attempts structure
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

Example 58. Searching device operations: Response example - /north/v80/search/entities/devices/operations?summary=true
{
    "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"
        }
    ]
}
Example 59. Searching device operations: Response example without summary - /north/v80/search/entities/devices/operations
{
    "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

Example 60. Searching device operations summary: Response example - /north/v80/search/entities/devices/operations/summary
{
    "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

URL parameters

There are not specific parameters applicable to this URLs

Applicable Filter Fields

Table 185. Filter fields for searching Catalogued operations
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

Table 186. Summary common structure
Entity Constraint

count (field)

number of occurrences found in the whole search

Operation Object

Table 187. Operation structure
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

Example 61. Operation Info as JSON without summary
{
    "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

URL

Type of Information URL

Operators name

/north/v80/search/catalog/operators

Applicable Filter Fields

Table 188. Filter fields for searching Catalogued operators
Field name field name in where clause type

name

operator.name

string

Operators structure

Table 189. Operators Object
Entity Constraint

id

string

name

string

An example could be something like this

Operators Info as JSON
{
    "operators": [
        {
            "name": "MOVISTAR"
        },
        {
            "name": "ORANGE"
        }
    ]
}

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

Table 190. Filter fields for searching Catalogued plans
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

Table 191. Plan objects and attributes
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

Table 192. flowRate object
value max number of event per unit of time. Mandatory

unit

unit of time per flow rate. Mandatory

Table 193. maxStorageLifeTime object
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

Example 62. Searching organization’s plans (/north/v80/search/catalog/plans/organization?domainName=domain_plan)
{
      "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
        }
      ]
}
Example 63. Searching device’s plans (/north/v80/search/catalog/plans/device?domainName=domain_plan)
{
	"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.

URL

Type of Information URL

Rules provisioned in the platform

/north/v80/rules/search

Applicable Filter Fields

Table 194. Filter fields for searching Catalogued domains
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

URL parameters

There are not specific parameters applicable to this URLs

Applicable Filter Fields

Table 195. Filter fields for searching Catalogued software and software version
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

Table 196. Software Catalog Search: Summarized Elements
Entity Constraint

firmware

See Summarized Specific Object Operations Structure

manufacturer

See Summarized Specific Object Operations Structure

Software structure

For get the software of the platform the JSON response has the next format:

Table 197. Software Object
Entity Constraint

id

string

name

string

version

string

type

string. See Software Type Enumeration values

An example could be something like this

Example 64. Software Info as JSON
{
    "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

Example 65. Software summary info as JSON with summary - /[version]/search/catalog/software/summary
{
    "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:

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

Table 198. URLs
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

Request for json format (default if not Accept header is included)
POST /contacts HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

...
Request for csv format
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.

Example Filter using subscribers predefined fields
{
  "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:

Retrieving all subscribers with json format
{
    "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

Filter to obtain all subscribers with select clause
{
  "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:

Retrieving all subscribers as flattened format
{
    "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:

Retrieving the summary
{
    "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:

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

Table 199. URLs
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

Request for json format (default if not Accept header is included)
POST /contacts HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

...
Request for csv format
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.

Example Filter using subscriptions predefined fields
{
  "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:

Retrieving all subscriptions with json format
{
    "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

Filter to obtain all subscriptions with select clause
{
  "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:

Retrieving all subscriptions as flattened format
{
    "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:

Retrieving the summary
{
    "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

Table 200. URLs
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

Request for json format (default if not Accept header is included)
POST /contacts HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

...
Request for csv format
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.

Example Filter using ticket predefined fields
{
  "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:

Retrieving all tickets with json format
{
  "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 to obtain all tickets with select clause
{
  "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"
        }
      ]
    }
  ]
}
Retrieving all tickets with the above filter and csv format
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:

Retrieving all tickets as flattened format with a 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:

Retrieving the summary
{
    "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

URL parameters

Summary parameter

Using summary parameter in the URL request, "/north/v80/search/users?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

Table 201. Filter Fields for searching Users
Parameter Description

user.email

String

user.description

String

workgroup.name

String

domain.name

String

profile.name

String

user.name

String

user.surname

String

country.code

String

language.code

String

user.timezone

String

Summary Information

Table 202. Summary common structure
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

Example 66. User list as JSON without summary (/north/v80/search/users)
{
  "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"
      }
    }
  ]
}
Example 67. User list as JSON with summary (/north/v80/search/users?summary=true)
{
  "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"
      }
    }
  ]
}
Example 68. User list summary as JSON (/north/v80/search/users/summary)
{
  "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

Table 203. Filter fields for searching Catalogued workgroup
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

Table 204. Summary common structure
Entity Constraint

count (field)

number of occurrences found in the whole search

Workgroup Object

Examples

An example of response could be something like this

Example 69. Operation Info as JSON (/north/v80/search/workgroups without summary parameter)
{
    "workgroups": [
        {
            "name": "Workgroup_1",
            "description": "Workgroup description",
            "domain" : "domain_1",
            "administrative" : true

        },
        {
            "name": "Workgroup_2",
            "description": "Workgroup description",
            "domain" : "domain_1",
            "administrative" : true
        }
    ]
}
Example 70. Operation Info as JSON (/north/v80/search/workgroups?summary=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
        }
    ]
}
Example 71. Operation Info as JSON (/north/v80/search/workgroups/summary)
{
    "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

Execution modes

The operations service API provides two ways to execute an operation, tasks and jobs. A job immediately executes the operation on remote devices, while a task define scheduled jobs whose programming options detailed below.

Jobs

Job object

A job define the operation configuration and selected remote devices to send request with the following attributes:

Table 205. Job Object
Attributes Constraints Description

id[1]

UUID format

Job identifier

taskId

UUID format

Task to which the job belongs

request

see Job Request Object

includes all the information about the Job request

report

See Job summary Object attributes

Job execution report

Table 206. Job Request Object
Attributes Constraints Description

name[1]


1 Required field in creation

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

  • true: if you want to be notified (email, trap) with the operation result.

  • false: if you don’t want to be notified. This is the default value.

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

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

Table 207. Job Request: Schedule Object
Attributes Constraints Description

start

see Job Start/Stop Object

Allows to configure the scheduled start of the operation.

stop

see Job Start/Stop Object

Allows to configure the scheduled stop of the operation.

window

see Job schedule window Object

Allows to include a specific execution period of time

scattering

see Job Scattering Object

Allows dispersing the atomic operations regarding a particular parameter, this is an optional block

Table 208. Job Request: Operation Parameters Object
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

Table 209. Job Request: Target Object attributes
Attributes Constraints Description

append

see Target List Object

Allows to append entities to the job

remove

see Target List Object

Allows to append entities to the job

Table 210. Job Request: Target List attributes
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

Table 211. Entities With Parameters Object attributes
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

Table 212. Job Report Object attributes
Attributes Constraints Description

execution

See Execution Object

Execution info

summary

See Summary Object

Counters summarizing the Job execution

target

See Report Target Object

List entities related with the job report, only used in response to create or update operations

Table 213. Job Report Execution Object attributes
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

Table 214. Job Summary Object attributes
Attributes Constraints Description

total

Number

Total of operations tried

status

See Job Status Enumeration

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

See In Progress Summary Object

Summary of in progress operations states

finished

See Finished Summary Object

Summary of finished operations states

Table 215. In Progress Summary Object
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

Table 216. Finished Summary Object
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

See Cancelled Summary Object

Cancelled single operations summary

Table 217. Cancelled Summary Object
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)

Table 218. Job Report Target List Object attributes
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

Job Life Cycle

In the figure below you can see the Job life cycle:

operation job lifecycle

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:

  1. 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.

  1. 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

  1. 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):

  • GATEWAY, if you want to take into account only gateways.

  • ASSET, if you want to take into account only assets.

  • COMMUNICATIONS_MODULE, if you want to take into account only communication modules.

  • SUBSCRIPTION, if you want to take into account only subscriptions.

  • SUBSCRIBER, if you want to take into account only subscribers.

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.

Table 219. window examples
option Allowed

"start": "09:00:00Z" "stop": "15:00:00Z"

Allowed

"start": "09:30:00Z" "stop": "15:30:00Z"

Allowed

"start": "09:00:00Z" "stop": "15:30:00Z"

Not allowed

Some JSON request examples:

Example 72. Job on target entity list as JSON document
{
    "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" ]
                }
            }
        }
    }
}
Example 73. Job on target entity list with entities with parameters as JSON document
{
    "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.

Example 74. JSON document for a job to be executed using tagged devices as target
{
    "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.

Example 75. JSON document for a job to be executed using filtered devices as target
{
    "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.

Example 76. Job with a window section
{
    "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:

Example 77. Create operation response object
{
    "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.

operation entities
Figure 4. Job summary and results

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:

Example 78. Read operation response object
{
    "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.

Table 220. Operation list objects and attributes
Attributes Constraints Description

page

See Page object attributes

Current page info

operation [ ]

See Operation object attributes

Operation array

Table 221. Page object attributes
Attributes Constraints Description

number

Number

Current page number

of

Number

Number of pages

Table 222. Operation object attributes
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

See Operation Status Enumeration

Operation status

result

See Operation Result Enumeration

Result of de operation

description

string

Used by some device connectors to describe the result of the operation

steps[]

See Step object attributes

Operation step array

Table 223. Operation Execution Object attributes
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

Table 224. Attempts structure
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.

Table 225. HTTP page limit 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:

Example 79. Update Job object
{
    "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:

Example 80. Update Job object: Append targets as entity IDs
{
    "job" :
    {
        "request" : {
            "target" : {
                "append" : {
                    "entities" : [ "device_1", "device_2" "device_3" ]
                }
            }
        }
    }
}
Example 81. Update Job object: Append targets using tags
{
    "job" :
    {
        "request" : {
            "target" : {
                "append" : {
                    "tags" : ["tag_1"]
                }
            }
        }
    }
}
Example 82. Update Job object: Remove targets as entity IDs
{
    "job" :
    {
        "request" : {
            "target" : {
                "remove" : {
                    "entities" : [ "device_1", "device_2" "device_3" ]
                }
            }
        }
    }
}
Example 83. Update Job object: Remove all targets
{
    "job" :
    {
        "request" : {
            "target" : {
                "remove" : {
                    "entities" : []
                }
            }
        }
    }
}
Example 84. Update Job object: Remove targets using tags
{
    "job" :
    {
        "request" : {
            "target" : {
                "remove" : {
                    "tags" : ["tag_1"]
                }
            }
        }
    }
}
Example 85. Update Job object: Simply start it
{
    "job" :
    {
        "request" : {
            "active" : true
        }
    }
}
Example 86. Update Job object: Pause it when Job is already running (IN_PROGRESS)
{
    "job" :
    {
        "request" : {
            "active" : false
        }
    }
}
Example 87. Update Job object: Resume it when Job is already paused (PAUSED)
{
    "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:

Example 88. Update operation response object
{
    "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):

operation push api
Figure 5. Push Callback Flow

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"

Initiated Job callback example. JSON object
{
    "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"

Started Job callback example
{
    "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

Finished Job callback example. JSON object
{
    "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

Table 226. Task object attributes
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.

name[1]


1 Required in creation

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

  • ACTIVE

  • INACTIVE

  • FINISHED

  • CANCELLING

  • CANCELLED

schedule[task_obj_req_foot]

Schedule jobs definition

job[task_obj_req_foot]

Job configuration to launch

Table 227. Job object attributes for Task
Attributes Constraints Description

request

See job.request Object

Job.Request configuration to launch

Table 228. Schedule Object
Attributes Constraints Description

start

First date execution, if you don’t specify the start field, the default value is NOW.

stop

Last execution configuration. If not present it means forever.

repeating

Repeating strategy

Table 229. Repeating Object
Attributes Constraints Description

period[3]

See Repeating Period Object

Repeating in fix time periods.

pattern[3]

See Repeating Pattern Object

Repeating date patterns

Table 230. Repeating Period Object
Attributes Constraints Description

each[1]


1 Required in creation

Number

Number of time units between two executions

unit[repeatPeriod_obj_tool]

Values:

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Time unit

Table 231. Repeating Pattern Object
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

weekly[1]


1 Only one of them, if any schedule pattern is defined, it is scheduled daily

Weekly pattern. See weekly use

monthly[repeating_pattern_foot]

Monthly pattern. See monthly use

yearly[repeating_pattern_foot]

Yearly pattern. See yearly use

Table 232. Weekly Object
Attributes Constraints Description

days[ ][1]


1 must have at least one value

Values: * MON * TUE * WED * THU * FRI * SAT * SUN

Weekday list

Table 233. Monthly Object
Attributes Constraints Description

day[1]


1 Required field

Number between 1 and 31

Day of month

months[][1]


1 Must have al least one value

Values:

  • JAN

  • FEB

  • MAR

  • APR

  • MAY

  • JUN

  • JUL

  • AUG

  • SEP

  • OCT

  • NOV

  • DEC

Month list

Table 234. Yearly Object
Attributes Constraints Description

day[1]


1 Required field

Number between 1 and 31

Day of month

month[yearly_obj_foot]

Values:

  • JAN

  • FEB

  • MAR

  • APR

  • MAY

  • JUN

  • JUL

  • AUG

  • SEP

  • OCT

  • NOV

  • DEC

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.

Start date definition as JSON document
{
    "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 :

Specific stop date definition as JSON document
{
    "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:

Execution times definition as JSON document
{
    "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:

Period definition as JSON document
{
   "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:

Weekly pattern definition as JSON document
{
   "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:

Monthly pattern definition as JSON document
{
   "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.

Yearly pattern definition as JSON document
{
   "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.

  1. 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).

  1. Using a previously created tag.

You can’t mix target references with tag or filter references.

  1. 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):

  • GATEWAY, if you want to take into account only gateways

  • ASSET, if you want to take into account only assets

  • COMMUNICATIONS_MODULE, if you want to take into account only communication modules

  • SUBSCRIPTION, if you want to take into account only subscriptions

  • SUBSCRIBER, if you want to take into account only subscriber

Task as JSON document
{
   "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:

Read Task Object
{
   "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.

Table 235. HTTP page limit 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

Assigned entity of a task JSON document
{
   "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.

Assigned entity of a task JSON document
{
   "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

Table 236. Alarm Operation Object
Entity Constraint Description

id

UUID format. string

Unique identification of the alarm instance

action

String enumeration with the next values:

  • "CLOSE": Set Alarm to closed state

  • "ATTEND": Set Alarm to attended state

Severity of the raised alarm

Alarm operation response structure

Table 237. Alarm Operation Response Object
attribute (* required) Description

result

see result object below

Table 238. Alarm Operation Response Result Object
attribute (* required) Description

count

number of processed instances

successful

number of instances that have been processed with success

error

see error object below

Table 239. Alarm Operation Response Result Error Object
attribute (* required) Description

notExist

see error summary below

Table 240. Alarm Operation Response Result Error Summary Object
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.

Alarm closing as JSON document
{
    "action" : "CLOSE",
    "alarms" : [ "50dca9ab-f552-4805-9cff-019090d5b92b", "50dca9ab-f552-4805-9cff-019090d5b92c" ],
    "notes" : "notes of the reason"
}
Alarm attending as JSON document
{
    "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
Alarm operation response as JSON document
{
    "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

Table 241. Entity Type

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

Table 242. time zone
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 Common definitions

Operation Parameters type & subtype definition Values

See Field Definition Types

Operation Parameters

Table 243. Parameter Object
Field JSON type Description Used in

name

string

Name of the parameter used internally by the platform to identify the operation

  • Operations catalog searching

  • Operations reading & searching

  • Operations Job Request

  • Operations Job entitiesWithParameters

  • Datamodel

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.

  • Operations catalog searching

  • Datamodel

access

string

Parameter access type

  • Datamodel

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.

  • Operations catalog searching

  • Datamodel

type

string enumeration. See values in Type & Subtype table

Indicates the data type for the values to be applied to the parameter

  • Operations catalog searching

  • Operations reading & searching

  • Operations Job Request

  • Datamodel

subtype

string enumeration. See values in Type & Subtype table

Depends on the data type

  • Operations catalog searching

  • Operations reading & searching

  • Operations Job Request

  • Datamodel

required

boolean

Indicates if parameter is required or not when a operation is called through the Jobs API

  • Operations catalog searching

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

  • Operations catalog searching

  • Datamodel

properties[]

array of Parameters Objects

Only used when type is object

  • Operations catalog searching

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

  • Operations catalog searching

  • Operations reading & searching

  • Operations Job Request

  • Operations Job entitiesWithParameters

protocols

see protocol structure below

only used with datamodels to know the protocol for use the parameter

  • Datamodel

Table 244. Protocols object structure
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

Table 245. Attributes Object
Field JSON type Description Used With types/subtypes

maxLength

number

Max length allowed

  • string/all subtypes

  • array/all subtype

validator

string

Regular expression to validate the value

  • all types

gt

number

Greater than

  • number/all subtypes

lt

number

Lower than

  • number/all subtypes

list[]

array

Fixed set of choices

  • enumeration/all subtypes

url

string

Dynamic set of choices

  • enumeration/all subtypes

Table 246. Value Object
Field JSON type Description Used with type/subtype

string[operationParameterValueFootnote]

string

Contains the value

  • string/all subtypes

  • calendar/all subtypes

  • address/all subtypes

  • enumeration/string subtype

boolean[operationParameterValueFootnote]

boolean

Contains the value

  • boolean

number[operationParameterValueFootnote]

number

Contains the value

  • number

object[operationParameterValueFootnote]

object

Contains the value

  • coordinates

  • object

array[][operationParameterValueFootnote]

array

Contains the value

  • array/all subtypes

[5]

Operation Steps

Table 247. Step Object
Field JSON type Description Used in

name

string

Unique name of the step used internally by the platform to identify the operation

  • Operations catalog searching

  • Operations reading & searching

  • Operations Job Response

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.

  • Operations catalog searching

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.

  • Operations catalog searching

result

Valid values:

  • ERROR

  • SUCCESSFUL

  • SKIPPED

  • NOT_EXECUTED

Result of the step

  • Operations reading & searching

  • Operations Job Response

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

  • Operations reading & searching

  • Operations Job Response

response[]

array

Array of parameter definition list required by the operation. See Parameters Object.

  • Operations catalog searching

  • Operations reading & searching

  • Operations Job Response

Job Status Enumerations

Table 248. Job Status

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

Table 249. Operation Status

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

Table 250. Operation Result

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

Table 251. Job Start/Stop Object
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

Table 252. Task Start Object
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

Table 253. Task Stop Object
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

Table 254. Job schedule window Object
Attributes Constraints Description

weekly

see Job schedule weekly Object

Allows to configure the specific time of execution of a week

Table 255. Job schedule weekly Object
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

see Job schedule daily Object

Allows to specify de available time of execution for a specific day

Table 256. Job schedule daily Object
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

Table 257. Job Scattering Object
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

see strategy object

In this block you can define how the dispersion is made for a particular parameter

Table 258. Job Strategy Object
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.

Table 259. Format examples
What Format Sample

Year

YYYY

(eg 2015)

Year and month

YYYY-MM

(eg 2015-10)

Complete date

YYYY-MM-DD

(eg 2015-10-06)

Complete date plus hours and minutes

YYYY-MM-DDThh:mm

(eg 2015-10-06T17:35)

Complete date plus hours, minutes and seconds

YYYY-MM-DDThh:mm:ss

(eg 2015-10-06T17:35:21)

Complete date plus hours, minutes, seconds and a decimal fraction of a second

YYYY-MM-DDThh:mm:ss.s

(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:

iot basics V8
Figure 6. IoT API basics

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 at attribute indicates when the measure was collected.

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:

iot basics device datamodel concept

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:

iot basics smartmeter scenario basic

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.

iot basics smartmeter scenario enhanced

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

iot basics ehealth scenario

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:

Table 260. Datamodel object attributes
Attribute Mandatory Description

identifier

Yes

Datamodel Identifier. It must be unique.

organizationName

Yes

Name of the organization

name

Yes

Name of the datamodel

description

No

Description of the datamodel

version

Yes

Version of the datamodel

allowedResourceTypes[]

Yes

Array of resourceType allowed, see entities

categories[]

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

Table 261. Datamodel Category Object
Attribute Mandatory Description

identifier

Yes

Identifier of the category

name

No

Name of the category

datastreams[]

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

Table 262. IoT Datastream: Template Object
Attribute Mandatory Description

identifier

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".

name

Yes

Name of the template

description

Yes

Description of the template

period

No

String enumeration, one of:

- PULSE

- CUMULATIVE

- INSTANT. This is the default value

access

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.

schema

Yes

Used for defining the format of the datastream value. It must have a correct jsonSchema format. See see schema object

storage

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.

unit

No

See unit object attributes

modifiable

No

Boolean value to indicate if it is modifiable this datastream. The default value is true

calculated

No

Boolean value to indicate if it is a datastream internally calculated by the platform. The default value is false

required

No

Boolean value to indicate if it is required for this datastream. The default value is false

qrating

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

tags[]

No

Array of strings used to tag the datastream, 50 characters max. per tag

views

No

To be used in the future

icon

No

Used for asociate an icon in the web datastream visualitation, See IoT Datastream Icon Object.

Table 263. Unit object attributes
Attribute Description

type

String describing the type of unit you want

label

String with the label you want for your unit

symbol

String with the symbol you want for your unit

This fields are not mandatory and its default value is empty

Datamodel example
{
  "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.

Table 264. Qrating object attributes
Attribute Mandatory Type Description

version

Yes

String

Version of the configurated Qrating

max_score

Yes

Number

Datastream weight within the datastream

ideal

Yes

Number

The best value that can be collected for the datastream

min_required

Yes

Number

Minimum value accepted by the datastream (indicates when a data point collected is critical below the ideal)

min_desired

Yes

Number

Datastream desired minimum value (the datapoint collected is not critical but is below the ideal)

max_desired

Yes

Number

Datastream desired maximum value (the datapoint collected is not critical but is above the ideal)

max_allowed

Yes

Number

Maximum value accepted by the datastream (indicates when a data point collected is critical above ideal)

conversion_matrix

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

cumulative_period_divisor

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

Table 265. Conversion Matrix object attributes
Attribute Value of the attribute

expected value

Value translated for the expected value

Datamodel example with typical number datastream qRating object
{
  "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.

Table 266. Storage object attributes
Attribute Description

period

Specify the units of time that OpenGate have to consider for deleting historical datapoints, the available values are:

- DAYS

- MONTHS

- YEARS

- NEVER, if you select this value, no one datapoint will be storaged, the information of the last one could be got in datastream’s search

total

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

Table 267. Storage object attributes
Attribute Description

class

Specify the class to represent icon’s name

Datamodel example with icon object
{
  "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.

CollectionAsset-8.0.0.0

Parameter Description

ProvisionAsset-8.0.0.0

Parameter Description

ProvisionDevice-8.0.0.0

Parameter Description

ProvisionGenericIdentifier-8.0.2.0

Parameter Description

Ticket-8.0.21.0

Parameter Description

CollectionDevice-8.0.0.0

Parameter Description

Bts-8.0.32.0

Parameter Description

CollectionSubscription-8.0.21.0

Parameter Description

CollectionChannel-8.0.2.0

Parameter Description

CollectionOrganization-8.0.2.0

Parameter Description

ProvisionChannel-8.0.2.0

Parameter Description

ProvisionGeneric-8.0.2.0

Parameter Description

ProvisionOrganization-8.0.1.0

Parameter Description

Human-8.0.21.0

Parameter Description

ProvisionGenericChannel-8.0.2.0

Parameter Description

ProvisionGenericOrganization-8.0.2.0

Parameter Description

ProvisionSubscriber-8.0.0.0

Parameter Description

ProvisionSubscription-8.0.21.0

Parameter Description

CollectionSubscriber-8.0.0.0

Parameter Description

Entity-8.0.0.0

Parameter Description

SIM Management Specific Datamodels

This chapter describes how different flavour sensor signals can be modelled using the OpenGate datastream concept.

AnalyticSimManagement-1.1

Parameter Description

CollectionSimManagement-1.1

Parameter Description

ProvisioSimManagement-1.4

Parameter Description

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

Og Electricity-1.0

Parameter Description

Og Health-1.2

Parameter Description

Og Water-1.0

Parameter Description

Datamodel Basic Types

Type: address

Table 268. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "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

Table 269. Attributes
Attribute Value

type

string

description

values

  • ACTIVE

  • BANNED

  • DELETED

  • INVALID

  • READY

  • REPAIR

  • REQUESTED

  • RETIRED

  • SUSPENDED

  • TESTED

  • TESTING

  • UNKNOWN

Type in JSON format
{
    "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

Table 270. Attributes
Attribute Value

type

string

description

values

  • NORMAL

  • OPEN

  • SHORT_CIRCUIT

  • UNKNOWN

Type in JSON format
{
    "enum": [
        "NORMAL",
        "OPEN",
        "SHORT_CIRCUIT",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "NORMAL",
        "OPEN",
        "SHORT_CIRCUIT",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: area

Table 271. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "properties": {
        "description": {
            "type": "string"
        },
        "identifier": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "order": {
            "type": "integer"
        }
    },
    "type": "object"
}

Type: areas

Table 272. Attributes
Attribute Value

type

array

description

Type in JSON format
{
    "items": {
        "$ref": "#/definitions/area"
    },
    "type": "array"
}

Type: arrayIdentifier

Table 273. Attributes
Attribute Value

type

array

description

Type in JSON format
{
    "items": {
        "$ref": "#/definitions/ogIdentifier"
    },
    "type": "array"
}

Type: arrayString

Table 274. Attributes
Attribute Value

type

array

description

Type in JSON format
{
    "items": {
        "type": "string"
    },
    "type": "array"
}

Type: assetAdministrativeState

Table 275. Attributes
Attribute Value

type

string

description

values

  • BANNED

  • DELETED

  • IN_MAINTENANCE

  • IN_STOCK

  • IN_TRANSIT

  • IN_USE

  • MISSING

  • ORDERED

  • READY

  • RETIRED

Type in JSON format
{
    "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

Table 276. Attributes
Attribute Value

type

string

description

values

  • 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 in JSON format
{
    "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

Table 277. Attributes
Attribute Value

type

string

description

values

  • CHARGING

  • CHARGED

  • UNPLUGGED

  • ERROR

  • UNKNOWN

Type in JSON format
{
    "enum": [
        "CHARGING",
        "CHARGED",
        "UNPLUGGED",
        "ERROR",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "CHARGING",
        "CHARGED",
        "UNPLUGGED",
        "ERROR",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: certificateList

Table 278. Attributes
Attribute Value

type

array

description

Type in JSON format
{
    "items": {
        "type": "string"
    },
    "type": "array"
}

Type: clock

Table 279. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "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

Table 280. Attributes
Attribute Value

type

string

description

values

  • STOPPED

  • STOPPING

  • STARTING

  • RUNNING

  • DISABLED

  • ERROR

Type in JSON format
{
    "description": "",
    "enum": [
        "STOPPED",
        "STOPPING",
        "STARTING",
        "RUNNING",
        "DISABLED",
        "ERROR"
    ],
    "javaEnumNames": [
        "STOPPED",
        "STOPPING",
        "STARTING",
        "RUNNING",
        "DISABLED",
        "ERROR"
    ],
    "title": "Operational Status",
    "type": "string"
}

Type: commsModuleSpecificType

Table 281. Attributes
Attribute Value

type

string

description

values

  • ADSL

  • CAN

  • ETH

  • GENERIC

  • GSM

  • HAN

  • I2C

  • LOWPAN

  • MESH

  • MOBILE

  • MULTIMOBILE

  • PLC

  • RS232

  • RS422

  • RS485

  • SIGFOX

  • UMTS

  • WIFI

  • ZIGBEE

  • ZWAVE

  • NARROWBAND

  • LTE_M

Type in JSON format
{
    "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

Table 282. Attributes
Attribute Value

type

array

description

A geographical coordinates

Type in JSON format
{
    "description": "A geographical coordinates",
    "items": {
        "type": "number"
    },
    "maxItems": 2,
    "public": true,
    "type": "array"
}

Type: cpuStatus

Table 283. Attributes
Attribute Value

type

string

description

values

  • IDLE

  • IDLE/WORKING

  • WORKING

  • STRESSED

  • OVERLOAD

Type in JSON format
{
    "enum": [
        "IDLE",
        "IDLE/WORKING",
        "WORKING",
        "STRESSED",
        "OVERLOAD"
    ],
    "javaEnumNames": [
        "IDLE",
        "IDLE_WORKING",
        "WORKING",
        "STRESSED",
        "OVERLOAD"
    ],
    "type": "string"
}

Type: datamodelParamName

Table 284. Attributes
Attribute Value

type

string

description

Id of the parameter

Type in JSON format
{
    "description": "Id of the parameter",
    "title": "Id",
    "type": "string"
}

Type: datamodelParamNameValue

Table 285. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "properties": {
        "name": {
            "$ref": "#/definitions/datamodelParamName"
        },
        "value": {
            "description": "Value of the parameter",
            "title": "Value",
            "type": "string"
        }
    },
    "required": [
        "name",
        "value"
    ],
    "type": "object"
}

Type: datamodelResponse

Table 286. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "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

Table 287. Attributes
Attribute Value

type

string

description

Result code of Get Operation

values

  • SUCCESS

  • PARAM_NOT_SUPPORTED

  • INVALID_FORMAT

  • WRONG_VALUE

  • UNKNOWN

Type in JSON format
{
    "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

Table 288. Attributes
Attribute Value

type

string

description

date in ISO 8601

Type in JSON format
{
    "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

Table 289. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "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

Table 290. Attributes
Attribute Value

type

string

description

values

  • NORMAL

  • SAFE_MODE

  • TAMPER

  • TEST

  • DOWN

  • ALARM

  • UNKNOWN

Type in JSON format
{
    "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

Table 291. Attributes
Attribute Value

type

string

description

values

  • BLOODPRESSURE_SENSOR

  • COMHUB

  • CONCENTRATOR

  • CONTAINER

  • COORDINATOR

  • GATEWAY

  • GENERIC

  • GLUCOMETER_SENSOR

  • METER

  • MODEM

  • ROUTER

  • SENSOR

  • TPV

  • VEHICLE

  • VENDING

  • WEIGHT_SENSOR

Type in JSON format
{
    "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

Table 292. Attributes
Attribute Value

type

integer

description

Type in JSON format
{
    "default": 0,
    "minimum": 0,
    "title": "DST",
    "type": "integer"
}

Type: entityType

Table 293. Attributes
Attribute Value

type

string

description

values

  • GATEWAY

  • ASSET

  • COMMUNICATIONS_MODULE

  • SUBSCRIPTION

  • SUBSCRIBER

Type in JSON format
{
    "description": "",
    "enum": [
        "GATEWAY",
        "ASSET",
        "COMMUNICATIONS_MODULE",
        "SUBSCRIPTION",
        "SUBSCRIBER"
    ],
    "javaEnumNames": [
        "GATEWAY",
        "ASSET",
        "COMMUNICATIONS_MODULE",
        "SUBSCRIPTION",
        "SUBSCRIBER"
    ],
    "title": "Entity Type",
    "type": "string"
}

Type: ipStatus

Table 294. Attributes
Attribute Value

type

string

description

values

  • OK

  • NOK

Type in JSON format
{
    "description": "",
    "enum": [
        "OK",
        "NOK"
    ],
    "javaEnumNames": [
        "OK",
        "NOK"
    ],
    "title": "IP Reachability Status",
    "type": "string"
}

Type: ipv4

Table 295. Attributes
Attribute Value

type

string

description

IPV4 format

Type in JSON 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

Table 296. Attributes
Attribute Value

type

string

description

IPV6 format

Type in JSON 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

Table 297. Attributes
Attribute Value

type

object

description

A geojson enriched for OpenGate

Type in JSON format
{
    "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

Table 298. Attributes
Attribute Value

type

string

description

MAC48 format

Type in JSON 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

Table 299. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "description": "",
    "properties": {
        "manufacturer": {
            "type": "string"
        },
        "manufacturerOUI": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "version": {
            "type": "string"
        }
    },
    "public": true,
    "title": "Model",
    "type": "object"
}

Type: msisdn

Table 300. Attributes
Attribute Value

type

string

description

Type in JSON format
{
    "maxLength": 15,
    "minLength": 7,
    "public": true,
    "type": "string"
}

Type: ogIdentifier

Table 301. Attributes
Attribute Value

type

string

description

Type in JSON format
{
    "pattern": "^[a-zA-Z0-9_@.-]*$",
    "public": true,
    "type": "string"
}

Type: ogIdentifierUnreferenced

Table 302. Attributes
Attribute Value

type

string

description

Type in JSON format
{
    "pattern": "^[a-zA-Z0-9_@.-]*$",
    "public": true,
    "type": "string"
}

Type: ogImage

Table 303. Attributes
Attribute Value

type

string

description

Type in JSON format
{
    "type": "string"
}

Type: outage

Table 304. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "properties": {
        "duration": {
            "type": "number"
        },
        "started": {
            "$ref": "#/definitions/timestamp"
        }
    },
    "type": "object"
}

Type: percentage

Table 305. Attributes
Attribute Value

type

number

description

Type in JSON format
{
    "maximum": 100,
    "minimum": 0,
    "public": true,
    "type": "number"
}

Type: powerSupplySource

Table 306. Attributes
Attribute Value

type

string

description

values

  • BATTERY

  • DIESEL_GENERATOR

  • NETWORK_PLUGGED

  • SOLAR

  • OTHER

Type in JSON format
{
    "enum": [
        "BATTERY",
        "DIESEL_GENERATOR",
        "NETWORK_PLUGGED",
        "SOLAR",
        "OTHER"
    ],
    "javaEnumNames": [
        "BATTERY",
        "DIESEL_GENERATOR",
        "NETWORK_PLUGGED",
        "SOLAR",
        "OTHER"
    ],
    "type": "string"
}

Type: powerSupplyStatus

Table 307. Attributes
Attribute Value

type

string

description

values

  • PLUGGED_CHARGING

  • PLUGGED_CHARGED

  • OUTAGE

  • UNPLUGGED

  • UNKNOWN

Type in JSON format
{
    "enum": [
        "PLUGGED_CHARGING",
        "PLUGGED_CHARGED",
        "OUTAGE",
        "UNPLUGGED",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "PLUGGED_CHARGING",
        "PLUGGED_CHARGED",
        "OUTAGE",
        "UNPLUGGED",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: presenceGprs

Table 308. Attributes
Attribute Value

type

string

description

values

  • START

  • STOP

  • INTERIM_UPDATE

  • ON

  • OFF

  • NOK

Type in JSON format
{
    "enum": [
        "START",
        "STOP",
        "INTERIM_UPDATE",
        "ON",
        "OFF",
        "NOK"
    ],
    "javaEnumNames": [
        "START",
        "STOP",
        "INTERIM_UPDATE",
        "ON",
        "OFF",
        "NOK"
    ],
    "type": "string"
}

Type: presenceGsm

Table 309. Attributes
Attribute Value

type

string

description

values

  • OK

  • NOK

  • UNCONFIG

  • UNKNOWN

Type in JSON format
{
    "enum": [
        "OK",
        "NOK",
        "UNCONFIG",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "OK",
        "NOK",
        "UNCONFIG",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: presenceIp

Table 310. Attributes
Attribute Value

type

string

description

values

  • OK

  • NOK

Type in JSON format
{
    "enum": [
        "OK",
        "NOK"
    ],
    "javaEnumNames": [
        "OK",
        "NOK"
    ],
    "type": "string"
}

Type: signalQualityStatus

Table 311. Attributes
Attribute Value

type

string

description

values

  • LOW_CRITICAL

  • LOW_WARNING

  • NORMAL

  • EXCELENT

Type in JSON format
{
    "enum": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "javaEnumNames": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "type": "string"
}

Type: signalStrengthStatus

Table 312. Attributes
Attribute Value

type

string

description

values

  • LOW_CRITICAL

  • LOW_WARNING

  • NORMAL

  • EXCELENT

Type in JSON format
{
    "enum": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "javaEnumNames": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "type": "string"
}

Type: software

Table 313. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "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

Table 314. Attributes
Attribute Value

type

array

description

Type in JSON format
{
    "items": {
        "$ref": "#/definitions/software"
    },
    "type": "array"
}

Type: subscriberSpecificType

Table 315. Attributes
Attribute Value

type

string

description

values

  • ADSL

  • CAN

  • ETH

  • GENERIC

  • GSM

  • HAN

  • I2C

  • LOWPAN

  • MESH

  • MOBILE

  • PLC

  • RS232

  • RS422

  • RS485

  • SIM

  • UMTS

  • WIFI

  • ZIGBEE

  • ZWAVE

  • NARROWBAND

  • LTE_M

Type in JSON format
{
    "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

Table 316. Attributes
Attribute Value

type

string

description

values

  • ADSL

  • CAN

  • ETH

  • GENERIC

  • GSM

  • HAN

  • I2C

  • LOWPAN

  • MESH

  • MOBILE

  • PLC

  • RS232

  • RS422

  • RS485

  • SIGFOX

  • UMTS

  • WIFI

  • ZIGBEE

  • ZWAVE

  • NARROWBAND

  • LTE_M

Type in JSON format
{
    "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

Table 317. Attributes
Attribute Value

type

string

description

values

  • LOW_CRITICAL

  • LOW_WARNING

  • NORMAL

  • HIGH_WARNING

  • HIGH_CRITICAL

Type in JSON format
{
    "enum": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "HIGH_WARNING",
        "HIGH_CRITICAL"
    ],
    "javaEnumNames": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "HIGH_WARNING",
        "HIGH_CRITICAL"
    ],
    "type": "string"
}

Type: text

Table 318. Attributes
Attribute Value

type

string

description

Type in JSON format
{
    "type": "string"
}

Type: ticketIdentifier

Table 319. Attributes
Attribute Value

type

string

description

Type in JSON format
{
    "pattern": "^[a-zA-Z0-9_@.-]*$",
    "public": true,
    "type": "string"
}

Type: ticketPriority

Table 320. Attributes
Attribute Value

type

string

description

values

  • MAJOR

  • MINOR

  • CRITICAL

  • BLOCKER

Type in JSON format
{
    "enum": [
        "MAJOR",
        "MINOR",
        "CRITICAL",
        "BLOCKER"
    ],
    "javaEnumNames": [
        "MAJOR",
        "MINOR",
        "CRITICAL",
        "BLOCKER"
    ],
    "title": "Priority",
    "type": "string"
}

Type: ticketSeverity

Table 321. Attributes
Attribute Value

type

string

description

values

  • CRITICAL

  • URGENT

  • WARNING

  • NORMAL

Type in JSON format
{
    "enum": [
        "CRITICAL",
        "URGENT",
        "WARNING",
        "NORMAL"
    ],
    "javaEnumNames": [
        "CRITICAL",
        "URGENT",
        "WARNING",
        "NORMAL"
    ],
    "title": "Severity",
    "type": "string"
}

Type: ticketSpecificType

Table 322. Attributes
Attribute Value

type

string

description

values

  • WORKORDER

  • INCIDENT

  • REQUEST

  • FORM

Type in JSON format
{
    "enum": [
        "WORKORDER",
        "INCIDENT",
        "REQUEST",
        "FORM"
    ],
    "javaEnumNames": [
        "WORKORDER",
        "INCIDENT",
        "REQUEST",
        "FORM"
    ],
    "title": "Specific Type",
    "type": "string"
}

Type: ticketStatus

Table 323. Attributes
Attribute Value

type

string

description

values

  • CREATED

  • ASSIGNED

  • ANSWERED

  • RESTORED

  • RESOLVED

  • CLOSED

Type in JSON format
{
    "enum": [
        "CREATED",
        "ASSIGNED",
        "ANSWERED",
        "RESTORED",
        "RESOLVED",
        "CLOSED"
    ],
    "javaEnumNames": [
        "CREATED",
        "ASSIGNED",
        "ANSWERED",
        "RESTORED",
        "RESOLVED",
        "CLOSED"
    ],
    "title": "Status",
    "type": "string"
}

Type: ticketType

Table 324. Attributes
Attribute Value

type

string

description

values

  • INSTALLATION

  • TEST

  • TECHNICAL_TASK

  • UNINSTALLATION

  • MODIFICATION

  • BALANCES_AT_MT_TELEMEDIDA

Type in JSON format
{
    "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

Table 325. Attributes
Attribute Value

type

string

description

time in ISO 8601

Type in JSON format
{
    "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

Table 326. Attributes
Attribute Value

type

string

description

date & time in ISO 8601

Type in JSON format
{
    "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

Table 327. Attributes
Attribute Value

type

string

description

Type in JSON format
{
    "title": "timezone",
    "type": "string"
}

Type: topologyPath

Table 328. Attributes
Attribute Value

type

array

description

Type in JSON format
{
    "items": {
        "type": "string"
    },
    "type": "array"
}

Type: trafficSession

Table 329. Attributes
Attribute Value

type

object

description

Type in JSON format
{
    "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

Table 330. Attributes
Attribute Value

type

string

description

values

  • IP

  • GPRS

  • GSM

  • NOT_REGISTERED

  • UNKNOWN

Type in JSON format
{
    "enum": [
        "IP",
        "GPRS",
        "GSM",
        "NOT_REGISTERED",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "IP",
        "GPRS",
        "GSM",
        "NOT_REGISTERED",
        "UNKNOWN"
    ],
    "type": "string"
}

Administrative Status Enumeration

Table 331. Administrative State attribute values
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

Table 332. Device Operational Status
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

Table 333. Communications Modules Operational Status
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

Table 334. Subscription Object attributes
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

Table 335. Dimensions object
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.

Table 336. type & subtype definition available values
Type Subtype Description

string

  • text

  • password

Text based value

boolean

Boolean based value. Exmaples: true or false

calendar

  • datetime

  • date

  • time

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

  • ip

  • ipv4

  • ipv6

  • mac48

Network address value

number

  • integer

  • float

  • percentage

Numeric value

enumeration

  • string

  • number

Choice list values

array

  • string

  • number

Array of values

coordinates

  • geo

  • geotime

  • geojson

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

  • path

  • tree (not supported yet)

Object indicating relations. See following examples

path
[ "granparent_1", "parent_1"]

object

None

Not yet supported. For future uses only

Table 337. field definition attributes object
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

Table 338. Built in operations
Applicable To Name North Api parameters South Api parameters

Device

UPDATE (See Device update)

  • bundleName: String with the name of the bundle to be applied

  • bundleVersion: Version of the bundle to be applied

  • bundleName: String with the name of the bundle to be applied

  • bundleVersion: Version of the bundle to be applied

  • url: String with URL to download the bundle files in a zip format

Device

SET_CLOCK_EQUIPMENT

  • date (optional)

  • time (Optional)

  • timezone

  • dst

If you don’t include parameters the time sent to the device will be the actual in the moment of operation execution.

  • datetime: Number with the time in seconds from epoch

  • timezone

  • dst

Device

POWER_ON_EQUIPMENT

Device

POWER_OFF_EQUIPMENT

Device

REBOOT_EQUIPMENT

  • type

    • HARDWARE

    • SOFTWARE

    • APPLICATION

  • applications: Array of strings with name of applications to be rebooted

Same

Device

REFRESH_LOCATION

Device

REFRESH_INFO

Device

REFRESH_PRESENCE

Device

STATUS_DIAGNOSTIC

ADMINISTRATIVE_STATUS

Device

EQUIPMENT_DIAGNOSTIC

  • name

    • HARDWARE

    • SOFTWARE

    • DEVICE

Same

Device

WAKE_UP_COMMUNICATIONS

  • mode

    • ALL

    • SELECTED

  • profile

  • channel

    • IP-GPRS

    • IP-WIFI

    • SMS

Device

RESET_COMMUNICATIONS

PROFILE

Device, Subscription, Subscriber

ADMINISTRATIVE_STATUS_CHANGE

STATUS

Device

SHUT_DOWN_COMMUNICATIONS

PROFILE

Subscription

SERVICE_CONFIGURATION

  • data

    • ENABLED

    • DISABLED

  • smsIncoming

    • ENABLED

    • DISABLED

  • smsIncomingMode

    • BLACK_LIST

    • WHITE_LIST

  • smsOutgoing

    • ENABLED

    • DISABLED

  • smsOutGoingMode

    • BLACK_LIST

    • WHITE_LIST

    • smsOutGoingList[]

  • dataCallIncomingMode

    • ENABLED

    • DISABLED

  • dataCallOutgoing

    • ENABLED

    • DISABLED

  • dataCallOutgoingMode

    • BLACK_LIST

    • WHITE_LIST

  • dataCallOutgoingList[]

  • voiceCallIncoming

    • ENABLED

    • DISABLED

  • voiceCallOutgoing

    • ENABLED

    • DISABLED

  • voiceCallOutgoingMode

    • BLACK_LIST

    • WHITE_LIST

  • voiceCallOutgoingList[]

Subscription

RATE_PLAN_CHANGE

  • ratePlan

    • RATE_PLAN

    • TEST_RATE_PLAN

    • DISCOUNT_RATE_PLAN

    • SPECIAL_OFFER_RATE_PLAN

    • GENERIC_RATE_PLAN

Subscription

APN_ALLOWED

  • apnList[]

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

North API Parameters format
"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

South API Parameters format
"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:

opengate api south operation UPDATE flow
Figure 7. Update operation 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:

Table 339. Device Update operation parameters
Parameter (*required) Constraints Description

bundleName*

String

Name of the bundle.

bundleVersion *

String

Version of the bundle

Device Update Example
{
    "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:

Table 340. Device Update operation parameters
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

Table 341. 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

Table 342. South API Deployment Element Object
Parameter Constraints Description

type

string

Type of the validation algorithm

value

string

string to perform the validation

Device Update Example
{
    "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)

Table 343. Built in rules 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_location_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • datastream_name: Added parameter to check also

  • area: Identifier of the area, example: "Zone3"

  • datastream_value: Value of added parameter (datastream_name)

DATASTREAM

areaOutputWithParameter

Checks if an entity has exitted of a geofence

  • datastream_location_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • datastream_name: Added parameter to check also

  • area: Identifier of the area, example: "Zone3"

  • datastream_value: Value of added parameter (datastream_name)

DATASTREAM

batteryThreshold

Current value of datastream has an unusual value

  • threshold: Threshold that allows to manage if a measure is lower, example: 5 (integer)

DATASTREAM

cancelBatteryThreshold

Current value of datastream has is returned to usual value

  • threshold: Threshold that allows to manage if a measure is higher, example: 5 (integer)

DATASTREAM

changeCommsModuleOperationalStatusByNokPing

Put selected operational status to communication module if consecutive NOK Ping reach selected value. Needs countPings rule enabled

  • operational_status: Value to collect in datastream "device.communicationModules[].operationalStatus" when condition has been satisfied, example: "DISABLED"

  • threshold: Number of pings NOK in order to satisfy condition: 50 (integer)

DATASTREAM

changeCommsModuleOperationalStatusByOkPing

Put selected operational status to communication module if OK Ping received

  • operational_status: Value to collect in datastream "device.communicationModules[].operationalStatus" when condition has been satisfied, example: "RUNNING"

DATASTREAM

checkDistance

Checks if entity is farther than a defined distance

  • datastream_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • latitude: Coordinates of latitude, example: 40.47 (number)

  • longitud: Coordinates of latitude, example: -3.66 (number)

  • distance: Distance to be checked, example: 2000 (integer)

  • entityKeys: example: "ALL"

DATASTREAM

collectAreas

Calculate entity.area datastream (and its derivatives) based on entity.location datastream

  • datastream_location_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • datastream_area_name: Added parameter to check also, example: "entity.areas"

DATASTREAM

countAccountingStart

Count accounting start in subscription

  • subscription_accounting_datastream: example: "device.communicationModules[].subscription.counters.presence.accountingStartLastDay"

  • device_accounting_datastream: example: "device.counters.presence.accountingStartLastDay"

  • ttl_datapoints_collector: ttl for datapoints collected

DATASTREAM

countPings

Count number of ping [OK/NOK/NOK consecutives] to get information in mobile net

  • ignored_operational_status: example: "DISABLED"

  • ttl_datapoints_collector: ttl for datapoints collected

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_name: Added parameter to check also

  • threshold: Value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • extra_threshold: Extra value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • collect_datastream_to: Name of the data stream to set to true when condition is satisfied. By default its value is "presenciaTotal".

  • rule_to_close: Rule to close

DATASTREAM

presenceUnreachableAllInterfaces

Verify if the device is unreacheable through all its communication interfaces

  • datastream_name: Added parameter to check also

  • threshold: Value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • extra_threshold: Extra value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • collect_datastream_to: Name of the data stream to set to false when condition is satisfied. By default its value is "presenciaTotal".

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

  • operator_name: example, "Sigfox Operator"

DATASTREAM

subscriptionSuspension

Check if subscription is administrativeState = SUSPENSION for a configured operator

  • operator_name: example, "Sigfox Operator"

DATASTREAM

sumSessionBytes

Sum traffic bytes can get information in mobile net

  • daily_subscription_total_datastream: example, "device.communicationModules[].subscription.counters.totalBytesLastDay"

  • daily_subscription_sent_datastream: example, "device.communicationModules[].subscription.counters.sentBytesLastDay"

  • daily_subscription_received_datastream: example, "device.communicationModules[].subscription.counters.receivedBytesLastDay"

  • monthly_subscription_total_datastream: example, "device.communicationModules[].subscription.counters.totalBytesLastMonth"

  • monthly_subscription_sent_datastream: example, "device.communicationModules[].subscription.counters.sentBytesLastMonth"

  • monthly_subscription_received_datastream: example, "device.communicationModules[].subscription.counters.receivedBytesLastMonth"

  • daily_device_total_datastream: example, "device.counters.totalBytesLastDay"

  • daily_device_sent_datastream: example, "device.counters.sentBytesLastDay"

  • daily_device_received_datastream: example, "device.counters.receivedBytesLastDay"

  • monthly_device_total_datastream: example, "device.counters.totalBytesLastMonth"

  • monthly_device_sent_datastream: example, "device.counters.sentBytesLastMonth"

  • monthly_device_received_datastream: example, "Sigfox Operator"

  • ttl_datapoints_collector_daily: ttl for daily datapoints collected

  • ttl_datapoints_collector_monthly: ttl for monthly datapoints collected

Notifications

The platform can send notifications using SNMP protocol using the OpenGate MIB

Legal information

Contact

Contact Information

  • AMPLIA SOLUCIONES

  • Golfo de Salónica 27, 1ª

  • 28033 Madrid

  • Info@amplia.es

  • +34 91 112 67 47

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

Table 344. Built in user profiles
Profile Permissions

root

  • Total control for managing all resources in the platform

admin_domain

  • Access to the Provision APIs:

    • Domains (create, update, delete)

    • Subdomains (create and update)

    • Organizations (create, update, delete)

    • Workgroups (create, update, delete)

    • Channels (create, update, delete)

    • Users (create, update, delete)

    • Certificates (create, update, delete, download)

    • Datamodels (create, update, delete)

    • Areas (create, read, update, delete)

    • Bulk of Assets, Devices, subscriptions (create, update, delete)

    • Assets entities (create, read, update, delete)

    • Devices entities (create, read, update, delete)

    • Subscriptions entities (create, read, update, delete)

    • Subscribers entities (create, read, update, delete)

    • APNs (create)

    • Radius Clients (create)

    • Tags (create)

    • Tickets (create, read, update, delete)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (create, read, update, delete)

    • Tasks (create, read, update, delete)

    • Alarms (read, attend, close)

    • Rules (read, update, clone, delete)

    • Bundles (create, read, update, delete, execute)

    • Download csv

admin

  • Access to the Provision APIs:

    • Workgroups (create, update, delete)

    • Channels (create, update, delete)

    • Users (create, update, delete)

    • Certificates (create, update, delete, download)

    • Datamodels (create, update, delete)

    • Areas (create, read, update, delete)

    • Bulk of Assets, Devices, subscriptions (create, update, delete)

    • Assets entities (create, read, update, delete)

    • Devices entities (create, read, update, delete)

    • Subscriptions entities (create, read, update, delete)

    • Subscribers entities (create, read, update, delete)

    • APNs (create)

    • Radius Clients (create)

    • Tags (create)

    • Tickets (create, read, update, delete)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (create, read, update, delete)

    • Tasks (create, read, update, delete)

    • Alarms (read, attend, close)

    • Rules (read, update, clone, delete)

    • Bundles (create, read, update, delete, execute)

    • Download csv

advanced

  • Access to the Provision APIs:

    • Users (update yourself)

    • Certificates (download)

    • Areas (create, read, update, delete)

    • Bulk of Assets, Devices, subscriptions (create, update, delete)

    • Assets entities (create, read, update, delete)

    • Devices entities (create, read, update, delete)

    • Subscriptions entities (create, read, update, delete)

    • Subscribers entities (create, read, update, delete)

    • Tags (create)

    • Tickets (create, read, update, delete)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (create, read, update, delete)

    • Tasks (create, read, update, delete)

    • Alarms (read, attend, close)

    • Rules (read, update, clone, delete)

    • Bundles (create, read, update, delete, execute)

    • Download csv

viewer

  • Access to the Provision APIs:

    • Users (update yourself)

    • Certificates (download)

    • Areas (read)

    • Assets entities (read)

    • Devices entities (read)

    • Subscriptions entities (read)

    • Subscribers entities (read)

    • Tickets (read)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (read)

    • Tasks (read)

    • Alarms (read)

    • Rules (read)

    • Bundles (read)

    • Download csv


1. Field only showed in reading requests and push callbacks
2. Required field
3. Only one of them. Required in creation
4. Required field
5. The fields in the Value Object are exclusive. Only a field can be present in the value object at the same time