SIS Integration – IMS Enterprise Import Status Emails (Sysadmin)

TABLE OF CONTENTS

• 1 Overview
• 2 Import Status Quick Reference
• 3 Who Receives These Emails and When
• 4 High-Level Email Contents
  • 4.1 Import Status
  • 4.2 Data Element Counts
• 5 Why Would an Import Fail
  • 5.1 Too Many Changes (Protection Limits)
  • 5.2 Person or Group Updates
  • 5.3 Invalid XML File
• 6 Details of the Status Message
  • 6.1 Import Steps and Duplicates
  • 6.2 Summary of Changes
  • 6.3 Detailed Operation Counts

1 Overview

Most itslearning customers use a Student Information System (SIS) that can automatically synchronise user data, groups and courses with itslearning. This article describes the status email available for IMS Enterprise XML based imports.

See the available SIS integrations for more information.

2 Import Status Quick Reference

The following summarises the most important actions related to these emails.

3 Who Receives These Emails and When

The email is sent to recipients registered by itslearning as 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. It is also the system administrators who should contact itslearning support in case of any issue. 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 for every import attempt, both successful and failed. Conversely, not receiving any status email means the import has not attempted to run. This is usually because the data has not arrived at the itslearning servers for some reason. If this is unexpected, check the integration on your side wherever possible, then contact itslearning support.

4 High-Level Email Contents

4.1 Import Status

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: the import was successful

In both cases, the email includes a summary and more information about the import.

4.2 Data Element Counts

The email also gives high-level numbers for the following data element types, both before and after the import:

5 Why Would an Import Fail

5.1 Too Many Changes (Protection Limits)

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 see 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%.

When an import has failed, review the report and confirm that the cause is expected. As an itslearning support contact, you can then ask itslearning support to let the import run without the protection filter.

5.2 Person or Group Updates

In addition to deletes, the import can fail because of updates to either persons or groups. This typically happens when many users get new email addresses imported, or when group names are changed in the source system.

5.3 Invalid XML File

Another possible reason 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 shows 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, contact itslearning support.

6 Details of the Status Message

6.1 Import Steps and Duplicates

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 the technical description of the process for more detail.) The email also states how many duplicates exist in the data. These are usually normal to see, since for example the same person may be added more than once.

6.2 Summary of Changes

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.

6.3 Detailed Operation Counts

Next, the import explains in more detail which 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 ended

In this last section, 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, contact itslearning support.