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

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

Parameter	Description	Format	Allowed Values	Default Value
Object Name	Name of the called object.	AE name, script literal or script variable	n.a.	n.a.
WAIT	Script function waits until the object has ended . Important! You cannot use the WAIT keyword in combination with a start time.	Script literal	WAIT	n.a.
Logical Date	Logical date to use when you activate the object. For more information, see Logical Date and Real Date. (Optional) To use a different format, specify the date format, enter a separator (: or ;) and specify the date.	Script literal or script variable, YYMMDD or YYYYMMDD	n.a.	n.a.
TimeZone	Time Zone object used for timestamp calculation. For more information, see Time Zone (TZ).	Script literal or script variable	n.a.	n.a.
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") 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. For more information, see Period (PERIOD).	Script literal or script variable	n.a.	n.a.
PASS_VALUES	Passes object variables and PromptSet variables to the called object.	Script literal	PASS_VALUES	n.a.
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. For more information, see Queue (QUEUE).	AE name, script literal or script variable	n.a.	n.a.
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. The same rules apply for alias names and for object names: Maximum length: 200 characters Allowed characters: A-Z, 0-9, $, @, _, -, . and #	AE name, script literal or script variable	n.a.	n.a.
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. For more information, see PromptSets (PRPT).	Script literal	ENABLE_PROMPTS	n.a.
FixedTimeValue	Maximum runtime of the started object. 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 Executed-Object parameters for this purpose.	Script literal or script variable (HH:MM:SS format)	n.a.	n.a.
TERMINATE	Cancels the task if the maximum runtime (time limit) is exceeded.	Script literal	TERMINATE	n.a.
Executed-Object	Activates another object if the maximum runtime is exceeded.	AE name, script literal or script variable	n.a.	n.a.

Important Considerations

Key considerations include:

Execution time and start time can be two different points in time.
This script element writes all open transactions of the script 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.

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 Executing Objects: Generating Task at Activation Time vs Generating Task 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: