Error Handling

Errors in Exalate

Exalate has a built-in error recovery mechanism that allows you to fix problems and resume synchronization from the moment it fails.

Synchronization can fail due to a variety of causes, such as:

• Network connectivity
• Authentication issues
• Configuration failures
• Compatibility problems
• Sync Rules/Script errors

When an error arises in Exalate, synchronization is paused to allow an administrator to rectify the problem and resume operations.

Depending on the type of  error, the synchronization is paused at one of these error levels:

• Entity level
• Connection level
• Exalate Application level

For instance, when Exalate detects a script error, the connection is  paused. All other synchronizations, which are not related to that particular Connection, can proceed as usual.

If there is an error such as a network connectivity problem, all Connections are paused until the connectivity problem is fixed. Exalate resolves network errors automatically. This means that the synchronization will be recovered automatically once the network connectivity problem is resolved.

If the Exalate App has a problem, the whole synchronization will be stopped.

In the Exalate admin menu, you can access the Errors tab to get an overview of all the errors.

Here you will see a list of the existing errors. An error overview includes an error summary description, its impact level, and the time when the error occurred.

You can also get to the Error Details page from here:

Error Details

Error details include the following information:

• Impact: The title (Issue, Relation, Warning, Node, Trigger) indicates the type of error occurring in the backend. This may impact  either a certain issue or a connection synchronization. It may also affect the whole instance.
• Connection: The link to the Connection in which the error has occurred.
• Error Type: The type of error.
• Error Detail Message: Provides a detailed description of what's wrong.
• Error Stack Trace: Helps to find the root cause of an error. 

To fix the script, you can access the Connection from the Error Details page.

At the very bottom, you can also check the local and remote replica values. They are displayed as a prettified JSON file.

Below you can see how the replica values look.

Resolve and Retry

Once the error is fixed, you can check to make sure the fix has worked and proceed with the synchronization. 

Use the Resolve and Retry button accessible from the error list to do that. 

Decrease Error Impact

Exalate allows you to decrease the error impact level.

If the error does not affect all the entities under sync, you may change the error impact to the entity level. The synchronization will be blocked only for this specific entity.

The example below shows how the impact column looks on the error list screen:

Ignore Related Sync

Exalate allows you to ignore errors related to the sync.

If the error is ignored, changes related to the sync will not be applied. If it is the first sync, new entities will not be created.

While the Ignore Related Sync operation can be helpful for dealing with temporary errors, it's essential to exercise caution. Not all errors should be ignored. Some errors might be related to critical data discrepancies or configuration problems that need immediate attention.

How to Set up Error Notifications? 

In Exalate, you can notify administrators in case an error is raised.

When an error arises, a notification will be sent out to either the exalate-administrators group (if configured) or to the Jira-administrators group. 

There are 3 types of notifications:

• The in-app notification brings up a pop-up window.
• An email notification containing the error message.
• A sync status highlighting that something went wrong. 

Notifications on Jira on-premise

Types of Notifications

1. Email Notifications
   

   Administrator(s) will receive notifications each time there is an error in the synchronization process.

   You can choose which users should be informed of an error.
   When an error is raised, a notification will be sent out to either the exalate-administrators user group (if configured) or to the jira-administrators group.

   You can configure a new group of exalate-administrators with the users who should be notified in case of an error.

   For more information, check out How to configure error notifications in Jira on-premise.

   
   
2. In-JIRA Notifications will result in a pop-up notification, which would be shown to admins until the error is resolved or the notification is closed.

Configuring Notifications on Jira

Navigate to Jira > Admin > Add-ons > Exalate > General Settings and enable desired notification type.

Notifications on Other Platforms

Types of notifications

1. Email Notifications
   

   Administrator(s) will receive notifications each time there is an error in the synchronization process. You can add users who should be informed of an error.
   When an error is raised, a notification will be sent out to the users, specified in the Exalate admin menu under the Exalate Notifications tab.
   
   
   

2. In-App Notifications will result in a pop-up notification, which would be shown to admins until the error is resolved or the notification is closed.
   Below you can see the pop-up notification.
   

Configuring Notifications on Other Platforms

In-app notifications are displayed by default.

Email notifications could be configured in the Exalate admin menu. Navigate to the Exalate admin menu> Exalate Notifications and add an administrator to receive email notifications.

Error Debugging

Sometimes you need to have a closer look at synchronization scripts to find out what's wrong. 

There are two ways to get feedback from the Exalate App:

• Exalate logging: it doesn't block the synchronization and requires the processor changes to run again. We discuss this in the next section.
• Debugging error from the scripts - blocks the entity synchronization and requires Resolve and retry to run again.

Debugging Errors from the Scripts

To get more details about values passed in a replica you can use debug.error method.

debug.error method

This method helps to raise an IssueTrackerException error with the value of the field which is not syncing.

It allows you to see the content of the replica and the issue (if applicable). This helps to get a better understanding of what stage the problem has occurred.

debug.error("String message")

For example, when you synchronize a custom field, but the issue on the receiving side is not updated and you don't see any error.

The script below shows how to throw an error with the custom field value stored in a replica.

Receiving side - Incoming sync

debug.error("customFields."Foo".value from remote side is: " + replica.customFields."Foo"?.value)

How to Get Only Debug Logging for the Scripts?

If you want to debug your scripts, then capturing all com.exalate logging is too much as it also captures all transport protocol details.

You can limit the logging to different levels:

• for only script logging use com.exalate.script
• for information on how scripts run use com.exalate.processor

For Exalate 4.2 and lower

• for scripts and information on how they run use com.exalate.processor
• for Outgoing sync(data filter) scripts use com.exalate.processor.jira.JiraCreateReplicaProcessor
  
• for Incoming sync for new issues(create processor) scripts use com.exalate.processor.jira.JiraCreateIssueProcessor
  
• for Incoming sync for existing(change processor) scripts use com.exalate.processor.jira.JiraChangeIssueProcessor
  

You can test how logging works by adding the code, provided below. It will add the 'Hello world' text to the log file.

//add a 'Hello world' to the logging
log.info("Hello world ...") 

You can also enable debug (temporary and permanent) logging in Jira on-premise. 

Error Logging

You can enable logging for the Exalate App. For example in Jira on-premise, the log file is stored in <JIRA-HOME>/log directory.

It doesn't block the synchronization and requires the processor changes to run again.

Troubleshooting the Errors

You have an error and you want to find the root cause of that error. We recommend that you follow some basic troubleshooting steps:

1. Check the Error Details to see the stack trace behind the error. 

The Error Details page helps to get more details about the cause of an error.
2. Check if the error impact can be decreased.

Exalate allows you to decrease the error impact in case the error affects only a specific issue. This will unblock the rest of the synchronization. So that you can troubleshoot this specific issue.

Check how to change the error impact for more details.
3. Resolve and Retry to resume the synchronization from where it was paused.

Once the error is fixed, use the Resolve and Retry button to proceed with the synchronization.

Why isn't a particular Field Syncing?

You don't have an error anymore but you realize that the field you want to send over to the destination instance isn't syncing. 

This can be because:

• The field is not being sent.
• The field is being sent but is not applied properly on the receiving side.

Solution

To check if the field is being sent:

• Make sure it is included in the Outgoing sync of the sending instance
• If you are using Jira Server, check for its presence on the remote issue tab.
• If you have an error, check the remote replica (available on the Error details)

To check if the field is properly applied on the receiving side:

• Make sure you are mapping it in the Incoming sync.
• For fields where there is a set of available options (resolution, priority, list custom fields, user fields) make sure you have the proper option on the receiving instance.
• You can throw errors for not unexpected cases to validate the behavior in an easier way.

An example of the Resolution field

1. Check if the Sync Rules have been configured properly. You can find more details in our guide on how to synchronize resolution in Jira on-premise and Jira Cloud.
2. If it didn't help, add the script below to the Incoming sync. This script helps to check whether the issue is caused by different Resolutions used on the remote side.
   It will raise an error if the Resolution is not found on your side.

if (replica.resolution == null || nodeHelper.getResolution(replica.resolution?.name) == null) {
  throw new com.exalate.api.exception.IssueTrackerException("Failed to find resolution: `${replica.resolution?.name}`".toString())
}

Steps to Follow when Exalate Node is Unavailable

Whenever the Exalate node can't be accessed by a user there is a set of recommended steps to follow:

1. Check out the Exalate node status at status.exalate.com 
   Here you can see the current node status as well as Scheduled Maintenance.
2. Check out status.cloud.google.com
   The Exalate status page doesn't always hold a reference to original incidents from Google cloud.
   If Exalate service is down it's worthwhile to check Google's own status.
3. Contact our support team
   If you can't find any information on the scheduled maintenance but still cannot access the Exalate node, please contact our support team for further troubleshooting.
   You can submit a support request to our Service Desk directly. Or just send an e-mail to support@exalate.com. This will create an issue on our JIRA Service Desk allowing for further tracking.