Verba Integrator (formerly VFC to WFE Metadata Integrator)
AVAILABLE IN 9.7.7 AND ABOVE
- 1 Migration from the legacy application
- 2 Supported switch platforms
- 3 Minimum software version
- 4 Concepts and functionality
- 5 Deployment process
- 5.1 Create a parent organization in Workforce Engagement
- 5.2 Create a parent group in Workforce Engagement
- 5.3 Create API key in Workforce Engagement for each WFE Tenant
- 5.4 Configure file upload from Recorder Servers
- 5.5 Enable External Recorder data sources in Workforce Engagement
- 5.6 (optional) Enable AQS in Workforce Engagement
- 5.7 Enable the Integrator service
- 5.8 Configure the Integrator
- 5.9 Start the Integrator service
- 6 Troubleshooting
- 7 Post-deployment tasks
- 8 Resilience
- 9 Limitations
The purpose of the Verba Integrator (formerly VFC to WFE Metadata Integrator) tool is to import call metadata, supported by switch platform and user data, from the VFC platform to the Verint V15.2 Workforce Engagement (WFE) suite. Once imported, the data is available for use by certain applications within the WFE suite. The Integrator continuously verifies the data in both VFC and WFE and carries out a one-way synchronization periodically.
This integration offers the synchronization of the following information from VFC to WFE:
Call record metadata.
Call record audio quality scores, and if speech transcription and screen recording was carried out for the recordings.
Switch platforms, and extensions.
Groups and users.
The data synchronized to Workforce Engagement is then available for use in certain WFE applications:
You can configure Capture Verification Collectors to collect Call Detail Records (CDRs) from the switch platforms and verify your call recording, audio quality, audio transcription, archiving, screen recording, and sensitive data masking compliance with Automated Verification.
You can create Automated Verification reports to summarize your recording compliance results.
Design your integration based on your VFC and WFE deployments using this document before enabling and configuring the Integrator.
Migration from the legacy application
To use the Integrator with VFC versions 10.0.8 and newer, you must upgrade from the standalone VFC to WFE Metadata Integrator tool, and complete the migration to the Verba Integrator service.
The Verba Integrator service is no longer a standalone tool, and it does not need manual installation. The migration to the new service:
Moves your Integrator settings into the centralized VFC configuration system, storing settings in the database and registry.
Replaces the legacy VFC to WFE Metadata Integrator with the new Verba Integrator service, allowing you to manage it from the VFC web application.
The legacy tool is now deprecated. Follow Migrating from standalone VFC to WFE Metadata Integrator to the Verba Integrator service to complete the migration.
Supported switch platforms
The Integrator supports the synchronization of recording data for the following switch platforms:
Avaya DMCC/MR
Cisco Network Based
IPC Unigy
IP Trade
Genesys Cloud
Genesys T-Server
Zoom Meeting
Zoom Phone
Minimum software version
Workforce Engagement V15.2
VFC Capture 10.0.8 or higher
For older VFC versions using the legacy VFC to WFE Metadata Integrator tool, you must complete the migration to the Verba Integrator service before you upgrade to VFC 10.0.8. The legacy tool is now deprecated. Follow Migrating from standalone VFC to WFE Metadata Integrator to the Verba Integrator service to complete the migration.
Concepts and functionality
Architecture
The Integrator communicates with WFE services and sends VFC data to the WFE database using API calls.
The Integrator supports the following deployments:
System | On premise | Single-tenant Cloud | Multi-tenant Cloud |
|---|---|---|---|
VFC | Yes | Yes | Yes * |
WFE | Yes | Yes | Yes |
* Multi-tenant cloud VFC deployments are supported if each tenant has its own Integrator configured.
One Integrator service runs per VFC environment. If multiple VFC environments use the same VFC database, the Integrator of each environment can connect to that database at the same time. See Resilience for more information.
An Integrator synchronizes VFC data to a single WFE tenant. The connection to the WFE installation is specified by configuring the URL of the WFE Application Server on which the WFO_ProductionDomain_ProductionServer runs. Multiple Integrators can synchronize data to a single WFE tenant, but there are parameters in the Integrator configuration that must be unique to each connected Integrator. Refer to the Configuration Guide for more details. The tenant to which an Integrator connects is specified by creating an API token for the tenant in WFE and adding that token to the Integrator configuration.
User groups
The Integrator synchronizes all user data from the VFC database to WFE. The synchronization of all VFC users is supported, including users created by an Active Directory synchronization.
Synchronized VFC users do not have roles and privileges in WFE.
While organizations do not exist in VFC, WFE relies on organizations for enforcing user access scoping and for logically associating users and data sources. As the first step of the deployment process, the Integrator requires the creation of a parent organization in WFE. This organization can be on any level of an existing WFE organizational hierarchy. The name of the parent organization must be added to the Integrator configuration. The user groups and data sources managed by the integration are associated with the organization upon creation.
The parent organization must not be the Root organization that is created during the WFE deployment process.
You must also manually create a parent WFE group that holds all groups of VFC synchronized employees, and the name must be added to the Integrator configuration.
The parent group must not have employees assigned to it at any point in time and it must not be the Root group that is created during the WFE installation process.
Under the parent group, a default group holds all individual VFC synchronized employees, regardless of what VFC groups those employees belong to. On the same hierarchical level, under the parent group, the WFE groups matching the VFC groups get automatically created by the integrator.
The default group synchronization method creates an identical group hierarchy in WFE as the groups exist in VFC. These groups retain their names configured in VFC, but the Integrator removes special characters, and if a group name at any hierarchy level is longer than 50 characters, the Integrator does not process the group and logs an error.
If a group name is longer than 50 characters or the group needs to be synchronized to WFE with a different name, the Integrator can be configured to read a mapping of the original VFC group names and the corresponding shortened or amended group names, as intended to be listed in WFE.
The contents of the field must be entered in the following format:
Enter the VFC and WFE group name equivalents as a comma-separated key-value pair. The first value must bethe group name exactly as specified in VFC. The second value must bethe amended group name as it should be synchronized to WFE.
Every unique group must be in a separate row.
You can list groups from any level of the group hierarchy. Duplicate group names are ignored. Any groups not listed in the group mapping field are synchronized to WFE using the default synchronization process.
Example:
The top level parent group, and some sub-groups on the third level of the hierarchy have new names configured. Column A contains the original names in VFC, and column B lists the names intended to be used in WFE.
All VFC groups are synchronized to WFE, not just the groups listed in the configuration field. The group hierarchy remains, and the groups with new names configured in the field are synchronized with their new names.
As all groups in WFE must have a unique name, VFC groups with the same name under different parents cannot be synchronized without a change to the name. To avoid skipping groups with identical names, you can choose a level in the group hierarchy to act as a suffix to all of sub-groups by setting the Unique Identifier parameter in the Integrator configuration. The name of the groups on the specified level in the hierarchy get concatenated to the names of all their sub-groups with a dash.
Example:
Sales and Support exist as sub-groups in both the AMER and EMEA groups in VFC. The AMER and EMEA region group names are set as the suffix by setting the Unique Identifier to 1, making the group names unique.
The suffix counts towards the 50 character group name limit. Choose the hierarchy level for the Unique Identifier value after confirming that the resulting sub-group names will not look identical after the suffix is added.
You can limit how many levels in the VFC group hierarchy become separate groups and sub-groups in WFE by setting the Hierarchy Level Depth parameter in the Integrator configuration. Sub-groups under the specified hierarchy depth are not created as groups in WFE, and their users get assigned to the parent group on the level specified by the Hierarchy Level Depth parameter instead. If the parameter is not specified or set to the default value, all VFC groups are synchronized to WFO as unique groups.
Example:
Four levels of VFC groups get synchronized to three levels of WFE groups by setting the Hierarchy Level Depth parameter to 3. The Unique Identifier is not set.
After the Integrator completes the synchronization process, the country groups contain all users for their child city groups. and the VFC Synced Users group contains all users.
Changes to users or groups that happen in VFC are applied to their WFE equivalent the next time the synchronization process runs. Changes to users or groups that happen in WFE do not apply to their VFC equivalents. If conflicting information exists in VFC and WFE, the changes in WFE are overridden the next time the synchronization process runs. However, if a non-VFC user is manually added to any of the WFE groups representing a synchronized VFC group, the user is not removed the next time the synchronization process runs.
Do not add WFE users manually to the default VFC group that holds all synchronized users.
(optional) User roles and permissions
The Integrator can be configured to synchronize user Login IDs, group scopes, and roles.
The Synchronize User Logins parameter in the Integrator configuration determines which users have their VFC Login IDs synchronized to be the usernames for the newly created WFE users. You can choose to synchronize the Login ID of all users, no users, or group supervisors and investigators only.
The Login IDs of VFC users with the No Access to Conversations user scope are not synchronized.
In multi-tenanted VFC and WFE environments, where multiple Integrators are synchronizing user data to different tenants in the same WFE deployment, configure a unique username postfix in each Integrator, to ensure usernames in WFE are kept unique across tenants.
Special characters are allowed in VFC Login IDs, but are not allowed in WFE usernames, so the synchronization process removes special characters and notes any changes in the logs. WFE usernames have a maximum length of 50 characters, so any Login IDs longer than that get truncated. Configured postfixes count towards the 50 characters and are kept even if the Login ID is truncated.
Passwords are not synchronized. When the Login IDs are synchronized to WFE or a Login ID is synchronized again after it changes in VFC, the system forces a password reset when the user first logs in. If Login IDs are not synchronized, VFC synchronized users are set to the Locked by Admin status. The synchronized Login IDs of terminated employees in VFC, they are also set to the Locked by Admin status in WFE.
Synchronized Login IDs in WFE cannot be deleted using the Integrator, and have to be deleted manually.
The Integrator can also be configured to synchronize the group scopes and certain roles of users whose Login ID is synchronized. The WFE users are assigned to groups based on the user group configuration, and if the SynchronizeAccessRights parameter in the Integrator configuration is set to true, the groups are set as user scopes. Member and supervisor roles that the users have in the VFC groups are assigned as the roles of the WFE users. The Integrator configuration has to specify which WFE role is the equivalent of a group member and a group supervisor or investigator. If the configuration is not edited, group members are assigned the role of Agent, and group supervisors and investigators are assigned the role of Supervisor. You can configure different WFE role names, but the roles must exist in WFE before the Integrator is configured and enabled.
There is no difference between VFC group supervisors and investigators in WFE. Other group roles, such as Administrator and Manager, are not synchronized.
VFC role assignments allow the specification of a Valid From date, which prevents users from viewing or replaying conversations before they had the access right. This option is not available in WFE, and the synchronized users in WFE do not have this restriction.
Switches and data sources
To synchronize the required recording metadata, the VFC switch data sources for which the Integrator is configured must be specified in the Integrator settings.
The Integrator supports the synchronization of metadata from:
recorded switch platforms, and
import sources, where VFC does not record the calls, but it ingests the recordings from the switch platform through the configured import source.
The integration process does not run until one or more VFC data sources are added to the list of configured data sources in the settings.
Data sources in WFE do not have to be created manually, the Integrator automatically creates them to represent the switches configured in VFC. You must configure the Integrator to create the right WFE data sources for your deployment and monitoring needs by supplying switch configuration details in Integrator settings.
You must specify:
the VFC Recording Server addresses,
the VFC data source type, describing the platform ID or import source type of the switch,
the time zone of the switch,
and the data source name to be used in WFE.
The granular configuration options in the Integrator allow for the accurate mapping of extensions to data sources in WFE.
You must add the addresses of all VFC Recording Servers that recorded calls to the data source configuration. Those Recording Servers that are not added do not have their calls synchronized to WFE.
A data source object in the Integrator settings can only be of one platform name or import source type, and it must be in a single time zone. However, it can represent one or more recorded platforms or import sources of the same type, in the same time zone, being recorded by one or more VFC recorders. A data source object cannot represent multiple data sources of different recorded platform types or import source types. If the extensions are configured for the data source object representing a recorded platform, the specified extension numbers are associated to the WFE data source upon creation.
To synchronize all import sources of the same type to a single WFE data source, do not specify import source IDs for the data source objects in the Integrator settings. To synchronize multiple import sources of the same type to separate WFE data sources, create multiple data source objects in the Integrator settings, and list the import source IDs in the separate data source objects.
Specifying the same import source ID for different data source objects causes an error. This also means that you should not create a data source object with an empty import source ID configuration if you have a separate data source object of the same import source type configured with a specific import source ID.
The extension parameter can be omitted or left empty for a data source object, which results in all extensions recorded by the specified recorders on the specified platform type to be associated with that WFE data source. The extensions can be configured as an array of individual alphanumeric values or number ranges, but do not support wildcard operators
Do not add extension configuration for import source type VFC data sources.
If multiple identical data source objects exist in the Integrator settings without extension values specified, extensions for that platform name are associated with each WFE data source
If multiple data source objects exist in the Integrator settings without extensions specified but different platform names are set for them, extensions configured to record all VFC data sources are associated to each WFE data source.
If multiple identical data source objects exist in the Integrator settings and some of them have extensions specified, the described extensions are associated with the corresponding data source created in WFE. The other, unspecified extensions are associated with the first data source that has no extensions added
At a minimum, you must have one data source object without extensions per platform name. If you have data source objects with extensions specified, it is still recommended to have a data source without extensions specified to ensure that no missed extensions get excluded from the synchronization.
If a platform ID or import source type has been added to the Configured VFC Data Sources parameter, but no data source objects exist in the Data Mapping section, then no corresponding WFE data source is created, and no related recording data is synchronized to WFE.
The Integrator configures both the local and UTC time zone of a switch platform to the corresponding WFE data source. The Integrator configuration requires the time zone configured in the IANA time zone format <area>/<location>, but in the WFE user interface the time zone shows in both IANA and UTC/GMT-offset formats, depending on the application. For example, a switch at a site in Los Angeles is seen as America/Los_Angeles in Reports, but shows as GMT-08:00 Pacific Time (US & Canada) on the data source settings page under Recording Management.
Only a subset of IANA time zones are supported in WFE. You must configure a supported time zone value for the Integrator.
Refer to Data Mapping in the VFC to WFE Metadata Integrator Configuration Guide to select a supported time zone that represents your required time zone the closest.
For each configured data source in the settings, the Integrator searches WFE for an existing data source that meets the following criteria:
It has the same name as the data source name configured in the Data Mapping section of the Integrator settings.
The Type matches the data source type associated with the platform name or import source type specified in the Configured VFC Data Sources parameter of the Integrator settings.
The Switch/sub-type is External Recorder.
The Organization associated with the WFE data source matches the organization ID of the parent organization created as part of the Integrator deployment process.
If the Integrator finds an existing WFE data source with matching details, it notes the switch_ID of the WFE data source. If the Integrator does not find an existing data source with matching details, it creates one.
All WFE data sources created as part of the integration have the switch/sub-type External Recorder.
The Seating Arrangement property of the created WFE data source is set to:
Hybrid for phone types,
Free for trader and application types.
The Contact Policy Type of all created WFE data sources is set to Back office - Contact per call.
The Recorded Platform property of the created WFE data source is set to the value of the data source platform specified in the Integrator configuration.
Do not change the Recorded Platform or Contact Policy Type of the data source in WFE.
Recorders and call metadata
The Integrator synchronizes recording metadata to WFE by periodically checking the VFC database for new recording data and marking them for synchronization. Call marking is the process of reading in a call record from the database, evaluating it against the Integrator configuration, and sending it to the WFE database.
The Integrator only synchronizes recording metadata, not media files.
Each VFC installation is represented as a single recorder in WFE, and all synchronized call records get associated with this recorder, regardless of the number of distinct VFC recorders that captured the calls. The Integrator creates an external recorder server in WFE for each VFC installation. The Server Name of the external server must be specified in the Integrator settings. It is recommended the Server Name matches the host name of the Media Repository the Integrator connects to.
The way calls are recorded and stored is different in VFC and WFE. Refer to Data models for more details on the VFC call data models, and see Contacts and Interactions for information about the WFE call data models.
Due to the difference in the call record handling, the call search and replay functionality also differs in VFC and WFE. To keep the call search experience consistent across both systems for VFC users, the Integrator retains the VFC call model in WFE.
In WFE, every record in the search results under Interactions represents a single session from the WFE call model. In VFC, every record in the search results under Conversations represents a single conversation entry from the VFC call model.
If more than one record was created during a conversation, related records can be shown together by selecting the ellipsis (…) button on the record and selecting Show Related.
During the synchronization process, each VFC conversation is mapped to a WFE session, allowing for the WFE call search experience being the same as in VFC.
To maintain the Show Related functionality, sessions are related to contacts and associated records can be viewed when selecting a call record from the search results.
The call records originating from WFE remain unchanged and a single record in the Interaction search results still represents a single session.
If the time interval between the start time of the first segment of a call and the start time of the last segment is longer than 12 hours, the created sessions in WFE are not associated with the same contact.
(optional) Synchronize Communications Analytics (formerly Intelligent Voice) risk metadata using the Integrator
Communications Analytics (formerly Intelligent Voice) risk metadata can be synchronized to WFE using the Integrator. It requires the configuration of custom data synchronization.
Communications Analytics transcripts are not synchronized.
To associate custom data with calls in WFE, a user with the Assignment Manager role is required that has the access rights to send requests to the API and associate the custom data with the call. The User Context Request Username and Custom Data Association Role fields in the configuration define these values. For the Integrator to synchronize custom data, both values have to be filled in, and both the user and the role have to exist and be valid in WFE.
Not all custom data fields in VFC are synchronized to WFE.
On the first run, the Integrator creates the CustomDataMap.json data definition file in the same folder as the Integrator bin files. The data definition file contains the list of custom data fields that are synchronized to WFE as custom data fields. The file lists the display name of the data that describes the value, and a numerical value that defines which custom data field the data is synchronized to in WFE. The file is automatically updated if new custom data fields are available to be synchronized.
Do not edit the CustomDataMap.json data definition file. Any edits to the file are overwritten the next time the synchronization process runs.
Example:
The CustomDataMap.json file lists the following custom data description:
“Name”: “IntelligentVoiceRiskDetected”,
“Id”: “85”
This means that the Intelligent Voice Risk Detected data associated with the synchronized calls can be found in the Custom Data 85 field when replaying the call in the Interactions module in WFE.
Once the custom data settings are configured, the Communications Analytics Enabled field in the Integrator configuration can be set to true. This setting forces the Integrator to wait with synchronizing calls to WFE until the Communications Analytics transcription process is complete.
Communications Analytics transcripts are not synchronized.
In the custom data fields, the Integrator synchronizes two Communications Analytics risk scoring metadata values: IntelligentVoiceRiskDetected, and IntelligentVoiceRiskScore.
After the Integrator is enabled and synchronization is complete, you can view and replay calls in the Quality Management (QM) Interactions module in WFE, and view the custom data, including Communications Analytics risk metadata in the Player.
Deployment process
The Integrator deployment process requires configuration in the VFC and WFE environments before the installation of the Integrator. The configuration of the synchronization details is done in the VFC web application, under System>Servers>Change Configuration Settings>Verba Integrator, after the service is enabled.
Create a parent organization in Workforce Engagement
In an on-premise or single-tenant WFE environment, sign in as Administrator. In a multi-tenant environment, sign in as Tenant Administrator.
Follow the Create an organization topic in the WFE User Management Guide to set up an empty organization for the synchronized VFC data.
Note the name of the organization created. You must enter the exact name in the settings of each Integrator during the configuration process.
Do not change the organization name once it has been configured for an Integrator.
Create a parent group in Workforce Engagement
In an on-premise or single-tenant WFE environment, sign in as Administrator. In a multi-tenant environment, sign in as Tenant Administrator.
Follow the Create a group topic in the WFE User Management Guide to set up an empty group for the synchronized VFC data.
No users must be assigned to the created parent group, or the synchronization process fails.
Note the name of the group created. You must enter the exact name in the settings of each Integrator during the configuration process.
Do not change the group name once it has been configured for an Integrator.
Create API key in Workforce Engagement for each WFE Tenant
In an on-premise or single-tenant WFE environment, sign in as Administrator. In a multi-tenant environment, sign in as Tenant Administrator.
Follow the Generate an API Key topic in the WFE Enterprise Configuration and Administration Guide to create an API key for each Integrator.
Set Key type to External.
When each API key is generated, note their Key ID and Key Value. You must enter the exact values in the configuration of each Integrator that synchronizes data to this tenant during the configuration process.
Configure file upload from Recorder Servers
The Integrator does not process recordings that are stored on the Recorder Servers, so the upload of media and metadata files to a central storage location must be configured.
Sign in to VFC as an Administrator user.
Follow Configuring media file upload to configure policy-based or non-policy based file upload.
Enable External Recorder data sources in Workforce Engagement
To enable External Recorder data sources that represent the VFC switch platforms, turn on the Data Marking API for External Recorder license item in WFE.
In a multi-tenant WFE environment, the service provider must carry out these steps. The tenant administrator cannot enable licenses or configure data sources.
In a browser, go to http://<wfo_app_server_address>/wfo/control/license_edit.
On the License Data page, under Features, enable 2021R1 - Data Marking API for External Recorder.
Click Save.
(optional) Enable AQS in Workforce Engagement
If you have Voice Quality scoring enabled in VFC and would like the voice quality data synchronized, the WFE Audio Quality Statistics license item must be enabled.
In a multi-tenant WFE environment, the service provider must carry out these steps. The tenant administrator cannot enable licenses or configure data sources.
In a browser, go to http://<wfo_app_server_address>/wfo/control/license_edit.
On the License Data page, under Features, enable 2021R1 - Audio Quality Statistics.
Click Save.
Enable the Integrator service
Sign in to VFC as an Administrator user.
Under System, go to Servers .
Select your server from the list, then click on the Service Activation tab.
Activate the Verba Integrator Service by clicking on the cog button.
Set the service to Manual Startup.
Configure the Integrator
Follow the Configuration Guide to configure the Integrator.
Start the Integrator service
In the VFC web application, under System, go to Servers, and select a server.
Under Service Control, start the Verba Integrator service.
Review the logs to confirm successful initialization and operation.
Under Service Activation, set the Verba Integrator service to Automatic Startup.
Troubleshooting
Follow the Troubleshooting Guide to troubleshoot issues with the Integrator.
Post-deployment tasks
Once the integration is configured and active, the following items must be completed and checked:
Verify that the parent organization with the name specified during configuration exists in WFE.
Verify that the parent group with the name specified during configuration exists in WFE.
Verify that the VFC Synced group exists as a child of the parent group in WFE.
Verify that the VFC user groups exist in WFE.
Verify that VFC users are available in WFE, are associated with the same groups as in VFC, and have the right extensions associated to them.
Verify that the data sources specified in the Integrator configuration exist in WFE, and have the right name, time zone, recorded platform, contact policy type, and extensions associated with them.
Verify that recordings are visible in the Automated Verification component of WFE.
Verify that recordings are associated with the right users, extensions, and data sources.
Verify that recordings are associated to the Serial Number of the external server that is specified in the Integrator.
Verify that an external recorder server exists in WFE with the Server Name specified in the Integrator configuration.
Resilience
When an Integrator completes its initial dependency checks, it makes an internal note of all dependency statuses. If all dependencies are ready, the Integrator attempts to connect to the database to read data by sending the database a lock request. If no database locks are in place, the database grants the lock to the Integrator that requested it. The active Integrator keeps sending a heartbeat signal to the database to maintain ownership of the lock. While the ownership is allocated, the database declines any further lock requests from other Integrators.
Any Integrators that completed their dependency checks but were not granted the database lock remain in a passive state. In the passive state, Integrators periodically retries gaining ownership of the database lock. The period for reattempting to acquire the lock is 30% of the lock timeout value and is not modifiable. Before resubmitting the lock request, the passive Integrator checks its internal record of dependency statuses, and if all statuses are logged as ready, the Integrator sends the lock request. If any dependencies are not ready, the Integrator carries out another dependency check, and updates its record of statuses.
If the active Integrator fails and no heartbeat signal reaches the database, the lock timeout period starts. After the timeout period elapses, the lock is released, and the next Integrator to submit a lock request is granted database access. The lock timeout period is configurable in Integrator settings.
Limitations
The only WFE module with full functionality access through this integration is Automated Verification.
If the time interval between the start time of the first segment of a call and the start time of the last segment is longer than 12 hours, the created sessions in WFE are not associated with the same contact.
Passive Integrators that do not have ownership of the database lock use their internal record of the dependency statuses noted during the last dependency check to determine if all services are ready, and only run new dependency checks if any dependencies were previously not ready. This means that if a dependency was ready at the last dependency check but fails before the new lock request is sent to the database, the Integrator starts up and fails when it encounters the unavailable dependency, releasing the database lock and restarting the database lock timeout period. This can cause long wait times for Integrators competing for the database lock, as multiple Integrators failing can make the database connection unavailable for multiple consequent lock timeout periods.