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:

Important!

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:

Notes:

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:

Goals:

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

Return Codes

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

MODIFY_TASK, ADD_TASK has the following return codes:

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

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

Notes:

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:

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

Notes:

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

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

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

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:

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:

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

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:

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

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

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

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

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

Example

The following example edits dependencies in the Workflow:

: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

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

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.

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

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

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

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

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:

Syntax

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

Parameters

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: