Print Script API Reference

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

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

Note

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

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

Script Hooks (Entry Points)

The available print hooks are:

Hook Description

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

printJobHook(inputs, actions)

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

Point of Call: Immediately before account selection popup displays.

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

Limitations:

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

printJobAfterAccountSelectionHook(inputs, actions)

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

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

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

Limitations:

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

Other Hooks

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

Table 17.1. Print Workflow Hooks

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

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

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

Script Inputs

Job Info (`inputs.job`)

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

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

User Info (`inputs.user`)

Property/Method	Description
`inputs.user.username`	(string) The username of the user that printed the job.
`inputs.user.fullName`	(string) The full name of the user that printed the job (if known).
`inputs.user.email`	(string) The email address of the user that printed the job (if known).
`inputs.user.office`	(string) The office of the user that printed the job (if known).
`inputs.user.department`	(string) The deparment of the user that printed the job (if known).
`inputs.user.restricted`	(boolean) Determines if the user is restricted. i.e. printing is denied when they have no credit.
`inputs.user.balance`	(number) The user's current account balance.
`inputs.user.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.

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

Client Info (`inputs.client`)

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

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

Printer Info (`inputs.printer`)

Property/Method	Description
`inputs.printer.serverName`	(string) The name of the server where the printer is hosted.
`inputs.printer.printerName`	(string) The name of the printer.
`inputs.printer.fullPrinterName`	(string) The full name of the printer in format `server/printer`.
`inputs.printer.isVirtualQueue`	(boolean) Determines if this printer is a virtual queue.
`inputs.printer.isDisabled`	(boolean) Determines if this printer is currently disabled.
`inputs.printer.isStatusError`	(boolean) Determines if this printer is currently in an error state (e.g. paper jam, offline, etc.
`inputs.printer.statusInErrorSince`	(date) The time when the printer went into this error state.
`inputs.printer.statusInErrorSeconds`	(number) The number of seconds since the printer has been in error.
`inputs.printer.groups`	(Array) An array of all the printer groups that this printer is a member of.
`inputs.printer.isInGroup(groupName)`	(boolean) Determines if the printer belongs to a particular printer group. Returns `true` if the printer belongs to this group. Parameters: `groupName` (string) - The name of the printer group to check.

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

Utilities (`inputs.utils`)

Method Description

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

Table 17.6. Utilities Script Reference (inputs.utils)

Script Actions

Job Actions (`actions.job`)

Method	Description
`actions.job.addComment(comment)`	Appends a comment to the job. This will be logged to the database and is available in the job logs and reports. If the job already has a comment (e.g. set by the user with the advanced client) then this will append to the existing comment. Parameters: `comment` (string) - The comment to add to the print job.
`actions.job.setCost(cost)`	Sets the cost of the print job. NOTE: If there are other cost adjustments configured (e.g. user cost overrides), these may further modify the job cost later in the job processing. Parameters: `cost` (number) - The cost of the job. Must be greater than or equal to 0.
`actions.job.cancel()`	Cancels the current print job so that it will not be printed. The script should typically exit using `return` after cancelling the job.
`actions.job.chargeToPersonalAccount()`	Disables any client popups and account selection, and charges the job to the user's personal account.
`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: The actions.job.chargeToSharedAccount action requires the double \.
`actions.job.redirect(printerName[, options])`	Schedules the job to be redirected to the given printer queue. The job is redirected after it has completed processing (e.g. after print popups are acknowledged, filters are run, and the job is released from the hold/release queue). NOTE: Jobs should only be redirected between compatibles printers (e.g. those that support the same printer language and features). For more information see the section called “Requirements For Job Redirection (Load Balancing or Find Me Printing)”. Parameters: `printerName` (string) - The name of the printer to redirect to. This can be entered as `server\printer` or without the server name. If the server name is ommitted 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: `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 printer named "server\Fast Printer", recalculating the cost based on the cost settings of the destination printer. actions.job.redirect("server\\Fast Printer", {"recalculateCost": true}); NOTE: The actions.job.redirect() action requires the double \.
`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 ommitted the the job will be held in "User-release" mode. Parameters: `mode` (string) - An optional parameter defining the release station mode. If set to `user-release`, the user can release the job. If set to `manager-release`, only an admin or print release manager can release the job. Default: `user-release`
`actions.job.bypassFilters()`	Allows this job to pass through the queue without being denied by the configured print filters/restrictions.
`actions.job.changeDocumentName(documentName)`	Changes the name of the document that will be logged in the database. Parameters: `documentName` (string) - The new name of the document.
`actions.job.changeUser(username)`	Changes the user associated with the job (i.e. the user will be logged as the user that printed the job). Parameters: `username` (string) - The username of the user.
`actions.job.changePersonalAccountChargePriority(accountNames)`	Allows overriding which of a users' personal accounts to charge and in which order/priority. This can be useful when a printer can only be used when credit is available in a particular subset of user personal accounts (e.g. department allocated quotas). Only those accounts listed will be charged for the job. If credit isn't available in the listed accounts the jobs is denied. NOTE: This is only valid when Multiple Personal Accounts is enabled. See Chapter 29, Multiple Personal Accounts. Parameters: `accountNames` (array of strings) - the list of personal account names (as configured in Options → Advanced.) in the order they should be charged. e.g. `["Default", "Cash"]` 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.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. Parameters: `text` (string) - the watermark text to add to each page of the job. The text may include replacement variables such as "%user%" (replaced with the username of the user who printed the job). An empty string will disable watermarking for this job. For more information about watermarking and the replacement variables that can be used in `text` see the section called “Watermarking/Job Annotation”.

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

Client Actions (`actions.client`)

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

Method	Description
`actions.client.sendMessage(message)`	Sends a message to the user. This message is typically displayed as a task tray popup on Windows. Unlike the prompt actions, the user does not need to acknowledge the message to allow the job to print. Parameters: `message` (string) - the message to display to the user.
`actions.client.promptOK(message[, options])`	Prompts the user with the message dialog that displays an OK button. Returns a string: `"OK"` - if the user presses the OK button. `"TIMEOUT"` - If the the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptOKCancel(message[, options])`	Prompts the user with the message dialog that displays an OK and Cancel button. Returns a string: `"OK"` - if the user presses the OK button. `"CANCEL"` - if the user presses the OK button. `"TIMEOUT"` - If the the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptPrintCancel(message[, options])`	Prompts the user with the message dialog that displays a Print and Cancel button. Returns a string: `"OK"` - if the user presses the OK button. `"CANCEL"` - if the user presses the OK button. `"TIMEOUT"` - If the the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptYesNo(message[, options])`	Prompts the user with the message dialog that displays a Yes and No button. Returns a string: `"YES"` - if the user presses the Yes button. `"NO"` - if the user presses the No button. `"TIMEOUT"` - If the the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptYesNoCancel(message[, options])`	Prompts the user with the message dialog that displays a Yes, No and Cancel button. Returns a string: `"YES"` - if the user presses the Yes button. `"NO"` - if the user presses the No button. `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”.
`actions.client.promptForText(message[, options])`	Prompts the user with the message dialog that prompts the user to enter text, and shows an OK and Cancel button. Returns a string: `[user entered text]` - if the users enters text and presses OK. `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”. Additional options include: `defaultText` (string) - The text that will pre-populate the text entry field. `fieldLabel` (string) - The label displayed on the left side of the text field. By default no field label is displayed, and the text-box fills the full width of the dialog.
`actions.client.promptForChoice(message, choices[, options])`	Prompts the user with the message dialog that prompts the user to select from one or more choices from a drop-down list, and shows an OK and Cancel button. Returns a string: `[user selected choice]` - The selected choice item. `"CANCEL"` - If the user presses the Cancel button. `"TIMEOUT"` - If the the user does not respond within the timeout period. Parameters: `message` (string) - the message to display to the user. For information on formatting messages see the section called “Client Prompt Message Formatting”. `choices` (array of strings) - the list of choices to display in the drop-down list. e.g. `["Unclassified", "Restricted", "Top secret"]` `options` (object/dictionary) - Options to change the behavior of the prompt. For the standard prompt options see the section called “Client Prompt Standard Options”. Additional options include: `defaultChoice` (string) - The default choice which is pre-selected for the user. This must match one of the provided choices. `fieldLabel` (string) - The label displayed on the left side of the drop-down box. By default no field label is displayed, and the drop-down fills the full width of the dialog.

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

Client Prompt Standard Options

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

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

Client Prompt Message Formatting

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

Plain text formatting:

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

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

HTML formatting:

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

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

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

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

Bold text - <b>
Colored text - <span style='color: red'>
Images - <img src='http://host.com/image.jpg'>
Line breaks - <br>
Font sizes - <span style='font: 14px'>
Bullet lists - <ul> / <li>
Numbered lists - <ol> / <li>
Horizontal rule - <hr>

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

Figure 17.7. Print Script Client Prompt with HTML formatting

Tip

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

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

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

Log Actions (`actions.log`)

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

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

Print Script Requirements (Advanced)

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

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