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.

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.
  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 can only stop and start other Workflows, but not the Workflow that the script itself is in.
• You cannot use MODIFY_TASK to edit the Workflow that the script is in.

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:

• External Dependencies in Workflows
• External Dependency Tab

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.

• Variables Page
• Prompt Sets Page

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: