Appendix A. Tools - database, server-command scripting, and APIs (Advanced)

Table of Contents

Server Commands (server-command)
Accessing Server Commands remotely
Available Commands
Database Tool (db-tools)
export-db Command
import-db Command
init-db Command
delete-old-logs Command
The XML Web Services API
Web Services Example Code
Security
SSL/HTTPS Key Generation
Re-create the self-signed certificate
Using a custom signed SSL key
Importing an existing SSL key
Installing the Keystore
User Client Options
Command-line options
Configuration properties file
Changing the time after which jobs are deleted when awaiting popup response
Stopping and Starting the Application Server
Stopping and Starting the Application Server on Windows
Stopping and Starting the Application Server on Mac
Stopping and Starting the Application Server on Linux
Automating / Streamlining Installation on Windows
Importing Print Job Details

This appendix outlines the command line tools and advanced programming tools that come with PaperCut NG. Using these tools has been discussed throughout this manual, however this provides a reference guide to these tools and their use.

Caution

The advanced tools provided with PaperCut NG are very powerful and offer opportunities for all manner of customizations and enhancements. However, if used incorrectly, these tools could lead to unexpected results. Many of the advanced tools are written for software and script developers. It is expected that readers intending to use advanced tools are comfortable with using the command-prompt, and developing system management and server monitoring programs.

Server Commands (server-command)

The server-command tool provides access to dozens of server operations ranging from user management, system maintenance, account manipulation and printer control. The server-command tool is ideal for controlling the PaperCut NG Application Server via the command-line or automating via scripts.

Some examples of how an Administrator may choose to use the server-command tool:

  • Scheduling of online backups and data snapshots.

  • Scheduling user and/or group synchronization tasks.

  • Automating the addition of new users after the accounts are added to the network.

  • Performing account transactions such as adding funds/quota to user accounts.

  • Automating user account creation using custom scripts.

  • Disabling/Enabling printers.

  • Disabling/Enabling printing for users.

  • Controlling user restriction levels.

  • Managing shared accounts.

The server-command program is a command-line tool. It accepts the commands as arguments and outputs the results of the command on the console (standard-out). For security reasons only users with read access to the server.properties (normally only the Administrators group) have rights to execute the commands.

Typical use on a Windows system:

Add $10.00 to a user named 'testuser':

    C:\> cd [app-path]\server\bin\win
    C:\> server-command adjust-user-account-balance "testuser" 10.00 \
        "Added $10.00 to your account"
            

Note: backslash indicates text should be on the same line.

Accessing Server Commands remotely

Server commands can also be called remotely using standard remote command tools.

On Windows

Use PsExec - a remote command program provided by the Sysinternals team at Microsoft. For example (all on one line):

psexec.exe \\remoteserver \
  "C:\Program Files\PaperCut NG\server\bin\win\server-command.exe" \
   disable-printer printsrv1 labprinter -1
                        

On Linux/Novell/Mac

Use SSH - a secure remote command/shell program. SSH can be run non-interactively in scripts with the use of an authorized public key added under the papercut account's ~/.ssh/authorized_keys list. For example (all on one line):

ssh papercut@remoteserver \
  "/home/papercut/server/bin/linux-[x64|i686]/server-command \
  disable-printer printsrv1 labprinter -1"
                        

Available Commands

A full list of commands is available via server-command --help.

Usage: server-command COMMAND [ARGS...]

   COMMAND  : The server command name.
   ARGS     : A list of arguments to supply to the command.

COMMANDS: 
    user-exists <username>
        Test to see if a user exists.
        <username> - the username to test.

    get-user-account-balance <username> [<account>]
        Get a user's current account balance.
        <username> - the user's username.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled. Leave blank to get total balance.

    get-user-property <username> <property>
        Gets a user property.
        <username> - the name of the user.
        <property> - the name of the property to get. Valid properties include:
            balance - the user's current account balance
            primary-card-number - the user's primary card number
            secondary-card-number - the user's secondary card number
            card-pin - the user's card pin number
            default-shared-account - the user's default shared account name
            auto-shared-account - the user's automatically selected shared account name 
            department - the user's department
            disabled-net - whether or not the user's internet access is
                           currently disabled
            disabled-print - whether or not the user's printing is currently
                             disabled
            email - the user's email
            full-name - the user's full name
            notes - notes for the user
            office - the user's office
            print-stats.job-count - the total print job count for the user
            print-stats.page-count - the total printed page count for the user
            net-stats.data-mb - the internet data used by the user (in MB)
            net-stats.time-hours - the internet time used by the user (in hours)
            restricted - whether or not the user is currently restricted
            account-selection.mode - the user's current account selection mode
            account-selection.can-charge-personal - whether or not the user     
                                   can charge to their personal account
            account-selection.can-charge-shared-from-list - whether or not the
                      user can charge to a shared account, selected from a list
            account-selection.can-charge-shared-by-pin - whether or not the user
                      can charge to a shared account, selected by PIN
            other-emails - the user's other emails
            username-alias - the user's alias.  Only used when username aliasing
                         is enabled.

    set-user-property <username> <property> <value>
        Sets a user property.
        <username> - the name of the user.
        <property> - the name of the property to set. Valid properties and
                     values include:
            balance - the user's current account balance (a decimal number)
            primary-card-number - the user's card number (any text)
            secondary-card-number - the user's secondary card number (any text)
            card-pin - the user's card pin number (any text)
            default-shared-account - the user's default shared account name
            department - the user's department (any text)
            disabled-net - whether or not the user's internet access is
                           currently disabled (TRUE or FALSE)
            disabled-print - whether or not the user's printing is currently
                             disabled (TRUE or FALSE)
            email - the user's email (an email address, or any text)
            full-name - the user's full name (any text)
            notes - notes for the user (any text)
            office - the user's office (any text)
            password - the user's password (for internal users only) (any text)
            restricted - whether or not the user is currently restricted
                         (TRUE or FALSE)
            other-emails - the user's other emails
                           (a comma separated list)
                           Use blank to clear all other emails
            username-alias - the user's alias.  Only used when username aliasing
                         is enabled.               
            <value> - the value to set (see <property> for valid values).

    adjust-user-account-balance <username> <adjustment> <comment> [<account>]
        Adjust a user's account balance.
        <username> - the user's username.
        <adjustment> - the adjustment amount as a number. +ve or -ve.
        <comment> - a comment to be associated with the transaction.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled.

    adjust-user-account-balance-if-available <username> <adjustment> \
                <comment> [<account>]
        Adjust a user's account balance if there is enough credit available.
        <username> - the user's username.
        <adjustment> - the adjustment amount as a number. +ve or -ve.
        <comment> - a comment to be associated with the transaction.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled.

    adjust-user-account-balance-if-available-leave-remaining <username> \
                <adjustment> <leave-remaining> <comment> [<account>]
        Adjust a user's account balance if there is enough credit available
        to leave the given amount available in the account.
        <username> - the user's username.
        <adjustment> - the adjustment amount as a number. +ve or -ve.
        <leave-remaining> - the amount to leave in the account.
        <comment> - a comment to be associated with the transaction.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled.

    adjust-user-account-balance-by-group <group> <adjustment> <comment> \
                [<account>]
        Adjust the account balance for all users in a group.  This process 
        happens in the background.
        <group> - the group for which all users' accounts are to be adjusted.
        <adjustment> - the adjustment amount as a number. +ve or -ve.
        <comment> - a comment to be associated with the transaction.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled.

    adjust-user-account-balance-by-group-up-to <group> <adjustment> <limit>
                <comment> [<account>]
        Adjust the account balance for all users in a group, but don't increase
        user balance beyond the given limit.  This process happens in the
        background.
        <group> - the group for which all users' accounts are to be adjusted.
        <adjustment> - the adjustment amount as a number. +ve or -ve.
        <limit> - don't increase user balance beyond this limit.
        <comment> - a comment to be associated with the transaction.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled.

    set-user-account-balance <username> <balance> <comment> [<account>]
        Set a user's account balance to a set value.
        <username> - the user's username.
        <balance> - set the account to this value. +ve or -ve.
        <comment> - a comment to be associated with the transaction.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled.

    set-user-account-balance-by-group <group> <balance> <comment> [<account>]
        Set the balance for each member of a group to the given value.  This 
        process happens in the background. 
        <group> - the group for which all users' balance is to be set.
        <balance> - the value to set all users' balance to. +ve or -ve.
        <comment> - a comment to be associated with the transaction.
        [<account>] - Optional personal account name. Only used when multiple
            personal accounts are enabled.

    reset-user-counts <username> <reset_by>
        Reset the page and job counts associated with a user.
        <username> - the user's username.
        <reset_by> - name of the user/script/process resetting the counts.

    re-apply-initial-user-settings <username>
        Re-applies initial settings on the user. Initial user settings are based
        on group membership.
        <username> - the user's username. 

    disable-printing-for-user <username> <minutes_disabled>
        Disable printing for a user for a set period of time.
        <username> - the name of the user to disable printing for.
        <minutes_disabled> - the time in minutes to disable. -1 indicates 
        forever.

    add-new-user <username>
        Trigger the process of adding a new user account. Assuming the user 
        exists in the OS/Network/Domain user directory, the account will be 
        created with the correct initial settings as defined by the rules 
        set up in the admin interface under the Groups section.
        <username> - the user's system username.

    rename-user <current_username> <new_username>
        Rename the given existing user. Use this method with care. Renaming a
        user should be performed in conjunction with renaming the user in the
        OS/Network/Domain.
        <current_username> - the name of the user to rename.
        <new_username> - the user's new name.

    delete-existing-user <username>
        Delete a user account from the system.  Use this method with care. 
        Calling this will permanently delete the user account from the user 
        list (print history records remain).
        <username> - the user's system username.

    add-new-internal-user <username> <password> <full_name> <email> <card-id>
                          <pin>
        Create a new internal user.  Username and password are required.  Other
        properties may be omitted.  Properties may be changed after creation
        using 'set-user-property'.  For more information about internal users
        See the user manual chapter 'Managing Guests and Internal Users'.
        <username> - (required) the username of the new internal user.
        <password> - (required) user's password.
        <full_name> - (optional) user's full name.
        <email> - (optional) user's email address.
        <card-id> - the user's card or identity number.
        <pin> - the user's card/id PIN.

    look-up-user-name-by-id-no <id-no>
        Looks up the user with the given user id number and prints out their
        user name.  If no match was found an empty line is printed out.
        <id-no> - The user id number to look up.

    look-up-user-name-by-card-no <card-no>
        Looks up the user with the given user card number and prints out their
        user name.  If no match was found an empty line is printed out.
        <card-no> - The user card number to look up.

    add-user-to-group <username> <group>
          Add a user to the specified group. It changes the group 
          membership within the application not in the OS/Network/Domain user
          directory.
        <username> - the name of the user.
        <group> - the name of the group to which the user needs to be added.

    remove-user-from-group <username> <group>
          Remove a user from the specified group. It changes the group 
          membership within the application not in the OS/Network/Domain user
          directory.
        <username> - the name of the user.
        <group> - the name of the group from which the user needs to be removed.

    add-admin-access-user <username>
        Add a user as an admin with default admin rights.
        <username> - the name of the user.

    remove-admin-access-user <username>
        Remove an admin user from the list of admins.
        <username> - the name of the user.

    add-admin-access-group <groupname>
        Add a group as an admin group with default admin rights.
        <groupname> - the name of the group.

    remove-admin-access-group <groupname>
        Remove a group from the list of admin groups.
        <groupname> - the name of the group.

    set-user-account-selection-auto-select-shared-account <username>
                                                          <account_name>
                                                          <charge_personal>
        Sets a user's account selection to charge to a single shared account.
        <username> - the name of the user.
        <account_name> - Full name of the shared account to charge to.
        <charge_personal> - whether or not personal account should be charged.
                            (TRUE or FALSE)

    set-user-account-selection-auto-charge-personal <username>
        Sets a user's account selection to automatically charge to personal.
        account.
        <username> - the name of the user.

    set-user-account-selection-standard-popup <username> <allow_personal>
                                              <allow_list_selection>
                                              <allow_pin_code>
                                              <allow_printing_as_another_user>
                                              <charge_to_personal>
                                              [<default_shared_account>]
        Sets a user's account selection to standard account selection popup.
        <username> - the name of the user.
        <allow_personal> - allow user to charge to personal account.
        <allow_list_selection> - allow user to select a shared account from
                                 list. (TRUE  or FALSE)
        <allow_pin_code> - allow user to select a shared account using pin.
        <allow_printing_as_another_user> - allow user to print as another user.
        <charge_to_personal> - when shared account is selected charge to
                               personal account. (TRUE or FALSE)
        [<default_shared_account>] - Optional default shared account

    list-user-accounts
        List the names of all the user accounts in the system, sorted by
        username, one per line.

    get-total-users
        Gets a count of all the users in the system.

    list-shared-accounts
        List the names of all the shared accounts in the system, sorted by
        shared account name, one per line.

    list-user-shared-accounts <username> [<ignoreAccountMode>]
        List the names of all the shared accounts accessible by the given user
        sorted by account name, one per line.
        <username> - User for which to list accounts
        [<ignoreAccountMode>] - Optional. Specify TRUE to ignore user's
                                      account selection mode. (TRUE or FALSE)

    shared-account-exists <account_name>
        Test to see if a shared account exists.
        <account_name> - the shared account name to test.

    get-shared-account-account-balance <account_name>
        Get shared account's current account balance.
        <account_name> - the shared account's full name.

    get-shared-account-property <account_name> <property>
        Gets a shared account property.
        <account_name> - the name of the user.
        <property> - the name of the property to get. Valid properties include:
            access-groups - the shared account's access groups
                            (a comma separated list)
                            Use blank to clear all groups
            access-users - the shared account's access users
                           (a comma separated list)
                            Use blank to clear all users
            balance - the shared account's current balance
            comment-option - the shared account's commenting option
            disabled - whether or not the shared account is currently disabled
            invoice-option - the shared account's invoicing option
            notes - notes for the shared account
            pin - the shared account's PIN
            restricted - whether or not the shared account is currently
                         restricted

    set-shared-account-property <account_name> <property> <value>
        Sets a shared account property.
        <account_name> - the name of the shared account.
        <property> - the name of the property to set. Valid properties and
                     values include:
            access-groups - the shared account's access groups)
                            (a comma separated list)
            access-users - the shared account's access users
                           (a comma separated list)
            balance - the shared account's current balance (a decimal number)
            comment-option - the shared account's commenting option. One of:
                NO_COMMENT - no comment may be entered
                COMMENT_REQUIRED - a comment must be entered
                COMMENT_OPTIONAL - the user may enter a comment or not
            disabled - whether or not the shared account is currently disabled
                       (TRUE or FALSE)
            invoice-option - the shared account's invoicing option. One of:
                ALWAYS_INVOICE - print jobs will always be invoiced
                NEVER_INVOICE - print jobs will never be invoiced
                USER_CHOICE_ON - the user can choose (default on/yes)
                USER_CHOICE_OFF - the user can choose (default off/no)
            notes - notes for the shared account (any text)
            pin - the shared account's PIN (any text, must be unique)
            restricted - whether or not the shared account is currently
                         restricted (TRUE or FALSE)
        <value> - the value to set (see <property> for valid values).

    adjust-shared-account-account-balance <account_name> <adjustment> <comment>
        Adjust a shared account's account balance.
        <account_name> - the shared account's full name.
        <adjustment> - the adjustment amount as a number. +ve or -ve.
        <comment> - a comment to be associated with the transaction.

    set-shared-account-account-balance <account_name> <balance> <comment>
        Set a shared account's balance to a set value.
        <account_name> - the shared account's full name.
        <balance> - set the account to this value. +ve or -ve.
        <comment> - a comment to be associated with the transaction.

    add-new-shared-account <shared_account_name>
        Add a new shared account.
        <shared_account_name> - the name of the shared account.

    rename-shared-account <curr_shared_account_name> <new_shared_account_name>
        Rename an existing shared account.
        <curr_shared_account_name> - Current shared account name. Use a '\' to
                                     denote a subaccount e.g.: 'parent\sub'
        <new_shared_account_name> - New shared account name.
        
    delete-existing-shared-account <shared_account_name>
        Delete a shared account from the system.  Use this method with care.
        Calling this will permanently delete it from the shared account list
        (print history records will remain).
        <shared_account_name> - the name of the shared account to delete.

    add-shared-account-access-user <shared_account_name> <username>
        Allow the given user access to the given shared account without using
        a pin.
        <shared_account_name> - the name of the shared account to allow access
                                to.
        <username> - the name of the user to give access to.

    add-shared-account-access-group <shared_account_name> <group_name>
        Allow the given group access to the given shared account without using
        a pin.
        <shared_account_name> - the name of the shared account to allow access
                                to.
        <group_name> - the name of the group to give access to.

    remove-shared-account-access-user <shared_account_name> <username>
        Revoke the given user'- access to the given shared account.
        <shared_account_name> - the name of the shared account to revoke access
                                to.
        <username> - the name of the user to revoke access for.

    remove-shared-account-access-group <shared_account_name> <group_name>
        Revoke the given group's access to the given shared account.
        <shared_account_name> - the name of the shared account to revoke access
                                to.
        <group_name> - the name of the group to revoke access for.


    get-printer-property <server_name> <printer_name> <property>
        Gets a printer property.
        <server_name> - the name of the server the printer is hosted on.
        <printer_name> - the name of the printer.
        <property> - the name of the property to get. Valid properties include:
            disabled - whether or not the printer is currently disabled
            print-stats.job-count - the total print job count for this printer
            print-stats.page-count - the total printed page count for this
                                     printer
            cost-model - the cost model used by the printer (e.g. SIMPLE)
            custom-field-1 - the value for custom field 1 if set.
            custom-field-2 - the value for custom field 2 if set.
            custom-field-3 - the value for custom field 3 if set.
            custom-field-4 - the value for custom field 4 if set.
            custom-field-5 - the value for custom field 5 if set.
            custom-field-6 - the value for custom field 6 if set.

    set-printer-property <server_name> <printer_name> <property> <value>
        Sets a printer property.
        <server_name> - the name of the server the printer is hosted on.
        <printer_name> - the name of the printer.
        <property> - the name of the property to set. Valid properties and
                     values include:
            disabled - whether or not the printer is currently disabled
                       (TRUE or FALSE)
            custom-field-1 - the value for custom field 1
            custom-field-2 - the value for custom field 2
            custom-field-3 - the value for custom field 3
            custom-field-4 - the value for custom field 4
            custom-field-5 - the value for custom field 5
            custom-field-6 - the value for custom field 6
            override-user-level-settings - whether or not printer should
                                           override user level settings.
                                           (TRUE or FALSE)
            override-user-level-settings-charge-to - the name of the shared 
                                    account. Use "[personal]" for personal
                                    account. Use blank to disable charge to
                                    settings.
        <value> - the value to set (see <property> for valid values).

    list-printers
        List the names of all the printers in the system, sorted by
        printer name, one per line.

    set-printer-cost-simple <server_name> <printer_name> <cost_per_page>
        Sets the printer's page cost (using SIMPLE charging model).
        <server_name> - the name of the server the printer is hosted on.
        <printer_name> - the name of the printer.
        <cost_per_page> - the cost per page (simple charging model)

    get-printer-cost-simple <server_name> <printer_name>
        Get the printer's page cost (using SIMPLE charging model).
        <server_name> - the name of the server the printer is hosted on.
        <printer_name> - the name of the printer.

    reset-printer-counts <server_name> <printer_name> <reset_by>
        Reset the page and job counts associated with a printer.
        <server_name> - the name of the server hosting the printer.
        <printer_name> - the printer's name.
        <reset_by> - name of the user/script/process resetting the counts.

    add-printer-group <server_name> <printer_name> <printer_group_name>
        Add a printer to a single printer group in addition to existing printer
        group membership.
        <server_name> - the name of the server hosting the printer.
        <printer_name> - the printer's name.
        <printer_group_name> -  name of a printer group.

    set-printer-groups <server_name> <printer_name> <printer_group_names>
        Set the printer groups a printer belongs to, overwriting any existing
        group membership.
        <server_name> - the name of the server hosting the printer.
        <printer_name> - the printer's name.
        <printer_group_names> - a comma separated list of printer group names.
                                To clear all group association set to "".

    enable-printer <server_name> <printer_name>
        Enable a printer.
        <server_name> - the name of the server hosting the printer.
        <printer_name> - the printer's name.

    disable-printer <server_name> <printer_name> <minutes_disabled>
        Disable a printer for a set period of time.
        <server_name> - the name of the server hosting the printer.
        <printer_name> - the printer's name.
        <minutes_disabled> - the time in minutes to disable. -1 indicates 
        forever.

    delete-printer <server_name> <printer_name>
        Delete a printer.
        <server_name> - the name of the server hosting the printer.
        <printer_name> - the printer's name. Use "[All Printers]" to delete
                         all printers on the specified server.

    rename-printer <server_name> <printer_name> <new_server_name>
                   <new_printer_name>
        Rename a printer. This can be useful after migrating a print queue or
        print server (i.e. the printer retains its history and settings under
        the new name). Note that in some cases case sensitivity is important, so
        care should be taken to enter the name exactly as it appears in the OS.
        <server_name> - the existing printer's server name
        <printer_name> - the existing printer's queue name
        <new_server_name> - the new printer's server name
        <new_printer_name> - the new printer's queue name

    add-printer-access-group <server_name> <printer_name> <group_name>
        Adds the user group to the printer's access group list.
        <server_name> - the printer's server name
        <printer_name> - the printer's queue name
        <group_name> - the name of the user group that needs to be added.

    remove-printer-access-group <server_name> <printer_name> <group_name>
        Removes the user group from the printer's access group list.
        <server_name> - the printer's server name
        <printer_name> - the printer's queue name
        <group_name> - the name of the user group that needs to be removed.

    add-new-group <group_name>
        Add a new group to the system's group list. The group should already 
        exist in network directory.
        <group_name> - The name of the group to add.
    
    sync-group <group_name>
        Syncs an existing group with the configured directory server, updates group
        membership in the system.
        <group_name> - The name of the group to sync.    
        
    remove-group <group_name>
        Removes the group.
        <group_name> - The name of the group to remove.
    
    get-user-groups <user_name>
        Retrieves all groups a single user belongs to.
        <user_name> - The name of the user to query.
    
    list-user-groups
        List the names of all the user groups in the system, sorted by
        groupname, one per line.

    group-exists <group_name>
        Test to see if a group exists.
        <group_name> - the group name to test.

    set-group-quota <group_name> <quota_amount> <period> <quota_max_accum>
        <group_name> - the name of the group to set.
        <quota_amount> - the quota amount.
        <period> - the schedule period (i.e. DAILY, WEEKLY, MONTHLY).
        <quota_max_accum> - the quota maximum accumulation amount. Set to 
                            0.0 to have no limit.

    get-group-quota <group_name>
        Get the group quota allocation settings on a given group.
        Returns the quota amount, the schedule period and
            the quota maximumn accumulation amount.
        <group_name> - the name of the group to get.

    use-card <user_name> <card_number>
        Redeem a card and place the credit on the user's account.
        <user_name> - the name of the user with the account to credit.
        <card_number> - the number of the card to use.

    perform-online-backup
        Start an online backup.  The back file is written to 
        ~/server/data/backups. as a dated, zipped XML file. This process 
        happens in the background.

    perform-group-sync
        Start the process of synchronizing the system's group membership with
        the OS/Network/Domain's group membership. A call to this method will
        commence the sync process and the operation will complete in the
        background.

    perform-user-and-group-sync
        Start a full user and group synchronization. This is equivalent to
        pressing the "Synchronize Now" button in the admin interface. No
        existing users will be removed. Whether or not full details for existing
        users will be updated depends on the current user/group sync settings as
        defined in the admin interface. A call to this method will commence the
        sync process and the operation will complete in the background.

    perform-user-and-group-sync-advanced <delete_old_users> <update_details>
        An advanced version of the user and group synchronization process
        providing control over the sync settings. A call to this method will
        commence the sync process and the operation will complete in the
        background.
        <delete_old_users> - set to TRUE remove old users, else FALSE.
        <update_details> - set to TRUE if existing users details (e.g. email,
                           full-name, etc. ) are to be updated.

    add-new-users
        Calling this method will start a specialized user and group  
        synchronization process optimized for tracking down adding any new 
        users that exist in the OS/Network/Domain user directory and not in 
        the system. Any existing user accounts will not be modified. A group 
        synchronization will only be performed if new users are actually added 
        to the system.

    is-task-complete
        Returns TRUE if a long running task such as perform-group-sync,
        perform-user-and-group-sync, or add-new-users has completed.

    get-task-status
        Returns status information such as progress, completion status and, 
        error messages, on the current or last run long running task such as 
        perform-group-sync, perform-user-and-group-sync, or add-new-users.

    batch-import-shared-accounts <import_file> <test>
                                 <delete_non_existent_accounts>
        Import the shared accounts contained in the given tab-delimited import
        file.
        <import_file> - the import file location.
        <test> - (TRUE or FALSE) If TRUE, perform a test only. The printed
                 statistics will show what would have occurred if testing
                 wasn't enabled. No accounts will be modified.
        <delete_non_existent_accounts> - (TRUE or FALSE) If TRUE, accounts that
                             do not exist in the import file but exist in the
                             system will be deleted.  If FALSE, they will be
                             ignored.

    batch-import-users <import_file> <create_new_users>
        Import the users contained in the given tab-delimited import
        file.  See the user manual chapter 'Batch User Data Import and Update'
        for a description of the file format.
        <import_file> - the import file location.
        <create_new_users>
              If TRUE, users only existing in the import file will be newly
              created, otherwise ignored.

    batch-import-internal-users <import_file> <overwrite_existing_passwords>
                                <overwrite_existing_pins>
        Import the internal users contained in the given tab-delimited import
        file.  See the user manual chapter 'Managing Guests and Internal Users'
        for a description of the file format.
        <import_file> - the import file location.
        <overwrite_existing_passwords> (optional, default TRUE) - (TRUE or
              FALSE) If TRUE, passwords from the import file will overwrite
              existing passwords where a user already has a has a password set.
              If FALSE, existing passwords will not be changed.
        <overwrite_existing_pins> (optional, default TRUE) - (TRUE or FALSE) If
              TRUE, PINs from the import file will overwrite existing PINs where
              a user already has a has a PIN set.  If FALSE, existing PINs will
              not be changed.

    batch-import-user-card-id-numbers <import_file> <overwrite_existing_pins>
        Import the user card/ID numbers and PINs contained in the given
        tab-delimited import file.  See the user manual chapter 'Advanced User
        Management' for a description of the file format).
        <import_file> - the import file location.
        <overwrite_existing_pins> (optional, default TRUE) - (TRUE or FALSE) If
              TRUE, PINs from the import file will overwrite existing PINs where
              a user already has a has a PIN set.  If FALSE, existing PINs will
              not be changed.

    create-user-client-accounts-file
        Saves a file containing shared accounts data for the user client.
        See the manual for more information on how this feature can be used.
        The file will be saved on the server to the location:
            [app-path]\server\data\client\client-accounts.dat

        If this file already exists it will be over-written.

    get-config <config-name>
        Gets the value of the given config value printing the result.
        If the config value does not exist, a blank string is displayed.
        <config-name> - the name of the config value to get.

    set-config <config-name> <config-value>
        Sets the value of the give config item.
        NOTE: Take care updating config values. You may cause serious
              problems which can only be fixed by reinstallation of
              the application. Use the set-config command at your own risk.
        <config-name> - the name of the config value to set.
        <config-value> - the value to set.

    process-job <job-details>
        Takes the details of a job and logs and charges as if it were a "real"
        job.  Jobs processed via this method are not susceptible to filters,
        pop-ups, hold/release queues etc., they are simply logged.  See the user
        manual section "Importing Job Details" for more information and the
        format of <job-details>.
        <job-details> - the details of the job to log.

    run-command command-name [command args]
        Runs a custom command on the server. By default the server does not
        include any custom commands.  The command arguments depend on the custom
        command being run.
                

Tip

server-command is ideal for scripting via batch files or shell scripts. Some example scripts can be found at [app-path]/server/examples/scripting/.

Administrators wishing to control PaperCut NG using a programming language such as C#, Java, Visual Basic, Perl, Ruby or Python should consider the XML Web Services APIs. All commands available via the server-command tool are also accessible via calls to the Web Services layer.

More information on the XML Web Services API is available in the section called “The XML Web Services API”.

Tip

Checking for errors: generally server-command will return an exit value of 0. When writing your script you should check the string value that server-command prints on standard output instead. server-command will return a non-zero return value if it detects an error with the parameters passed on the command line.

Tip

Some commands (e.g. batch-import-internal-users) expect values that are true or false. In this case the command parameter is compared to the value true using a case insensitive compare, all other values are assumed to be false.