Inside Activate
Connectors
Link Handlers
9 min
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 \<link name="user account"> \<scope>=//roles/system roles/users\</scope> \<match when="employeenumber">(employeenumber=%=//current/employeenumber%)\</match> \<match when="domainname">(samaccountname=%=//current/domainname%)\</match> \<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 \<role> \<root>=//roles/departments\</root> \<key>departmentcode\</key> \<field>departmentcode\</field> \<name>=//current/department\</name> \<parent>parentcode\</parent> \<parameters> \<departmentcode name="departmentcode" type="string">=/departmentcode\</departmentcode> \</parameters> \<events> \<missing> \<createrole> \<description>created by import %=//system/now%\</description> \</createrole> \</missing> \</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 \<ticket> \<match field="ticketnumber">=/ticketnumber\</match> \<match field="jobid">=/jobid\</match> \<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 handler reference — e g , parent>region\</parent> to chain multiple levels field reference — e g , parent>parentcode\</parent> for recursive structures expression — e g , parent>=//roles/departments\</parent> to fix a known parent role