Home | Table of Contents | ExecuteScript | CloverETL 4.6.1
--- | --- | ---
Prev | Job Control | Next

## ExecuteScript

# Not available in Community Designer

Short Description
Ports
Metadata
ExecuteScript Attributes
Details
Best Practices
See also

### Short Description

ExecuteScript is a component that runs either shell scripts or scripts interpreted by a selected interpreter. It either runs a script only once or the script is executed repeatedly for each incoming record. Each incoming record can redefine almost all parameters of run including the script itself.

### Icon

### Ports

Port type | Number | Required | Description | Metadata
--- | --- | --- | --- | ---
Input | 0 |  | Parameters of script run (including a script itself if needed). | Any
Output | 0 |  | Component input and results of a script run. | Any
Error | 1 |  | Component input and results of a script run. Records for scripts that cannot run or return 1. | Any

### Metadata

ExecuteScript does not propagate metadata from left to right or from right to left.

This component has metadata templates available. See general details on Metadata Templates.

Metadata template ExecuteScript_RunConfig available on first input port is described in Input Mapping Fields Description.

Metadata template ExecuteScript_RunResult available output ports is described in Output Mapping Fields Description.

### ExecuteScript Attributes

Attribute | Req | Description | Possible values
--- | --- | --- | ---
Basic
Script | no | Code of a script to be executed. If an interpreter attribute value is kept default, script must be a code of a shell script. Thus, it can easily be used for running one or more system commands. Otherwise, the code format depends on a chosen interpreter. |
Script URL | no | URL of a script to be executed. If an interpreter attribute value is kept default, script must be a code of a shell script. Thus, it can easily be used for running one or more system commands. Otherwise, the code format depends on a chosen interpreter. If both, script and script URL attributes are specified, only script URL is used. |
Script charset | no | This character encoding is used for an executed script file. A script file reference is specified either in 'Script URL' attribute or temporary batch file is created automatically from 'Script' attribute. The default encoding depends on DEFAULT_CHARSET_DECODER in defaultProperties. | UTF-8 (default) | <other encodings>
Working directory | no | Working directory of the executed script. All relative paths used inside the script will be interpreted with respect the this directory. By default it is set to the root of CloverETL project containing the graph. |
Timeout | no | A limit for script execution (in milliseconds). When a script runs longer than the limit the components kills it. In this case in the output record fields are set as follows: exitValue is set to 1, reachedTimeout to true and duration is greater or equal to timeout. | 0 (unlimited) | positive number
Input Mapping | no | Input mapping defines how data from incoming token overrides default component settings. See input mapping fields description | CTL transformation
Output Mapping | no | Output mapping maps results of successful script executions to the first output port. See output mapping fields description | CTL transformation
Error Mapping | no | Error mapping maps results of unsuccessful scripts to the second output port. See output mapping fields description | CTL transformation
Redirect Error Output | no | By default, results of failed scripts are sent to the second output port (error port). If this switch is true, results of unsuccessful scripts are sent to the first output port in the same way as successful scripts. | false (default) | true
Interpreter | no | Set an interpreter to be used for running a script. When an interpreter is executed `${}` is substituted with a name of a temporary batch file that contains a copy of the script. If an interpreter is sensitive to an extension of a script file, it is necessary to set Batch file extension property so that a temporary file will have the right extension. | A path to an interpreter followed by `${}`. By default a script is interpreted by a system shell (e.g. `cmd` in Windows and `sh` in Linux).
Environment variables | no | Sets environment variables values in the script. It allows either to setting or appending to them. Appending to a non-existing variable leads to defining it and setting its value. Note that variable values are only visible inside of a script, i.e. setting `PATH` cannot be used for setting path to an interpreter. Variable values set in this property can be overridden by mapping of input to EnvironmentVariables metadata in an input mapping dialog. If you are appending a value to the system variable (e.g.) $PATH, the correct system-dependent path delimiter should be used at the beginning of the appended value (colon on Linux, semicolon on Windows). |
Standard input | no | Contents of standard input that will be sent to the script. Be aware that if the script expects more input lines than available, it may hang. | string
Standard input file URL | no | File URL to contents of standard input that will be sent to the script. Be aware that if the script expects more input lines than available, it may hang. |
Standard output file URL | no | File URL of a file to store standard output of the script. The file content is either rewritten or appended depending on the append flag. |
Standard error file URL | no | File URL of a file to store error output of the script. The file content is either rewritten or appended depending on the append flag. |
Append | no | Sets whether standard output and error output written into files (attributes Standard output file URL and Error output file URL) should rewrite existing content or it should be appended. | false (default) | true
Data charset | no | Character encoding used to encode standard input passed from input port and to decode standard and error output to be passed to output ports. | UTF-8 (default) | <other encodings>
Batch file extension | no | Sets an extension of a batch file that is given to the interpreter (its name is substituted for `${}` in the interpreter setting). | `bat` (default) | string
Stop processing on fail | no | By default, any failed script causes the component stops executing other scripts and information about skipped tokens are sent to the error output port. This behaviour can be turned off by this attribute. | true (default) | false

| Note
The contents of `script` attribute are copied to a temporary batch file. On Microsoft Windows, it is often useful to start the script with `@echo off` to disable echoing the executed commands.

### Details

Input Mapping Fields Description
Output Mapping Fields Description

ExecuteScript runs a script with a given interpreter (default system shell by default).

When there is no edge connected to an input port, the component runs a script only once. One output record is produced in this case.

When there are records coming to an input port, one script execution per record is performed and one output record per script execution is produced.

If the script was successful the component continues with processing of next input tokens. Otherwise, component stops executing other scripts and from now all incoming tokens are ignored and information about ignored tokens are sent to error output port. This behaviour can be changed in parameter Stop processing on fail.

Output record contains all important information about a script run (times, exit value, error reports and standard output). Mapping of these values to user-defined output metadata can be defined in Output Mapping and Error Mapping attributes. If output mapping is empty, fields of RunStatus record are mapped to output by name.

All script execution parameters can be set via input records with use of Input Mapping attribute. The mapping sets which values for the input are used as script execution parameters. Input and output mapping are common to job control components.

A single run of a script is performed as follows:

- The script code is copied to a temporary batch file.

- An interpreter is run with a `${}` string substituted with the name of the temporary file

- When the script is over, the output record is produced and sent to first output port for successful runs and to second output port for unsuccessful runs.

For more detailed information see attribute description.

#### Input Mapping Fields Description

Input records can be mapped to two different metadata: RunConfig and EnvironmentVariables.

Fields of RunConfig have the following functionality:

Field | Description
--- | ---
script | Overrides component attribute Script
scriptURL | Overrides component attribute Script URL
scriptCharset | Overrides component attribute Script charset
interpreter | Overrides component attribute Interpreter
workingDirectory | Overrides component attribute Working Directory
timeout | Overrides component attribute Timeout
environmentVariables | Overrides component attribute Environment Variables. It is expected that the value contains a list of variable assignments delimited with ";". An assignment with simple "=" symbol assigns a value to an assigned environment variable. An assignment with "+=" symbol appends a value to an assigned environment variable.
stdIn | Overrides component attribute Standard Input
stdInFileURL | Overrides component attribute Standard Input File URL
stdOutFileURL | Overrides component attribute Standard Output File URL
errOutFileURL | Overrides component attribute Error Output File URL
append | Overrides component attribute Append
dataCharset | Overrides component attribute Data charset
scriptFileExtension | Overrides component attribute Script File Extension

| Note
In Input mapping, you can use the `$out.0.script` field to create a dynamic command line. Just map a script and its parameters onto the field. Example: `$out.0.script = "md5.exe " + $in.0.filePath;`

| Note
Environment variables provided to the executed script can be defined in three different ways. Use component's attribute Environmental variables for statical definition of environment variables. Variable names and values are defined once for all script executions. The output record EnvironmentVariables populated in Input mapping is the second way how the environment variables can be defined. Set of variable names is still statically defined by the record structure, but values of variables can be derived from input tokens. The most complex way how the environment variables can be defined is to populate environmentVariables field in the output record RunConfig in Input mapping. Value of this field has same syntax and meaning like component's attribute Environment variables. Both, set of variables and their values can be defined fully dynamically in this case.

| Note
If you want to append a string to an environment variable in Input mapping, use getEnvironmentVariables() CTL function. Example: `$out.1.PATH = getEnvironmentVariables()["PATH"] + ":" + $in.0.additionalPath;`

#### Output Mapping Fields Description

If output mapping is empty, fields of input record and result record are mapped to output by name.

Field | Description
--- | ---
stdOut | Standard output of a script.
errOut | Error output of a script.
startTime | Start time of a script.
stopTime | Stop time of a script.
duration | Duration of a script. (duration = stopTime - startTime)
exitValue | Value returned by the script. Typically 0 means no error, non-zero values stand for errors.
reachedTimeout | Boolean determining whether the script reached timeout.
errException | If the script call finished with error, it may contain an exception that caused the error. This happens only in situation when the script has not started (e.g. path to the script is not valid) or its run has been interrupted (e.g. when a timeout has been reached).
errMessage | Message reported by the exception in errException.

### Best Practices

We recommend users to specify Data charset.

If the script is in an external file (specified with Script URL), we recommend users to explicitly specify Script charset too.

### See also

SystemExecute
Common Properties of Components
Specific Attribute Types
Common Properties of Job Control

Prev | Up | Next
ExecuteProfilerJob | Home | Table of Contents | Fail