Most itslearning customers utilise a Student Information System (SIS) that can automatically synchronise user data as well as groups and courses with itslearning. This article describes the status email available from the IMS Enteprise XML based imports.
Please note that for IMS Enteprise Services API based integrations, logs are available for system administrators on the site.
Please see here for more information the available SIS integrations.
Please note that if your integration is configured to run so called delta imports, their status emails have similar contents but instead of one email per import, the summary is sent every 24h hours.
Who receives these emails and when?
The email is sent to recipients registered by itslearning to be responsible for the integration. This should always include the system administrators for the itslearning site so they are aware of what is happening with the integration. Also it is the system administrators that should contact our support team in case of anything. The recipients can also include a technical contact. We recommend reviewing the recipients at least annually with your itslearning account manager, since the information can be critical.
The email is sent by every import attempt, i.e. both successful and failed attempts. Conversely, not receiving any status email means the import has not attempted to run. Usually this is because the data has not arrived at the itslearning servers for some reason. If this is unexpected, please check the integration on your side wherever possible and then contact itslearning support.
High level contents of the email
The most important information is already in the title of the email: whether the import was successful or not.
- Import finished with status Failed: for some reason the import failed
- Import finished with status Completed: import successful
In both cases, you will see a summary and more information about the import.
The email will also give you the high level numbers on the various types of data elements, both before and after the import:
- persons: users with various profiles, i.e. students, teachers, carers
- groups: groups of various types, i.e. courses and other
- memberships: memberships of persons in the groups. These numbers are typically high, and also hard to relate to
- relationships: connections between carers and children in the data. If no carers are imported, this will be 0
We store these emails for a limited number of days, so it is important to react to failures or unexpected results fast.
Why would an import fail?
The most common reason for import failure is that the file contains too many changes compared to the previous import, in relation to the defined protection limits. In this case, you may read something like this at the end of the message:
06:03 To many group changes. aborting import
06:03 Import got exception To many group deletes: 48%. Max allowed: 20%.At the beginning of the school year or term, this is perfectly normal as groups from the previous year or term would be deleted and new ones created. Expected changes like this are of course also possible in the middle of the academic year or term. The exact value for what level of changes are let through is customisable and should be adjusted to a level that is appropriate; it is however important that there is a limit, to prevent unexpected or accidental changes or deletes.
When an import has failed, please review the report and make sure the cause is expected. Then, as an itslearning support contact, you can ask our support team to let the import run without the protection filter.
In addition to deletes, the import can fail because of updates either on persons or groups. These happen typically if many users for example get new emails imported, or if group names are changed in the source system.
Other possible reasons for the import to fail is that the XML file is not valid for some reason. If this is a file you or your IT department has access to, one way to check it is to open it as a file in a browser. The browser will give an error message if the file is broken in any way. In a Linux environment, you can verify the file with the xmllint program.
For any other reasons, please reach out to our support team.
Details of the status message
In case of a successful import, the email first describes the different steps of the import as well as the number of files to be imported and their names. (See here for a more detailed technical description of the process.) The email also tells you how many "duplicates" exist in the data - these are usually quite normal to see in the data as for example same persons may be added more than once.
Next, the email summarises the contents of the import, for example:
07:01 Summary of changes to data:
Before this import there were 29165 persons, 16998 groups, 189614 memberships and 0 relationships.
After this import there are 29483 persons, 24447 groups, 552444 memberships and 0 relationships.
Positive person changes: 1%
Positive group changes: 44%
Positive membership changes: 192%
Positive relationship changes: 0%
Negative person changes: 0%
Negative group changes: 0%
Negative membership changes: 1%
Negative relationship changes: 0%
Total person changes: 1%
Total group changes: 43%
Total membership changes: 191%
Total relationship changes: 0%Here you can see the numerical and percentage changes compared to the previous import.
Next, the import explains in more detail what operations it performs, and how they succeed. The first set of numbers is the time - if the amount of data to be imported is large, the import may take a while.
07:01 Total person updates: 49.
07:01 Total person inserts: 443.
07:01 Total person deletes: 125.
07:01 Total relationship updates: 0.
07:01 Total relationship inserts: 0.
07:01 Total relationship deletes: 0.
07:01 Total groups update: 12432.
07:01 Total group inserts: 7512.
07:01 Total group deletes: 63.
07:01 Total membership update: 3107.
07:03 Total membership inserts: 365407.
07:03 Total membership deletes: 2577.
07:03 End filtering data and adding to queue.
07:34 Items completed ok: 389476.
07:34 Items completed with warning: 2229.
07:34 Items completed with error: 10.
07:34 Persons completed ok: 528.
07:34 Persons completed with warning: 88.
07:34 Persons completed with error: 1.
07:34 Relationships completed ok: 0.
07:34 Relationships completed with warning: 0.
07:34 Relationships completed with error: 0.
07:34 Groups completed ok: 20005.
07:34 Groups completed with warning: 0.
07:34 Groups completed with error: 2.
07:34 Memberships completed ok: 368943.
07:34 Memberships completed with warning: 2141.
07:34 Memberships completed with error: 7.
07:34 Mentor memberships completed ok: 0.
07:34 Mentor memberships completed with warning: 0.
07:34 Mentor memberships completed with error: 0.
07:34 Import endedIn this last section you should pay attention mainly to the number of errors. In the example above, errors occurred in the data of one user, two groups, and seven memberships. (Membership errors are usually caused by errors in either the user or the group.) For a more detailed error log, please contact our support team.