Managing a workflow definition from the Orchestration CLI

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

Workflows begin with the schedule keyword, and after it you can add attributes and dependencies. To introduce a task in a workflow, place a colon delimiter before the task.

Each workflow definition has the following format and arguments:

Syntax

schedule [[folder/]workstation#][folder/]jobstreamname
    # comment
    [validfrom date]
    [timezone|tz tzname]
    [description ”text”]
    [draft]
    [ISSERVICE
      SERVICENAME "service_name"
      SERVICEDESCRIPTION "free_text"
      SERVICECONTACT "contact_information"
      SERVICETAGS "tag1|tag2"
      SERVICEVARIABLES
        [{
      "type" : "variable_type",
      "key1" : "value1",
      "key1" : "value1"
        }]
    [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]
       [({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]



   :

[trigger ”name”]
   [description ”text”]
   [correlationattributes ”correlated_attributes”]
   [timeout ”duration”]
   [triggerontimeout]
   [inorder]
   [conditions]
      [name ”condition_name”] [description ”text”] [type ”plugin_name/event_type”] [source ”eventsource_name”] [scope ”scope_type”] [filters ”filter_type + operator + value,  filter_type + operator + value,  ...”]

[job-statement...]
end

To define a workflow statement, see: Managing a task in workflow from the Orchestration CLI.

Arguments

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

Table 1. List of scheduling keywords
Keyword	Description
at	Using this keyword, you can define the earliest time in which workflows can run. When you define it in a run cycle, the keyword specifies the earliest time workflows 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 workflow. The line must begin with a number sign (#). In a workflow definition, comments can be added immediately after the line with the schedule keyword.
conditions	Using this keyword, you can define the event conditions that events received from the event source can match.
correlationattributes	Using this keyword, you can specify which filters in common between different events are required for the satisfaction of the event group.
deadline	Using this keyword, you can specify the time within which workflows or tasks should complete. When you define it in a run cycle, the keyword specifies the time within which a workflow or task should complete in that specific run cycle. For more information, see: Time restriction keywords.
description	Using this keyword, you can add a description. The content must be enclosed within double quotation marks. To use quotation marks ("), place a backslash (\) before.
draft	Using this keyword, the workflow 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 workflow definition syntax.
every	Using this keyword, you can define how often a workflow 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.
filters	Using this keyword, you can specify the filter type, the operator and the value that events must match to be received by the event source.
folder\|fol	Using this keyword, you can specify the item folder.
follows	Using this keyword, the workflow runs only after the predecessor workflows 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 workflow must not run. For more information, see: Run cycle keywords.
inorder	Using this keyword, you can specify that the events in an event group must be received in order to guarantee the satisfaction of the event group.
join	Using this keyword, you can define sets of conditional dependencies workflows. For more information, see: Dependency keywords.
jsuntil	Using this keyword, you can specify that a workflow should start before its latest start time even if one of the tasks contained in the workflow 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 workflow. For more information, see: Dependency keywords.
name	Using this keyword, you can specify the name of the event condition.
onuntil	When the until time has been reached, you can use this keyword to define the action to take on the workflow. 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 workflow must not run. on You can specify the days to be included in the run cycle, that is when the workflow must run. For more information, see: Run cycle keywords.
service	You can use this option to create a workflow as a service. For more information, see: Creating workflows as a service using Orchestration CLI.
schedule	The first keyword in a workflow, with the exception of comments. It can be followed by the on keyword.
schedtime	Using this keyword, you can specify the time of the workflow in the plan to determine predecessors and successors. For more information, see: Time restriction keywords.
scope	Using this keyword, you can specify the scope type of the event condition.
source	Using this keyword, you can specify the name of the event source the event is received from.
timeout	Using this keyword, you can specify a time duration after which the events in the event group are checked. If all the events are received before the timeout, the workflow goes from ADD to READY status and is launched. If all the events in the event group are not received by the timeout time, the workflow goes from ADD to SUPPR status.
timezone \| tz	Using this keyword, you can specify the time zone to use for the start time. For more information, see: Time restriction keywords.
trigger	Using this keyword, you can define the name of the event group associated with the workflow.
triggerontimeout	Using this keyword, if a timeout time is specified, the workflow is launched if the events in the event group are not satisfied within the specified timeout.
type	Using this keyword, you can specify the name of the plug-in the event is received from and the type of the event.
until	Using this keyword, you can define the latest start time of a workflow. If you specify it in a run cycle, it defines the latest start time for a workflow 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 workflow instance must start. For more information, see:Validity keywords.
validto	This keyword defines the date on which the workflow instance must end. The validto value is automatically set according to the validfrom date of the following version. 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 task name of a new task definition and it can cause errors during the creation process.

Examples

The following example defines the JS1 workflow that runs everyday. JS1 contains a task 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 workflow named JS2 that contains a task 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 workflow named JS3 that is valid since 31/03/2023 and has a dependency on JS1. The timezone of the workflow 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 workflow. For more information, see: validfrom / validto.

When you add or edit a workflow definition, also the attributes of its tasks are added or edited. When a workflow is adedd or replaced, any task changes apply also to all other workflows that use that task.

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

Time zone specification rules

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

Specifying a time zone at workflow 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 workflow level and at time restriction level. If it is not specified neither at workflow or at time restriction level, the workstation time zone is used.

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

Time restriction specification rules

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