When you enable data sync for a record type, the record type caches your source data in Appian. To keep your synced data up-to-date with the source, an immediate sync occurs whenever Appian writes to the source of your data. You can also schedule daily syncs so your data is synced at least once a day.

However, sometimes record types fail to sync to the source. When this happens, you can use the information in this page and in the error messages found in the monitoring view to resolve issues with sync.

This page explains the different types of errors that can occur, and troubleshooting steps for sync failures due to:

• Mismatched schemas
• Invalid value in a source row field
• Invalid credentials
• Data source exceeds the row limit
• Sync timeout
• Web service errors
• Other sync errors

Types of sync errors

When an error occurs during a sync, the record type will either have a sync status of Failed, Failed and Skipped, or Failed and Retrying. The type of error that occurs will determine the sync status on your record type, and whether or not the record type is available. It's important to understand which errors cause each status so you can determine how to address them.

Failed sync

You may see a Failed sync status on your record type when there is an error syncing data as a result of a record type save, an immediate sync, or an error in deployment. When a failed sync occurs, references to the record type will be temporarily unavailable. This means that a!queryRecordType() will not return data, the record list will be unavailable, and any grids or charts that use the record type may return an error.

This behavior can also occur when using related records. For example, suppose a query returns data from the Customer record type, which is related to an Order record type. If the Order record type has a sync status of Failed and the query includes fields from Order, the query will also fail.

Usually the best way to resolve failed syncs is to identify the problem and perform a full sync from the record type or the Monitoring view. When viewing the record type, failed syncs will display with a link to an error message with more details. See the section for causes of sync errors to find methods to resolve common errors.

Failed and skipped sync

In other cases, you may see a sync status of Failed and Skipped. You can configure a record type to skip failed syncs that occur during manual syncs, scheduled syncs, or syncs from an import customization file kicked off during a deployment. By default, this setting is enabled on all new record types.

When a failed sync is skipped, the record type will remain available and use data from the last successful scheduled sync. This means that any queries to the record type will succeed. However, since the sync was skipped, the data may be outdated. To investigate the cause of the sync error, click the link on the sync status in either the record type or the Monitoring view.

Failed and retrying

There are some instances where a sync can be automatically retried if an error occurs. When the sync is retrying, the sync is still considered in progress and the data for the record type is still available.

There are two ways that a retry occurs: retrying the entire sync or only retrying a single batch.

Full retry

When the entire sync is retried, the sync starts over from the first batch after a delay of a few minutes. A full retry can occur when some intermittent issues occur such as connection timeout with the source system. The retry occurs automatically, and the status while retrying will show as Failed and Retrying in the sync history grid during a retry.

Batch retry

When performing a full sync (all syncs other than an immediate sync), data is queried in batches, all of which must finish for the sync to succeed.

In some cases, an intermittent error occurs that only affects a single batch. For instance, a record type that uses a web service as the source could have a request time out for a single batch, even if prior batches succeeded. Appian will automatically retry the failing batch. If the automatic retry succeeds, Appian will continue with the remainder of the sync.

The sync will fail or be skipped if either of the following occur:

• A single batch fails three times in a row. A failed batch is automatically retried after a brief delay, up to a maximum of two retries. If the second retry (the third total attempt) fails, the entire sync fails.
• More than 10 failures occur across the entire set of batches in the full sync. For example, say there are 30 batches in a full sync. If there are 10 total retries across any number of batches, then the entire sync fails.

The Sync History only shows information about the last failed batch. However, any failure is logged in the application server log to aid with additional troubleshooting.

Sync failure alerts

When an error occurs that causes the sync to fail or skip, an email alert will be sent to system administrators, and any users with Administrator permissions on the record type. The email will contain a summary of the issue and a link to the record type so you can quickly resolve the issue.

Causes of sync errors

Mismatched schemas

When you enable data sync for your record type and configure your record fields, Appian automatically creates a mapping between the source schema and record type schema. The source schema includes the names, types, and uniqueness constraints of all the fields in your source. This schema must match the record type's schema in order for Appian to sync the source data.

Resolution steps

If a change is made to the source schema without making a corresponding change to the record type, the record type will fail to sync. There are three common causes for a mismatch between the two schemas.

• The data type of a source field was changed
• The name of a source field was changed
• A source field was deleted.

To update the mappings for any of these scenarios, follow these steps:

1. Open the record type and go to Data Model. There will be a banner at the top of the page indicating the number of record fields that are not properly mapped to a source field.
2. Click UPDATE MAPPINGS. An Update Mappings dialog will appear.
3. In the Source Field column, choose a source field from the dropdown. If there is a matching source field name, the column will auto-suggest the source field for you. Note that a source field can only be mapped to one record field.
4. The Record Field Type column will reflect the Appian data type of the source field. If the data type of the source field changed, the original data type will display with an arrow pointing to the updated data type of the new source field.

5. To remove a record field and its source field, click the delete icon.

   Removing a record field will cause any existing field references to break. To see which objects reference a record field, click next to the record field on the Data Model page of the record type.

6. To remove all unmapped fields, click REMOVE ALL UNMAPPED FIELDS.
7. Click OK on the dialog.
8. Click SAVE CHANGES at the top of the Record Type Designer. Upon clicking save, a sync will run.

You can also use this mapping tool if you need to change the database table or Salesforce object that backs your record.

Invalid value in a source row field

When data is entered into your source, it's possible to enter values which aren't compatible with data sync. This means that the value in a source field may work fine in your source, but may not be a compatible value for that field in Appian when data sync is enabled.

This most commonly occurs with date fields and date and time fields. Appian has a certain range that all date and date and time values must be within in order for the source data to work with data sync. This range may not be the same range that is accepted by the source; so it's possible that a value can be valid in the source's range but not in Appian's. If the value of a date or date and time field isn't within the range allowed by data sync, the sync will fail.

This specific error message appears when the value of a date and time field in the source is outside of the range of date values that work with data sync. To resolve the error, find the field with the invalid date and time value, update the value so that it is within the valid range, and then resync the record type to the source.

Resolution steps

Date and time value in a database

To update the invalid date and time value in the database table:

1. In the error message, copy the issue identifier.
2. Go to the APPLICATIONS View.
3. In the Navigation menu, select System Logs.
4. Open Application Server Log and search for the issue identifier.
5. Read the stack trace to determine which field and value caused the error. Example error: APNX-3-1100-007: marshal: unsupported timestamp 3000-01-01 00:00:00 +0000 UTC
6. Open the SQL Workbench or phpMyAdmin for the database.
7. Run a SQL statement to find the date and time field with the invalid value. Example SQL statement:

   1
      SELECT * FROM `< table name >` WHERE date(< field name >) = `< the invalid value >
   

8. Update the invalid field value so that it is within the valid range.
9. Go back to the APPLICATIONS View and click MONITORING.
10. Go to the RECORD SYNC STATUS tab.
11. Select your record type and click START SYNC.

Date and time value in Salesforce

To update the invalid date and time value in Salesforce:

1. In the error message, copy the issue identifier.
2. Go to the APPLICATIONS View.
3. In the Navigation menu, select System Logs.
4. Open Application Server Log and search for the issue identifier.
5. Read the stack trace to determine which field and value caused the error. Example error: APNX-3-1100-007: marshal: unsupported timestamp 3000-01-01 00:00:00 +0000 UTC
6. Login to Salesforce.
7. Update the invalid date and time field value so that it is within data sync's valid range.
8. Go back to the APPLICATIONS View and click MONITORING.
9. Go to the RECORD SYNC STATUS tab.
10. Select your record type and click START SYNC.

Invalid credentials

When you set up your Salesforce object as the source for your record type, you have to provide login credentials in order to access Salesforce. If the Salesforce object's credentials are determined to be invalid at the time of the sync, your sync will fail. It could simply be that the password has expired or that the credentials have changed. In order to successfully sync, you need to verify the credentials and re-sync the record type.

Resolution steps

To check the credentials and re-sync:

1. From the APPLICATIONS View, open your Salesforce object for your record type.
2. Verify that the credentials use the username-password OAuth authentication and are correct.
3. Click TEST CONNECTION. If the test fails, contact your system administrator for help. If the test passes, continue to step 4.
4. Click SAVE.
5. From the APPLICATIONS View, click MONITORING.
6. In the gray bar menu, click RECORD SYNC STATUS.
7. Select your record type and click START SYNC.

For more information on authentication, credentials, and configuring a Salesforce object, see Salesforce Connected Systems.

Data source exceeds the row limit

With data sync, a record type object can sync up to 1,000,000 rows of data from a selected source. This limit applies to new rows of data introduced by an immediate sync.

If you try to sync more than 1,000,000 rows, the sync will fail and the record type will be unavailable. Sources within 10% of the limit (900,000 to 1,000,000 rows) will sync successfully, but a warning will let you know that the source is approaching or has reached the row limit.

Mitigation steps

To keep your source from exceeding the row limit, apply one or more source filters to limit the number of rows cached in Appian from the source. If the source is expected to regularly exceed 1,000,000 rows, you may choose to disable data sync.

To disable data sync, you will need to change the data source from the record type's Data Model and update all references to the original record fields throughout your application.

To find specific field references in your environment:

1. Find an instance of a reference that you need to replace.
2. Comment it out by wrapping the reference in /* and */.
3. Copy the string and go back to the APPLICATIONS View.
4. In the header bar of the APPLICATIONS View, click OBJECTS.

5. In the OBJECTS View, paste the string into the search box under DESIGN OBJECTS.

   You can search for multiple strings at once by separating each string with a space.

6. Next to the search button, click the down arrow and select Expression.
7. Click the search icon.

Every object that references the string will appear in your search results. Once you have located all the references in your objects, update the field references. For updating field references in interfaces, we recommend updating the references in Expression Mode.

Sync timeout

If you're performing a full sync (all syncs other than an immediate sync) that takes longer than 4 hours, it's possible that the sync will time out and fail. When the sync fails, the record type will become unavailable and you'll see an alert message that says "The sync failed because it exceeded the 4 hour time limit."

A sync timeout can occur on any record type with data sync enabled, but may be more common on synced record types that use a web service as the source.

Mitigation steps

To prevent a sync from timing out, consider:

• Removing the rate limit to reduce the total sync time.
• Allowing for larger batch sizes.
• Adding a source filter to limit the number of rows synced in Appian.
• Refactoring the source system to be more efficient.

If you cannot modify the above configurations, or your record type uses a database table as the source, you may choose to disable data sync on your record types that take longer than 4 hours to sync.

To disable data sync, you will need to change the data source from the record type's Data Model and update all references to the original record fields throughout your application.

To find specific field references in your environment:

1. Find an instance of a reference that you need to replace.
2. Comment it out by wrapping the reference in /* and */.
3. Copy the string and go back to the APPLICATIONS View.
4. In the header bar of the APPLICATIONS View, click OBJECTS.

5. In the OBJECTS View, paste the string into the search box under DESIGN OBJECTS.

   You can search for multiple strings at once by separating each string with a space.

6. Next to the search button, click the down arrow and select Expression.
7. Click the search icon.

Every object that references the string will appear in your search results. Once you have located all the references in your objects, update the field references. For updating field references in interfaces, we recommend updating the references in Expression Mode.

Web service errors

When you use a web service as the source of a record type with sync enabled, the web service itself could return an error. For instance, the web service could be temporarily unavailable or the request from Appian may not be structured correctly.

When these errors occur, the Monitoring View can display the error received from the web service to help in troubleshooting. However, the source expression must be set up correctly to expose these error messages to the monitor.

Configuring web services to expose error messages

In the source expression rule, each batch result must return a list of dictionary, map, or CDT to perform a successful sync; any other result will cause the sync to fail.

However, if the expression rule returns a result of type Integration Error in a batch, the batch will fail and the full details of the integration error will be displayed in the Monitoring View for the record sync.

The Integration Error data type returns details on the error that occurred with any integration call. It is returned by default in any integration response using the error parameter. See below for an example on how to configure the source expression to return the integration error.

Since the integration error typically contains the error received from the web service, it can help troubleshoot issues for the batch that failed.

Example source expression with integration error

To provide the integration error in a failed batch, make sure the source expression returns the appropriate integration error. For example, the following source expression would return the results if the integration succeeds and the integration error if it fails.

1
2
3
4
5
6
7
8
a!localVariables(
  local!integration: rule!EX_IntegrationResult(batch: ri!batch),
  if(
    local!integration.success,
    local!integration.result.body, /* Returns the result body when the request succeeds */
    local!integration.error /* Returns the integration error when the request fails*/
  )
)

Resolution steps

Check the integration error against common HTTP errors and update the configuration of the integration object to resolve the error. For example, an error code of 401 typically means that the request did not have the correct authentication, so the credentials may need to be updated.

In some cases, it may be necessary to contact the owner of the web service to troubleshoot further.

Other sync errors

Sometimes record types fail to sync to the source because of issues that require troubleshooting outside of Appian. When this happens, check the error message for information to help you troubleshoot the issue or contact your system administrator for further assistance. Here are a few brief explanations of these issues and their possible causes: