Using actions to run workers, create child tasks and trigger parent tasks

You can define an action to be taken on completion of a state transition within a task definition in the Workflow Service. There are currently three types of actions available for you to use in a task definition to provide further functionality to your workflow:

For example, you could use actions to help model the following workflow in a task definition:

Pass input parameters into and kick off a worker using RunWorker

You can use the RunWorker action in your task definition to kick off a run of a worker you have created in the Workflow Service. See how to create a worker.

For example, you might configure a RunWorker action in your task definition to kick off a worker that checks quotes for outliers after they're imported into LUSID. To do this, call the CreateTaskDefinition or UpdateTaskDefinition API and, within actions, pass in:

  • A name that uniquely identifies the action within the task definition.

  • The action type, which is RunWorker.

  • Optionally, a value for runAsUserId to perform the action on behalf of a service user. Read more about this.

  • The scope and code of the worker that this action should kick off.

  • Any triggers to prompt a task state transition depending on the outcome of the worker. You can configure the action to trigger a state transition when or if the worker:

    • Starts using started.

    • Completes and outputs at least one row of results using completedWithResults.

    • Completes and outputs no rows using completedNoResults.

    • Fails to start using failedToStart.

    • Fails to complete using failedToComplete.

  • Mapping for the worker input parameters. For each Luminesce view input parameter name, specify the name and either:

    • Use mapFrom to map the input parameter value from a particular task field.

    • Use setTo to set the input parameter to a particular value.

  • Any child tasks which should be created for the worker results. Each child task configuration should include the following:

    • The scope and code of the task definition for each child task.

    • Optionally, a resultMatchingPattern using LUSID's filtering syntax. If omitted, one child task is created for each row of the worker results. If resultMatchingPattern is specified, child tasks are created for a subset of the worker results. Note: If there are multiple childTaskConfigurations specified in one action, one of each of the child task configurations is created for each row of results (if it meets the resultMatchingPattern). Once a worker run has completed with results, all subsequent child tasks are created at once.

    • The trigger the child task should be prompted with as soon as it is created.

    • Mapping for the task fields of one or more child tasks. For each child task field, specify the name and either:

      • Use mapFrom to map the task field value from a particular worker result.

      • Use setTo to set the task field value to a particular value.

This portion of the API request might look like this:

...
"actions": [
  {
    "name": "quote-outliers-check-worker",
    "actionDetails" : {
      "type": "RunWorker",
      "workerId": {
        "scope": "Finbourne-Examples",
        "code": "Check-Quotes-For-Iqr-Outliers"
      },
      "workerStatusTriggers": {
        "completedWithResults": "exceptionsFound",
        "completedNoResults": "noExceptions"
      },
      "workerParameters": {
        "StartDate": {
          "MapFrom": "iqrQuoteRangeStartDate"
        },
        "EndDate": {
          "MapFrom": "iqrQuoteRangeEndDate"
        },
         "PfolioScope": {
          "SetTo": "Finbourne-Examples"
        },
         "PfolioCode": {
          "MapFrom": "portfolioCode"
        }
      },
      "childTaskConfigurations": [
        {
          "taskDefinitionId": {
            "scope": "Finbourne-Examples",
            "code": "Quote-Outliers-Exception"  
          },
          "initialTrigger": "start",
          "childTaskFields": {
            "clientInternal": {  "mapFrom": "ClientInternal" },
            "lowerLimit": {  "mapFrom": "LowerLimit" },
            "upperLimit": {  "mapFrom": "UpperLimit" },
            "price": {  "mapFrom": "Price" },
            "priceDate": {  "mapFrom": "PriceDate" },
          }
        }
      ]
    }
  }
   ]
   ...

Create one or more tasks as a child of the current task using CreateChildTasks

You can use the CreateChildTasks action in your task definition to create one or more tasks as a child of the current task on completion of a state transition.

For example, you might configure a CreateChildTasks action in your task definition to create a child task to check quotes for outliers after they're imported into LUSID. To do this, call the CreateTaskDefinition or UpdateTaskDefinition API and, within actions, pass in:

  • A name that uniquely identifies the action within the task definition.

  • The action type, which is CreateChildTasks.

  • Optionally, a value for runAsUserId to perform the action on behalf of a service user. Read more about this.

  • The scope and code of the task definition that this action should use when creating a child task.

  • Mapping for the values of child task fields. For each child task field, specify the name and either:

    • Use mapFrom to map the child task field value from a particular parent task field.

    • Use setTo to set the child task field value to a particular value.

  • The trigger the child task should be prompted with as soon as it is created.

This portion of the API request might look like this:

...
"actions": [
  {
    "name": "trigger-control-outliers-child-task",
    "actionDetails": {
      "type": "CreateChildTasks",
      "childTaskConfigurations": [
        {
          "taskDefinitionId": {
            "scope": "Finbourne-Examples",
            "code": "Control-Outlier-Quotes"
          },
          "childTaskFields": {
            "iqrQuoteRangeStartDate": {  "mapFrom": "iqrQuoteRangeStartDate"},
            "iqrQuoteRangeEndDate": {  "mapFrom": "iqrQuoteRangeEndDate"},
            "portfolioScope": {  "setTo": "Finbourne-Examples"},
            "portfolioCode": {  "mapFrom": "portfolioCode"}
          },         
          "initialTrigger": "start"
        } 
      ]
    }
  }
   ]
   ...

Note that you can create a child task for the results of a worker instead of on completion of a state transition; this must be configured within a RunWorker action. See how to do this.

Trigger a state transition for the parent of the current task using TriggerParentTask

You can use the TriggerParentTask action in your child task definition to trigger a state transition for the parent of the current task.

For example, you might configure a TriggerParentTask action in an “exception” child task definition to resume the parent task once the exception has been resolved. To do this, call the CreateTaskDefinition or UpdateTaskDefinition API and, within actions, pass in:

  • A name that uniquely identifies the action within the task definition.

  • The action type, which is TriggerParentTask.

  • Optionally, a value for runAsUserId to perform the action on behalf of a service user. Read more about this.

  • The trigger the parent task should be prompted with.

This portion of the API request might look like this:

... 
"actions": [
     {
       "name": "trigger-control-outliers-parent-task",
       "actionDetails" : {
         "type": "TriggerParentTask",
         "trigger": "resolved"
       }
     }
   ]
   ...