17.4 Manual
You are here: Configuration > Advanced scripting (print scripting) > Print script API reference

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.

Note:

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:

Table 65: Print workflow hooks
HookDescription
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:

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

Table 66: Job Info Script Reference (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: NOTE: The inputs.job.calculateCostForPrinter input requires the double \ character.

User Info (inputs.user)

Table 67: User Info Script Reference (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:

  • 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 retrieves 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 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 User Defined Persistent Properties (Storage).

Client Info (inputs.client)

Table 68: Client Info Script Reference (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. The client is considered "running" if there was activity from that client within the last 5 minutes. Use this:

  • To adapt a script when the client is not running (e.g. to display an optional popup question using the actions.client.prompt* APIs)
  • ONLY when response to the client prompt is optional (e.g. the print job is allowed to continue uninterrupted, even when the client is inactive and does not respond to the prompt).

Printer Info (inputs.printer)

Table 69: Printer Info Script Reference (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:

  • 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 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 User Defined Persistent Properties (Storage).

Utilities (inputs.utils)

Table 70: Utilities Script Reference (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 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 User Defined Persistent Properties (Storage).

Script Actions

Job actions (actions.job)

Table 71: Job Actions Script Reference (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:

  • 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 can 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 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:

  • 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. 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:

  • 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. If this action happens after the analysis completes, that might 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, 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:

  • printerName (string) - The name of the printer to redirect to. Enter this 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 holds in the destination printer's hold/release queue if present. Although the job is displayed 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 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:

  • 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/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:

  • newCopies (number) - The new number of copies to print.

Note: Changing the number of copies might not work on all devices. If you experience problems and the steps in Troubleshooting do not assist, please contact support for assistance.
actions.job.changeDocumentName(documentName) Changes the name of the document that is 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 is 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 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:

  • accountNames (array of strings) - the list of personal account names (as configured in Options > Advanced.) in the order they are 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 disables the watermark, overriding a queue-level setting. Example: actions.job.setWatermark(""); Parameters: For more information about watermarking and the replacement variables that you can use in text see Watermarking/job annotation.
actions.job.setHoldReleaseTimeout(timeoutMins) Sets the timeout in minutes for a hold/release job, which overrides the system setting. Parameters:

  • timeout (number) - the time, in minutes, that a hold/release job is held in the queue before it is canceled. The minimum timeout is 5 minutes.

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.

Table 72: Client Actions Script Reference (actions.client)
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 clicks OK.

  • "TIMEOUT" - If the user does not respond within the timeout period.

Parameters:
actions.client.promptOKCancel(message[, options])

Prompts the user with a message dialog that displays OK and Cancel.

Returns a string:

  • "OK" - if the user clicks OK.

  • "CANCEL" - if the user clicks CANCEL.

  • "TIMEOUT" - If the user does not respond within the timeout period.

Parameters:
actions.client.promptPrintCancel(message[, options])

Prompts the user with a message dialog that displays Print and Cancel.

Returns a string:

  • "PRINT" - if the user clicks PRINT.

  • "CANCEL" - if the user clicks CANCEL.

  • "TIMEOUT" - If the user does not respond within the timeout period.

Parameters:
actions.client.promptYesNo(message[, options])

Prompts the user with a message dialog that displays Yes and No.

Returns a string:

  • "YES" - if the user clicks Yes.

  • "NO" - if the user clicks No.

  • "TIMEOUT" - If the user does not respond within the timeout period.

Parameters:
actions.client.promptYesNoCancel(message[, options])

Prompts the user with a message dialog that displays Yes, No and Cancel.

Returns a string:

  • "YES" - if the user clicks Yes.

  • "NO" - if the user clicks No.

  • "CANCEL" - If the user clicks Cancel.

  • "TIMEOUT" - If the user does not respond within the timeout period.

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:

  • [user entered text] - if the users enters text and clicks OK.

  • "CANCEL" - If the user clicks Cancel.

  • "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 Client Prompt Message Formatting.

  • options (object/dictionary) - Options to change the behavior of the prompt.

    For the standard prompt options see Client Prompt Standard Options.

    Additional options include:

    • defaultText (string) - The text that pre-populates 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 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:

  • [user entered text] - if the users enters text and clicks OK.

  • "CANCEL" - If the user clicks Cancel.

  • "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 Client Prompt Message Formatting.

  • options (object/dictionary) - Options to change the behavior of the prompt.

    For the standard prompt options see Client Prompt Standard Options.

    Additional options include:

    • defaultText (string) - The text that pre-populates 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 a message dialog to select from a list, and shows OK and Cancel.

Returns a string:

  • [user selected choice] - The selected choice item.

  • "CANCEL" - If the user clicks Cancel.

  • "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 Client Prompt Message Formatting.

  • choices (array of strings) - the choices to display in the list. e.g. ["Unclassified", "Restricted", "Top secret"]

  • options (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see 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 list. 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. 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']:

  • [JavaScript object containing form data] - when the users enters text; then clickes OK. To retrieve the value of the fieldName field, use response['fieldName'].

  • "CANCEL" - If the user clicks Cancel.

  • "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 Client Prompt Message Formatting.

  • options (object/dictionary) - Options to change the behavior of the prompt.

    For the standard prompt options see Client Prompt Standard Options.

Use of promptForForm is demonstrated in a code snippet and in a recipe.

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

    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.

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)

Table 73: Log Actions Script Reference (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 is helpful to diagnose problems with print scripts. Parameters:

  • message (string) - the message to log.

Utility actions (actions.utils)

Table 74: Utility Actions Script Reference (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 are 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 canceled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see 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 canceled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see User Defined Persistent Properties (Storage).

User actions (actions.user)

Table 75: User Actions Script Reference (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:

  • propName (string) - the name/key of the property to set.

  • value (string) - the property value. Note: Numbers are 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 canceled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see 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 canceled (eg. insufficient credit). By default, this is set to false.

For more information using storage properties see User Defined Persistent Properties (Storage).

Printer actions (actions.printer)

Table 76: Printer Actions Script Reference (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:

  • propName (string) - the name/key of the property to set.

  • value (string) - the property value. Note: Numbers are 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 canceled (eg. insufficient credit). By default, this is set to false.

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:

  • propName (string) - the name/key of the property to set.

  • value (number) - the amount by which to increment. 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 canceled (eg. insufficient credit). By default, this is set to false.

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

Tip:

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:

  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.

Print Script Frequently Asked Questions

ClosedI'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.

ClosedCan I suppress the account selection pop-up and wait for my print job analysis to complete?

If your script allows users to cancel a job based on its content (such as the number of pages or whether or not it’s in color), then in your script, isAnalysisComplete must equal true. Depending on the print job, this can sometimes take a few minutes.

When the script first runs, the analysis is not complete so you need to suppress the popup. This allows the decision to be deferred until the analysis is completed. To do this, you need to add actions.job.chargeToPersonalAccount(); to the section where analysis is not complete.

See the script below:

function printJobHook(inputs, actions) {

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.

We are here to help

As a company full of techies we know how important a well supported product is.

Contact Support

© 2017 Copyright PaperCut Software International 1999-2017   |   Privacy Policy

PaperCut MF version 17.4