Contents
EX Engage Connector Configuration Sync Service (EXCS)
EXCS is a component responsible for the synchronizing resources with Genesys Cloud EX.
Configuration Object Mapping Table
Refer to the Resource Synchronization chapter of the Genesys Cloud EX Integration Guide for a list of the configuration objects, which should be created in the EX Org to enable event injection. Those configuration objects are listed in the EX Org Object column and the Engage Object column contains a configuration object of the Engage Contact Center, which is used to create a corresponding object in the EX Org.
| EX Org Object | Engage Object |
|---|---|
| User | Persons |
| Skill | Skill |
| Language | Engage Contact Center doesn't have Language as a configuration object. Languages are assigned to Persons as Skills. |
| Queue | Virtual Queue |
| Wrap-up Code | Business Attribute |
| Source | EXEC creates a new Source object in the EX Org. This data is not mapped. |
| Division | All EX Org Users mapped from Engage are assigned to Home Division |
| Secondary presence status definition | Not Supported |
The Configuration Object Synchronization follows these rules:
- If a new object is created in Engage, a corresponding object is created in the EX Org.
- If a mapped object is deleted in Engage, then the behavior of EXCS depends on the object type:
- Virtual Queues: The corresponding EX Org object will not be deleted, but all members in that object will be removed from the queue members list in near-real-time.
- Virtual Queue Members: The corresponding EX Org objects will be removed from the queue members list in near-real-time.
- Persons: The corresponding EX Org object will not be deleted, but will be moved into an inactive state. If the same Person object is later re-created in Engage, then the corresponding EX Org object will be moved back into active state (but a different externalId value was assigned because the re-created Person object will be assigned a different DBID value in Engage).
- Skills: The corresponding EX Org object will not be deleted.
- Wrap-up Codes: The corresponding EX Org object will not be deleted.
- If a mapped object is deleted in EX Org, then this object is not re-created in the EX Org. The objects, deleted in EX Org, may be re-mapped from the Engage configuration only after the clearing of the Redis cache and restarting of the Config-Sync service.
- If a mapped object is modified in Engage, then the changes are applied to the corresponding EX Org object.
- If the mapped parameters of a mapped object (for example, a new skill is added to an agent) are modified in the EX Org, then they are updated in the EX Org to match the Engage configuration.
- If a new parameter not controlled by Engage is added to the EX Org object, then it is not changed by the EXCS
Deletion of the ACD queues and queue members in the EX Org
If an Engage DN mapped to an ACD queue in the EX Org is deleted from the Engage configuration, then EXCS does not delete it from the EX Org.
If an Engage Person mapped to the EX Org as a member of one or multiple ACD queues is deleted from the Engage configuration, then EXCS deletes the corresponding queue member from all EX ACD queues. EXCS doesn't delete a corresponding User from the EX Org.
Case-Sensitivity of Object Names
In Engage, the names of Persons, DNs, Skills, and Business Attributes (BA) are case-sensitive. For example, it is possible for two distinct queues with the names queue1 and Queue1 to exist. In GC, the names of the Users, Queues, Skills, and Wrap-up Codes (which are derived from the corresponding Engage objects) are not case-sensitive. If a queue with the name queue1 exists, then the attempt to create a new queue with the name Queue1 would fail.
Customers must resolve these naming problems, if they exist, before running EXCS for the first time. This can be done by deleting the conflicting object and re-creating it with a non-conflicting name.
If these naming conflicts are not resolved prior to starting EXCS, or if they are introduced at a later point in time, the result will be that more than one Engage object will be mapped to a single GC object.
Selecting Engage Objects for Mapping to EX Org using Folder Filtering
Folder filtering is a process of selecting Engage configuration objects to be mapped to the EX Org. It allows Engage customers to enable only part of their contact center to use Genesys Cloud (GC) services. For example, customers can pilot GC services for one of their lines of business (LOB) and add more LOBs later.
Engage configuration folders are used to identify the configuration objects, which should be mapped to the EX Org. Folder filtering is applicable to the following configuration objects:
- Persons
- Skills
- DNs
- Agent Groups
For effective folder filtering, the folder to be synced should be selected for Persons, Skills, DNs, and Agent Groups Engage objects.
Folder filtering cannot be used for the Business Attributes.
To execute this approach two EXCS environment variables should be configured:
- SYNC_CUSTOMER_OBJECTS_ONLY = true
- SYNC_CUSTOMER_FOLDER_NAME = <FOLDER_NAME_1>, <FOLDER_NAME_2>...
The SYNC_CUSTOMER_FOLDER_NAME environment variable contains a comma-separated list of the CME folder names. EXCS searches those folders in all four configuration units listed above (Persons, Skills, DNs, and Agent Groups) and syncs configuration objects found in those folders to GC. If a listed folder has subfolders, then all subfolders are synchronized to the GC too.
Genesys recommends including existing CME folders into the list to avoid moving configuration objects around, which can cause an unnecessary load on Configuration Server. Also, existing CME folders usually represent current business infrastructure, and it can be convenient to use them to mark a certain LOB for syncing to GC.
If customers want to create a pilot agent group, which does not correspond to any existing CME folder, then a new folder with an unique name (for example, EX_EVOLUTION) should be created under the configuration unit of each mapped configuration object. For example, to select queues, the EX_EVOLUTION folder should be created under the DNs folder. The folder to be filtered can be present in any level of the configuration object and not necessary to be at Root level.
It is advised to use a maintenance window to move the Engage configuration objects to new folders in CME as it can create a substantial load on the Configuration Server (CS) and CS Proxies.
Synchronization of Wrap-up Codes
GC Wrap-up Codes are derived from the Engage Business Attributes (BA). EXCS selects the BAs to be mapped based on the following requirements:
- Type = Interaction Operational Attributes, and
- Either of:
- Name = DispositionCode, or
- Annex has the following set (case-sensitive): Annex / htcc / contains=dispositions
All values inside all BAs satisfying the above requirements are synchronized to GC. If multiple BAs have Values with the same name, only one Wrap-Up Code will be created for the name. For example, if both BAs, Tech Support Disposition Codes and Billing Disputes Disposition Codes have a value named 'Resolved', only one Wrap-Up Code called 'Resolved' is created in GC. All mapped Wrap-up codes are assigned to all ACD queues in the EX Org.
Folder Filtering cannot be used for BAs.
Synchronization of Skills
GC Skills are derived from the Engage Skills, which are selected for mapping based on the Folder Filtering rules.
Synchronization of Queues
GC ACD queues are derived from the Engage DNs, which are selected for mapping based on the Folder Filtering rules. The following types of Engage DNs are mapped to the GC queues:
- Virtual Queue
GC ACD queues are configured with members. Calls arriving to an ACD queue can be distributed to one of its members. In Engage an association between users and queues can also be configured but most often it is identified at run time. Additional configuration should be applied on the Engage side to explicitly link agents to queues. EXCS uses this configuration to create members of the GC ACD queues.
Customers should identify Engage Virtual Queues as important for the GC WFM scheduling and forecasting. For each selected Engage VQ, the customer must identify an existing or create a Virtual Agent Group (VAG) that will be used for Queue-User mapping. The following configuration should be applied to the Annex of these VAG objects to link them to their corresponding queues:
- Annex / hybrid / WFM_queue_number = <QUEUE_DN_NAME>
Changes made to the Engage VAG membership are synchronized to membership of the corresponding GC ACD queues.
Queues
If an Engage Person is a member of one or several VAGs, which are linked to a VQ using the hybrid/WFM_queue_number parameter, then a GC User derived from the Engage Person is added as a member to the corresponding ACD queue in GC. See more information in the Synchronization of Queues section above.
Mapping Queue Parameters
EXCS uses the rules below to populate parameters of the ACD queues created in the EX Org.
- Name: <ENGAGE_QUEUE_DN_NAME>__<ENGAGE_SWITCH_NAME>__Engage-external
- VQ DNs created under different Engage switches may have the same name. GC EX ACD queues must have unique names. To guarantee the queue name uniqueness EXCS adds the name of the switch as a suffix to the name of the ACD queue.
- Example: if an Engage VQ DN called VQ_Sales_Leads configured under the switch VQ-Switch is mapped to the EX Org, then the name of the corresponding ACD queue is set to VQ_Sales_Leads__VQ-Switch__Engage-external.
- Description: Engage Reference: <TENANT_NAME-SWITCH_NAME-DN>; Last modified: <hh:mm:ss MM/DD/YYYY>;
- Example: The following Description line is compiled for the DN VQ_Sales_Leads configured under the switch SIP_Switch in tenant tenant001:
- Engage Reference: tenant001-SIPSwitch-VQ_Sales_Leads; Last modified: 13:05:25 04/19/2023;
- Example: The following Description line is compiled for the DN VQ_Sales_Leads configured under the switch SIP_Switch in tenant tenant001:
- Because there is no TimeZone info available for the object last modification time in the Engage Config DB, the Last modified date/time in GC Queue Description field is represented in UTC format.
- If the corresponding Engage DN object was not yet modified (there are no related records in the Engage Config DB history table), then the Last modified info is not displayed in GC Queue Description field.
- If TENANT_NAME environment variable is not available, value of the environment variable TENANT_ID will be used. If both TENANT_NAME and TENANT_ID is not set, the default value default_tenant will be used.
- Peer Id: <DN_DBID>
This field contains a DBID of a DN in the Engage Config DB
Synchronization of Users
GC Users are derived from the Engage Persons, which are selected for mapping based on the Folder Filtering rules.
Person Details
| EX Org User Parameter | Engage Person Parameter | Comment |
|---|---|---|
| active: Indicates whether the user's administrative status is active. | State Enabled | |
| userName: The user's Genesys Cloud email address. Must be unique. | User Name | GC requires a userName to be a valid email address. EXCS is checking the Persons configuration fields in the following order to find a valid email address, which should be used as a GC User userName:
|
| displayName: The display name of the user. | First Last, or User Name | if both Person's first and last names aren't present, User Name is used |
| emails: Defines a SCIM email address. | ||
| externalId: The external ID of the user. Set by the provisioning client. | DBID__username |
Roles
When EXCS synchronizes an Engage Person to GC for the first time, EXCS determines whether the Person is a non-agent, an agent, or a supervisor:
- A non-agent is a Person who does not have the "Is Agent" flag checked. In a Engage environment, this could be anything including from administrative user to business analyst.
- An agent is a Person who has the "Is Agent" flag checked.
- A supervisor is a Person who has the "Is Agent" flag checked, and has "Supervisor" as one of the HTCC roles in the annex (i.e., "htcc/roles" has "Supervisor" as one of the roles).
The following roles are assigned to a new GC User created by the EXCS:
- Non-agent Roles: Employee
- Agent Roles: Employee, User
- Supervisor Roles: Employee, User, Supervisor
Default roles can be changed using the following configuration parameters under the "hybrid_integration" transaction:
- Non-agents: nonagent_role_names
- Agents: agent_role_names
- Supervisors: supervisor_role_names
If some of the specified GC Role(s) do not exist, the User will still be created, and all the existing Roles will be assigned.
After the initial creation of the GC User, EXCS does not change any of the assigned GC Role(s) of the User, with the following exceptions:
- If EXCS has detected a Person has transitioned from agent to supervisor, all the GC Roles in supervisor_role_names are added to the User. (None of the existing GC Roles are removed from the User.)
- If EXCS has detected a Person has transitioned from supervisor to agent, all GC Roles in agent_role_names are added to the User. (None of the existing GC Roles are removed from the User.)
Queues
If an Engage Person is a member of one or several AGs/VAGs, which are linked to an ACD Queue or a VQ using hybrid/WFM_queue_number parameter, then a GC User derived from the Engage Person is added as a member to corresponding ACD queue in GC. See more information in the 'Synchronization of Queues' section above.
ACD skills
If an Engage Person has one or several skills, and those skills are configured to be mapped to GC, then a GC User derived from this Engage Person has corresponding ACD Skills assigned in GC. See more information in the 'Synchronization of Queues' section above.
Engage Person's skill level range is not limited. Proficiency level range of a GC User is from 0 to 5. EXCS translates the Engage skill level to the GC Proficiency level using the following rules:
- For a given skill find MIN and MAX values across all configured persons.
- If MIN or MAX value of a skill level is outside of the range [skill_level_min_value, skill_level_max_value], replace it with the corresponding range boundary value.
- Proficiency Level = 5 * Skill Level / (MAX-MIN) - the result is rounded to one decimal place.
Languages
EXCS doesn't configure a Language for an EX User. If a Language is required for an EX User to enable some EX functionality such as WFM grouping, then it can be configured for the Users mapped from Engage using GC UI. EXCS ignores User's properties, which are not included in its synchronization scope. Hence, EXCS won't change or remove the User's Language.
Extension DNs
EXCS doesn't map the Extension DNs to the Genesys Cloud but it reads those DNs and stores them in Redis. This data is required by the EX Conversation Provider (EXCP) to interpret the Engage events properly while injecting them into the GC. There can be a large number of Extension DNs configured in Engage contact centers. It is recommended to minimize the number of Extension DNs read by the EXCS. For example, if only a subset of contact center agents are selected for the EX integration, then Folder Filtering can be used to filter only those Extension DNs, which are used by agents selected for the EX integration.