Subsections of provision

Base Provision

This is an abstract class; it must be extended by another class that defines the specific actions of a given provision. This class is responsible for managing requests to OpenGate North API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
resource string ❌ this is a base url resource
timeout number ✅ timeout on request
requiredParameters array ❌
serviceBaseURL string ❌ base of the uri petition

create()

This invoke a request to OpenGate North API and the callback is managed by promises This function creates a provisioned entity

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.organizationsBuilder().create()

delete(body)

This invoke a request to OpenGate North API and the callback is managed by promises This function deletes a provisioned entity

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.organizationsBuilder().withName('delete_organization').delete();
ogapi.usersBuilder().withEmail('delete@user.com').delete();
ogapi.certificatesBuilder().withId('d3l3t3-c3rt1f1c4t3').delete();

update()

This invoke a request to OpenGate North API and the callback is managed by promises This function updates a provisioned entity

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.organizationsBuilder().update()

Subsections of bulk

Bulk Execution Builder

This builder gives you the tools necessary to create bulk executions using the OpenGate REST API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ required field. This is ogapi instance
organization string ❌ required field. This is the organization name
processorId string ❌ required field. This is the provision processor use for bulk provision
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception

bulk(rawFile, extension)

Do a bulk using specific Provision Processor.

Parámetros

Nombre Tipo Opcional Descripción
rawFile `string File` ❌
extension string ✅ File format

Ejemplos

ogapi.bulkExecutionBuilder('orgname', 'processorId', 10000).bulk(rawFile, extension)

plan(rawFile, extension, numberOfEntriesToProcess)

Instead of creating a bulk process, returns the provision process planning for the specified entries. This is a synchronous process that does not cause changes in the database.

Parámetros

Nombre Tipo Opcional Descripción
rawFile `string File` ❌
extension string ✅ File format
numberOfEntriesToProcess number ✅ Number of entries to be processed.

Ejemplos

ogapi.bulkExecutionBuilder('orgname', 'processorId', 10000).plan(rawFile, extension)
 ogapi.bulkExecutionBuilder('orgname', 'processorId', 10000).plan(rawFile, extension, numberOfEntriesToProcess)

Subsections of country

Countries Catalog

This class allows making GET requests to the countries catalog resource in OpenGate North API.

It needs the _internalCountriesFilter client option, and there is no default. It is built that way on purpose: the catalogue is not an endpoint but an asset entity with entityType WIRE and an identifier of the form DOMAIN_<domain>, so the caller has to say which entity to read, the same way it says which api key to use. There is an intention to replace this with a real catalogue endpoint and drop the option again.

new OpenGateAPI({ url, apiKey, _internalCountriesFilter: { organization: ‘myorg’, identifier: ‘DOMAIN_myorg’, ds: ‘provision.administration.countries’ } });

Without it, getCountries() used to die with Cannot read properties of undefined (reading 'organization'), which said nothing about the option that was missing.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ Reference to the API object.

getCountries()

Performs a get that returns countries

Retorna

Tip

Tipo: Promise

Subsections of entities

Asset Builder

Asset builder. This builder gives you the necessary tools to create an asset using the OpenGate REST API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
organization string ❌ this is the organization name where subscription will be created
allowedDatastreams array ✅ Allowed datastreams to add into the new subscription
definedSchemas array ✅ Jsonschema about all OpenGate specific types
jsonSchemaValidator Validator ✅ Json schema validator tool

Bulk Builder

This class provides the bulk create, update, patch, and delete operations shared by the CSV and JSON bulk builders.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ required field. This is ogapi instance
resource resource ❌ required field. This is the resource used for the bulk provision
extension extension ❌ required field. Type of file to send
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception

create(rawFile, csv_response)

Execute the bulk creation operation

Parámetros

Nombre Tipo Opcional Descripción
rawFile `string Blob` ❌
csv_response boolean ✅ true if you want a response on format csv. False or null if you want a response on format json

Ejemplos

ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).create(rawFile)
 ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).create(new Blob(), true)

delete(rawFile, csv_response)

Execute the bulk delete operation

Parámetros

Nombre Tipo Opcional Descripción
rawFile `string Blob` ❌
csv_response boolean ✅ true if you want a response on format csv. False or null if you want a response on format json

Ejemplos

ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).delete(rawFile)
 ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).delete(new Blob(), true)

deleteAll(rawFile, csv_response)

Execute the bulk delete-all operation

Parámetros

Nombre Tipo Opcional Descripción
rawFile `string Blob` ❌
csv_response boolean ✅ true if you want a response on format csv. False or null if you want a response on format json

Ejemplos

ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).deleteAll(rawFile)
 ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).deleteAll(new Blob(), true)

patch(rawFile, csv_response)

Execute the bulk patch operation

Parámetros

Nombre Tipo Opcional Descripción
rawFile `string Blob` ❌
csv_response boolean ✅ true if you want a response on format csv. False or null if you want a response on format json

Ejemplos

ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).update(rawFile)
 ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).update(new Blob(), true)

update(rawFile, csv_response)

Execute the bulk update operation

Parámetros

Nombre Tipo Opcional Descripción
rawFile `string Blob` ❌
csv_response boolean ✅ true if you want a response on format csv. False or null if you want a response on format json

Ejemplos

ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).update(rawFile)
 ogapi.newCsvBulkBuilder('orgname', 'entities', 10000).update(new Blob(), true)

Complex Builder

This class extends SimpleBuilder to allow setting complex values. What is a complex value? It is simply a value that needs a communications module identifier to be set into the box.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
resource string ❌ this is the resource url where can be create/delete/update/read the entity
allowedDatastreams array ✅ Allowed datastreams to add into the new entity
definedSchemas array ✅ Jsonschema about all OpenGate specific types
jsonSchemaValidator Validator ✅ Json schema validator tool

withComplex(_id, idCommunicationModules, val)

Set a complex value to entity

Parámetros

Nombre Tipo Opcional Descripción
_id string ❌ Datastream identifier
idCommunicationModules string ❌ Communications module identifier
val object ❌ Value to set.

Csv Bulk Builder

CSV builder. This builder gives you the necessary tools to run a CSV bulk provisioning operation using the OpenGate REST API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ required field. This is ogapi instance
organization string ❌ required field. This is the organization name where entities will be created, updated or deleted
resource resource ❌ required field. This is the resource used for the bulk provision
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception
async boolean ✅ forces async execution for the bulk operation

Device Builder

Device builder. This builder gives you the necessary tools to create a device using the OpenGate REST API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
organization string ❌ this is the organization name where device will be created
allowedDatastreams array ✅ Allowed datastreams to add into the new device
definedSchemas array ✅ Jsonschema about all OpenGate specific types
jsonSchemaValidator Validator ✅ Json schema validator tool
ms number ❌ timeout in milliseconds

create()

This invoke a request to OpenGate North API and the callback is managed by promises This function creates a provisioned entity

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.organizationsBuilder().create()

update()

This invoke a request to OpenGate North API and the callback is managed by promises This function updates a provisioned entity and checks whether any subscriber/subscription already exists. If a subscriber/subscription does not exist, it will be created and then added to the entity box.

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.entityBuilder.devicesBuilder().update()

Entity Builder

This is a base object that gives you access to everything you can do to provision entities.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ Reference to the API object.

assetsBuilder(organization, timeout)

Get an AssetBuilder to operate with entities of type asset

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field
timeout number ✅ timeout on request

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.assetsBuilder('orgname').then(function(assetBuilder){//...}).catch()

devicesBuilder(organization, timeout)

Get a DeviceBuilder to operate with entities of type device.

It resolves a builder rather than returning one, because the allowed datastreams and their schemas are read from the platform first. Note that `with()` ignores a datastream the organization does not allow, warning rather than throwing, so a typo in a datastream name produces an entity missing that value rather than an error.

A device that the platform will accept needs more than an identifier. This is a create that works, and every line of it was needed:

```js const builder = await ogapi.entityBuilder.devicesBuilder('sensehat'); await builder .with('provision.device.identifier', 'my-device') // the entity key .with('provision.administration.identifier', 'my-device') .with('provision.administration.organization', 'sensehat') .with('provision.administration.channel', 'default_channel') .with('provision.administration.plan', 'dev__100_per_day') .with('provision.administration.serviceGroup', 'emptyServiceGroup_onSession') .create(); ```

The platform rejects an omission one field at a time, so finding this set means a round trip per missing field:

  • without `plan`: 400 `0x010E10`, "Device plan is mandatory…"
  • without `serviceGroup`: 400 `0x010000`, "Required field."

These are not validated here on purpose. The plan message ties the requirement to the state of the organization, so a client-side rule would refuse calls that other organizations accept. `provision.device.identifier` is different: it is the entity key, and its absence is refused locally with `OGAPI_ENTITY_KEY_REQUIRED`.

List the plans an organization actually has with `ogapi.newDevicePlansFinder().findByOrganization(organization)`.

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field
timeout number ✅ timeout on request

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.entityBuilder.devicesBuilder('orgname').then(function(deviceBuilder){//...}).catch()

newCsvBulkBuilder(organization, resource, timeout, async)

Get a new CsvBulkBuilder

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field.
resource string ❌ required field. Type of resource: entities or tickets
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception
async boolean ✅ forces async execution for the bulk operation

Retorna

Tip

Tipo: CsvBulkBuilder

Ejemplos

ogapi.newCsvBulkBuilder('orgname', 'entities', 10000, false)
 ogapi.newCsvBulkBuilder('orgname', 'entities', 10000, true)

newJsonBulkBuilder(organization, resource, timeout, async)

Get a new JsonBulkBuilder

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field.
resource string ❌ required field. Type of resource: entities or tickets
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception
async boolean ✅ forces async execution for the bulk operation

Retorna

Tip

Tipo: JsonBulkBuilder

Ejemplos

ogapi.newJsonBulkBuilder('orgname', 'entities', 10000)

newJsonFlattenedBulkBuilder(organization, resource, timeout, async)

Get a new JsonFlattenedBulkBuilder

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field.
resource string ❌ required field. Type of resource: entities or tickets
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception
async boolean ✅ forces async execution for the bulk operation

Retorna

Tip

Tipo: JsonFlattenedBulkBuilder

Ejemplos

ogapi.newJsonFlattenedBulkBuilder('orgname', 'entities', 10000)

subscribersBuilder(organization, timeout)

Get a SubscriberBuilder to operate with entities of type subscriber

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field
timeout number ✅ timeout on request

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.subscribersBuilder('orgname').then(function(subscriberBuilder){//...}).catch()

subscriptionsBuilder(organization, timeout)

Get a SubscriptionBuilder to operate with entities of type subscription

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field
timeout number ✅ timeout on request

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.subscriptionsBuilder('orgname').then(function(subscriptionBuilder){//...}).catch()

ticketsBuilder(organization, timeout)

Get a TicketBuilder to operate with entities of type ticket

Parámetros

Nombre Tipo Opcional Descripción
organization string ❌ required field
timeout number ✅ timeout on request

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.ticketsBuilder('orgname').then(function(ticketBuilder){//...}).catch()

Json Bulk Builder

JSON builder. This builder gives you the necessary tools to run a JSON bulk provisioning operation using the OpenGate REST API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ required field. This is ogapi instance
organization string ❌ required field. This is the organization name where entities will be created, updated or deleted
resource resource ❌ required field. This is the resource used for the bulk provision
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception
async boolean ✅ forces async execution for the bulk operation

Json Flattened Bulk Builder

JSON flattened builder. This builder gives you the necessary tools to run a flattened-JSON bulk provisioning operation using the OpenGate REST API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ required field. This is ogapi instance
organization string ❌ required field. This is the organization name where entities will be created, updated or deleted
resource resource ❌ required field. This is the resource used for the bulk provision
timeout number ✅ timeout in millisecons. The request will have a specific time out if it will be exceeded then the promise throw an exception
async boolean ✅ forces async execution for the bulk operation

Simple Builder

This class allows setting simple values.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
resource string ❌ this is the resource url where can be create/delete/update/read the entity
allowedDatastreams array ✅ Allowed datastreams to add into the new entity
definedSchemas array ✅ Jsonschema about all OpenGate specific types
jsonSchemaValidator Validator ✅ Json schema validator tool

deleteAll()

This invoke a request to OpenGate North API and the callback is managed by promises This function deletes a provisioned entity

Retorna

Tip

Tipo: Promise

getAllowedDatastreams()

Retorna

Tip

Tipo: array

  • Allowed Datastream definition array

getEntityKey()

Retorna

Tip

Tipo: string

  • Entity identifier

patch()

This invoke a request to OpenGate North API and the callback is managed by promises This function patches a provisioned entity

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.organizationsBuilder().update()

update()

This invoke a request to OpenGate North API and the callback is managed by promises This function updates a provisioned entity

Retorna

Tip

Tipo: Promise

Ejemplos

ogapi.organizationsBuilder().update()

with(_id, val)

Set new datastream value

Parámetros

Nombre Tipo Opcional Descripción
_id string ❌ Datastream identifier
val objecr ❌ Datastream value. If this value is null then datastream value will be removed.

Subscriber Builder

Subscriber builder. This builder give you the necessary tools to create a subscriber using our OpenGate REST.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
organization string ❌ this is the organization name where subscriber will be created
allowedDatastreams array ✅ Allowed datastreams to add into the new subscriber
definedSchemas array ✅ Jsonschema about all OpenGate specific types
jsonSchemaValidator Validator ✅ Json schema validator tool

Subscription Builder

Subscription builder. This builder give you the necessary tools to create a subscription using our OpenGate REST.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
organization string ❌ this is the organization name where subscription will be created
allowedDatastreams array ✅ Allowed datastreams to add into the new subscription
definedSchemas array ✅ Jsonschema about all OpenGate specific types
jsonSchemaValidator Validator ✅ Json schema validator tool

Ticket Builder

Ticket builder. This builder gives you the necessary tools to create a ticket using the OpenGate REST API.

constructor

Constructor

Parámetros

Nombre Tipo Opcional Descripción
ogapi InternalOpenGateAPI ❌ this is ogapi instance
organization string ❌ this is the organization name where subscription will be created
allowedDatastreams array ✅ Allowed datastreams to add into the new subscription
definedSchemas array ✅ Jsonschema about all OpenGate specific types
jsonSchemaValidator Validator ✅ Json schema validator tool