Managing a shadow task from the Orchestration CLI

You can create a shadow task from the Orchestration CLI to establish a cross dependency on a remote engine by configuring the specific shadow task plug-in attributes and referencing an endpoint.

Overview

You can define a shadow task by running the ocli model new command and configuring the template. This process establishes a dependency on a remote engine, known as a cross dependency.

To successfully configure a shadow task, you need the following access and information:

Connection parameters (URL and API Key) for the remote engine, or USE access to an existing Endpoint definition.
ADD access to tasks.

Important: When defining connection parameters for a shadow task or its referenced endpoint, you must use an API Key of type Cross dependencies. If a valid API Key of any other type (such as Personal or Service) is provided, bind requests and test connection actions explicitly fail and return an error.

Restriction: Shadow tasks do not support the kill command.

Configuration template

The ocli model new job command generates a template where you define mandatory and optional attributes. You can list connection parameters explicitly in the Connection section or specify an endpointRef to point to an existing endpoint object.

The following example demonstrates a shadow task definition with inline connection parameters:

[folder/]workstation#jobname 
     TASK
     {
         "unoshadowtask": {
             "Action": {
                 "remoteTask": {
                     "workstation": "/target_workstation",
                     "workflow": "/folder/target_workflow",
                     "taskName": "target_task_name",
                     "successOnFailedBind": false,
                     "mandatory": false,
                     "matchingCriteria": {
                         "type": "useDefault"
                     }
                 }
             },
             "Connection": {
                 "urls": ["https://remote_engine_url:port"],
                 "jwt": "your_api_key_or_encrypted_token",
                 "hostnameSSLVerification": false
             }
         }
     }
     RECOVERY STOP

Note: To use an endpoint instead of inline connection parameters, remove the Connection block and add endpointRef: /Your_Folder/Your_Endpoint_Name at the definition level.

Shadow task attributes

unoshadowtask: The shadow task plug-in type. Specify the plug-in that corresponds to the target remote engine (in this example, an HCL Universal Orchestrator to HCL Universal Orchestrator connection).
Action: The block that contains the target identification details, specified under remoteTask.
workstation: The target workstation where the remote workflow runs.
workflow: Mandatory. The identifier of the target workflow. For HCL Universal Orchestrator, specify the full folder path and workflow name.
taskName: The identifier of the specific target task to monitor.
successOnFailedBind: A Boolean flag (true or false). If set to true, the shadow task completes successfully (SUCC status) even if the binding process fails.
mandatory: A Boolean flag (true or false). If set to true and the system cannot find the remote instance, the bind request waits until the instance appears or the pre-production plan ends. If false, the shadow task fails immediately if the system cannot find the instance.