DEACTIVATE_UC_OBJECT

Use the DEACTIVATE_UC_OBJECT script function to deactivate a completed task. The function lets you deactivate tasks that have already ended:

  • Tasks that completed successfully
  • Tasks that were canceled

Important!

  • You cannot deactivate Workflows that include active tasks or deactivate child Workflows that include active tasks.
  • To deactivate tasks that have been started by a Workflow, you must deactivate the top Workflow and ensure that none of the child tasks are active.
  • When you deactivate tasks, they are removed from the Process Monitoring perspective.

Tip: You can define settings in executable objects to automatically deactivate the task. For more information, see Automatic Deactivation Section.

Syntax

DEACTIVATE_UC_OBJECT (RunID [,FORCED])

Parameters

  • DEACTIVATE_UC_OBJECT
    Deactivates a completed task

  • RunID
    RunID of the task to deactivate
    Format: script literal, script variable, or number without quotation marks

  • FORCED
    (Optional, Workflows only) Deactivates the Workflow task and all child tasks, regardless of their status and any automatic deactivation settings in the child tasks. Everything that is active is removed from the Workflow monitor (EJPP table), but not from the Process Montoring View (EH table).
    Format: AE name, script literal or script variable
    Important!

    • The system does not check whether the task that you are deactivating is running in a Workflow.
    • The system does not check whether child tasks in the Workflow are active.

    Example: The following example explains the logic behind a forced deactivation of Workflow tasks.

    Assume you run a Workflow with three active tasks, all with dependencies set. If the first task does not find a file, the following tasks are blocked and ended. The Post-Process page includes a script that cancels and deactivates the Workflow.

    What you see:

    • The Process Monitoring perspective shows the Workflow status ENDED_CANCEL - manually canceled.
    • If you go to the Workflow executions, it shows the status ENDED_CANCEL - manually canceled.
    • However, if you open the Workflow from Executions in the Workflow Monitor, you see that the first task is green as if it were still active.

    The logic behind:

    Deactivating is impossible during a normal deactivation if a job inside the Workflow is running. During normal deactivation, the statuses in the context of the Workflow table (EJPP) are copied to the history records (AJPP table). In Workflows that finish normally, these are usually ENDED_OK or ENDED_NOT_OK.

    What is now happening is that the first Job is still running due to the processing of the Post Process page; the status in the EH table is 1574. The forced deactivation is triggered through the post-processing, and the current status from the EJPP table is moved into the AJPP table then deleted from the EJPP table.

    Post-condition processing finishes, the job finishes and is deactivated and removed from the EH table, and the correct values are copied to the AH table.

    If a Workflow is deactivated, the AJPP table does not receive any further updates, such as, for example, that the job has finished correctly. The Workflow Monitor, on the other hand, loads the information from the AJPP table for the RunID, which shows that the job is still running. Therefore, the Workflow Monitor still shows this job in green. You can either avoid applying a forced deactivation during post-processing (Workflow logic change) or ignore this. For details on database tables, see Database Areas.

Return Codes

The script function returns the following codes:

  • 12204
    Task cannot be deactivated because you cannot deactivate objects of a Workflow
  • 12205
    Task cannot be deactivated because the task has active child tasks
  • 12206
    Status definition is not numerical
  • 12207
    Status definition is not in an ascending order (from-to)
  • 12208
    Status definition is syntactically incorrect
  • 12209
    Cannot find the status definition, so the object has not been deactivated automatically
  • 12210
    Status definition is not numerical, so the object has not been deactivated automatically

Example

The following example activates an object, and waits for the task to complete. If an error occurs, the system sends an email to a user. If the task completes without an error, the script deactivates the task.

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(&OBJ#,WAIT)

:
IF &ACTOBJ# = "0"
:   
SET &ERRNR# = SYS_LAST_ERR_NR()
:   
SET &ERRINS#  = SYS_LAST_ERR_INS()
:   
SET &MESSAGE# = GET_MSG_TXT(&ERRNR#,&ERRINS#)
:   
SET &RET# = SEND_MAIL("John.Smith@automic.com",,&MESSAGE#, "Please check. Thanks!")
:ELSE
: SET &DEACTJOB# = DEACTIVATE_UC_OBJECT(&ACTJOB#)
:
ENDIF

See also: