Naming conventions

Choose the names for modules, folders, processes, context items, and concepts carefully. Use names that are consistent within the module and meaningful to the task being accomplished.

This topic presents information about the following subjects:

Guidelines for creating input and output parameter names

  • All parameters must have readable names that accurately describe the required data in the context of the function to be performed.
  • When a context item or variable is used in multiple workflows, the same name should be used across all workflows. For example, use incident description in all workflows that require the use of that data. TrueSight Orchestration Development Studio can match inputs to outputs if the names are the same in both workflows.
  • Whenever possible, do not use the short form of words. For example, use number instead of num and continue instead of cont.

  • Workflow inputs and outputs must have descriptions that include valid values when the input is restricted to a list of acceptable values and indicate whether a default value will be used for optional inputs when a user does not specify an input. 

    Example of a good workflow
    Example: input name \[Optional\]:
    description of input:
    valid values: a comma separated list of values
    default value:

  • Inputs that are of type XML must include a sample of that XML that includes all the possible elements. If necessary, include some possible variations of the XML input.

    XML sample that includes all the possible elements
    <ip-addresses>
      <ip-address>   
        <first-octet>10</first-octet>
        <second-octet>1</second-octet>
        <third-octet>1</third-octet>
        <fourth-octet>4</fourth-octet>
      <ip-address>
      <ip-address>
        <first-octet>10</first-octet>
        <second-octet>1</second-octet>
        <third-octet>1</third-octet>
        <fourth-octet>5</fourth-octet>
      <ip-address>
    <ip-addresses>
  • Inputs that use the same value should have the same name for consistency within a module. For example, in the case of host and host name, if these are each expecting a host name or IP address, they should be called host. Similarly, username and filename, when used as input or output parameter names, should be username and filename.  This rule should be followed for all similar names.
  • Whenever possible, the order of defining workflow input parameter names should be the same. For example, consider two workflows in the VMware Infrastructure adapter: Add Host to Cluster and Remove Host from Cluster:
    • In Add Host to Cluster, the first few inputs are:
      • adapter name
      • version
      • alternate username
      • alternate password
      • cluster compute resource inventory path
      • host name
    • In Remove Host from Cluster,the inputs are:
      • adapter name
      • version
      • alternate username
      • alternate password
      • host folder inventory path
      • host name
  • To be consistent, list the common inputs in each process first and then the unique inputs for each process as follows:
    • adapter name
    • version
    • alternate username
    • alternate password
    • host name
    • cluster compute resource inventory path
    • host folder inventory path

Context items or variables

  • Context item or variable names should be in lowercase. Multiword names should use spaces instead of camelCase or underscores.
  • Global context items and static context items should have the first letter capitalized. For example, use World Cup Soccer instead of World_Cup_Soccer.
  • The name should accurately describe the value it holds. For example, use change ID instead of index.
  • Acronyms and abbreviations should always be in uppercase in process names and input or output parameter names. Use IP instead of Ip, and CPU instead of cpu or Cpu, and number of CPUs instead of num CPUs.

Large context values and their proper usage

Valid responses from adapter calls, monitor events, or transforms can result in context items containing values larger than 100 KB. TrueSight Orchestration is built to handle variable sizes far greater than 100 KB; however, you must optimize workflows when passing these larger values between context items and as input or output parameters between workflows.

When a context item of 200 KB is assigned to another context item in a workflow, a copy of the data is made, so 400 KB of memory is used.  Likewise, when a context item with a value of size 200 KB is passed into a child workflow via an input parameter, the recipient local context item in the child workflow mapped to the input parameter will also contain a copy of the data, and so will consume an additional 200 KB of memory.

Problems can arise if the variable sizes are larger than 500 KB and there is a large concurrent job load of workflows passing around context items with such large values. A peer has a finite amount of memory allocated to the Java Virtual Machine (JVM) and developers must ensure that they make prudent use of the resources allocated to each peer on the grid:

  • Prior to production, identify large context values that could be introduced into a workflow.
  • If possible within the monitor or actor adapter configuration or within an adapter call, try to filter the specific data being returned.  For example, with a SQL monitor adapter, specify the columns that you are interested in specifically, instead of using *, the wildcard character.
  • After a large context value is present within a workflow, do not make copies of it unless your workflow logic specifically requires it.
  • Pass between workflows only the data that you will be using.
  • Consider filtering a large value down to contain only the data on which you will operate.  For example, consider the following scenario:
    • An adapter call returns an XML document with 1000 elements of size 500 KB.
    • A child workflow operates on 5 element values within this XML document.
    • In the parent workflow, transform the XML document by using an advanced XSLT transform to build a new XML document containing just the 5 element values.
    • Pass the output of the transform back into the same context item used as the input to the transform.
    • You have reduced an XML context item of 500 KB/1000 elements to 1–2 KB/5 elements.
    • When you pass the value as an input parameter to a child workflow, you consume only an additional 1–2 KB of memory, and not another 500 KB.

Workflow internals

When creating workflows, use the following guidelines for activities:

  • All Switch activities must be labeled with a question that yields either a yes or no, or some specific value (for example, File exists? or System type?)
  • All paths flowing from a Switch must be labeled with a representation of the resultant condition.
  • Include a labeled default path.
  • All activities must have a process-specific name and not the default name.

Module configuration

When creating node items in the module configuration, use the following format:

  • The first letter should be in uppercase.
  • Multiword names should be separated by an underscore, _.
  • When the module configuration refers to an application, the manufacturer and full application name must be used.

  • Restrict the use of module configuration elements to only the essential attributes needed to configure the module because all the elements defined in the module configuration are held as global variables.

    Note

    In 

    TrueSight Orchestration

     Platform, the use of global variables is very resource-intensive because whenever a global variable is accessed, it must be synchronized across the entire grid.

Module names

Historically, module names were generated by TrueSight Orchestration Development Studio as a two-part name linked together by SA (Service Actions/Run books), OA (Operation Actions), or AD (Adapter Wrappers), each of which instructs TrueSight Orchestration Development Studio of the location to display the module in the Project Explorer. Including an _ results in a space being displayed in TrueSight Orchestration Development Studio.

Depending on the solution, a module name should be chosen to give as much information as possible about its owner, contents, and function. For example, choose a name that identifies the vendor, solution, and function. The module name would be represented as Vendor-OA-Solution-Function. Do not use a hyphen within one of these individual entries, such as in a solution or function name that consists of multiple names. Instead use an underscore.

Examples:

  • AutoPilot OA Applications Utilities contain operations actions utilities
  • AutoPilot OA Change Management contains task management functions
  • VMWare OA Virtual Server Management contains reusable workflows for performing hypervisor actions
  • AutoPilot-SA-Network_Problem_Management is the run book for Network Problem Management
  • BladeLogic-SA-ITSM_Integration is the run book for BMC BladeLogic Server Automation to IT service management integration
  • Closed_Loop_Server-SA-Audit is the run book for continuous audit for server management
  • RBA-AD-Active_Directory is the adapter wrapper for the Active Directory actor adapter 
  • AO-AD-BMC_Database_Automation is the adapter wrapper for the BMC Database Automation actor adapter
  • AO-AD-Microsoft_Exchange is the adapter wrapper for the MS Exchange actor adapter

Folder names

Folder names should represent the category of activities that is performed by the processes contained in the folder. In multiword folder names, use an underscore or a space.

Examples:

  • Search contains processes that perform searches.
  • Standard OA folders are Setup_Validation, Search, Custom, and Utilities.

Process names

Top-level processes in any module should be composed of the base processes that implement the functionality of the solution being built. These base processes, at a minimum, should include Create, Update, and Delete actions. Design base processes to take a small number of complex XML inputs and to produce a small number of complex outputs. Categorize these inputs and outputs as follows:

  • Application details: <items/>
  • Network access: <ConnectionDetails/>
  • Process options: <ProcessOptions/>

Along with these base processes, create a series of helper processes to accept simple inputs that can construct the complex input required for the base processes.Create processes to accept simple input that will be transformed into the complex <items/>. Similarly, host name, user name, port, and so on will be transformed into <ConnectionDetails/>.

Example:

  • Create, Find, Delete, and Update will receive <items/> as input.
  • <items/> is constructed from input elements and other complex documents.

The processes that create the complex XML that will be used as input to base processes should be named Construct item for <XMLDocumentName/>.  For example, Construct item for Connection Details or Construct item for Configuration Item.

The names should reflect the action being taken by the process.  Examples of OA Utilities processes are: Create Object, Delete Object, Get Object, Put Object, and Perform Action (where Action consists of a verb and an object). These processes are expected to perform one action on an external system.

Examples: 

  • Get Routing Table
  • Perform Change Route
  • Perform Add Route
  • Delete Route
  • Create ARP Entry
  • Delete ARP Entry
  • Get ARP Table

Process descriptions

The process description should contain a concise description of the purpose and function of the process. Input and output descriptions should not be included in the process description.

Passing parameters between processes

Whenever possible, avoid using static XML as input to a transform or called process when other input parameters are available. For example, do not use a value of <empty/> as the input to a transform where all other data is contained in tokens to the transform.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*