Process Best Practices

Learn about recommended best practices for working with processes.

Table of Contents

Process best practices: recommended steps

The steps below are an example of some best practices you can use, when working with processes, to help develop clear and maintainable process definitions.

Recommended best practice steps for building a process

  1. Declare a dedicated Request and Response processContext variable of type Message for every downstream call you are going to make in a process. This helps make sure that multiple split/join threads match up correctly for request and response messages later.
  2. Declare all of the other variables, regardless of type, that you’re going to use in the process. This ensures that they appear in dialogs in the user interface.
  3. Use short, meaningful variable names, so that their usage is easy to remember and understand, by yourself or by others, later.
  4. Do not simply overwrite the default incoming request message variable message with a response message. You might need to refer back to the incoming message later.
  5. Normalization:
    • To make sure you always get the normalized message object back, use var normMsg = msg.normalize(); and don’t continue to use msg later. Use var so that the variable is local to the script, not a global variable. The msg.normalize() method produces a new normalized Message object, but does not change the msg object itself. However, even so, assigning the output to another variable in your script ensures that you are working with the normalized message.
    • Do not rely on the Transformation Activity for normalizing your message. If a script activity is used in your process, it's a good idea to use the isNormalized() function for the message object, to verify whether or not normalization is needed and take steps accordingly. For example:

      if(!isNormalized()){ msg.normalize();}

  6. If you are going to be making many changes to the message content in a script, it's a good idea to transform XML to a JSON object using the XML2JSON methods. It's easy to work with JSON in JavaScript, but not so easy to work with XML. In addition, it’s easy to access JSON properties in a JSON JavaScript object by name, but more difficult using the XML DOM.

    Some examples:

    • jsonObj.fixedPropName
    • jsonObj[ variablePropName ]
    • jsonObj.fixedPropName.fixedSubPropName
    • jsonObj[ variablePropName][variableSubPropName]
  7. The Transform activity using FreeMarker produces debug-level messages in the auditLog for every Message object declared in the Process that has a null value when the Transform step is executed. This can clutter the debug log; instead, you can use the following Javascript function, which performs the process initialization steps: 
    initializeProcess( reqMsgVarName, partNamesArray, msgVarNamesToInitializeArray )

    To implement this function, call it in a script step at the beginning of each process. It does the following:

    1. First, normalizes the incoming request message in the reqMsgVarName variable (default is message), and then sets this normalized Message object back into the processContext with the same name. Result: the message is normalized.
    2. Gets each message Part specified in the partNamesArray from the reqMsgVarName variable, and saves each part value in a processContext variable of type String with that part name. Later in the process, you can easily access these part values from anywhere. You can also declare each of these part name variables in the process.
    3. Finally, initializes each variable specified in msgVarNamesToInitializeArray to a new normalized Message object, and saves it into the processContext with that name.

      It's a good idea to also declare each of the Message name variables in the process, so that they show up in the selection combo fields in the user interface.

    The result is that there are no debug messages from Transform activities for null Message variables, the parts from the incoming message are all in the processContext by name, and everything runs smoothly because each downstream invoke has its own request and response Message object to work with.

Example script

For an example script that implements many of the best practices listed above, see ScriptUtils.js.

Notes:

  • This script is offered as an example only. It is not part of the supported Akana product, but is an example of how you could build the above best practices into your processes with a script. You could use any part of it, modified for your own implementation, or you could implement the above best practices in some other way.
  • To implement any version of this script, you will need to copy the script contents into a Script in your Akana tenant organization, and then import it into each script step in your process.
  • A .txt extension has been added to the filename.