Skip to end of metadata
Go to start of metadata

Introduction

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

Expressions are a means of dynamically calculating values for variables. Note that the 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:

Expressiontrue
JSON"var": true
Expressionfalse
JSON"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
JSON"var": "some value"
ExplanationUnquoted values that are added to the JOC Cockpit GUI are considered strings if they do not start with a digit, a Boolean value or the name of a built-in function.
Expression
'some value'
JSON"var": "'some value'"
ExplanationSingle quoted values are considered string constants.
Expression
"\t means the TAB control character"
JSON"var": "\"\\t means the TAB control character\""
ExplanationDouble quoted values can hold special special characters and variables. Inside double quotes backslashes are automatically doubled with the JSON storage format.
Expression
"\r means the CR control character"
JSON"var": "\"\\r means the CR control character\""
Expression
"\n means the LF control character"
JSON"var": "\"\\n means the LF control character\""
Expression
"\$ means the literal character"
JSON"var": "\"\\$ means the literal character\""
ExplanationA backslash can be used to escape the $ character that otherwise signals a variable. 

Number

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

Example:

Expression
1
JSON"var": 1
ExplanationNumeric values that are assigned without use of quoting are considered being numbers.
Expression
'05331'
JSON"var": "'05331'"
ExplanationNumeric values that are assigned with single quotes are considered being strings and for exapmle preserve leading zeros.

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 observed and should, for example, a number be compared with a string then the Order will fail.

Example:

Expression
$var >= 199
JSON"isGreater": "$var >= 199"

Arithmetic Operators

Addition and Subtraction of two numbers with: +, -

Examples:

Expression
1 + 1
JSON"var": 1 + 1
Expression
100 - 210
JSON"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"
JSON"var": "\"abc\" ++ \"def\""

Logical Operators

Evaluate a Boolean expression and if the result is false then an alternative value is returned.

Example:

Expression
false orElse true
JSON"var": "false orElse true"

Conversion

Convert to Number

If the value of a variable of the 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
JSON"var": "\"123\".toNumber"

Convert to String

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

Example:

Expression
123.toString
JSON"var": "123.toString"

Reading Variables

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. Note that the label is not quoted. Example: label=A.
    • job=<job> (optional) is the name of a job for which the variable is recalled. Note that the job name is not quoted. For example: job=MYJOB.
      • label and job cannot be specified at the same time
    • default=<default> (optional) specifies the default value if the variable does not exist.

Note that a call to the variable function will fail if the variable is unknown and a default value has not been specified. This function cannot be used within a Job Resource.

Examples:

Expression
variable( "my_var", job=my_job )
JSON"variable( \"my_var\", job=my_job )"
CommentThe 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" )
JSON"variable( \"my_var\", label=my_label, default=\"some value\" )"
CommentThe 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. Note that the name does not include the workflow folder location.
  • $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, for example, 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')
      JSON"env( 'JS7_AGENT_CONFIG_DIR' )"
      Sample Value/var/sos-berlin.com/js7/agent/var_4445/config
      Expression
      env( 'JAVA_HOME', '/usr/lib/jvm/java-1.8-openjdk' )
      JSON"env( 'JAVA_HOME', '/usr/lib/jvm/java-1.8-openjdk' )"
      Sample Value/usr/lib/jvm/java-1.8-openjdk
      Expression
      env( 'HOSTNAME', env( 'COMPUTERNAME', ' ' ) )
      JSON"env( 'HOSTNAME', env( 'COMPUTERNAME', ' ' ) )"
      Sample Value2021-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' )
      JSON"now( format='yyyy-MM-dd' )"
      Sample Value2021-05-03
      Expression
      now( format='yyyy-MM-dd hh:mm:ss' )
      JSON"now( format='yyyy-MM-dd hh:mm:ss' )"
      Sample Value2021-05-03 07:30:42
      Expression
      now( format='yyyy-MM-dd  hh:mm:ssZ', timezone="Europe/Berlin" )
      JSON"now( format='yyyy-MM-dd hh:mm:ssZ', timezone=\"Europe/Berlin\" )"
      Sample Value2021-05-03 09:30:42+02:00


  • scheduledOrEmpty( format='yyyy-MM-dd hh:mm:ss', timezone='Europe/Berlin' )
    • The date for which an order has been scheduled.
    • The date formatting options are the same as described 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 will not be 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' )

      JSON"replaceAll( $js7OrderId, '^#([0-9]{4}-[0-9]{2}-[0-9]{2})#.*$', '$1')"
      Sample Value2021-06-27

      This example extracts the daily plan date from the build-in $js7OrderId variable, for example it will extract the date from an Order ID such as #2021-06-27#P0000000412-jdScheduleBusinessDays .


  • 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 necessary to specify the requested Job Resource outside of the function. In fact the Controller reads the relevant variable values from the Job Resources indicated and adds them to an Order Variable that is considered final and cannot be modified later on.
    • This function can be used with the variable declaration of a workflow, with job arguments, node arguments and environment variables. When used with the declaration of an order variable with the workflow then the final data type has to be used.
    • Examples:

      Expression
      jobResourceVariable( 'database', 'db_user' )
      JSON"jobResourceVariable( 'database', 'db_user' )"
      Sample Valuescott
      Expression
      jobResourceVariable( 'database_' ++ $country, 'db_password' )
      JSON"jobResourceVariable( 'database_' ++ $country, 'db_password' )"
      Sample Valuetiger

      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>. This function cannot be used within a Job Resource.
    • Note the shorthand syntax which does not use brackets.
    • Examples:

      Expression
      JobResource:database_uk:db_user
      JSON"JobResource:database_uk:db_user"
      Sample Valuescott
      Expression
      JobResource:database_uk:db_user orElse 'scott'
      JSON"JobResource:database_uk:db_user orElse 'scott'"
      Sample Valuescott

      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.

  • toFile( string: <Content>, string: <FileSpecification>
    • The function returns the absolute path to a temporary file which holds the value of the specified <Content>. This can be a constant string or a variable of type string.
    • The file path is determined by the Agent using its JS7_AGENT_DATA/work/values directory and a temporary sub-directory.
    • The <FileSpecification> is used to determine the file extension, for example *.xml.
    • The function can only be used with JS7 - Job Resources and JS7 - Jobs.
    • Typical use cases include a situation when longer values for job resource variables or order variables are used and where these would be truncated when exposed as environment variables in shell jobs. In this situation the variable's value can be written to a temporary file and the job's environment variables receives the path to the temporary file. This can then be processed using, for example, OS commands.
    • Examples:

      Expression
      toFile( 'some long string value', '*.txt' )
      JSON"toFile( 'some long string value', '*.txt' )"
      Sample Value/home/sos/agent/var_4445/work/values/0/32.txt

Further Resources




  • No labels