--- title: "How do I create a task?" slug: "how-do-i-create-a-task" tags: ["workflow service"] updated: 2025-08-04T09:41:37Z published: 2025-08-04T09:41:37Z canonical: "support.lusid.com/how-do-i-create-a-task" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/v1/docs/how-do-i-create-a-task-definition). Note the following: - Once created, you can [update a task](/v1/docs/how-do-i-create-a-task#updating-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. ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/3759303a-b635-49ec-8dab-99ebba8a768b.png) - Method 1: [Using the Workflow REST API](/v1/docs/how-do-i-create-a-task#using-the-workflow-rest-api) - Method 2: [Using the LUSID web app](/v1/docs/how-do-i-create-a-task#using-the-lusid-web-app) - Method 3: [Using system event handlers](/v1/docs/how-do-i-create-a-task#using-system-event-handlers) ## Using the Workflow REST API Currently, you can create one task per API call. 1. [Obtain an API access token](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta). 2. Call the [CreateTask](https://www.lusid.com/docs/api/workflow/endpoints/tasks/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](/v1/docs/how-do-i-create-a-task-definition). - Optionally, one or more `correlationIds` to [track and group API calls](/v1/docs/tracking-and-grouping-api-calls-using-correlation-ids). - 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. ```json curl -X POST "https://.lusid.com/workflow/api/tasks"  -H "Authorization: Bearer "  -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: ```json {  "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](https://www.lusid.com/docs/api/workflow/endpoints/tasks/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. ```json curl -X POST "https://.lusid.com/workflow/api/tasks/79315001-b4bf-40e6-aae1-24850119aa9f?trigger=grant"  -H "Authorization: Bearer "  -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`: ```json {  ...  "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](https://www.lusid.com/workflow/swagger/index.html) API, passing in the task `id` and, optionally, an `asAt` datetime: ```sql curl -X GET "https://.lusid.com/workflow/api/tasks/79315001-b4bf-40e6-aae1-24850119aa9f" -H "Authorization: Bearer " -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](https://www.lusid.com/app/home) and select **Workflow Service > Tasks** from the left-hand menu: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/344409ca-8cfa-446c-845e-ac9420c8fca1.png) 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/16f258a5-931a-4647-8870-c29c1bf0a6a6.png) 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/12c323e3-9170-44dd-a352-47a578ade29c.png) ## Using system event handlers [See how to automatically create or update tasks when LUSID emits a system event.](/v1/docs/how-do-i-use-system-event-handlers-to-automatically-create-or-update-tasks) The way in which data is passed into, around and out the other end of the task in the Workflow Service. Field names and data types are completely customisable and can be defined in a task definition. Field values can be specified when creating or updating a task. Defined within a state transition, a prompt which induces a state transition to occur in the Workflow Service. Movement from one state to another in the Workflow Service. Each state transition includes a start state, end state and is prompted by a trigger. An operational condition which must be met for a state transition to succeed in the Workflow Service. For example, all child tasks are in the state **Complete** . A condition a task can exist in, for example **Pending**, **In progress**, or **Complete**. State names are customisable and can be defined in a task definition. Movement from one state to another in the Workflow Service. Each state transition includes a start state, end state and is prompted by a trigger. Modelled as a Mealy state machine, a sequence of states and actions which encapsulate a workflow (or part of a complex workflow). Within a task definition, you can configure parameters for a task, such as states, fields and allowable state transitions. Task definitions also include actions, which can run workers to interrogate your data and generate child tasks. The task definition determines what a particular task does when an instance of that task occurs. The way in which data is passed into, around and out the other end of the task in the Workflow Service. Field names and data types are completely customisable and can be defined in a task definition. Field values can be specified when creating or updating a task. A series of one of more task definitions and workers that combine to complete a process.