Creating Script automations

You can create an automation of type script by using the SSH provider. The Operating System of the endpoint system can be either UNIX (including AIX and Linux®) or Windows. For UNIX, the SSH provider executes a script using the default shell. Alternatively, a shebang (#!) can be used to execute the script in any scripting language the target system can interpret. The SSH provider does not require an additional agent as it uses a direct remote execution connection via SSH.

1. Create a Script connection. For more information, see Create a connection.
2. Create an automation of type script. Click Automations > New Automation. Complete the following fields:

   Type

   Select Script.

   If you want to run a script as an automation, you must configure a Script Automation Provider on the Connections page.

   Name

   Provide a name that describes what this automation does. For example, Find large file systems.

   Prerequisites

   If this automation requires prerequisites, add this information. For example, Db2 Version 10.5 or higher.

   Description

   Provide any helpful additional information so that the user can immediately understand which problem this automation solves.

   Shell

   Select Bash for scripts that run on UNIX systems using bash as the ssh shell. Within the script you can specify other script interpreters that are installed on the target system, for example python. See the item Script below for an example.

   Notes about how Runbook Automation invokes Bash scripts:

   • It generates a temporary file with the script content.
   • It exports parameters as environment variables.
   • It runs the temporary script file.
   • It deletes the temporary script file.
   • It returns the script return code of the temporary script execution.

   Select Powershell for scripts that run on Windows systems using powershell as the ssh shell (using cmd as the ssh shell is not supported).

   Notes about how Runbook Automation invokes Powershell scripts:

   • It assigns parameter values to variables with the selected type.
   • It executes the commands from the script.

   Script

   You can either select Import to select the script from your file system, or you can directly enter the script into the editor. If you selected Bash the script can only be run on UNIX systems using the default shell or the interpreter, which is specified after the shebang #!. If you selected Powershell the script can only be run on Windows systems using Powershell.

   Notes

   • Imported scripts must be in UTF-8 format if they contain non-ascii characters (for example, Chinese).
   • If the "Bash" shell type is selected, then any Windows line endings from the imported script are automatically converted to UNIX line endings.

   Examples

   1. Create a script automation with the following Bash script that uses the python interpreter:

      #!/usr/bin/env python3
      import os
      import platform
      
      print("Your message \'" + os.environ.get("message") + "\' is presented by python version " + platform.python_version())

      Create a parameter message and assign the default value Hello python to the parameter. Run the script on a target system where python3 is installed. The output looks similar to the following output:

      Your message 'Hello python' is presented by python version 3.9.13

   2. Create a script automation with the following Bash script that uses the IBM WebSphere Application Server CLI to start, stop, or get the server status of the server:

      $profilePath/bin/$serverAction.sh $serverName

      Create the parameters:
      • profilePath (the path name of the WAS profile, set the type to a single string, example default value: /opt/IBM/JazzSM/profile)
      • serverAction (the action to take on the WAS server, set the type to an enumeration of strings (serverStatus, startServer, stopServer), example default value: serverStatus)
      • serverName (the name of the WAS server, set the type to a single string, example default value: server1).
      Run the script on a target system where IBM WebSphere Application Server is installed and has administrative credentials configured in $profilePath/properties/soap.client.props. Alternatively, add parameters for the administrative user name and password and modify the CLI command accordingly.

   Automation output

   • Filter automation output By default, all automation output gets collected and printed to the automation output field. If you are only interested in a subset of the automation output (for example, because you want to create a chain of two automations within a runbook, where some particular information from the first automation is used as input to the second automation), then you can enable the Filter automation output toggle and specify a pattern that controls which part of the automation output gets returned.
   • Choose query syntax Depending on the type of output that gets created you can choose between three types of pattern-matching engines and their respective syntax:
     • XPath: best suited for parsing XML data
     • JSONPath: best suited for parsing JSON data
     • Regular expression: best suited for parsing unstructured data
   • Choose query syntax at runtime Select this check box if you want to allow the query syntax to be chosen when testing the automation, and also within the parent runbook. This check box is typically disabled. If this check box is enabled, the system property filter-syntax is added to the automation.
   • Enter query pattern Enter a pattern that is supported by the selected query syntax. For example, if the JSON output object is expected to contain an attribute called "version" and you selected the "JSONPath" query syntax, then you can use the query pattern "$.version" to pick the value of the version attribute out of the overall JSON output.
   • Enter query pattern at runtime Select this check box if you want to allow the query pattern to be chosen when testing the automation, and also within the parent runbook. If this check box is enabled, the system property filter-query is added to the automation.
   • Test output filter Click this link (or the Test button in the actions menu) when you are ready to test the automation. This saves the automation and directly opens the Test automation page for the current automation. For many developers, working with query patterns is an iterative process. Therefore it is recommended to enable Enter query pattern at runtime at least while you are developing the automation, and switch to Test automation to fine-tune the query pattern. The development of the query pattern is also supported within the Test automation page itself, where you can toggle between Show filtered output and Show unfiltered output after you have run the automation. You can also toggle between Edit automation and Test automation until you are satisfied with the result.

   Parameters

   Add input parameters to run the automation script. Those input parameters are available to the script as environment variables. For example, a parameter filesystem is used in a Linux script as $filesystem. The $ sign is automatically added to distinguish user-defined parameters from system parameters such as target and user. The parameter is exported without the dollar sign. Note: input parameter names must consist of alphanumeric characters and the underscore character only. System parameters are not available for use within your own script code. If you want to use some of that data within your script code, you must create related user-defined parameters. The following system parameters exist:

   target

   Mandatory parameter. Applies to automations of type Script. The target parameter is created to define the target machine where the script is running. By default, it is assumed that the SSH server on the target machine is listening on port 22. If a different SSH port is used, then set the value for the target parameter to hostname:port, for example, mytarget.mycompany.com:2022.

   user

   Mandatory parameter. Applies to automations of type Script. The user parameter defines the UNIX or Windows username that is used to run the script on the target machine.

   Note: If the value of the user parameter contains the @ symbol, for example an email address, the @ symbol and all characters that follow it are ignored.

   filter-syntax, filter-query

   These system parameters are added if you enable the related check boxes for automation output parsing.

3. Add the automation to the runbook, see Adding automations.
4. Run the runbook, see Run your first runbook.