Designing the script body of a local ruby script

This topic provides a guideline for understanding the script body to enable you to create your own new local ruby scripts. The script body is the core of an automation script and is made up of various elements. These elements define what action the script must perform, what output it must provide once the action is performed, and the mechanism used for performing those actions.

The script body elements can be categorized as the upper section containing the arguments and the lower section or the main script body. The arguments include the input and output arguments. The main script body includes routines (or functions), variables, constants, 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 arguments defined in the script. Arguments are set in a triple-commented block so that they do not get 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. This indicates that when you select this script while creating a step, you can see a field with the label adapter_name. 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 in the New Step dialog box. The value of the attribute position indicates the exact location where the field adapter_name can be viewed in the New Step dialog box. The type attribute indicates the kind of output that must show in the New Step dialog box for the template_id field. In this case it must be a list that allows you to select any one item as the value. This is because the value for the type attribute is in-external-single-select. The external_resource attribute indicates that a resource automation script is being used to pull data for the template_id field. The value of this attribute, remedy-change-request-templates indicates the resource ID of the particular resource automation script that is being used to fetch data for the template_id field.

The following figure shows the upper section containing the arguments in the script body for one of the default scripts available with the product:

Upper section script body

_{(Click the image to expand it)}

Arguments can have attributes that are of two types:

• Input attributes—These arguments define the design of the New step dialog box that you see when you select the script on the Automation tab in a step. These arguments define what inputs you can provide in the step. These inputs are needed to execute the action that you want to perform by using the automation script. An automation script typically might refer to resource automation scripts for retrieving some necessary data from the external system. This data might be needed for the automation script to run successfully. For a list of input attributes that you can use while creating or updating a script, see Input-and-output-attributes-for-arguments.
• Output arguments—These attributes define the results that you want to see after the automation script is run and the step is completed. These results are available under the Notes tab when you open the step in which you used the automation script. For a list of output attributes that you can use while creating or updating a script, see Input-and-output-attributes-for-arguments.

The following figure shows a one-to-one mapping of the input arguments and attributes in the script body of the Remedy create change request automation script with the corresponding fields that show in the New Step dialog box:

Mapping of input arguments with fields in the New Step dialog box

_{(Click the image to expand it)}

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. As an automation author, you write your script and then assign it to a step. At run time, the script gets a header appended to it, that includes framework routines to facilitate the authoring process. The automation engine places 3 files on the filesystem as a part of each run of a step or script:

• Script file that contains the script that was run and the library files used for routines (or functions) used in the script. This file is used by the automation engine at the the time of executing the script at run time.
• Input file that contains a dictionary of properties and intrinsic values of the step or request that is running. Script arguments are accessed inside the script from the params dictionary. The input file becomes the params dictionary at run time. For information about the list of entries (variables) added to the input file at run time, see Variables-and-constants-for-automation-scripts.
• An output file that summarizes the run and gets the results. This file contains the entire automation script, contents of the input file, and the output results.

These files are placed in the automation results folder to form a repository of information on any specific run of automation in a step. This folder is placed outside of the BMC Release Process Management application directory so that it can persist between successive installs. The location path of this folder is BRPM_HOME/public/automation_results.

The following figure provides a simple sample of the main script body used in an automation script:

Sample main script body

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.

The following figure shows the constants (integration server details) and Gems for loading that are used in one of the automation scripts:

Constants and Gems used in the main script body

(Click the image to expand it)

The following figure shows the pack_response routine (or function) and the write_to command used for adding the output results of the automation script to results stream and the output file:

Routine and write_to command used in the main script body

(Click the image to expand it)