Import and synchronize users

The loading from a Student Information System is performed using zipped XML files that are placed at a predefined, secure FTP location. Alma fetches the files, parses them, and updates external users according to the input file and the parameters defined in the integration profile.

The following diagram illustrates the communication between the SIS and Alma:

• Import
• Synchronize

The import mode is a one-time load, used to initially create new external users. It is intended to be used only when you have a file of users you know are new, such as during the migration process, when you want to load users from your legacy system into Alma.
The synchronize mode is an ongoing load, used to update external users and add new ones.

See Introduction to SIS integration.

To load external users from the SIS system, an external system profile of “Users” type must be defined with active “Import” or “Synchronize” action.

Following is a list of the decisions that must be taken when defining a profile:

• Users type – The SIS profile loads one type of user (Staff, Public, or Contact). Each SIS generally manages one type of user, so you should select this type of user as the Record type when creating your profile. If your institution has more than one type of user in a single SIS, it is recommended that you define the Record type in the profile as Public. This means that all the users will be created in Alma as public users. You can then use the user roles to differentiate between patrons and staff.

• Match ID (for synchronize mode – The IT department and the library must determine the identifier that Alma and the SIS have in common in order to provide a matching point when synchronizing external users in Alma with the incoming data from the SIS. This may be the primary identifier or any other identifier. The determined identifier must exist as part of the input XML of each user, for both new and existing users.

NOTE: Because the determined identifier is used for matching purposes, it cannot be changed by the synchronization process.

If your institution uses the student ID as the user identifier in the SIS, this ID type should be defined in Alma as a possible additional identifier. For example, the User Identifier Type code table (accessible to Ex Libris staff only) would be configured as follows:

In the SIS integration profile, the student ID should be defined as the match identifier (by selecting it from the Match ID type drop-down list).
The input file XML should include this identifier for each external user.

IMPORTANT: institutions that use institutional IDP authentication, should supply the match identifier in the SIS input file.

If the primary identifier is the match ID, it must always be supplied in the input file. If it is not the match ID, it should always be supplied for existing users. For new users, if the primary identifier is not supplied, the system generates a default one by concatenating the first and last name. If this value already exists cross-institution, a sequence starting from 0 is added until no match is found.
For example, if a user with the identifier John Smith already exists, the primary identifier will be John Smith0. If this user also exists, the primary identifier will be John Smith1.
For further details on configuring an SIS profile, see Alma OLH.

The input file containing external users information must be in XML format, contained within a .zip file.

IMPORTANT: It is recommended to have one zip file, containing a consolidated XML file. Note that there is a maximum limit of 50 XML files in one zip file and a maximum of 20 zip files for each import/synchronization.
Note that the maximum size for a zip file is 4 GB.
In order to give better performance, we recommend to include only users which have changed (and not all the users in the SIS system).
If you do send all the users from the SIS system, Alma will check and update only users which have change. Therefore we recommend to update fields only when required, and not, for example, update the Modification date of all the users.
Users which were not modified will not be handled by Alma, hence their entire information will remain the same.
The zip file should be placed on a secure FTP server, as defined in the integration profile. After the file is handled by Alma, its name is changed to <filename>.zip.old.

NOTE: You can create sample user files from existing users to assist you in accurately creating the user file(s) that you want to upload. See the Create Sample File option in Alma OLH.

Alma does not support a situation in which a user appears more than once in a single import/synchronization.

Input file structure

There are 2 versions of input file: version 1, version 2.
Version 1 is deprecated  – no additional enhancements will be applied to this version.
Version 2 of the input file should be used – this version is the same as the user API object. Note that the list of users is built from users according to the rest_user.xsd.

Note that existing profiles with version 1 will continue to work. New profiles must be defined with version 2.

Moving to version 2

In order to switch from version 1 to version 2, you should modify the exported files from your SIS system to match version 2 structure.
After you have your files in the correct format, update the SIS profile to indicate that you are using version 2.

For each external user in the input file, the synchronization job attempts to find a match according to the defined match identifier. All the existing external users are checked, regardless of the SIS to which they initially belonged (Internal users are not considered for matching purposes.)
If no match is found, the synchronization job adds the user as a new external user or rejects the user, according to criteria selected in the external system profile. The addition of a new external user is similar to the addition of a new user via the import mode.
If a match is found (that is, the external user already exists in Alma), all the external information of the user is replaced as follows:

• Core information – All the fields are replaced by those in the input file. Only several fields are not replaced if they were updated manually – see here for more information.

• Related segments (identifiers, addresses, phone numbers, email addresses, notes, blocks, and statistics) – The existing external segments are deleted and the segments from the input file are added. Internal segments (that were added manually) are not deleted.

NOTE: The existing external segments are deleted even if the input user file contains a list of empty segments.

IMPORTANT: The synchronization is performed in a “swap all” mode. This means that all of the existing information is replaced. If a field does not exist in the input file, it is deleted from the existing user. The input file must therefore always include all of external user’s information, not only the updated fields.

The synchronization job workflow is illustrated in the following diagram:

For each external user in the input file, the import job checks the validity of the information. The validations are similar to those performed when creating a new user manually or using the API. If an error is found, it is added to the load report and the user is rejected. The system continues to process the next user in the input file. If the user information is valid, a new external user is created with the information from the input file. Alma assigns roles to the user according to the role assignment rules (see Configuring Role Assignment Rules on the Alma Administration guide).

IMPORTANT: Import does not try to match users. It is therefore faster than the synchronization mode. Use it only when you have a file of users you know are new.
The import job workflow is illustrated in the following diagram:

As described in the synchronization and import workflows above, errors may occur during loading from the SIS. These errors may be related to the input file structure or to the user information. Identifier-related errors cause a user to be rejected. For example, if you are importing a user whose primary identifier matches a primary identifier of one of the existing users, a User rejected on identifier event is generated.

NOTE: The configuration of the Mandatory Fields section (in User Management Configuration) is not taken into account during the SIS load. This means that even if a record is missing fields defined as mandatory, it is not rejected.
For further details on monitoring SIS import/synchronization, see Alma OLH.

It might happen that a patron comes to the circulation desk, and the circulation staff finds that no such user exists in Alma. This can happen, for example, for a new student, whose information was not yet loaded from the SIS. In such case, the circulation desk staff can perform “fast registration” of the user: The user will be created manually as external user. His information will be updated by the next synchronization.
During the fast registration, it is required to supply the SIS match identifier. This is information which should be known by the user requiring the registration.
If the supplied identifier is incorrect, the user information will not be synchronized. If this happens, the identifier must be manually corrected.

The recommended schema is version 2, which is the same as for the user API: the list of users is built from users according to the rest_user.xsd.

(The deprecated schema, version 1 can be found here).