Managing a job stream definition from the Orchestration CLI

In this topic you can find the syntax to manage a job stream definition.

Job streams begin with the schedule keyword, and after it you can add attributes and dependencies. To introduce a job in a job stream, place a colon delimiter before the job.

Each job stream definition has the following format and arguments:

Syntax

schedule [[folder/]workstation#][folder/]jobstreamname
    # comment
    [validfrom date]
    [timezone|tz tzname]
    [description ”text”]
    [draft]
    [vartable [folder/]table_name]
    [freedays [folder/]calendarname [-sa] [-su]]
    [on [runcycle name
       [validfrom date] [validto date]
       [description ”text”]
       [vartable [folder/]table_name]]
      {date|day|[folder/]calendar|request|”icalendar”} [,...]
       [fdignore|fdnext|fdprev] (to verifiy)
       [({at time [+n day[s]] |
       schedtime time [+n day[s]]}
       [until | jsuntil time [+n day[s]] [onuntil action]]
       [every rate {everyendtime time[+n day[s]]}
       [deadline time [+n day[s]]])]]
    [,...]]

    [except [runcycle name]
          [validfrom date] [validto date]
          [description ”text”]
          {date|day|[folder/]calendar|request|”icalendar”| "cronexpression"} [,...]
          [fdignore|fdnext|fdprev]
          [{(at time [+n day[s]])] |
          (schedtime time [+n day[s]])}]
    [,...]

    [{at time [timezone|tz tzname] [+n day[s]] |
    schedtime time [timezone|tz tzname] [+n day[s]]}]
    [until | jsuntil time [timezone|tz tzname] [+n day[s]] [onuntil action]]
    [deadline time [timezone|tz tzname] [+n day[s]]]
    [matching {previous|sameday|relative from [+ | -] time to [+ | -] time|
      from time [+ | -n day[s]] to time [+ n day[s]] [,...]}]
    [follows {[workstation#]jobstreamname[.jobname |
      @] [previous|
      sameday|relative from [+|-] time to [+|-] time|
      from time [+|-n day[s]] to time [+|-n day[s]]
    ][if <condition> [| <condition>...]]
       } ] [,...]] [...]
   [join condition_name [number | numconditions | all] of
      description "..."
      .....
      endjoin]



   :


[job-statement...]
end

To define a job statement, see: Creating a job in job stream from the Orchestration CLI.

Arguments

The following List of scheduling keywords table contains a brief description of the job stream definition keywords.

Table 1. List of scheduling keywords
Keyword	Description
at	Using this keyword, you can define the earliest time in which job streams can run. When you define it in a run cycle, the keyword specifies the earliest time job streams can run for that specific run cycle. For more information, see:Time restriction keywords.
comment	Using this keyword, you can include comments in the definition of a job stream. The line must begin with a number sign (#). In a job stream definition, comments can be added immediately after the line with the schedule keyword.
deadline	Using this keyword, you can specify the time within which job streams or jobs should complete. When you define it in a run cycle, the keyword specifies the time within which a job stream or job should complete in that specific run cycle. For more information, see:Time restriction keywords.
description	Using this keyword, you can add a description of the job stream. The content must be enclosed within double quotation marks. To use quotation marks ("), place a backslash (\) before.
draft	Using this keyword, the job stream is saved as a draft and is not included in the plan generation process. For more information, see:Validity keywords.
end	Using this keyword, you close the job stream definition syntax.
every	Using this keyword, you can define how often a job stream must run. For more information, see: Run cycle keywords.
fdignore \| fdnext \| fdprev	Using this keyword, you can specify the rule to apply if the date selected as exclusion is on a non-working day.
folder\|fol	Using this keyword, you can specify the item folder.
follows	Using this keyword, the job stream runs only after the predecessor job streams have successfully completed, or one or more output conditions have been satisfied. For more information, see: Dependency keywords.
freedays	Using this keyword, you can specify the days during which the job stream must not run. For more information, see: Run cycle keywords.
join	Using this keyword, you can define sets of conditional dependencies job streams.Dependency keywords.
jsuntil	Using this keyword, you can specify that a job stream must start before its latest start time even if one of the jobs contained in the job stream starts running after that latest start time. It is mutually exclusive with the until keyword. For more information, see:Time restriction keywords.
matching	If not already specified, use this keyword to specify a matching criteria for the job stream. For more information, see: Dependency keywords.
onuntil	When the until time has been reached, you can use this keyword to define the action to take on the job stream. For more information, see:Time restriction keywords.
runcycle	Using this keyword, you can define the name of the run cycle. Use it together with one the following keywords: except You can specify the days to be excluded by the run cycle, that is when the job stream must not run. on You can specify the days to be included in the run cycle, that is when the job stream must run. For more information, see: Run cycle keywords.
schedule	The first keyword in a job stream, with the exception of comments. It can be followed by the on keyword.
schedtime	Using this keyword, you can specify the time of the job stream in the plan to determine predecessors and successors. For more information, see:Time restriction keywords.
timezone \| tz	Using this keyword, you can specify the time zone to use for the start time. For more information, see:Time restriction keywords.
until	Using this keyword, you can define the latest start time of a job stream. If you specify it in a run cycle, it defines the latest start time for a job stream for that specific run cycle. It is mutually exclusive with the jsuntil keyword. For more information, see:Time restriction keywords.
validfrom	Using this keyword, you can define the date from which the job stream instance must start. For more information, see:Validity keywords.
validto	Using this keyword, you can define the date on which the job stream instance must end. For more information, see:Validity keywords.
vartable	Using this keyword, you can specify the name of the variable table to be used by the run cycle. For more information, see: Data exchange and transformation

Note: It is important to correctly type the keywords, otherwise they are considered as the job name of a new job definition and it can cause errors during the creation process.

Examples

The following example defines the JS1 job stream that runs everyday. JS1 contains a job named JOBDEF1:
```
SCHEDULE WS_AGT_0#JS1
ON EVERYDAY
:
WS_AGT_0#JOBDEF1
END
```
After saving the definition, you can see it displayed as follows:
```
$jobstream

JOBSTREAM /WS_AGT_0#/JS1
  ON RUNCYCLE RC1 "FREQ=DAILY;"
:
  / WS_AGT_0#/JOBDEF1

END
```
The following example defines a job stream named JS2 that contains a job named JOBDEF1 that has a deadline set for 8 p.m. of the following day:
```
SCHEDULE /FOLDER1/JS2
:
JOBDEF1
  DEADLINE 2000 +1 DAYS ONLATE KILL
END
```
After saving the definition, you can see it displayed as follows:
```
$jobstream

JOBSTREAM /WS_AGT_0#/FOLDER1/JS2
:
  /WS_AGT_0#/ JOBDEF1
    DEADLINE 2000 +1 DAY ONLATE KILL
END
```

The following example defines a job stream named JS3 that is valid since 31/03/2023 and has a dependency on JS1. The timezone of the job stream is Europe/Berlin:

SCHEDULE WS_AGT_1#JS3
VALIDFROM 03/31/2023 TIMEZONE Europe/Berlin
DESCRIPTION "Sample Job Stream"
FOLLOWS WS_AGT_0#JS1.@
:
WS_AGT_1#JOBDEF1 
END

After saving the definition, you can see it displayed as follows:

$jobstream

# Sample Job Stream
JOBSTREAM /WS_AGT_1#/JS3
  VALIDFROM 03/31/2023 0000
  TIMEZONE Europe/Berlin
  DESCRIPTION "Sample Job Stream"
  FOLLOWS /WS_AGT_0#/JS1.@
:
  / WS_AGT_1#/JOBDEF1 
END

Comments

You can define different versions of the same job stream. For more information, see: validfrom / validto.

When you add or edit a job stream definition, also the attributes of its jobs are added or edited. When a job stream is adedd or replaced, any job changes apply also to all other job streams that use that job.

The same applies when you lock a version of the job stream: all versions of that job streams are locked too.

Time zone specification rules

Within a job stream definition, the time zone can be specified for the job stream (including all its keyword specifications), for each job statement included in the job stream definition, or it can be specified at time restriction level (using the at, deadline, schedtime, and until keywords).

Specifying a time zone at job stream level, the time zone applies both to the time definitions of the run cycle, defined with the on keyword, and to the time definitions specified with the time restrictions.

Time zones must be the same when you specify them both at job stream level and at time restriction level. If it is not specified neither at job stream or at time restriction level, the workstation time zone is used.

At job level, you can define a different time zone from the job stream level one; the time zone at job level overrides the one at job stream level. If it is not specified neither at job stream or job level, the time zone of the workstation that runs the job is used.

Time restriction specification rules

Time restrictions can be specified using the at, deadline, schedtime, and until keywords, both at job stream and run cycle level. If you specify both, the time restriction specified at run cycle level overrides the one at job stream level.