How do I create a task?

Providing you are a LUSID user with sufficient privileges, you can create a task to set in motion the workflow modelled in a task definition. Note the following:

• Once created, you can update a task to supply new field values and/or manually trigger state transitions at any time.
• A task continues to operate according to the original specification even if the underlying task definition is updated or deleted.

• Method 1: Using the Workflow REST API
• Method 2: Using the LUSID web app
• Method 3: Using system event handlers

Using the Workflow REST API

Currently, you can create one task per API call.

1. Obtain an API access token.
2. Call the CreateTask API, passing in:
   • Optionally, a trigger in the request URL. Providing any guard conditions are met, the trigger transitions the task to a particular state. If omitted, the task is created in its initial state.
   • The scope and code of an existing task definition. See how to create a task definition.
   • Optionally, one or more correlationIds to track and group API calls.
   • A name and an appropriate value for any required fields. This may be field(s) required by the initial state and, if a trigger with a guard is specified, field(s) required by that guard.

curl -X POST "https://<your-domain>.lusid.com/workflow/api/tasks"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{
  "taskDefinitionId": {
    "scope": "approvals",
    "code": "dataApproval"
  },
  "correlationIds": ["track-this-in-the-logs"],
  "fields": [
    {
      "name": "dataToApproveDescription",
      "value": "Data x for this x client"
    }
  ]
}'

Part of a response is shown below. Note the unique id, which can be used to retrieve or update the task:

{
  "id": "79315001-b4bf-40e6-aae1-24850119aa9f",
  "correlationIds": [
    "track-this-in-the-logs"
  ],
  "taskDefinitionId": {
    "scope": "approvals",
    "code": "dataApproval"
  },
  "taskDefinitionVersion": {
    "asAtModified": "2023-09-15T11:08:15.1522320+00:00"
  },
  "version": {
    "asAtCreated": "2023-09-15T12:39:12.8015030+00:00",
    "userIdCreated": "00uji4twb4jDcHGjN2p7",
    "asAtModified": "2023-09-15T12:39:12.8015030+00:00",
    "userIdModified": "00uji4twb4jDcHGjN2p7",
    "asAtVersionNumber": 1
  },
  "state": "Pending",
  "terminalState": true,
  ...

Updating a task

You can update a task to supply new field values and/or manually trigger state transitions. To do so, call the UpdateTask API, passing in the following:

• Within the request URL:
  • The unique id for the task you want to update.
  • Optionally, a trigger to prompt a state transition.
• The name and an appropriate value for fields you want to update, or propagate, or that are required to meet guard conditions.

Note that when updating a task, any fields or correlationIds not provided in the request are set to null.

curl -X POST "https://<your-domain>.lusid.com/workflow/api/tasks/79315001-b4bf-40e6-aae1-24850119aa9f?trigger=grant"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{
  "fields": [
    {
      "name": "assignee",
      "value": "Joe Bloggs"
    },
    {
      "name": "dataToApproveDescription",
      "value": "Data x for this y client"
    },
    {
      "name": "portfolioScope",
      "value": "Finbourne-Examples"
    },
    {
      "name": "portfolioCode",
      "value": "New-UK-Equities"
    },
    {
      "name": "baseCurrency",
      "value": "GBP"
    },
    {
      "name": "displayName",
      "value": "New UK Equities Portfolio"
    },
  ]
}'

Part of a response is shown below. Note the incremented asAtVersionNumber and, since a trigger was specified above, the new task state:

{
  ...
  "taskDefinitionVersion": {
    "asAtModified": "2023-09-16T08:12:42.2904480+00:00"
  },
  "version": {
    "asAtCreated": "2023-09-16T13:57:37.9615180+00:00",
    "userIdCreated": "00uji4twb4jDcHGjN2p7",
    "asAtModified": "2023-09-16T13:58:08.3013150+00:00",
    "userIdModified": "00uji4twb4jDcHGjN2p7",
    "asAtVersionNumber": 2
  },
  "state": "Approved",
  "terminalState": true,
  ...

You can check the current status of a task, when it was last modified, who last modified it and more by calling the GetTask API, passing in the task id and, optionally, an asAt datetime:  

curl -X GET "https://<your-domain>.lusid.com/workflow/api/tasks/79315001-b4bf-40e6-aae1-24850119aa9f"
 -H "Authorization: Bearer <your-API-access-token>"
 -H "Content-Type: application/json"

Using the LUSID web app

You can create tasks and view their current status via the LUSID web app:

1. Sign into the LUSID web app and select Workflow Service > Tasks from the left-hand menu:
   
2. On the Tasks dashboard, click the Create task button (top right).
3. Select the task definition to create a task from.
4. On the Create task screen, specify values for all the required fields (indicated by a '*') plus values for any optional fields you want to provide. Note you can select State transition diagram to inspect the workflow as a state diagram generated by the web app:
     
5. Select Save to create the new task.

Once the task is created, you can inspect and edit this task and any of your other tasks via the Workflow Service > Dashboard menu:

Using system event handlers

See how to automatically create or update tasks when LUSID emits a system event.