Table of Contents
Overview
Merge Duration
Merge Order
Merge Settings
Integration Pipeline
Reasons For Errors
Identifying Errors - Merge Reports
Related Articles
Overview
Coursedog executes a complex system of integration functions every night to sync the Coursedog system with your SIS.
We both GET data out of the SIS and POST updates back through REST API endpoints.
Every school for which an SIS integration has been set up will have their integration functions executed on a nightly basis.
Merge Duration
Start and end time can vary; if you have any questions about the merge duration for your institution, please reach out to Coursedog.
When a nightly merge ends depends on a variety of factors, including the time it starts, whether or not the institution or SIS is undergoing maintenance/backup, whether or not your institution consists of multiple schools, and whether your nightly integration queue is not progressing due to issues in other instances.
When the merge is running, users will see a message indicating that a sync is in progress.
It is not common, but occasionally nightly merges do run into business hours.
Merge Order
Merges are executed in a specific order as defined by the dependencies between different elements (sections before courses, etc.). When a single institution has multiple schools, execution functions are run in batches, so the order in which the function starts is not necessarily the order in which it is completed.
Merge Settings
Overview | Default Source of Truth Options | Execute Merge
PATH: Integrations Hub > Global Settings
Overview
Merge settings are configured during implementation and tailored to your institution’s needs. Contact your Customer Success representative for any adjustments.
What you see below is a general overview; please work with your Customer Success representative to confirm the correct settings for you. They will work with a data engineer (DE) to modify as needed.
During implementation, your Coursedog team will enable all relevant merge types for nightly merges.
The “Source of truth” defines the logic for handling merge conflicts.
You can review the source of truth on each of your fields on your templates (course template for Curriculum, section template for Scheduling). Learn more here.
Default Source of Truth Options
Each option is outlined below; if you wish to see the potential outcome(s) for any of these settings, check out Integration Outcomes Based on the Defined Source of Truth.
Manual Resolution | Resolve as Coursedog | Resolve as Institution
Always Coursedog | Always Institution
Manual Resolution
If there is a conflict, stop the integration for that object and return an error.
This option isn’t recommended for any use cases.
Resolve as Coursedog
If there is a conflict, take the value from the Coursedog system as the source of truth.
Use this setting if a data type exists in both Coursedog and the SIS but it is maintained in Coursedog (and therefore you know that Coursedog is always the most current).
This is useful for bidirectional integrations where we can pull information from your SIS; store it in Coursedog; edit it in Coursedog; and then post back to the SIS.
There are many potential use cases for this – essentially, any field that exists in both your SIS and Coursedog but that is maintained in Coursedog.
Resolve as Institution
If there is a conflict, take the value from the SIS as the source of truth.
Always Coursedog
Take all values from Coursedog (this is the same as not having the integration on at all).
Use this setting if this data type doesn’t exist in the SIS. This will help prevent data from being wiped in a merge.
A potential use case for this setting would be department dynamic steps, requirement levels, Course Ids, Section Numbers, and Last Edited At Relationship Fields. Other example use cases are outlined here, here, here.
Always Institution
Take all values from SIS.
Execute Merge
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 initiate a manual merge via the Integrations Hub under the Execute Merge tab, with this protection turned off. Learn more here.
Integration Pipeline
Every night when the integration is run, the following occurs:
We first GET all the school data and run it through our internal data verifier. If there is a verification error, we return an error and stop the merge.
We then GET all of our data.
We GET a copy of the previous night's data (stored in our data backups) which represents the last successful merge.
We execute a three-way merge because we use three data sources to execute the merge. The three sources being: the institution’s data, Coursedog’s data, and yesterday’s version of the data.
After executing the merge, if any merge conflicts exist, we store the merge conflicts as errors and stop the merge for all objects that had a conflict. For all other objects, they continue to the next phase.
If the institution has POST APIs set up, the POST APIs are executed.
After the POST APIs, we GET the institution’s data again because the SIS sometimes adds IDs or other fields to the data, and we want to make sure we have those updated IDs.
If there were no issues with the POST APIs, we take the new version of all objects and store it in our database.
We send out a merge report email.
Reasons For Errors
The following issues can lead to errors with a nightly merge:
SIS servers down
API middleware down
GET endpoint returning multiple objects with the same ID
Verification Error
Merge Conflict
POST API Error
Identifying Errors - Merge Reports
The easiest way to review merge errors is through your Integrations Hub.
On the overview page in the Integrations Hub, you’ll see a full list of all bidirectional entities (sections, courses, etc.) that are currently in an active error state. You can review and resolve these one by one here.
Merge errors can also be reviewed in the Integrations Hub under Merge History, via email notifications, or on relevant dashboards (e.g., Scheduling or Section).
For issues you are unable to resolve, please submit a ticket through Freshdesk or contact your Customer Success Manager.