---
title: Link Handlers
slug: link-handlers
docTags: 
createdAt: 2025-10-29T21:34:57.174Z
---

Link Handlers are reusable lookup definitions that let a connector find related data in other systems or in Activate itself. They are often used by Change Handlers to resolve users, managers, roles, or tickets.

# AD Link Handler

The **AD Link Handler** looks up Active Directory entries based on connector data.

**Example**

:::BlockQuote
\<link name="User Account">
&#x20; \<scope>=//Roles/System Roles/Users\</scope>
&#x20; \<match when="employeeNumber">(employeeNumber=%=//Current/employeeNumber%)\</match>
&#x20; \<match when="domainName">(samAccountName=%=//Current/domainName%)\</match>
&#x20; \<match>(givenName=%=//Current/firstName%)(sn=%=//Current/lastName%)\</match>
\</link>
:::

## Attributes

| Path  | Required | Example                                  | Description                                                      |
| ----- | -------- | ---------------------------------------- | ---------------------------------------------------------------- |
| scope | Optional | =//Roles/System Roles/Users              | Sets the AD search scope. Defaults to Global Catalog if not set. |
| match | ✅        | (samAccountName=%=//Current/domainName%) | LDAP filter or field reference to use for lookup.                |
| when  | Optional | employeeNumber                           | Expression or field name controlling when to run that match.     |

## Supported match formats

| Format        | Description                                       |
| ------------- | ------------------------------------------------- |
| (filter=...)  | LDAP filter string searched in the current scope. |
| DOMAIN\\\user | Domain + username combination (bypasses scope).   |
| GUID          | Direct GUID lookup in AD (bypasses scope).        |

# Role Link Handler

The **Role Link Handler** finds or creates Activate Roles based on connector fields. It’s the basis of most RoleChangeHandlers.

**Example**

:::BlockQuote
\<role>
&#x20; \<root>=//Roles/Departments\</root>
&#x20; \<key>DepartmentCode\</key>
&#x20; \<field>departmentCode\</field>
&#x20; \<name>=//Current/department\</name>
&#x20; \<parent>parentCode\</parent>
&#x20; \<parameters>
&#x20;   \<departmentCode name="DepartmentCode" type="String">=/departmentCode\</departmentCode>
&#x20; \</parameters>
&#x20; \<events>
&#x20;   \<missing>
&#x20;     \<createRole>
&#x20;       \<description>Created by import %=//System/Now%\</description>
&#x20;     \</createRole>
&#x20;   \</missing>
&#x20; \</events>
\</role>
:::

## Search Options

| Path    | Required | Example              | Description                                                |
| ------- | -------- | -------------------- | ---------------------------------------------------------- |
| root    | ✅        | =//Roles/Departments | Root role where searches begin.                            |
| key     | ✅        | DepartmentCode       | Field used to search roles (ID, Name, Path, or Parameter). |
| field   | ✅        | departmentCode       | Field from connector data used as lookup value.            |
| rootKey | Optional | 12345                | Value in connector data considered the hierarchy root.     |

## Role Creation Options

| Path          | Required | Example                            | Description                                              |
| ------------- | -------- | ---------------------------------- | -------------------------------------------------------- |
| name          | ✅        | =/department                       | Name for the role; used for creation and rename.         |
| parent        | ✅        | parentCode                         | Parent role — may be field, handler name, or expression. |
| description   | Optional | =/department                       | Role description.                                        |
| parameters/\* | Optional | \<param name="DepartmentCode" ...> | Parameter values to set on created/updated roles.        |

# Service Desk Ticket Link Handler

The **ServiceDeskTicketLinkHandler** matches connector rows to Activate service desk tickets.

**Example**

:::BlockQuote
\<ticket>
&#x20; \<match field="ticketNumber">=/ticketNumber\</match>
&#x20; \<match field="JobID">=/jobId\</match>
&#x20; \<match field="JobID" regex="\\\\\[Activate Job#(?'JobID'(\\\d\*))\\\\]">=/details\</match>
\</ticket>
:::

## Options

| Path  | Required | Example                                    | Description                                                       |
| ----- | -------- | ------------------------------------------ | ----------------------------------------------------------------- |
| field | ✅        | ticketNumber                               | Ticket field to check (ticketID, ticketNumber, JobID, or custom). |
| regex | Optional | \\\\\[Activate Job#(?'JobID'(\\\d\*))\\\\] | Regex for extracting IDs from text fields.                        |

# Parent Role Resolution

Role parents can be set via:

1. **Handler reference** — e.g., parent>region\</parent> to chain multiple levels.&#x20;
2. **Field reference** — e.g., parent>parentCode\</parent> for recursive structures.&#x20;
3. **Expression** — e.g., parent>=//Roles/Departments\</parent> to fix a known parent role.&#x20;