Built-in variables you can use in flows

Edit online

Built-in variables are those defined by IBM Spectrum LSF Process Manager, where the value is obtained automatically by IBM Spectrum LSF Process Manager and made available for use by a flow. No special setup is required to use IBM Spectrum LSF Process Manager built-in variables. You can use these variables in many of the job definition fields in Flow Editor.

IBM Spectrum LSF Process Manager provides the following built-in variables:

Built-in variable

Description

Usage

%I

Index of a job array element.

You use the built-in variable %I to obtain the index of a job array element. You can use %I ion the Job Array Definition—Edit Job dialog, General tab, in the following fields:

  • Input file

  • Output file

  • Error file

Specify the variable as follows when you want to use its current value:

file_name.%I

Do not specify brace brackets and # sign.

%J

Job ID of a job array.

You use the built-in variable %J to obtain the job ID of a job array. You can use %J on the Job Array Definition—Edit Job dialog, General tab, in the following fields:

  • Output file

  • Error file

Specify the variable as follows when you want to use its current value:

file_name.%J

Do not specify # sign and brace brackets.

JS_FLOW_ID

Unique ID number of a flow.

You use the built-in variable JS_FLOW_ID when you need to use the unique ID number of a flow.

Specify the variable as follows when you want to use its current value:

#{JS_FLOW_ID}

JS_FLOW_NAME

You use the built-in variable JS_FLOW_NAME when you need to use the complete, unique name of a flow. The flow name is returned in the following format:

flow_ID:username:flowname

Specify the variable as follows when you want to use its current value:

#{JS_FLOW_NAME}

JS_FLOW_FULL_NAME

You use the built-in user variable JS_FLOW_FULL_NAME when you need to use the long version of a subflow name.

For example,

  • For a subflow named 11:usr1:F1:SF1:SSF1, this variable is set to 11:usr1:F1:SF1:SSF1.

  • For a main flow named 11:usr1:F1, this variable is set to 11:usr1:F1.

  • For a flow array element named 11:usr1:F1:FA(1), this variable is set to 11:usr1:F1:FA. Note that this does not include the array index. If you need to differentiate between array elements, you must use the JS_FLOW_INDEX built-in user variable.

#{JS_FLOW_FULL_NAME}

#{JS_FLOW_FULL_NAME}

(#{JS_FLOW_INDEX})
JS_FLOW_PROJECT

Specifies a project name. All jobs in the flow will have variable applied.

Flow admin and designers can define JS_FLOW_PROJECT in the flow attributes. The project name will be used for all work items (jobs, job arrays, submission forms) in a flow, unless the work item specifies its own project name.

A flow user can also specify a project name when triggering a flow or in a submission form.

The JS_FLOW_PROJECT is displayed in the flow detail page, the job detail page

Users can search or filter by project name in a Workload list.

 JS_FLOW_PROJECT can be applied to jobs, job arrays, job scripts, and submission forms. If used for job scripts, add the parameter "-P $JS_FLOW_PROJECT" to the script.
To trigger a flow and add a project name using command line:
jtrigger -v JS_FLOW_PROJECT=ppp1 <Flow Name>
You can specify a project name to a submission template for a flow definition. Modify the submission script by adding it the parameter:
PARAM_OPT="-v\"RUNASUSER=$EXECUTIONUSER;JS_FLOW_PROJECT=$FORM_PROJECT;"
FORM_PROJECT is the field ID defined in the template.
JS_FLOW_SHORT_NAME

Shortened version of the flow name to avoid a potential name conflict issue when using JS_PARENT_FLOW_VARIABLE_FILE to set parent flow variables.

For example, there are two dynamic subflows (DSF1 and DSF2) in a main flow (11:usr1:F1), that both refer to the same target flow (TF). If the target flow sets a parent flow variable myvar, both dynamic subflows will overwrite each other’s value of the myvar variable.

To prevent this issue, for all subflows and flow arrays in a triggered flow, use the JS_FLOW_SHORT_NAME variable to indicate the name of the subflow.

For example,

  • For a subflow named 11:usr1:F1:SF1:SSF1, this variable is set to SSF1.

  • For a main flow named 11:usr1:F1, this variable is set to F1.

  • For a flow array element named 11:usr1:F1:FA(1), this variable is set to FA. Note that this does not include the array index. If you need to differentiate between array elements, you must use the JS_FLOW_INDEX built-in user variable.

Set the parent flow variable to variable_name_#{JS_FLOW_SHORT_NAME} in the job.

For example, for the myvar variable name, the DSF1 dynamic subflow will set #{myvar_DSF1} and the DSF2 dynamic subflow will set #{myvar_DSF2}.

This allows both dynamic subflows to avoid variable name conflicts even though both dynamic subflows use the same target flow.

If you want to use an environment variable (such as myvar_$JS_FLOW_SHORT_NAME, you must list JS_FLOW_SHORT_NAME as an input variable for the flow or job).
JS_ITERATION_COUNTER

You use the built-in variable JS_ITERATION_COUNTER when you have specified a rerun exception handler for a flow or subflow, and you need to know how many times the flow or subflow has been rerun. The first time the flow or subflow is run, the value of JS_ITERATION_COUNTER is 0. If the flow or subflow is rerun, the counter is incremented. For example, if the value of JS_ITERATION_COUNTER is 3, the flow or subflow has been rerun three times—it is running for the fourth time.

Specify the variable as follows when you want to use its current value:

#{JS_ITERATION_COUNTER}
JS_EVENT[n]_FILENAME

You use the built-in variable JS_EVENT[n]_FILENAME when you need to use the name of the file that triggered this particular flow.

If a flow is triggered by multiple files, multiple variables are created, each with a different value for n. The value of n is determined by the position of the triggering event in the list of possible flow-triggering events, including all types of events.

Consider the following examples, where a flow definition is submitted with multiple events that can trigger the flow.

Example: one event at a time:

In this example, myflow is triggered to run under either of the following conditions:

  • At 5:00 p.m. on the first Thursday of the month (a time event)

  • If a file called payupdt arrives in the tmp directory

    Flow Attribute triggering events:

    First_thursday_of_month@Sys, 17:0

    "/tmp/payupdt" arrival

    Trigger flow when any event is true

    When the file /tmp/payupdt arrives, the name and value of the built-in variable are as follows:

    JS_EVENT[2]_FILENAME=/tmp/payupdt

    If the flow is triggered by the time event, no value is set for JS_EVENT[2]_FILENAME.

    Note that the value of n in the name of the variable corresponds to the position of the file event in the list of events.

Specify the variable as follows when you want to use its current value:

#{JS_EVENT[n]_FILENAME}

where n is the position of the triggering event in the list of possible events.
 

Example: multiple events

In this example, myflow is triggered to run when all of the following are met:

  • A file called payupdt arrives in the tmp directory

  • Today is Wednesday

  • The file /tmp/dbupdt exists

    Flow Attribute triggering events::

    "/tmp/payupdt" arrival

    Wednesdays@Sys, 0:0

    "/tmp/dbupdt" exist

    In this example, all of the conditions must be met before the flow is triggered. When the flow triggers, the names and values of the built-in variables are as follows:

    JS_EVENT[1]_FILENAME=/tmp/payupdt

    JS_EVENT[3]_FILENAME=/tmp/dbupdt

    Note that the value of n in the name of the variable corresponds to the position of the file event in the list of events.

  

JS_EVENT_n_FILENAME_BASE

Base file name, part of JS_EVENT[n]_FILENAME.

Specify the variable as follows when you want to use its current value:

#{JS_EVENT_n_FILENAME_BASE}