Genesys Cloud CX is a suite of cloud-based services for enterprise communications, collaboration, and customer experience management.
The current Genesys Cloud Integration uses the Genesys Cloud API to provide near real-time ingestion of audio files created by the Genesys system.
Please note: Genesys Cloud CX integration with SBC recording and Genesys Cloud CX integration with AudioHook recording are not currently supported.
For a general description of Verba Import sources, please refer to Import sources.
Migration Support
The following modalities are supported: Voice only.
1. Creating a Genesys Import Source
1.1. Pre-requisites
1.1.1. Customer firewall team enables access to:
- *.*.*.amazonaws.com on port 443.
- HTTPS Genesys Cloud API Authentication URL and port 443 from the VFC server or via the Proxy if required.
- HTTPS Genesys Cloud API URL URL and port 443 from the VFC server or via the Proxy if required.
1.1.2. Customer provides TLS Certificate, otherwise standard VFC API certificate will be used.
1.2. Create a Genesys OAuth Integration
Follow these steps in Genesys Cloud before creating a new VFC Import Source:
Step 1 - Open the Genesys Cloud Admin Page, navigate to Integrations > OAuth and press the Add Client button:
Step 2 - Select Grant Type Client Credentials. The Token Duration can be adjusted as required because it is renewed automatically by the VFC integration. Then click Save. The Client ID and Client Secret are automatically generated.
Step 3 - From the Genesys Cloud Admin Page, navigate to Admin > Roles/Permissions and create a role for the OAuth integration to run under.
Each recording file is considered an object that is subject to access control at the user level. When a recording file is generated, the access control for the recording file is set based on the following criteria:
- Access control is set based on the agent that was recorded. Agents are organized as an agent hierarchy; for example, the hierarchy can be a reporting structure in an organization.
- Access control is set based on partitions. Partitions are set as a specific attached data in a call, and the attached data is typically set by a routing strategy.
For more details, see https://docs.genesys.com/Documentation/CR/latest/Solution/AccessControl
1.3. Create a VFC Import Source
Next, follow the steps in Verba to create a new Import source:
Step 1 - Open the Verba Web interface then select Data > Import Sources from the top menu
Step 2 - Click on the Add New Import Source link on the top right
Step 3 - Complete the configuration according to the requirements in the following table
Configuration Item | Description |
|---|---|
| Name | Name your Import Source. This name will identify the source across the system. |
| Type | Select Genesys Cloud Import Source. |
| Client Id | Mandatory value copied from the Genesys Cloud OAuth Integration. |
| Client Secret | Mandatory value copied from the Genesys Cloud OAuth Integration. |
| HTTPS Genesys Cloud API Authentication URL | Mandatory Genesys URL used when the Import Source obtains the Access Token, for example: https://login.usw2.pure.cloud. Full list available at: https://developer.genesys.cloud/platform/api/ under Auth Server Customer firewall team must enable access to this URL and port 443 from the VFC server or via the Proxy if required. |
| HTTPS Genesys Cloud API URL | Mandatory Genesys URL used when the Import Source interacts with the Genesys API, for example to obtain user information. For example: https://api.usw2.pure.cloud Full list available at: https://developer.genesys.cloud/platform/api/ under API Server Customer firewall team must enable access to this URL and port 443 from the VFC server or via the Proxy if required. |
| TLS Certificate File / Thumbprint | Optional certificate file / certificate thumbprint used for the Genesys Cloud connection. If not configured, the server certificate will be used. For more information see Server Certificates |
| TLS Key File | Optional file system location where the certificate key is stored. |
| TLS Key Password | Specify the password for the file that contains the certificate keys. |
| TLS Trust List | Certificate chain (or Chain of Trust) is made up of a list of certificates that start from a server's certificate and terminate with the root certificate. If your server's certificate is to be trusted, its signature has to be traceable back to its root CA. |
| Forward Proxy Address | Optional. IP address or FQDN of the forward proxy. When defined, the system will connect through a forward proxy. |
| Forward Proxy Port | Optional. The port of the forward proxy. |
| Forward Proxy Username | Optional. Username for basic authentication for the forward proxy server. |
| Forward Proxy Password | Optional. Password for basic authentication for the forward proxy server. |
| Transcoding by Genesys | Mandatory codec selection. Genesys transcodes to the specified codec before delivering audio to the Import Source. |
| Recording Timezone | Mandatory Import Source timezone as all Genesys times are in UTC. This ensures recordings are presented with the correct time. |
| Recording Start Timestamp | Mandatory. Timestamp of the earliest Genesys content to be ingested. This can be a timestamp in the past, e.g., 2020, if historic Genesys content is required to be ingested. The Import Source will gradually catchup with real-time as it is run by successive Data Management Policies, but will take longer to catch up depending on the number of historic recordings, the Maximum Recording Length and Availability Delay. In the case of mass historical ingest, it is recommended to set the Maximum Recording Length to a large number, e.g., 999 and reduce the Availability Delay to a small number, e.g., 10 minutes. Once the ingestion has caught up, adjust each of these parameters to their correct operational values. |
| Genesys Cloud Maximum Recording Length (minutes) | Mandatory. Maximum length of Genesys content to be ingested. Content exceeding the maximum length may not be ingested or an alert generated. |
| Genesys Cloud Availability Delay (minutes) | Mandatory. Maximum time the import source waits for Genesys content to become available for ingestion. If the content is not available after this time, it may not be ingested or an alert generated. |
| Genesys Cache Lifetime (minutes) | Mandatory time to store Genesys user information for performance reasons within the Import Source before it is automatically refreshed. |
On Completion Delete Recordings Stored in Genesys Cloud | Optional to make Verba the single recording source for search, replay, archive and analysis. |
Step 4 - Click Save to save the settings
2. Import Policy Configuration
Follow the steps below to configure the Data Import action:
Step 1 - In the Verba web interface, navigate to Data > Data Management Policies
Step 2 - Click on the Add New Data Management Policy button at the top-right corner of the page
Step 3 - For the action, select Data Import
Step 4 - Under Available Import Sources, select the Import Source that you created, then click on the Add button just below the text field
Step 5 - Configure the policy details, based on the information that is shown in the configuration items summary table below
Step 6 - Set up how frequently the Import should be run in the Scheduling section
Step 7 - Click on Save
Configuration Parameter Name | Description |
|---|---|
| Enable Recording Rules | Specifies if all data should be processed in the imported data set or just the records of the recorded users as configured in Verba. Currently this setting is mandatory switched on (checked). |
| Execute Only on Selected Servers | If enabled, a specific server can be chosen that will run this policy |
3. User and Extension Configuration
Step 1 - In the Verba web interface, navigate to Users > Administration > Users and then click Add New User
Step 2 - In the Verba web interface, navigate to Users > Administration > Extensions and then click Add New Extension - It must be of type Number/Address.
4. Types of alerts raised by the Genesys Import Source
Alert Message | Explanation |
|---|---|
| Failed to retrieve next batch | Unable to retrieve list of recordings, likely network connectivity issue. |
Conversation failed to import | Problem with call metadata or media file. |
Could not obtain timezone offsets | Timezone offsets could not be extracted from the VFC database. |
| CDR placed in retry buffer | Call media unavailable for download. |
| Conversation failed to delete from Genesys Cloud | Permission issue. |
5. Migration Status Reporting
No report files are generated, however at the end of each batch, a notification alert is raised containing details of recordings migrated from Genesys into VFC. The alert contains the Genesys Cloud Conversation Id, along with the extension that participated in the call and a call participant number. The alert also contains the VFC conversation identifier and flags indicating whether the recording was successfully imported and media successfully downloaded, for example, it will take a few minutes to become available once the call ends. Another flag indicates if the conversation was already imported, for example, if the start time of ingestion was reset. If the switch is quiet, for example, overnight, the notification alert will normally state 'No conversations imported'.
6. Genesys Metadata
The system captures the following metadata specific to Genesys recordings. These fields are available through the standard metadata template.
Metadata Field | Description | Template | Available |
|---|---|---|---|
| Start Date | Start date of the conversation | Standard | Yes |
| Start Time | Start time on the conversation | Standard | Yes |
| End Date | End date of the conversation | Standard | Yes |
| End Time | End time of the conversation | Standard | Yes |
| Duration | Length of the conversation | Standard | Yes |
| User | Name of the recorded user | Standard | Yes |
| From | Subscriber / Third Party Phone number | Standard | Yes |
| From Info | User / contact name | Standard | Yes |
| To | Subscriber / Third Party phone number | Standard | Yes |
| To Info | User / contact name | Standard | Yes |
| Direction | Direction of the call from the system perspective, requires configuring internal number/domain patterns | Standard | Yes |
| Direction (User) | Direction of the call from the recorded user perspective | Standard | Yes |
| From (Verba) | Verba user name associated with the From Number | Standard | Yes |
| To (Verba) | Verba user name associated with the To number | Standard | Yes |
| Location | Hostname of the recording server | Standard | Yes |
| End Cause | Normal | Standard | No |
| Audio Codec | Audio codec of the recorded streams | Standard | No |
| Video codec | Video codec of the recorded streams | Standard | No |
| Platform Call ID | Unique conversation identifier received from the recorded platform | Standard | Yes |
| Silence Ratio | Ratio of silence in the conversation | Standard | No |
| Talkover Ratio | Talkover ratio of the conversation | Standard | No |
| Longest Silence | Length of the longest silence present in the conversation | Standard | No |
| User ID / Agent ID | User ID | Standard | No |
| From Device | Device ID of the calling party | Standard | No |
| To Device | Device ID of the called party | Standard | No |
| Dialed Number | Original dialed number | Standard | No |
| From IP | IP address associated with the calling party | Standard | No |
| To IP | IP address associated with the called party | Standard | No |
| Source Platform | Genesys | Standard | Yes |
| Conversation Type | Voice | Standard | Yes |
| Media Length | Length of the media file related to the conversation in hhh:mm:ss format | Standard | No |
| Media Error | Shows the media processing errors during recording | Standard | No |
| Voice Quality | Overall voice quality check score for the conversation | Standard | No |
| Record Type | Standard | Standard | Yes |
| 2N Source | In case of duplicate (2N) recording, records are marked as primary or secondary | Standard | No |
7. Resilience
In the event of failure to ingest Genesys content, resilience is provided by the retry buffer. This contains VFC CDR files in XML format that failed to be ingested and must be retried. The Genesys import source automatically adds a batch of up to 25 of these files to the current ingestion each time it runs. Once added, the XML file is removed from the retry buffer, but will automatically be re-added should the ingestion fail again. If the CDR is successfully ingested, it will appear in the ingestion status report alongside the other content. Files can be manually added or removed to the retry buffer if required for troubleshooting purposes. Retry buffer capability also enables the import source to track real-time as it enables historic failures to be retried.
Alternatively, if the Verba Import Service is required to be stopped for reasons of troubleshooting or maintenance, the manual procedure below must be used:
Step 1 - In the Verba web interface, disable the Data Management Policy associated with the Import Source
Step 2 - Open windows explorer and navigate to Program Files\Verba\work\cdrimport\GenesysCloud\laststate\policyId_importSourceId
Step 3 - Open the policyId_importSourceId.cursor file in notepad - it is one line and will look similar to:
c84f2f698fc9d64d64ed161d87b00c25_I_251182078220051266_19d0243a-9fd0-11d1-ac11-13453884b96c;2023.02.02 07:00:00.000
Step 4 - Set the timestamp to a date and time before the failure ensuring this timestamp plus the import batch duration and the recording lag is less than the current timestamp and then save the file.
Step 5 - Re-enable the Data Management Policy associated with the Genesys Import Source
8. Folders used by the Genesys Cloud Import Source
| Folder Location | Purpose |
|---|---|
| Program Files\Verba\work\cdrimport\GenesysCloud\work\policyId_importSourceId | Encrypted Token storage, temporary Genesys Cloud content download. |
| Program Files\Verba\work\cdrimport\GenesysCloud\laststate\policyId_importSourceId | Cursor file containing current import status so that import source can be stopped and restarted from previous Recording Start Timestamp value. The cursor file also contains the conversation identifier of the last ingested Genesys Cloud content for monitoring and troubleshooting purposes. |
| Program Files\Verba\work\cdrimport\GenesysCloud\retryBuffer\policyId_importSourceId | Contains VFC CDR files in XML format that failed to be ingested and must be retried. The import source automatically adds a batch of up to 25 of these files to the current ingestion each time it runs. Once added, the XML file is removed from the retry buffer, but will automatically be re-added should the ingestion fail again. If the CDR is successfully ingested, it will appear in the ingestion status report alongside the other content. Files can be manually added or removed to the retry buffer if required for troubleshooting purposes. Retry buffer capability also enables the import source to track real-time as it enables historic failures to be retried. |