--- title: "How do I use system event handlers to automatically create or update tasks?" slug: "how-do-i-use-system-event-handlers-to-automatically-create-or-update-tasks" updated: 2025-11-05T12:15:03Z published: 2025-11-05T12:15:03Z canonical: "support.lusid.com/how-do-i-use-system-event-handlers-to-automatically-create-or-update-tasks" --- > ## 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 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](/v1/docs/what-is-an-event-in-lusid#system) 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](/v1/docs/setting-up-a-data-quality-control-to-check-new-pricing-data-for-outliers) when a CSV file arrives in Drive - When a [business calendar](/v1/docs/using-calendars-in-lusid)-aware schedule is triggered ## Methods Workflow APILUSID web appLuminesce Call the [CreateEventHandler](https://www.lusid.com/docs/api/workflow/endpoints/event-handlers/CreateEventHandler) API. The fields you must supply depend on your matching pattern type. For an `eventMatchingPattern`, the following example creates an event handler that creates an [Import-Quotes-From-File task](/v1/docs/setting-up-a-data-quality-control-to-check-new-pricing-data-for-outliers) when a file is uploaded to the `/quotes` folder in Drive: ```json curl -X POST "https://.lusid.com/workflow/api/eventhandlers"  -H "Authorization: Bearer "  -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 '//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" }       } } }" ``` For a `scheduleMatchingPattern`, you might send the following in the request body to create a daily run-reconciliation task for the previous day, between the 1st and 8th August: ```json {  "id": {    "scope": "Finbourne-Examples",    "code": "Daily-Reconciliation"  },  "displayName": "Daily Reconciliation Schedule",  "description": "Creates reconciliation tasks on business days with appropriate effective dates",  "status": "Active",  "taskDefinitionId": {    "scope": "Finbourne-Examples",    "code": "run-reconciliation"  },  "runAsUserId": { "setTo": "00u5mi3egiUNgaCtW2p7" },  "scheduleMatchingPattern": {    "context": { "timeZone": "GB" },    "recurrencePattern": {      "timeConstraints": {        "startDate": "2025-08-01",        "endDate": "2025-08-09",        "timesOfDay": [ {            "type": "Specified",            "hours": 10,            "minutes": 30          }, {            "type": "Specified",            "hours": 10,            "minutes": 45          } ]      },      "dateRegularity": {        "type": "Day",        "frequency": 1      },      "businessDayAdjustment": "Following"    }  },  "taskActivity": {    "type": "CreateNewTask",    "scheduleDependentTaskFields": {      "effectiveDate": {        "dateAdjustment": {          "deltaDays": -1,          "businessDayAdjustment": "Following"        },        "timeAdjustment": {          "setTo": {            "type": "Specified",            "hours": 17,            "minutes": 0          }        }      },      "processingDate": {        "dateAdjustment": {          "deltaDays": 1,          "businessDayAdjustment": "Following"        },        "timeAdjustment": {          "setTo": {            "type": "Specified",            "hours": 9,            "minutes": 15          }        }      }    }  } } ``` Coming soon. Coming soon. Once you have created an event handler, you can monitor tasks in the [LUSID web app](https://www.lusid.com/app/home) by navigating via the top left menu to **Workflow Service > Dashboard**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/5dbe9781-34f5-4ff7-bf43-2371c70228d9.png) ## Fields You should specify either: - An `eventMatchingPattern` for system event triggers - A `scheduleMatchingPattern` for scheduled triggers ### `eventMatchingPattern` For an event handler that can trigger task transitions when system events occur in LUSID, you must specify: - The system event you want to handle under `eventType`. [See what system events you can handle.](/v1/docs/what-system-events-can-i-subscribe-to) - Optionally, a `filter` to handle the specified system event conditionally. [See how to use LUSID filtering syntax.](/v1/docs/using-lusid-filtering-syntax-to-subscribe-to-events-conditionally) ### `scheduleMatchingPattern` For an event handler that can trigger task transitions on a schedule, you must specify: - The schedule `context`, containing: - A `timeZone` as an [ISO country code or IANA timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - Optionally, one or more `holidayCalendars` to define [business days](/v1/docs/using-calendars-in-lusid). You can retrieve the `scope` and `code` of your calendars by calling the [ListCalendars](https://www.lusid.com/docs/api/lusid/endpoints/calendars/ListCalendars) API. - The `recurrencePattern` for when and how often to trigger the schedule, containing: - `timeConstraints`: - When the schedule should come into effect as `startDate` - Optionally, when the schedule should end as `endDate` - The `timesOfDay` the schedule should trigger at. You can specify one or more specific times, or [cut labels](/v1/docs/what-is-a-cut-label) (if specified, LUSID prioritises the cut label timezone over `timeZone`). - One of the following `dateRegularity` types to define how often the schedule should repeat and on which specific dates: - `Day`: The `frequency` value tells the schedule to trigger every `x` days. - `SpecificMonth`: - The `frequency` value tells the schedule to trigger every `x` months. - The `daysOfMonth` value tells the schedule to trigger on the `x` day of the month, for example `-1` defines this as the last day of the month. - `RelativeMonth`: - The `frequency` value tells the schedule to trigger every `x` months. - The `daysOfWeek` value tells the schedule to trigger on particular days. - The `index` value tells the schedule the relative position in the month to trigger, for example `First`, `Third`, or `Last`. - `Week`: - The `frequency` tells the schedule to trigger every `x` weeks. - The `dayOfWeek` tells the schedule to trigger on particular days of that week. - `Year`: One or more `month` and `day` combinations that tell the schedule to trigger every year on a particular date. - One of the following `businessDayAdjustment` values to define the [business day convention](/v1/docs/roll-conventions-and-business-day-conventions) for the schedule: - `Following` - `Preceding` - `ModifiedFollowing` - `ModifiedPreceding` - `None` *****Click to expand example: Trigger a workflow on every hour, every day***** ```json ... "scheduleMatchingPattern": {        "context": {            "timeZone": "UTC"        },        "recurrencePattern": {            "timeConstraints": {                "startDate": "2025-08-01",                "endDate": "2025-09-01",                "timesOfDay": [                    {                        "type": "Specified",                        "hours": 0,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 1,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 2,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 3,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 4,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 5,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 6,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 7,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 8,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 9,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 10,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 11,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 12,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 13,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 14,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 15,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 16,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 17,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 18,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 19,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 20,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 21,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 22,                        "minutes": 0                    },                    {                        "type": "Specified",                        "hours": 23,                        "minutes": 0                    }                ]            },            "dateRegularity": {                "type": "Day",                "frequency": 1            },            "businessDayAdjustment": "None"        }    }, ... ``` For schedule-based handlers, you can use either: - `taskFields` to populate static field values, as with system event handlers - `scheduleDependentTaskFields` to set dynamic field values that transform the scheduled datetime for your task fields. For each task field, you can specify: - `dateAdjustment` to modify the date relative to the schedule trigger: - A positive or negative number of days, weeks, months, and/or years to add or subtract: - `deltaDays` - `deltaWeeks` - `deltaMonths` - `deltaYears` - `businessDayAdjustment` values to define the [business day convention](/v1/docs/roll-conventions-and-business-day-conventions) for the schedule: - `Following` - `Preceding` - `ModifiedFollowing` - `ModifiedPreceding` - `None` - `timeAdjustment` to modify the time; you can use either: - `setTo` to set the value to a specific time: - `type` value of `Specified` for fixed times - An `hours` value between `0` and `23` - A minutes value between `0` and `59` - `addTime` to modify the existing scheduled time: - An `hours` value between `0` and `23` - A `minutes` value between `0` and `59` ### `taskActivity` 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.](/v1/docs/using-lusid-filtering-syntax-to-subscribe-to-events-conditionally) - 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 ### `runAsUserId` A value for `runAsUserId` to create or update the task on behalf of a service user. [Read more about this.](/v1/docs/setting-up-a-schedule-subscription-or-other-activity-on-behalf-of-a-service-user) *Either*: - Use `mapFrom` with the value `header.userId` to map from the user ID of the user who created the event. - Use `setTo` to set the value to a particular [service user ID](/v1/docs/what-is-a-user-id-and-how-do-i-discover-one). ### `taskDefinitionAsAt` A `taskDefinitionAsAt` to control the task definition version used by the system event handler. If omitted, the value defaults to the current datetime. 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. 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. 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. 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.