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 differs 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.

Script hooks (entry points)

The available print hooks are:

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 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)

Job Info Script Reference (inputs.job)

User Info (inputs.user)

User Info Script Reference (inputs.user)

Client Info (inputs.client)

Client Info Script Reference (inputs.client)

Printer Info (inputs.printer)

Printer Info Script Reference (inputs.printer)

Utilities (inputs.utils)

Utilities Script Reference (inputs.utils)

Script Actions

Job actions (actions.job)

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.

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 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/MF 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.

  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.

Log Actions (actions.log)

Log Actions Script Reference (actions.log)

Utility actions (actions.utils)

Utility Actions Script Reference (actions.utils)

User actions (actions.user)

User Actions Script Reference (actions.user)

Printer actions (actions.printer)

User Actions Script Reference (actions.user)

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")

• the printer, use inputs.printer.getProperty(),

• global properties, use inputs.utils.getProperty().

There is also a set of convenient 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})

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:

1. 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.

2. 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.

if (!inputs.job.isAnalysisComplete) {

actions.job.chargeToPersonalAccount();

return;

}

if (inputs.job.totalPages < 10) {

// Charge to the personal account

actions.job.chargeToPersonalAccount();

// Or maybe charge to a single shared account

}

// Account Selection will still show

}

For more information, see Advanced Scripting: Conditionally Suppress Pop-up.