Data mappings

The Data mappings section is a form-based interface to guide you as you specify how your imported Speech data is processed and stored in Medallia Experience Cloud. It provides instant error messaging and real-time previews. The data is used to provide context for voice signals by processing metadata associated with the signals (audio files).

Screen capture of the data mapping form for file-based connectors

By default, API-based connectors collect a minimum required set of metadata, which varies from vendor to vendor, and bring it into Experience Cloud so they work without additional configuration, though you can customize them by adding mapping rows to the initial setup.

Screen capture of the data mapping form for API-based connectors showing default metadata mappings

To create a data mapping:
  1. Load a sample file
  2. Map agent data to unit fields
  3. Map input data to data fields
  4. Save the data mapping

Load a sample file

For File-based connectors

Load a sample file with Browse files to create the data mapping. The file must be in the same format (i.e., same columns and same types of data) as future files containing call-recording metadata.

Ensure the metadata file contains data for these required properties:

  • Unit identifier or UDF (unit data field) to tie the record to an agent unit

  • Unique identifier for call

  • Unique identifier for signal file

  • Call date time

Note: This step is required for file-based connector types, to know what fields are available. As mentioned before, API-based connectors already bring required fields into Medallia Experience Cloud by default. If using the Speech API’s speech_additional_info field to add additional metadata, see For the Medallia Speech API connector below.

Screen capture highlighting the Browse File to upload a new sample file option

Restriction: The maximum size of the sample file is 5 MB (5,242,880 bytes).
Warning: Avoid using Excel files for production imports because large Excel files can cause large performance problems. The current best practice is to convert the file to ASCII or UTF-8 encoded CSV first; CSV does not have the same size issues as Excel.

Experience Cloud analyzes the uploaded sample file and reports the number of columns and rows available for mapping. The columns represent the “input” fields and the rows represent records.

Example of the mapping for a successfully loaded sample file

For the Medallia Speech API connector

The Speech API and the Speech API connector are almost identical mechanisms, with one key difference: the Speech API connector allows for clients to bring their own custom metadata. This is not supported by the native Speech API.

When using the Medallia Speech API’s speech_additional_info parameter to send additional metadata, map the values in the API request to Experience Cloud fields. For more information, see Speech API.

Load a JSON file with an example of the data values included in the speech_additional_info parameter of the Speech API request. Use the same schema in the JSON file that is used in the Speech API request.

Restriction: The maximum size of the JSON file is 1 MB (1,048,576 bytes).
Example JSON file:
{
  "agent_first_name": "Jane",
  "agent_last_name": "Doe",
  "direction": "inbound",
  "skill": "testing",
  "custom_field_1": 1,
  "custom_field_2": 2,
  "custom_field_3": 3
}

Click Browse files to load the file.

Screen capture highlighting the Browse File field with a JSON file uploaded.

After you load the sample JSON file, manually map the values to Experience Cloud fields via Add Mapping Row. For more information, see Mapping input data to data fields.

For Speech API, doing a transform on the unit agent mapping is not supported. You must provide exact unit IDs (with prefixes) to the unit_identifier property in the Speech API.

Map agent data to unit fields

When Experience Cloud pulls in a call recording, you can map it to an agent. Call recordings can be tagged to specific agents when the agents are part of your Org hierarchy as a unit, and their external system agent IDs are stored in a unit data field in Experience Cloud. When call recordings are associated with specific agents, you can set up reporting tools to show who was the contact center agent for each call.

The agent data mapping includes:

  • The Incoming Value is the column in the incoming file that has the external system agent ID, the Agent Mapping Unit Field is the field in Experience Cloud in which the agent ID will be stored, and the Medallia Field is the record field in which the unit data will be stored, for example Unit ID (e_unitid).

  • Custom Formula alters the input data to the format required for the output. For example, a transform might be a JavaScript that converts agents' full name into agents' first and last name.

Screen capture showing agent mapping columns

When viewing an active connector, hover over transforms to see the full formula transform being done for mappings. You can select the formula for analysis.

Screen capture showing tooltip with full formula transform being done for the mapping

Agent unit mappings

Connectors have additional capabilities for unit linkage. Agent unit mappings can be done not just by Unit ID (e_unitid), but by unit data fields. Some source systems may use a different identifier for agent units than Experience Cloud does, but do not force the source system or Experience Cloud to change how an agent hierarchy is architectured. Experience Cloud supports matching on unit data fields. When you configure a connector based on unit data fields, make sure unit data field values are unique in the Experience Cloud Org hierarchy. Having duplicate values creates issues in unit mappings.

Map input data to data fields

API-based connectors collect a minimum required set of metadata and map it into Medallia fields.

Screen capture showing automatic mapping of vendor fields into required Medallia fields for API-based connectors

After uploading a file, file-based connectors automatically populate Incoming Value drop-down lists, so you can select the right input for each required Medallia Field.

Screen capture showing option to map incoming values into required Medallia fields for file-based connectors

When there is additional call-recording metadata available, you can manually map it clicking Add Mapping Row.

Important: Be careful when mapping file metadata to e_speech_agent_channel and e_status fields since such mappings can cause processing issues. Generally, it is better to avoid these fields for connector data mappings.

For Speech API speech_additional_info metadata, click Add Mapping Row. Click Choose Value, then scroll to and click speech_additional_info to display the list of the fields uploaded in the sample JSON file. Select the input for each Medallia Field needed.

The call record mapping includes:

  • The Incoming Value is the column in the incoming file that has the call-recording metadata, and the Medallia Field is the field in Experience Cloud to which the data will be imported.

  • Custom Formula alters the input data to the format required for the output. For example, a transform might be a JavaScript that converts agents' full name into agents' first and last name.

Restriction: You can map an Incoming Value to a Medallia Field as long as they have the same data type.

Save the data mapping

Click Save (frequently) to save changes to the mapping.

When there are validation issues with the mappings, the screen shows a warning message. Hover over the error notification next to each row to review the details of each mapping.

Screen capture highlighting the validation issue warning messages.

When done, click Close to go back to the Connectors screen; you do not need to also save on that screen.

Exporting the mapping

Once you have completed the data mapping process, click Data export icon Export mappings in the top right corner of the record mapping pane to generate a CSV file with all mappings.

Screen capture showing the record mapping pane with highlighted export mappings button

The CSV file fas the format: first column = Incoming value, second column = Medallia field.

Screen capture showing exported mapping sample