Properties

Name

Name of the Omni Exporter specification.

Description

Text description of the specification. Describe the purpose of the specification and any noteworthy implementation details.

Processing mode

Whether or not, and how the Omni Exporter processes events. Omni Exporter has three components that process events:

• Event generation — A trigger happens (database change or scheduled activity) which places an event in the Omni Exporter processing queue.

• Web call — Read the event in the queue and execute a web call based on the event.

• Response processing — When enabled, web call responses are processed and passed to the importer.

The web call and response processing modes can operate in pretend mode: they run like normal but do not actually make the web call or update the database. This mode is useful for testing the exporter without actually sending a request to the target system, or actually updating the database,

The processing mode determines which of the components are enabled and how they respond.

Event generation enabled, web call enabled

Complete processing: events are triggered and queued, the web call executes with the target system, and response processing results can be passed to the importer.

Previously this mode was called Active.

Event generation disabled, action enabled

Does not process new events. However, the web call continues to process any events already in the queue (placed there when the event generation was previously enabled).

Previously this mode was called Inactive.

Event generation enabled, action disabled

Events are triggered and queued, but the web call does NOT execute (and as such, no responses handling). The queued events will be processed the next time the web call is active or put in pretend mode.

Event generation enabled, action pretend

Events are triggered and queued. The web call executes in pretend mode: it removes events from the queue but does not actually send data to the target system, and as such, there is no response processing.

Use this to test the exporter specification (such as trigger condition or field lists) without interacting with the target system. The Omni Exporter events lists shows these events in gray color.

Previously this mode was called Pretend.

Event generation enabled, action enabled, response handling on pretend

Events are triggered and queued, the web call is executes in active mode, but response processing is executes in pretend mode: the importer pretends to accept the response but it does not actually import them into the database.

Use this to test the request and response without updating the database. The Events list shows these events in gray color.

Previously this mode was called Active with pretend handling.

Event generation disabled, action disabled

No processing: no events and no web calls.

Trigger properties

The trigger defines the condition(s) that activates the Omni Exporter for this specification.

Trigger by

The catalyst that starts an export event.

• Field value changes — Export starts when one or more trigger fields changes value. Use this option to export record data.
• Schedule — Omni Exporter sends a request to the target system the selected  schedule. The request cannot contain record data, though the HTTP header may contain dynamically generated header-field values. Use this option to "ping" the target at a scheduled time, and optionally collect data in the response from the target and pass it on to Auto Importer.

Data object

Type of Medallia records to export and to use for triggers.

• Survey — Survey records, includes invitation details for surveys.
• Account — User account records.

Trigger an event on record

These additional options further clarify the trigger for record exports; one must must be selected:

• CREATION — Triggers when a new record is created. This option ignores any Triggering fields, but does adhere to the Matching condition (which is recommended).
• UPDATE — (default) Triggers when an existing record is modified. It is highly recommended to also include Triggering fields to limit the records to a common set.

Triggering fields

Field(s) to watch for change. The record export only happens when the watched field changes value and as the result of an UPDATE event. When multiple fields are selected, a change in any of the fields triggers the event.

Restriction: Do not select field e_lastupdated to trigger an Omni Exporter.

Warning: K-field processing happens in the same transaction that created or updated the record, which is also the transaction that triggers Omni Exporter. If the K-field is incomplete or has and error at the time Omni Exporter accesses the field, the field is considered "blocked", an event ticket is logged, and Omni Exporter abandons the export.

Matching condition

Identifies records — based on field values — that will be included in the export.

This option is only available for when the Data object is Survey.

The match condition follows Conditions syntax. For example, for surveys in the completed (1) or delivered (12) states, and belonging to a specific feedback program:

(e_status = 1 OR e_status = 12) AND e_company_account_id present AND e_company_feeback_program_enum=1

Note: When using fields in the condition, be sure to use fields that have values at the time you want to trigger the export. For example, Q-Fields will be empty until after customers have submitted feedback. Generally, it is a best practice to make sure that all fields in your matching condition are also included in your triggering fields to ensure you are not missing a value in one of the fields used in your condition string.

Batching properties

Control how many records to send to the target system, and how they are grouped when there are more than one. These options are not relevant to scheduled triggers; only to record exports.

Maximum batch size

How many records can be combined in a single export event (one HTTP request). Default is one (1); maximum is 1,000.

Increase this value to reduce the number of HTTP requests. Verify the target system can handle more than one before increasing this value.

When Omni Exporter triggers this specification, it will include all the records currently available, up to the count specified by this property. The exporter does not wait for this many records to be available; rather, it sends the count currently available.

This option is useful when Auto Importer processes large batches of records. Then every record in the batch has the potential to trigger an Omni Exporter event.

Grouped by

Field that identifies when to split a batch into separate Omni Exporter events. By default, None, Omni Exporter includes all the export records up to the maximum batch count in a single event. Use this option to separate "like" records into their own batches/events.

Use this option when the target system requires all records in the batch to be similar based on some criteria, such as all records for a specific survey or business market.

Multi-threading properties

Maximum number of concurrent threads

How many parallel connections to use to connect to the target system. Default is 1; maximum is 50 per company.

Note: Before changing this setting, verify the change with the owner of the remote host. Often they want to receive the items in strict order, which requires the concurrency level must be set to 1; otherwise, parallel events can arrive out of order. it is also possible the remote host owners (typically IT department of the company) will complain if Omni Exporter hits their server too hard.

Restriction: There is a default maximum limit of 50 concurrent threads per company. If several active Omni Exporters are already using 50, a new Omni Exporter will be blocked until one of the others finishes. If you have more than 50 threads, contact your Medallia representative to request a higher limit.

Retry Policy properties

These properties determine what to do when the target system is not accepting data, or not responding in a timely manner. When Omni Exporter fails to connect to to the target, it waits for the specified count of seconds, and then tries again to connect (when the number of retries is greater than zero). When the retry fails, Omni Exporter waits for a longer period of time before trying again. Each wait-interval is exponentially longer than the one before.

If the target server does not respond within 120 seconds, the request is considered a failure and Omni Export retries the connection based on these properties.

After attempting to connect per the count of times specified by Number of tries, Omni Exporter abandons the request and reports a Failed state.

After saving the changes, the Retry Policy section reports the wait times for the intervals. For details about the event and retries, and to review debugging information about the activities, see Omni Exporter events.

Number of retries

Count of retry attempts to make; range is zero (no retries) to five.

Base wait time (seconds)

Wait time between each retry; increases exponentially based on the base wait time.

The first retry attempt is at the base wait time; then, for each new attempt, the previous wait time doubles and is added to the base wait time. To see when each retry attempt occurs, enter the number of retries and the base wait time and click Save, Medallia Experience Cloud shows the wait time for each attempt.

JSON Web Token properties

JSON Web Token (JWT) is an open standard for securely transmitting information in a JSON object.

JWT

A JSON Web Token (JWT) is split into three Base64Url-encoded parts separated by dots. The first two parts encode JSON objects. The first part is a header detailing the signature and hashing algorithm. The second part is the payload and it contains a list of claims. Claims are statements about an entity (typically, the user) and additional data. There are three types of claims:

• Registered claims — A set of predefined claims with known meaning. They are not mandatory, but recommended. For example: iss (issuer), exp (expiration time), sub (subject), and aud (audience).

  Tip: Use the ISO-8601 duration format to define dates and times in the payload. For example, expiration time can be expressed as shown below:

  {
     "exp" : "PT15M"
  }

• Public claims — User defined claims that should be collision-resistant. That means they should be defined in a IANA Registry or using a collision-resistant URL namespace.

• Private claims — Any claim defined for private usage.

Message Digest

Secure hash algorithm used for signing the JSON Web Token.

Restriction: JWT tokens must be secured with RSA 2048 bits, or with Elliptic Curve P256, P384, or P513 algorithms. HMAC signatures are not supported.

JWT Signing Key

It is the third part of a JWT: a private key for signing the JSON Web Token.

Important: For signing keys to be available in the JWT Signing Key dropdown, they must be registered in Experience Cloud.

To set up a JWT in Omni Exporter:

For more details on how to include JWT values in login headers or in request headers, see OAuth tokens and request headers.

Action

Action properties define the type of action that is used for this exporter.

Login properties

Login properties define how to authorize with the target system.

Login method

Login protocol to access the target system.

• None — Target system does not require a login.
• OAuth — Open Standard for authorization.

• Slack — Authorization method for Slack. The access token from Slack is stored in the Experience Cloud database, and is used for all interactions between Medallia Experience Cloud and Slack. For details on how to set up the Slack integration, see Medallia for Slack.

Pick a Login Method, then click Save to see additional properties applicable to the chosen protocol.

OAuth Login properties

When the Login method is OAuth, these additional Login properties appear after clicking Save.

When using custom HTTP request headers, you must include the OAuth access token in the header. See OAuth tokens and request headers, below, for details.

Login URL type

How the Login URL property is evaluated.

• Static — The property is literal text.

After selecting this value, click Save.

Login URL

URL (HTTPS) where the authorization request will be sent. Depending on the value of the Login URL Type property, this is either literal text, or a JavaScript that generates the URL.

Restriction: The URL must be an HTTPS connection, and the target host must be configured with a public certificate with a publicly resolvable host name. By default, a self-signed certificate or one with an IP address will not work: typically, the target must be configured with a SSL/TLS certificate signed by a public and trusted certificate authority. However, if you would like support for self-signed certificates enabled on your instance; ask your Medallia expert about adding advanced SSL features to your Omni Exporter configuration. For more information regarding SSL/TLS certificates, see SSL/TLS options.

Login headers type

How the Login Headers property is evaluated.

• None — Hides the Login headers property.
• Static — The property is a comma-separated list of literal field-name/value pairs, where the names and values are separated by a colon. For example, Pragma:no-cache,Content-Language:en.

After changing this value, click Save to show or hide the Login headers property.

Login headers

Additional HTTP header fields to include when the Login headers type property is Static. This is literal text of the fields.

Typically the Login headers includes name/value fields that identify the Medallia customer to the authorizing agent. Some field values are automatically masked with asterisks (*) by Medallia when the export specification is saved. The fields that are masked include any where the name is or contains "password", "token", "secrets", "credential", or "authentication". This example shows some login header fields with masked values:

password : ***,
grant_type : password,
client_secret : ***,
client_id : 3MVG93hUw4lyaoWGMccRmM6iF0G2BLyfWNK4OBfX8usGHB7Ar,
username : omni-integration-user@medallia.com

Note: If any of the names/value fields contain special characters such as a double-quote (") or comma (,), an advanced JSON-based format is required. Contact Medallia Support for further details and enable this advanced mode on your instance.

Use HTTP Basic Authentication

Encode the client_id and client_secret values in the Login Headers field using the Authorization header and the HTTP basic authorization schema defined by RFC-7617.

Otherwise, when not checked, the client_id and client_secret values in the Login Headers field are encoded in the HTTP POST body as URL-encoded form parameters. This is the default behavior from before this option existed.

Test the login

Verify Omni Exporter can use OAuth to login to the target system.

After providing the OAuth login property values, click Save and then use the Test the login button to verify Omni Exporter can login to the target system. Each time the authorization is requested, the Omni Exporter events screen lists the activity and includes reports to the request and response headers for debugging.

You should see “Your request was successful” at the bottom of the Setup screen.

If the test failed, you will see an authentication failed message at the top of the screen. When this happens, verify the Login settings are correct for your installation.

HTTP Request Assembly properties

These properties define the HTTP request, optional header, and optional content (body) to send as the request to the target system.

HTTP method

HTTP request method; one of:

• POST — Create new records in the target; expects a 201 (Created) response code from the target.
• GET — Read-only (some targets require a GET to receive data); expects a 200 (OK) response code from the target.

• PUT — Create, update or modify existing records in the target; expects a 200 (OK), 201 (Created) or 204 (No Content) response code from the target.

• PATCH — Update or modify existing records in the target; expects a 404 (Not Found) response code from the target.
  Note: A PATCH is supposed to include instructions to pass to the target, and then the target updates the records based on the instructions; unlike a PUT, which is supposed to be just the data.

URL type

How the URL property is evaluated:

• Static — The property is literal text.
• JavaScript — The property is a JavaScript that generates the URL. When using this option, the script must write() the URL to the output.

After changing this value, click Save to show or hide the URL property.

URL

URL where the request will be sent. Depending on the value of the URL Type property, this is either literal text, or a JavaScript that generates the URL.

Important: When using an HTTPS connection (and you should), the target host must be configure with a public certificate; a self-signed certificate will not work.

Content type

The nature of the data in the body (content) the target expects; this sets the Content-Type header field. Options are:

• TEXT_HTML — Content is plain HTML (text/html)
• TEXT_PLAIN — Content is plain text (text/plain)
• APPLICATION_XML — Content is XML (application/xml)
• APPLICATION_JSON — Content is JSON (application/json)

This option sets the HTTP Content-header field; it does not affect the body of the request. For example, if you choose to send a JSON header, you need to use JavaScript and create the data in the body.

Headers type

How the Headers property is evaluated

• None — Hides the Headers property.
• Static — The property is a comma-separated list of literal field-name/value pairs, where the names and values are separated by a colon. For example, Pragma:no-cache,Content-Language:en
• JavaScript — The property is a JavaScript that generates the headers. When using this option, the script must generate the headers as JSON a object.

After changing this value, click Save to show or hide the Headers property.

Headers

Additional HTTP header fields to include. Depending on the value of the Headers type property, this is either a list of the field names and values as text, or a JavaScript that generates the fields.

Note: When using OAuth login, the authorization server returns a token whose value must be included in the request header. See OAuth tokens and request headers, below, for details.

Restriction: Including a Content-Type: field here overrides the Content type property value.

Any field whose name is or contains "password", "token", "secrets", "credential", "authorization", or "authentication" is automatically masked and the value is replaced with asterisks (*) when the export specification is saved.

Fields used in the action

Fields to be used in the assembly of the request body, and the response body processing, and whose values will be included in the contents. Select the fields to include, and then reference them in the Body property when using JavaScript to assemble the contents. The set of available fields include all A-field, E-Fields, Q-Fields, K-Fields, and any "survey_id" field; other system fields cannot be used.

If the exporter triggers when field value changes, the current field value is the new value. To include the value prior to the change, select the version of the field whose name that ends with @pre.

Additionally, there are specific suffixes for enumerated fields to distinguish between the name of the field (/name) and its sequence number (/sequence_number) or numeric value (/numeric_value).

Note that since @ and / are special characters in JavaScript, you need to use an alternative syntax to collect the data of these fields and include it in the request body. For information see JavaScript in Omni Exporter.

Warning: K-field processing happens in the same transaction that created or updated the record, which is also the transaction that triggers Omni Exporter. If the K-field is incomplete or has and error at the time Omni Exporter accesses the field, the field is considered "blocked", an event ticket is logged, and Omni Exporter abandons the export.

Restriction: Depending on when the record is processed and ready for export by Omni Exporter, some fields may not be populated or up-to-date when the export happens. This is especially true for Alert and other A-Fields processed after the customer submits the survey. See Triggering Omni Exporter on database events for more information.

Restriction: Do not use the @pre forms of these fields because the results are not what is expected.

a_alert_assigned_to_groups
a_alert_assigned_to_minutes
a_alert_assigned_to_names
a_alert_closed_by
a_case_edited_by
a_case_edited_by_role
a_log_notes
a_rapid_response_all_templates_used
a_rapid_response_comment
a_rapid_response_send_date
a_rapid_response_sent_by
a_rapid_response_status
a_rapid_response_template
a_socialresponse_comment
a_socialresponse_first_publish_date
a_socialresponse_publish_date
a_socialresponse_send_date
a_socialresponse_sent_by_role
                     

This property has no effect when the Body type is None or Static.

Body type

How the Body property is evaluated

• None — Hide the property and do not include any contents in the request (just send header fields).
• Static — The property is literal text.
• JavaScript — The property is a JavaScript that generates the URL. When using this option, the script must write() the URL to the output. See JavaScript in Omni Exporter for details.

This property is hidden when the HTTP method is GET.

Accepted HTTP status codes

Comma separated list of HTTP status codes that trigger request processing (get passed to the importer for further processing). Other status codes (except 2XX codes) are be treated as errors and trigger retries. All 2XX status code are considered successful, so they are not accepted in list.

For example, suppose the target system returns a 400 (Bad Request) code, and the body of the response includes an error message. You could add 400 to this option, and then have the importer specification process the response, extract the error message, and insert it into a field in the survey record.

Normally you would want the 400 to be an unsuccessful request. By omitting it from this list, when the exporter encounters this error it marks the event as a failure. In that case, you need to manually examine the error on the Omni Exporter events screen.

Body

Definition of the contents section of the HTTP request. Depending on the value of the Body type property, this is either literal text, or a JavaScript that generates the fields.

In most cases use JavaScript to collect the values from the selected fields, and to include them in the contents. The output of the script must match the format defined by the Content type property, such as JSON or XML. Retrieve the records and fields with the ChangedEntities data array. There is one row in the array for each record to be output. This example builds a JSON object that pairs the names of the fields in the target system with the values of the matching export fields.

See the example in "Accessing record data," in JavaScript in Omni Exporter for an example of collecting record data and including it in the request body.

HTTP Response Processing properties

These properties construct data to send to Auto Importer Processors after receiving a response from the target host. The processing may — but does not have to — include data returned from the target host.

Omni Exporter exports directly to Auto Importer. Select an Auto Importer specification and send the resulting Omni Exporter payload directly through the Auto Importer without any intermediate steps required.

Typically this processing is used to update the exported records based on the Omni Export event, or based on information returned from the target, or both.

Response body processing

Whether or not to process the response, and how to do it.

Tip: Medallia recommends selecting None for this parameter.

• None — Take no action; do not process the response.
• JavaScript — Use JavaScript to process the response and then send data to the Auto Importer for inclusion in the Medallia database. Choose this option and save the specification to show the JavaScript editor. See JavaScript in Omni Exporter for details.
  Important: Medallia Experience Cloud uses a JavaScript processing engine called Mozilla Rhino — also known as the Rhino Engine — to provide flexibility for scripting. Access to the Rhino Engine is restricted by a ClassShutter mechanism, which implements arbitrary logic to determine whether Rhino can access the class. When access is denied, Experience Cloud shows an error message. To access a class that is not currently allowed, contact your Experience Cloud expert. For more information, see JavaScript allow-listing.

Auto Importer specification

The Auto Importer specification that will incorporate the processed response into the database.

Pre-processor specification

The data import Preprocessor specification to pre-process responses before the Auto Importer. Leave blank to skip Auto Importer pre-processing.

OAuth tokens and request headers

OAuth uses a third-party, trusted by the target system, to approve the login by issuing a token that Omni Exporter then presents to the target system. Omni Exporter can continue to access the target system until the token expires, at which time it will again request access from the authorization agent.

When using OAuth login, the token value must be included in the request. You must include the token in the header definition. For example, an HTTP GET header might look like this:

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer someTokenText

Static header

To include the token in a Static header, add this line:

Authorization: Bearer $TOKEN$

The access token can be a JWT; to include it in a Static header, add:

jwt_token: $JWT$

JavaScript header

When constructing the header with JavaScript, enclose "Bearer " and the $TOKEN$ object in a quoted string, like this:

var entities = data.changedEntities;
var entity = entities[0];
return {
    'Authorization' : 'Bearer $TOKEN$',
    'SurveyID' : entity.a_surveyid,
    'DestinationCode' : 'CC' 
  }

For JSON Web Tokens, use the $JWT$ object in a quoted string, like this:

var entities = data.changedEntities;
var entity = entities[0];
return {
    'jwt_token' : '$JWT$',
    'SurveyID' : entity.a_surveyid,
    'DestinationCode' : 'CC' 
  }

Login with username and password

Some target systems use username and password for authentication. This is common in some older REST APIs. For example, and call to a REST API that requires a username and password might look like this when using the curl utility in a console window:

curl -u 'username:myPa33w0rd' https://api.example.com/rest/api/issue

For Omni Exporter, the last part of the command is the URL property. But Omni Exporter does not have properties for username and password properties. Instead, you need to create an Authorization key based on the username and password, and enter that as a field in the Headers property.

To create and use an Authorization key:

1. Use curl to verify you can connect to the external system using the username and password to retrieve (get) some information. For example, a request might look like this:

   curl -u 'username:myPa33w0rd' https://api.example.com/rest/api/issue/1563

   This should return a message from the external system, in this case, data about "issue 1563". If you get an error like "(401) Unauthorized", you do not have the proper username or password.

2. When you have successfully connected to the target system, repeat the command, but insert "--verbose", like this:

   curl -u 'username:myPa33w0rd' --verbose https://api.example.com/rest/api/issue/1563

   This time, the data returned will also include details about the curl operation. The console output should look similar to this:

   curl -u 'username:myPa33w0rd' --verbose https://api.example.com/rest/api/issue/1563
   *   Trying 10.15.99.999...
   * Connected to api.example.com (10.15.99.999) port 443 (#0)
   * TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
   * Server certificate: api.example.com
   * Server certificate: SSL.com DV CA
   * Server certificate: USERTrust RSA Certification Authority
   * Server certificate: AddTrust External CA Root
   * Server auth using Basic with user 'username'
   > GET /rest/api/issue/1563 HTTP/1.1
   > Host: api.example.com
   > Authorization: Basic am7rR62diw3XNz4VyNoOo1CV3k5RW4iSG8cDon"sdd=
   > User-Agent: curl/7.43.0
   > Accept: */*
   > 
   < HTTP/1.1 404 
   ...
   

3. Near the beginning of the verbose output locate the Authorization line:

   > Authorization: Basic am7rR62diw3XNz4VyNoOo1CV3k5RW4iSG8cDon"sdd=

4. Copy the line, excluding the "> " at the beginning, and paste it into the Headers property:

   

5. Click Save.

6. Because the field name is "Authorization", one of the special field names, the authorization key is masked to hide it from people looking at this screen.

   

After completing the rest of the Omni Exporter specification, the exporter should be able to connect to the target system.