MODIFY_TASK

Use the MODIFY_TASK script function to modify active STANDARD Workflows and tasks in active STANDARD Workflows. You cannot use it with IF or FOREACH Workflows. MODIFY_TASK lets you change task properties for a particular Workflow, without editing the object definitions. The task properties in the Workflow override the settings in the object definition. For more information, see Task Properties in Workflows .

This page includes the following:

Overview

Before and after making modifications with MODIFY_TASK, you must always change the Workflow status with preliminary MODIFY_TASK script lines. Follow this sequence when you modify a Workflow with MODIFY_TASK:

  1. Use MODIFY_TASK with the STOP_MODIFY parameter to stop the Workflow and allow editing.
  2. Use MODIFY_TASK with other parameters to make one or more modifications to the Workflow.
  3. Use MODIFY_TASK with the COMMIT parameter to activate your modifications.
  4. Use MODIFY_TASK with the GO parameter to start the Workflow.

Syntax and Parameters

The basic syntax of this script function contains the following elements:

MODIFY_TASK (RunID, parameters, KEYWORD)

Where:

  • MODIFY_TASK

    Modifies an active Workflow

  • RunID
    RunID of the active Workflow to modify

  • parameters
    One or more parameters specify which task to modify, or other parameters depending on the modification

  • KEYWORD
    Specifies the action to take
    All available keywords are described in this topic.
    Note: Some keywords have additional parameters after the keyword.

Important!

  • You must write the parameters of MODIFY_TASK in the order in which they are shown in the syntax samples in this topic.
  • You must use commas as shown in the syntax samples even if you omit individual parameters.

Several modifications that you can perform with MODIFY_TASK require you to specify a particular task. Use one or both of the following parameters to specify the task:

  • task name
    Name of the task
    Note: Use START or END when you want to modify the start or end box of a Workflow.
    Format: script literal, number, or script variable.

  • sequence number
    Sequence number of the task
    The sequence number refers to the number within the Workflow, such as 3 for the third task. The sequence number is displayed in the task box in the Workflow editor. The sequence number is not the RunID. For more information, see Task Boxes in Workflows .
    Format: script literal, number, or script variable.

Notes:

  • If you specify both the task name and the sequence number, ensure that they match the same task.
  • If there are several tasks with the same name in the Workflow and you do not specify a sequence number, the system uses the task that has the lowest number.

Sample Scenario

You want to add two tasks to a Workflow when the Workflow is active. This example demonstrates how to combine MODIFY_TASK functions with several different keywords to add and place the tasks, and create the required dependencies.

Prerequisites:

  • Workflow object
    For the purposes of this example, the Workflow currently has one child task.
  • Two executable objects (Task.01 and Task.02)

Goals:

  • Both tasks are dependent on their predecessors in the Workflow:
    • Task.01 starts when the Workflow starts.
    • Task.02 starts after Task.01 finishes.
  • The Workflow ends when Task.02 finishes.

Write the following script on the Process page of the child task that is currently in the Workflow.

Syntax

:SET &RUNID# = SYS_ACT_PARENT_NR(ACT)

:PRINT &RUNID#

:SET &RET# = MODIFY_TASK(&RUNID#, STOP_MODIFY)

:SET &RET# = MODIFY_TASK(&RUNID#, 'TASK.01', ,ADD_TASK)

:SET &RET# = MODIFY_TASK(&RUNID#, 'TASK.01', ,MOVE_TASK, 2, 3)

:SET &RET# = MODIFY_TASK(&RUNID#, 'TASK.01', ,ADD_DEPENDENCY, 'START', , 'NONE' )

 

:SET &RET# = MODIFY_TASK(&RUNID#, 'TASK.02', ,ADD_TASK)

:SET &RET# = MODIFY_TASK(&RUNID#, 'TASK.02', ,MOVE_TASK, 3, 3)

:SET &RET# = MODIFY_TASK(&RUNID#, 'TASK.02', ,ADD_DEPENDENCY, 'TASK.01', , 'NONE' )

 

:SET &RET# = MODIFY_TASK(&RUNID#, 'END', ,ADD_DEPENDENCY, 'TASK.02', , 'NONE' )

:SET &RET# = MODIFY_TASK(&RUNID#, 'END', ,REMOVE_DEPENDENCY, 'START', , 'NONE' )

:SET &RET# = MODIFY_TASK(&RUNID#, COMMIT)

:SET &RET# = MODIFY_TASK(&RUNID#, GO, FORCED)

Parameters

  • SYS_ACT_PARENT_NR
    Retrieves the RunID of the Workflow that the task is in

  • PRINT
    Prints the retrieved RunID in the activation report

  • MODIFY_TASK
    Performs a modification to the Workflow, or to a task in the Workflow

  • STOP_MODIFY
    Stops the Workflow for modification purposes

  • ADD_TASK
    Adds a task to the Workflow

  • MOVE_TASK
    Moves the added task to the desired place (identified by the column and line) in the Workflow

  • ADD_DEPENDENCY
    Draws a line to the predecessor of the added task to create a dependency

  • REMOVE_DEPENDENCY
    Deletes the line to a predecessor task to remove the dependency

  • COMMIT
    Commits the changes to the Workflow

  • GO, FORCED
    Starts the Workflow again even if another user has opened it for editing

Return Codes

MODIFY_TASK has the following return codes, depending on the type of modification.

  • 0

    The modification was successful
  • 9

    You are not authorized to modify the specified task at runtime
  • 20591

    A workflow with this RunID does not exist or is no longer active
  • 20738

    The task is in a status in which modifications are not possible
  • 20739

    The task cannot be modified because it is being modified by another user
  • 20740

    The object type you specified is invalid
  • 20741

    There is no task with the specified name and/or RunID
  • 20742

    The specified task name and RunID do not match the same task
  • 20743

    The task cannot be modified because the corresponding Workflow has not been stopped for editing purposes
  • 20744

    The task cannot be modified because it is in an unmodifiable status
  • 20745

    The task cannot be modified because the value is not allowed
  • 20746

    The dependency cannot be added because it already exists
  • 20747

    The dependency cannot be modified because it is in an unmodifiable status
  • 20748

    The task cannot be added because this position is already occupied by another task
  • 20749

    The object type of the indicated task is invalid
  • 20750

    The function cannot be processed for this task with the particular RunID because of a previous error
  • 20752

    You can only replace external tasks with external tasks
  • 20753

    You cannot replace <START> or <END>
  • 20754

    <START> cannot have a predecessor
  • 20755

    <END> cannot have a successor
  • 20756

    External tasks cannot have a predecessor
  • 20757

    The task you specified for the modification of an external dependency is invalid
  • 20758
    External dependencies cannot be indicated
  • 20783
    MODIFY_TASK not possible for workflow '&01' (RunID '&02') of type '&03'.

MODIFY_TASK, ADD_TASK has the following return codes:

  • Sequence number of the task you added to the Workflow
  • 0 - the task could not be added

MODIFY_TASK, REPLACE_TASK and MODIFY_TASK, CLONE_AND_REPLACE_TASK have the following return codes:

  • Sequence number of the task you added to the Workflow
  • 0 - the task could not be replaced

Stopping, Committing Changes and Starting the Workflow

Use MODIFY_TASK with status parameters to stop the Workflow, make and commit your changes, and start the Workflow again. You must stop and start the Workflow to use the other MODIFY_TASK parameters described in this topic.

Syntax

MODIFY_TASK (RunID, status [, FORCED])

Parameters

  • status
    Status to set for the Workflow
    Format: AE name, script literal, or script variable
    Allowed values:

    • COMMIT
      Activates modifications without starting the Workflow
    • GO
      Starts a stopped Workflow
      Use the parameter FORCED to start a workflow even if its Monitor is open for editing purposes
    • STOP
      Stops the Workflow
    • STOP_MODIFY
      Stops the Workflow for modification purposes

  • FORCED
    (Optional) Starts a stopped Workflow even if the Workflow Monitor is open for editing purposes
    Use this keyword in combination with the GO Status.
    Important! Modifications made by another user will be lost if you stop the Workflow while they are editing.

Notes:

  • You cannot modify a workflow by using a MODIFY_TASK statement in the workflow's own Process page.
  • You can, however, modify a workflow by using a MODIFY_TASK statement in the Process page of a child task, such as a script (SCRI).

Examples

The following example stops the MM.DAY Workflow, and allows you to carry out modifications.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RET# = MODIFY_TASK(&RUNID#, STOP_MODIFY)

The following example starts the MM.DAY Workflow even if another user may be editing the Workflow.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RET# = MODIFY_TASK(&RUNID#, GO, FORCED)

Modifying Workflow Contents

The following keywords let you modify the contents of an active Workflow:

  • ADD_TASK
    Adds a task in the Workflow

  • REPLACE_TASK or CLONE_AND_REPLACE
    Replace a task in the Workflow

  • MOVE_TASK
    Moves a task in the Workflow to a different position within the Workflow

  • ACTIVE
    Activates or deactivates a Workflow task

Adding a Task or External Dependency

Use MODIFY_TASK with ADD_TASK to add a task to an active Workflow. Use the EXTERNAL keyword to add a task as an external dependency.

The task that you add is not automatically linked with other tasks. Use MODIFY_TASK with ADD_DEPENDENCY to draw the required lines. Use MODIFY_TASK with MOVE_TASK to place the task in the right place in the Workflow.

Syntax

MODIFY_TASK (RunID, object name ,, ADD_TASK [, EXTERNAL [, Workflow name]] )

Parameters

  • object name
    Name of the object to insert into the Workflow
    Format: script literal, number, or script variable

  • ADD_TASK
    Adds the task

  • EXTERNAL
    (Optional) Adds the task as an external dependency

  • Workflow name
    (Optional) Name of the Workflow to which the external dependency refers
    Format: script literal or script variable

Notes:

  • Write 2 commas after the object name parameter. This third parameter is the sequence number of a task within the workflow. It is irrelevant when you add a task.
  • If the Workflow is configured so that tasks inherit the AE priority of the Workflow, then the task that you add also inherits that priority.

Tip: Use the sequence number that the function returns to specify the task when making other modifications to the added task.

Example

The following example adds the object FILE.INPUT to the Workflow MM.DAY.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#,"FILE.INPUT",, ADD_TASK)
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Replacing a Task in a Workflow

Use MODIFY_TASK with REPLACE_TASK or CLONE_AND_REPLACE to replace a particular task in the Workflow with another object. You can only replace an external dependency with an external dependency, and a regular workflow task with a regular workflow task.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number], REPLACE_TASK|CLONE_AND_REPLACE , object name [, EXTERNAL [, Workflow name]])

Parameters

  • REPLACE_TASK or CLONE_AND_REPLACE
    Replaces the task with the object that you specify

    • REPLACE_TASK 
      Sets the status of the old, replaced task to inactive
    • CLONE_AND_REPLACE
      Keeps the old task active

  • object name
    Name of the object to replace the task with
    Format: script literal or script variable

  • EXTERNAL
    Replaces an external dependency

  • Workflow name
    Name of the Workflow to which the external dependency refers
    Format: script literal or script variable

Example

The following example uses MODIFY_TASK with REPLACE_TASK to replace an external dependency (MM.GET.FILES) by an other external dependency (MM.FILE.INPUT).

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "MM.GET.FILES",, REPLACE_TASK, "MM.FILE.INPUT", EXTERNAL)
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Moving a Task in a Workflow

When you use MODIFY_TASK to add a task, the added task is placed in an available empty spot in the Workflow. Use MODIFY_TASK with MOVE_TASK to move the task to the desired place in the Workflow. Specify the column and line of the desired empty place.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number], MOVE_TASK , Column, Line)

Parameters

  • MOVE_TASK
    Moves the task

  • Column
    Number of the column to which to move the task
    Format: script literal, number, or script variable

  • Line
    Number of the line to which to move the task
    Format: script literal, number, or script variable

Example

The following script moves the task FILE.INPUT to the fourth line of the first column.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, MOVE_TASK, 1, 4)
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Activating or Deactivating a Workflow Task

Use MODIFY_TASK with ACTIVE to activate or deactivate a task.

Syntax

MODIFY_TASK (RunID, [Task name], [sequence number], ACTIVE , YES|NO)

Parameters

  • ACTIVE
    Sets the status of the task to active or inactive

  • YES or NO
    Determines the status of the task:

    • YES
      Sets the Workflow task to active
      Processing starts at the specified start time.
    • NO
      Sets the Workflow task to inactive
      Processing does not start at the start time.

Example

The following example sets the status of the FILE.INPUT task in the MM.DAY Workflow to inactive.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, ACTIVE, "NO")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

General Tab

The following keywords let you modify properties that are set on the General tab of a Workflow task:

  • ALIAS
    Changes the alias of a task or an external dependency in an active Workflow

  • ALIAS_PARENT
    Changes the alias of the Workflow of an external dependency

  • BREAKPOINT
    Adds or removes a breakpoint in a Workflow task

For more information about general properties of tasks in Workflows, see General Tab .

Modifying a Task Alias

Use MODIFY_TASK with ALIAS to change the alias of a task or an external dependency in an active Workflow.

Note: You can only change the alias of Workflow tasks and external dependencies that you have added with a MODIFY_TASK, ADD_TASK statement in the script.

Syntax

MODIFY_TASK (RunID,[Task name], [sequence number],ALIAS|ALIAS_PARENT, New Alias|New Parent Alias)

Parameters

This function has the following parameters:

  • ALIAS or ALIAS_PARENT
    Modifies the alias name of a task or an external dependency in the Workflow
    Use ALIAS_PARENT to change the alias of the Workflow of an external dependency (for external tasks that derive from a different Workflow only).

  • Alias Name or Parent Alias Name
    New alias name
    Format: AE name, script literal, number, or script variable
    For more information about alias names, see General Tab .

Example

The following example adds a File Transfer to the Workflow, and changes the alias of the task. The return code of MODIFY_TASK, ADD_TASK is the sequence number of the added task, and is stored in a script variable (&NR#). The script variable is used to specify which alias to change.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &NR# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, ADD_TASK)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",&NR#,ALIAS,ALIAS.FT)
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO) 

Setting or Removing a Breakpoint

Use MODIFY_TASK with BREAKPOINT to set or remove a breakpoint in a Workflow task.

Syntax

MODIFY_TASK (RunID, [Task name], [sequence number], BREAKPOINT, YES|NO)

Parameters

  • BREAKPOINT
    Sets or removes the breakpoint for the Workflow task

  • YES or NO
    Determines whether the keyword adds or removes a breakpoint:

    • YES
      Sets a breakpoint
    • NO
      Removes the breakpoint

Example

The following example uses MODIFY_TASK with the BREAKPOINT keyword to set a breakpoint for the task called FILE.INPUT.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, BREAKPOINT, "YES")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Time & Dependencies Tab

The following keywords let you modify properties that are set on the Time & Dependencies tab of a Workflow task:

  • EARLIEST_START
    Sets an earliest start time to a Workflow task

  • LATEST_START
    Adds or removes a latest start time for a Workflow task

  • CHECKPOINT
    Adds or removes a checkpoint in a Workflow task

  • DEPENDENCY_STATE_MATCH
    Number of states of predecessor task that must apply

For more information about properties that determine timing and dependencies, see Time & Dependencies .

Adding or Removing a Start or End Time

Use MODIFY_TASK with a start or end keyword to set or remove the start or end time of a task in an active Workflow.

Syntax

MODIFY_TASK (RunID, [Task name], [sequence number], KEYWORD, Timestamp [, Time zone])

Parameters

  • KEYWORD
    Sets or removes the start or end time of the task:

    • EARLIEST_START
      Sets or removes the earliest start time of the task
    • LATEST_START
      Sets or removes the latest start time of the task
    • LATEST_END
      Sets or removes the latest end time of the task

  • Timestamp
    Defines the time
    Format: script literal or script variable
    Allowed values: DD/HH:MM [, Time zone]
    Is the
    Where:

    • DD
      Number of days to add to the current date
    • HH:MM
      Time
    • Time zone
      (Optional) Name of a Time Zone object to convert the time to a particular time zone
      Format: script literal or script variable
      For more information, see Time Zone (TZ).

Note: The comparison value for the earliest start time is the real date (the time at which the top workflow is generated). For more information, see Logical Date and Real Date

Examples

The following example sets the earliest start time for the FILE.INPUT task.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, EARLIEST_START, "00/18:00")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

The following example sets the latest start time for the task.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, LATEST_START, "00/10:00")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

The following example sets the latest end time for the task.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, LATEST_END, "00/18:00")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Adding or Removing a Checkpoint

Use MODIFY_TASK with CHECKPOINT to add or remove a checkpoint in a task in an active Workflow.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number], CHECKPOINT, timestamp [, Time Zone] [, Alarm object])

Parameters

  • CHECKPOINT
    Sets or removes a checkpoint

  • Alarm object
    (Optional) Object to start when the checkpoint is passed
    Format: script literal or script variable

Example

The following example sets a checkpoint in a task called FILE.INPUT, which is part of the MM.DAY workflow. When the checkpoint elapses, a Notification object that is called DAYSHIFT starts.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, CHECKPOINT, "00/15:00",,"DAYSHIFT")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Determining the Number of Predecessor States Required

Use MODIFY_TASK with DEPENDENCY_STATE_MATCH to define whether one or all predecessor states must apply before the Workflow task is processed. On the Time & Dependencies tab in the task properties, this setting is labeled Run this task if all statuses match/at least one condition matches.

Syntax

MODIFY_TASK (RunID, [Task name], [sequence number], DEPENDENCY_STATE_MATCH , ALL|ONE)

Parameters

  • DEPENDENCY_STATE_MATCH
    Specifies the number of predecessor states that must apply

  • ALL or ONE
    How many predecessor states must apply:

    • ALL
      All states must apply
    • ONE
      At least one state must apply

Example

The following example uses MODIFY_TASK with the DEPENDENCY_STATE_MATCH keyword to ensure that all predecessors of the FILE.INPUT task must have the expected status before the task is processed.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, DEPENDENCY_STATE_MATCH, "ALL")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Adding, Modifying or Removing a Dependency to a Workflow Task

Use MODIFY_TASK with a DEPENDENCY keyword to add, remove, or modify a dependency to a task in a Workflow. The function adds, removes or modifies lines that link tasks in the Workflow editor.

Syntax

MODIFY_TASK (RunID, [successor task name], [sequence number], ADD_DEPENDENCY|MODIFY_DEPENDENCY|REMOVE_DEPENDENCY, [source task name] , [sequence number], status)

Parameters

  • successor task name or sequence number
    Name or sequence number of the successor task of the dependency
    Format: script literal, number, or script variable

  • ADD_DEPENDENCY or MODIFY_DEPENDENCY or REMOVE_DEPENDENCY
    Adds, modifies or removes the dependency

  • source task name or sequence number
    Name or sequence number of the task whose dependency you want to edit
    Format: script literal, number, or script variable

  • status
    Expected status of the preceding task at the end of the task's execution
    Format: script literal or script variable
    Note: You do not need to specify a status when you remove a dependency.
    Allowed values:

    • End status
      Expected status of the preceding task
      Example: ENDED_OK
    • NONE
      The end status of the preceding task is not monitored

For more information about specifying task names and running numbers, see Syntax and Parameters .

Example

The following example edits dependencies in the Workflow:

  • The 4th task requires the Start box to get ENDED_OK status.
  • The 9th task requires the 8th task to get ANY_OK status.
  • The dependency of the 11th task on the 10th task is removed.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#,, 4, ADD_DEPENDENCY, "START",, "ENDED_OK")
:SET &RET# = MODIFY_TASK(&RUNID#,, 9, MODIFY_DEPENDENCY,, 8,"ANY_OK")
:SET &RET# = MODIFY_TASK(&RUNID#,, 11, REMOVE_DEPENDENCY,, 10, "ENDED_OK")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Defining an Action to Take when Dependencies are not Fulfilled

Use MODIFY_TASK with DEPENDENCY_ELSE_ACTION to define the action to take when a dependency is not fulfilled.

Syntax

MODIFY_TASK (RunID, [Task name], [sequence number], DEPENDENCY_ELSE_ACTION , ABORT|BLOCK|BLOCK_ABORT|SKIP [ , Alarm object] )

Parameters

  • DEPENDENCY_ELSE_ACTION
    Determines that action is to be taken when dependencies are not fulfilled as expected

  • ABORT, BLOCK, BLOCK_ABORT or SKIP
    Defines the action to take:

    • ABORT
      Cancels the task and the Workflow
    • BLOCK
      Blocks the Workflow at the preceding task
    • BLOCK_ABORT
      Blocks the Workflow at the preceding task and sends and abort message to the parent Workflow, if applicable
    • SKIP
      Skips the Workflow task

  • Alarm object
    Name of a Notification object of Alarm type to start if the checkpoint is exceeded
    Format: script literal or script variable

Example

The following example skips the FILE.INPUT task when the conditions for the dependency are not fulfilled.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, DEPENDENCY_ELSE_ACTION, "SKIP")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Runtime Tab

The following parameters let you modify settings on the Runtime tab of a Workflow task. For more information, see Runtime Properties.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number], runtime option, value )

Parameters

  • runtime option
    Runtime setting that you want to edit
  • value
    Defines the value for the setting, depending on the runtime setting you want to edit

Runtime Options:

  • RUNTIME_USE_TASK_SETTINGS
    Uses the MRT and SRT settings of the task
    Allowed values:

    • YES
      Uses the runtime settings defined for the task on the Runtime tab (task properties in the Workflow)
    • NO
      Uses the runtime settings defined in the properties on the Runtime page in the object definition

  • RUNTIME_MRT_NONE
    No specified maximum runtime
    Do not enter a value.

  • RUNTIME_MRT_FIXED
    Uses a fixed value for the maximum runtime
    Allowed values: Fixed value in HHHH:MM:SS format

  • RUNTIME_MRT_ERT
    Uses ERT plus a percentage for the maximum runtime
    Allowed values: Percentage
    Example: Write 50 to add 50% to the maximum runtime.

  • RUNTIME_MRT_TIME
    Uses the current date plus a period for the maximum runtime
    Allowed values: DD/HH:MM [, Time zone]
    Where:

    • DD
      Number of days to add to the current date
    • HH:MM
      Time
    • Time zone
      (Optional) Name of a Time Zone object to convert the timestamp

  • RUNTIME_SRT_NONE
    No minimum runtime
    Do not enter a value.

  • RUNTIME_SRT_FIXED
    Fixed value for the minimum runtime
    Allowed values: Fixed value in HHHH:MM:SS format

  • RUNTIME_SRT_ERT
    Uses ERT minus a percentage for the minimum runtime
    Allowed values: Percentage

  • RUNTIME_ELSE_ACTION
    Defines an action to carry out when the actual runtime deviates from the expected runtime
    Allowed values: CANCEL|NONE [, Alarm object]
    Where:

    • CANCEL
      Cancels or ends the task
    • NONE
      No action is taken
    • Alarm object
      (Optional) Name of a Notification object of Alarm type to start if the expected runtime is exceeded

Example

The Notification object DAYSHIFT starts if the FILE.INPUT task takes longer than two hours to execute. The script also removes any minimum runtime setting.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RETMRT# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, RUNTIME_MRT_FIXED, "2:00:00")
:SET  &RETSRT# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, RUNTIME_SRT_NONE)
:SET  &RETACT# = MODIFY_TASK(&RUNID#, "FILE.INPUT",, RUNTIME_ELSE_ACTION,"CANCEL", "DAYSHIFT")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

External Dependency Tab

The following keywords let you modify settings on the External Dependencies tab of an external task in a Workflow.

  • EXTERNAL_SATISFACTION
    Defines when an external task is expected to end

  • EXTERNAL_STATUS
    Sets the expected status of an external task

  • EXTERNAL_ELSE_ACTION
    Defines the action to take when an external task does not fulfill expectations

  • EXTERNAL_TIMEOUT_ACTION
    Defines the action to take when an external task times out

More Information:

Defining the Execution Settings of an External Dependency

Use MODIFY_TASK with EXTERNAL_SATISFACTION to define how the Workflow handles an external dependency. The Workflow is configured to expect the external task to start or end at a particular time, such as before or after the current Workflow starts. EXTERNAL_SATISFACTION lets you modify the settings that determine the expected lead time.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number],EXTERNAL_SATISFACTION , lead time satisfaction [, duration])

Parameters

  • EXTERNAL_SATISFACTION
    Defines the lead time satisfaction

  • lead time satisfaction
    Defines when the external dependency is considered as fulfilling expectations:

    • LOGICAL_DATE
      Checks if the external task was activated on the same logical date as the Workflow
    • LAST_EXECUTION
      Checks if the external task end is after the last Workflow execution end
    • BEFORE_START
      Checks if the external task end is within a period before the Workflow starts
    • AFTER_START
      Checks if the external task end is after the current Workflow starts

  • duration
    (BEFORE_START only) Period in HH:MM:SS format
    Format: script literal or script variable

Example

In the following example, the lead time for the external dependency MM.GET.FILES commences when the Workflow starts.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "MM.GET.FILES",, EXTERNAL_SATISFACTION, "AFTER_START")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Setting the Expected Status of an External Dependency

Use MODIFY_TASK with EXTERNAL_STATUS to set the status expected for an external task.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number], EXTERNAL_STATUS , status)

Parameters

  • EXTERNAL_STATUS
    Sets or removes the expected status of an external task

  • status
    Expected status for the external task:

    • End status
      Status such as ENDED_OK
    • NONE
      The system only checks whether the task ended within the lead time, regardless of the status

Example

In the following example, the MM.DAY Workflow expects an ENDED_OK status from the external task that is called MM.GET.FILES.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "MM.GET.FILES",, EXTERNAL_STATUS, "ENDED_OK")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Defining the Else Action of an External Dependency

Use MODIFY_TASK with EXTERNAL_ELSE_ACTION to define the action to take if an external task does not get the expected status, or does not end within the expected time.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number], EXTERNAL_ELSE_ACTION , WAIT|SKIP|CANCEL [, Alarm object] )

Parameters

  • EXTERNAL_ELSE_ACTION
    Determines that action is to be taken when an external task does not get the expected status at least once, or does not end within the expected time

  • WAIT, SKIP, or CANCEL
    Defines the action to take:

    • WAIT
      Waits for the external task to complete
      Note: Use MODIFY_TASK with EXTERNAL_TIMEOUT_ACTION to define the timeout for this action.
    • SKIP
      Skips the external task
    • CANCEL
      Cancels the Workflow

  • Alarm object
    (Optional) Name of a Notification object of Alarm type to start if a timeout occurs
    Format: script literal or script variable

Example

In the following example, the MM.DAY Workflow is canceled if the external MM.GET.FILES task does not end as expected. When the script cancels the Workflow, it starts a Notification object called DAYSHIFT.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "MM.GET.FILES",, EXTERNAL_ELSE_ACTION, "CANCEL", "DAYSHIFT")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Defining the Timeout Setting of an External Dependency

Use MODIFY_TASK with EXTERNAL_TIMEOUT_ACTION to define the timeout setting of an external task when you use WAIT and define an Else action.

Syntax

MODIFY_TASK (RunID, [task name], [sequence number], EXTERNAL_TIMEOUT_ACTION , timeout length, WAIT|SKIP|CANCEL[, Alarm object])

Parameters

  • EXTERNAL_TIMEOUT_ACTION
    Determines the length of time to wait when you define an Else action with WAIT

  • timeout length
    Timeout duration in HH:MM:SS format
    Format: script literal or script variable

  • WAIT, SKIP, or CANCEL
    Defines the action to take:

    • WAIT
      Waits for the external task to complete
    • SKIP
      Skips the external task
    • CANCEL
      Cancels the Workflow

  • Alarm object
    (Optional) Name of a Notification object of Alarm type to start if a timeout occurs
    Format: script literal or script variable

Example

In the following Workflow, there is an external dependency on a task that is called MM.GET.FILES. The Workflow skips the external task if the task fails to end as expected within 1 hour.

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &RET# = MODIFY_TASK(&RUNID#, "MM.GET.FILES",, EXTERNAL_TIMEOUT_ACTION, "01:00:00", "SKIP")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

Modifying the Value of a Variable

Use MODIFY_TASK with VALUE to modify the value of a variable stored on the Variables & Prompts tab:

  • Object variable
    Modify an existing variable value, or create a new variable with a specified value.
  • PromptSet variable
    Modify an existing variable value of a PromptSet control.

Syntax

MODIFY_TASK (RunID, task name, sequence number, VALUE,PROMPTSET NAME|<VALUE>, VARIABLE|NEW VARIABLE, "VALUE", [SELECT|DESELECT|CLEAR|SPACE])

Parameters

  • VALUE
    Modifies the value of a variable:

    • Modifies the value of an existing object variable, or creates a new object variable
    • Modifies the value of an existing PromptSet variable

  • PromptSet name or <VALUE>
    Specifies the variable:

    • PromptSet name
      Name of the PromptSet object
    • <VALUE>
      Name of the object variable

  • variable
    (Object variables only) Name of the new variable if the object variable does not exist yet
    Note: Write the variable name without the leading ampersand

  • value
    (Optional) Value to set for the variable
    Note: You must set a value if you are modifying a PromptSet variable that is an array.
    Format: script literal or script variable

  • SELECT, DESELECT, CLEAR or SPACE
    (Optional) Modifies the values selected in the variable:

    • SELECT
      (PromptSet variable arrays only) Selects rows of an array
    • DESELECT
      (PromptSet variable arrays only) Deselects rows of an array
    • CLEAR
      (PromptSet variable arrays only) Deselects all rows of an array
    • SPACE (default)
      Changes the PromptSet variable or object variable value to empty text
    Note: These keywords let you select or deselect values when the variable allows multiple values. Use these parameters to manage values from PromptSet controls such as checkboxes. The selected values can be values selected by a user, default values, or values defined for the Workflow.

Examples

In the following example, the script activates a Workflow, and stops the Workflow for modifications. The script creates a variable and assigns a value the variable.

:SET &RUNID# = ACTIVATE_UC_OBJECT("JOBP.NEW.01")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &MODIFY# = MODIFY_TASK(&RUNID#, "SCRI.NEW.01", 4, VALUE, "<VALUE>", "&&VARIABLE#", "Vienna")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

In the following example, a Script object has an assigned PromptSet. The script modifies the values of the PromptSet variable CKG#, that is an array of values from a checklist control. The parameters in MODIFY_TASK, VALUE select the Test01 value from the PromptSet variable.

:SET &RUNID# = ACTIVATE_UC_OBJECT("JOBP.NEW.01")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &MODIFY# = MODIFY_TASK(&RUNID#, "SCRI.NEW.01", 4, VALUE, "PRPT.NEW.01", "CKG#", "Test01", SELECT)
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

In the following example, the value of the PromptSet variable Textfield01# is set to mytextfieldvalue.

:SET &RUNID# = ACTIVATE_UC_OBJECT("JOBP.NEW.01")
:SET &RETSTOP# = MODIFY_TASK(&RUNID#, STOP_MODIFY)
:SET &MODIFY# = MODIFY_TASK(&RUNID#, "SCRI.NEW.01", 4, VALUE, "PRPT.NEW.01", "Textfield01#", "mytexfieldvalue")
:SET &RETCOMMIT# = MODIFY_TASK(&RUNID#, COMMIT)
:SET &RETGO# = MODIFY_TASK(&RUNID#, GO)

See also:

seealso

Script Elements for Handling Tasks