ACTIVATE_UC_OBJECT

Use the ACTIVATE_UC_OBJECT function to execute an object through a script. You can activate any type of executable object with this function. Parameters in the function let you define when the object executes, and which variables are passed to the object.

This function includes several parameters that let you define start times. If you do not specify a start time, the new task is immediately launched into the execution queue. If you define a start time, the task is scheduled and has the status Waiting for start time. You can also activate the object at a logical date, or specify an alternative object to activate when the called object exceeds a time limit.

This script function returns the RunID of the called object. Parameters on the Attributes page of the object determine whether the RunID is returned after the activation or generation phase:

  • Generate Task at Activation time: the script function returns the RunID after the generation phase of the called object
  • Generate Task at Runtime: the script function returns the RunID at object activation

More information:

Notes

  • Execution time and start time can be two different points in time.
  • This script statement causes all open transactions of the script to be written to the AE database. For more information, see Script Processing.
  • The MAX_NESTING_DEPTH variable performs a security check and limits the number of recursive object activations. For more information, see MAX_NESTING_DEPTH in UC_SYSTEM_SETTINGS - Systemwide Settings. By default, the 16th attempt to activate an object is canceled with the status FAULT_OTHER. Setting the value to 0 (zero) disables the security check.
    The limit also applies to recursive workflow activations or a mix of workflow activations and object activations.
    Example: A workflow activates a script which in turn activates the workflow again. If the loop happens 5 times (3 times 5 is 15), the 16th activation is canceled.

Syntax

ACTIVATE_UC_OBJECT ( Object name [ , , [Logical Date] [ , [TimeZone] [ , [ Start time|Period object] [ , [ PASS_VALUES] [ , [Queue] [ , [Alias] [ , [ENABLE_PROMPTS] ] ] ] ] ] ] ])
ACTIVATE_UC_OBJECT ( Object name [ , [WAIT] [ , [Logical Date] [ , [TimeZone] [ , , [ PASS_VALUES] [ , [Queue] [ , [Alias] [ , [ENABLE_PROMPTS[, FixedTimeValue, [TERMINATE][, Executed-Object] ] ] ] ] ] ] ] ] ])

Note: You must write the parameters of this script function in the order shown above. Set commas if you omit parameters.

Parameters

  • ACTIVATE_UC_OBJECT
    Executes the object

  • Object Name
    Name of the called object

  • WAIT
    Script function waits until the object has ended
    Important! You cannot use the WAIT keyword in combination with a start time.

  • Logical Date
    Logical date to use when you activate the object
    For more information, see Logical Date and Real Date.
    Format: script literal or script variable, YYMMDD or YYYYMMDD
    (Optional) To use a different format, specify the date format, enter a separator (: or ;) and specify the date.

  • TimeZone
    Time Zone object used for timestamp calculation
    Format: script literal or script variable

  • Start time|Period object
    Timestamp string or name of an existing Period object

    • Start time
      Timestamp that consists of a date and time ("YYYY-MM-DD HH:MM:SS")
      Format: script literal or script variable
    • Period object
      Period object for recurring executions
      When you use this parameter, the execution starts once immediately. All subsequent executions start as defined in the settings of the Period object.
      Note: If you define a Period object, the parameters Logical Date and Start time are ignored.
  • PASS_VALUES
    Passes object variables and PromptSet variables to the called object

  • Queue
    Overrides the queue definition in the called object
    If you do not specify a Queue object, the task automatically starts in the queue that is defined in the called object.

  • Alias
    Alias of the called object
    This display name is used in the Process Monitoring perspective and the statistics instead of the actual object name.
    Format: AE name, script literal or script variable
    The same rules apply for alias names and for object names:
    Maximum length: 200 characters
    Allowed characters: A-Z, 0-9, $, @, _, -, . and #
  • ENABLE_PROMPTS
    Forces the PromptSet input form of the activated object to be displayed in the Automic Web Interface.
    Notes:

    • If the user is not logged on to the Automic Web Interface, the called object waits for the user.
    • When no PromptSet objects are assigned, script processing is not affected and the input form is not displayed.

  • FixedTimeValue
    Maximum runtime of the started object
    Format: script literal or script variable, in the format HH:MM:SS, where HH can be a single-digit value, but MM and SS must be two-digit values
    Example: "1:05:07"

    If you define a maximum runtime, you must also define at least one action that will be processed when the limit is exceeded. Use the TERMINATE and Execute parameters for this purpose.

  • TERMINATE
    Cancels the task if the maximum runtime (time limit) is exceeded

  • Executed-Object
    Activates another object if the maximum runtime is exceeded
    Format: AE name, script literal or script variable

More Information:

Return Codes

The ACTIVATE_UC_OBJECT script function returns the following return codes:

  • RunID of the activated object if activation is successful
  • 0 if activation is unsuccessful
  • 20380 if the object is canceled with the :EXIT script statement

Tip: Always query the return code in your scripts so that you can analyze error causes. For more information, see Error Handling in Scripts

The script function returns the RunID of the object in the following situations:

  • Object activation was successful

    This is the normal case.

  • The starting point lies in the past

    The execution is listed as ENDED_TIMEOUT - Starttime exceeded in the report.

The script function returns 0 in the following situations:

  • Object does not exist

    The object could not be found, so activation is not possible.

  • No object execution rights

    The user who activated the object is not authorized to execute the object.

  • Object activation aborted

    The task was aborted manually or by another task.

The object attribute Generate Task at Runtime or Activation has an impact on return codes. For more information, see Generating at Activation or at Runtime .

If the object is configured to be generated at activation, the script function returns the RunID of the object in the following situations:

  • :EXIT 0

    This statement does not abort script processing, it terminates it. It is not handled as an error.

  • :STOP NOMSG

    This statement does not abort script processing, it terminates it. It is not handled as an error.

The script function returns 0 in the following situations:

  • Scripting error in object

    Object activation has been aborted due to scripting errors.

  • :EXIT <> 0

    This statement cancels the activation of the object.

  • :STOP MSG

    This statement cancels the activation of the object.

If the object is configured to be generated at runtime, then script execution does not take place during the activation process. The ACTIVATE_UC_OBJECT script function cannot identify errors that occur. The function returns the RunID in the following cases:

  • :EXIT 0

  • :EXIT <> 0

  • :STOP MSG

  • :STOP NOMSG

Examples

The following example activates a Job called Status, checks the return code, and sends an email with the error code and error message if the job fails to activate:

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(STATUS)

:
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. Thank you!")
:
ENDIF

The following example activates the Job with a logical date:

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(STATUS,,"DD.MM.YY:01.12.15"

In the following example, the Workflow object MM.WEEK runs at a specific date and time:

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(MM.WEEK,,, "MEZ", "2018-07-15 18:00:00")

In the following example, object variables are inherited by the Job MM.END.PROCESSING:

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT("MM.END.PROCESSING",,,,, PASS_VALUES)

See also: