Managing a run cycle group definition from the Orchestration CLI

In this topic you can find the syntax to manage a run cycle group definition.

A run cycle group acts as a container that evaluates rules in three layers:

Run cycle group: The top-level item. It holds global settings like the Non-working days calendar, which defines non-working days for the entire group, and a common variable table.
Subsets: Logical branches within the group. You use subsets to separate different scheduling scenarios, for example Standard Weekly vs. Month-End.
Run cycles: The individual rules within a subset. These are categorized as:
- Inclusive (ON): Define when the workflow should run.
- Exclusive (EXCEPT): Define when the workflow must be suppressed.

HCL Universal Orchestrator first calculates the dates within each subset using the internal AND/OR logic, and then merges all subsets together to create the final production plan.

If no folder is defined for an item, the default folder (/) is used. For more information, see: Configuring the Orchestration CLI.

You can move items to a specific folder by using the ocli model rename command.

Each run cycle group definition has the following format and arguments:

Syntax

runcyclegroup
[folder/]runcyclegroupname [description“text”]
      [vartable [folder/]tablename]
       [freedays [folder/]calendarname [-sa] [-su]]
[on [runcycle [folder/]name
        [validfrom date] [validto date]
        [description ”text”]
        [vartable [folder/]table_name]]
      {date | day | [folder/]calendar | ”icalendar” | "cronexpression" } [,...]
       [fdignore | fdnext | fdprev][subset subsetname AND | OR]
       [({at time [+n day[s]] |
       schedtime time [+n day[s]]}
       [until | jsuntil time [timezone|tz tzname][+n day[s]]
        [onuntilaction]]
       [every rate {everyendtime time[+n day[s]]}
       [deadline time [+n day[s]]])]]
    [,...]]
    [except [runcycle [folder/]name]
          [validfrom date] [validto date]
          [description ”text”]
          {date | day | [folder/]calendar | ”icalendar” | "cronexpression" } [,...]
          [fdignore | fdnext | fdprev]subset subsetname AND | OR  
          [{(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]] [onuntilaction]]
        [deadline time [timezone|tz tzname] [+n day[s]]]
end

Arguments

[folder/]runcyclegroupname

Using this keyword, you can define the name of the run cycle group, optionally preceded by the folder name within which the run cycle group is defined.

The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores.

description "description"

Using this keyword, you can define a description for the run cycle group.

The content must be enclosed within quotation marks ("), placing a backslash (\) before.

vartable "[folder/]tablename"

Using this keyword, you can define the name of the variable table to be used by the run cycle group.

[freedays [folder/]calendarname [-sa] [-su]]

Using this keyword, you can define the days during which the workflow must not run.

[folder/]calendarname: Using this keyword, you can define the name of the non-working days calendar for the workflow. You cannot use names of weekdays as calendar name. The default calendar holidays is used if the Calendar_Name is not in the database when the schedule command runs.
-sa: Using this keyword, you can define Saturdays as working days.
-su: Using this keyword, you can define Sundays as working days.

For more information, see freedays.

runcycle name

Using this keyword, you can define the name of the run cycle.

valid from date ... valid to date

Using these keywords, you can define the date from which the workflow instance is valid and is added to the production plan, and the date on which the workflow instance must end. The date specified in valid to is not included in the run cycle, so the workflow does not run on that day.

description ”text”

Using this keyword, you can define a description for the run cycle.

vartable

Using this keyword, you can define the name of the variable table to be used by the run cycle.

date

Using this keyword, you can define specific dates on which the run cycle must run. You can use the following syntax:

yyyymmdd [,yyyymmdd][,...]

In the following example, the workflow is scheduled to run on the 20th of July 2023 and on the 15th of August 2023:

on
20230720,20230815

day

Using this keyword, you can define one or more days on which the run cycle must run. You can use the following syntax:

{mo|tu|we|th|fr|sa|su}

In the following example, the workflow is scheduled to run every Friday:

on
fr

[folder/]calendar

Using this keyword, you can define the dates of a specific calendar, identified by its name. You can use the following syntax after the calendar name to define an offset:

{+ | -}n {day[s] | weekday[s] | workday[s]}

The following table provides a description of the keywords used in the above syntax:


Keyword	Description
n	Using this keyword, you can define the number of days, weekdays or workdays.
days	Using this keyword, you can define every day of the week.
weekdays	Using this keyword, you can define the days from Monday to Friday.
workdays	By default, using this keyword you can define the days from Monday to Friday. If you define different working days, this keyword identifies the days that are not included in the freedays nor in the holidays calendar.

icalendar

Using this keyword, you can set a recurrence rule that defines when the workflow must run. You can use the following syntax:

FREQ={DAILY|WEEKLY|MONTHLY|YEARLY}
[;INTERVAL=[-]n]
[;{BYFREEDAY|BYWORKDAY|BYDAY=weekday_list|
BYMONTHDAY=monthday_list}]

By default, the INTERVAL value is 1. If you define a value greater than 1, the count of the days starts from the validfrom value defined in the run cycle. If the INTERVAL has not been specified, the count of the days starts from 2020/01/01.

To define the recurrence rule, you can use the syntax described in the iCalendar syntax table:

Table 1. iCalendar syntax
Recurrence rule	Syntax	Notes
every n days	FREQ=DAILY[;INTERVAL=n]	The value set for valid from is the first day of the resulting dates.
every free or work days	FREQ=DAILY[;INTERVAL=n];BYFREEDAY\|BYWORKDAY
every n weeks on specific weekdays	FREQ=WEEKLY[;INTERVAL=n] ;BYDAY=weekday_list ;BYDAY=weekday_list	The value set for weekday_list is `[SU][,MO][,TU][,WE][,TH][,FR][,SA]`
every n months on specific dates of the month	FREQ=MONTHLY[;INTERVAL=n] ;BYMONTHDAY=monthday_list	The value set for monthday_list is represented by a list of `[+number_of_day_from_beginning_of_month] [-number_of_day_from_end_of_month] [number_of_day_of_the_month]`
every n months on specific days of specific weeks	FREQ=MONTHLY[;INTERVAL=n] ;BYDAY=day_of_m_week_list	The value set for day_of_m_week_list is represented by a list of `[+number_of_week_from_beginning_of_month] [-number_of_week_from_end_of_month] [weekday]`
every n years	FREQ=YEARLY[;INTERVAL=n]	The value set for valid from is the first day of the resulting dates.

Examples

In the following example, a workflow is scheduled to run every three days:
```
FREQ=DAILY;INTERVAL=3
```
In the following example, a workflow is scheduled to run every fourth workday:
```
FREQ=DAILY;INTERVAL=4;BYWORKDAY
```
In the following example, a workflow is scheduled to run every two weeks on Monday and Tuesday
```
FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TU
```
In the following example, a workflow is scheduled to run every 3 months on the 7th and on the last day of the month:
```
FREQ=MONTHLY;INTERVAL=3;BYMONTHDAY=7,-1
```
In the following example, a workflow is scheduled to run every two months on the 3rd Tuesday:
```
FREQ=MONTHLY;INTERVAL=2;BYDAY=3TU
```
For a workflow that is scheduled to run every 5 years the value is:
```
FREQ=YEARLY;INTERVAL=5
```

cronexpression

Using this keyword, you can enter a Cron expression and use it as base for the excluding run cycle.

HCL Universal Orchestrator accepts both Crontab and CronTrigger expressions, but when you enter a Crontab expression, it is converted into a CronTrigger expression.

Crontab and CronTrigger expressions have different structures, and sometimes the differences might change the original meaning of the expression:

Specifying month and week days: In CronTrigger expressions, you cannot define both the day of the month and the day of the week, while in Crontab expressions you can define both.

Day of week: Both CronTrigger and Crontab expressions accept the 3 characters day name format and the number of the day format.; In Crontab expressions, you can define the day of the week using the 0-6 (Sunday to Saturday) or 1-7 (Sunday to Saturday) format, but in CronTrigger expression the only number of the day format that is accepted is 1-7 (Sunday to Saturday).

runcyclegroup

Using this keyword, you can define one or more run cycles that can be grouped to define a set dates in which the workflow is scheduled to run. You can use the following syntax:

$RCG
                                    runcyclegroup

fdignore|fdnext|fdprev

Using this keyword, you can define the rule to apply if the date selected as exclusion is on a non-working day. The available keywords are:

fdignore: Using this keyword, the date is not added.
fdnext: Using this keyword, the added date is the nearest workday after the non-working day.
fdprev: Using this keyword, the added date is the nearest workday before the non-working day.

[subset subsetname AND|OR]

subset subsetname: Using this keyword, you can define a name for the subset. By default, it is SUBSET_1.
AND|OR: Using this keyword, you can define the logical AND relationship for run cycles within a subset, if the run cycle groups result is a positive date or set of dates. By default, is OR.

at time [timezone | tz tzname][+n day[s]]

Using this keyword, you can define the earliest time a workflow can run for a specific run cycle.

time: Using this keyword, you can define a time of the day from 0000 to 2359.
tzname: Using this keyword, you can define the time zone to use. The default time zone is the one on the workstation on which the workflow or task runs.
Time zones must be the same if at time and until or deadline time have been specified.
n: Using this keyword, you can extend the value of time, defining a number of days.

schedtime time [timezone|tz tzname][+n day[s]]: Using this keyword, you can define the time of the workflow in the plan to determine predecessors and successors.

time: Using this keyword, you can define a time of the day in the HHHHmm format. Possible values are from 0000 to 2359, or 0000 + <number of days>, where the value of the number of days can be from 1 to 100 days.
tzname: Using this keyword, you can define the time zone to use. The default time zone is the one on the workstation on which the workflow or task runs.
See Managing time zones for time zone names.
n: Using this keyword, you can extend the value of time, defining a number of days.

[until time [timezone|tz tzname][+n day[s]][onuntil action]]

Using this keyword, you can define the latest start time of a workflow or task. It is mutually exclusive with jsuntil, which is the default value. For more information about the jsuntil keyword, see jsuntil.

time

Using this keyword, you can define a time of the day from 0000 to 2359.

tzname

Using this keyword, you can define the time zone to use. The default time zone is the one on the workstation on which the workflow or task runs.

Time zones must be the same if until time and at or deadline time have been specified. See Managing time zones for time zone names.

n

Using this keyword, you can extend the value of time, defining a number of days.

action

Using this keyword, you can define the action to take when the until time has expired, either on a task that has not yet started or on a workflow that has not completed.

In the following table, you can find the supported onuntil action values:


Action	Description
hold	The task or workflow and any dependent tasks or workflows do not run. This is the default action. When the until time has expired, the workflow status that is displayed is based on the status of the tasks included in the workflow. The suppressed task or workflow keeps its status in READY. The successors keep the HOLD status.
cont	The task or workflow can start running when all the dependencies have been satisfied, even if the until time has expired. When the until time elapses, an event is generated.
canc	A task or workflow must be cancelled and all the dependencies of the successors are released.

If you do not define an until time for the task and define a deadline time with an onlate kill action, the until keyword is automatically set to the same time as the deadline keyword. As a result, if the task has not yet started, it does not run.

[jsuntil time [timezone|tz tzname][+n day[s]] [onuntilaction]]

Using this keyword, you can define the latest start time of a workflow. You can use this keyword to define that a workflow that has started running before its latest start time must complete 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 until and onuntil.

time: Using this keyword, you can define a time of the day from 0000 to 2359.
tzname: Using this keyword, you can define the time zone to use. The default time zone is the one on the workstation on which the workflow or task runs.
n: Using this keyword, you can extend the value of time, defining a number of days.

action

Using this keyword, you can define the action to take on a workflow when the defined until time has expired, but the workflow has not completed in SUCC status.

In the following table, you can find the supported onuntil action values:


Action	Description
hold	The task or workflow and any dependent tasks or workflows do not run. This is the default action. When the until time has expired, the workflow status that is displayed is based on the status of the tasks included in the workflow. The suppressed task or workflow keeps its status in READY. The successors keep the HOLD status.
cont	The task or workflow can start running when all the dependencies have been satisfied, even if the until time has expired. When the until time elapses, an event is generated.
canc	A task or workflow must be cancelled and all the dependencies of the successors are released.

every rate {everyendtime time[+n day[s]]}

Using this keyword, you can define how often a workflow must run.

rate

Using this keyword, you can define how often the instances of the workflow are launched. It is expressed in hours and minutes (hhmm).

everyendtime

time: Using this keyword, you define the time after which workflow instances cannot run anymore. It is expressed in hours and minutes (hhmm).

n: Using this keyword, you can extend the value of everyendtime, defining a number of days.

Example

The following example shows how to define a run cycle group that manages the lead time for a business process. In this scenario, the RCG_PREP_SESSIONS group generates dates that occur three workdays before the target dates defined in a master calendar. This ensures that a preparation workflow always completes ahead of the main event, automatically accounting for weekends and holidays.

 $runcyclegroup

RUNCYCLEGROUP /RCG_PREP_SESSIONS
  DESCRIPTION "Lead time logic: 3 workdays before monthly board meeting"
  FREEDAYS /CORPORATE_CAL
  ON RUNCYCLE RC_PREP_WINDOW DESCRIPTION "Trigger 3 workdays before the dates in BOARD_MEETINGS calendar" /BOARD_MEETINGS -3 WORKDAYS FDPREV SUBSET SUBSET_PREP OR
  ( AT 0900 TIMEDEP  )
  EXCEPT RUNCYCLE RC_EXCLUDE_BLACKOUT DESCRIPTION "Suppress preparation during blackout periods" /BLACKOUT_CAL SUBSET SUBSET_PREP AND
  ( AT 0900  )
END