---
title: "How do I create a worker?"
slug: "how-do-i-create-a-worker"
updated: 2025-08-04T09:13:44Z
published: 2025-08-04T09:13:44Z
canonical: "support.lusid.com/how-do-i-create-a-worker"
---

> ## 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 worker?

Providing you are a LUSID user with sufficient privileges, you can create a worker to add functionality to your workflows, for example creating or updating an entity after receiving approval for the data.

> **Note**: If you are the LUSID domain owner, you are automatically assigned the built-in `lusid-administrator` role, which has all the permissions necessary to perform the operations in this article.

## Step 1: Create your Luminesce custom view

To create a worker, you first need to use Luminesce, our data virtualization engine, to create a [custom view](/v1/docs/using-sysadminsetupview-to-create-custom-views) which can carry out the functionality your workflow requires. For example, to support a workflow for creating or updating portfolios with new data, you might create the following custom view that:

1. Takes in a portfolio scope and code, display name, creation date and base currency as input parameters.
2. Upserts the portfolio data to LUSID; that is, create the portfolio if it does not yet exist, or update it if it does.
3. Outputs the upserted table of data.

[See how to create a Luminesce custom view.](/v1/docs/using-sysadminsetupview-to-create-custom-views)

```sql
@x = use Sys.Admin.SetupView
--provider=Worker.UpsertTransactionPortfolio
--parameters
EntityScope,Text,Finbourne-Examples,true
EntityCode,Text,FR-Equities,false
PortfolioName,Text,French Equities,false
CreatedDate,DateTime,2020-01-01,true
Currency,Text,EUR,false
----

@@portfolioType = select 'Transaction'; 
@@portfolioScope = select #PARAMETERVALUE(EntityScope);
@@portfolioCode = select #PARAMETERVALUE(EntityCode);
@@displayName = select #PARAMETERVALUE(PortfolioName);
@@createdDate = select #PARAMETERVALUE(CreatedDate);
@@currency = select #PARAMETERVALUE(Currency);
@@subHoldingKeys= select '';

@table_of_data = select 
  @@portfolioType as PortfolioType,  
  @@portfolioScope as PortfolioScope, 
  @@portfolioCode as PortfolioCode,
  @@displayName as DisplayName, 
  @@createdDate as Created, 
  @@currency as BaseCurrency, 
  @@subHoldingKeys as SubHoldingKeys;

select PortfolioScope, PortfolioCode, WriteErrorCode, WriteError, WriteErrorDetail from Lusid.Portfolio.Writer where ToWrite = @table_of_data;

enduse;

select * from @x
```

## Step 2: Create your worker

You can now create a worker to use the custom view within a workflow:

- Method 1: [Using the Workflow REST API](/v1/docs/how-do-i-create-a-worker#step-1-create-your-luminesce-custom-view)
- Method 2: [Using the LUSID web app](/v1/docs/how-do-i-create-a-worker#step-2-create-your-worker) (coming soon)

### Using the Workflow REST API

Currently, you can create one worker 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 [CreateWorker](https://www.lusid.com/docs/api/workflow/endpoints/workers/CreateWorker) API, passing in your API access token and:
  - A `scope` and `code` that together uniquely identify the worker.
  - A `displayName` and `description` for the worker.
  - A worker `type` of `LuminesceView`.
  - The `name` of the Luminesce custom view to be used.

The following example creates a worker which enables parameters to be passed into the `Worker.UpsertTransactionPortfolio` custom view [created above](/v1/docs/how-do-i-create-a-worker#step-1-create-your-luminesce-custom-view):

```json
curl -X POST "https://<your-domain>.lusid.com/workflow/api/workers"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token"
  -d "{
  "id": {
    "scope": "Finbourne-Examples",
    "code": "UpsertPortfolio"
  },
  "displayName": "Create or update portfolio",
  "description": "Worker that creates or updates a transaction portfolio",
  "workerConfiguration": {
    "type": "LuminesceView",
    "name": "Worker.UpsertTransactionPortfolio"
  }
}"
```

Part of the response looks like this, showing which input parameters the Luminesce view takes in and the fields the view can output:

```json
{
  "id": {
    "scope": "Finbourne-Examples",
    "code": "UpsertPortfolio"
  },
  "workerConfiguration": {
    "type": "LuminesceView",
    "name": "Worker.UpsertTransactionPortfolio"
  },
  "parameters": [
    {
      "type": "DateTime",
      "name": "CreatedDate",
      "displayName": "Created Date",
      "required": false,
      "defaultValue": "2020-01-01T00:00:00Z"
    },
    {
      "type": "String",
      "name": "Currency",
      "displayName": "Currency",
      "required": true
    },
    {
      "type": "String",
      "name": "EntityCode",
      "displayName": "Entity Code",
      "required": true
    },
    {
      "type": "String",
      "name": "EntityScope",
      "displayName": "Entity Scope",
      "required": false,
      "defaultValue": "Finbourne-Examples"
    },
    {
      "type": "String",
      "name": "PortfolioName",
      "displayName": "Portfolio Name",
      "required": true
    }
  ],
  "resultFields": [
    {
      "name": "PortfolioCode",
      "type": "String",
      "displayName": "Portfolio Code"
    },
    {
      "name": "PortfolioScope",
      "type": "String",
      "displayName": "Portfolio Scope"
    },
    {
      "name": "WriteError",
      "type": "String",
      "displayName": "Write Error"
    },
    {
      "name": "WriteErrorCode",
      "type": "Decimal",
      "displayName": "Write Error Code"
    },
    {
      "name": "WriteErrorDetail",
      "type": "String",
      "displayName": "Write Error Detail"
    }
  ],...
```

You can set up your workflow to do a variety of things with a worker's output, or `resultFields`, such as:

- Trigger a parent task
- Create a child task
- Trigger another worker.

For example, you might tweak the worker above to only return non-zero error codes and configure your task definition to create an exception task which takes in any result fields, ready for a person to investigate further.

You can check your worker functions as expected by calling the [RunWorker](https://www.lusid.com/docs/api/workflow/endpoints/workers/RunWorker) API, passing in your API access token and:

- The worker `scope` and `code`
- The parameter `name` and `value` pairs you wish to pass into your Luminesce custom view.

For example:

```json
curl -X POST "https://<your-domain>.lusid.com/workflow/api/workers/Finbourne-Examples/UpsertPortfolio/$run"
  -H "accept: text/plain"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "parameters": [
    {
      "name": "EntityScope",
      "value": "Finbourne-Examples"
    },
    {
      "name": "EntityCode",
      "value": "Worker-Test-Portfolio"
    },
    {
      "name": "PortfolioName",
      "value": "Test for making sure worker runs as expected"
    },
    {
      "name": "Currency",
      "value": "GBP"
    },
    {
      "name": "CreatedDate",
      "value": "2023-01-01"
    }
  ]
}"
```

Note the `runId` in the response. You can inspect the current status and outcome of your worker run by calling the [GetWorkerResult](https://www.lusid.com/docs/api/workflow/endpoints/workers/GetWorkerResult) API, passing in your API access token and the `runId`, for example:

```json
curl -X GET "https://<your-domain>.lusid.com/workflow/api/workers/303/$result"
  -H "accept: text/plain"
  -H "Authorization: Bearer <your-API-access-token>"
```

Once you have created your worker, you can empower your workflow by configuring a task definition to include your worker. [See how to configure workers in your task definitions.](/v1/docs/how-do-i-create-a-task-definition)

### Using the LUSID web app

<Coming soon>

A series of one of more task definitions and workers that combine to complete a process.

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.

An occurrence of the workflow defined in a task definition. You can create multiple tasks from one task definition, typically with changing input values, for example you might create one task per LUID for securities to be screened.

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.