MODIFY_TASK

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

Overview and Modification Sequence

Before and after making modifications with MODIFY_TASK, you must alter the Workflow status using preliminary script lines. Follow this exact sequence when modifying a Workflow:

Use MODIFY_TASK with the STOP_MODIFY parameter to stop the Workflow and enable editing.
Use MODIFY_TASK with other specific parameters to apply one or more modifications.
Use MODIFY_TASK with the COMMIT parameter to save and activate your changes.
Use MODIFY_TASK with the GO parameter to restart the Workflow.

Syntax and Core Parameters

The basic syntax of this script function follows this structure:

MODIFY_TASK (RunID, parameters, KEYWORD)

Important!

You must define the parameters in the exact sequence shown in the syntax examples within this topic.
You must include the commas exactly as shown, even if you omit individual parameters.

Several modifications require you to specify a particular task. Use one or both of the following parameters to identify the task:

Task name

Defines the name of the task. Use START or END to modify the start or end box of a Workflow. (Format: script literal, number, or script variable).
Sequence number

Defines the number representing the task's position within the Workflow (e.g., 3 for the third task). This is displayed in the task box in the Workflow editor and 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 sequence number, ensure they both refer to the same task.
If the Workflow contains multiple tasks with identical names and you omit the sequence number, the system automatically modifies the task with the lowest sequence number.

Return Codes

Depending on the type of modification, MODIFY_TASK returns the following codes:

0: The modification was successful.
9: You lack the authorization to modify the specified task at runtime.
20591: A workflow with this RunID does not exist or is no longer active.
20738: The task resides in a status that blocks modifications.
20739: The task cannot be modified because another user is currently editing it.
20740: The specified object type is invalid.
20741: No task matches the specified name and/or RunID.
20742: The specified task name and RunID do not point to the same task.
20743: The task cannot be modified because the corresponding Workflow has not been stopped for editing.
20744: The task cannot be modified due to an unmodifiable status.
20745: The task cannot be modified because the provided value is disallowed.
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 the target position is occupied.
20749: The object type of the indicated task is invalid.
20750: The function cannot process this task with the particular RunID due to a prior error.
20752: External tasks can only be replaced by other external tasks.
20753: You cannot replace <START> or <END> boxes.
20754: <START> cannot have a predecessor.
20755: <END> cannot have a successor.
20756: External tasks cannot have a predecessor.
20757: The task specified for modifying an external dependency is invalid.
20758: External dependencies cannot be indicated.
20783: MODIFY_TASK not possible for workflow '&01' (RunID '&02') of type '&03'.

ADD_TASK, REPLACE_TASK, and CLONE_AND_REPLACE_TASK Return Codes:

Returns the Sequence number of the task added or replaced.
Returns 0 if the task could not be added or replaced.

Stopping, Committing Changes, and Starting Workflows

Use MODIFY_TASK with status parameters to stop the Workflow, commit your changes, and start it again. You must halt the Workflow to utilize the other MODIFY_TASK parameters detailed in this topic.

Syntax

MODIFY_TASK (RunID, status [, FORCED])

Parameters

Parameter	Description	Allowed Values
status	Specifies the status to set for the Workflow.	COMMIT: Activates modifications without starting the Workflow. GO: Starts a stopped Workflow. Use with FORCED to bypass open monitors. STOP: Stops the Workflow. STOP_MODIFY: Stops the Workflow specifically for modification purposes.
FORCED	(Optional) Starts a stopped Workflow even if the Workflow Monitor is open for editing. Use this in combination with the GO status. Important! Modifications made by another user will be lost if you force start the Workflow while they are editing.	FORCED

Parameter

Description

Allowed Values

status

Specifies the status to set for the Workflow.

COMMIT: Activates modifications without starting the Workflow.
GO: Starts a stopped Workflow. Use with FORCED to bypass open monitors.
STOP: Stops the Workflow.
STOP_MODIFY: Stops the Workflow specifically for modification purposes.

FORCED

(Optional) Starts a stopped Workflow even if the Workflow Monitor is open for editing. Use this in combination with the GO status.

Important! Modifications made by another user will be lost if you force start the Workflow while they are editing.

FORCED

Notes:

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

Examples

The following example stops the MM.DAY Workflow and enables modifications:

:SET &RUNID# = GET_UC_OBJECT_NR("MM.DAY")

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

The following example forces the MM.DAY Workflow to start, bypassing any open editor sessions:

: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: Adding a Task or External Dependency

Use ADD_TASK to inject a task into an active Workflow. Use the EXTERNAL keyword to add a task as an external dependency. The new task is not automatically linked; use ADD_DEPENDENCY to create connections and MOVE_TASK to place it appropriately.

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

Notes: Include two commas after the object name parameter. This acts as a placeholder for the sequence number, which is irrelevant when adding a task. The function returns the new sequence number, which you should capture to modify the task further. Added tasks inherit the AE priority from the Workflow if so configured.

REPLACE_TASK or CLONE_AND_REPLACE: Replacing a Task in a Workflow

Use REPLACE_TASK or CLONE_AND_REPLACE to swap a task. External dependencies must be replaced by external dependencies, and regular tasks by regular tasks. REPLACE_TASK sets the old task to inactive, while CLONE_AND_REPLACE keeps it active.

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

MOVE_TASK: Moving a Task in a Workflow

Newly added tasks are placed in available empty spots. Use MOVE_TASK to reposition the task by specifying the target column and line number.

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

ACTIVE: Activating or Deactivating a Workflow Task

Use ACTIVE with YES or NO to toggle the active status of a task. When deactivated (NO), processing will bypass the task at the scheduled start time.

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

Modifying General Properties

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

ALIAS or ALIAS_PARENT: Modifying a Task Alias

Use ALIAS or ALIAS_PARENT to alter the alias of an added task or external dependency. Note: You can only modify the alias of tasks added dynamically using ADD_TASK during the script run.

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

BREAKPOINT: Setting or Removing a Breakpoint

Use BREAKPOINT to toggle a breakpoint for a task. Specify YES to add it, or NO to remove it.

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

Modifying Time Properties

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

EARLIEST_START, LATEST_START, or LATEST_END: Adding or Removing a Start or End Time

Use EARLIEST_START, LATEST_START, or LATEST_END to define task timing constraints. The format is DD/HH:MM, where DD represents days to add to the current date.

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

CHECKPOINT: Adding or Removing a Checkpoint

Use CHECKPOINT to assign a checkpoint. You can optionally trigger an Alarm object if the checkpoint is passed.

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

Modifying Dependencies

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

DEPENDENCY_STATE_MATCH: Determining the Number of Predecessor States Required

Use DEPENDENCY_STATE_MATCH to specify whether ALL or ONE predecessor states must match before execution proceeds.

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

ADD_DEPENDENCY, MODIFY_DEPENDENCY, or REMOVE_DEPENDENCY: Adding, Modifying, or Removing a Dependency

Manage workflow links using ADD_DEPENDENCY, MODIFY_DEPENDENCY, or REMOVE_DEPENDENCY. You must define the target status (e.g., ENDED_OK) or use NONE to bypass status checks.

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

DEPENDENCY_ELSE_ACTION: Defining the Else Action

Use DEPENDENCY_ELSE_ACTION to define handling for unfulfilled dependencies. Options include ABORT, BLOCK, BLOCK_ABORT, or SKIP.

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

Modifying Runtime Properties

Modify maximum/minimum runtimes (MRT/SRT) and exception handling options using runtime keywords.

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

Available Runtime Options:

RUNTIME_USE_TASK_SETTINGS: YES (workflow task properties) or NO (object definition properties).
RUNTIME_MRT_NONE / RUNTIME_SRT_NONE: Clears the maximum/minimum runtime limits.
RUNTIME_MRT_FIXED / RUNTIME_SRT_FIXED: Sets a fixed time (HHHH:MM:SS).
RUNTIME_MRT_ERT / RUNTIME_SRT_ERT: Adds or subtracts a percentage from the Estimated Runtime (ERT).
RUNTIME_MRT_TIME: Sets a duration to add to the current date.
RUNTIME_ELSE_ACTION: Sets CANCEL or NONE if runtime deviates, optionally launching an Alarm object.

Modifying External Dependencies

Edit settings for external dependencies, including lead time satisfaction, expected status, and timeout logic.

EXTERNAL_SATISFACTION: Options include LOGICAL_DATE, LAST_EXECUTION, BEFORE_START, or AFTER_START.
EXTERNAL_STATUS: A specific status or NONE.
EXTERNAL_ELSE_ACTION: Set to WAIT, SKIP, or CANCEL.
EXTERNAL_TIMEOUT_ACTION: Configures the timeout length when the Else action is WAIT.

Modifying the Value of a Variable

Use the VALUE keyword to edit object variables or PromptSet variables on the task. When modifying PromptSet array controls (like checkboxes), you can use SELECT, DESELECT, CLEAR, or SPACE to target multiple selections.

Sample Scenario: Combining Modifications

This example demonstrates how to add two tasks to an active workflow, place them, and map out their dependencies. First, the workflow is stopped; then Task 1 is added, moved, and linked to START. Task 2 is added, linked to Task 1, and the END box is relinked to Task 2. Finally, changes are committed and the Workflow restarts.

: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)