Batch Load Technical Information

Version 4

    (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.