---
title: Event Handlers (Actions)
slug: event-handlers-actions
createdAt: 2025-10-29T21:34:48.525Z
---

Event Handlers define what happens when a connector detects a change (create, update, delete, enable, disable, etc.). They live inside \<events> blocks within change handler definitions.

Each event type can contain one or more **steps** that specify what to do — submit a job, run a script, notify users, update tickets, and more.

# Supported Event Steps

| Step                | Purpose                                               |
| ------------------- | ----------------------------------------------------- |
| submit              | Submit a job or task within Activate.                 |
| execute             | Run a script directly from the workflow.              |
| notify              | Send an email or in-system notification.              |
| end                 | End the current workflow successfully.                |
| retry               | Leave the change pending and rerun later.             |
| error               | Throw an error and mark the row as failed.            |
| set                 | Set Activate parameters or attributes.                |
| ticket              | Create or update a ticket in Activate.                |
| publish / unpublish | Change the publication state of provisioning objects. |

## Example

:::BlockQuote
\<events>
&#x20; \<create>
&#x20;   \<submit>
&#x20;     \<task>=//Tasks/User/Create User\</task>
&#x20;     \<arguments>
&#x20;       \<user>
&#x20;         \<firstName>%=//Current/firstName%\</firstName>
&#x20;         \<lastName>%=//Current/lastName%\</lastName>
&#x20;         \<manager>=//Links/manager\</manager>
&#x20;       \</user>
&#x20;     \</arguments>
&#x20;   \</submit>
&#x20; \</create>
\</events>
:::

## Step Details

### submit

Submit a task to Activate’s workflow engine.

:::BlockQuote
\<submit>
&#x20; \<task>=//Tasks/User/Update User\</task>
&#x20; \<arguments>
&#x20;   \<data>
&#x20;     \<user>=//User\</user>
&#x20;     \<department>=//Current/department%\</department>
&#x20;   \</data>
&#x20; \</arguments>
\</submit>
:::

### execute

Run a script inline or referenced from a resource.

:::BlockQuote
\<execute>=//Scripts/UpdateUserFields\</execute>
:::

### notify

Send an email or message, optionally conditional.

:::BlockQuote
\<notify>
&#x20; \<when>errors\</when>
&#x20; \<users>admin\@domain.com\</users>
&#x20; \<message>
&#x20;   \<subject>Connector Error\</subject>
&#x20;   \<body>\<!\[CDATA\[
&#x20;     The Employee connector encountered %=//Errors/Count% error(s):
&#x20;     \<table class='grid'>
&#x20;       \<tr>\<th>ID\</th>\<th>Name\</th>\<th>Error\</th>\</tr>
&#x20;       %=foreach(=//Errors, "\<tr>\<td>%=/employeeNumber%\</td>\<td>%=/displayName%\</td>\<td>%=/Log/0/Message%\</td>\</tr>")%
&#x20;     \</table>
&#x20;   ]]>\</body>
&#x20; \</message>
\</notify>
:::

### ticket

Log or update an Activate ticket.

:::BlockQuote
\<ticket>
&#x20; \<ticketNumber>=/ticketNumber\</ticketNumber>
&#x20; \<name>=/name\</name>
&#x20; \<state>=if(=/state, "Closed", "Open")\</state>
&#x20; \<status>=/status\</status>
&#x20; \<user>=//User\</user>
&#x20; \<description>=/details\</description>
&#x20; \<notes>=/notes\</notes>
\</ticket>
:::

**Ticket fields**

| Field        | Required | Example            | Description               |
| ------------ | -------- | ------------------ | ------------------------- |
| ticketNumber | Optional | HR12345            | External ticket number.   |
| name         | Optional | Onboarding Failure | Ticket title.             |
| description  | Optional | —                  | Detailed message.         |
| state        | Optional | Open / Closed      | Ticket state in Activate. |
| status       | Optional | Assigned           | External status.          |
| user         | Optional | =//User            | Assigned user.            |
| notes        | Optional | —                  | Long-form note text.      |
| type         | Optional | Request / Fault    | Ticket type.              |
| priority     | Optional | High               | Ticket priority.          |
| category     | Optional | Hardware           | Ticket category.          |

### retry

Keep the change pending and rerun later.

:::BlockQuote
\<retry />
:::

### error

Mark a change as failed and stop processing.

:::BlockQuote
\<error>User could not be updated\</error>
:::

### set

Assign parameters without needing a script.

:::BlockQuote
\<set>
&#x20; \<departmentCode name="DepartmentCode" type="String">=/departmentCode\</departmentCode>
\</set>
:::

### publish / unpublish

Toggle publication status of provisioning objects.

:::BlockQuote
\<publish />
\<unpublish />
:::

# Best Practices

- Chain multiple steps in order: e.g., submit → set → notify.&#x20;
- Use when=errors in notify blocks to alert only on failures.&#x20;
- Keep retry timeouts bounded — use options/retry/timeout in the process.&#x20;
- Avoid infinite loops: ensure scripts and jobs don’t re-trigger the same connector immediately.&#x20;