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 datastream 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, datastreams (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.

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.

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.

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.

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

Rule name must be specified.

0x010901

HTTP 400

Specified rule not found.

0x010902

HTTP 400

Notification name cannot be empty.

0x010903

HTTP 400

Specified notification not found.

0x010904

HTTP 400

Condition name cannot be empty.

0x010905

HTTP 400

Specified condition not found.

0x010906

HTTP 400

Parameter name cannot be empty.

0x010907

HTTP 400

Specified parameter not found.

0x010908

HTTP 400

Bearer name cannot be empty.

0x010909

HTTP 400

Specified bearer not found.

0x01090A

HTTP 400

Channel not found to modify rules.

0x01090B

HTTP 400

Organization not found to modify rules.

0x01090C

HTTP 400

Delay field cannot be specified in simple conditions.

0x01090D

HTTP 400

Delay field is less than the minimum required.

0x01090E

HTTP 400

Duplicated rule in file.

0x01090F

HTTP 400

Effective date bad format.

0x010910

HTTP 400

Effective date not valid.

0x010911

HTTP 400

There cannot be syncCache.

0x010912

HTTP 400

Specified rule cannot be removed because is in default catalog.

0x010913

HTTP 400

Specified rule cannot be cloned because has child rules.

0x010914

HTTP 400

Specified rule name already exists.

0x010915

HTTP 400

Rule to clone must have actions.

0x010916

HTTP 400

Rule to close not exists.

0x010917

HTTP 400

Rule to close must have an open action.

0x010918

HTTP 400

Rule name has invalid characters. Only support alphanumeric, score, underscore, @ and dot chars.

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.

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.

Platform Event Process

Table 25. Event Generic
Code Returned HTTP Status Description

0x070000

HTTP 400

Element not exists.

0x070001

HTTP 400

Element not identified.

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.

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 30. 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 31. 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 32. 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.

This association between Asset and device is through the provision.device.related datastream. It must contain the identifier of the asset.

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

Here’s how to create an asset with the minium fields

Minimum device 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 device 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 device 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"
        }
      }
    }
  }
}

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.

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"

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.

curl --request DELETE \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/entities/worker_battery_id

Automation Rules

All automation rules provisioned in an organization can be configured in a different way to each channel in this organization. Also, they can be cloned to modify them.

You can see the default list of rules in the Default Automation Rules Catalog section

Using provision API You can configure the parameters of the rule

Rule Configuration object structure

You can access to the Rule Configuration using the name of the rule

Table 34. Rule Configuration object and attributes
attribute (* required) Description

name *

Name of the rule to be configured

enabled *

Indicates if rule have to be evaluated or not

severity *

Indicates the seriousness of this alarm. The possibles values are:

  • WITHOUT_ALARM

  • INFORMATIVE

  • URGENT

  • CRITICAL

description

Description of the alarm raised by this rule

conditions *

notifications *

open

If open alarm, boolean

close

If close an alarm specify the name of the rule who opens the alarm

groupParent

If the rule is a parent of a group of rules, boolean

groupRule

If is grouped by a rule, specify the name of the grouper rule

Table 35. Conditions Object
Entity Description

name

Name of the rule condition

delay

Delay time in milliseconds to evaluate the rule when an event to this rule is raised

parameters

List of Parameter Condition Objects. See Parameter Condition Object

Table 36. Parameter Condition Object
Entity Description

name

Name of the Parameter

value

Value of the Parameter

Table 37. Notifications Object
Entity Description

name

Name of the notification

enabled

Indicates if rule have to be evaluated or not

bearers

List of Notification Bearer Objects. See Notification Bearer Object

Table 38. Notification Bearer Object
Entity Description

name

Name of the bearer

enabled

Indicates if notification will be sent through this bearer or not

recipients

List of recipients to be used with current Bearer (example: msisdns, emails, ip:ports, …​.)

It is possible send notifications via SMS, SNMP and EMAIL

The SMS capability is possible onpremise solution. It is required integration with a external service provider

Reading a Rule Configuration

GET /north/v80/provision/organizations/{organizationName}/channels/{channel_id}/ruleconfigurations

The response JSON includes the syncCache object as showed in next tables:

Table 39. syncCache Parameter
attribute (* required) Description

syncCache

object. Specific parameters for synchronized cache mechanism. See Synchronized Cache Object below

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

You can apply for a rule sending a GET request using the URL above. 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}/channels/{channel_id}/ruleconfigurations

nhe response body could be something like this:

Example 3. Read Rule Configuration object as JSON document
{
    "configurations": [
        {
            "name": "rulename_1",
            "syncCache" : {
                "effectiveDate": "2014-05-28T15:20:51Z"
            },
            "enabled": true,
            "severity": "INFORMATIVE",
            "description": "text",
            "conditions": [
                {
                    "name": "cond1",
                    "delay": 2000,
                    "parameters": [
                        {
                            "name": "threshold",
                            "value": "value1"
                        },
                        {
                            "name": "param2",
                            "value": "value2"
                        }
                    ]
                },
                {
                    "name": "cond2",
                    "delay": 2000,
                    "parameters": [
                        {
                            "name": "threshold",
                            "value": "value1"
                        },
                        {
                            "name": "param2",
                            "value": "value2"
                        }
                    ]
                }
            ],
            "notifications": [
                {
                    "name": "notif1",
                    "enabled": true,
                    "bearers": [
                        {
                            "name": "SMS",
                            "enabled": true,
                            "recipients": [
                                "msisdn1",
                                "msisdn2"
                            ]
                        },
                        {
                            "name": "SNMP",
                            "enabled": true,
                            "recipients": [
                                "ip:port",
                                "ip:port"
                            ]
                        }
                    ]
                },
                {
                    "name": "notif2",
                    "enabled": true,
                    "bearers": [
                        {
                            "name": "SMS",
                            "enabled": true,
                            "recipients": [
                                "msisdn1",
                                "msisdn2"
                            ]
                        }
                    ]
                }
            ],
            "open": false,
            "groupParent": false,
            "groupRule": "containsPresence",
            "close": "noPresence",
        },
        {
            "name": "rulename_2",
            "enabled": true,
            "severity": "CRITICAL",
            "description": "text",
            "conditions": [
                {
                    "name": "cond1",
                    "delay": 2000,
                    "parameters": [
                        {
                            "name": "threshold",
                            "value": "value1"
                        },
                        {
                            "name": "param2",
                            "value": "value2"
                        }
                    ]
                },
                {
                    "name": "cond2",
                    "delay": 2000,
                    "parameters": [
                        {
                            "name": "threshold",
                            "value": "value1"
                        },
                        {
                            "name": "param2",
                            "value": "value2"
                        }
                    ]
                }
            ],
            "notifications": [
                {
                    "name": "notif1",
                    "enabled": true,
                    "bearers": [
                        {
                            "name": "SMS",
                            "enabled": true,
                            "recipients": [
                                "msisdn1",
                                "msisdn2"
                            ]
                        },
                        {
                            "name": "SNMP",
                            "enabled": true,
                            "recipients": [
                                "ip:port",
                                "ip:port"
                            ]
                        }
                    ]
                },
                {
                    "name": "notif2",
                    "enabled": true,
                    "bearers": [
                        {
                            "name": "SMS",
                            "enabled": true,
                            "recipients": [
                                "msisdn1",
                                "msisdn2"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Configuring a Rule to a specified Channel

PUT /north/v80/provision/organizations/{organizationName}/channels/{channel_id}/ruleconfigurations?syncCache&effectiveDate={effectiveDate}

You can update a rule configuration by sending a PUT request using the URL above. In one shot you can modify the configuration of all per organization alarm rules to the same channel. This is the request using curl:

Rule Configuration 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

Is not necessary to include all the fields in the request, only the fields that you want to change, but you must be careful with conditions and notifications if you want to change or include a new condition or notification you must introduce all the section

The configuring must take into account:

  • To activate notifications, the original rule must be have notifications.

  • The rule to close, it must have configured an open rule.

curl --request PUT \
     --data-binary @tag.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/channels/{channel_id}/ruleconfigurations \
     -H "Content-type: application/json"

An example could be something like this

{
    "configurations": [
        {
            "name": "rulename_1",
            "enabled": true,
            "severity": "INFORMATIVE",
            "description": "text",
            "conditions": [
                {
                    "name": "cond1",
                    "delay": 2000,
                    "parameters": [
                        {
                            "name": "threshold",
                            "value": "value1"
                        },
                        {
                            "name": "param2",
                            "value": "value2"
                        }
                    ]
                },
                {
                    "name": "cond2",
                    "delay": 2000,
                    "parameters": [
                        {
                            "name": "threshold",
                            "value": "value1"
                        },
                        {
                            "name": "param2",
                            "value": "value2"
                        }
                    ]
                }
            ],
            "notifications": [
                {
                    "name": "notif1",
                    "enabled": true,
                    "bearers": [
                        {
                            "name": "SMS",
                            "enabled": true,
                            "recipients": [
                                "msisdn1",
                                "msisdn2"
                            ]
                        },
                        {
                            "name": "SNMP",
                            "enabled": true,
                            "recipients": [
                                "ip:port",
                                "ip:port"
                            ]
                        }
                    ]
                },
                {
                    "name": "notif2",
                    "enabled": true,
                    "bearers": [
                        {
                            "name": "SMS",
                            "enabled": true,
                            "recipients": [
                                "msisdn1",
                                "msisdn2"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Cloning a Rule

A rule must be cloned if it is wanted to modify. This cloning must take into account:

  • The name of the cloned rule must not exist in the organization/channel.

  • It is not possible to clone rules associated to other rules.

POST http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/channels/{channel_id}/ruleconfigurations/{rule_id}/clone

The default automation rules can be cloned by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.

clone rule as JSON object
{
  "name": "batteryThreshold_cloned",
  "actions": {
    "open": true,
    "close": "nombre_regla_a_cerrar",
    "notification": 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/battery_organization/channels/batery_channel/ruleconfigurations/batteryThreshold/clone \
     -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 cloned rule. Let’s look the response.

HTTP/1.1 201 Created
Location: http://[your_opengate_address]/north/v80/provision/organizations/battery_organization/channels/battery_channel/ruleconfigurations/batteryThreshold_cloned

Deleting a cloned rule

DELETE http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/channels/{channel_id}/ruleconfigurations/{rule_id}

You can delete only cloned rules by sending a DELETE request using the URL above. You must replace {rule_id} with the identifier of the cloned rule you want to delete. Also, you must replace {organization_name} with the identifier of the cloned rule organization and {channel_name} with the name of the cloned rule channel. 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/ruleconfigurations/batteryThreshold_cloned

Only It can be deleted the cloned rules

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 41. Bulk Object
Object / attribute Description

entities[]

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

Table 42. JSON Entity Response Object
Object / attribute Description
Table 43. 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 44. 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 45. 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": []
    }
  }
]

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 46. 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 4. 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 5. 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 6. 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 47. 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 48. 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 49. 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 7. 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 8. DeploymentElement.json Uninstall example
{
    "deploymentElement": {
        "name": "bundle_1-file_1",
        "version": "1-SNAPSHOT",
        "type": "SOFTWARE",
        "path": "./",
        "order": "2",
        "operation": "UNINSTALL",
        "option": "MANDATORY"
    }
}
Example 9. 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 10. 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 11. 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 50. 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 51. 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 52. 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 53. 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 54. Certificate Public Key Field object attributes
Attribute Description

algorithm

string

size

number

format

string

Supported File Types

Table 55. 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 56. 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

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 57. 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:

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

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"

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 58. 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 59. 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 60. 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 12. 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 13. 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 61. 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 62. 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 63. 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 14. 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 15. 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 64. 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 65. 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 66. 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

  • A set of default rules of alarms

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 67. 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 68. 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 16. 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 17. 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

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

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

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 71. 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 72. 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 73. 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 74. 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 75. 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 76. 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 77. Tag Operation Respo4nse Result Error Object
attribute (* required) Description

notExist

see error summary below

Table 78. 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 79. 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 18. 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 19. 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 20. 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 21. 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 22. 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 23. 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 24. 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 80. Tag entities list Object
Attributes Constraints Description

page

See Page Object

Paging fields

entities[]

array of string

List of entities in the tag

Example 25. 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 26. 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 81. 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

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 82. 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 83. 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 27. 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 28. 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 84. 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 29. 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 30. 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 31. 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 85. Inventory of Entities
Entity Type Search Service

Assets

See Assets Search

Devices

See Devices Search

Subscriptions

See Subscriptions Search

Subscribers

See Subscribers Search

Table 86. Operations on Entities
Querying over URI

Operations

See Operations Search

Table 87. Jobs Resources
Querying over URI

Jobs

See Jobs Search

Table 88. Alarms raised on Entities
Querying over URI

Alarms

See Alarms Search

Table 89. Hardware Resources
Querying over URI

Hardware

See Manufacturer & Models Search

Table 90. Software Resources
Querying over URI

Software

See Software Search

Table 91. Operation Types
Querying over URI

Operation Types

See Operation Types Search

Table 92. Bundles Resources
Querying over URI

Bundles

See Bundles Search

Table 93. Device Datamodels Resources
Querying over URI

Datamodels

See Datamodels Search

Table 94. Certificates Resources
Querying over URI

Certificates

See Certificates Search

Table 95. Plans Resources
Querying over URI

Plan

See Plans Search

Table 96. 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 32. 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 33. 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 97. Pagine JSON object
Parameter Description

limit

See Limit Object

Table 98. 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 99. 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 100. Filter JSON object
Parameter Description

filter

See Operator Object

Filtering operators

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

Table 101. Comparison operators supported by search API
Operation Description

eq

Equals

neq

Not equals

like

like

gt

Greater than

lt

Lower than

gte

Greater than or equals

lte

Lower than or equals

in[]

Included in a concrete group

Table 102. Logical operators supported by search API
Operation Description

and[]

And

or[]

Or

not

Not

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": "ACTIVE"
        }
      },
      {
        "like": {
          "provision.device.communicationModules[].mobile.imei": "commsMod_battery_imei"
        }
      }
    ]
  }
}

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 34. searching basic operators
{
    "filter": {
        "and": [
            {
               "not": {
                  "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": {
        "equals": {
            "device.communicationModules[].mobile.imei": "351873000102290"
        }
    }
}
Example 35. searching using "in" operator like aggregation of id’s
{
    "filter": {
        "in": {
            "device.name": [
                "device_1",
                "device_2"
            ]
        }
    },
    "limit": {
        "start": 26,
        "size": 50
    }
}
Example 36. searching using a tag
{
    "filter": {
       "eq": {
            "tag": "my_sticky_tag"
        }
    },
    "limit": {
        "start": 26,
        "size": 50
     }
}
Example 37. searching for hardware fields
{
    "filter": {
        "and": [
           {
               "like": {
                    "device.model": "EF5"
                }
            }
        ]
    },
    "limit": {
        "start": 1,
        "size": 10
    }
}
Example 38. searching for software fields
{
    "filter": {
        "and": [
            {
                "like": {
                    "device.software": "1.0"
                }
            }
        ]
    },
    "limit": {
        "start": 1,
        "size": 10
    }
}

Searchs the devices whose software have this chain

Example 39. 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 40. searching for device alarms, /north/v80/search/entities/devices/alarms
{
    "filter": {
        "in": {
            "device.name": [
                "DEVICE22"
            ]
        }
    },
   "limit":{
      "start":1,
      "size":10
   }
}
Example 41. 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 103. SQL to JSON queries mapping chart
SQL OpenGate search API JSON queries
SELECT * FROM device WHERE serialNumber <> '82A75D494B0EBF7A95587285AE78E83F'

/north/v80/search/devices

{
    "filter": {
        "and": [
            {
                "not": {
                    "eq": {
                        "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": "123456786543210"
                }
            }
        ]
    },
    "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 104. 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 105. 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 42. 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 only a subset of the fields included in the searched object (i.e: device), the JSON select object can be included in the search request, see Select Object.

This clause must be included when 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

As described above, any parameter of the list included in the device Default Datamodels can be used as select fields, including the custom datastreams.

The order to apply the filters is securization, resourceType if it has, sort, filter and finally selecting (the fields to show)

Select JSON object

Table 106. Search Select Object
Entity Description

select[]

Array of parameters to be selected. See Select Parameter Object

Table 107. Search Select Object
Entity Description

name

String. Name of the parameter in the datamodels (See Default Datamodels)

fields[](optional)

Array of Strings with the name of the fields to be retrieved when a CSV format is required. In JSON format all the fields are retrieved. The possible values are:

* "value"

* "updated": Date when value was updated

* "performance": Performance of the value following qrate configuration of the parameter

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.

  • The select clause only can be used for entity searching.

  • 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

  • The atribute select must not be empty

  • The different fields must be in Default Datamodels

  • By default, in the response is shown the organization, channel and identifier of entity.

  • It is possible to do the select whatever final value:

    • value

    • date

    • at

    • from

    • tags

    • feedId

    • scoring.performance

    • scoring.qrating

    • provType

  • If the field is not exist, it will not show nothing inside it

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 108. 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 109. Summarized Specific Object structure
Entity Constraint

SpecificObjectParameterDatamodel

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

Table 110. Summarized Element structure
Entity Constraint

count

number of these specific elements found

list

Array of each type of Summarized Element List

Table 111. 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 112. Group JSON object
Parameter Description

parameters[]

Array of grouping parameters, see group parameter object

Table 113. 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 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 subscribers

/north/v80/search/entities/subscribers/alarms

Currently performed summary of alarms on the subscribers

/north/v80/search/entities/subscribers/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 114. 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 115. Entity alarms Search: 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 116. 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 117. 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 118. Filter fields for searching raised alarms
Field name field name in where clause type

alarmId

alarm.id

string

rule

alarm.ruleName

string

name

alarm.name

string

severity

alarm.severity

string

status

alarm.status

string

priority

alarm.priority

string

source

alarm.source

string

openDate

alarm.openDate

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

organization

alarm.organization

string

channel

alarm.channel

string

specificType

alarm.specificType

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 119. Entities with alarms. Response structure
Entity Constraint

page

See page object

summary

See summary object in this section

alarms[]

See Alarm Object bellow

Table 120. Alarm Object
Entity Constraint Description

id

UUID format. string

Unique identification of the alarm instance

entityType

string

entityId

string

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

source

String enumeration with the next values:

  • ENGINE

  • DEVICE

Origin of the alarm

rule

string

Rule name

name

string

Alarm type name

description

string

Alarm description

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 checked 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

organization

string

Organization name

channel

string

Channel name

specificType

string

Alarm specific type

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": [
    {
      "id": "50dca9ab-f552-4805-9cff-019090d5b92b",
      "entityId": "device_1",
      "entityType": "DEVICE",
      "severity": "CRITICAL",
      "status": "CLOSED",
      "priority": "HIGH",
      "source": "ENGINE",
      "rule": "rulename_1",
      "name": "alarmname_1",
      "description": "alarm description",
      "openingDate": "2017-12-11T10:10:00Z",
      "attentionDate": "2017-12-11T10:10:00Z",
      "attentionUser": "user@user.es",
      "attentionNote": "notes",
      "closureDate": "2017-12-11T10:10:00Z",
      "closureUser": "user@user.es",
      "closureNote": "notes",
      "channel": "battery_channel",
      "organization": "battery_organization",
      "specificType": "MODEM"
    },
    {
      "id": "50dca9ab-f552-4805-9cff-84765432b92c",
      "entityId": "device_2",
      "entityType": "DEVICE",
      "severity": "CRITICAL",
      "status": "CLOSED",
      "priority": "HIGH",
      "source": "ENGINE",
      "rule": "rulename_2",
      "name": "alarmname_2",
      "description": "alarm description",
      "openingDate": "2017-12-11T10:10:00Z",
      "attentionDate": "2017-12-11T10:10:00Z",
      "attentionUser": "user@user.es",
      "attentionNote": "notes",
      "closureDate": "2017-12-11T10:10:00Z",
      "closureUser": "user@user.es",
      "closureNote": "notes",
      "channel": "battery_channel",
      "organization": "battery_organization",
      "specificType": "MODEM"
    }
  ]
}

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 43. Searching summary of device alarms
{
  "summary": {
    "count": 30,
    "status": {
      "count": 30,
      "list": [
        {
          "count": 20,
          "name": "OPEN"
        },
        {
          "count": 10,
          "name": "ATTENDED"
        }
      ]
    },
    "severity": {
      "count": 30,
      "list": [
        {
          "count": 10,
          "name": "INFORMATIVE"
        },
        {
          "count": 10,
          "name": "CRITICAL"
        },
        {
          "count": 10,
          "name": "URGENT"
        }
      ]
    },
    "rule": {
      "count": 30,
      "list": [
        {
          "count": 30,
          "name": "rulename_1"
        }
      ]
    }
  }
}

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
id;entityId;entityType;severity;status;priority;source;rule;name;description;openingDate;attentionDate;attentionUser;attentionNote;closureDate;closureUser;closureNote;channel;organization;specificType
50dca9ab-f552-4805-9cff-019090d5b92b;device_1;DEVICE;CRITICAL;CLOSED;HIGH;ENGINE;rulename_1;alarmname_1;alarm description;2017-12-11T10:10:00Z;2017-12-11T10:10:00Z;user@user.es;notes;2017-12-11T10:10:00Z;user@user.es;notes;battery_channel;battery_organization;MODEM
50dca9ab-f552-4805-9cff-019090d5b92c;device_2;DEVICE;CRITICAL;CLOSED;HIGH;ENGINE;rulename_2;alarmname_2;alarm description;2017-12-11T10:10:00Z;2017-12-11T10:10:00Z;user@user.es;notes;2017-12-11T10:10:00Z;user@user.es;notes;battery_channel;battery_organization;MODEM

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 121. 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 <<search_select, 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"}"

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 122. 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 123. 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 124. Bundle. Response structure
Entity Constraint

bundles[]

see Bundle structure below

Table 125. 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 126. 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 44. 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 127. 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 128. 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 129. 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 130. 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 131. 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 45. 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 46. 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 47. 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 132. Datamodel response objects
Attribute Description

page

See page

datamodels[]

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

URL

Table 133. 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 134. 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.cumulativePeriodDivisor

Number

Cumulative period divisor (calculation of the median velocity of collection against the previous value collected 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 48. 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 135. 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 136. Datapoint response objects
Attribute Description

page

See Page Object

datapoints[]

Array of datapoint objects. See Datapoint object definition

Table 137. 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 138. 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 139. 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 140. 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
        },
        "tags": [],
        "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 141. Datastream response objects
Attribute Description

page

See page

datastreams[]

Contains the array of datastreams, see Datastream description

Table 142. Datastream object attributes
Attribute Description

entityIdentifier

Identifier of the entity of any device’s or feed datastream. Example: device_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 143. 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 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 144. 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 145. 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 49. Request JSON
Filter to select a specific datastream
{
    "filter": {
        "eq": {
            "datastreams.datastreamId": "batteryPercentage"
        }
    }
}
Response JSON
{
  "page": {
    "number": 1
  },
  "datastreams": [
    {
      "entityIdentifier": "device_4D2BB5",
      "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": "2018-06-20T11:49:17.890+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": 100
        },
        "tags": [],
        "at": "2018-06-20T11:49:16+02:00"
      }
    }
  ]
}

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 146. 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": "ACTIVE"
        }
      },
      {
        "like": {
          "provision.device.communicationModules[].mobile.imei": "commsMod_battery_imei"
        }
      }
    ]
  }
}

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
Unresolved directive in opengate-api-north-search-devices.adoc - include::json/examples/opengate_api_search_utc_devices_example.json[]

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 147. 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 148. 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 50. 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 51. 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 52. 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 149. 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 150. 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 151. 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 152. URLs
Querying over URI

Feeds Info

POST - /north/v80/search/feeds

URL parameters

Specific Filter Fields

Table 153. 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 53. 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 154. 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