Genesys Cloud CX - Import Source Configuration

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.


Note: Genesys Cloud CX integration with SBC recording and Genesys Cloud CX integration with AudioHook recording are not currently supported.

Migration Support

The following modalities are supported: Voice only.


For a general description of VFC Import sources, refer to Import sources.


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 using the Proxy if required.
  •  HTTPS Genesys Cloud API URL and port 443 from the VFC server or using the Proxy if required.

1.1.2. Customer provides TLS Certificate, otherwise standard VFC API certificate is used.

1.2. Create a Genesys OAuth Integration


Follow these steps in Genesys Cloud before creating a VFC Import Source:

Step 1 - Open the Genesys Cloud Admin Page, go to Integrations > OAuth, and select Add Client:


Step 2 - Select Grant Type Client Credentials. The Token Duration can be adjusted as required because it is automatically renewed by the VFC integration. Then click Save. The Client ID and Client Secret are automatically generated.


Step 3 - From the Genesys Cloud Admin Page, go 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:

    1. 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.
    2. 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 VFC to create a new Import source:

Step 1 - Open the VFC Web interface, then select Data > Import Sources from the top menu.

Step 2 - Select Add New Import Source.

Step 3 - Complete the configuration according to the requirements in the following table:

Configuration Item

Description

NameName your Import Source. This name identifies the source across the system.
TypeSelect 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 using the Proxy if required.

HTTPS Genesys Cloud API URL

Mandatory Genesys URL used when the Import Source interacts with the Genesys API 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 using 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 is used. For more information, see Server Certificates.

TLS Key FileOptional file system location where the certificate key is stored.
TLS Key PasswordSpecify the password for the file that contains the certificate keys.
TLS Trust ListCertificate chain (or Chain of Trust) consists of a list of certificates that start from a server's certificate and terminate with the root certificate. If the certificate of your server is to be trusted, its signature has to be traceable back to its root CA.
Forward Proxy AddressOptional. IP address or FQDN of the forward proxy. When defined, the system connects through a forward proxy.
Forward Proxy PortOptional. The port of the forward proxy.
Forward Proxy UsernameOptional. User name for basic authentication for the forward proxy server.
Forward Proxy PasswordOptional. Password for basic authentication for the forward proxy server.
Transcoding by GenesysMandatory 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 value ensures recordings are presented with the correct time.

Recording Start Timestamp

Mandatory. Time stamp of the earliest Genesys content to be ingested. This value can be a time stamp in the past, for example, 2020, if historic Genesys content has to be ingested.

The Import Source gradually catches up with real-time as it is run by successive Data Management Policies, but takes 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, for example, 999 and reduce the Availability Delay to a small number, for example, 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 VFC 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 VFC web interface, go to Data > Data Management Policies.

Step 2 - Select Add New Data Management Policy.

Step 3 - For the action, select Data Import.

Step 4 - Under Available Import Sources, select the Import Source that you created, then select Add 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 runs in the Scheduling section.

Step 7 - Click 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 VFC.

Currently this setting is mandatory switched on (checked).

Execute Only on Selected Servers

If enabled, a specific server can be chosen that runs this policy

3. User and Extension Configuration

Step 1 - In the VFC web interface, go to Users > Administration > Users and then click Add New User

Step 2 - In the VFC web interface, go to Users > Administration > Extensions and then click Add New Extension. It must be of type Number/Address and contain the user's actual extension number.

4. Types of alerts raised by the Genesys Import Source

Alert Message

Explanation

Failed to retrieve next batchUnable 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 bufferCall media unavailable for download.
Conversation failed to delete from Genesys CloudPermission 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 newly imported and media successfully downloaded, for example, it takes 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 typically states '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 DateStart date of the conversationStandardYes
Start TimeStart time on the conversationStandardYes
End DateEnd date of the conversationStandardYes
End TimeEnd time of the conversationStandardYes
DurationLength of the conversationStandardYes
UserName of the recorded userStandardYes
FromSubscriber / Third-Party Phone numberStandardYes
From InfoUser / contact nameStandardYes
ToSubscriber / Third-Party phone numberStandardYes
To InfoUser / contact nameStandardYes
DirectionDirection of the call from the system perspective, requires configuring internal number/domain patternsStandardYes
Direction (User)Direction of the call from the recorded user perspectiveStandardYes
From (Verba)VFC user name associated with the From NumberStandardYes
To (Verba)VFC user name associated with the To numberStandardYes
LocationHost name of the recording serverStandardYes
End CauseNormalStandardNo
Audio CodecAudio codec of the recorded streamsStandardNo
Video codecVideo codec of the recorded streamsStandardNo
Platform Call IDUnique conversation identifier received from the recorded platformStandardYes
Silence RatioRatio of silence in the conversationStandardNo
Talkover RatioTalkover ratio of the conversationStandardNo
Longest SilenceLength of the longest silence present in the conversationStandardNo
User ID / Agent IDUser IDStandardNo
From DeviceDevice ID of the calling partyStandardNo
To DeviceDevice ID of the called partyStandardNo
Dialed NumberOriginal dialed numberStandardNo
From IPIP address associated with the calling partyStandardNo
To IPIP address associated with the called partyStandardNo
Source PlatformGenesysStandardYes
Conversation TypeVoiceStandardYes
Media LengthLength of the media file related to the conversation in hhh:mm:ss formatStandardNo
Media ErrorShows the media processing errors during recordingStandardNo
Voice QualityOverall voice quality check score for the conversationStandardNo
Record TypeStandardStandardYes
2N SourceIn duplicate (2N) recording scenarios, records are marked as primary or secondaryStandardNo

7. Resilience

If the ingestion of Genesys content fails, the retry buffer provides resilience. This buffer 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 is automatically readded if the ingestion fails again. If the CDR is successfully ingested, it appears 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 VFC Import Service is required to be stopped for reasons of troubleshooting or maintenance, the manual procedure below must be used:

Step 1 - In the VFC web interface, disable the Data Management Policy associated with the Import Source.
Step 2 - Open Windows Explorer and go to Program Files\Verba\work\cdrimport\GenesysCloud\laststate\policyId_importSourceId
Step 3 - Open the policyId_importSourceId.cursor file in a text editor program. The file contains one line and looks similar to the following example:
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 that the sum of the time stamp, the import batch duration, and the recording lag is less than the current time stamp, 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 LocationPurpose
Program Files\Verba\work\cdrimport\GenesysCloud\work\policyId_importSourceIdEncrypted Token storage, temporary Genesys Cloud content download.
Program Files\Verba\work\cdrimport\GenesysCloud\laststate\policyId_importSourceIdCursor 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_importSourceIdContains 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 is automatically readded if the ingestion fails again. If the CDR is successfully ingested, it appears 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.