How do I use system event handlers to automatically create or update tasks?

Providing you are a LUSID user with sufficient privileges, you can create a system event handler that automatically creates or updates a task in the Workflow Service when a system event occurs in LUSID. For example, you could create an event handler for the FileCreated event that creates a new task to import quotes and check them for outliers when a CSV file arrives in Drive.

Using the Workflow REST API

Currently, you can create one system event handler per API call.

  1. Obtain an API access token.

  2. Call the CreateEventHandler API, passing in your API access token and:

    • A scope and code that together uniquely identify the event handler.

    • A friendly displayName and description for the event handler.

    • An eventMatchingPattern containing:

    • The scope and code of an existing task definition.

    • Optionally, a taskDefinitionAsAt to control the task definition version used by the system event handler. If omitted, the value defaults to the current datetime.

    • The taskActivity to perform when a matching system event occurs. There are two types of activity:

      • To create a new task, specify:

        • A type value of CreateNewTask.

        • An initialTrigger to prompt a state transition when the task is kicked off.

        • taskFields to define mapping for the task field values. For each task field you want to populate, specify the name and either:

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

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

      • To update existing open tasks, specify:

        • A type value of UpdateMatchingTasks.

        • Optionally, a filter to update existing open tasks conditionally. See how to use LUSID filtering syntax.

        • A trigger to prompt a state transition.

        • taskFields to define mapping for the task field values. For each task field you want to populate, specify the name and either:

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

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

    • A value for runAsUserId to create or update the task on behalf of a service user. Read more about this.

The following example creates an event handler that creates an Import-Quotes-From-File task when a file is uploaded to the /quotes folder in Drive:

curl -X POST "https://<your-domain>.lusid.com/workflow/api/eventhandlers"
  -H "Authorization: Bearer <your-api-access-token>"
  -H "Content-Type: application/json-patch+json"
  -d "{
  "id": {
    "scope": "Finbourne-Examples",
    "code": "New-Quotes-File"
  },
  "displayName": "NewQuotesFileInDrive",
  "description": "Event handler that creates a quote import and data quality check task when a new file arrives in the quotes folder in Drive.",
  "status": "Active",
  "eventMatchingPattern": {
    "eventType": "FileCreated",
    "filter": "body.filePath startswith '/<your-domain>/quotes'"
  },
  "runAsUserId": {
    "setTo": "00uji4ve5haBc1Hlf2p7"
  },
  "taskDefinitionId": {
    "scope": "Finbourne-Examples",
    "code": "Import-Quotes-From-File"
  },
  "taskActivity": {
    "initialTrigger": "start",
    "type": "CreateNewTask",
    "taskFields": {
      "folder":
        { "mapFrom": "body.filePath" },
      "quoteScope":
        { "setTo": "Finbourne-Examples" }  
     }
}
}"

Part of a response is as follows:

{
  "id": {
    "scope": "Finbourne-Examples",
    "code": "New-Quotes-File"
  },
  "version": {
    "asAtCreated": "2024-06-05T15:12:39.3181750+00:00",
    "userIdCreated": "00uji4twb4jDcHGjN2q7",
    "requestIdCreated": "0HN44I6HGTMTA:00000002",
    "asAtModified": "2024-06-05T15:12:39.3181750+00:00",
    "userIdModified": "00uji4twb4jDcHGjN2q7",
    "requestIdModified": "0HN44I6HGTMTA:00000002",
    "asAtVersionNumber": 1
  },
 ...

Once you have created an event handler, you can monitor tasks in the LUSID web app by navigating via the top left menu to Workflow Service > Dashboard: