Triggering Omni Exporter on database events

Omni Exporter can trigger export events based on changes in the database (as opposed to triggering on a schedule). When designing the database trigger, it is important to understand how and when the Medallia Experience Cloud database gets updated.

Omni Exporter can trigger when:

  • A survey record is created and/or updated.

  • During an update, the values of one or more specific fields changes.

  • A matching condition is true for the record, such as a field has a specific value.

Experience Cloud has a cache that buffers updates to the databases. It is possible to trigger Omni Exporter before the customer has finished the survey, or at least before the cache has finishes writing the completed survey to the database. Further, for anonymous surveys, also known as feedless surveys, it is possible for create and update events to happen at the same time, in which case Omni Exporter treats it as a create event; otherwise, it treats them as two separate events. See Triggering on anonymous surveys, below, for details.

Some Experience Cloud operations that update survey records do not happen until the customer has completed the survey, including Alerts, Text Analytics analysis, Anti-Cheating engine. Each of which can trigger an Omni Export event. But it is also the case that an export event can be triggered before these post-processing events have completed their updates.

Important: It is best to trigger an export after all post-processing events are complete by using a matching condition where e_status=1 (COMPLETED).
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: Do not select Last updated (e_lastupdated) field to trigger an Omni Exporter during an update.

This diagram illustrates various operations that create and update survey records in the database.

Database read events can happen before the database has been updated by earlier write events

Here are the key points in the various database operations:

  • The database has a cache. The cache buffers database write operations received from the importer, Survey Engine, internal operations, and post-processing events.

  • When the Importer performs an update operation, it reads directly from the database.

  • Personalized survey records are created from raw invitations, and some fields have values before the survey taker takes the survey. When taking the survey, updates are sent to the database every time the survey taker navigates to a page by clicking Next, Back, Finish, etc. See Triggering on a personalized survey, below, for details.

  • Anonymous survey records are created and then updated when the survey taker completes the survey, but these are each distinct database events. It is possible for the create to be written to the database while the update remains in the cache, or both events may happen in the same cache-to-database event. See Triggering on anonymous surveys, below, for details.

  • Omni Exporter can be triggered by any database create or update event. An anonymous survey create event might have no values in the fields if the update from the Survey Engine has not yet been written from the cache.

  • Post-processing operations happen when a survey is complete, that is, when Survey status (e_status) = 0 (COMPLETION_PENDING). After all post-processing operations are complete, Experience Cloud updates the record and sets Survey status = 1 (COMPLETED).

  • Updates from Omni Exporter can happen before post-processing operations are complete, that is, before they have been written to the database. You cannot, for example, trust that an Alert will have been triggered.

Triggering on a personalized survey

Newly created personalized surveys typically do not include the information needed for an export, except maybe the survey ID. As such, it is generally best to trigger on a schedule or on database update events.
Important: Beginning with the Winter 2020 release, the length of Survey IDs is increased to 64 bits (values can be greater than 2 billion). Make sure that your application can handle these values for Survey ID fields. Consider storing these values as text or as a big integer (signed 2's-compliment 64-bit integer).

When taking a survey, there may be several update events before the survey taker completes the survey. As such, the safest way to trigger is on an update where the Survey status (e_status) field is COMPLETED or at least COMPLETION_PENDING, and to use either some field unique to the program, or use a field value that identifies the survey to export. This ensures all the information provided by the survey taker is in the record. For example, (e_status=1) and (e_survey_program=17)

Some integrations create a record already in the COMPLETED state. That is one of the few times it is useful to trigger on a Create event.

Triggering on anonymous surveys

Anonymous surveys are special in that they are not added to the database until the survey taker completes the survey. This is different from a personalized survey where the record is created before the Invitation email is sent to the respondent, and the record is updated every time the survey taker navigates to a new page. When a survey taker begins to take an anonymous survey, the Survey engine creates a ballot, which is a temporary record. If the survey taker completes the survey, the ballot is is used to create and update the record in the database. If the survey taker never completes the survey, the ballot is discarded and the database is not touched.

On the way to the database the anonymous survey record goes through the database cache. It is possible that both events leave the cache and get written to the database in the same operation, in which case Omni Exporter considers it a single Create event. It is also possible that the anonymous Create and Update events happen separately, in which case Omni Exporter sees both a Create and an Update event. Which method Experience Cloud uses is realistically unpredictable.

Anonymous surveys might not have an initial update event

Important: It is best to trigger an export after all post-processing events are complete by using a matching condition where Survey status (e_status) = 1 (COMPLETED).

It is best to trigger an export after all post-processing events are complete by using a matching condition where Survey status (e_status) = 1 (COMPLETED) and when the database is updated. Something like this condition which triggers an export when the record for a specific program is complete: (e_status=1) and (e_survey_program=17).

If you need to trigger before the record is complete, you need to use a combination of triggers that account for create and update conditions. For example, if the survey includes a required question, use the presence of that question in the survey record as a Create trigger, and a change in the value of that field as the Update trigger.

A trigger using q_osat_scale11 for both the create and update triggers

The trigger happens when either:

  • A record is created and the field q_osat_scale11 is present in the record. In this case, that field must be a required field in the survey. If the field is not present, the Create event will not trigger. Further, because the record is new — the field value did not change — the Triggering fields assignment is ignored. This trigger is necessary for the case where the create and update operations happened in the same cache write.

  • A record is updated and the value of the q_osat_scale11 changed. This accounts for the update event from the Survey engine. This trigger is necessary for the case where the create and update happened as separate write operations. The create would have no values in the fields, so you need to trigger on the update to be able to export records.