Alma CSV User Load Manual - ExLibrisGroup/alma-csv-user-load GitHub Wiki

Table of Contents

• Getting Started
• Configuring Profiles
  • Adding, renaming, removing profiles
  • Importing and exporting profiles
  • User Type
  • Profile Type
  • Field Mapping
  • Supported Fields
• Loading User Records
• Examples
  • Basic example
  • Default values
  • Multiple fields
  • Date fields
  • Institution-defined fields
  • Full example
• Getting Help

Getting Started

Welcome to the Alma CSV User Loader. This application gives you the ability to load users to your Ex Libris Alma instance using a CSV file. It's implemented as a Cloud App, which means you can install it and use it directly in your Alma instance.

You first need to ensure that your institution allows Cloud Apps and that this app is enabled. Then you can open the Cloud Apps pane and search for CSV in the search box. Click the install button to install the app, then click the Open button.

For more information on using Cloud Apps in Alma, see the online help.

Configuring Profiles

The first time you enter the app, you're taken to the settings screen. You should begin by defining a profile which describes the CSV file you wish to load. Multiple profiles are supported. Initially a single profile called Default is defined.

Adding, renaming, removing profiles

To add, rename, or remove a profile, click the plus, pencil, and trash can icons respectively. Follow the instructions in the prompts. To switch between profiles to edit the field mapping, select the profile name from the drop down.

Importing and exporting profiles

You can share profiles between users. Click the Share button to reveal a menu which enables the following options:

• Export all profiles: Export all of the user's profiles to a file
• Export current profile: Export the currently selected profile to a file
• Import profile(s): Opens a file selection window to select a file previously exported with one of the export options. A dialog will be presented which shows the names of the profile(s) to be added or replaced. Note that profiles of the same name will be replaced, so be sure to read the dialog carefully to avoid unexpected results. To restore the previous settings click the Restore button or navigate back to the home page.

User Type

By default, the app loads users defined as internal. You can specify that a profile should load users defined as external by selecting the appropriate value in the drop down. For more on information on internal and external users in Alma, see this documentation.

Profile Type

The CSV User Loader supports four different profile types: Add, Add/Update, Delete, and Enrich. Update, delete, and enrich profiles require a primary user ID as one of the fields. The update process is "swap all" - any fields provided in the input are replaced in the user record. Lists such as addresses, phone numbers, and email addresses are replaced completely. In the case of enrich, the update process is "swap all" except for lists, where any new values are added for the user identifier, user note, user proxy, user statistic, user address, user phone, and user email and existing values for those fields are left in place. This applies to internal segments for external users as well.

Field Mapping

The field mapping section is where you define the fields which are included in the CSV file and how they map to fields in Alma. The field mapping table has 3 columns:

• Header- the name of the column in the CSV file
• Default- the value to be used if no value is specified
• Name- the name of the field in Alma to which the value should be mapped

To add additional fields click the plus icon. To remove a field click the trash can next to the entry.

When you've finished editing the profiles, click the Save button. To restore the previous values, click Reset. To return to the main screen after editing the settings, click the Back button at the top.

See the section below for examples of field mappings.

Supported Fields

The following fields are supported:

• Primary ID
• First Name
• Middle Name
• Last Name
• Address Line 1
• Address Line 2
• Address Line 3
• Address Line 4
• Address Line 5
• City
• State
• Postal Code
• Country Code
• Address Type
  • home, work, school, alternative
• Email address
• Email address type
  • personal, work, school, alternative, ccAddress
• Phone Number
• Phone Type
  • home, office, mobile
• Identifier Type
  • Out of the box user identifiers: BARCODE, INST_ID
• Identifier Value
• Identifier Note
• Note type
  • OTHER (viewable in Discovery), LIBRARY, ADDRESS, BARCODE, CIRCULATION, ERP, POPUP (General), REGISTAR
• Note visible to patrons (true/false)
• Note pops up in patron services (true/false)
• Note text
• Statistical category
• User Group (use the user group code, not the description)
• Campus Code
• Preferred Language (use the language code, not the language name)
• Gender
• Birth Date (yyyy-mm-dd)
• Expiration Date (yyyy-mm-dd)
• Purge Date (yyyy-mm-dd)
• Password
• Force password change (TRUE/FALSE)
• Prefrerred First Name
• Prefrerred Middle Name
• Preferred Last Name
• External System Code
  • Mandatory for external users. Can be any default value. Example: SIS
• Record Type (CONTACT, PUBLIC, STAFF)
• Job Category
  • From the Job Category code table. See job_category in the documentation for a list of allowed values
• Job Description
• PIN Number
• Title
  • From the User Title code table. See the online help for how to configure this field
• User Status
• Resource Sharing Library (library code)

Note: The first address, phone, and email provided is marked as preferred.

Loading User Records

To load a CSV file, select the desired profile from the profile list. Then drag the CSV file into the specified area, or click the area to browse for the file. Then click the Load users button to begin the load process. Confirm the prompt and the app will begin loading the users. Progress will be shown in the results pane at the bottom. The primary ID will be displayed for each created user. If there are errors, the error message will be displayed.

To begin the process again, click the OK button at the end of the results pane and start over.

Examples

The following examples show how to handle different use cases. A snippet from a CSV File and the corresponding field mapping are displayed for each example.

Basic example

This shows a basic example with several fields.

First Name,Last Name,Address,City,Address Type,Email,Email Type
Josh,Testman,123 Main St,Mainville,home,[email protected],school
Harold,Henry,456 Main Ave,Anywhere,home,[email protected],school

Header	Default	Name
First Name		First Name
Last Name		Last Name
Address		Address Line 1
City		City
Address Type		Address Type
Email		Email address
Email Type		Email address type

Default values

This example shows the use of default values. To use default values, define a line in the field mapping with a value for the Default column.

Default values can be used with or without a column header:

• If a column header is provided, the default value is used when the column value is empty.
• If no column header is defined, the default value is always used.

First Name,Last Name,Email
Josh,Testman,[email protected]
Harold,Henry,[email protected]

Header	Default	Name
First Name		First Name
Last Name		Last Name
Email		Email address
	school	Email address type

Multiple fields

For fields which accept multiple values, such as addresses and email addresses, you can define multiple occurances in the CSV file.

First Name,Last Name,Email,Email Address Type,Personal Email,Personal Email Type
Josh,Testman,[email protected],school,[email protected],personal

Header	Default	Name
First Name		First Name
Last Name		Last Name
Email		Email address
Email Address Type		Email address type
Personal Email		Email address
Personal Email Type		Email address type

First Name,Last Name,Note,Note 2
Josh,Testman,This is my note,This is another note

Header	Default	Name
First Name		First Name
Last Name		Last Name
Note		Note text
	OTHER	Note type
Note 2		Note text
	OTHER	Note type

Date fields

Date fields (e.g. birth date and expiration date) must be in the yyyy-mm-dd format.

First Name,Last Name,Expiration date
Josh,Testman,2020-07-20

Institution-defined fields

Institution-defined fields, such as User Group and Identifier Type, should use the code rather than the description.

First Name,Last Name,User group
Josh ,Testman,ALUM

Full Example

user_group,univ_id,first_name,last_name,expiration_date,address_line1,address_line2,city,state,postal_code,phone_number,email_address,additional_identifier,stat_category_code1,stat_category_code2,stat_category_code3,note,note_visible,popup_note
staff,12345,Harry,Tester,2030-01-01,123 Test St,,Testville,,12345,412-444-4444,[email protected],abc123,B2,B3,,This is a note,true,true

Header	Default	Name
univ_id		Primary ID
first_name		First Name
last_name		Last Name
address_line1		Address Line 1
	home	Address Type
address_line2		Address Line 2
city		City
state		State
postal_code		Postal Code
email_address		Email address
	personal	Email address type
phone_number		Phone Number
	home	Phone Type
user_group		User group
expiration_date		Expiration Date
additional_identifier		Identifier Value
	BARCODE	Identifier Type
stat_category_code1		Statistical category
stat_category_code2		Statistical category
stat_category_code3		Statistical category
note		Note Text
	OTHER	Note Type
note_visible		Note Visible
	SIS	External System Code

Getting Help

If you would like to report a bug or request a feature, you can open an issue.