Print Script API Reference

Print Script API Reference
Prev	Chapter 18. Advanced Scripting (Print Scripting)	Next

Print scripts are segments of code that are run whenever a new print job arrives. The script is defined using the concept of a "hook". A hook is a JavaScript function that is defined by you, the script writer. It is also commonly referred to as an entry point or method. A number of print hooks (entry points) are available and each differ by the point in the print workflow when they are called. For example, a hook early in the workflow has the ability to influence behavior later in the flow, while scripts late will correspondingly have access to additional information that would not be available earlier. In most cases the generic main hook will satisfy most requirements.

Note

This API reference describing the all the properties and functions available to print scripts. Many of these inputs and functions reference JavaScript objects (e.g. String, Boolean, Date etc.). A good JavaScript reference will assist with making use of and formatting these objects. A good reference can be found at the Mozilla Developer Center here:

https://developer.mozilla.org/en/JavaScript/Reference.

Script Hooks (Entry Points)

The available print hooks are:

Hook Description

Hook	Description
`printJobHook(inputs, actions)`	This is the main multi-purpose hook and will be suitable for most situations. Point of Call: Immediately before account selection popup displays. Suitability: Most situations as all print job inputs and most actions are available. Limitations: Can't influence popup authentication behavior End-user account selection information is not available
`printJobAfterAccountSelectionHook(inputs, actions)`	This hook should only be used to perform actions that use the result of the account selection popup (i.e. accesses `inputs.job.selectedSharedAccountName`). Point of Call: Immediately after account selection popup displays (or would display if enabled). Suitability: Only use when the result of the account selection is required. Limitations: Can't influence account selection popup behavior or selected results (because it's already been completed) Can't influence popup authentication behavior
`Other Hooks`	If you have the need for another hook (e.g. pre-authentication), please explain your requirements to the support team. Your input can influence the development of future scripting features.

printJobHook(inputs, actions)

This is the main multi-purpose hook and will be suitable for most situations.

Point of Call: Immediately before account selection popup displays.

Suitability: Most situations as all print job inputs and most actions are available.

Limitations:

Can't influence popup authentication behavior
End-user account selection information is not available

printJobAfterAccountSelectionHook(inputs, actions)

This hook should only be used to perform actions that use the result of the account selection popup (i.e. accesses inputs.job.selectedSharedAccountName).

Point of Call: Immediately after account selection popup displays (or would display if enabled).

Suitability: Only use when the result of the account selection is required.

Limitations:

Can't influence account selection popup behavior or selected results (because it's already been completed)
Can't influence popup authentication behavior

Other Hooks

If you have the need for another hook (e.g. pre-authentication), please explain your requirements to the support team. Your input can influence the development of future scripting features.

Table 18.1. Print Workflow Hooks

All print job hooks have access to job, printer and user information and can perform a variety of actions that affect the job processing. The scripts have access to these through the two function arguments:

inputs - Read-only access to the print job, user and printer information.
actions - Access to perform actions that can influence the job processing, e.g. to cancel a job or send a message to the client software.

inputs are read-only and any modification to variables will not affect the print job. All actions (also known as side-effects) must be performed via the available actions. All available inputs and actions are listed below.

Script Inputs

Job Info (`inputs.job`)

Property/Method	Description
`inputs.job.date`	(date) The date/time the job was printed.
`inputs.job.username`	(string) The username of the user that printed the job.
`inputs.job.printerServerName`	(string) The name of the server the print queue is hosted on.
`inputs.job.printerName`	(string) The printer name.
`inputs.job.fullPrinterName`	(string) The full name of the printer including the server name, in the format `server\printer`.
`inputs.job.documentName`	(string) The document name.
`inputs.job.isAnalysisComplete`	(boolean) Indicates that the print job has been completely analyzed. Before the job analysis is completed, only basic job information is available (e.g. date, username, printer, document name, client machine, etc). The detailed job information like page counts, paper size, costs, etc are only available after analysis is completed. If scripts require access to the detailed information, they should only access these once the job analysis is completed. This is achieved by placing the following snippet at the start of the print hook function: if (!inputs.job.isAnalysisComplete) { return; } This snippet will exit the script if analysis is not complete. Once analysis is completed the script will be called again and continue past this point.
`inputs.job.isWebPrintJob`	(boolean) Determines if the job has been submitted by web print.
`inputs.job.jobSourceName`	(string) The machine name of the client workstation where the job was printed, or the type of job if originating from Google Cloud Print (GOOGLE_CLOUD_PRINT), Web Print (WEB_PRINT) or Email to Print (EMAIL_PRINTING). May be blank if the client machine name is not known.
`inputs.job.clientIP`	(string) The IP address of the client workstation where the job was printed. This may not be populated if the client IP address is not known.
`inputs.job.clientMachineOrIP`	(string) The machine name or IP address of the client workstation where the job was printed. If we know both the machine name and the IP address the machine name will be returned.
`inputs.job.selectedSharedAccountName`	(string) The full name of the selected shared account. If no shared account is selected the an empty string is returned (""). (Only available after the account selection is completed. i.e. from within the `printJobAfterAccountSelectionHook` hook.)
`inputs.job.totalPages`	(number) The total number of pages in the print job. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.totalSheets`	(number) The total number of sheets of paper produced by the job. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.totalColorPages`	(number) The total number of color pages in the print job. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.totalGrayscalePages`	(number) The total number of grayscale pages in the print job. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.isGrayscale`	(boolean) Determines if the job is grayscale (i.e. contains no color). (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.isColor`	(boolean) Determines if the job is color (i.e. contains at least one color page). (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.isDuplex`	(boolean) Determines job is duplex. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.cost`	(number) The cost of the job. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.copies`	(number) The number of copies. The `totalPages` attribute already takes the copies into account. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.spoolSizeKB`	(number) The size of the spool size in kilobytes (KB). (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.paperSizeName`	(string) The paper size name (e.g. Letter, Tabloid, A4, A3). (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.printerLanguage`	(string) The printer language of the print job (e.g. PostScript, PCL5, etc). (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.paperSizeHeightMM`	(number) The height of the paper size in millimetres (mm). (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.paperSizeWidthMM`	(number) The width of the paper size in millimetres (mm). (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.environmentBulbHours`	(number) The amount of energy used by this job in terms of the number of hours of use of a 60W light bulb. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.environmentTrees`	(number) The amount of paper used by this print job in terms of number of trees. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.environmentGramsCO2`	(number) The amount of carbon dioxide (C02) produced by this print job. (Only available when job analysis is complete. i.e. `isAnalysisComplete` is `true`.)
`inputs.job.calculateCostForPrinter(printerName)`	Calculates the cost of printing this job on another printer. This can be used to determine the "Least cost route" for this job. This returns the cost of the job. Parameters: `printerName` (string) - The name of the printer to calculate the cost of the job for. This can be entered as `server\\printer` or without the server name. If the server name is ommitted it is assumed the printer is on the same print server as the current job. NOTE: The inputs.job.calculateCostForPrinter input requires the double `\` character.

Table 18.2. Job Info Script Reference (inputs.job)

User Info (`inputs.user`)

Property/Method	Description
`inputs.user.username`	(string) The username of the user that printed the job.
`inputs.user.fullName`	(string) The full name of the user that printed the job (if known).
`inputs.user.email`	(string) The email address of the user that printed the job (if known).
`inputs.user.office`	(string) The office of the user that printed the job (if known).
`inputs.user.department`	(string) The deparment of the user that printed the job (if known).
`inputs.user.restricted`	(boolean) Determines if the user is restricted. i.e. printing is denied when they have no credit.
`inputs.user.balance`	(number) The user's current account balance.
`inputs.user.balance(accountName)`	(number) The user's current account balance. Parameters: `accountName` (string) - This is only valid when Multiple Personal Accounts is enabled. This is an optional parameter to specify the personal account name. If not specified, it will retrieve the user's total account balance.
`inputs.user.isInGroup(groupName)`	Determines if the user belongs to the given group name (as defined on the Groups tab). Returns `true` if the user belongs to this group. Parameters: `groupName` (string) - The name of the group to check. NOTE: The group name is case-sensitive.
`inputs.user.getProperty(propName)`	Return a value as a `string` associated with a persistent custom-defined property saved on the user, or `null` if there is no such value. Parameters: `propName` (string) - The name/key of a user property to look-up. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.
`inputs.user.getNumberProperty(propName)`	A convenience method to return a value as a `number` associated with a persistent custom-defined property saved on the user, or `null` if there is no such value. Parameters: `propName` (string) - The name/key of a user property to look-up. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

Table 18.3. User Info Script Reference (inputs.user)

Client Info (`inputs.client`)

Property/Method Description

Property/Method	Description
`inputs.client.isRunning`	(boolean) Determines if the user who printed the job is running the user client software. This can be used to adapt the script to handle when a client isn't running. e.g. Only display a popup question when the client is running. The client is considered "running" if there was activity from that client within the last 5 minutes.

inputs.client.isRunning

(boolean) Determines if the user who printed the job is running the user client software. This can be used to adapt the script to handle when a client isn't running. e.g. Only display a popup question when the client is running.

The client is considered "running" if there was activity from that client within the last 5 minutes.

Table 18.4. Client Info Script Reference (inputs.client)

Printer Info (`inputs.printer`)

Property/Method	Description
`inputs.printer.serverName`	(string) The name of the server where the printer is hosted.
`inputs.printer.printerName`	(string) The name of the printer.
`inputs.printer.fullPrinterName`	(string) The full name of the printer in format `server/printer`.
`inputs.printer.isVirtualQueue`	(boolean) Determines if this printer is a virtual queue.
`inputs.printer.isDisabled`	(boolean) Determines if this printer is currently disabled.
`inputs.printer.isStatusError`	(boolean) Determines if this printer is currently in an error state (e.g. paper jam, offline, etc.)
`inputs.printer.statusInErrorSince`	(date) The time when the printer went into this error state.
`inputs.printer.statusInErrorSeconds`	(number) The number of seconds since the printer has been in error.
`inputs.printer.groups`	(Array) An array of all the printer groups that this printer is a member of.
`inputs.printer.isInGroup(groupName)`	(boolean) Determines if the printer belongs to a particular printer group. Returns `true` if the printer belongs to this group. Parameters: `groupName` (string) - The name of the printer group to check.
`inputs.printer.getProperty(propName)`	Return a value as a `string` associated with a persistent custom-defined property saved on the printer, or `null` if there is no such value. Parameters: `propName` (string) - The name/key of a printer property to look-up. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.
`inputs.printer.getNumberProperty(propName)`	A convenience method to return a value as a `number` associated with a persistent custom-defined property saved on the printer, or `null` if there is no such value. Parameters: `propName` (string - The name/key of a printer property to look-up. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

Table 18.5. Printer Info Script Reference (inputs.printer)

Utilities (`inputs.utils`)

Method	Description
`inputs.utils.formatBalance(amount)`	Formats the balance amount based on the server currency settings. Returns a string. Parameters: `amount` (number) - the amount to format.
`inputs.utils.formatCost(amount)`	Formats the cost amount (e.g. a job cost) based on the server currency settings. Returns a string. Parameters: `amount` (number) - the amount to format.
`inputs.utils.formatNumber(amount, decimals)`	Formats a number with the given number of decimal places. Returns a string. Parameters: `amount` (number) - the amount to format. `decimals` (number) - The number of decimal places to format.
`inputs.utils.getProperty(propName)`	Return a value as a `string` associated with a persistent custom-defined global property, or `null` if there is no such value. Parameters: `propName` (string) - The name/key of a global property to look-up. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.
`inputs.utils.getNumberProperty(propName)`	A conveneince method to return a value as a `number` associated with a persistent custom-defined global property, or `null` if there is no such value. Parameters: `propName` (string) - The name/key of a global property to look-up. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

Table 18.6. Utilities Script Reference (inputs.utils)

Script Actions

Job Actions (`actions.job`)

Method	Description
`actions.job.addComment(comment)`	Appends a comment to the job. This will be logged to the database and is available in the job logs and reports. If the job already has a comment (e.g. set by the user with the advanced client) then this will append to the existing comment. Parameters: `comment` (string) - The comment to add to the print job.
`actions.job.setCost(cost)`	Sets the cost of the print job. NOTE: If there are other cost adjustments configured (e.g. user cost overrides), these may further modify the job cost later in the job processing. Parameters: `cost` (number) - The cost of the job. Must be greater than or equal to 0.
`actions.job.cancel()`	Cancels the current print job so that it will not be printed. It will not log the cancelled job. To log the job use `actions.job.cancelAndLog`. The script should typically exit using `return` after cancelling the job.
`actions.job.cancelAndLog([comment])`	Cancels the current print job and logs it under job logs. It can also add a comment to the job which is then available in the job logs and reports. The script should typically exit using `return` after cancelling the job. Parameters: `comment` (string) - An optional parameter to add a comment to the print job.
`actions.job.chargeToPersonalAccount()`	Disables any client popups and account selection, and charges the job to the user's personal account. NOTE: If you're using this in conjunction with e.g. inputs.job.jobSourceName to suppress popups when processing e.g. Google Cloud Print jobs, you'll need to remove the initial loop in the script that checks for inputs.job.isAnalysisComplete being true. The reason being is that if this action happens after the analysis completes, that may be too late to suppress the client popup.
`actions.job.chargeToSharedAccount(accountName)`	Disables any client popups and account selection, and charges the job to the specified shared account. Parameters: `accountName` (string) - The name of the shared account. If the shared account is a sub-account then the account name must be provided in the format `parentName\\subName`. NOTE 1: The actions.job.chargeToSharedAccount action requires the double `\` character. NOTE 2: If you're using this in conjunction with e.g. inputs.job.jobSourceName to suppress popups when processing e.g. Google Cloud Print jobs, you'll need to remove the initial loop in the script that checks for inputs.job.isAnalysisComplete being true. The reason being is that if this action happens after the analysis completes, that may be too late to suppress the client popup.
`actions.job.redirect(printerName[, options])`	Schedules the job to be redirected to the given printer queue. The job is redirected after it has completed processing (e.g. after print popups are acknowledged, filters are run, and the job is released from the hold/release queue). NOTE 1: Jobs should only be redirected between compatible printers (e.g. those that support the same printer language and features). For more information see the section called “Requirements For Job Redirection (Load Balancing or Find Me Printing)”. NOTE 2: By default, once a job is redirected it will be printed on the destination queue. You may not run another script or use print popups at the destination queue. If you wish the job to be held at the destination queue, you must specify the option: allowHoldAtTarget:true. Parameters: `printerName` (string) - The name of the printer to redirect to. This can be entered as `server\printer` or without the server name. If the server name is omitted it is assumed the printer is on the same print server as the current job. `options` (object/dictionary) - An optional parameter defining the additional options to the redirect command. Options include: `allowHoldAtTarget` (boolean) - Determines whether the job will hold in the destination printer's hold/release queue if present. Although the job appears in the destination's hold/release queue, it is not physically redirected until printed. Default: `false`. `recalculateCost` (boolean) - Determines whether to recalculate the cost based on the settings of the destination printer. Default: `false`. Example 1: Redirect to a printer named "server\Fast Printer". actions.job.redirect("server\\Fast Printer"); Example 2: Redirect to a virtual queue named "server\Utility Room". The job will hold at the release station. actions.job.redirect("server\\Utility Room", {allowHoldAtTarget: true}); Example 3: Redirect to a virtual queue named "server\Utility Room", recalculating the cost based on the cost settings of the destination printer. actions.job.redirect("server\\Utility Room", {allowHoldAtTarget: true, recalculateCost: true}); NOTE 3: The actions.job.redirect() action requires the double `\` character.
`actions.job.bypassReleaseQueue()`	Allows this job to pass through the queue without being held in a hold/release queue.
`actions.job.holdInReleaseQueue([mode])`	Holds this job in a hold/release queue that it was printed to. If the `mode` argument is omitted the job will be held in "User-release" mode. Parameters: `mode` (string) - An optional parameter defining the release station mode. If set to `user-release`, the user can release the job. If set to `manager-release`, only an admin or print release manager can release the job. Default: `user-release`
`actions.job.bypassFilters()`	Allows this job to pass through the queue without being denied by the configured print filters/restrictions.
`actions.job.convertToGrayscale()`	Convert this job to grayscale (if it is not already grayscale). The job's cost will be recalculated after conversion to grayscale. For more information and troubleshooting with job conversions please see the section called “Print Conversion Filters in Detail”.
`actions.job.convertToDuplex()`	Convert this job to duplex (if it is not already duplex). The job's cost will be recalculated after conversion to duplex. For more information and troubleshooting please see the section called “Print Conversion Filters in Detail”.
`actions.job.changeNumberOfCopies(newCopies)`	Change the number of copies in this job. E.g. change to print 4 copies instead of 1 copy. This should only be used to increase the copy count from 1, not to reduce the count or change in other ways. The job's cost will be recalculated after the number of copies has been changed. This feature may not be available for all print drivers. For more information and troubleshooting please see the section called “Print Conversion Filters in Detail”. Parameters: `newCopies` (number) - The new number of copies to print. Note: changing the number of copies is experimental and may not work on all devices. If you experience problems and the steps in the section called “Troubleshooting” do not assist, please contact support for assistance.
`actions.job.changeDocumentName(documentName)`	Changes the name of the document that will be logged in the database. Parameters: `documentName` (string) - The new name of the document.
`actions.job.changeUser(username)`	Changes the user associated with the job (i.e. the user will be logged as the user that printed the job). Parameters: `username` (string) - The username of the user.
`actions.job.changePersonalAccountChargePriority(accountNames)`	Allows overriding which of a users' personal accounts to charge and in which order/priority. This can be useful when a printer can only be used when credit is available in a particular subset of user personal accounts (e.g. department allocated quotas). Only those accounts listed will be charged for the job. If credit isn't available in the listed accounts the jobs is denied. NOTE: This is only valid when Multiple Personal Accounts is enabled. See Chapter 30, Multiple Personal Accounts. Parameters: `accountNames` (array of strings) - the list of personal account names (as configured in Options → Advanced.) in the order they should be charged. e.g. `["Default", "Cash"]`. When searching for the account names the case differences are ignored. If any of the accounts supplied to do not exist then an entry is written to the server log. If no valid accounts are found then the personal account charge priority is unchanged. Example: To allow the jobs to be only charge to the accounts "Science Department" and "Cash" (in that order) actions.job.changePersonalAccountChargePriority( ["Science Department", "Cash"]);
`actions.job.disableArchiving()`	Disable print job archiving if it's been enabled for this job.
`actions.job.setWatermark(text)`	Sets the watermark text for this job. Watermarking allows text to be added on each printed page, e.g. the date and name of the user who printed the job. NOTE: Using an empty string will disable the watermark, overriding a queue-level setting. Example: actions.job.setWatermark(""); Parameters: `text` (string) - the watermark text to add to each page of the job. The text may include replacement variables such as "%user%" (replaced with the username of the user who printed the job). An empty string will disable watermarking for this job. For more information about watermarking and the replacement variables that can be used in `text` see the section called “Watermarking/Job Annotation”.

Table 18.7. Job Actions Script Reference (actions.job)

Client Actions (`actions.client`)

The client actions allow a script to send messages to the user client and prompt the user for a variety of questions. These require that the user is running the client software.

Method	Description
`actions.client.sendMessage(message)`	Sends a message to the user. This message is typically displayed as a task tray popup on Windows. Unlike the prompt actions, the user does not need to acknowledge the message to allow the job to print. Parameters: `message` (string) - the message to display to the user.
`actions.client.promptOK(message[, options])`	Prompts the user with the message dialog that displays an OK button. Returns a string: `"OK"` - if the user presses the OK button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptOKCancel(message[, options])`	Prompts the user with the message dialog that displays an OK and Cancel button. Returns a string: `"OK"` - if the user presses the OK button. `"CANCEL"` - if the user presses the OK button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptPrintCancel(message[, options])`	Prompts the user with the message dialog that displays a Print and Cancel button. Returns a string: `"OK"` - if the user presses the OK button. `"CANCEL"` - if the user presses the OK button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptYesNo(message[, options])`	Prompts the user with the message dialog that displays a Yes and No button. Returns a string: `"YES"` - if the user presses the Yes button. `"NO"` - if the user presses the No button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptYesNoCancel(message[, options])`	Prompts the user with the message dialog that displays a Yes, No and Cancel button. Returns a string: `"YES"` - if the user presses the Yes button. `"NO"` - if the user presses the No button. `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptForText(message[, options])`	Prompts the user with the message dialog that prompts the user to enter text, and shows an OK and Cancel button. Returns a string: `[user entered text]` - if the users enters text and presses OK. `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”. Additional options include: `defaultText` (string) - The text that will pre-populate the text entry field. `fieldLabel` (string) - The label displayed on the left side of the text field. By default no field label is displayed, and the text-box fills the full width of the dialog.
`actions.client.promptForPassword(message[, options])`	Prompts the user with the message dialog that prompts the user to enter a password, and shows an OK and Cancel button. User input will be masked. Note that this function simply masks user input - it does not perform any actual password authentication. Returns a string: `[user entered text]` - if the users enters text and presses OK. `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”. Additional options include: `defaultText` (string) - The text that will pre-populate the text entry field. `fieldLabel` (string) - The label displayed on the left side of the text field. By default no field label is displayed, and the text-box fills the full width of the dialog.
`actions.client.promptForChoice(message, choices[, options])`	Prompts the user with the message dialog that prompts the user to select from one or more choices from a drop-down list, and shows an OK and Cancel button. Returns a string: `[user selected choice]` - The selected choice item. `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `choices` (array of strings) - the list of choices to display in the drop-down list. e.g. `["Unclassified", "Restricted", "Top secret"]` `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”. Additional options include: `defaultChoice` (string) - The default choice which is pre-selected for the user. This must match one of the provided choices. `fieldLabel` (string) - The label displayed on the left side of the drop-down box. By default no field label is displayed, and the drop-down fills the full width of the dialog.
`actions.client.promptForForm(htmlForm[, options])`	Prompts the user with a dialog containing a multiple input field form. The dialog also shows OK and Cancel buttons. The input fields and layout are defined using HTML with form elements. The `htmlForm` parameter must contain valid HTML including at least one or more form elements such as <input>. When the user presses the OK button, the form data is returned in a JavaScript object where the values may be retrieved using the field name. e.g. `response['fieldName']`: `[JavaScript object containing form data]` - when the users enters text and presses OK. To retrieve the value of the field named `fieldName` use `response['fieldName'].` `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the user does not respond within the timeout period. Parameters: `htmlForm` (string) - the HTML form/message to display to the user. The HTML needs to include one or more HTML input elements - including text fields (normal, password or multi-line), radio boxes, check boxes and choice lists. Each form element must have a unique name that is used to identify the field when the user's input is returned to the server. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”. Use of `promptForForm` is demonstrated in a code snippet and in a recipe.

Table 18.8. Client Actions Script Reference (actions.client)

Client Prompt Standard Options

All the client prompt options have an options parameter to customize the prompt behavior. Some prompt types have additional options, but all prompt types have the following options:

dialogTitle (string) - The title of the dialog.
dialogDesc (string) - The brief one-line description to complement the dialog title.
hideJobDetails (boolean) - Used to hide the job details from the user. e.g. document name, printer name, pages, cost, etc. Default: false - the job details are displayed.
timeoutSecs (number) - The number of seconds to wait for a response from the user. Once this time elapses, the prompt method returns "TIMEOUT". The default timeout is 5 minutes (300 seconds).
questionID (string) - Uniquely identifies a question for a given print job and script. Once a user has responded to a prompt with a given questionID, the result will be remembered and the user will not be prompted again for this job. This is important as the print script may be called repeatedly if jobs are held awaiting prompts, popups or are held in a release queue. If the questionID is not provided, the question ID is automatically generated based on the prompt parameters (e.g. message, buttons, choices, etc).
The questionID is rarely required, only in the following cases:
- If the same prompt/question is required multiple times for a single script, and the user must answer each time. Assigning a different questionID to each prompt will ensure that the user is re-prompted.
- If the message of a prompt changes with each call. e.g. if the message included the current time it would change each time the prompt was called. Another example is if the message includes the user's balance, this might change if they are printing multiple print jobs. Both of these would cause the multiple prompts to appear. Assigning a questionID will avoid this re-prompting.
- When performing validation of user-entered text from a text prompt in a while loop. A unique questionID should be assigned with each loop iteration, otherwise the user will not be reprompted and an infinite loop will occur (PaperCut NG will detect this and cancel the script execution).
fastResponse (boolean) - When set to true PaperCut will enable fast response mode to retrieve the response to the client prompt more quickly. This is only useful when displaying a sequence of prompts, and will cause the next prompt to display more quickly.
IMPORTANT: This setting is only useful when displaying a sequence of prompts. Care should be taken when enabling this option as it may cause increased load on the server.
You might also want to consider displaying a multi-input form instead of separate prompts. See actions.client.promptForForm() for details.

Client Prompt Message Formatting

The client prompts allow the administrator to display a message to the user and ask for user input. The dialog messages provide a subset of the most useful HTML formatting options. You can use them to make your message stand out and grab the user's attention.

Plain text formatting:

To use plain text formatting simply provide a standard JavaScript string as the message parameter. To start a new line, use the new line character \n. e.g.

  actions.client.promptOK("First line\n\nSecond line");

HTML formatting:

The dialogs messages HTML formatting that provides a large subset of the most useful HTML formatting options. So you can get creative and make your message stand out and grab the user's attention.

To enable HTML formatting, surround the message text in <html> and </html> tags. Below is a very simple example that shows the word bold in bold.

  actions.client.promptOK("<html>This is <b>bold</b></html>");

The client dialogs support many of the commonly used HTML features/elements including:

Bold text - <b>
Colored text - <span style='color: red'>
Images - <img src='http://host.com/image.jpg'>
Line breaks - <br>
Font sizes - <span style='font: 14px'>
Bullet lists - <ul> / <li>
Numbered lists - <ol> / <li>
Horizontal rule - <hr>
Text Field Input - <input name="comment"> (only valid in actions.client.promptForForm)

The dialog below shows most of the formatting options outlined above. The code for this dialog is available in the "Show a dialog with HTML formatting" snippet.

Figure 18.7. Print Script Client Prompt with HTML formatting

Tip

To reference an image stored in the directory [app-path]/server/custom/web/my-image.jpg use the HTML:

    <img src='http://%PC_SERVER%/custom/my-image.jpg'>

The special substitution variable %PC_SERVER% is expanded to the name and port of your active PaperCut server.

Log Actions (`actions.log`)

Method	Description
`actions.log.info(message)`	Logs an informational message to the App. Log. Parameters: `message` (string) - the message to log.
`actions.log.warning(message)`	Logs an warning message to the App. Log. Parameters: `message` (string) - the message to log.
`actions.log.error(message)`	Logs an error message to the App. Log. Parameters: `message` (string) - the message to log.
`actions.log.debug(message)`	Logs a message to the server's text-based log file (`[app-path]/server/logs/server.log`). This can be helpful to diagnose problems with print scripts. Parameters: `message` (string) - the message to log.

Table 18.9. Log Actions Script Reference (actions.log)

Utility Actions (`actions.utils`)

Method	Description
`actions.utils.sendEmail(recipient, subject, body)`	Sends an email to an email address or username. Parameters: `recipient` (string) - either the email address or username of the email recipient. `subject` (string) - subject text of the email. `body` (string) - body text of the email.
`actions.utils.sendEmail(recipients, subject, body)`	Sends an email to one or many email addresses or usernames. Parameters: `recipients` (array of strings) - either the email addresses or usernames of the email recipients. `subject` (string) - subject text of the email. `body` (string) - body text of the email. Example: to send an email to many email addresses or usernames actions.utils.sendEmail( ["Administrator", "[email protected]"], "Oh no!", "we're out of print credit!");
`actions.utils.onCompletionSaveProperty(propName, value[, options])`	Saves a global value as a `string` associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed. Parameters: `propName` (string) - the name/key of the property to set. `value` (string) - the property value. Note: Numbers will be converted to a string. `options` (object/dictionary) - options to modify behavior of the command. `saveWhenCancelled` (boolean) - If set to `true`, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to `false`. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.
`actions.utils.onCompletionIncrementNumberProperty(propName, value[, options])`	A convenience method to increment a global number value associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed. Parameters: `propName` (string) - the name/key of the property to set. `value` (number) - the amount to increment by. A negative number will decrement. `options` (object/dictionary) - options to modify behavior of the command. `saveWhenCancelled` (boolean) - If set to `true`, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to `false`. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

Table 18.10. Utility Actions Script Reference (actions.utils)

User Actions (`actions.user`)

Method Description

Method	Description
`actions.user.onCompletionSaveProperty(propName, value[, options])`	Saves a value on the user as a `string` associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed. Parameters: `propName` (string) - the name/key of the property to set. `value` (string) - the property value. Note: Numbers will be converted to a string. `options` (object/dictionary) - options to modify behavior of the command. `saveWhenCancelled` (boolean) - If set to `true`, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to `false`. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.
`actions.user.onCompletionIncrementNumberProperty(propName, value[, options])`	A convenience method to increment a number value on the user associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed. Parameters: `propName` (string) - the name/key of the property to set. `value` (number) - the amount to increment by. A negative number will decrement. `options` (object/dictionary) - options to modify behavior of the command. `saveWhenCancelled` (boolean) - If set to `true`, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to `false`. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

actions.user.onCompletionSaveProperty(propName, value[, options])

Saves a value on the user as a string associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.

Parameters:

propName (string) - the name/key of the property to set.
value (string) - the property value. Note: Numbers will be converted to a string.
options (object/dictionary) - options to modify behavior of the command.
- saveWhenCancelled (boolean) - If set to true, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

actions.user.onCompletionIncrementNumberProperty(propName, value[, options])

A convenience method to increment a number value on the user associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.

Parameters:

propName (string) - the name/key of the property to set.
value (number) - the amount to increment by. A negative number will decrement.
options (object/dictionary) - options to modify behavior of the command.
- saveWhenCancelled (boolean) - If set to true, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

Table 18.11. User Actions Script Reference (actions.user)

Printer Actions (`actions.printer`)

Method Description

Method	Description
`actions.printer.onCompletionSaveProperty(propName, value[, options])`	Saves a value on the printer as a `string` associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed. Parameters: `propName` (string) - the name/key of the property to set. `value` (string) - the property value. Note: Numbers will be converted to a string. `options` (object/dictionary) - options to modify behavior of the command. `saveWhenCancelled` (boolean) - If set to `true`, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to `false`. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.
`actions.printer.onCompletionIncrementNumberProperty(propName, value[, options])`	A convenience method to increment a number value on the printer associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed. Parameters: `propName` (string) - the name/key of the property to set. `value` (number) - the amount to increment by. A negative number will decrement. `options` (object/dictionary) - options to modify behavior of the command. `saveWhenCancelled` (boolean) - If set to `true`, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to `false`. For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

actions.printer.onCompletionSaveProperty(propName, value[, options])

Saves a value on the printer as a string associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.

Parameters:

propName (string) - the name/key of the property to set.
value (string) - the property value. Note: Numbers will be converted to a string.
options (object/dictionary) - options to modify behavior of the command.
- saveWhenCancelled (boolean) - If set to true, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

actions.printer.onCompletionIncrementNumberProperty(propName, value[, options])

A convenience method to increment a number value on the printer associated with a persistent custom-defined property. This operation is performed once the print script completes and the print-job is printed.

Parameters:

propName (string) - the name/key of the property to set.
value (number) - the amount to increment by. A negative number will decrement.
options (object/dictionary) - options to modify behavior of the command.
- saveWhenCancelled (boolean) - If set to true, the operation is performed even if the print job is cancelled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see the section called “User Defined Persistent Properties (Storage)”.

Table 18.12. Printer Actions Script Reference (actions.printer)

User Defined Persistent Properties (Storage)

Print scripts have the ability to store or save information between executions. They allow script authors to implement advanced logic which takes advantage of not just the current print event information, but any information that has been stored by previous script events. Properties also can be used to share data between different scripts. Some ideas that can be implemented with print script properties could include:

Rate limits – knowledge of previous jobs in the given period need to be stored/known.
Detecting duplicate events/situations over time.
Detecting repeatable user behavior. e.g. how many times a user uses duplex in a row.
Shared settings between scripts . e.g. Global defined configuration variables/settings.

Properties are key-value pair storage which are associated with a user or printer, or optionally can be global. Keys are Strings that uniquely define the property. Values are stored as Strings and hence values can be any data that can be converted to and from a string. The maximum length of a key is 70 characters, and the value is 1,000 characters.

Working with properties

Properties are fetched via the getProperty call on the associated source. For example, to fetch a property stored on the user associated with the print job, use inputs.user.getProperty("my-key"). Printer properties are fetched via inputs.printer.getProperty(), and global via inputs.utils.getProperty(). There exists a set of convenience methods called getNumberProperty() if dealing exclusively with a number.

By default, properties are only saved (to the database) after the print script completes and the job is printed (i.e. not cancelled or denied). If saving/incrementing properties on job cancellation is required (e.g. the user has insufficient credit, or actions.job.cancel is called, use the saveWhenCancelled optional argument. For example, to set a property on the user, use:

    actions.user.onCompletionSaveProperty("my-key", "my-value")

The same command with "save on cancellation" behavior enabled is:

    actions.user.onCompletionSaveProperty("my-key", "my-value", {'saveWhenCancelled' : true})

Tip

Global properties are stored as PaperCut config settings and hence can be edited by any priviledge system administrator. You can find your properties via Options → Actions → Config editor (Advanced). All script properties are prefixed with script.user-defined. and are searchable by name. Hence global properties are a great way to define editable configuration values that are shared between scripts.

Implementing Counters (Advanced)

There are two ways to implement a counter (e.g. a page number count). One approach is to simply get the current value, increment, then save. On high volume networks there exists the possibility of another event overwriting the value. Print scripts provide a convenience method which avoids this called onCompletionIncrementNumberProperty(). See the recipe "Prevent overuse of lab printers (rate limiting)" for an example.

Print Script Requirements (Advanced)

These notes are intended for advanced developers "pushing the limits" of print script functionality. All print scripts must conform to the following technical requirements:

Timeouts: All scripts execution logic should complete within 5 seconds of CPU time. Failure to comply - say due to an infinite loop - will result in the script terminating and raising a runtime error. Five seconds should be adequate as even the most advanced example recipes complete within a few milliseconds.
Reentrant and Idempotent: All scripts should be reentrent - designed to be called multiple times for the same job, each time producing the same result/behavior. For example your script will be called multiple times at various stages of analysis and it's expected to provide the same output given the same input. Side-effects based off logic other than the inputs are not recommended. For example, logic based off the result of Math.random() would violate this principle.
New APIs: If you have a need for new APIs, please email the developers. We have a number planned such as the ability to influence account selection popup behavior, options to store/persist attributes on users and printers, exec external processes, and more layout options for dialogs. Please share your ideas!