Connector functions - Provision JS API guide

This API allows users to manage entity provisioning (creation and retrieval) from a connector function.

provision – Main Object

The provision global object provides properties and methods to interact with the Provisioning API.

provision – Object Properties

Property Type Default Description
apiKey string If available, current connection’s apikey API Key for the request.
host string Frontend’s default endpoint Host for the Provisioning API.
identifier string null Identifier of the entity to act upon.
organization string Device`s organization Organization to which the entity belongs.
serviceGroup string "emptyServiceGroup" Service Group for the entity.
defaultChannel string "defaultChannel" Channel to which the entity belongs.
plan string null Provisioning plan to apply.
extraDatastreams Array [] Extra data as an array of objects like {datastreamId:value} pairs.

provision – Functions

provision.get(id)

Retrieves an existing entity from the database with specified identifier.

Kind: global function
Returns: Object - If entity is found, entity data will be returned in result. If it is not found, result field will be null. If some error happened, it will be returned in error field.

Param Type Default Description
id string this.identifier (Optional) Entity identifier. If not defined identifier field will be used.

Example with provision.identifier:

provision.identifier = "device_123";
const resp = provision.get();
if (!resp.error && resp.result) {
    logger.info("Entity identifier:", resp.result._value("provision.administration.identifier"));
}

Example with parameter:

const resp = provision.get("device_123");
if (!resp.error && resp.result) {
    logger.info("Entity identifier:", resp.result._value("provision.administration.identifier"));
}

Example with unexepected error:

const resp = provision.get("device_123");
if (resp.error) {
    logger.error("Some error:", resp.error);
}

The object resp.result contains then same functions than entity object.

provision.create(fullBody)

Creates a new entity in the platform.

Kind: global function

Param Type Description
fullBody Object (Optional) Complete JSON body for the creation request. If not provided, it is generated from the object properties.

Returns: Object - An object containing either result (201 status) or error.

Example using properties:

provision.identifier = "new_device_001";
provision.plan = "TEST_PLAN";
provision.extraDatastreams = [{ "provision.device.name": "cellName" }, { "provision.device.administrativeState": "ACTIVE" }, { "provision.device.specificType": "COMHUB" }, { "provision.tec": "NBIoT Cell" }];
const resp = provision.create();
if(!resp.error && resp.result == 201) {
    logger.info('Created');
} else {
    logger.error('Error creating entity:', resp.error);
}

Previous example will create with following body:

{
    "provision.administration.channel": {
        "_value": {
            "_current": {
                "value": "defaultChannel"
            }
        }
    },
    "provision.administration.identifier": {
        "_value": {
            "_current": {
                "value": "new_device_001"
            }
        }
    },
    "provision.administration.organization": {
        "_value": {
            "_current": {
                "value": "deviceOrg"
            }
        }
    },
    "provision.administration.serviceGroup": {
        "_value": {
            "_current": {
                "value": "emptyServiceGroup"
            }
        }
    },
    "provision.administration.plan": {
        "_value": {
            "_current": {
                "value": "TEST_PLAN"
            }
        }
    },
    "provision.device.name": {
        "_value": {
            "_current": {
                "value": "cellName"
            }
        }
    },
    "provision.device.administrativeState": {
        "_value": {
            "_current": {
                "value": "ACTIVE"
            }
        }
    },
    "provision.device.specificType": {
        "_value": {
            "_current": {
                "value": "COMHUB"
            }
        }
    },
    "provision.tec": {
        "_value": {
            "_current": {
                "value": "NBIoT Cell"
            }
        }
    }
}

If fullBody is provided, it will be used as the request body instead of building it from the object properties.

Example:

const body = {
    "provision.administration.channel": {
        "_value": {
            "_current": {
                "value": "defaultChannel"
            }
        }
    },
    "provision.administration.identifier": {
        "_value": {
            "_current": {
                "value": "new_device_001"
            }
        }
    },
    "provision.administration.organization": {
        "_value": {
            "_current": {
                "value": "deviceOrg"
            }
        }
    },
    "provision.administration.serviceGroup": {
        "_value": {
            "_current": {
                "value": "emptyServiceGroup"
            }
        }
    }
};
const resp = provision.create(body);
if(!resp.error && resp.result == 201) {
    logger.info('Created');
} else {
    logger.error('Error creating entity:', resp.error);
}