Using extended Java classes or executables in scripts

PaperCut NG/MF internally uses the Rhino scripting engine. If enabled, Rhino can use the power of extended Java classes, which can be used to perform actions such as executing external processes or calling Java library functions.

This is an advanced feature and is disabled by default in all installations. PaperCut recommends that before you enable this feature you understand the risks of using extended Java classes in scripts.

To understand if you’re using extended classes, generally, if you’re using classes outside of dates, numbers, and strings (those listed on the Print script API reference ) then you might be using extended classes. These may include calling OS-level commands or accessing non-type classes from your print or device script.

Generally this is rare!

If you are using extended Java classes in print scripting or device scripting, you need to enable the related config key in the security.properties file.

1. In any operating system, open the [app-path]/server/security.properties file.

   Windows

   a. In the Start menu, right-click Notepad and select Run as administrator.

   b. From the File menu select Open.

   c. Browse to and open the security.properties file.

   macOS/Linux

   We recommend using sudo or su to open the file in your favorite editor as root.

2. Set the necessary config keys to Y:

   • security.print-script.allow-unsafe-code
   • security.device-script.allow-unsafe-code
   • security.card-no-converter-script.allow-unsafe-code

3. Save the security.properties file.

4. Restart the PaperCut Application Server .

We recommend you keep these keys set to N unless absolutely necessary.

Troubleshooting the scripting engine

Before you can edit a print script or device script, you need to enable the print and device scripting config keys .

If you don’t have print scripting and device scripting enabled and you attempt to edit a print script or device script, the script editor interface will be greyed out and not editable and you’ll see a warning in the admin interface.

Print Scripting and Device Scripting are not enabled. To enable them, update the security.print-and-device-script.enabled config key in the [app-path]/server/security.properties file. Learn more.

Troubleshooting extended Java class script failures

If you are attempting to use an extended Java class in your script but any of the following config keys are set to N, the non-extended parts of the script will run as normal, however, the script will not run the extended class.

• security.print-script.allow-unsafe-code
• security.device-script.allow-unsafe-code
• security.card-no-converter-script.allow-unsafe-code

In the Application Log (under Logs > Application Log), you’ll see an error:

The print script encountered an error when running [function] for job on printer [printer name]… Error: ReferenceError: [class] is not defined.

The error lists the line number where the issue occurred in the print script.

In the screenshot below, the script is using the actions.log.info (message) method (documented on the Print Scripting API page) to log the message ‘script starting’ at the start of the script.

To fix the error, either enable the use of unsafe code or remove the extended classes from your script.