Overview

Scripts allows you to store scripts in the Universal Controller database.

When a task that specifies a stored script is executed, the script is transmitted to the remote machine for execution.

Note

There is a 1MB limit on the content size of scripts, whether the content is defined in the Script Details or a uploaded from a local file system (see Uploading a Script, below).

You can use scripts with the following task types: Windows, Linux/Unix, SAP, and File Transfer (UDM scripts for UDM File Transfer tasks).

You cannot import compiled executables into Scripts. The content of scripts must be text that can be processed by some shell, script host, or command interpreter.

You can embed Universal Controller variables in the script content. Embedded variables are resolved at trigger/run time before the script is sent to an Agent.

Controller variables can be passed as parameters, but the script still has to be written to parse the variables. However, you cannot pass variables as parameters that contain data longer than the parameter field (for example, SQL results).

For example, the following script shows how a Controller variable could be used.

#!/bin/bash
echo Task Name: ${ops_task_name}
echo Task Instance: ${ops_task_id}

Note

You also can enter a script directly into a Universal Template, but you cannot select a stored script.

Types of Scripts

There are five types of scripts:

Script	For use in Windows or Linux/Unix tasks.
SAP Definition	For use in SAP tasks.
UDM Script	For use in UDM File Transfer tasks.
Web Service Payload	For use in Web Service tasks.
Data	For use in a script or task (see Data Scripts, below).

Data Scripts

Data Scripts (Script Type = Data) are meant to be used with scripts and commands specified in tasks, and resolved when the script or command is executed. Data Scripts provide the script or command with access to a path on the UAG file system where the temporary Data Script content resides.

Note

Deleting a Data script is prohibited if it is referenced by one or more Universal Tasks or Universal Template Fields (Default Value).

Changing the type for a Data script is prohibited if it is referenced by one or more Universal Tasks or Universal Template Fields (Default Value).

The Tasks tab on the Script Details is enabled for Data scripts and lists Universal Tasks that reference the script via a mapped Script field.

Using Data Scripts in a Script

To use a Data Script with a script, embed the Data Script in any of the following:

Content of a Script specified in the Script field in a Linux/Unix or Windows task.
Content of a Data Script.
Universal Template Script (Script, Linux/Unix Script, or Windows Script field).

Using Data Scripts in a Task

To use a Data Script with a task, embed the Data Script in any of the following:

Command field in a Linux/Unix or Windows task
Parameters field in a Linux/Unix or Windows task

Note

Although you can embed a Data Script in the Command field or Parameters field of a Linux/Unix or Windows task, only scripts with Script Type = Script can be referenced in a Linux/Unix or Windows task; that is, it is the only type of script that is available for selection in the Linux/Unix or Windows task Script field.

Embedding a Data Script

To embed a Data Script, use the following Script Function:

Name	Description	Syntax
Return Path to Data Script	Used for embedding the path to a Data Script.	`${_scriptPath('<script_name>')`}

Note

_scriptPath requires Agent 6.4.0.0 or later.

Upon task instance execution, the Controller will resolve ${_scriptPath('<script_name>')} and replace it with a token representing the path to the embedded Data Script in the following format: $(ops_unv_script_path_<script-sys_id>).

For every Data Script embedded in a Data Script, the Controller will resolve ${_scriptPath('script_name')} (if Resolve UAC Variables is enabled for the Data Script), and look for additional Data Script references (and Resolvable Credentials references). This process will continue until no additional Data Script references are found.

For each Data Script reference, the Controller will send UAG the Data Script Content, file extension, and the corresponding token - $(ops_unv_script_path_<script-sys_id>) - that would represent a reference to that Content, which would ultimately be temporarily written to the UAG file system.

UAG will replace any tokens within the Script Content, Universal Template Script, Command, or Parameters with the appropriate file path associated with the Data Script Content. UAG also will replace any tokens within each Data Script Content.

Additionally, for a Universal Template, you can create a Field of Type = Script, which lets you select or create Data Scripts. The Controller will create a variable for the Data Script Field, which you can embed in the Universal Template script using the Script Functions. This also lets you change Scripts when you run a Universal Task based on the Universal Template.

Restrictions on Embedding Data Scripts

For every embedded Script, the Script Type must be Data; otherwise, the task will transition to the Start Failure status with one of the following status descriptions:

Execution for script "script-name", contained within the Universal Template Script, prohibited due to script type constraint; only Data script type permitted.

Execution for script "script-name", contained within the command field or parameters field prohibited due to script type constraint; only Data script type permitted.

Execution for script "script-name", contained within the script "script-name", prohibited due to script type constraint; only Data script type permitted.

For every embedded Data Script, the Execution User must have Execute permission for the Data Script; otherwise, the task instance will transition to the Start Failure status with one of the following status descriptions:

Execution for script "script-name", contained within a Universal Template Script or script, prohibited due to security constraints.

Execution for script "script-name", contained within a script, command field, or parameters field, prohibited due to security constraints.

Creating a Script

Step 1	From the Automation Center navigation pane, select Other > Scripts. The Scripts list displays a list of all existing scripts. To the right of the list, Script Details for a new script displays.
Step 2	Enter / select Details for a new script, using the field descriptions below as a guide. Required fields display an asterisk ( * ) after the field name. Default values for fields, if available, display automatically. To display more of the Details fields on the screen, you can either: Use the scroll bar. Temporarily hide the list above the Details. Click the button above the list to display a pop-up version of the Details.
Step 3	Click a button. The script is added to the Controller database, and all buttons and tabs in the Script Details are enabled.

Note

To open an existing record on the list, either:

Click a record in the list to display its record Details below the list. (To clear record Details below the list, click the New button that displays above and below the Details.)
Clicking the Details icon next to a record name in the list, or right-click a record in the list and then click Open in the Action menu that displays, to display a pop-up version of the record Details.
Right-click a record in the a list, or open a record and right-click in the record Details, and then click Open In Tab in the Action menu that displays, to display the record Details under a new tab on the record list page (see Record Details as Tabs).

Script Details

The following Script Details is for an existing script. See the field descriptions, below, for a description of all fields that display in the Script Details.

For information on how to access additional details - such as Metadata and complete database Details - for Scripts (or any type of record), see Records.

Script Details Field Descriptions

The following table describes the fields, buttons, and tabs that display in the Script Details.

Field Name	Description
Details	This section contains detailed information about the Script.
Name	Name of the script. This name can be the same as the name of the script file. You also can specify a file extension; the default file extension for Windows is `.bat`. If the name has the extension `.ps1`, Windows will run the script as a powershell script. You may have to create the appropriate file association and security for this to work.
Version	System-supplied; version number of the current record, which is incremented by the Controller every time a user updates a record. Click the Versions tab to view previous versions. For details, see Record Versioning.
Description	Description of this record. Maximum length is 255 characters.
Member of Business Services	User-defined; Allows you to select one or more Business Services that this record belongs to. (You also can Check All or Uncheck All Business Services for this record.) You can select up to 62 Business Services for any record type, and enter a maximum of 2048 characters for each Business Service. If the Business Service Visibility Restricted Universal Controller system property is set to true, depending on your assigned (or inherited) Permissions or Roles, Business Services available for selection may be restricted.
Script Type	Type of script: Options: Script SAP Definition UDM Script Web Service Payload Data
Resolve UAC Variables	Controls whether or not the Script will be parsed in pursuit of Universal Controller variables. It allows the Controller to avoid the overhead of parsing a Script that does not contain variables. Note Variables could be embedded with this field disabled; likewise, you could have a Script with no variables but have this field enabled. However, enabling this field for a Script that does not contain Controller variables will impose an unnecessary burden (however small) on the Controller.
Content	Content of the script or SAP definition file. You can enter content manually or upload content from the local file system by using the Upload Script button. For UDM Scripts, Source and Destination credentials are available for use. The credentials can be coded into the UDM script using the following File Transfer variables: ops_src_cred_user ops_src_cred_pwd ops_dst_cred_user ops_dst_cred_pwd The variables will be resolved by UDM internally. The following example illustrates the correct way to code them: The values for these variables are sent to UDM via stdin. This provides a secure channel where the credentials never show up in the script or on the command line.
Metadata	This section contains Metadata information about this record.
UUID	Universally Unique Identifier of this record.
Updated By	Name of the user that last updated this record.
Updated	Date and time that this record was last updated.
Created By	Name of the user that created this record.
Created	Date and time that this record was created.
Buttons	This section identifies the buttons displayed above and below the Script Details that let you perform various actions.
Save	Saves a new script record in the Controller database.
Save & New	Saves a new record in the Controller database and redisplays empty Details so that you can create another new record.
Save & View	Saves a new record in the Controller database and continues to display that record.
New	Displays empty (except for default values) Details for creating a new record.
Update	Saves updates to the record.
Upload Script	Allows you to upload a script from the local file system and place it in the Content field (see Uploading a Script, below).
Copy	Creates a copy of this script, which you are prompted to rename.
Delete	Deletes the current record.
Refresh	Refreshes any dynamic data displayed in the Details.
Close	For pop-up view only; closes the pop-up view of this task.
Tabs	This section identifies the tabs across the top of the Script Details that provide access to additional information about the script.
Tasks	Lists of all tasks using this script.
Notes	Lists all notes associated with this record.
Versions	Stores copies of all previous versions of the current record. See Record Versioning.

Uploading a Script

To upload a script into the Content field in the Script Details:

Step 1	Click the Upload Script button. The Script File Uploader pop-up displays.
Step 2	Click the Choose File button and select a script from the local file system.
Step 3	From the Select file encoding drop-down list, select the character set of the script: ISO-8859-1, US-ASCII, UTF-8, UTF-16, UTF-16BE, or UTF-16LE.
Step 4	Click the Submit button to add the script to the Content field.

Browser not supported