19
Using Equitrac Utilities
Topics
Enabling SSL Communication
Import Utilities
Import Campus Card Account Information
Directory Synchronization Access Permissions
Purge Database Transactions
Modifying User Accounts from a Flat File
Refining the User Group View
Map LPR User IDs
Creating Trusted Certificates
Print Queue Viewer
Logging
Equitrac Office and Express provide several different utilities that can help you speed up the time spent on configuration tasks. This chapter contains instructions to run some of these utilities. Instructions to use other utilities are located throughout this guide in the appropriate location. Use the table below to locate instructions for running all
Equitrac utilities.
Utility
CampusCardImport.exe
(for Equitrac Express)
CardSwipeWizard.exe
EQAcctMonitor.exe
EQAccountRegroup.exe
EQCmd.exe
Description See Page
Imports Campus Card account information into the
CAS database.
Import Campus Card Account
Information
on page 474
Determines the encoding and data positions on magnetic or proximity cards.
Runs within the System Tray on user workstations to provide account balance information.
Determining Code Start and
Stop Positions – Known Codes
on page 175
Configuring the Account
Monitor Popup
on page 260
Filters the User Group view when managing a large account base.
Refining the User Group View
on page 484
Adds, deletes, modifies or query user, department and billing code accounts from a flat file.
Modifying User Accounts from a Flat File
on page 477
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 471
EQ-AG-5.7-20160921
Chapter 19: Using Equitrac Utilities
Utility
EQEnableSSL.exe
EQKIPImport.exe
EQLRSVPSXImport.exe
EQModifyDeletedContainer
Security.exe
EQPDToolTray.exe
EQRightFaxImport.exe
EQRptload.exe
EQSAPImport.exe
EQSSLCertificateManager.exe
EQTransactionPurge.exe
EQToolTray.exe
EQXLPD.exe
EQXWinConfig.exe
Description See Page
Enables/disables SSL (Secure Socket Layer) communication between Equitrac services and clients
A command line utility to import KIP plot transaction data into CAS.
Enabling SSL Communication
on page 473
Import Utilities
on page 473
A command line utility to import transactions from
LRS.
Import LRS Transactions
on page 63
Changes the administrative access permissions on the deleted objects container in a Windows Active
Directory.
Directory Synchronization
Access Permissions
on page 475
Enables Print Distribution when installed and running on a user workstation.
Send To Printing Configuration
Workflow
on page 312
Imports RightFax records into CAS.
Import Utilities
on page 473
Adds a custom logo to generated reports, or uplink reports to the master CAS.
Customizing Standard Reports
on page 366
Imports SAP records into CAS.
Import Utilities
on page 473
Installs trusted certificates to use with Equitrac services.
Purges transactions from the database.
Creating Trusted Certificates
page 490
on
Purge Database Transactions
on page 476
Enables/disables the billing code prompt on a workstation.
Disabling Billing Code Popups
on page 199
Modifies incoming LPR print job IDs to match User
IDs within the Equitrac database
Map LPR User IDs
on page 486
Modifies device configuration settings.
Embedded Devices
on page 56
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 472
Chapter 19: Using Equitrac Utilities
Enabling SSL Communication
Communication between Equitrac components running in a Windows environment can utilize SSL (Secure Socket
Layer) if required. To enable this feature, run the EQEnableSSL.exe utility located in the Program
Files\Equitrac\Office
or Express\Tools folder.
NOTE: EQEnableSSL.exe must be run on every system running Equitrac software that uses an SSL connection. (e.g.
CAS, DRE, DCE). Shutdown all Equitrac services and utilities (e.g. System Manager) before running this command.
The command-line utility accepts the following command:
EQEnableSSL.exe [-e -d –h]
Listed in the table are the values for each letter:
-d
-h
Value
-e
Description
Enables SSL communication from this system.
Disables SSL communication from this system.
Displays this help screen.
No parameters display the current settings.
NOTE: For compatibility reasons, management communications are not currently encrypted even if this feature is
enabled. Non-Windows DREs do not support encrypted connections.
Import Utilities
Equitrac Office and Express also comes with several import utilities for integration with external applications. All import utilities require an External Data Sources license. The installer places the utility files and instructions on the
CAS server in the Tools and Docs folders respectively.
The following table lists the available import utilities along with a description for each.
Utility
EQRightFaxImport.exe
EQSAPImport.exe
EQKIPImport.exe
DeviceImportTool.exe
Description
A command line utility to import RightFax transaction data into CAS.
A command line utility to import SAP print transaction data into CAS.
A command line utility to import KIP plot transaction data into CAS.
A command line utility to import a device into Equitrac Office and Express.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 473
Chapter 19: Using Equitrac Utilities
Import Campus Card Account Information
This Equitrac Express features allows Campus Card account information to be imported into the CAS database and make CAS account assignments, use the CampusCardImport.exe utility located in the Tools subfolder of the Equitrac
Express installation folder (usually Program Files\Equitrac\Express\Tools).
Create a CSV file that contains raw swipe data collected by the Card Swipe wizard and the Windows account name or
User ID of a CAS account (one per line).
For example:
12345,johndoe
NOTE: If the Campus Card system being used (e.g. Blackboard and CBORD) does not provide an export feature to
generate the CSV file, you must create it manually.
From any directory on the Core Accounting Server, type the command:
CampusCardImport.exe -f filename [-c] where -f filename is the CSV file to import (including the path to the file). The optional -c cleans old account records on CAS before importing the file.
This command imports the specified file into the Equitrac Express database.
Importing Domain Qualified Users
The Campus Card Import utility recognizes the "\" symbol as an escape character and removes the "\" separator in domain qualified user names. In order to import domain qualified users, you need to use "\\" as the separator.
For example, the domain qualified user: my_domain\johndoe should be specified in the import file as: my_domain\\johndoe
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 474
Chapter 19: Using Equitrac Utilities
Directory Synchronization Access Permissions
EQModifyDeletedContainerSecurity.exe
changes the administrative access permissions on the deleted objects container in a Windows Active Directory, so that Equitrac Office and Express can access the objects during directory synchronizations.
By default, only Active Directory administrators have access permission. The Windows account running the Equitrac services need this access if you wish to synchronize deleted accounts between Active Directory and Equitrac Office and Express. The account running the EQModifyDeletedContainerSecurity.exe command must be an administrator in the Active Directory domain.
See
Importing Users with Active Directory Services
on page 219 for more information on configuring Active
Directory Synchronization options.
Equitrac Office and Express installs this utility on the accounting server in the Program Files\Equitrac\Office or
Express\Tools
folder.
The command-line utility accepts commands in the following format:
EQModifyDeletedContainerSecurity.exe <-s server> [-p | (-r -un -pw) -a accountname]
Parameters enclosed in parentheses < > are mandatory; parameters within square brackets [ ] are optional.
Parameter
-s server
-p
-r
- a accountname
-un username
-pw password
Description
Server name of the Active Directory domain controller.
Display current permissions on the container.
Remove access permissions for the specified accountname.
Account to be granted access to the container. Access permission is removed if specified with the
-r option.
Optional Authentication Admin UserName Credentials.
Optional Authentication Admin Password Credentials.
You can add the credentials of a user who has rights to bind to the Active Directory database with the –un/-pw parameters when connecting to either a remote domain controller where there is a two-way trust between the CAS domain and the domain where the specified AD database exists, or when connecting to a domain where there is no trust setup. This can also be done with a local domain controller, however, this is typically not necessary.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 475
Chapter 19: Using Equitrac Utilities
-o
-d
-i
-e
-u
-m
-s
Purge Database Transactions
The EQTransactionPurge.exe utility purges transactions from the database.
Equitrac Office and Express install this utility on the accounting server in the Program Files\Equitrac\Office or
Express\Tools
folder.
The command-line utility accepts commands in the following format:
EQTransactionPurge.exe [-f] [-e [n] ] [-u] [-m] [-s] (-o n | -d yyyy-mm-dd | -i
NNNNN) [-t]
Parameters enclosed in parentheses < > are mandatory; parameters within square brackets [ ] are optional.
Parameter Description
-t
Exclusive force execution of transaction purge by chunks of n (5000 - default).
Purge from uplink tables.
Purge from DME usage tables.
Purge from SDR usage tables.
Purge transactions more than n days old.
Purge transactions from present date, minus 24 hours.
Purge a single transaction where NNNNN is a 32 digit transaction ID. The transaction ID can be viewed by running any detailed activity report and using the Configure report layout option to display the Document
ID column.
Enable trace logging.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 476
Chapter 19: Using Equitrac Utilities
Modifying User Accounts from a Flat File
Use the EQCmd.exe utility to add, delete, modify and query user, department and billing code accounts from a flat file. You can also assign users and departments to billing codes. This method is a one-time import and does not synchronize data beyond the import.
Equitrac Office and Express install this utility on the accounting server in the Program Files\Equitrac\Office or
Express\Tools
folder.
The command-line utility accepts commands in the following format:
EQCmd -s<Server> <Action> <Obj_type> <Obj_ID>|All [<Options>]
Execute the command with a batch file:
EQCmd -s<Server> -f<BatchFile>
Command-line parameters enclosed in parentheses < > are mandatory and require a specified value. Parameters within square brackets [ ] are optional entries and do not need to have a specified value if they will not be included in the command. Optional parameters that will be in the command, do require a specified value.
Equitrac Office and Express accepts CSV files as batch files. Batch operation allows all the command actions except for the “query” command. Use the table below to fill in the parameters.
Parameter
Server
Action
Obj_type
Obj_ID
Variables
Specify the name or IP address of CAS.
Specify the action to take on the account. Use one of:
• add - Add user, department and billing code.
• assign - Assign a billing code to a user or a department.
• delete - Delete user, department or billing code. It does not use <details> parameter.
• remove - Remove the association between billing code and user or department.
• query - Query database. Output differs based on <Obj_type>.
• modify - Modify an object attribute.
• adjust - Adjust the balance for user, department and billing code; set a new balance to a object type or set a balance no less than a certain amount.
• lock/unlock - Lock or unlock a user, department or billing code.
• quota - sets the color pages quota to a set amount for a single user or all users within a department.
Use one of:
• ur - user
• dp - department
• bc - billing code
Applies
<action> only to the specified object ID. Use double quotes around object IDs that have a space, for example human resources. To apply
<Action> to all accounts of <Obj_type>, use All.
Note: You can use “All” for “Assign”, “Remove”, “Query”, “Adjust” actions. You cannot use it for “Add”,
“Delete”, “Modify”, “Lock” and “Unlock” actions.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 477
Chapter 19: Using Equitrac Utilities
Parameter Variables
Options for Action
Command
Specify additional values.
•
<init_bal> - Initial account balance
•
<min_bal> - Minimum account balance
•
<desc> - Description
•
<user_id> - User ID
•
<user_name> - Full user name
•
<dept_name> - Department name
•
<bc_name> - Billing code name
•
<email> - User email
•
<amount> - Amount of balance value. The value can be both positive (+) and negative (-)
•
<quota> - User color quota
•
<primaryPIN> - User Primary PIN
•
<secondaryPIN> - User Secondary PIN and Confirm Secondary PIN
•
<alternatePIN> - Alternate to user Primary PIN
•
<home_server> - DRE print server
•
<locked> - User account is locked
•
<location> - Location of the user
•
<delegate_id> - Delegate user ID
•
<default_bc> - Default billing code
•
<additional_info> - Additional information about the user
•
<home_folder> - User home scan folder as a full network location (UNC path). It is used as a destination folder for scan processing
EQCmd Actions
Add
Parameters within the square brackets [ ] must contain values up to and including the final field needed. For example, if the final field is <primaryPIN>, all fields to the left must have a specified value—those to the right can be excluded from the command. If you want to leave a field blank (i.e. skip a field), enter 0 (zero) to indicate an empty value. Use double quotes around values that have spaces. Specify monetary amounts with a period for the decimal separator.
Add a user: add ur <user_id> [<init_bal> <user_name> <min_bal> <email> <dept_name> <primaryPIN>
<secondaryPIN> <quota> <alternatePIN> <home_server> <locked> <location> 0
<additional_info> <home_folder>]
Example: EQCmd -sMyServer add ur JohnD 35.50 “John Doe” 25.00 [email protected]
Accounting 123 456 20 321 WATSRV lock Waterloo 0 UserX_folder
Add a department: add dp <dept_name> [<init_bal> <desc> <min_bal> <primaryPIN> <secondaryPIN>]
Add a billing code: add bc <bc_name> [<init_bal> <desc> <min_bal> <primaryPIN> <secondaryPIN>]
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 478
Chapter 19: Using Equitrac Utilities
Assign
Assign a user to a billing code or all available billing codes: assign ur <user_id> <bc_name>|All
Example:
EQCmd -sMyServer assign ur johnd billing1
Assign a user to a default billing code: assign ur <user_id> <default_bc>
Example:
EQCmd -sMyServer assign ur johnd billing1-d
(where the "-d" represents default)
Assign a department to a billing code or all available billing codes: assign dp <dept_name> <bc_name>|All
Example:
EQCmd -sMyServer assign dp hr billing1
Assign a delegate to a user: assign dlg <user_id> <delegate_id>
Assign a user to a department or all available departments in Department Manager: assign mgr <user_id> <dept_name>|All
Delete
Delete a user: delete ur <user_id>
Delete a billing code: delete bc <bc_name>
Delete a department: delete dp <dept_name>
Example: delete HR department accounts:
EQCmd 127.0.52.1 delete dp hr
Remove
Remove an association between a user and a billing code or all available billing codes: remove ur <user_id> <bc_name>|All
Remove an association between a user and a default billing code: remove ur <user_id> <default_bc>
Example: EQCmd -sMyServer remove ur johnd billing1-d (where the "-d" represents default)
Remove an association between a department and billing code or all available billing codes: remove dp <dept_name> <bc_name>|All
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 479
Chapter 19: Using Equitrac Utilities
Remove an association between a user and a department or all available departments in Department Manager: remove mgr <user_id> <dept_name>|All
Remove an association between a user and a delegate or all available delegates: remove dlg <user_id> <delegate_id>|All
Query
Displays results from query database. Query is only allowed from the command prompt, not in a .csv file batch operation.
Query a user: query ur <user_id>|All
It displays: user_id Full_name Email Balance Limit Dept Status
Query a department: query dp <dept_name>|All
It displays: dept_name Desc Balance Limit Status
Query a billing code: query bc <bc_name>|All
It displays: bc_name Desc Balance Limit Status
Modify
Modifies the database settings for user, department and billing code.
Modifying requires values up to and including the final modified field. For example, if the final field is <email>, all fields to the left must have a specified value—those to the right can be excluded from the command. Insert an “!” for the fields to the left that you do not want to change. Any unmodified field after <email> can be left blank except for
<dept_name>. If the department name variable is left blank, the user is removed from that department.
Modify a user: modify ur <user_id> [<user_name> <min_bal> <email> <dept_name> <primaryPIN>
<secondaryPIN> <quota> <alternatePIN> <home_server> <locked> <location> <default_bc>
<additional_info> <home_folder>]
Example: Update email address of user johnd and keep the rest of the information:
EQCmd -sMyServer modify ur johnd! ! [email protected] !
Modify a department: modify dp <dept_name> [<desc> <min_bal> <primaryPIN> <secondaryPIN>]
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 480
Chapter 19: Using Equitrac Utilities
Modify a billing code: modify bc <bc_name> [<desc> <min_bal> <primaryPIN> <secondaryPIN>]
Modify the user default billing code: modify ur <user_id> <default_bc>
Example:
EQCmd -sMyServer modify ur johnd billing1-d
(where the "-d" represents default)
To lock a user, set the
<locked> value to "1". To unlock a user, use the unlock ur <user_id>
command. See
Lock and Unlock
on page 482 for details.
Adjust
Allows the administrator to adjust the balance for a certain object type. Adjust has three formats:
...adjust <Obj_type> <Obj_ID>|All <amount>
...adjust <Obj_type> <Obj_ID>|All set <amount>
...adjust <Obj_type> <Obj_ID>|All atleast <amount>
adjust … <amount>
Allows the administrator to adjust a balance to an object type. When adjusting the user balance, there is also a description field to state what the adjustment was regarding. Use double quotes around the description, with a maximum string length of 225 characters.
Adjust a user balance: adjust ur <user_id>|All <amount> <description>
Adjust a department balance: adjust dp <dept_name>|All <amount>
Adjust a billing code balance: adjust bc <bc_name>|All <amount>
Example: adjust user balance by $50.00 with a description of the adjustment
EQCmd -sMyServer adjust ur johnd 50 ”deposit funds”
adjust … set <amount>
Allows the administrator to set a new balance to an object type. When adjusting the user balance, there is also a description field to state what the adjustment was regarding. Use double quotes around the description, with a maximum string length of 225 characters.
Set a new balance to a user: adjust ur <user_id>|All set <amount> <description>
Set a new balance to a department: adjust dp <dept_name>|All set <amount>
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 481
Chapter 19: Using Equitrac Utilities
Set a new balance to a billing code: adjust bc <bc_name>|All set <amount>
adjust … atleast <amount>
Allows the administrator to set the object balance value no less than a certain amount. For example: if a user current balance is $10.00, if the administrator set atleast amount $5.00, the user's new balance is still $10.00; if the administrator set the atleast amount $15.00, then the user's new balance is changed to $15.00.
Atleast a user account: adjust ur <user_id>|All atleast <amount> <description>
Atleast a department: adjust dp <dept_name>|All atleast <amount>
Atleast a billing code: adjust bc <bc_name>|All atleast <amount>
Adjust Department
The adjdept parameter adjusts the account balance of all users in a particular department. This command does not set the overall department balance. It adjusts the balances of users belonging to the department by adding or adjusting the account balance. adjdept dp <dept_name> <amount>
As depicted in the examples below, two additional parameters may be used ( set
and atleast
). If neither set
nor atleast
are used, the amount is added to each user's account in the department. If you use the set
parameter, each user account belonging to the department is adjusted to the set
amount whether the account balance is above or below that amount. If the atleast
parameter is present, account balances below the atleast
amount are adjusted up, but accounts balances above the atleast
amount are not adjusted.
Example1: Add $500 to all user account balances in the Marketing department:
EQCMD -sMyServer adjdept dp Marketing 500.00
Example 2: Set all user account balances in the Marketing department to $500:
EQCMD -sMyServer adjdept dp Marketing set 500.00
Example3: Ensure all user account balances in the Marketing department are at least $500:
EQCMD -sMyServer adjdept dp Marketing atleast 500.00
Lock and Unlock
Allow the administrator to lock/unlock a user, department or a billing code.
Lock a user: lock ur <user_id>
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 482
Chapter 19: Using Equitrac Utilities
Lock a department: lock dp <dept_name>
Lock a billing code: lock bc <bc_name>
Unlock a user: unlock ur <user_id>
Unlock a department: unlock dp <dept_name>
Unlock a billing code: unlock bc <bc_name>
Color Quota
Use the following syntax to reset color quotas. The first string resets the quota for a specific user ID, and the second string resets the quota for all users within a specified department.
EQCmd.exe -s<CASServer> quota ur <UserID>|All <newquota|reset>
EQCmd.exe -s<CASServer> quota dp <DeptName> <newquota|reset>
Use a newquota value of -1 (minus 1) to set an unlimited quota.
EQCmd Batch File Process
EQCmd has a batch mode. It accepts a CSV file as an batch file, one file per server.
For Equitrac Office:
[Equitrac Office\Tools file path]\EQCmd –s<Server> –fBatchFileName.csv
For Equitrac Express:
[Equitrac Express\Tools file path]\EQCmd –s<Server> –fBatchFileName.csv
NOTE: Copy the .csv file to the Equitrac Office or Equitrac Express > Tools folder.
CSV File Format
<Action>, <Obj_type>, <Obj_ID>|All, [<Details>]
CSV File Sample
Test.csv file: Create an R&D department and add two users.
add, dp, R&D add, ur, user1, “10.00”, Sample, “1.00”, [email protected], R&D add, ur, user2, “10.00”, Sample, “1.00”, [email protected], R&D
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 483
Chapter 19: Using Equitrac Utilities
Refining the User Group View
For large installations, you may have a large-enough account base that the User Group view does not provide a sufficiently refined view of the user or billing code accounts. Equitrac Office and Express include a command line utility to divide the group listing into smaller sections or sub-sections for easier viewing.
On the CAS server, open a command prompt, and go to the Program Files\Equitrac\Office or Express\Tools folder then type the following command and replace the variables with appropriate values:
EQAccountRegroup [-sCASName] [-f filename] [-q] -t accounttype [-g groupmaxsize]
[-l refinedgroupminimum]
-s identifies the core accounting server hosting the accounts you wish to view.
Argument
-t
-s
-f
-q
-g
-l
Result
required argument that identifies the type of account listing you want to view:
• use
-t bc for billing codes
• use
-t ur for user accounts
Optional argument that identifies the core accounting server hosting the accounts
If you run the command on the CAS server, you do not need to enter this argument.
Identifies the output path for the command log file
Example: diagnostics.txt
Hides error details from the console
Specifies the limit when the subgroups appears in Accounts Manager.
Example:
-g 1500 shows the users in the normal view until the number of users reaches 1500.
Specifies the number of users within the subgroups.
Example:
-l 100 list at most 100 users in each subgroup
The following example illustrates the overall usage of the command.
Subgroup after
20,000 accounts
EQAccountRegroup -sBora -f diagnostics.txt -t ur -g 20000 -l 100
CAS Output Path
User
Accounts
100 users in each subgroup
The command is invoked on the CAS called Bora, with the command log saved to a file called diagnostics.txt. The user accounts are grouped, and if there are more than 20,000 user accounts, the tool splits them into viewable groups of 100.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 484
Chapter 19: Using Equitrac Utilities
When you open the User group view dialog box, Equitrac Office and Express sorts the list alphabetically. Using this example, if there are less than 20,000 users, only views based on first character (0-9, A-Z) are available. When there are
20,000 or more users then the refined groupings are available. The refined groups in this example list at most 100 accounts, though not necessarily 100 accounts in each group.
The refinements are based on first character groups that have over 100 accounts. If a first character group has 100 accounts or less, it is not further refined. For example if there are 99 users with names starting with B, then the tool does not refine the view of the B accounts. If there are 200 accounts starting with B, then there are two sub-groups of
Bs available in the refined view.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 485
Chapter 19: Using Equitrac Utilities
Map LPR User IDs
The EQXLPD utility extends the existing Equitrac Office and Express functionality to modify the User IDs associated with incoming LPR print jobs. If the format of the LPR print job User ID does not match the IDs used in the Equitrac database, you can use this utility to modify incoming IDs to match existing Equitrac IDs.
For example, if the LPR jobs arrive in the format “[email protected]”, Equitrac will not associate the user with a corresponding ID in the Equitrac database. You can use this utility to remove the domain information, thereby mapping the LPR job ID with a User ID that Equitrac Office and Express expects.
CAUTION: This utility requires a dedicated External Data Sources license. This license must be applied within System
Manager prior to running the executable.
Installing EQXLPD
The EQXLPD tool is available from the Equitrac Installer, under the Auxiliary Applications sub-folder. It is not selected in the Installer by default. Click on EQXLPD, and select This feature is installed on local hard drive.
When installed, the tool is located under Program Files\Equitrac\Office or Express\Tools\EQXLPD. There are two files in this folder:
• eqxlpd.cfg – specifies the actions that are applied when EQXLPD.exe is run
• EQXLPD.exe – maps or modifies User IDs for incoming LPR print jobs
The EQXLPD service is not started automatically after installing Equitrac Office or Express. You must run the
EQXLPD.exe within the command-line utility to add it to the Administrative Tools > Services application, and then configure the service to start automatically. See
Starting the EQXLPD Service
on page 489. However, before starting
the service, you must first modify the configuration file.
Modifying the Configuration File
on page 487.
CAUTION: Only one service can “listen” on the printer at a time. If the Microsoft LPD service is running, the EQXLPD
service is blocked. To determine if a service is running on the printer port, open the command line utility and type
telnet localhost 515. If the result is “connection refused”, no other service is running, and you can proceed with
EQXLPD. If a connection is made, another service is already running, and you must stop it before proceeding.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 486
Chapter 19: Using Equitrac Utilities
Modifying the Configuration File
Prior to running the executable, modify the configuration file to change the User ID mappings. Supported
configuration parameters are listed in the table below. See an
Obtaining Debug Logs
on page 489.
Parameter
Spooling: SpoolDir
LPQ-status: Banner
Username:
IncludeIPAddress
UserName:
RegExPatterns
Description
• Directory for the spooled LPR files
• Banner text for the LPQ status queries
• If the IP Address is appended to the user ID
• 1 = do not append; 0= append
• The default value is 1, or do not append
• The number of POSIX regular expression patterns to apply to each user ID
• The actual POSIX expression patterns are placed in the
Username-Regex parameter listed below
• If the configuration file contains more expressions than this value is set to, the remaining expressions are ignored. For example, if this value is set to 3, but there are 5 expressions in the configuration file, only the first
3 expressions are applied.
Example
[Spooling]
SpoolDir=c:/temp
[LPQ-status]
Banner="LPD server"
[UserName]
IncludeIPAddress=1
[UserName]
RegExPatterns=3
UserName:
IgnoreCase
UserName:
RefuseUnMapped
• If case-sensitivity is enabled or disabled
• 1 = ignore case; 0 = case-sensitive
• If print jobs from unmapped user IDs are refused or allowed
• 1 = allowed; 0 = refused
[UserName]
IgnoreCase=1
[UserName]
RefuseUnMapped=1
Username-Regex • Defines the POSIX expressions that are applied to each
User ID
• Each expression must include a From value and a To value. These values determine the User ID to start with, and the User ID to stop at when applying the expression.
• Supported characters include "\" to rearrange values,
"|" to ??, and "^" to indicate the start of a string??.
Placing the syntax within brackets captures a pattern.
• Example 1 to the right matches any number of digits at the end of each User ID and removes the digits. The
From value is set to 1 and the To value is also set to 1 to apply the expression to all User IDs.
• Example 2 examines all User IDs for the sequence
"ababa" and replaces the sequence with "babab".
Ex 1
[UserName]
RefuseUnMapped=1[UserName-
Regex]
From1=[0123456789]*$
To1=
Ex 2
[UserName-Regex]
From1=ababa
To1=babab
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 487
Chapter 19: Using Equitrac Utilities
Parameter
Username-Regex
(continued)
Username-Map
Printers
Description Example
• Example 3 starts examining UserIDs with ID 2, then looks for all instances of the @ symbol. The expression then swaps all information before the @ symbol to the end. For example, "[email protected]" is mapped to "company\person"
• Example 4 examines all User IDs, then strips out all characters located after a period, up to and including the colon. This expression can be used to strip out a username suffix for example. All characters to the left of the period are left untouched.
Ex 3
[UserName-Regex]
From2=^(.+)@([^.]+)(\..*)?$
To2=\2\\\1
Ex 4
[UserName=Regex]
From1=^.*:
To1=
• Mapping of disparate User IDs from LPR to match User
IDs in Equitrac database
• Use this setting to support a cluster.
• The LPR command to print job.txt is
LPR-S VirtualServer1-PrinterA job.txt
• In the cluster, EQXLPD is set up like EQDRE service.
• An identical CFG is required on each node.
• In the example, PrinterR is the real printer, and PrinterA is an alias and does not exist as a real queue. EQXLPD picks up the LPR print job and looks up the mapping to send the job to the real printer.
[UserName-Map]
AlfredN=aneumann
BobL=blyndham
[Printers]
PrinterA=\\VirtualServer1\
PrinterR
Example Configuration File
The following example shows the default configuration file that is installed with EQXLPD. Follow this example to ensure you are using the correct formatting.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 488
Chapter 19: Using Equitrac Utilities
Starting the EQXLPD Service
The EQXLPD.exe must be run in the command-line utility as an Administrator to add it to the Administrative Tools >
Services application. From the Services application, you can configure how the service starts.
To start the EQXLPD service, do the following:
1
2
3
4
5
6
7
Go to Windows\System32, right-click cmd.exe and select Run as Administrator from the menu.
In the command line type the following:
Tools\EQXLPD\EQXLPD.exe /Service
.
Select Start > Control Panel > Administrative Tools > Services.
Right-click the EQXLPD Service in the right pane and select Properties from the menu.
On the General tab, set the Startup type as Automatic (Delayed start), Automatic, or Manual.
On the Log On tab, ensure that Local System account is selected.
Click Start, and click OK to save the changes.
Obtaining Debug Logs
If the EQXLPD service fails to start, the case name may be incorrect, CAS is unable to find an unallocated External
Data Sources license, or the user is not mapped to the correct Equitrac account. You can check the debug log to determine the source of the problem.
To produce a debug log, do the following:
1
2
3
4
Select Start > Control Panel > Administrative Tools > Services.
Right-click the EQXLPD Service in the right pane and select Properties from the menu.
On the General tab, enter /Debug in the Start parameters field.
Restart
the service, and click OK to save the changes.
The resulting file is named eqxlpd.dbg and is located in the temporary directory of the account running the service. To end the log, you need to Stop the service. You can examine the file to determine if the mapping is performed correctly without waiting for the entire process to finish. Remove /Debug from the Start parameters when you no longer need to generate a debug log.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 489
Chapter 19: Using Equitrac Utilities
Creating Trusted Certificates
A certificate is requested whenever a user logs into any Equitrac web-based tool that uses SSL such as Dashboard
Reports. When you install an Equitrac service, a self-signed certificate is created. The disadvantage of a self-signed certificate is that end-users are prompted to accept the certificate the first time they access a web-based Equitrac tool.
There is no such prompt for a trusted certificate.
EQSSLCertificateManager.exe is located in the Program Files\Equitrac\Office or Express\Tools folder on any machine where Equitrac administration tools have been installed. This tool is designed to assist an administrator in replacing automatically generated self-signed certificates with certificates signed by a trusted certificate authority.
To replace the self-signed certificate, do the following:
1
2
3
Generate a certificate request using EQSSLCertificateManager.
Obtain a trusted certificate.
Accept the certificate file using EQSSLCertificateManager.
EQSSLCertificateManager must be run on each server that is running Equitrac’s CAS service. If you are using the Web
Release Station, then EQSSLCertificateManager must also be run on the DCE service. When running the tool, two self-signed certificates may show up for the machine: one with a fully qualified DNS name (e.g. eqserverx.ee41) and one with an unqualified machine name (e.g. eqserverx).
The certificate with the unqualified name is left over from previous versions of the Equitrac software; newer versions of the software use fully qualified names in the certificates. The older certificate may be deleted as it is not used by the newer software.
After upgrading to Equitrac Office or Express software version 5.7, you may be asked to accept the new fully qualified self-signed certificates.
CAUTION: The maximum length of the host name and of the fully qualified domain name (FQDN) is 63 bytes per label
and 255 bytes per FQDN. Microsoft Windows does not permit computer names that exceed 15 characters, and you cannot specify a DNS host name that differs from the NETBIOS host name.
Select the Authorized User Account
Before running EQSSLCertificateManager, you need to select the user account under which the Equitrac services are running.
To select the user account to run EQSSLCertificateManager, do the following:
1
2
3
4
Open the Program Files\Equitrac\Office or Express\Tools folder.
Right-click the EQSSLCertificateManager.exe file and select Run as from the menu.
Select The following user option, and enter the User name and Password of the user account you want to run the program.
Click OK to save the setting.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 490
Chapter 19: Using Equitrac Utilities
Generate the Certificate Request
To create a certificate request to replace a self-signed certificate, do the following:
1
2
Open the Program Files\Equitrac\Office or Express\Tools folder and run EQSSLCertificateManager.exe.
Select the self-signed certificate with the fully qualified DNS name, and press Create Certificate Request.
The Create Certificate Request dialog box opens. The Subject field is pre-populated with an appropriate value
(typically CN=dnsname where dnsname is the fully qualified dns name of the computer).
3
4
Select the Key size from the drop-down list according to the site’s policy.
Press OK and save the .req file (request). The .req file can be saved in any location on your system, as it is only used to obtain a trusted certificate.
NOTE: Some certificate authorities require more than just the DNS name component to appear in the Subject field. To
create certificate requests for such certificate authorities, manually specify the subject name in a format similar to the following: CN=ServerName.domain, OU=OrganizationUnit, O=Organization, L=Location, S=State, C=Country.
Obtain a Trusted Certificate
Submit the .req file to a trusted CA (Certification Authority). The CA can be a locally implemented Microsoft Stand-
Alone CA or a third party CA. The CA provides a trusted certificate file (.cer or .crt). It is recommended that you save the certificate file in the same location as the request file.
Accept the Trusted Certificate File
Run EQSSLCertificateManager, and press Accept Certificate. Select and open the trusted certificate file.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 491
Chapter 19: Using Equitrac Utilities
Cluster Configuration
In order to use the same certificate in a cluster environment, the certificate file must be installed on every cluster node where the services run on. To generate certificate-authority-signed certificates for all relevant virtual servers and replicate those certificates to all nodes in the cluster, do the following:
1
2
3
4
5
6
7
Move all Equitrac resource groups onto the same cluster node, and bring them online. This causes a self-signed certificate to be created on that node for all virtual servers (failover cluster instances) that the Equitrac services use.
Run EQSSLCertificateManager on that node.
For each certificate displayed, do the following: a b c d
Select the self-signed certificate.
Press Create Certificate Request.
Submit the certificate request to a CA (certificate authority) to obtain a trusted certificate file.
Press Accept Certificate, and open the certificate file.
Press Export All Certificates. a
Enter a self-assigned password to protect the private keys that are exported with the certificates. b
Click OK, and save the equitrac-certificates.pfx file. It is recommended that you save the .pfx file in the same location as the trusted certificate file for easy retrieval.
On each of the other cluster nodes, run EQSSLCertificateManager and press Import Certificates.
a b
Select and open the equitrac-certificates.pfx file.
Enter the password, and click OK.
Close EQSSLCertificateManager.
Take all Equitrac resource groups offline, then bring them back online through Cluster Administrator to begin using the new trusted certificates.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 492
Chapter 19: Using Equitrac Utilities
Print Queue Viewer
The Print Queue Viewer provides a tool for Administrators to view and delete documents within the secure print queue. Each DRE has its own print queue, and therefore its own Viewer. If you deployed multiple DREs you can run multiple Viewers at the same time. You must specify the print server (DRE) you want to connect to when you launch the Viewer.
The Print Queue Viewer utility is installed as part of the management tools when Equitrac Office or Express is installed on your system.
The EQPrintQueueViewer.exe file is placed in the Program Files\Equitrac\Office or Express\Tools folder, and a shortcut is created in the Equitrac Office and Express group under the Windows Start menu.
To open the Print Queue Viewer, do the following:
1
2
On your Windows desktop, go to Start > All Programs > Equitrac Office or Equitrac Express > Print Queue
Viewer
. This creates the Viewer icon in the Windows task tray.
Double-click the icon to open the Print Queue Viewer.
3
4
Click any document in the list to select it. Hold down SHIFT or CTRL to select multiple documents in the queue.
You can sort documents in the list by clicking any of the column headings visible in the Viewer.
To delete selected documents from the queue, press the Delete key or choose Delete from the Document menu.
Select View > Simple view or View > Full view to change the default view depending on how many document details you want to display.
NOTE: Start the Print Queue Viewer with the
-s
option to customize Viewer’s visible columns. Select View > Custom
view, and then select View > Select columns to select or clear columns as desired.
Select View > Hide to close the Viewer without shutting down the service. The Viewer icon remains visible in the
Windows Task tray. Use the Refresh option to update the Viewer document list while the Viewer is open; the list does not refresh automatically.
To shut down the service, right-click the icon in the task tray and select Exit. You can also select Show/Hide to open or close the Print Queue Viewer window.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 493
Chapter 19: Using Equitrac Utilities
Running Print Queue Viewer on a Workstation
To run the Print Queue Viewer application on a workstation, choose one of the following options:
• Use Equitrac Installer with one of the management tools, such as System Manager.
The EQPrintQueueViewer.exe file is placed in the Program Files\Equitrac\Office or Express\Tools folder, and a shortcut is automatically created in the Equitrac Office and Express group under the Windows Start menu.
—Or—
• Copy the EQPrintQueueViewer.exe file to the workstation.
When manually copying EQPrintQueueViewer.exe you need to run it with the -s<DRE_server> option if you want to customize the Print Queue Viewer columns, and to view other user’s print jobs.
If the -s<DRE_server> option is not used, then the Print Queue Viewer only shows print jobs for the current user.
After running EQPrintQueueViewer.exe, a shortcut is created in the Equitrac Office and Express group under the
Windows Start menu.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 494
Chapter 19: Using Equitrac Utilities
Logging
During installation or operation of the software, errors may occur. Diagnosis of the problem often requires logs generated when system errors occur and error state details are required by Equitrac Support Services to resolve the reported error condition.
System Manager provides a streamlined logging configuration for rolling log files for debugging purposes. The rolling logs can be simplified into standard, diagnostic or custom modes. Error messages are always logged, allowing for additional information for when an error occurs, providing further details into what failed.
Log files are rolled over when the file size reaches 30 Mb, and up to 12 rolling log files can be archived before the oldest is replaced by a new one once the file size limit is reached.
To configure trace logging settings, do the following:
1
2
In System Manager, go to Diagnostics > Settings.
Right-click a service, and select Trace file settings.
3
In the Trace file settings dialog box, select the logging mode:
• Standard – turns off Journaling and Immediate flush, sets Severity filter to WARN.
• Diagnostic –turns on Journaling and Immediate flush, sets Severity filter to DEBUG.
• Custom – Journaling and Immediate flush can be turned on or off, Severity filter can be set to DEBUG, INFO,
WARN, ERROR, FATAL, OFF.
NOTE: To turn logging Off, set the Severity filter in the Custom setting to OFF.
Saving and Clearing Log Files
To save a log file, right-click a service and select Send to zip file. On the Save As dialog, name the EQLogs.zip file and save the file.
To clear log files, right-click a service and select Clear file contents. This clears the log files on the server. However, it will not clear the latest rolling log file.
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 495
Chapter 19: Using Equitrac Utilities
EQ-AG-5.7-20160921
Nuance® Equitrac® Office and Express 5.7 Administration Guide | 496
