This page details out error handling and troubleshooting in Exalate.
Exalate has a built-in error recovery mechanism that allows you to fix problems and resume the synchronization from the moment it fails.
Synchronization can fail at various levels 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 the error, the synchronization is paused at one of these error levels:
- issue level
- connection level
- Exalate application level
For instance, when Exalate detects a script error, the connection is then 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.
Errors Overview Page
In the Exalate admin menu, you can access the Errors tab to get an overview of 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 include the following information:
- error impact: affects either a certain issue or a connection synchronization. It may affect the whole instance as well.
- related connection link
- error type
- error detail message: provides a detailed description of what's wrong
- error stack trace: helps to find the root cause of an error
You can access the connection from the Error Details page to fix the script.
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.
Decrease Error Impact
Exalate allows you to decrease the error impact level.
If the error does not affect all the issues under sync, you may change the error impact to the issue level. The synchronization will be blocked only for this specific issue.
The example below shows how the impact column looks on the error list screen:
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 which brings up a pop-up window
- An email notification containing the error message
- A sync status highlighting that something went wrong
Sometimes you need to have a closer look at the synchronization scripts to find out what's wrong.
You can debug errors from the scripts when an error blocks the issue synchronization and requires Resolve and retry to run again.
Debugging can be used in the Outgoing sync(data filter) and the Incoming sync (create and change processor).
You can enable logging for the Exalate app. For example in Jira Server, the log file is stored in <JIRA-HOME>/log directory.
It doesn't block the synchronization and requires the processor changes to run again.
In order to find the cause of the error, we recommend that you take some basic troubleshooting steps:
Check if the error you're facing is already described in the troubleshooting section.
1. Check the Error Details to see the stack trace behind the error.
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.