Managing a task in workflow from the Orchestration CLI

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

In a HCL Universal Orchestrator distributed environment, tasks can be defined either independently from workflows or within a workflow definition.

Note: Because a task in a workflow is identified only by its name, tasks with the same name require an alias even if their definitions have different workstations or folders.

Syntax

You can use the following syntax for the task statement:

#comment job_name [as job_alias]
[outcond joboutputcondition interval seconds]
[{at time [timezone|tz tzname] [+n day[s]] | schedtime time [timezone|tz tzname] [+n day[s]]}]
[until time [timezone|tz tzname] [+n day[s]][onuntil action]]
[deadline time [timezone|tz tzname] [+n day[s]][onlate action]] 
[maxdur time | onmaxdur action] [mindur time | onmindur action]
[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] [confirm]   [nop]

Note: The job_name can either refer to an existing task or to a new one:

To add a task already defined in the database, use the following syntax: [[folder/]workstation#][folder/]jobname.
To add a new task that does not exist in the database, define it using the same syntax of the task definition: Task definition syntax.
To create an embedded task in a workflow, see Creating an embedded task in a workflow.

You can edit task definitions from a workflow definition; any change is also applied to the task definitions stored in the database. For example, if you edit the task definition of task_a in the js_a workflow definition, and task_a is also used in the js_b workflow, the definition of task_a in js_b changes accordingly.

Arguments

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

Table 1. List of scheduling keywords
Keyword	Description
at	Using this keyword, you can define the earliest time in which tasks can run. When you define it in a run cycle, the keyword specifies the earliest time tasks 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 task. The line must begin with a number sign (#). In a task definition, comments can be added immediately after the line with the schedule keyword.
confirm	Using this keyword, you can change the status of a task after it finishes. For more information, see: confirm
deadline	Using this keyword, you can specify the time within which tasks should complete. When you define it in a run cycle, the keyword specifies the time within which a task 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 task. The content must be enclosed within double quotation marks. To use quotation marks ("), place a backslash (\) before.
folder\|fol	Using this keyword, you can specify the item folder.
follows	Using this keyword, the task runs only after the predecessor tasks have successfully completed, or one or more output conditions have been satisfied. For more information, see: Dependency keywords.
join	Using this keyword, you can define sets of conditional dependencies tasks. For more information, see: Dependency keywords.
maxdur	Using this keyword, you can specify the maximum length of time a task can run. For more information, see: Time restriction keywords.
mindur	Using this keyword, you can specify the minimum expected time for the task to complete. For more information, see: Time restriction keywords.
nop	Using this keyword, you can specify that the task must not run when the plan runs. For more information, see: nop.
onlate	Using this keyword, you can define the action to take on a task in the workflow when the deadline of the task has expired. For more information, see: Time restriction keywords.
onuntil	When the until time has been reached, you can use this keyword to define the action to take on the task. For more information, see:Time restriction keywords.
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.
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 task. If you specify it in a run cycle, it defines the latest start time for a task for that specific run cycle. It is mutually exclusive with the jsuntil keyword. For more information, see: Time restriction keywords.

For the other keywords refer to Managing a task definition from the Orchestration CLI.

Comments

When you define a task in a workflow definition, the new task definition is added to the database, and then it can be referenced from other workflows.

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.

When you change the name of a task defined in a workflow version, the new name is applied in all the other versions of the workflow. Internal and external workflow associations remain consistent when you apply changes. For more information about workflow versions, see: Managing a task in workflow from the Orchestration CLI.

Note: The plan does not run the tasks that are scheduled to run on workstations that are marked as ignored, even if they are added to it because the workflow that contains them is scheduled to run on an active workstation.

Examples

The following example defines a workflow that contains an executable task:

SCHEDULE WF1
:
TASK1
  TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl" xmlns:jsdle="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdle">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>dir</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
  DESCRIPTION "Sample jsdl Task Definition"

END

After saving, the definition is displayed as follows:

$jobstream

jobstream /WS_AGT_0#/WF1
:
  /WS_AGT_0#/TASK1
END

The following workflow definition contains already existing and defined tasks:

schedule WS_AGT_1#WFWJ:
  WS_AGT_0#task1
  WS_AGT_0#task2
    follows WS_AGT_0#task1
end

Creating an embedded task in a workflow

You can create independent tasks within the workflow. This ensures greater customization, and control without being affected by external changes in the task definition. You can fully customize tasks inside a workflow tailored for your needs.

You can edit the workflow definition to add an embedded task. This type of task is correlated to the corresponding workflow. Traditionally, when creating a task definition for a workflow, any later changes to the task itself reflect on the workflow. This cannot happen with the embedded task that exists only inside the workflow definition.

You can add the entire task definition within the workflow as embedded that ensures the task is not impacted by external updates, as the updates must happen to the workflow itself. This approach creates greater flexibility and control over the specific task parameters used within the workflow. You need to run the display workflow (job stream | js) command to view embedded jobs. The entire embedded definition is displayed in such cases and to modify it, you need to run the modify workflow (job stream | js) command. You can add the embedded task definition as follows in a workflow:

Syntax


  jobs:
  - workstation: worstation_name
    name: JOB_name
    jobDefinition: 
        Specify the job_deinition

workstation: Mandatory parameter and specify the workstation for the task.

name: Mandatory parameter and specify a name for the task. You can provide any alphanumeric value and wildcard characters. You can use a maximum of 64 characters.

jobDefinition: Specify the job definition.

Important: If you are using schedlang format, use the BUILTIN parameter to create the definition. For more information, see Example.

Example

You can create a workflow definition as follows to add an embedded task that can run the ls command.

---
kind: JobStream
def:
  folder: /
  name: JS_EMBEDDED
  workstation: /WS_AGT_0
  description: Job stream containing an embedded job
  jobs:
  - workstation: /WS_AGT_0
    name: JOB_EMBEDDED1
    jobDefinition:
      workstation: /WS_AGT_0
      type: executable
      task:
        executable:
          interactive: false
          suffix: ""
          script: ls
          credential: {}
      recovery:
        action: STOP
        repeatAffinity: false

If you are using schedlang format, create the definition as follows:

$jobstream

JOBSTREAM /WS_AGT_0#/JS_EMBEDDED
  DESCRIPTION "Job stream containing an embedded job"
:

  /WS_AGT_0#JOB_EMBEDDED1 BUILTIN
    TASK
      {
        "executable" : {
          "interactive" : false,
          "suffix" : "",
          "script" : "ls",
          "credential" : { }
        }
      }
    RECOVERY STOP
    END