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 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:

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

See how to create a Luminesce custom view.

@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
Method 2: Using the LUSID web app (coming soon)

Using the Workflow REST API

Currently, you can create one worker per API call.

Obtain an API access token.
Call the 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:

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:

{
  "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 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:

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 API, passing in your API access token and the runId, for example:

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.

Using the LUSID web app