##### Page tree
Go to start of banner

# JS7 - Expressions for Variables

Go to start of metadata

# Introduction

Variables are assigned constant values and expressions. This applies to:

Expressions are a means to dynamically calculate values for variables. Consider that names of variables are case-sensitive.

Examples:

• `true`
• `1`
• `"some string"`
• `\$variable`
• `\$returnCode <= 3`
• `\$number + 1`

# Data Types

## Boolean

The following constant values are supported: `true, ``false`

Examples:

Expression `true` `"var": true`
Expression `false` `"var": false`

## String

Strings are written in double quotes. The control characters `\t` (tab), `\r` (CR) and `\n` (NL) are literally written. To suppress its special meaning the \$ character is written `\\$`. No other characters are allowed to follow the \ escape character.

Examples:

Expression ``"some value"`` `"var": "\"some value\""`
Expression ``"\t means the TAB control character"`` `"var": "\"\\t means the TAB control character\""`
Expression ``"\r means the CR control character"`` `"var": "\"\\r means the CR control character\""`
Expression ``"\n means the LF control character"`` `"var": "\"\\n means the LF control character\""`
Expression ``"\\$ means the literal character"`` `"var": "\"\\\$ means the literal character\""`

## Number

Numeric constants are implemented as Java  `BigDecimal` values and allow integer and long values to be specified.

Example:

Expression ``1`` `"var": 1`

# Operators

## Comparison Operators

The operators `<`, `<=`, `==`, `!=`, `>=`, `>` are supported.

The result of a comparison is the `Boolean` data type. Comparisons are available for strings and numbers. Both sides of a comparison have to use the same data type.

Should this rule not be considered and should e.g. a number be compared to a string then an Order will fail.

Example:

Expression ``\$var >= 199`` `"isGreater": "\$var >= 199"`

## Arithmetic Operators

Addition and Subtraction of two numbers with: +, -

Examples:

Expression ``1 + 1`` `"var": 1 + 1`
Expression ``100 - 210`` `"var": 100 - 210`

## String Operators

Concatenation of two strings with the` ++ `operator`.` Should operands of type Boolean or Number be used then they are converted to String.

Example:

Expression ``"abc" ++ "def"`` `"var": "\"abc\" ++ \"def\""`

## Logical Operators

Check a Boolean expression and if it evaluates to `false` then an alternative value is returned.

Example:

Expression ``false orElse true`` `"var": "false orElse true"`

# Conversion

## Convert to Number

If a value of a variable with String data type represents a number then it can be converted. Otherwise an error is raised and the affected order fails.

Example:

Expression ``"123".toNumber`` `"var": "\"123\".toNumber"`

## Convert to String

Values of the Number data type can be converted to String.

Example:

Expression ``123.toString`` `"var": "123.toString"`

## Referencing Variables

The syntax` \$VARIABLE`, `\$`VARIABLE`, ``\${VARIABLE}` or `\${`VARIABLE`}` is used to read the value of a variable.

• Similar to a number of Unix shells a variable can be recalled with \$ or with \${}.
• Variable names can include dots, however, not at the beginning and not at the end of the variable name and not as a sequence of dots.
• Variable names with dots have to be referenced like this: `\$`mail.smtp.host` `or `\${`mail.smtp.host`}`

If the variable is unknown then an error is raised and the affected Order will fail.

## Variable Function

Variables can be retrieved using the function

variable( string: <variable>, label=<label>, job=<job>, default=<default> )

• `<variable>` is a string expression for the name of the variable.
• `label=<label>` (optional) is the label of an instruction for which the variable is recalled. Consider that the label is not quoted. Example: `label=A`.
• `job=<job>` (optional) is the name of a job for which the variable is recalled. Consider that the job name is not quoted. Example: `job=MYJOB`.
• `default=<default>` (optional) specifies the default value should the variable not exist.

Consider that a call to the `variable` function will fail if the variable is unknown and no default value is specified.

Examples:

Expression ``variable( "my_var", job="my_job" )`` `"variable( \"my_var\", job=\"my_job\" )"` The value of the variable `my_var` is returned as available with the job `my_job` in a workflow. If the variable is unknown then the function fails.
Expression ``variable( "my_var", label=my_label, default="some value" )`` `"variable( \"my_var\", label=my_label, default=\"some value\" )"` The value of the variable `my_var` is returned as available with the job identified by the label `my_label` in a workflow. If the variable is unknown then the default value `some value` is returned.

# Built-in Variables

Built-in variables are available at the following scopes:

## Workflow

• `\$js7WorkflowPath`
• The unique name of a workflow. Consider that the name does not include the folder location of a workflow.
• `\$js7WorkflowPosition`
• The position of an order in the workflow.
• `\$js7Label`
• The label of the current instruction for which an order is executed.
• `\$js7OrderId`
• The order identifier.
• `\$js7ControllerId`
• The Controller's identifier as specified on installation.

## Job

• `\$js7JobName`
• The name of the current job for which an order is executed.
• `\$js7JobExecutionCount`
• A counter for the number of times that the same job node is executed within a workflow, e.g. if used with the JS7 - Retry Instruction
• `\$js7EpochMilli`
• The number of milliseconds since January 1st 1970 UTC.
• `\$returnCode`
• The numeric exit code of the current job for which an order is executed.

# Built-in Functions

• `env( string: <environment-variable>, string: <default> )`
• The function reads the value of an existing OS environment variable. The name has to be specified in correct uppercase/lowercase spelling.
• If the environment variable does not exist then an error is raised and the Order fails. Alternatively an optional default value can be specified.
• Examples:

Expression ``env( ('JS7_AGENT_CONFIG_DIR')`` `"env( 'JS7_AGENT_CONFIG_DIR' )"` `/var/sos-berlin.com/js7/agent/var_4445/config`
Expression ``env( 'JAVA_HOME', '/usr/lib/jvm/java-1.8-openjdk' )`` `"env( 'JAVA_HOME', '/usr/lib/jvm/java-1.8-openjdk' )"` `/usr/lib/jvm/java-1.8-openjdk`
Expression ``env( 'HOSTNAME', env( 'COMPUTERNAME' ) )`` `"env( 'HOSTNAME', env( 'COMPUTERNAME' ) )"` `2021-05-03 07:30:42`

This example assumes the `\$HOSTNAME` environment variable to be available for Agents running on Unix or the `%COMPUTERNAME%` environment variable to be available for Agents with Windows.

• `now( format='yyyy-MM-dd hh:mm:ss', timezone='Europe/Berlin' )`
• The job start date. This date can be formatted using Java date qualifiers. Optionally a time zone can be specified, by default the UTC time zone is used.
• Examples:

Expression ``now( format='yyyy-MM-dd' )`` `"now( format='yyyy-MM-dd' )"` `2021-05-03`
Expression ``now( format='yyyy-MM-dd hh:mm:ss' )`` `"now( format='yyyy-MM-dd hh:mm:ss' )"` `2021-05-03 07:30:42`
Expression ``now( format='yyyy-MM-dd hh:mm:ssZ', timezone="Europe/Berlin" )`` `"now( format='yyyy-MM-dd hh:mm:ssZ', timezone=\"Europe/Berlin\" )"` `2021-05-03 09:30:42+02:00`

• `scheduledOrEmpty( format='yyyy-MM-dd hh:mm:ss', timezone='Europe/Berlin' )`
• The date for which an order is scheduled.
• The date formatting options are the same as explained with the `now()` function.

• `replaceAll( string: String, regex: String, replacement: String)`
• Similar to the Java replaceAll method.
• Use of `\$` and `\` in `replacement`: If capturing groups from the `regex` are used in `replacement` e.g. `\$1` then  `\$1` is not a variable but an identifier of `replaceAll` similar to the Java method `replace(\$myString, 'x', '-->\$1<--')``replacement`.
• Examples:

Expression `replaceAll( \$js7OrderId, '^#([0-9]{4}-[0-9]{2}-[0-9]{2})#.*\$', '\$1' )` `"replaceAll( \$js7OrderId, '^#([0-9]{4}-[0-9]{2}-[0-9]{2})#.*\$', '\$1')"` `2021-06-27`

This example extracts the daily plan date from the build-in `\$js7OrderId` variable, e.g. from an Order ID `#2021-06-27#``P0000000412-jdScheduleBusinessDays` the date is extracted.

• `jobResourceVariable( string: <JobResource>, string: <Variable> )`
• The function provides access to JS7 - Job Resources: it reads from the Job Resource specified with the first argument and returns the value of the Job Resource variable specified with the second argument. The function is evaluated by the Controller when adding an order. It is therefore not required to specify the requested Job Resource outside of the function. In fact the Controller reads the respective variable values from the indicated Job Resources and adds them to an Order Variable that is consider final and cannot be modified later on.
• This function can be used with the variable declaration of a workflow only. It cannot be used with later job arguments or environment variables. When declaring the order variable with the workflow then the `final` data type has to be used.
• Examples:

Expression ``jobResourceVariable( 'database', 'db_user' )`` `"jobResourceVariable( 'database', 'db_user' )"` `scott`
Expression ``jobResourceVariable( 'database_' ++ \$country, 'db_password' )`` `"jobResourceVariable( 'database_' ++ \$country, 'db_password' )"` `tiger`

This example dynamically specifies the name of the Job Resource by concatenating the fixed value `'database_'` and the value of the `\$country` order variable.

• `JobResource:<JobResource>:<Variable>`
• The function returns the value of the specified `<Variable>` from the given `<JobResource>`.
• Consider the shorthand syntax that does not use brackets
• Examples:

Expression ``JobResource:database_uk:db_user`` `"JobResource:database_uk:db_user"` `scott`
Expression ``JobResource:database_uk:db_user orElse 'scott'`` `"JobResource:database_uk:db_user orElse 'scott'"` `scott`

This example reads the `db_user` variable from the `database_uk` Job Resource. If the variable does not exist then the default value `'scott'` is used.

• No labels
Write a comment…