Batch Load Technical Information

Layout of input file
Using previously archived data
Running the Batch Loader from the command line
Batch Loading from Active Directory
Command line examples

Input file layout

The Batch Loader can import users either from a Windows domain controller or from a text file. When loading users from a text file, the following file layout is expected:

The <purse;action;amount...> and <credit> strings are mutually exclusive - <credit> is included for backward compatibility with versions of Pharos that don't have multiple purses.

All fields after (and including) <card ID> are optional.

The fields may contain single quotes and spaces. If a field contains commas, it must be enclosed in double quotes. If a field contains double quotes, they must be doubled up (i.e. each double quote must be replaced with two double quotes). Items that are longer than the specified maximum length are automatically truncated.

Blank fields in a CSV file will not change existing data already stored in the database. For example, existing values will not be deleted or overridden when updating users. Only those fields with values in them will be updated. This implies a) The Batch Loader can be used to just update certain fields (e.g. change card IDs for all users without overwriting other data) and b) The Batch Loader cannot be used to empty any fields (e.g. password field cannot be made blank by using a CSV file with no value in the password field).

Column name	Meaning	Restrictions
last name	The user's last name.	Max 30 characters. If blank, the logon ID will be used.
first name	The user's first name(s).	Max 50 characters.
logon ID	The user ID.	Max. 255 characters, must be unique.
billing option	How the user is to be billed.	Must be "Arrears" or "Advance".
group	Name of the User Group the user belongs to.	If the group does not already exist in the Pharos database it is either added or ignored, depending on the option selected. If no group is specified, the User will be added to the 'public' group.
password	The user's password.	Max. 255 characters.
role	The user's role in the Pharos system.	Must be one of "User", "Proctor", "Cashier", "Administrator"
purse	The purse to be affected.	The unique ID for the purse. By default: 1 = Technology Grant 2 = Tuition Fees 3 = User Pays
action	What is to be done to the purse.	0 = do nothing to the purse 1 = credit purse balance 2 = set/adjust purse balance An action must be specified for each purse, even if that action is to do nothing.
amount	The credit amount or balance to be set for the purse.	Any amount in dollars and cents, e.g. "10.00".
credit	Amount to credit the user with.	A number, or blank. If <credit> is used instead of a <purse> string, the Batch Loader will set the User Pays purse (ID=3) to the amount.
address	The user's address.	Max. 255 characters. Can be blank.
phone	The user's phone number.	Max. 30 characters. Can be blank.
comment	Any miscellaneous comments about the user.	Max. 255 characters. Can be blank.
rate schedule	The Discount Rate Schedule to apply to the user.	Name of an existing Discount Rate Schedule in the Pharos Database, or blank.
card ID	The user's Card ID.	Max 255 characters. Optional.
middle initial	The user's middle initial.	1 character. Optional.
alias	The user's alias.	Optional. If an Alias is not specified, one will be auto-generated according to the selection made on the System Settings screen.
email	The user's email address.	Optional.
custom1	Custom text to appear in the user's Custom1 field.	Optional.
custom2	Custom text to appear in the user's Custom2 field.	Optional.
active	Whether the user account is currently authorized to use the system.	1 = active, 0 = inactive. Optional. If a value is not specified, a new account is active and an existing account retains its current status.

Using previously archived data

CSV files produced by the Batch User Archive can be re-imported into the Pharos Database using the Batch Loader. Before a file can be imported, it must be modified slightly.

The following instructions apply only to non-Unicode characters. Microsoft® Excel does not support the required process for Unicode characters. However, you can use other tools, for example, OpenOffice Calc to deal with Unicode characters.

Non-Unicode

To use previously archived data (non-Unicode)

Open the file in a spreadsheet application, e.g. Microsoft Excel.
Delete the three columns that contain the balance of the three purses.
Either:

Leave the "Current Balance" column as it is. This will result in the value for the user's overall balance (which may have been across multiple purses) being loaded into the User Pays purse when the data is imported.
For each User, replace the "Current Balance" column with details of the purse balances in the <purse;action;amount> format required by the Batch Loader for multiple purses.

Delete the first row (which contains the column titles).
Save the file.
Rename the file from filename.csv to filename.txt - this will make the file easier to find when browsing for it in the Batch User Load wizard.

CSV files can also be edited with a text editing application like Notepad, although doing so is likely to be more cumbersome.

The next set of steps give instructions on how to use previously archived data with Unicode characters using Open Office Calc.

Unicode (Using Open Office Calc)

Open the CSV file generated from in Open Office Calc. This opens the Text Import dialog.
In the Character set, select Unicode UTF-8 from the drop-down menu.
In the Separator options, select Separated by Comma, and then click OK.
Delete the three columns that contain the balance of three purses - Purse1 Balance, Purse 2 Balance, Purse 3 Balance.
Save the file.
Rename the file using .txt format.
You can now use the batch user load to import the files.

Command line options

The Batch Loader (userload.exe) can be run from within the Pharos Administrator or standalone from the command line or a script file. When run from the command line, the following options can be specified.

The parameters for the command-line batch loader are case sensitive. If the short option of command line options is used, options must be in uppercase. If the long version is used, options must be in lowercase.

Short option	Long option	Parameter	Meaning
General Options
-?	--help		Show this list of parameters. No parameters also triggers help.
	--nohelp		Default.
-LG	--logfile	<filename>	Write results to the specified log file. If the file name contains backslash characters (\) they must be escaped by two backslashes (\\).
-AL	--archivelog	<filename>	Write an archive log to the specified file. The archive log stores the details of any users that were archived.
Input Source Options
-FN	--file	<filename>	Specifies a file as the source for any of the Batch Loader operations. If the file name contains backslash characters (\) they must be escaped by two backslashes (\\).
-NT	--server	<server>	Domain controller. Specifies a Windows domain as the source for any of the Batch Loader operations.
-DG	--domaingroup	<NT Group name>	The name of the Windows domain group to process. -NT is a co-requisite parameter.
Action
-PD	--delete		Delete users. All users that are specified in the input source are removed from the Pharos database. If transaction records associated with a user have not already been archived, they are deleted with the user.
	--nodelete		Default.
-RM	--deleteonsync		Delete users who no longer exist in the Windows database. -PS is a co-requisite parameter.
	--nodeleteonsync		Default.
-PU	--update		Update users. Only users that already exist in the Pharos database are updated with the data given in the input source.
	--noupdate		Default.
-PS	--addupdate		Add or Update users. Users that exist in the Pharos database are updated, and non-existent users are added.
	--noaddupdate		Default.
User Group Options
-GS	--group	<group>	Make all users part of the specified group.
-GC	--groupcmt		Retrieve group from description.
	--nogroupcmt		Default.
-IG	--groupinsert		Insert group if not already existing.
	--nogroupinsert		Default.
-MD	--skip		Default. When extracting the group from the Windows description, skip user if description is blank.
-MK	--assigntogroup	<group>	When extracting the group from the Windows description and the description is missing, place the user in the specified group.
-AU	--uid		Generate alias from user ID.
	--auto		Default. Auto generate, according to the option selected on the System Properties dialog.
-RG	--retaingroup		All Users already in the Pharos Database will remain in whatever Groups they are already in. This overrides any other User Group option that conflicts with it.
	--noretaingroup		Default.
Billing Options
-BO	--billing	<option>	Billing option - must be one of "Advance" or "Arrears". Only applies if users are loaded from an NT domain. Default is "Advance".
-CL	--cashier	<cashier>	Name of the Cashier- or Administrator-level user who is performing the credit. Always required when loading users from a file. Otherwise only required if users are credited, i.e. if the -CP or -CA options are used.
-CP	--purse	<purse;action;amount ;purse;action;amount; ;purse;action;amount;>	A string of purse balance information follows this switch. This string is a ; (semi-colon) separated list of purse information for setting or crediting each purses balance. See above for the meanings of each variable.
-CA	--credit	<amount>	Credit all users with initial amount. If used instead of -CP, the Batch Loader will set the User Pays purse balance to the amount passed and leave all other purses.
-RS	--rate	<rate>	Assign the specified Discount Rate Schedule to all users.
Name and Password Options
-NF	--nameformat	<format>	Define the name format to be extracted. <format> can be one of the following:
		--fsl	Full name field is in first last format (default). Only applies if users are loaded from a Windows domain.
		--lcf	Full name field is in 'last, first' format. Only applies if users are loaded from a Windows domain.
		--lsf	Full name field is in 'last first' format. Only applies if users are loaded from a Windows domain.
-SB	--skipblankname		Skip users with blank full name (else use the Logon ID).
	--noskipblankname		Default.
-PO	--userpwd	<password>	Set all passwords to the specified value.
-PI	--idpassword		Set user password to be the same as the Logon ID.
-OC	--comment		If this value is present, users' Comment fields will be left as they are. If it is not present, comment fields will be overwritten.
-DM	--deactivateonsync		If this option is specified, user accounts that are in the Pharos Database, but not in the source file are deactivated . The user's "Active" property in the User > Accounts context will be set to "No".
-AE	--appendemail		If this option is specified, when the source file specifies one email address and the updated user account already has another, the user has both addresses after the batch load.
	--noappendemail		Default. When the source file specifies one email address and the updated user account already has another, after the batch load the user has only the address from the file.

Batch loading from Active Directory

The batch loader supports loading the following user details from an Active Directory domain:

User name/Logon ID
Full name (split into First Name(s) and Last Name)
Description (loaded into the Comment field)

However, the account that is running the batch load operation must have sufficient permissions to be able to see all of the user accounts being loaded.

To set Active Directory permissions:

On the Active Directory domain controller, open the Active Directory Users and Computers manager (under Administrative Tools).
Make sure that Advanced Features is selected in the View menu.
For each container or organizational unit containing users that you want to batch load:

Right-click on the object and select Properties.
From the Security tab, select the user account or group that the batch load will run under, and tick the Read permission box.
Click the Advanced button, select the same user/group you selected previously and click the View/Edit button.
Change the Apply onto property to "this object and all child objects".
Click OK to exit out of all dialogs.

Command line examples

How to use the Batch Loader to meet your requirement depends on what you want to do with the user accounts already in the Uniprint database. For example, if you want to leave them as they are, then you can simply run the Batch Loader without any of the parameters that specify what kind of action to take (i.e. -PU, -PS, -PD).

Lacking such parameters, the Batch Loader will default to "insert only", inserting the new users into the Uniprint database (and setting their balances) while taking no action for users already present in the Uniprint database.

userload -PS -FN c:\temp\users.txt -CL admin -LG c:\temp\log.txt

Function: Add/Update users in the Pharos Database from a file users.txt with logging outputted to the file load.txt. The Cashier user performing the operation is admin (a Cashier must always be specified when batch loading from a file).

userload -NT VarsityDC -DG Students -PO pword -CL admin -CP 1;0;0.0;2;2;10.00;3;0;0.0

Function: Add new users, set their initial balance without updating/affecting all of the existing users balances. This command adds new users who exist in the Windows domain with a Domain Controller named "VarsityDC" and belong to the group "Students". Their initial password is set to "pword" and the Cashier performing the operation is "admin".

Credit user purses as follows:

Technology Grant (ID = 1):	do nothing	(action = 0)
Tuition Fees (ID = 2):	set balance to	$10.00 (action = 2)
User Pays (ID = 3):	do nothing	(action = 0)

userload -PS -FN c:\temp\users.txt -CL admin

Function: Add/Update users in the Pharos Database from a file users.txt. The Cashier user performing the operation is admin (a Cashier must always be specified when batch loading from a file). Take note that the -PS parameter updates existing users and adds non-existing users.

userload -PU -NT VarsityDC -DG Students

Function: Update users in the Pharos Database from a Windows domain with a Domain Controller named VarsityDC. Process only users who are members of the Students group.

userload --delete --server VarsityDC --domaingroup Students --archivelog c:\temp\deletedusers.txt

Function: Delete users in the Pharos Database who exist in the Windows domain with Domain Controller named VarsityDC and belong to the group Students. Details of users deleted from the Pharos Database are logged in a file named deletedusers.txt. Note that all transactions relating these users will be deleted from the Pharos Database at the same time.

userload -PU -NT VarsityDC -CL admin -CP 1;2;10.00;2;1;20.00;3;0;0.00

Function: Update users in the Pharos Database from a Windows domain with a Domain Controller named VarsityDC. Credit user purses as follows:

Technology Grant (ID = 1):	set balance to	$10.00 (action = 2)
Tuition Fees (ID = 2):	credit balance by	$20.00 (action = 1)
User Pays (ID = 3):	do nothing	(action = 0)

The Cashier user performing the credit is admin.

userload --update --server VarsityDC --cashier admin --purse 25.00

Function: Update users in the Pharos Database from a Windows domain with a Domain Controller named VarsityDC. Set all User Pays balances to $25.00. Equivalent to -PU -NT VarsityDC -CP 1;0;0;2;0;0;3;2;25.00

The Cashier user performing the credit is admin.