Execute Script
Run a script synchronously during the operation scope of the caller script.
Command availability: IBM RPA SaaS and IBM RPA on premises
Description
The Execute Script (executeScript) command loads a script and runs its commands synchronously during the operation of the script that called Execute Script. For reference, the script that uses the
Execute Script command is called caller script and the script referenced in the Execute Script command is called referenced script.
You can use Execute Script to load a local script or a script from a tenant of the IBM RPA server. The Bot Runtime caches the referenced script for subsequent use if you meet at least one of the following requisites:
- You are referencing a local script.
- You are referencing a specific version of script from a tenant.
If you don't meet any of the previous requisites, the Bot Runtime downloads the referenced script every time it calls Execute Script.
If the referenced script has input parameters, you can send initial values to these parameters, which means that these parameters, or variables, will hold the value you sent to them rather than their default values when the referenced script starts.
If the referenced script has output parameters, you can load their values to the caller script once the referenced script ends by binding these parameters to the caller script's variables.
The referenced script runs synchronously during the operation of the caller script. This means that, when Execute Script runs, the commands from the referenced script runs one by one while the caller script waits for this operation
to end. If the referenced script fails, you can either handle the error in the Execute Script command by enabling the Handle error (handleError) parameter or capture the error event with the Handle Error (onError) command.
Starting on version 21.0.3, if you enable the Handle error parameter and the script that Execute Script called fails, the error environment variable from the script running Execute Script will contain the error metadata from the script that failed. Read The error environment variable for details about what metadata the error environment variable stores.
Script syntax
IBM RPA's proprietary script language has a syntax similar to other programming languages. The script syntax defines the command's syntax in the script file. You can work with this syntax in IBM RPA Studio's Script mode.
executeScript [--handleError(Boolean)] [--isfromfile(Boolean)] --filename(String) --name(String) [--parameters(String)] [--output(String)] [--version(Numeric)] (Boolean)=value (String)=errormessage (Numeric)=linenumber (String)=errorsubname (Error)=error
Input parameter
The following table displays the list of input parameters available in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label.
| Designer mode label | Script mode name | Required | Accepted variable types | Description |
|---|---|---|---|---|
| Handle error | handleError |
Optional |
Boolean |
If enabled, prevents the caller script from failing if the referenced script fails. Sends the error status to the output variables. If disabled, the caller script raises an error if the referenced script fails. Starting on version 21.0.3, if you enable the Handle error parameter and the script that Execute Script called fails, the error environment variable from the script running Execute Script will contain
the error metadata from the script that failed. Read The error environment variable for details about what metadata the error environment variable stores. |
| File | isfromfile |
Optional |
Boolean |
If enabled, you must reference a local script by providing its absolute file path to the Filename parameter. If disabled, you must reference a script from an IBM RPA Control Center tenant in the Name parameter. Starting from 21.0.4, this parameter is deprecated. Use the Name parameter instead. |
| Filename | filename |
Required when the File parameter is True |
Text |
The absolute file path to the script that you want to run. Starting from 21.0.4, this parameter is deprecated. The data from this parameter is migrated to the Name input parameter automatically. |
| Name | name |
Required when the File parameter is False |
Text |
The name of the script from the tenant that you want to run. Starting from 21.0.4, it accepts either the absolute file path to the script or just the name of the script that you want to run. If only the name is specified, the script must be already published to the same tenant that you are logged in. |
| Parameters | parameters |
Optional |
Text |
Binds input parameters from the referenced script to values or variables from the caller script, loading the values from the caller script to the input parameters of the referenced script when the referenced script begins its operation. The parameter field references the input parameter variable from the referenced script.The value field must be either a value to send to its correlated input parameter or a variable from the caller script.
If you use a variable, the value stored in this variable is sent to the input parameter of the referenced script. |
| Outputs | output |
Optional |
Text |
Binds output parameters from the referenced script to variables in the caller script, loading the values from the output parameters to the variables of the caller script when the referenced script ends its operation. The parameter field references the output parameter variable from the referenced script.The value field references the variable in the caller script. |
| Version | version |
Optional |
Number |
The version of the script that you want to run. Leave empty to reference the production version. You can set version only when file is disabled.If you set version, the Bot Runtime caches the
script to improve performance. Otherwise, the Bot Runtime downloads the script on each run. |
Output parameter
| Designer mode label | Script mode name | Accepted variable types | Description |
|---|---|---|---|
| Success | value |
Boolean |
Returns status of the referenced script's operation. True if successful; False if the operation failed.You can only use this parameter if you enable Handle error. |
| Error message | errormessage |
Text |
Returns the error message that the referenced script raised if it failed. You can only use this parameter if you enable Handle error. |
| Error line number | linenumber |
Number |
Returns the line number where the error happened if the referenced script failed. You can only use this parameter if you enable Handle error. |
| Error routine name | errorsubname |
Text |
Returns the subroutine name where the error happened if the referenced script failed. You can only use this parameter if you enable Handle error. |
| Error | error |
Error |
Returns the error event's full details if the referenced script failed. You can only use this parameter if you enable Handle error. |
Example
The following code demonstrates how to run other scripts using the Execute Script command in the same scope of execution. This main script runs the sendEmail script, providing the destinatary email and the content
of the email as parameters after connecting to the email server.
defVar --name filePath --type String
defVar --name scriptFolderPath --type String
defVar --name userEmail --type String
defVar --name userPassword --type String
defVar --name emailConnection --type EmailConnection
defVar --name destinataryEmail --type List --innertype String
defVar --name emailBody --type String
defVar --name emailConnectionHost --type String
defVar --name emailPort --type Numeric
defVar --name runScriptSuccess --type Boolean
// Gets the Desktop folder from the system.
getSpecialFolder --folder "Desktop" filePath=value
// Connects to the email server.
add --collection "${destinataryEmail}" --value "user@example.com"
smtpConnect --smtphost "${emailConnectionHost}" --smtpport ${emailPort} --smtpusername "${userEmail}" --smtppassword "${userPassword}" emailConnection=value
executeScript --handleError --isfromfile --filename "C:\\Users\\ExampleUser\\Documents\\walscripts\\sendEmail.wal" --parameters "emailBody=${emailBody},destinataryEmail=${destinataryEmail},emailConnection=${emailConnection}" runScriptSuccess=value
emailDisconnect --connection ${emailConnection}
Use the following script to call it in the Execute Script command. This script sends an email with the parameters provided by the main script.
defVar --name emailConnection --type EmailConnection --parameter
defVar --name destinataryEmail --type List --innertype String --parameter
defVar --name emailBody --type String --parameter
// Sends an email with parameters provided by the script which called the current script.
emailSend --connection ${emailConnection} --to ${destinataryEmail} --bodytype "Text" --body "${emailBody}"