---
title: Change Handlers
slug: change-handlers
docTags:
createdAt: 2025-10-29T21:35:03.848Z
---
Change Handlers consume pending changes detected by processImport and decide what to do (submit jobs, create roles, update users, log tickets, etc.). You select a handler by setting the process/provider in the workflow.
# Shared Concepts
**Where they run**
After processImport, each row in the **data** table with a pending action (Create/Update/Delete) is passed to the handler.
**Common options**
:::BlockQuote
\
\Innovation.Activate.Library\Innovation.Activate.Connectors.UserChangeHandler\
\
\0\ \
\500\
\
\+2days\ \
\false\ \
\
\
\
\
:::
**Common events** (inside an \ block)
- create, update, move, delete, enable, disable
- Steps you can use: submit, execute, notify, end, retry, error, set, ticket, publish, unpublish
# UserChangeHandler
Use when connector data represents **people** that should link to AD users and drive identity lifecycle automation.
**Minimum config**
:::BlockQuote
\
\Innovation.Activate.Library\Innovation.Activate.Connectors.UserChangeHandler\
\
\
\=//Roles/System Roles/Users\
\(employeeNumber=%=//Current/employeeNumber%)\
\(samAccountName=%=//Current/domainName%)\
\(givenName=%=//Current/firstName%)(sn=%=//Current/lastName%)\
\
\
\=/isActive\
\
\
\
\=//Roles/System Roles/Users\
\(samAccountName=%=//Current/managerDomainName%)\
\
\
\
\
\
\=//Tasks/User/Create User\
\
\
\%=//Current/firstName%\
\%=//Current/lastName%\
\=//Links/manager\
\
\
\
\
\
\
:::
**Globals provided**
- User — matched AD user (if found)
- Links — collection of additional linked users (e.g., manager)
- RoleLinks — roles resolved by role link handlers
# RoleChangeHandler
Use when connector data represents a **hierarchy** you want as Activate **Roles** (e.g., departments, locations).
**Minimum config**
:::BlockQuote
\
\Innovation.Activate.Library\Innovation.Activate.Connectors.RoleChangeHandler\
\
\=//Roles/Departments\
\DepartmentCode\
\departmentCode\
\=//Current/department\
\
\parentCode\ \
\
\=/departmentCode\
\
\
\
\
\Created by import %=//System/Now%\
\
\
\
\
\
:::
**Events raised by handler**: create, update, delete (plus createRole step for new roles)
# GenericChangeHandler
Use when you need event-driven actions (submit jobs, run scripts) without built-in user/role semantics.
**Minimal skeleton**
:::BlockQuote
\
\Innovation.Activate.Library\Innovation.Activate.Connectors.GenericChangeHandler\
\
\
\
\
\
\
\=//Tasks/Custom/Create Thing\
\
\
\=/id\
\
\
\
\
\
\
:::
**Globals**: Links (if configured)
# ScriptChangeHandler
Use when change processing logic itself must be scripted (complex business rules, multi-step orchestration).
**Skeleton**
:::BlockQuote
\
\Innovation.Activate.Library\Innovation.Activate.Connectors.ScriptChangeHandler\
\
\
\200\
\
\
:::
# ServiceDeskTicketChangeHandler
Use when connector data represents **tickets** you want to create/update inside Activate.
**Minimum config**
:::BlockQuote
\
\Innovation.Activate.Library\Innovation.Activate.Connectors.ServiceDeskTicketChangeHandler\
\
\
\
\
\
\=/ticketNumber\
\=/jobId\
\
\
\
\
\=/ticketNumber\
\=/name\
\=if(=/state, "Closed", "Open")\
\=/status\
\=//User\
\=/details\
\=/notes\
\
\
\
\
:::
**Globals**: User (if user link configured), Ticket (when matched)
# Event Steps (Quick Reference)
- **submit** — Submit a job/task with arguments.
- **execute** — Run a script (inline reference).
- **notify** — Send an email/notification (supports when=errors).
- **end** — Mark successful end of the current event.
- **retry** — Keep change pending to retry later.
- **error** — Mark row as error; respects retry policy.
- **set** — Set parameter values without a script.
- **ticket** — Create/update an Activate ticket.
- **publish / unpublish** — Toggle publication state for provisioning objects.
# Troubleshooting & Hardening
- Use options/retry/timeout to bound retry loops; alert on exceeded retries.
- Emit **meaningful messages** in error so operators can triage quickly.
- Add notify with when=errors and include a table of last error rows.
- For bulk anomalies, prefer end + notify + manual intervention over automated retries.