Designing the script body of a data retriever script

This topic provides a guideline for understanding the script body to enable you to create your own new data retriever scripts. The script body is the core of a script and is made up of various elements. These elements define what the script must do, how it must do it, and what result output it must provide.

You can access arguments values in a data retriever script by using the script_params dictionary. The script body elements for a data retriever automation script can be categorized as the upper section containing the constants (with integration server details) and the input arguments and the lower section or the main script body. The main script body includes routines (or functions), variables, and Gems.

• Upper section of the script
• Lower section or the main script body

Upper section of the script

The upper section of the script body consists of the input arguments defined in the script. The input arguments in a data retriever script define the output for a data retriever in the New Step dialog box. Arguments are set in a triple-commented block so that they are not executed with the script. Arguments use YAML format, which is a simple indent and colon notation. The argument name is defined followed with a colon. Any indented lines under the argument name are considered to be attributes of that argument. Attributes are indented with two spaces followed by a colon and a value.

For example, in the following figure adapter_name: is an argument and name is an attribute with a value description after the colon. You also see an attribute called required with the value yes. This indicates whether the field adapter_name must be a mandatory field or not. You see another argument called status with various attributes. This indicates that this data retriever automation script fetched information about the Status field and provides it to an automation script. The type attribute indicates the kind of output that must show in the New Step dialog box for the status field. In this case, it must be a list that allows you to select any item at a time as the specified value for the type attribute is in-external-single-select. This means that a data retriever script not only fetches particular data from an external system, but also decides how to display the output for that data, whether it must show as a list or a text box, and so on. The automation script merely uses a reference of the data retriever ID of the appropriate data retriever script to pull that data in the format (already decided) and display it in the New Step dialog box.

The following figure shows the upper section containing the input arguments for one of the data retriever automation scripts available with the product:

Upper section script body

Lower section or the main script body

The lower section or the main script body includes the logic that your script needs to execute for performing the required action. The main script body contains your Ruby code that indicates how the script must work and conditions, if any. The lower section includes various elements such as the constants (indicating the integration server details), routines (or functions), variables, and gems similar to that of an automation script. But there are some differences that occur in designing the lower section of a data retriever automation compared to that of an automation script. The following differences occur between a data retriever automation and an automation script:

• Unlike an automation script, the main script body of a data retriever automation script (excluding the constants or the integration server details) must be enclosed in the following framework in case of a data retriever automation script:

  def execute(script_params, parent_id, offset, max_records)
  Script logic or the main script body
  end

• In case of a data retriever script, you can specify the Render as output of the data retrieved to show as a List, Table, or Tree. Each of these outputs require a different way of designing the script. For more information about designing the script for rendering the various outputs, see Script-customizations-for-various-outputs.
• A data retriever script can be used for various purposes apart from only fetching certain data. It can also be used for retrieving external tickets (and adding them under a plan) and component mapping with an external object.

The lower section or the main script body includes the following elements:

• Routines (or functions): The automation engine uses several routines or functions to help with the scripting process. Routines are set directives that provide you the ability to set values for objects such as application, components, servers, and properties in BMC Release Process Management, from inside a script. You can use these directives to add or modify objects in the context of the step that is running. You can also update objects with information from an external system by using routines. For a list of routines supported, see Routines-for-local-ruby-scripts.
• Variables and constants: Variables store information about arguments that are in run time. Variable values are dynamically set and get added to the input file at run time. These variables are actually arguments that get converted into variables and get added in a YAML format in the input file at run time. Variables can be used for accessing the values stored in the arguments at run time. 
  Constants are another variant of variables that start with an uppercase letter. These are mostly used for adding details of an integration server in the default scripts provided in the product. For more information, see Variables-and-constants-for-automation-scripts.
• Gems: Gems are packaged Ruby libraries with a name and a version. These can be used for connecting to the external system and trigger an action by using various web services such as REST and SOAP API calls.