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)