Batch Load Technical Information

Document created by Richard Post on Sep 3, 2014Last modified by Richard Post on Feb 24, 2015
Version 4Show Document
  • View in full screen mode

(This information source is found in Pharos Help which is part of every Uniprint installation)

 

Batch Load Technical Information

 

 

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:

<last name>,<first name>,<logon id>,<billing option>,<group>,<password>,<access level>,<purse;action;amount;purse;action;amount;purse;action;amount> OR <credit>,<address>,<phone>,<comment>,<rate schedule> ,<card ID>,<middle initial>,<alias>,<email>,<custom1>,<custom2>,<active>

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.

   

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. 32 characters.

access level

The user's access level 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)

  1. Open the file in a spreadsheet application, e.g. Microsoft Excel.
  2. Delete the three columns that contain the balance of the three purses.
  3. Either:
    1. 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.
    2. 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.
  4. Delete the first row (which contains the column titles).
  5. Save the file.
  6. 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)

  1. Open the CSV file generated from in Open Office Calc. This opens the Text Import dialog.
  2. In the Character set, select Unicode UTF-8 from the drop-down menu.
  3. In the Separator options, select Separated by Comma, and then click OK.
  4. Delete the three columns that contain the balance of three purses - Purse1 Balance, Purse 2 Balance, Purse 3 Balance.
  5. Save the file.
  6. Rename the file using .txt format.
  7. 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--deactivateonsyncIf 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".

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:

  1. On the Active Directory domain controller, open the Active Directory Users and Computers manager (under Administrative Tools).
  2. Make sure that Advanced Features is selected in the View menu.
  3. For each container or organizational unit containing users that you want to batch load:
    1. Right-click on the object and select Properties.
    2. From the Security tab, select the user account or group that the batch load will run under, and tick the Read permission box.
    3. Click the Advanced button, select the same user/group you selected previously and click the View/Edit button.
    4. Change the Apply onto property to "this object and all child objects".
    5. 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.

 

Copyright ©2014 Pharos Systems International, Inc.

Attachments

    Outcomes