User Import

The User Import feature allows for Portal user accounts to be created automatically from data held in a CSV file. It is only intended to be used when the out-of-the-box local user account functionality is to be used for the Portal, it is not advised for use alongside any integrated third-party authentication service such as SAML, CAS, or Jadu Connect.

Managing user import

User import is managed via the OnBase menu.

If your account has permission to access User import, you navigate to it's management area by the following:

1. Click the OnBase icon in the left navigation bar. The OnBase menu will open.
2. Click the User Import link.

Importing users

1. Navigate to the user import management area, and click the Import Users button. A window will open prompting you to select a CSV file to upload.
2. Select the file on your filesystem and click the Save button. At this point the file will be validated to ensure that it meets the expected structure. If validation fails, the issues will be presented on the upload form.
3. If validation succeeds, the import will be queued for processing. This may take some time; the status of the import will be shown as Waiting in the list of user imports. You will need to refresh the page to see the up-to-date status.
4. When the import is complete, the status of the import will change to Success

Once the import has completed, the import file will be deleted from the Jadu filesystem. The contents of all import and result files are stored in an encrypted form.

warning

Whilst the import process has been optimized as much as possible to work with large data sets, there will of course be a limit as to what it can handle. This limit will vary depending upon the exact configuration of your environment and file, however as a guide CSVs containing 25000 records should be processable with no issues.

For very large datasets it is advisable to split the records across multiple CSV files to be imported.

Reviewing the result of an import

The import process will produce a result file which will be the same as the CSV provided for import but with two additional columns - user id and error.

Where a data row was successfully imported, the user id column will be populated with the id of the JaduUser record created.

Where a data row failed to be imported, the user id column will be blank, and the error column will be populated with details of why the record could not be created. This could be because some of the data provided in that row was invalid, or because a user with the email address already existed in the system, or earlier within the import file.

To download the results of an import:

1. Navigate to the user import management area
2. Identify the import to be reviewed in the list of user imports and confirm that the status of the import is Success.
3. Click the Download Result link for that record. The file will be downloaded to your filesystem.

note

Result files will be kept for 7 days after the import was completed, in order to allow them to be downloaded. There is however a manual delete option within the Control Center, which we advise is used once you have successfully downloaded the result file.

CSV structure

The CSV file provided for import must be well formed with the appropriate escaping of special characters:

• Any fields which contain a comma (,) or newline will need to be surrounded by double quotes (" ")
• If a field contains a double quote character ("), this must be escaped by prefixing it with another double quote character, or a backslash (\).

The CSV must include a header row indicating the data fields in the CSV, the field names must match those expected (see below). It must include the email field as a minimum.

The other optional columns are:

• salutation
• forename
• surname
• birthday
• age
• sex
• occupation
• company
• address
• city
• county / state (either heading will be accepted)
• postcode / zip_code (either heading will be accepted)
• country
• telephone
• mobile
• fax
• website
• data_protection
• access_level
• external_id

Any additional fields included in the CSV will be ignored.

Data validation

As the CSV file is processed, each line will be checked to ensure that the data provided is valid.

There will also be a check to ensure that there is not already a user account with the provided email address.

note

You should disable user registration and change details functions whilst the user import is in progress to prevent a user registering with email address that exists in the CSV file while the import is in progress.

This can be done by enabling the MyAccount Registration Forms integration and ensuring that no urls are specified for Registration and Change Details forms urls.

If this integration was already in use, it is also advised that the registration & change details forms themselves be taken offline during the import.

The table below indicates the maximum field length and any specific format or restricted options for each of the expected fields.

Field	Max length	Format / options
email	235	a valid email address
salutation	100
forename	95
surname	95
birthday	10	date in the format: yyyy-mm-dd
age	20
sex	20
occupation	100
company	100
address	235
city	100
county	100
postcode	15
country	100
telephone	31
mobile	31
fax	31
website	255
data_protection	1	0 or 1
access_level	1	1, 2, 3, 4, or 5
external_id	255