IDM

The iCC.Utils.Idm.exe utility is used for automated agent management. This utility is designed to unidirectionally synchronize information from Active Directory (AD) or another LDAP server to agent and permission tables. The identity key is the login name (Agent.SystemName).

The tool is usually run, for example, daily at night when there is the least traffic in the contact center. You can use operating system resources such as Windows Task Scheduler to schedule the start.

Depending on the configuration, the utility performs the following activities:

  • Create and delete agent accounts according depending on to which groups in AD they belong

  • Synchronize agent parameters (name, e-mail address, telephone number) according to user attributes

  • Synchronize agent parameters (supervisor, team, group) according to group affiliation

  • Synchronize rights (Role) according to group affiliation

  • Synchronize location (Seating - allowed workplaces) according to user attributes

  • Synchronize skills and knowledge according to group affiliation

Configuration file

Set the FrontStage database connection string, editing the iCC.Utils.Idm.exe.config config file, tag <connectionStrings>:

Parameter

Description

Atlantis.iCC.Model.Dbml.Properties.Settings.DbConnectionString

Connection to the FrontStage database (usually iCC)

In addition to the connection string, there are other generic parameters in the <applicationSettings> section:

Parameter

Description

LdapServer

URL for contacting the LDAP server

LdapAuthType

Authentication type (Basic, NTLM, Negotiate, Kerberos)

LdapUserDn

The user’s DN used for Basic authentication (an empty value means Do not use)

LdapPassword

User password

LdapRoot

Default level for queries (base) – It must contain a DN

LdapVersion

The LDAP protocol version, whereby Version 3 is preferred

Synchronization rules

../../_images/idm-rule-map-relation.png

IdmRule table

Column

Description

DisplayName

Name for administration.

Rank

The order in which the rules are executed.

Suspended

Option to temporarily suspend rule processing.

Command

CreateAgents, UpdateOrRemoveAgents, SyncSupervisors commands.

LdapFilter

LDAP query to obtain query members (https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx).

SubjectText

A text parameter of the rule; its interpretation depends on the command.

ReferenceText

A text parameter of the rule; its interpretation depends on the command.

ReferenceId

A GUID parameter of the rule; its interpretation depends on the command.

Reference

A numeric parameter of the rule; its interpretation depends on the command.

IdmMap table

(Its meaning depends on the command.)

Column

Description

FieldName

The field from which data is to be drawn (usually a field of the IdmAccount table).

FieldFormat

A format string used to obtain the field value from the attribute value that is supplied as the first format parameter {0}. If the LdapAttribute field is empty, it can serve as a constant. NULL means that the attribute value without formatting is used directly.

LdapAttribute

An attribute to be retrieved using LDAP for each query member.

Convertor

Attribute conversion method (String, Byte2Utf8, Byte2Cp1250, Byte2Cp1252, Byte2SID).

Synchronization algorithm

During synchronization, the rules are processed in blocks according to the command type, in the following order of commands:

  1. UpdateOrRemoveAgents

  2. CreateAgents

  3. SyncSupervisors

All rules of one command are evaluated and a list of members is created (table IdmAccount). Within the command, the rules toward LDAP are processed in the order specified for the rules.

Synchronization will use either the distinguishedName or objectSid attribute as the control key. This is set by the IdmUniqueKey configuration parameter, which can be SystemName or SID.

Algorithm for the SystemName control key

The distinguishedName attribute is loaded for each member and is used as a key in the IdmAccount table (unique occurrences only). Next, attributes are loaded according to the field of the IdmMap table. If LdapAttribute is filled in, it is added as the required query result and the field is mapped using the FieldFormat format string to FieldName. Mapping for SystemName is required. Mapping for DisplayName is recommended; otherwise, DistinguishedName is used as DisplayName.

If an existing agent is included in the IdmRedemption role, then the agent is not affected or is completely excluded from the IDM synchronization process, depending on the permission level:

Permissions

Description

AllowRead

It is not subject to deletion, i.e. it will not be deleted even if it is not found by the UpdateOrRemoveAgents command; it is subject to changes in rights and changes in attributes

AllowWrite

It is not subject to deletion or change of rights by the SyncSupervisors command; it is subject to attribute changes

AllowFull

It is not subject to any changes, i.e. neither deleting nor changing rights, nor changes to attributes in the Agent table with the UpdateOrRemoveAgents command (e.g. DisplayName, PersonalEmail,…)

The IdmRedemptionSystemNames configuration parameter specifies semicolon-separated system names that will never be created with the CreateAgents command. If the specified name begins with *, then no agent will be created whose system name contains the text after the asterisk (anywhere). The string comparison is not case-sensitive.

Example:

atl\novak;*worker;atl\vrana

Algorithm for SID control key

The objectSid attribute is loaded for each member and is used as a key in the IdmAccount table (unique occurrences only). Next, attributes are loaded according to the field of the IdmMap table. If LdapAttribute is filled in, it is added as the required query result and the field is mapped using the FieldFormat format string to FieldName. Mapping for SID is required. Mapping for DisplayName is recommended; otherwise, DistinguishedName is used as DisplayName.

If an existing agent is included in the IdmRedemption role, then the agent is not affected or is completely excluded from the IDM synchronization process, depending on the permission level:

Permissions

Description

AllowRead

It is not subject to deletion, i.e. it will not be deleted even if it is not found by the UpdateOrRemoveAgents command; it is subject to changes in rights and changes in attributes

AllowWrite

It is not subject to deletion or change of rights by the SyncSupervisors command; it is subject to attribute changes

AllowFull

It is not subject to any changes, i.e. neither deleting nor changing rights, nor changes to attributes in the Agent table with the UpdateOrRemoveAgents command (e.g. DisplayName, PersonalEmail,…)

The IdmRedemptionSIDs configuration parameter specifies semicolon-separated security IDs that will never be created by the CreateAgents command.

Description of synchronization commands

Create agent accounts [CreateAgents]

Members are evaluated according to the LDAP filter and non-existent records according to the given SystemName are created as new agents.

In addition, the following can be specified in the rule configuration:

  • ReferenceId – An ID of the template (AgentId) from which the agent is to be created by the copy method

  • Reference – A bit flag indicating what is to be copied from the template (values are added: 1 - Header, 2 - Skills, 4 - Proficiency, 8 - Seating)

If a member with the given SystemName does not exist, then such an agent is created. If a member with the given SystemName already exists and is deleted (Deleted=1), it is restored. If it exists and is active (Deleted=0), nothing happens.

Parameters:

  • SubjectText – Parameter {0} used to create an LDAP filter

Mapping examples

FieldName

FieldFormat

LdapAttribute

SystemName

ATLANTIS2000\{0}

sAMAccountName

SystemPin

pager

DisplayName

displayName

TeamName

department

GroupName

title

PersonalEmail

mail

ExternalPhone

mobile

SID

objectSid

WFM

Note

WFM mapping does not draw data from LDAP but ensures that there is a WfmAgent entry for the agent - the agent profile used for shift scheduling.

The AgentCreated record is created in the AgentEvent table with the following values:

  • Reference – either Insert for a brand new record, or Undelete for a restored existing record; the following number indicates attribute changes (sum of flags):

    • 1 – SystemPin

    • 2 – DisplayName

    • 4 – TeamName

    • 8 – GroupName

    • 16 – PersonalEmail

    • 32 – ExternalPhone

    • 64 – SystemName

    • 128 - SID

    • 256 - WFM (profile record created)

  • Actor – always Idm

  • ReferenceId – An ID of the rule (IdmRuleId) according to which the record was processed

  • ResultData – The first 64 characters of DistinguishedName

Update or delete accounts [UpdateOrRemoveAgents]

Members are evaluated according to the LDAP filter and existing records based on the given SystemName are updated according to the mapping (if necessary); excess agents, if any, are deleted.

Note

If no such rule is configured (even in the suspended status), the system skips this phase as all agents would be deleted (except for redemption), and it is most likely an invalid configuration.

If a member with the given SystemName does not exist, nothing happens; if it exists, it is updated. If an agent exists but there is no group member, the agent is marked as deleted (Deleted=1) and Activity = Logoff is logged out.

Parameters:

  • SubjectText can be used as a {0} parameter to create an LDAP filter.

The mapping works the same as with the CreateAgents command.

The AgentDeleted record is created in the AgentEvent table with the following values:

  • ReferenceData – A copy of the Agent.Activity field before the agent logs out

  • ReferenceId – A copy of the Agent.StatusId field before the agent logs out

  • Actor – always Idm

For updated records, there is the AgentUpdated record in the AgentEvent table with the following values:

  • ReferenceData – The number indicates attribute changes (sum of flags):

    • 1 – SystemPin

    • 2 – DisplayName

    • 4 – TeamName

    • 8 – GroupName

    • 16 – PersonalEmail

    • 32 – ExternalPhone

    • 64 – SystemName

    • 128 – SID

    • 256 - WFM (profile record created)

  • Actor – always Idm

  • ReferenceId – An ID of the rule (IdmRuleId) according to which the record was processed

  • ResultData – The first 64 characters of DistinguishedName

Supervisor synchronization [SyncSupervisors]

Members are evaluated according to the LDAP filter and existing records according to the given SystemName are set as a supervisor flag; other agents have this flag removed.

Note

If no such rule is configured (even in the Suspended status), the system skips this phase as all supervisors would be deleted (except for redemption), and it is most likely an invalid configuration.

Parameters:

  • SubjectText can be used as parameter {0}.

If a member with the SystemName does not exist, nothing happens; if it exists, it is set as Supervisor=1. If an agent exists but there are no members of the group, the agent is set as Supervisor=0.

For updated records, the AgentEvent table contains the SetSupervisor record with the following values:

  • ReferenceData – An indication of settings

    • true – The agent set as supervisor (in which case also ReferenceId and ResultData are filled in)

    • false – The agent is not set as supervisor

  • Actor – always Idm

  • ReferenceId – An ID of the rule (IdmRuleId) according to which the record was processed

  • ResultData – The first 64 characters of the distinguishedName or objectSid

Configuration example

../../_images/idm-example-rule.png

Example of the IdmRule table.

../../_images/idm-example-map.png

Example of the IdmMap table.

../../_images/idm-example-account.png

Example of the IdmAccount table (stable status).

The Reference parameter in the IdmRule table

The parameter in the Reference column in the IdmRule table (IDM Rules) can take the following values. The value from the first column, i.e. a decimal digit, is written to the rules table.

Basic configuration values

Value

Bit representation

Synchronization type

1

(0001)

CopyHeader

2

(0010)

CopySkills

4

(0100)

CopyProficiencies

8

(1000)

CopySeatings

Combined configuration values – example:

Value

Bit representation

Synchronization type

3

(0011)

CopyHeader, CopySkills

7

(0111)

CopyHeader, CopySkills, CopyProficiencies

15

(1111)

CopyHeader, CopySkills, CopyProficiencies, CopySeatings

9

(1001)

CopyHeader, CopySeatings

13

(1101)

CopyHeader, CopyProficiencies , CopySeatings