Table of Contents
Overview
Merge Error Types
Best Practices
When to Submit a Ticket
Ways to Review Merge Errors
Troubleshooting Errors
Related Articles
Overview
This article captures an overview of merge error types; merge error best practices; determining when to submit a support ticket; as well as ways to view integration errors.
Merge Error Types
Unique to SIS | Shared Across Multiple SISs | General Integration Failure
There are a few different categories of merge errors. They can be specific to your SIS; issues shared across multiple SISs; and general integration failures.
Unique to SIS
These are documented, by each available SIS, here. These guides can be downloaded and printed for your convenience.
Shared Across Multiple SISs
Some of the more common issues are noted here.
General Integration Failure
These are different from merge errors caused by the specific data or contents of a merge.
Network, infrastructure, system, load, and several other external factors can cause instability and integration failures.
Persistent integration difficulties should be discussed with your Coursedog Customer Success Manager, Coursedog Support, your integration provider, and your internal IT infrastructure team.
Best Practices
Prevention
As you work through merge error resolution, identify any trends or common issues/mistakes being made.
Fortify your instance to prevent the merge errors in the future. You can do this by:
Creating Section Rules that will prevent section submission with error-causing issues. Learn more here.
Updating your Section Template to provide better guidance and enforce SIS requirements with end users.
Use Extended descriptions (guidance, examples, lists, links).
Use “required,” “editable,” etc. settings to enforce.
Define “minimum”, “maximum”, and “not allowed” characters.
Use defaults (default from Course or Term).
Learn more about configuring templates here.
Resolution
Monitor your merge error reports regularly (after nightly syncs or once a week during active scheduling) to catch and resolve these issues. Learn more about merge reports here.
Admins and Super Admins should also have the "View Section Integration Status" permission enabled (under Roles) in order to take advantage of viewing the Integration Errors report in the Reporting console.
If your institution is operating with real-time or nightly merges:
Admins should manage and resolve merge errors as regularly as possible during active scheduling phases.
Pull merge reports daily or weekly and resolve all merge errors as they come in.
When the scheduling phase is complete, ensure you have allowed at least 1-3 weeks between the scheduling phase end and the necessary/target date for final posting to the SIS to allow for resolution of any final merge errors.
If your institution is operating with manual merges:
Execute manual merges regularly and resolve errors throughout the active cycle and allow 2-3 weeks between final schedule submission and final posting to SIS for merge error resolution.
You will need to merge the schedule, pull the merge error report, resolve all, and then merge again.
When to Submit a Ticket
Integration Errors Dashboard
Submit a ticket if there are sections in the Integration Errors Dashboard with errors that meet any of the below criteria:
You do not understand how to resolve the issue.
The resolutions are not trivial but are difficult or time consuming to resolve.
The mistakes could be prevented with rules and either:
You need assistance creating the rule or
There are gaps in the rule engine that prevent the rule from being created.
Nightly Synchronization Merge Report
Submit a ticket if your nightly merge report:
Contains an error.
The number of sections posted nightly doesn’t align with expectations.
The nightly merge is taking more than 4 hours to complete or is running too close to any SIS/DB nightly maintenance/outage windows.
The nightly merge report contains information that you don’t understand.
Merge Report Contains an Error
Number of Sections Posted Nightly Doesn’t Align with Expectations
Since real-time synchronization is ON, all sections that are edited will be posted in real-time and there should be few POSTs occurring nightly except for section deletes which are not posted in real-time and section edits that failed during real-time that get re-sent during the nightly merge. For example, it is not common for there to be more than 20 items sent to the SIS during the nightly sync. In the image below note that there are 406 which would normally represent an item for which you should submit a Freshdesk ticket.
In other words, if you see “Unable to sync some changes” and you aren't able to explain the discrepancy as outlined below, you should submit a ticket.
In nightly merges, updates won’t be sent to the SIS when there are more than 100 entities with changes (this is a protective measure to prevent unintended updates).
If you need to update more than 100 entities, you can run a manual merge with this protection turned off at Admin > Execute Merge.
If your merges are consistently triggering the threshold check, submit a support ticket so that Coursedog can evaluate raising the threshold. Learn more here.
Ways to Review Merge Errors
Overview | Integration Errors Dashboard | Merge Reports | Out of Sync Fields Dashboard
Section SIS Sync Tool | Merge Notifications (Daily Email) | Conflicts Reports | Exportable Reports
Section Dashboard Merge Notifications
Overview
Coursedog provides many tools to monitor and manage the synchronization with the SIS:
Integration Errors Dashboard – Used to identify sections with merge errors.
Out of Sync Fields Dashboard – Used to identify the complete set of field differences between Coursedog and the SIS
Merge Reports – View any/all integrations that have been run including nightly, manual and real-time as well as drill down into any issues.
Section SIS Sync Tool – Used to identify for a particular section what the differences are between Coursedog and the SIS. Allows you rectify differences on the fly.
Merge Notifications (Daily Email) – Used to identify if the overall merges are healthy and whether the system is in sync.
Conflicts Report – Used to hone in on specific rule violations that lead to and result in merge errors.
Reports – Allows you to export the list of fields that are out of sync with the SIS for all sections.
Section Dashboard Merge Notifications – Enables you to identify that a section has a merge error as well as view the error message and access the merge report.
We recommend using the Integration Errors Dashboard as the main tool to identify synchronization issues between Coursedog and the SIS.
Additionally, please review the nightly synchronization reports and file tickets for any concerns.
Integration Errors Dashboard
Overview
This is the most powerful, focused method for viewing integration errors and allows clicking on any row to access the section directly to rectify the issue.
We recommend checking the dashboard daily as the primary mechanism for managing sections with integration errors.
You can access the Integration Errors Dashboard at Academic Scheduling > Reports > Integration.
Comparing with the Nightly Merge Report
The number of “failed to sync” sections in the nightly merge report will match what you see in the integration errors dashboard.
Nightly Merge Report
Integration Errors Dashboard
Merge Reports
Overview | How It Works | Downloading the Merge Report
PATH: Admin > Merge Reports
Overview
This tool allows you to view any merges that have been done as well as identify any issues.
How It Works
Overview | Errors | Unable to Sync Some Changes
Overview
There are two things you are looking for in your merge reports: Errors and “Unable to Sync some Changes”.
Errors
If you encounter errors, file a ticket with Coursedog unless you know that your infrastructure was down during that period.
Unable to Sync Some Changes
If you see “Unable to sync some changes” you should be able to:
Glance at the number of “failedPostTransactions” and explain those by looking at the Integration Errors Dashboard.
Glance at the “totalPostTransactions”; if it represents the number of section deletes plus the number of failed sections during the realtime sync during the day, then all is well. If it doesn’t, then you should file a ticket.
Downloading the Merge Report
If there are only a few issues in the merge, you can see them right on the screen in the Coursedog user interface (UI).
If you are unable to see everything:
Download the merge report using the cloud icon on the right hand side.
Open the file in a tool like Notepad++ with the JSON Viewer plugin added.
In the download, you’ll be able to view the differences detected between Coursedog and the SIS that resulted in the POST operation.
You’ll also be able to see all errors that were encountered – these are the same errors you see in the Integration Errors Dashboard.
Out of Sync Fields Dashboard
PATH: Scheduling > Reports > Integration > Out of Sync Fields
This report shows a comparison of which section fields in Coursedog are out of alignment with fields in the SIS.
Section SIS Sync Tool
PATH: Scheduling > Reports > Integration > Out of Sync Fields
This feature allows you to see which fields in the section are out of alignment with the SIS.
You can live-edit the section in Coursedog or in the SIS and then hit “Refresh Comparison Data” to identify when the section in Coursedog is fully in sync with the section definition in the SIS.
Learn more here.
Merge Notifications (Daily Email)
Overview | Signing Up | Sample Emails
Overview
Users subscribed to merge notifications will receive a digest showing a summary of the real-time and nightly merges.
This push notification can be useful as a way to identify nightly integration issues.
When a user is added they will receive daily emails with an email body plus a pdf attachment.
The PDF will contain a link to “View on Coursedog” that takes you to the merge report for that item. Every real-time and all nightly synchronizations will exist as a row in the report. We recommend searching the report for the words “Finished With Issues” or “Error” to focus quickly on the merges that need attention.
Signing Up
Navigate to Admin > Merge Notifications.
Click “+ User”.
Type in the email address of the user who should receive merge notifications.
In the “notification setting” dropdown, select how frequently you would like to receive notifications: “send daily” (i.e. An email will be sent nightly after the automated synchronization executes) or “send if issue” (i.e. An email will only be sent when synchronization issues are encountered).
Sample Emails
Email Indicating a Successful Nightly Merge | Emails Indicating Merge Errors | Email Attachment
Once you are set to receive merge notifications, you will receive emails from Coursedog with details regarding the synchronization.
Email Indicating a Successful Nightly Merge
Emails Indicating Merge Errors
The two emails below capture four sets of merge errors:
2 out of 21 nightly merges did not succeed.
8 out of 35 realtime merges did not succeed.
1 of the 14 nightly merge errors was due to a fatal error persisting SIS and Coursedog data. Learn more here.
13 of the 14 nightly merge errors were due to being unable to fetch data from the SIS. Learn more here.
Email Attachment
Although the body of the email will summarize your report, it will also include a multi-page PDF attachment with additional information and direct links to Coursedog for more details concerning each merge.
Conflicts Reports
Overview
For any rule that is not OFF, you can run a conflict report to identify any section that is violating that rule.
Many rule violations, such as room double bookings, will result in merge errors.
How to Do It
Navigate to Scheduling > Reports.
Click on the “Conflicts” option on the left-hand navigation.
Use the multi-select dropdown to view conflicts for the rule(s) you wish to check against.
Exportable Reports
Overview
You can export a report of all conflicts detected in the current schedule as well as sections out of sync with the SIS.
You can learn how to export reports here.
Banner School Note
For the “Sections Out of Sync with SIS CSV” report to be useful for Banner schools, it is necessary to filter out the timeIndex related items since Coursedog does not sync that field with Banner, and it will raise false positives.
Section Dashboard Merge Notifications
You can view merge notifications from within the Section Dashboard.
If sections experienced issues, you will see a red icon next to it and/or its parent course (image 1 below).
The integration status for a section will appear under the status column (image 2 below).
You can click into the integration status to see the error and merge report (image 3 below).
Troubleshooting Errors
Go here for merge error FAQs and troubleshooting as well as links to all SIS-specific merge error guides.