SIS Synchronization Troubleshooting

Common Problems with Student Information Systems (SIS) Synchronization and Their Potential Solutions

Now that you have started loading user records into Alma via the SIS Synchronization process, you will inevitably have to deal with errors and/or rejected records. The post-load summary reports that Alma provides (Admin -> Monitor Jobs -> History tab -> Job Category: Users) can be a good starting place to identify issues that need resolution. 

Some of the most common errors you will find are:

"Identifier of type XXX and value XXX is already taken AcrossInstitution in this feed"

  • Problem a): These type of errors (especially the "in this feed" variety), are usually the result of multiple "versions" of a user record existing in the same XML file. In these cases, a unique identifier from one user is matching with that of another user, but another piece of information, such as user group, does not match between the two. If there are 2 versions of a user (i.e. 1 for the faculty user group and 1 for the student user group) in the same file, Alma will load the first instance and reject the second.
  • Solution a): Make sure that the preferred user group is listed first in the file or some type of deduplication is done to remove the "unwanted" version of the user record prior to the file being uploaded. That means that these kinds of errors may still show up in the post load reports, even if nothing is necessarily wrong (in the scenario where both versions of the user remain in the file and you are making sure to load the preferred user group).
  • Problem b): It's also possible for this error to come up when there's only 1 version of the user record in the file, but there are 2 identifiers (primary ID and barcode, for example) that are using the same value. Alma does not allow duplicate identifiers on a record, even if the same identifier value is found in differently labeled fields.
  • Solution b): For the record(s) in question, make sure that no 2 identifiers are being assigned the same value in the XML file. If so, then you must change the value being assigned to the identifier that is not the primary ID.

"Identifier of type XXX and value XXX is already taken AcrossInstitution"

  • Problem: A unique identifier, such as an email address or NetID or barcode, for a user in the XML file is already taken by an existing Alma user and perhaps the primary ID does not match what's in the xml file for that user. This results in a rejection and the user's information will not be updated in their Alma user record. 
  • Solution: Using the offending record's identifier that triggered the error, consult Alma, your XML file and your student information system to search for an existing user that may have already been assigned the identifier and find out why a new user is trying to use it. A new unique identifier will most likely need to be assigned to the 2nd user (in the SIS and, therefore, the XML file) to prevent ALMA from continuing to reject it.

"Mandatory field is missing: (address line 1, address type, phone number, etc.)"

  • Problem: The field may be missing for several reasons. Sometimes a required field (CARLI-required and/or Institutionally required via User Registration Form) really is missing and needs to be populated in your student information system (and the resulting XML file) and sometimes the XML fields (often a stanza of fields) are present in the XML file for a certain field, but if the data isn't strictly required, Alma will reject the record because the XML fields are there with no data. 
  • Solution: Investigate whether the field in question is really required (Alma: Configuration -> User Management -> User Details -> User Registration Form) and if not, try to adjust any scripts that are in place to build the XML file to remove the XML field(s) that do not have data. If the data is required by your institution and is simply not in the source records (SIS) then that needs to be rectified at the source or some generic "place-holder" may be added via script (i.e. "0000000000" for a blank phone number, "123 Main Campus Bldg..." -a general campus building- for a blank home address).

"Could not parse file/s / 1 general errors"

  • Problem: This error can occur for a few different reasons:
    • The file has data (as small as a single character) that is not in the proper UTF-8 format that Alma expects/requires.
    • Certain characters (<, >, ', ", &) are not valid XML characters and can cause the entire file to fail with a parse error if not replaced or "escaped" by properly encoding them.
    • There is an error (or errors) in the XML tags such as incorrect field name or mismatched open/close tags, etc.
  • Solution: You can search the XML file for errors or run it through your favorite XML checker. If you don't have one, you can use the one CARLI developed: CARLI's SIS Validator Tool. Just select the file you want to test from your local machine (in either .xml or .zip
    format) and the results will appear on screen. FYI, for data privacy, all uploaded file data is deleted after the results are returned. Any parse errors will usually be listed right at the top of the results and will even provide the line number as well as the offending bit of data. <upload example screenshot here>

"Fail in file id 99999999. Errors: The field (Expiration date, Purge date) is mandatory..."

  • Problem: This error most likely means that the XML tags as well as the data itself are not present in the XML file.
  • Solution: Consult the CARLI Mandatory I-Share Fields documentation for a list of required fields and their associated XML tags for proper format and placement within the file.

"I checked the post-load report in Alma and it says 'Completed Successfully' with a nice, green checkmark but no new user records were added/updated. What gives?"

  • Problem: This "error" will show up if you have your SIS loads (synchronizations) on a schedule, but you didn't upload an XML file before Alma checked for it at the scheduled time. This is a quirk of Alma that makes it look like everything worked as it should, but that may only be partially true. Alma considers the job successful if no errors were encountered, but unfortunately, that also includes cases where it found no XML file to load. That is obviously not the desired outcome if you thought you uploaded a file to the right spot.
  • Solution: If you expected a file to be loaded and it wasn't, there was most likely a breakdown in the process that creates and then uploads the file to the designated location (either the CARLI Secure FTP server or your institution's own FTP server). Consult your IT department to see if they can help you identify the reason. Was a file simply not created that day because it only gets created when user information gets updated? Did the script that FTPs the file fail? Did the cronjob that runs the script(s) fail?

"My SIS load was successful, but none of my users had their expiry date updated and now they are all expired"

  • Problem: The most likely scenario is that the process that generated your XML file used the wrong expiry date. This could happen for a variety of reasons, but generally, something like a setting or value for the current "term" may not have been updated properly (or at all).
  • Solution: Consult with your IT department (or whoever is in charge of the XML file creation process) and ask them to verify that the correct term (Fall 2023, Spring 2024) is set in your student information system. A setting like that is often what determines the expiry date (and purge date) that gets assigned to the users that populate the XML file. Additionally, sometimes only certain users in the student information system have the proper privileges to run the process that updates the term, so verify that the process was actually run successfully for all necessary (those that need to be added or updated in Alma) user records.

"Some users in my SIS load failed due to an invalid user group error"

  • Problem: Alma is particular about using the correct value for the user group field when performing a SIS load. There are 2 values (Code and Description) in the User Management configuration settings for User Group.
  • Solution: Be sure to double-check that your XML file contains the "Code" value for each user group rather than the "Description" value (assuming they are actually different, as it is technically allowed to use the same value when setting up the user groups in Alma).

Other SIS-related Documentation