Batch Shared Account Import and Update

Batch Shared Account Import and Update
Prev	Chapter 8. Shared Accounts	Next

The batch import and update feature allows the administrator to import accounts, and optionally update existing account details by reading data from a simple text file or directory structure. In addition to being able to create accounts, it enables administrators to update the following account data:

Enabled / disabled status
Account PIN / Code
Credit balance
Restriction status
Users allowed to use the account
Groups allowed to use the account
Invoicing options
Comment options
Notes

Examples of where the batch import feature is useful include:

When importing account and balance data from another external system (e.g. a project management or accounting system).
To reset the account balances at the end of a billing period (year/term/semester).
To bulk update the users and groups who are allowed to use/access the accounts (security).

Tip

To update shared accounts from a tab delimited file on a regular basis, see the section called “Shared Account Synchronization” instead. You can also synchronize shared accounts against the directory structure of a file system, for example when there is a separate folder for each department or customer.

To perform a batch import:

Manually inspect your file in a text editor and ensure it's in the prescribed tab-delimited format as detailed at the section called “Batch Account Import File Format”.
Navigate to the Accounts section.
Click the Batch Import / Update tab.
Click Browse to select the file to import. (The format of the file is described in the section called “Batch Account Import File Format”).
Choose whether you want to delete accounts that exist in PaperCut NG but not in the import file.
Press the Test Settings button.
The window shown will tell you how many lines were processed, and how many shared accounts will be imported, updated or deleted when Import is pressed.
If you are happy with the results of the test, press the Import button.

Tip

Consider testing your import file format with a small sample first (e.g. maybe a copy of the file containing only the first five lines). This way any formating mistake will only propagate to a few accounts rather than all!

Some example shared account import files can be found at [app-path]/server/examples/import/shared-accounts/ in both Excel and TSV (tab separated values) formats. The Excel format may be used to produce the TSV format by saving as Text (Tab delimited). Examples include a flat list of accounts using the example of departments in a school (school-departments.tsv) and another with subaccounts using the example of a client-matter layout for a business' clients (client-matter.tsv).

Batch Account Import File Format

The import file is in tab delimited format and contains the following fields in the given order.

No.	Field	Description	Optional?	Limitations
1.	Parent Account Name	The name of this account's parent. When creating a top level account, leave the sub-account name blank (and this will be the account's name).	Mandatory	Max. 255 characters
2.	Sub-account Name	When creating a sub-account (1 level deep only), enter its name here.	Optional - account will be top level if blank	Max. 255 characters
3.	Enabled	Whether or not this account is enabled. (Y/N where Y = YES, and N = No).	Optional - account will be enabled if blank
4.	Account PIN/Code	The account PIN/Code. For parent accounts, the code must be unique for all parent accounts. For sub-accounts, the code must unique amongst accounts with the same parent account.	Optional - PIN not set if blank	Max. 50 characters
5.	Credit Balance	The account balance.	Optional - Balance set to 0 if blank	A number with no currency symbol or separators, using a full stop for the decimal separator. Correct: `1.23` Incorrect: `$1.23` or `1,23` or `1,023.00`
6.	Restricted Status	The account's restricted status. (Y/N where Y = YES, and N = No).	Optional - if blank, set to a configurable default
7.	Users	Modifies the users that are allowed to select this account from the list (no CODE/PIN required). The access list may be modified as follows: To replace the previously defined access list, use a pipe (`\|`) delimited list of usernames. e.g. `user1\|user2\|user3` sets the list to these three users (removing any previously defined). To add users to the existing access list, prefix the pipe delimited user list with a plus sign (`+`). e.g. `+user1\|user2\|user3` adds these three users to the access list. To remove users from the existing user list, prefix the pipe delimited user list with a hyphen (`-`). e.g. `-user1\|user2\|user3` removes these three users from the access list. To remove all users from the access list, enter a hyphen (`-`).	Optional - users are not updated if blank	No real limit, but if there are many users consider using an access group instead
8.	Groups	Modifies the groups that are allowed to select this account from the list (no CODE/PIN required). To reference the special 'All Users' group, use the syntax `[All Users]`. The access list may be modified as follows: To replace the previously defined access list, use a pipe (`\|`) delimited list of groups. e.g. `group1\|group2\|group3` sets the list to these three groups (removing any previously defined). To add groups to the existing access list, prefix the pipe delimited group list with a plus sign (`+`). e.g. `+group1\|group2\|group3` adds these three groups to the access list. To remove groups from the existing group list, prefix the pipe delimited group list with a hyphen (`-`). e.g. `-group1\|group2\|group3` removes these three groups from the access list. To remove all groups from the access list, enter a hyphen (`-`).	Optional - groups are not updated if blank
9.	Invoice Option	The invoicing option defines how prints allocated to this account are invoiced. Available values are: `ALWAYS_INVOICE` - prints allocated to this account are always invoiced `NEVER_INVOICE` - prints allocated to this account are never invoiced `USER_CHOICE_ON` - it is up to the user whether or not to invoice prints allocated to this account. The default is yes. `USER_CHOICE_OFF` - it is up to the user whether or not to invoice prints allocated to this account. The default is no.	Optional - set to USER_CHOICE_ON if blank
10.	Comment Option	The comments option defines whether or not comments should be added to prints allocated to this account. Available values are: `NO_COMMENT` - comments may not be added `COMMENT_REQUIRED` - comments must be added `COMMENT_OPTIONAL` - it is up to the user whether or not to add a comment	Optional - set to COMMENT_OPTIONAL if blank
11.	Notes	Notes about the shared account (placed in the Notes field).	Optional - notes not set if blank	Max. 2000 characters

Table 8.1. Shared Account Import File Format

Other limitations: Although any actual limit to the size of an import file should be large enough for any purpose, we recommend keeping the file size below 10MB.

Tip

A simple way to create a tab delimited file is to create a spreadsheet in Microsoft Excel, and then save it in the Text (Tab delimited) format.

Import File Format Examples

The following lines shows importing all the above fields. (The fields are separated by tabs).

Maths   Y 12  5 N user1|user2 group1|group2 ALWAYS_INVOICE COMMENT_REQUIRED
Science Physics Y 1620 100 Y user3   NO_COMMENT A Note
Science Biology N 16 12.50 N   group3  USER_CHOICE_OFF

The following lines show updating only the groups that can access the account. NOTE: The tabs still exist for the enabled status, pin, balance, restriction and users fields, but each entry is blank.

Maths           group1|group2|group3
Science Physics         group1
Science Biology         group3

Tip

The shared account import process can be triggered via the command-line scripting tool server-command. See the section called “Server Commands (server-command)”.

Prev	Up	Next
Account Selection in Non-Domain Environments (Workgroups)	Home	Shared Account Synchronization