JavaScript API

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(assetExist));
   }

   /* 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;
}

JS API

Error_Api

This module contains ErrorManager class specification.

Error_Api~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

new ErrorManager(platformErrors, actionObject, defaultErrorMessage)

Initialize ErrorManager entity.

Param Type Description
platformErrors Object list of ApiPlatformError representation.
actionObject Object OdmProvisionAction representation.
defaultErrorMessage String default error message.

errorManager.getDefaultMessage() ⇒ string

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

errorManager.getFirstError() ⇒ Object

Returns first error object.

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

errorManager.getFirstErrorAsString() ⇒ string

Returns first error object as string

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

errorManager.getFirstErrorMessage() ⇒ String

Returns first error’s message property.

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

errorManager.getFirstErrorCode() ⇒ String

Returns first error’s code property.

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

errorManager.getFirstErrorContextArray() ⇒ array

Returns first error’s context property.

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

errorManager.getFirstErrorContextArrayAsString() ⇒ string

Returns first error’s context property.

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

errorManager.getFirstContextName() ⇒ string

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.

errorManager.getFirstContextValue() ⇒ string

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.

errorManager.getFirstContext() ⇒ Object

Returns first error’s first context object.

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

errorManager.getFirstContextAsString() ⇒ string

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.

errorManager.getErrorsSize() ⇒ number

Returns number of errors contained.

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

errorManager.getSpecificErrorObject(index) ⇒ Object

Returns specific error object

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

Param Type Description
index number error index in errors list

errorManager.getSpecificErrorObjectAsString(index) ⇒ string

Returns specific error object as a string

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

Param Type Description
index number error index in errors list

errorManager.getSpecificErrorMessage(index) ⇒ String

Returns specific error’s message

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

Param Type Description
index number error index in errors list

errorManager.getSpecificErrorCode(index) ⇒ String

Returns specific error’s code

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

Param Type Description
index number error index in errors list

errorManager.getSpecificErrorContextArray(index) ⇒ array

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.

Param Type Description
index number error index in errors list

errorManager.getSpecificErrorContextArrayAsString(index) ⇒ string

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.

Param Type Description
index number error index in errors list

errorManager.getSpecificContext(errorIndex, contextIndex) ⇒ Object

Returns specific context in specific error.

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

Param Type Description
errorIndex number error index in errors list
contextIndex number context index in specified error

errorManager.getSpecificContextAsString(errorIndex, contextIndex) ⇒ string

Returns specific context in specific error as string.

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

Param Type Description
errorIndex number error index in errors list
contextIndex number context index in specified error

errorManager.getSpecificContextName(errorIndex, contextIndex) ⇒ string

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.

Param Type Description
errorIndex number error index in errors list
contextIndex number context index in specified error

errorManager.getSpecificContextValue(errorIndex, contextIndex) ⇒ string

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.

Param Type Description
errorIndex number error index in errors list
contextIndex number context index in specified error

errorManager.getAdministrationIdentifier() ⇒ string

Returns entity administration identifier.

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

errorManager.getDatastreamValue(index) ⇒ Object

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.

Param Type Description
index number error index in errors list

errorManager.getDatastreamValueAsString(index) ⇒ string

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.

Param Type Description
index number error index in errors list

errorManager.getAction() ⇒ string

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

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

errorManager.isPost() ⇒ boolean

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

errorManager.isPut() ⇒ boolean

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

errorManager.isPatch() ⇒ boolean

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

errorManager.isDelete() ⇒ boolean

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

errorManager.getEntityType() ⇒ string

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

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

errorManager.isSubscription() ⇒ boolean

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

errorManager.isSubscriber() ⇒ boolean

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

errorManager.isDevice() ⇒ boolean

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

errorManager.isAsset() ⇒ boolean

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

Main_Module

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

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) ⇒ String

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.
Param Type Description
rawObject Object Json with with excel row data
processorParamsMap Object Processor extra params map: can contain necessary parameters for odm api calls (key, organization) or useful parameters to define specfic behaviors

Example

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 in case of main methods (normalizeRawObject and actionsPlanning) are defined correctly as functions

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.

  • V8_Api

V8_Api~printLog(msg)

Invokes Java V8 printLogInternal method.

Kind: inner method of V8_Api

Param Type Description
msg String String to be printed in Java logs

V8_Api~getEntity(entityId, resourceType, queryContextParams) ⇒ Object

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

Param Type Description
entityId String Id of the entity to be retrieved
resourceType String Parameter used to specify the entity type to be retrieved
queryContextParams Object Parameters for query. Not mandatory

V8_Api~entitiesGenericSearch(searchFilter, queryContextParams) ⇒ Object

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.

Param Type Description
searchFilter String json search filter
queryContextParams Object Parameters for query. Not mandatory

V8_Api~_minJavaParams(queryContextParams) ⇒ Object

Auxiliary method to build params maps for Java Queries

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

Param Type Description
queryContextParams Object parameters for query. Not mandatory.

V8_Utils

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

V8_Utils~checkAsset(id) ⇒ boolean

Check if an Asset exists for specified id.

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

Param Type Description
id String asset identifier.

V8_Utils~checkDevice(id) ⇒ boolean

Check if a Device exists for specified id.

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

Param Type Description
id String Device identifier.

V8_Utils~checkSubscription(id) ⇒ boolean

Check if a Subscription exists for specified id.

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

Param Type Description
id String Subscription identifier.

V8_Utils~checkSubscriber(id) ⇒ boolean

Check if a Subscriber exists for specified id.

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

Param Type Description
id String Subscriber identifier.

V8_Utils~getAssetEntity(id) ⇒ Object

Gets specific Asset for specified id.

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

Param Type Description
id String Asset identifier.

V8_Utils~getDeviceEntity(id) ⇒ Object

Gets specific Device for specified id.

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

Param Type Description
id String Device identifier.

V8_Utils~getSubscriptionEntity(id) ⇒ Object

Gets specific Subscription for specified id.

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

Param Type Description
id String Subscription identifier.

V8_Utils~getSubscriberEntity(id) ⇒ Object

Gets specific Subscriber for specified id.

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

Param Type Description
id String Subscriber identifier.

V8_Utils~duplicatedDsInSubscriptions(currentSubscriptionId, …datastreamsToCheck) ⇒ boolean

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.

Param Type Description
currentSubscriptionId String The Subscription id with the datastreams to be checked.
…datastreamsToCheck Object Datastreams to be checked if they are duplicated. Each datastream must be defined as {“datastreamId”: “datastreamValue”}.

V8_Utils~duplicatedDsInSubscribers(currentSubscriberId, …datastreamsToCheck) ⇒ boolean

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

Param Type Description
currentSubscriberId String The Subscriber id with the datastreams to be checked.
…datastreamsToCheck Object Datastreams to be checked if they are duplicated. Each datastream is defined as a pair {“datastreamId”: “datastreamValue”}.

V8_Utils~duplicatedDsInDevices(currentDeviceId, …datastreamsToCheck) ⇒ boolean

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.

Param Type Description
currentDeviceId String The Device id with the datastreams to be checked.
…datastreamsToCheck Object Datastreams to be checked if they are duplicatedEach datastream is defined as a pair {“datastreamId”: “datastreamValue”}.

V8_Utils~duplicatedDsInAssets(currentAssetId, …datastreamsToCheck) ⇒ boolean

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.

Param Type Description
currentAssetId String The Asset id with the datastreams to be checked.
…datastreamsToCheck Object Datastreams to be checked if they are duplicated. Each datastream is defined as a pair {“datastreamId”: “datastreamValue”}.

V8_Utils~_checkEntity(id, resourceType) ⇒ boolean

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.

Param Type Description
id String Entity id to be checked.
resourceType String Entity type to be checked.

V8_Utils~_checkDuplicatedDS(currentEntityIdentifierDatastream, currentEntityIdentifierValue, …datastreamsToCheck) ⇒ boolean

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.

Param Type Description
currentEntityIdentifierDatastream String Datastream used to specify the Entity id with the datastreams to be checked.
currentEntityIdentifierValue String Value for currentEntityIdentifierDatastream field.
…datastreamsToCheck Object Datastreams to be checked if they are duplicated. Each datastream is defined as a pair {“datastreamId”: “datastreamValue”}.

Action_Utils

Action Utils: Functions for building ODM Actions.

Example

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

Action_Utils~CREATE_ASSET_ACTION(entityJson, description) ⇒ Object

Builds Create Asset action with provided JSON.

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

Param Type Description
entityJson Object Asset Entity Json to be created.
description String Action short description.

Action_Utils~UPDATE_ASSET_ACTION(entityJson, description) ⇒ Object

Builds Update Asset action with provided JSON.

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

Param Type Description
entityJson Object Asset Entity Json to be updated.
description String Action short description.

Action_Utils~PATCH_ASSET_ACTION(entityJson, description) ⇒ Object

Builds Patch Asset action with provided JSON.

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

Param Type Description
entityJson Object Asset Entity Json to be updated.
description String Action short description.

Action_Utils~DELETE_ASSET_ACTION(entityJson, description) ⇒ Object

Builds Delete Asset action with provided JSON.

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

Param Type Description
entityJson Object Asset Entity Json to be deleted.
description String Action short description.

Action_Utils~CREATE_DEVICE_ACTION(entityJson, description) ⇒ Object

Builds Create Device action with provided JSON.

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

Param Type Description
entityJson Object Device Entity Json to be created.
description String Action short description.

Action_Utils~UPDATE_DEVICE_ACTION(entityJson, description) ⇒ Object

Builds Update Device action with provided JSON.

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

Param Type Description
entityJson Object Device Entity Json to be updated.
description String Action short description.

Action_Utils~PATCH_DEVICE_ACTION(entityJson, description) ⇒ Object

Builds Patch DEVICE action with provided JSON.

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

Param Type Description
entityJson Object Device Entity Json to be updated.
description String Action short description.

Action_Utils~DELETE_DEVICE_ACTION(entityJson, full, description) ⇒ Object

Builds Delete Device action with provided JSON.

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

Param Type Description
entityJson Object Device Entity Json to be deleted.
full boolean true to delete also related Subscriptions and Subscribers.
description String Action short description.

Action_Utils~CREATE_SUBSCRIPTION_ACTION(entityJson, description) ⇒ Object

Builds Create Subscription action with provided JSON.

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

Param Type Description
entityJson Object Subscription Entity Json to be created.
description String Action short description.

Action_Utils~UPDATE_SUBSCRIPTION_ACTION(entityJson, description) ⇒ Object

Builds Update Subscription action with provided JSON.

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

Param Type Description
entityJson Object Subscription Entity Json to be updated.
description String Action short description.

Action_Utils~PATCH_SUBSCRIPTION_ACTION(entityJson, description) ⇒ Object

Builds Patch Subscription action with provided JSON.

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

Param Type Description
entityJson Object Subscription Entity Json to be updated.
description String Action short description.

Action_Utils~DELETE_SUBSCRIPTION_ACTION(entityJson, description) ⇒ Object

Builds Delete Subscription action with provided JSON.

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

Param Type Description
entityJson Object Subscription Entity Json to be deleted.
description String Action short description.

Action_Utils~CREATE_SUBSCRIBER_ACTION(entityJson, description) ⇒ Object

Builds Create Subscriber action with provided JSON.

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

Param Type Description
entityJson Object Subscriber Entity Json to be created.
description String Action short description.

Action_Utils~UPDATE_SUBSCRIBER_ACTION(entityJson, description) ⇒ Object

Builds Update Subscriber action with provided JSON.

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

Param Type Description
entityJson Object Subscriber Entity Json to be updated.
description String Action short description.

Action_Utils~PATCH_SUBSCRIBER_ACTION(entityJson, description) ⇒ Object

Builds Patch Subscriber action with provided JSON.

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

Param Type Description
entityJson Object Subscriber Entity Json to be updated.
description String Action short description.

Action_Utils~DELETE_SUBSCRIBER_ACTION(entityJson, description) ⇒ Object

Builds Delete Subscriber action with provided JSON.

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

Param Type Description
entityJson Object Subscriber Entity Json to be deleted.
description String Action short description.

Action_Utils~_createAction(action, entityJson, entityType, full, description) ⇒ Object

Internal method. Builds an action object with specified parameters.

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

Param Type Description
action String Action to be done.
entityJson Object Entity JSON to be processed.
entityType String Entity type to be processed.
full Boolean Only for DELETE device. true to delete also related Subscriptions and Subscribers.
description String Action short description.

Entities_Utils

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

Entities_Utils~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 updated desired datastreams to 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

new Entity(entityIdentifier)

Init entityJson property with an entity identifier.

Param Type Description
entityIdentifier String identifier for current entity.

entity.withPrefix(prefixToBeUsed) ⇒ Entity

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

Param Type Description
prefixToBeUsed String The prefix that will be used in next addDatastream calls. If it is empty the prefix will be removed.

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.

Param Type Description
datastream String Datastream complete flattened name.
_index String If datastream is an array, index should be provided, if not, first element will be returned.

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.

Param Type Description
datastream String Datastream complete flattened name.
_index String If datastream is an array, index should be provided, if not, first element will be returned.

entity.addDatastream(datastream, value, _index) ⇒ Entity

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

Param Type Description
datastream String Datastream flattened name.
value String Value for the datastream.
_index String If provided, it will create special indexed datastream (for communicationModules[] datastreams).

entity._addToEntity(datastream) ⇒ Entity

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

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

Param Type Description
datastream Object Object to be attached to current Entity.

entity._generateDatastreamJsonWithArray(datastream, valuesArray) ⇒ Object

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.

Param Type Description
datastream String Datastream flattened name.
valuesArray Array Array of objects for the datastream.

entity._generateDatastreamWithJson(datastream, value) ⇒ Object

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.

Param Type Description
datastream String Datastream flattened name.
value Object Json object with datastream value.

entity._generateIndexedJson(index, value) ⇒ Object

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.

Param Type Description
index String Identifier for _index value.
value * It can be plain value (String,…) or complex Json.

entity._generateJsonCurrentValue(value) ⇒ Object

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

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

Param Type Description
value * It can be plain value (String,…) or complex Json

Example

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

entity._cleanArray(valuesArray) ⇒ Array

Internal method. Auxiliar 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.

Param Type Description
valuesArray Array Array to be checked.

entity._generateDatastreamEntry(datastream, dsJson) ⇒ Object

Internal method. Auxiliar 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.

Param Type Description
datastream String Datastream flattened name.
dsJson Object Json value for the datastream.

Example

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

Entities_Utils~readMapValue(map, headerName, defaultValue, headerColumn) ⇒ *

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

Param Type Description
map Object map from which to read values.
headerName String Header name for mapped row.
defaultValue * If no value is read or it is empty or undefined, default value will be returned.
headerColumn String Header column letter for mapped row (if null, only headerName will be used as key).

Entities_Utils~newEntityBuilder(fromEntityJson) ⇒ Entity

Creates Entity class object with specified entity json.

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

Param Type Description
fromEntityJson Object Json with Opengate flattened entity