Print script API reference
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 satisfies most requirements.
This APIApplication Programming Interface (API) is a set of routines, protocols, and tools for building software and applications. An API expresses a software component in terms of its operations, inputs, outputs, and underlying types, defining functionalities that are independent of their respective implementations, which allows definitions and implementations to vary without compromising the interface. 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. For more information, see the Mozilla Developer Center here: https://developer.mozilla.org/en/JavaScript/Reference.
Script hooks (entry points)
The available print hooks are:
| Hook | Description |
|---|---|
| printJobHook(inputs, actions) | This is the main multi-purpose hook and is 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:
|
| 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:
|
| Other Hooks | If you have the need for another hook (e.g. pre-authentication), explain your requirements to the support team. Your input can influence the development of future scripting features. |
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 do 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 queueA print queue displays information about documents that are waiting to be printed, such as, the printing status, document owner, and number of pages to print. You can use the print queue to view, pause, resume, restart, and cancel print jobs. 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, such as, 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 exits the script if analysis is not complete. Once analysis is completed the script is called again and continue past this point. |
| inputs.job.isWebPrintJob | (boolean) Determines if the job has been submitted by Web PrintWeb Print enables printing from user-owned devices without the need to install printer drivers and manage server authentication.. |
| 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 PrintGoogle Cloud Print is a technology that allows you to print to any printer from any web connected device, such as a phone. Google Cloud Print works on a phone, tablet, Chromebook, PC, and any other web-connected device you want to print from. (GOOGLE_CLOUD_PRINT), Web Print (WEB_PRINT) or Email to PrintEmail to Print allows any device to print documents by sending an email to your network's print devices. (EMAIL_PRINTING). Can 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 might 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 both the machine name and the IP address are known, the machine name are returned. |
| inputs.job.selectedSharedAccountName | (string) The full name of the selected shared accountA shared account is an account that is shared by multiple users. For example, in business, shared accounts can be used to track printing costs by business unit, project, or client. Organizations like legal firms, engineering firms, or accounting offices often have long lists of accounts, projects, clients, or matters. In a school or university, shared accounts can be used to track printing by departments, classes, or subjects.. If no shared account is selected the an empty string is returned ("") (available only 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. (available only 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. (available only 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. Use this to determine
the "Least cost route" for this job. This returns the cost of the job.
Parameters:
|
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.getBalance(accountName) |
(number) The user's current account balance.
Parameters:
|
| 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:
|
| 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:
|
| 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:
|
Client Info (inputs.client)
| Property/Method | Description |
|---|---|
| inputs.client.isRunning | (boolean) Determines if the user who printed the job is running the User ClientThe User Client tool is an add-on that resides on a user's desktop. It allows users to view their current account balance via a popup window, provides users with the opportunity to confirm what they are about to print, allows users to select shared accounts via a popup, if administrators have granted access to this feature, and displays system messages, such as, the "low credit" warning message or print policy popups. software. Use this 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. |
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 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 groupPrinter groups allow administrators to tag or group printers by attributes. Group names are user definable and can represent any attribute appropriate for printer management. For example, you can group printers by printer type, location, make, function, owner, age, and so on. You can report by printer group and also send notifications per printer group.. Returns true if the printer belongs to this group. Parameters:
|
| 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:
For more information using storage properties see 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:
For more information using storage properties see User Defined Persistent Properties (Storage). |
Utilities (inputs.utils)
| Method | Description |
|---|---|
| inputs.utils.formatBalance(amount) |
Formats the balance amount based on the server currency settings. Returns a string. Parameters:
|
| inputs.utils.formatCost(amount) |
Formats the cost amount (e.g. a job cost) based on the server currency settings. Returns a string. Parameters:
|
| inputs.utils.formatNumber(amount, decimals) |
Formats a number with the given number of decimal places. Returns a string. Parameters:
|
| 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:
For more information using storage properties see 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:
For more information using storage properties see User Defined Persistent Properties (Storage). |
Script Actions
Job actions (actions.job)
| Method | Description |
|---|---|
| actions.job.addComment(comment) |
Appends a comment to the job. This is 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 appends to the existing comment.
Parameters:
|
| 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 can further modify the job cost later in the job processing.
Parameters:
|
| actions.job.cancel() | Cancels the current print job so that it is not printed. It does not log the canceled 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:
|
| 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. If this action happens after the analysis completes, that might 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:
|
| 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, filtersFilters allow you to control attributes of the print settings by either forcing a particular attribute or denying a a print job that does not meet specific criteria. There are two types of print filters: conversions and restrictions. 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 Requirements for job redirection (load balancing or Find-Me printing). NOTE 2: By default, once a job is redirected it is printed on the destination queue. You cannot run another script or use print popups at the destination queue. If you want the job to be held at the destination queue, you must specify the option: allowHoldAtTarget:true.
Parameters:
actions.job.redirect("server\\Fast Printer"); Example 2: Redirect to a virtual queue named "server\Utility Room". The job holds at the Release StationPrint Release Stations place a print job on hold and allow users to release it when required. Often a Release Station is a dedicated PC terminal located next to the printers, however, Release Stations can take other forms such as a web browser based interface. Some common examples where Release Stations can be used include secure printing, approved printing, and authentication. In a secure printing environment jobs are only printed when the user arrives at the print area and confirms his or her identity. This ensures the user is there to collect the job and other users can't "accidentally" collect the document. In some organizations it may be appropriate to hold jobs until they are approved by selected individuals. A good example would be a teacher approving printing on an expensive color printer. Hold/Release queues can be used as a form of authentication in an unauthenticated environment. Users must authenticate prior to releasing their jobs allowing PaperCut NG to confirm their identity..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 is held in "User-release" mode.
Parameters:
|
| actions.job.bypassFilters() | Allows this job to pass through the queue without being denied by the configured print filters/restrictionsRestrictions are a type of print filter that ensures jobs meet certain criteria (denying those that don't). For example, you can restrict access to one or more printer, define a maximum number of pages allowed in a single job, or allow only duplex.. |
| actions.job.convertToGrayscale() | Convert this job to grayscale (if it is not already grayscale). The job's cost is recalculated after conversion to grayscale. For more information and troubleshooting with job conversionsConversions are a type of print filter that changes something about the print job, for example, from color to grayscale, or convert to duplex., see Using Print filters: conversions and restrictions. |
| actions.job.convertToDuplex() | Convert this job to duplex (if it is not already duplex). The job's cost is recalculated after conversion to duplex. For more information and troubleshooting, see Using Print filters: conversions and restrictions. |
| 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 is recalculated
after the number of copies is changed. This feature might not be available
for all print drivers.
For more information and troubleshooting, see
Using Print filters: conversions and restrictions.
Parameters:
|
| actions.job.changeDocumentName(documentName) |
Changes the name of the document that is logged in the database.
Parameters:
|
| actions.job.changeUser(username) |
Changes the user associated with the job (i.e. the user is logged as the user that printed the job).
Parameters:
|
| actions.job.changePersonalAccountChargePriority(accountNames) |
Allows overriding which of a users' personal accountsA personal account is the individual user's account that is charged by default. Each user has their own personal account. to charge and in which order/priority.
This is 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 are 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 Multiple personal accounts.
Parameters:
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 disables the watermark, overriding a queue-level setting. Example: actions.job.setWatermark("");
Parameters:
|
| actions.job.setHoldReleaseTimeout(timeoutMins) |
Sets the timeout in minutes for a hold/release job, which overrides the system setting.
Parameters:
|
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:
|
| actions.client.promptOK(message[, options]) |
Prompts the user with the message dialog that displays an OK button. Returns a string:
Parameters:
|
| actions.client.promptOKCancel(message[, options]) |
Prompts the user with a message dialog that displays OK and Cancel. Returns a string:
Parameters:
|
| actions.client.promptPrintCancel(message[, options]) |
Prompts the user with a message dialog that displays Print and Cancel. Returns a string:
Parameters:
|
| actions.client.promptYesNo(message[, options]) |
Prompts the user with a message dialog that displays Yes and No. Returns a string:
Parameters:
|
| actions.client.promptYesNoCancel(message[, options]) |
Prompts the user with a message dialog that displays Yes, No and Cancel. Returns a string:
Parameters:
|
| actions.client.promptForText(message[, options]) |
Prompts the user with a message dialog that prompts the user to enter text, and shows OK and Cancel. Returns a string:
Parameters:
|
| actions.client.promptForPassword(message[, options]) |
Prompts the user with a message dialog that prompts the user to enter a password, and shows OK and Cancel. User input is masked. Note that this function masks user input - it does not perform any actual password authentication. Returns a string:
Parameters:
|
| actions.client.promptForChoice(message, choices[, options]) |
Prompts the user with a message dialog to select from a list, and shows OK and Cancel. Returns a string:
Parameters:
|
| actions.client.promptForForm(htmlForm[, options]) |
Prompts the user with a dialog containing a multiple input field form. The dialog also shows OK and Cancel. 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 clicks OK, the form data is returned in a JavaScript object where the values can be retrieved using the field name. e.g. response['fieldName']:
Parameters:
|
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 is remembered and the user is not prompted again for this job. This is important as the print script can 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 ensures 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 be displayed. Assigning a questionID avoids this re-prompting.
-
When performing validation of user-entered text from a text prompt in a while loop. Assign a unique questionID with each loop iteration, otherwise the user will not be reprompted and an infinite loop will occur (PaperCut NG detects this and cancel the script execution).
-
-
fastResponse (boolean) - When set to truePaperCut enables fast response mode to retrieve the response to the client prompt more quickly. This is useful only when displaying a sequence of prompts, and causes the next prompt to display more quickly.
Important:This setting is useful only when displaying a sequence of prompts. Take care when enabling this option as it can 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, 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.
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:
|
| actions.log.warning(message) |
Logs an warning message to the App. Log.
Parameters:
|
| actions.log.error(message) |
Logs an error message to the App. Log.
Parameters:
|
| actions.log.debug(message) |
Logs a message to the server's text-based log file
([app-path]/server/logs/server.log). This is helpful to
diagnose problems with print scripts.
Parameters:
|
Utility actions (actions.utils)
| Method | Description |
|---|---|
| actions.utils.sendEmail(recipient, subject, body) |
Sends an email to an email address or username.
Parameters:
|
| actions.utils.sendEmail(recipients, subject, body) |
Sends an email to one or many email addresses or usernames.
Parameters:
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:
|
| 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:
|
User actions (actions.user)
| 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:
|
| 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:
|
Printer actions (actions.printer)
| 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:
For more information using storage properties see 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:
For more information using storage properties see User Defined Persistent Properties (Storage). |
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 that takes advantage of not just the current print event information, but any information that has been stored by previous script events. Properties can also 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 that 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 are 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 canceled 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})
Global properties are stored as PaperCut config settings so any priviledge SysAdmin can edit them. 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. 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 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 convenient method that 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 (for example, due to an infinite loop), results in the script terminating and raising a runtime error. Five seconds is 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 is 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.
Print Script Frequently Asked Questions
-
I'm getting multiple popups for questions I've already answered.
It's possible that the script has been written with multiple questions or has an issue with the syntax of the script itself. Consider creating a simpler script and working in additional complexity as you go.
If the data used in the popup changes, such as a users balance when releasing multiple jobs or printing multiple jobs, then the script triggers the popup again as the conditions have changed. You can avoid this by using the questionID option explained above in Client Prompt Standard Options.