Troubleshooting Data Destinations
Contents
About
After adding or updating a TrueContext Data Destination
A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats., it is important to test it thoroughly before using it in production.
Destination Executions
A Data Destination executes each time that a form linked to the Data Destination is submitted. When it executes, the Data Destination then attempts to route data to the configured location. Executions (one per destination per form submission) are listed in the web administration portal.
The Web Portal offers several ways to view the details of a Data Destination execution, making it easy to determine if filters, Connections A Connection is an integration point that's used to link a TrueContext Data Source or Data Destination to an external service to import or export data. Data Destinations and Data Sources that share the same external service can also share the same Connection., and other options are configured correctly. It also clearly lists details of execution failures.
When incorrect configuration results in a failure, it is simple to update the Data Destination and re-execute failed executions to try sending the data again.
Problem Contact Email Addresses
A key tool in testing and troubleshooting Data Destinations A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats. is ensuring that your team has at least one Problem Contact Email Address configured. This is the easiest way to gain visibility to data destination execution failures; an email notification will be sent to the provided addresses. Problem Contact Email Addresses can be configured through Team Settings The Team Settings page is the page where an admin can manage their team's account and edit certain information, such as assigning a Problem Contact Email Address, toggling push notifications, and viewing the account's billing information. (under General Settings).
Error Handling
When a data destination fails, TrueContext automatically retries the destination at set intervals. Most failures correct themselves and require no intervention; however, TrueContext will automatically send a failure notification email to Problem Contact Email Addresses after the third failure (approximately an hour after the first attempt). This can be configured under the Destination Basics tab of the Data Destination setup. For more information, see the topic Set Up Failure Notification Emails.
Testing Data Destinations
The only way to test a Data Destination is to submit a form linked to the Data Destination. While some Data Destination configuration issues will become obvious when a form is submitted (like if the execution fails), other configuration errors may not be immediately noticeable. Without thorough testing, these errors can make it into production before being spotted. Save yourself production errors and delays by testing your Destinations before deploying to your users.
Connection
A Connection that is not functional will cause Data Destination executions to fail. Submit a form linked to the Data Destination, check that the execution has not failed, and check that every document/notification was successfully delivered to the configured locations/recipients.
Enabling/Disabling Data Destinations
Disable this destination: Enable this option if you wish to create the Destination without allowing it to accept form submissions—it can still be linked in forms, but the Destination will not execute if forms are submitted.
Note: Disabled Data Destination will still appear in the Destinations tab in the Form Builder, but it will not receive any form submissions.
Filtering
Ensure that any filtering that is configured functions correctly, and the Destination only executes when you want it to. This is particularly important in the case of Custom Filter rules, which use regular expressions, and a single incorrect character can break the expression. Test filter rules by submitting forms in a test environment, testing all answers referenced in filter rules to determine if the rules behave as expected.
Always Test:
- Answers that should pass the filter rules
- Answers that should NOT pass the filter rules
You will want to test other things based on your specific filter rules and the use of your form. It is best if questions referenced in filter rules have pre-defined answers (dropdown, radiobutton, multi-select, Yes/No), as it is impossible to predict all potential typos/errors made by mobile users and to build a regular expression to accommodate them.
Uses of DREL
Most fields that you can enter DREL Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms. in will show sample text underneath the field as you are configuring it, so make use of this. For example, if %u[name] is entered in the field, the sample text should list a "sample" username -- if it doesn't, something has been entered incorrectly.
Data Destinations might use DREL in a number of places:
- Folder Expressions
- Filename Expressions
- Email Subject Lines
- Pushing data to specific fields
- And more...
Any question referenced in DREL should be marked as "Required" in the form, particularly if it is the only field in the expression; if a filename expression ends up empty, for example, the transmission of data to most destinations will fail. Test that this cannot happen in your forms.
Data Types
Some Data Destinations push data from a selected TrueContext field to a specific field in the destination service. Salesforce Data Destinations require this, for example. Salesforce has validation set on many of their fields -- an email field will only accept a correctly formatted email, and an integer field will only accept numbers. If data pushed to Salesforce doesn't match the validation, no record will be created in Salesforce. For these Data Destinations, and others that push to services that use validation, it is best to ensure that the TrueContext data type matches the validation. Be sure to test the form and make sure that users cannot enter anything into these fields that the destination service will not accept.
Viewing Execution Details
Once forms linked to the Data Destination have been submitted, there are a few ways that Admin users can view execution details.
Data Destination Execution Statistics
-
Hover over Manage Forms, confirm that you are in the desired FormSpace, and select Data Destinations.
-
Select a Data Destination.
Result: The Data Destination Configuration page opens.
On the right side of the Data Destination Configuration page is an Executions table. This table shows the state and number of form submissions (limited to the past 30 days to optimize performance).
Active: The number of Data Destination executions in process.
Successful: The number of Data Destination executions that were successful.
Skipped: If a Data Destination has been "skipped," a form submission failed to save properly, and the Data Destination was not processed. This can occur for a number of reasons; contact TrueContext support for troubleshooting help.
Filtered: The number of Data Destination executions with submitted data that did not meet the filtering rules.
Failed: The number of Data Destination executions that have failed.
-
Select an execution state to open the Data Destination Executions page that lists the executions with that state. You can then use Search Options to list executions for a different date range and apply other filters. The topic View Data Destination executions provides more details on the various search options.
Form Submission Processing Details
To see more detailed data on each form submission, navigate to the Data & Analytics tab in the main menu, and select All Form Activity. All submitted forms will be listed; if a data destination execution failed there will be a red "X" icon beside the name. Select the form submission reference number to view details.
Form Submission Processing
The Form Submission Processing table outlines in order each action performed by the TrueContext server as it processes the data. Note that this table does not include any information about processing/handling of the data in the mobile app before the form was submitted.
The standard processing steps are as follows:
- Save Data: Saves the data to the server. The subsequent steps will not be completed if "Save Data" fails. Contact our support team if this step fails.
- Resolve Geo Address: Will be skipped if no geolocation was collected by the device and attached to the form.
- Process Images: Reading of images collected with the form. Will be skipped if no images are attached. If this step fails, the subsequent steps can still process.
- Data Destination: A new row will be listed for each Data Destination linked to the form. If one Data Destination execution fails, the others can still execute.
Symbols: Processing Status
- The step has been successfully processed.
- The step has failed. See details for more information.
- The step has been skipped. This usually happens because the step is not applicable.
- The "Process Images" step will be skipped if there are no images in the form.
- A Data Destination execution will be skipped if the form submission does not meet the Destination's filter rules.
Troubleshooting Data Destinations
Skipped
A Data Destination execution will only show as "skipped" if the submitted data does not meet filter rules. Either adjust the filter rules or change your source data so that it will meet filter rules. Details will be provided about the string that is being filtered. In the sample below, the question referenced in the filter rule is not returning a value, causing the email Data Destination to skip executing, and not send an email.
Failed
Occasionally, a Data Destination will fail due to a glitch or a momentary outage in either TrueContext or the external service the destination is linked to. Sometimes simply re-executing the failed execution (see below) will resolve the issue.
The error causing the problem will be listed in the "details" column of the form submissions processing table. The messages listed can vary widely but are typically reasonably descriptive and make the cause quite clear. One common problem is security solutions such as firewalls blocking TrueContext IP addresses. If you are uncertain of the cause, feel free to contact TrueContext Support and we will look into the details of the error for you.
Re-Executing a Failed Execution
How automatic re-executions work
When a Data Destination fails, TrueContext automatically re-executes the Data Destination. TrueContext stops re-executions when
-
the execution succeeds, or
-
the execution fails 30 consecutive times, or
-
the related form submission is removed from the TrueContext system according to Form Submission Retention and Deletion guidelines.
When the system re-executes a Data Destination, it either
-
follows the third-party app re-execution strategy, or
-
follows an exponential backoff process. This means that it re-executes in increasingly long intervals of time. This avoids overloading the TrueContext system.
The following diagram describes how TrueContext re-executes Data Destinations that fail.
Note:Every time a Data Destination re-execution fails, the system notifies all Problem Contact Email addresses for the team.
How to stop automatic re-executions
You can stop automatic re-executions in any of the following ways:
-
Fix any issues in the third-party system.
-
Go to the Form Submission Details page. Select the option to DISABLE AUTOMATIC RETRIES in the Form Submission Processing section.
-
Delete the submitted form.
Automatic Re-Executions and the Data Passthrough Feature
When using the Data Passthrough feature, automatic re-executions are limited. Please see the Data Passthrough overview for more information.
Manually Re-Execute a Failed Execution
A re-execution can be initiated manually through the TrueContext Web Portal as well. This can be useful after correcting configuration issues with a Data Destination, to test if the changes are effective (or if it is simply inconvenient to wait until the next automatic execution attempt).
Navigate to the desired Data Destination and select “Re-execute Failed Executions” to re-process all failed form submissions associated with the Data Destination.
You can also re-execute the single failed step in an execution; select the desired form submission name, then mouse over the desired step. A “re-execute” icon will appear to the right.
Set Up Failure Notification Emails
If a form submission fails to reach the Data Destination after (by default) three attempts, TrueContext will send an email to the Problem Contact Email Addresses. You can adjust this default in the Data Destination Basics tab of the destination configuration.
