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