Introduction to provision processors

This API’s purpose is to facilitate the development of Provision Processors in the simplest possible way.

The API is divided into several modules/scripts:

• Provision_Processor / provision_processor.js: This is the entry point from Java. It defines a template for Provision Processor execution.
• Entities_Utils / provision_entity_utils.js: Utility class to facilitate the entities building.
• Action_Utils / provision_actions_utils.js: Utility functions to create the actions to be returned to Java process.
• V8_Api / provision_JavaV8_api.js: Functions used to invoke Java V8 methods.
• V8_Utils / provision_JavaV8_utils.js: Some generic functions to use V8_API. When developing a new Provision Processor, instead of calling directly V8_Api functions is better to use the methods defined here.
• Error_Api: Facility class to manage and transform caught OpenGate provision error.

Provision Processor

One Provision Processor is a script that, using Provision Javascript API, implements the business logic to transform inbound data into several actions to be done by Java to do correct provisioning actions.

How to Implement Provision Processor

When implementing a Provision Processor it is mandatory to implement two specific functions. These functions are called from Provision_Processor.processRow function:

• normalizeRowMap(rawObject): This function receives a map with the data to be processed. For example, a map with the data read from an excel file. It takes the inbound parameter and transforms it into an object to be used to calculate and build the actions for this row. In this function, values validation and transformation should be done.
  • Input parameter: JSON object with raw keys and values.
  • Output: JSON object with the desired structure.
• actionsPlanning(normalizedObject): Takes the result from normalizeRowMap function and calculates the actions to be done in Java.
  • Input parameter: Normalized object.
  • Output: Array of Actions.

It is possible to define extra functions to manage and transform provision errors. This function will be called from Main_Module.transformErrorMessage:

• customErrorTransformer(errorManager): This function will be called when some provision error is caught (for example: duplicated entity). The goal is to create a customized error message for the Excel row update. This function is not mandatory, and if it is not defined, a default message will be returned by Main_Module.transformErrorMessage.
  • Input parameter: Object with error information (caught exception, failed action specification, and default message) and useful methods to manage this information.
  • Output: This function must return a String with the customized message.

Example of Provision Processor for creating devices and assets with some fields. It uses the functions and classes defined in Provision Javascript API.

   /* *******************
      MANDATORY FUNCTIONS 
      ******************* */

   function normalizeRawObject(rawObject) {

      try {
         var normalizedObject = {
            /* 
            In this case, raw object data comes from an excel
            and to specify the full key, we use the header name and column letter
            */
            organization: readMapValue(rawObject, 'Organization', '', 'A'),
            channel: readMapValue(rawObject, 'Channel Name', '', 'B'),

            /* maybe some values can be defined in the script as constants */
            service_group: 'emptyServiceGroup',

            /* We can do values validation and transformations. For example remove blanks from the value. */
            device_identifier: readMapValue(rawObject, 'Serial number', '', 'D').replace(/\s/g, ''),
            asset_identifier: readMapValue(rawObject, 'Asset Id', '', 'C').replace(/\s/g, '')
         };
         return normalizedObject;
      } catch (e) {
         printLog('>> normalizeRawObject(): exception: ' + e);
         throw e;
      }
   }


   function actionsPlanning(normalizedObject) {
      var actions = [];

      /* 
         In this case, we will create an asset and a device. 
         In the case of the device, if it exists, we are going to update it.
      */

      /* we check if the asset exists before creating it. */
      var assetExist = checkAsset(normalizedObject.asset_identifier);
      if(!assetExist){
         var assetEntity = generateAssetEntity(normalizedObject)
         actions.push(CREATE_ASSET_ACTION(assetEntity));
      }

      /* we check if the device exists. */
      var deviceExist = checkDevice(normalizedObject.device_identifier);
      var deviceEntity = generateDeviceEntity(normalizedObject)
      if(!deviceExist){
         actions.push(CREATE_DEVICE_ACTION(deviceEntity));
      }else{
         actions.push(UPDATE_DEVICE_ACTION(deviceEntity));
      }

      return actions;
   }


   /* ******************************************
      OPTIONAL FUNCTION for error transformation 
      ****************************************** */

   /* This function will be called when a provision exception is caught to get a customized message for excel row update */

   function customErrorTransformer(errorManager) {
      return 'This is customized message for error code: ' + errorManager.getFirstErrorCode() + ' and message: ' + errorManager.getFirstErrorMessage();
   }



   /* *************************
      Other auxiliary functions 
      ************************* */

   function generateDeviceEntity(normalizedObject) {
      try {
         var deviceEntity = new Entity()
               .addDatastream('provision.administration.channel', normalizedObject.channel)
               .addDatastream('provision.administration.serviceGroup', normalizedObject.service_group)
               .addDatastream('provision.administration.organization', normalizedObject.organization)
               .addDatastream('provision.administration.identifier', normalizedObject.device_identifier)
               .addDatastream('provision.device.related', normalizedObject.asset_identifier);

         return deviceEntity.entityJson;
      } catch (e) {
         printLog('>> generateDeviceEntity: Exception: ' + e);
         throw e;
      }
   }



   function generateAssetEntity(normalizedObject) {
      try {
         var assetEntity = new Entity()
               .addDatastream('resourceType', 'entity.asset')
               .addDatastream('provision.administration.channel', normalizedObject.channel)
               .addDatastream('provision.administration.serviceGroup', normalizedObject.service_group)
               .addDatastream('provision.administration.organization', normalizedObject.organization)
               .addDatastream('provision.administration.identifier', normalizedObject.asset_identifier);
         return assetEntity.entityJson;
      } catch (e) {
         printLog('>> generateAssetEntity: Exception: ' + e);
         throw e;
      }

   }

Important tips when writing a Provision Processor script

To add the script to Provision Processor JSON, it is necessary to take into these rules:

• For strings, use single quotes (’) instead of double quotes (")
• Use block comments (/**/) instead of line comments (//)
• Format the script in a unique line script.

Action format

actionsPlanning returns an array of objects specifying the action to be done. Actions must be built with the functions defined in Action_Utils. Just to see the output format and following the previous example:

[
   {
      "action": "POST",
      "resourceType": "entity.asset",
      "actionDescription": "Create Asset",
      "json": {
         "resourceType": {
            "_value": {
               "_current": {
               "value": "entity.asset"
               }
            }
         },
         "provision.administration.channel": {
            "_value": {
               "_current": {
               "value": "some_channel"
               }
            }
         },
         "provision.administration.serviceGroup": {
            "_value": {
               "_current": {
               "value": "some_service_group"
               }
            }
         },
         "provision.administration.organization": {
            "_value": {
               "_current": {
               "value": "some_organization"
               }
            }
         },
         "provision.asset.identifier": {
            "_value": {
               "_current": {
               "value": "some_asset_identifier"
               }
            }
         }
      },
      "full": false
   },
   {
      "action": "POST",
      "entityType": "device",
      "actionDescription": "Create Device without Subscription",
      "json": {
         "resourceType": {
            "_value": {
               "_current": {
               "value": "entity.device"
               }
            }
         },
         "provision.administration.organization": {
            "_value": {
               "_current": {
               "value": "some_organization"
               }
            }
         },
         "provision.administration.channel": {
            "_value": {
               "_current": {
               "value": "some_channel"
               }
            }
         },
         "provision.administration.serviceGroup": {
            "_value": {
               "_current": {
               "value": "some_service_group"
               }
            }
         },
         "provision.device.identifier": {
            "_value": {
               "_current": {
               "value": "some_device_identifier"
               }
            }
         },
         "provision.device.related": {
            "_value": {
               "_current": {
               "value": "some_asset_identifier"
               }
            }
         }
      },
      "full": false
   }
]

Error management

Sometimes, it could be necessary to stop processing and abort all provision processes. For example, because some validation is not passed. In that case, an error must be thrown with a descriptive message. For example:

function actionsPlanning(normalizedObject) {
   var actions = [];

   ...

   if(! someValidation(normalizedObject)){
      throw new Error("Provision Processor Error: some validation not passed");
   }

   ...

   return actions;
}

Main Module

Main Script: Defines Provision Processor template to be called from Java

• Main Module
  • ~globalParams
  • ~processRow(rawObject, processorParamsMap)
  • ~_testTemplateImplementation()

Main_Module~globalParams

Global parameter with a received map of params from the java process. This parameter is set at the beginning of processRow and it can be used in any function in the script.

Kind: inner property of Main_Module

Main_Module~processRow(rawObject, processorParamsMap)

This is the function that will be called from the Java process.

To work correctly this function, it is mandatory to implement in the provision processor script the following functions:

• normalizeRowMap(rawObject): This function will read and transform inbound rawObject and transform to normalizedObject object that will be used in actionsPlanning() function.
• actionsPlanning(normalizedObject): This function has to apply business rules and calculate the actions array to be done by the Java process.

Kind: inner method of Main_Module
Returns: String - Json with following properties:

• scriptDirectResult: OK or descriptive error text,
• actionsToDo: Array with the list of Actions to be done in Java Process. This array can be empty.

Return Example

   {
      "scriptDirectResult": "OK",
      "actionsToDo":[
            {
               "action": "POST",
               "json": {...},
               "actionDescription": "Create Asset",
               "full": false,
               "resourceType": "entity.asset"
            },
            {
               "action": "PUT",
               "json": {...},
               "actionDescription": "Update Device",
               "full": false,
               "resourceType": "entity.device"
            }   
      ]
   }

Main_Module~_testTemplateImplementation()

Auxiliary function to check if main functions are implemented.

Kind: inner method of Main_Module
Throws:

• Error if the main methods (normalizeRawObject and actionsPlanning) are not correctly defined as functions

Entities_Utils

This module contains Entity class specifications and other useful functions to convert processor script inbound data to ODM Entities.

• readMapValue is the method to read values from inbound data.

• newEntityBuilder is the method to create a new Entity Builder from an existing Entity JSON.

• Entity class: Entity class definition. Used to build Entity Jsons.

• Entities_Utils

  • Entity
  • readMapValue(map, headerName, defaultValue, headerColumn)
  • newEntityBuilder(fromEntityJson)

Entity

Class used to build Entity Jsons. It contains the necessary properties and methods to build any entity JSON.

• entityJson: this property contains the Entity JSON.
• addDatastream: this is the main method to be used to add or update desired datastreams to the Entity
• deleteDatastream: this is the main method to be used to remove some datastream from Entity
• getDatastream: this is the main method to be used get the value from specific datastream in the Entity
• Other internal methods should not be necessary to call them.

Kind: inner class of Entities_Utils

Entity(entityIdentifier)

Init entityJson property with an entity identifier. Use new Entity(entityIdentifier) to create a new Entity.

Example of use:

const entity = new Entity("entityIdentifier");

entity.withPrefix(prefixToBeUsed)

Define the prefix of the datastreams to be used by addDatastream method. Adding a new prefix will override the previously added one. Use this method with an empty or undefined parameter to stop using any prefix.

Kind: instance method of Entity
Returns: Entity - Current Entity instance

Example of use:

entity.withPrefix("prefix");

entity.getDatastream(datastream, _index)

Search specified datastream and returns value. This function requires always complete datastream (ignores withPrefix functions calls).

Kind: instance method of Entity
Returns: * - Found datastream’s value, it can be complex. Null if not found.

Example of use:

entity.getDatastream("datastream");

entity.deleteDatastream(datastream, _index)

Delete specified datastream. This function requires always complete datastream (ignores withPrefix functions calls).

Kind: instance method of Entity
Returns: * - Found datastream’s value, it can be complex. Null if not found.

Example of use:

entity.deleteDatastream("datastream");

entity.addDatastream(datastream, value, _index)

Method to be used to add datastreams to current entity. Calling this method more than one time for the same datastream will have two different behaviors:

• If _index parameter is defined, a new value will be added or updated to the array.
• If _index parameter is not defined, the previous datastream will be overridden.

Kind: instance method of Entity
Returns: Entity - Current Entity instance

Example of use:

entity.addDatastream("datastream", "value");

entity._addToEntity(datastream)

Internal method. Attach provided datastream to current Entity’s JSON.

Kind: instance method of Entity
Returns: Entity - Current Entity instance.

Example of use:

entity._addToEntity({ datastream: "value" });

entity._generateDatastreamJsonWithArray(datastream, valuesArray)

Internal method. Generates an object with datastream as field and provided array as value. This method is helpful for communicationModules[] datastreams.

Internally calls _cleanArray method to add good array.

Kind: instance method of Entity
Returns: Object - Json object with built datastream.

Example of use:

entity._generateDatastreamJsonWithArray("datastream", ["value"]);

entity._generateDatastreamWithJson(datastream, value)

Internal method. Generates an object with datastream as field and provided value. In this case, value can be a plain value (for example, String) or a complex JSON

Internally calls _generateJsonCurrentValue to build basic json structure.

Kind: instance method of Entity
Returns: Object - Json object with built datastream.

Example of use:

entity._generateDatastreamWithJson("datastream", { value: "value" });

entity._generateIndexedJson(index, value)

Internal method. Generates a json with provided index and value. This method will be used when creating datastreams with communicationModules[].

Kind: instance method of Entity
Returns: Object - Json object with indexed value structure.

Example of use:

entity._generateIndexedJson("index", "value");

entity._generateJsonCurrentValue(value)

Internal method. Generates a JSON with basic structure datastream value.

Kind: instance method of Entity
Returns: Object - Json object with basic value structure.

Example of use:

entity._generateJsonCurrentValue("value");

Return example:

{
    "_value":{
        "_current":{
            "value": value
        }
    }
}

entity._cleanArray(valuesArray)

Internal method. Auxiliary method to clean empty ("", null, undefined) elements from provided array.

Kind: instance method of Entity
Returns: Array - New array without empty elements. null if the array is empty.

Example of use:

entity._cleanArray(["value", "", null, undefined]);

entity._generateDatastreamEntry(datastream, dsJson)

Internal method. Auxiliary method to build an object with datastream as field and provided JSON as value.

Kind: instance method of Entity
Returns: Object - Json object with built datastream.

Example of use

entity._generateDatastreamEntry("datastream", { value: "value" });

Return examples:

{
    "datastream.name": {...}
}

or

{
    "datastream.name": [...]
}

readMapValue(map, headerName, defaultValue, headerColumn)

Auxiliary method to read values from the specified map.

A key will be created with headerName and headerColumn and the value for this key will be retrieved. If there is no entry for this key or the value is empty or undefined, defaultValue will be returned.

If headerColumn is null, only headerName will be used as the key.

Kind: inner method of Entities_Utils
Returns: * - Obtained value for specified header name and column or at least defined default value.

Example of use:

readMapValue(map, "headerName", "defaultValue", "headerColumn");

newEntityBuilder(fromEntityJson)

Creates Entity class object with specified entity json.

Kind: inner method of Entities_Utils
Returns: Entity - Entity Class instance

Example of use:

var entity = newEntityBuilder(fromEntityJson);

Action_Utils

Functions for building ODM Actions.

Action structure example:

{
   "action": "POST",
   "entityType": "device",
   "actionDescription": "Create Simple Device",
   "json": {...},
   "full": false
}

• Action_Utils
  • CREATE_ASSET_ACTION(entityJson, description)
  • UPDATE_ASSET_ACTION(entityJson, description)
  • PATCH_ASSET_ACTION(entityJson, description)
  • DELETE_ASSET_ACTION(entityJson, description)
  • CREATE_DEVICE_ACTION(entityJson, description)
  • UPDATE_DEVICE_ACTION(entityJson, description)
  • PATCH_DEVICE_ACTION(entityJson, description)
  • DELETE_DEVICE_ACTION(entityJson, full, description)
  • CREATE_SUBSCRIPTION_ACTION(entityJson, description)
  • UPDATE_SUBSCRIPTION_ACTION(entityJson, description)
  • PATCH_SUBSCRIPTION_ACTION(entityJson, description)
  • DELETE_SUBSCRIPTION_ACTION(entityJson, description)
  • CREATE_SUBSCRIBER_ACTION(entityJson, description)
  • UPDATE_SUBSCRIBER_ACTION(entityJson, description)
  • PATCH_SUBSCRIBER_ACTION(entityJson, description)
  • DELETE_SUBSCRIBER_ACTION(entityJson, description)
  • _createAction(action, entityJson, entityType, full, description)

CREATE_ASSET_ACTION(entityJson, description)

Builds Create Asset action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const assetJson = {
    "name": "asset1",
    "description": "asset1",
    "type": "asset"
}
const action = CREATE_ASSET_ACTION(assetJson, "Create Asset");

UPDATE_ASSET_ACTION(entityJson, description)

Builds Update Asset action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const assetJson = {
    "name": "asset1",
    "description": "asset1",
    "type": "asset"
}
const action = UPDATE_ASSET_ACTION(assetJson, "Update Asset");

PATCH_ASSET_ACTION(entityJson, description)

Builds Patch Asset action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const assetJson = {
    "name": "asset1",
    "description": "asset1",
    "type": "asset"
}
const action = PATCH_ASSET_ACTION(assetJson, "Patch Asset");

DELETE_ASSET_ACTION(entityJson, description)

Builds Delete Asset action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const assetJson = {
    "name": "asset1",
    "description": "asset1",
    "type": "asset"
}
const action = DELETE_ASSET_ACTION(assetJson, "Delete Asset");

CREATE_DEVICE_ACTION(entityJson, description)

Builds Create Device action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const deviceJson = {
    "name": "device1",
    "description": "device1",
    "type": "device"
}
const action = CREATE_DEVICE_ACTION(deviceJson, "Create Device");

UPDATE_DEVICE_ACTION(entityJson, description)

Builds Update Device action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const deviceJson = {
    "name": "device1",
    "description": "device1",
    "type": "device"
}
const action = UPDATE_DEVICE_ACTION(deviceJson, "Update Device");

PATCH_DEVICE_ACTION(entityJson, description)

Builds Patch DEVICE action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const deviceJson = {
    "name": "device1",
    "description": "device1",
    "type": "device"
}
const action = PATCH_DEVICE_ACTION(deviceJson, "Patch Device");

DELETE_DEVICE_ACTION(entityJson, full, description)

Builds Delete Device action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const deviceJson = {
    "name": "device1",
    "description": "device1",
    "type": "device"
}
const action = DELETE_DEVICE_ACTION(deviceJson, true, "Delete Device");

CREATE_SUBSCRIPTION_ACTION(entityJson, description)

Builds Create Subscription action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriptionJson = {
    "name": "subscription1",
    "description": "subscription1",
    "type": "subscription"
}
const action = CREATE_SUBSCRIPTION_ACTION(subscriptionJson, "Create Subscription");

UPDATE_SUBSCRIPTION_ACTION(entityJson, description)

Builds Update Subscription action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriptionJson = {
    "name": "subscription1",
    "description": "subscription1",
    "type": "subscription"
}
const action = UPDATE_SUBSCRIPTION_ACTION(subscriptionJson, "Update Subscription");

PATCH_SUBSCRIPTION_ACTION(entityJson, description)

Builds Patch Subscription action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriptionJson = {
    "name": "subscription1",
    "description": "subscription1",
    "type": "subscription"
}
const action = PATCH_SUBSCRIPTION_ACTION(subscriptionJson, "Patch Subscription");

DELETE_SUBSCRIPTION_ACTION(entityJson, description)

Builds Delete Subscription action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriptionJson = {
    "name": "subscription1",
    "description": "subscription1",
    "type": "subscription"
}
const action = DELETE_SUBSCRIPTION_ACTION(subscriptionJson, "Delete Subscription");

CREATE_SUBSCRIBER_ACTION(entityJson, description)

Builds Create Subscriber action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriberJson = {
    "name": "subscriber1",
    "description": "subscriber1",
    "type": "subscriber"
}
const action = CREATE_SUBSCRIBER_ACTION(subscriberJson, "Create Subscriber");

UPDATE_SUBSCRIBER_ACTION(entityJson, description)

Builds Update Subscriber action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriberJson = {
    "name": "subscriber1",
    "description": "subscriber1",
    "type": "subscriber"
}
const action = UPDATE_SUBSCRIBER_ACTION(subscriberJson, "Update Subscriber");

PATCH_SUBSCRIBER_ACTION(entityJson, description)

Builds Patch Subscriber action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriberJson = {
    "name": "subscriber1",
    "description": "subscriber1",
    "type": "subscriber"
}
const action = PATCH_SUBSCRIBER_ACTION(subscriberJson, "Patch Subscriber");

DELETE_SUBSCRIBER_ACTION(entityJson, description)

Builds Delete Subscriber action with provided JSON.

Kind: inner method of Action_Utils
Returns: Object - Created action.

Example of use:

const subscriberJson = {
    "name": "subscriber1",
    "description": "subscriber1",
    "type": "subscriber"
}
const action = DELETE_SUBSCRIBER_ACTION(subscriberJson, "Delete Subscriber");

_createAction(action, entityJson, entityType, full, description)

Internal method. Builds an action object with specified parameters.

Kind: inner method of Action_Utils
Returns: Object - Action object with provided parameters.

Example of use:

const action = _createAction("CREATE", deviceJson, "device", false, "Create Device");

V8_Api

Java V8 API: Functions encapsulate the logic for calling Java V8 Methods.

Java V8 Methods are defined in: es.amplia.odm.frontend.ws.provision.bulk.bulkProcessor.jsEngine.ProvisionProcessorScriptExecutor

These are the methods defined:

• printLogInternal (printLog): writes INFO log messages.
  • params:
    • String msg: message to be printed.
• getEntityInternal (getEntity): gets specific Entity for provided id.
  • params:
    • String provisionType: it should be always ‘ENTITY’.
    • String resourceType: the entity type to be retrieved.
    • String entityId: entity to be retrieved.
    • Map javaParams: mandatory params to configure the query (api key, organization id…).
  • return:
    • String: Entity json.
• genericSearchInternal (genericSearch): searches entities with provided filter.
  • params:
    • String searchTypeValue: What kind of elements must be search.
    • String searchQueryValue: Json format filter.
    • Map javaParams: mandatory params to configure the query (api key, organization id…).
  • return:
    • String: Json with found elements and page information.

printLog(msg)

Invokes Java V8 printLogInternal method.

Kind: inner method of V8_Api

Example of use:

printLog('Provision processor started');

getEntity(entityId, resourceType, queryContextParams)

Invokes Java V8 getEntityInternal method.

Use queryContextParams parameter to specify query behavior. It is a JSON with next properties:

• utc: used to format datetime fields. Default value: false.
• flattened: used to specify if entity must be returned flattened or not. Default value: true.

Kind: inner method of V8_Api
Returns: Object - Entity Json. null if no entity is found

Example of use:

var assetEntity = getEntity(normalizedObject.asset_identifier, 'entity.asset');

entitiesGenericSearch(searchFilter, queryContextParams)

Invokes Java V8 genericSearchInternal method for ENTITIES.

Use queryContextParams parameter to specify query behavior. It is a JSON with next properties:

• utc: used to format datetime fields. Default value: false.
• flattened: used to specify if entity must be returned flattened or not. Default value: true.
• defaultSorted: specifies if result must be sorted by default field. Default value: false.

Kind: inner method of V8_Api
Returns: Object - Search result json. null if no result is found.

Example of use:

var assetEntity = entitiesGenericSearch(normalizedObject.asset_identifier, 'entity.asset');

_minJavaParams(queryContextParams)

Auxiliary method to build params maps for Java Queries

Kind: inner method of V8_Api
Returns: Object - Json object

Example of use:

var javaParams = _minJavaParams({ utc: true });

V8_Utils

Java V8 Utils: Some predefined functions for Java V8 calls. These functions internally call V8_Api functions.

checkAsset(id)

Check if an Asset exists for specified id.

Kind: inner method of V8_Utils
Returns: boolean - If the asset exists.

Example of use:

if (checkAsset(normalizedObject.asset_identifier)) {
  printLog('Check returned true');
}

checkDevice(id)

Check if a Device exists for specified id.

Kind: inner method of V8_Utils
Returns: boolean - If the Device exists.

Example of use:

if (checkDevice(normalizedObject.device_identifier)) {
  printLog('Check returned true');
}

checkSubscription(id)

Check if a Subscription exists for specified id.

Kind: inner method of V8_Utils
Returns: boolean - If the Subscription exists.

Example of use:

if (checkSubscription(normalizedObject.subscription_identifier)) {
  printLog('Check returned true');
}

checkSubscriber(id)

Check if a Subscriber exists for specified id.

Kind: inner method of V8_Utils
Returns: boolean - If the Subscriber exists.

Example of use:

if (checkSubscriber(normalizedObject.subscriber_identifier)) {
  printLog('Check returned true');
}

getAssetEntity(id)

Gets specific Asset for specified id.

Kind: inner method of V8_Utils
Returns: Object - Asset entity, null if the Asset does not exist.

Example of use:

var assetEntity = getAssetEntity(normalizedObject.asset_identifier);

getDeviceEntity(id)

Gets specific Device for specified id.

Kind: inner method of V8_Utils
Returns: Object - Device entity, null if the Device does not exist.

Example of use:

var deviceEntity = getDeviceEntity(normalizedObject.device_identifier);

getSubscriptionEntity(id)

Gets specific Subscription for specified id.

Kind: inner method of V8_Utils
Returns: Object - Subscription entity, null if the Subscription does not exist.

Example of use:

var subscriptionEntity = getSubscriptionEntity(normalizedObject.subscription_identifier);

getSubscriberEntity(id)

Gets specific Subscriber for specified id.

Kind: inner method of V8_Utils
Returns: Object - Subscriber entity, null if the Subscriber does not exist.

Example of use:

var subscriberEntity = getSubscriberEntity(normalizedObject.subscriber_identifier);

duplicatedDsInSubscriptions(currentSubscriptionId, …datastreamsToCheck)

Searches for duplicated datastreams in other Subscriptions (other than currentSubscriptionId).

Kind: inner method of V8_Utils
Returns: boolean - If some Subscription has been found with some of duplicated datastreams.

Example of use:

if (duplicatedDsInSubscriptions(normalizedObject.subscription_identifier, normalizedObject.datastreams)) {
  printLog('Check returned true');
}

duplicatedDsInSubscribers(currentSubscriberId, …datastreamsToCheck)

Searches for duplicated datastreams in other Subscribers (other than currentSubscriberId).

Kind: inner method of V8_Utils
Returns: boolean - If some Subscriber has been found with some of duplicated datastreams

Example of use:

if (duplicatedDsInSubscribers(normalizedObject.subscriber_identifier, normalizedObject.datastreams)) {
  printLog('Check returned true');
}

duplicatedDsInDevices(currentDeviceId, …datastreamsToCheck)

Searches for duplicated datastreams in other Devices (other than currentDeviceId).

Kind: inner method of V8_Utils
Returns: boolean - If some Device has been found with some of duplicated datastreams.

Example of use:

if (duplicatedDsInDevices(normalizedObject.device_identifier, normalizedObject.datastreams)) {
  printLog('Check returned true');
}

duplicatedDsInAssets(currentAssetId, …datastreamsToCheck)

Searches for duplicated datastreams in other Assets (other than currentAssetId).

Kind: inner method of V8_Utils
Returns: boolean - If some Asset has been found with some of duplicated datastreams.

Example of use:

if (duplicatedDsInAssets(normalizedObject.asset_identifier, normalizedObject.datastreams)) {
  printLog('Check returned true');
}

_checkEntity(id, resourceType)

Internal method. Check if an ENTITY exists for the specified id and resource type.

Kind: inner method of V8_Utils
Returns: boolean - If the ENTITY exists.

Example of use:

if (_checkEntity(normalizedObject.asset_identifier, 'asset')) {
  printLog('Check returned true');
}

_checkDuplicatedDS(currentEntityIdentifierDatastream, currentEntityIdentifierValue, …datastreamsToCheck)

Internal method. Searches for duplicated datastreams in other entities than the specified one.

Kind: inner method of V8_Utils
Returns: boolean - If duplicated Datasteams are found in other entities.

Example of use:

if (_checkDuplicatedDS(normalizedObject.subscription_identifier, normalizedObject.subscription_identifier, normalizedObject.datastreams)) {
  printLog('Check returned true');
}

Error_Api

This module contains ErrorManager class specification.

ErrorManager

Class used to manage and extract information from caught provision action exception. Internally contains following objects:

• platformErrors: list of ApiPlatformError representation.
• actionObject: OdmProvisionAction representation.
• defaultErrorMessage: default error message string.

Kind: inner class of Error_Api

ErrorManager(platformErrors, actionObject, defaultErrorMessage)

Initialize ErrorManager entity. Use new keyword to create an instance of ErrorManager.

Example of use:

var errorManager = new ErrorManager(platformErrors, actionObject, defaultErrorMessage);

errorManager.getDefaultMessage()

Kind: instance method of ErrorManager
Returns: string - initialized default message

Example of use:

var defaultMessage = errorManager.getDefaultMessage();

errorManager.getFirstError()

Returns first error object.

Kind: instance method of ErrorManager
Returns: Object - first error. It can be undefined or null.

Example of use:

var firstError = errorManager.getFirstError();

errorManager.getFirstErrorAsString()

Returns first error object as string

Kind: instance method of ErrorManager
Returns: string - first error as string. It can be undefined or null.

Example of use:

var firstErrorAsString = errorManager.getFirstErrorAsString();

errorManager.getFirstErrorMessage()

Returns first error’s message property.

Kind: instance method of ErrorManager
Returns: String - message property value. It can be undefined or null.

Example of use:

var firstErrorMessage = errorManager.getFirstErrorMessage();

errorManager.getFirstErrorCode()

Returns first error’s code property.

Kind: instance method of ErrorManager
Returns: String - code property value. It can be undefined or null.

Example of use:

var firstErrorCode = errorManager.getFirstErrorCode();

errorManager.getFirstErrorContextArray()

Returns first error’s context property.

Kind: instance method of ErrorManager
Returns: array - context property value as array. It can be undefined or null.

Example of use:

var firstErrorContextArray = errorManager.getFirstErrorContextArray();

errorManager.getFirstErrorContextArrayAsString()

Returns first error’s context property.

Kind: instance method of ErrorManager
Returns: string - context property value as string. It can be undefined or null.

Example of use:

var firstErrorContextArrayAsString = errorManager.getFirstErrorContextArrayAsString();

errorManager.getFirstContextName()

Returns first error’s first context’s name property.

Kind: instance method of ErrorManager
Returns: string - context name property value. It can be undefined or null.

Example of use:

var firstContextName = errorManager.getFirstContextName();

errorManager.getFirstContextValue()

Returns first error’s first context’s value property.

Kind: instance method of ErrorManager
Returns: string - context value property value. It can be undefined or null.

Example of use:

var firstContextValue = errorManager.getFirstContextValue();

errorManager.getFirstContext()

Returns first error’s first context object.

Kind: instance method of ErrorManager
Returns: Object - context object. It can be undefined or null.

Example of use:

var firstContext = errorManager.getFirstContext();

errorManager.getFirstContextAsString()

Returns first error’s first context object as string.

Kind: instance method of ErrorManager
Returns: string - context object as string. It can be undefined or null.

Example of use:

var firstContextAsString = errorManager.getFirstContextAsString();

errorManager.getErrorsSize()

Returns number of errors contained.

Kind: instance method of ErrorManager
Returns: number - size of contained errors.

Example of use:

var errorsSize = errorManager.getErrorsSize();

errorManager.getSpecificErrorObject(index)

Returns specific error object

Kind: instance method of ErrorManager
Returns: Object - error object. It can be undefined or null.

Example of use:

var specificErrorObject = errorManager.getSpecificErrorObject(0);

errorManager.getSpecificErrorObjectAsString(index)

Returns specific error object as a string

Kind: instance method of ErrorManager
Returns: string - error object as string. It can be undefined or null.

Example of use:

var specificErrorObjectAsString = errorManager.getSpecificErrorObjectAsString(0);

errorManager.getSpecificErrorMessage(index)

Returns specific error’s message

Kind: instance method of ErrorManager
Returns: String - message property value for specified error. It can be undefined or null.

Example of use:

var specificErrorMessage = errorManager.getSpecificErrorMessage(0);

errorManager.getSpecificErrorCode(index)

Returns specific error’s code

Kind: instance method of ErrorManager
Returns: String - code property value for specified error. It can be undefined or null.

Example of use:

var specificErrorCode = errorManager.getSpecificErrorCode(0);

errorManager.getSpecificErrorContextArray(index)

Returns specific error’s context property as array.

Kind: instance method of ErrorManager
Returns: array - context property value as array. It can be undefined or null.

Example of use:

var specificErrorContextArray = errorManager.getSpecificErrorContextArray(0);

errorManager.getSpecificErrorContextArrayAsString(index)

Returns specific error’s context property as string.

Kind: instance method of ErrorManager
Returns: string - context property value for specified error. It can be undefined or null.

Example of use:

var specificErrorContextArrayAsString = errorManager.getSpecificErrorContextArrayAsString(0);

errorManager.getSpecificContext(errorIndex, contextIndex)

Returns specific context in specific error.

Kind: instance method of ErrorManager
Returns: Object - context object. It can be undefined or null.

Example of use:

var specificContext = errorManager.getSpecificContext(0, 0);

errorManager.getSpecificContextAsString(errorIndex, contextIndex)

Returns specific context in specific error as string.

Kind: instance method of ErrorManager
Returns: string - context object. It can be undefined or null.

Example of use:

var specificContextAsString = errorManager.getSpecificContextAsString(0, 0);

errorManager.getSpecificContextName(errorIndex, contextIndex)

Returns specific context’s name in specific error.

Kind: instance method of ErrorManager
Returns: string - name property value for specified context. It can be undefined or null.

Example of use:

var specificContextName = errorManager.getSpecificContextName(0, 0);

errorManager.getSpecificContextValue(errorIndex, contextIndex)

Returns specific context’s value in specific error.

Kind: instance method of ErrorManager
Returns: string - value property value for specified context. It can be undefined or null.

Example of use:

var specificContextValue = errorManager.getSpecificContextValue(0, 0);

errorManager.getAdministrationIdentifier()

Returns entity administration identifier.

Kind: instance method of ErrorManager
Returns: string - It can be undefined or null.

Example of use:

var administrationIdentifier = errorManager.getAdministrationIdentifier();

errorManager.getDatastreamValue(index)

Returns from entity (in OdmProvisionAction) specific datastream value (datastream._value._current.value). It can be an object or plain string.

Kind: instance method of ErrorManager
Returns: Object - Object with specific datastream. It can be undefined or null.

Example of use:

var datastreamValue = errorManager.getDatastreamValue(0);

errorManager.getDatastreamValueAsString(index)

Returns from entity (in OdmProvisionAction) specific datastream value (datastream._value._current.value). It can be a json string.

Kind: instance method of ErrorManager
Returns: string - String with specific datastream. It can be undefined or null.

Example of use:

var datastreamValueAsString = errorManager.getDatastreamValueAsString(0);

errorManager.getAction()

Returns provision action type (POST, PUT, PATCH, DELETE) from OdmProvisionAction

Kind: instance method of ErrorManager
Returns: string - It can be undefined or null.

Example of use:

var action = errorManager.getAction();

errorManager.isPost()

Kind: instance method of ErrorManager
Returns: boolean - true if provision action is POST.

Example of use:

var isPost = errorManager.isPost();

errorManager.isPut()

Kind: instance method of ErrorManager
Returns: boolean - true if provision action is PUT.

Example of use:

var isPut = errorManager.isPut();

errorManager.isPatch()

Kind: instance method of ErrorManager
Returns: boolean - true if provision action is PATCH.

Example of use:

var isPatch = errorManager.isPatch();

errorManager.isDelete()

Kind: instance method of ErrorManager
Returns: boolean - true if provision action is DELETE.

Example of use:

var isDelete = errorManager.isDelete();

errorManager.getEntityType()

Returns provision entity type (asset, device, subscription, subscriber) from OdmProvisionAction

Kind: instance method of ErrorManager
Returns: string - It can be undefined or null.

Example of use:

var entityType = errorManager.getEntityType();

errorManager.isSubscription()

Kind: instance method of ErrorManager
Returns: boolean - true if provision entity is subscription.

Example of use:

var isSubscription = errorManager.isSubscription();

errorManager.isSubscriber()

Kind: instance method of ErrorManager
Returns: boolean - true if provision entity is subscriber.

Example of use:

var isSubscriber = errorManager.isSubscriber();

errorManager.isDevice()

Kind: instance method of ErrorManager
Returns: boolean - true if provision entity is device.

Example of use:

var isDevice = errorManager.isDevice();

errorManager.isAsset()

Kind: instance method of ErrorManager
Returns: boolean - true if provision entity is asset.

Example of use:

var isAsset = errorManager.isAsset();