Creating device scripts

This topic explains the steps to create device scripts. To learn more about what this is all about, take a look at the device scripting overview .

Enabling Device Scripting

You need to enable the feature for scripts to run.

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. Find the security.print-and-device.script.enabled=N key and set it to Y.

3. Save the security.properties file.

4. Restart the PaperCut Application Server .

Creating a device script

Before you start, be sure that Device Scripting is enabled .

1. In the Web admin interface, click Devices > [device name] > Scripting. The Advanced Scripting page is displayed.

   

2. Create your script in one of the following ways:

   • Import a predefined recipe

   • Use snippets

   • Combine device scripts

   • Use common scripts

   • Create a script from scratch.

3. Select the Enable device script checkbox.

4. Click Apply.

5. Test your script to make sure it works as you expect.

6. Copy the script to your production MFDs.

7. On the Advanced Scripting tab, click Apply. Your script is immediately made live.

Importing a predefined recipe

Recipes demonstrate best practices and should be considered as a starting point for developing your own scripts.

For an example of creating a device script using recipes, see Example: Set a daily color copying quota for all users .

To use a recipe:

1. On the Advanced Scripting page, click Import Recipe.
   A list of the predefined recipes is displayed. For example, the Discount for copying and scanning for staff recipe.

   

2. Click import next to the recipe you want to use. A confirmation prompt is displayed.

3. Click OK. The recipe replaces what is currently in your script.

4. Click Apply.

Using snippets

Code snippets are small code fragments that demonstrate how to use the scripting API (inputs, functions, and methods). Consider using snippets as a base for adding functionality to your script. For an example of a script created using snippets, see Example: Prevent access to devices out of business hours .

To use a snippet:

1. Place your cursor in the position you want to insert the snippet.

2. Click Insert Snippet at Cursor.

   A list of code snippets is displayed. For example, the Test if job is color snippet provides the code to check if a copy, scan, or fax job is color. This could be used as part of a script to perform an action on all color jobs.

   

3. Click insert next to the snippet you want to use. A confirmation prompt is displayed.

4. Click OK. The snippet is added to your script.

5. If required, you can modify the code to suit your needs.

6. Click Apply.

Combining device scripts

If you have an understanding of JavaScript, you can combine parts of two or more device scripts.

A typical device script contains one deviceLoginHook() function:

function deviceLoginHook(inputs, actions) { ....some JavaScript code ... }

PaperCut MF calls deviceLoginHook once when a user logs in. If you want to have two recipes called on login, then you must call them both from one deviceLoginHook() function.

A simple way to call recipe 2 after recipe 1 is:

1. Copy the first recipe into your script and rename its deviceLoginHook to deviceLoginHook1.

2. Copy the second recipe into your script and rename its deviceLoginHook to deviceLoginHook2.

3. Below the two renamed recipes (at the very end of the script text) add a deviceLoginHook function that calls deviceLoginHook1 then deviceLoginHook2/:

   function deviceLoginHook(inputs, actions) { deviceLoginHook1(inputs, actions); deviceLoginHook2(inputs, actions); }

Troubleshooting a combined script

If your combined script doesn’t work on your device:

1. Check that recipe 1 alone works on your device. You can do this by saving the combined script in a text editor and re-importing recipe 1.

2. Check that recipe 2 alone works on your device. You can do this by saving the combined script in a text editor and re-importing recipe 2.

3. Confirm that it makes sense to call recipe 2 after recipe 1.

4. If the combined script still doesn’t work, there might be some JavaScript knowledge required. You should discuss your script with someone who knows more about JavaScript.

Using common scripts

If you have a large number of devices, you might consider using a common script that is called from each devices script. This allows reuse of JavaScript code and functions without the need to copy script code to all devices. It also makes it much easier for administrators to change and edit the scripts being used on multiple devices as it needs to be changed only once.

Writing a common script involves creating a single JavaScript file on your PaperCut MF Application Server with all of the functions you want to reuse. These functions are created much like they would in the Scripting window for a single device.

To create a common script file:

1. In a text editor (such as Notepad++) create a new file.

2. Save the file as device-script-common.js in[PaperCut MF install path]/server/custom/.

3. Create the script on a test device, testing all variables of the script to ensure it works as intended.

4. Once your script is working and you are happy with how it’s running, add it to the device-script-common.js file.

5. Call this function in the device script by adding a line below the main function that calls the function in the device-script-common.js. For example, the function in device-script-common.js might be called blockAccessAfterHours.

6. Test that your device script works before deploying to a live device.