Open Custom Links In The Same Tab

Custom links in the user navigation menu, Now with Extra Fancy!

“The navigation menu in the user web interface contains links for the PaperCut services that are enabled and available to the user. In some cases, you might want to add additional external links to this menu. Examples include:
Linking to a print policy page on the organization’s intranet.
Linking to a page with key contact details.
A link to return to the “main” intranet page/portal.
Custom links are displayed above the Log Out item.”

From the PaperCut MF/NG manual

Follow the link above to the manual to see you how you can configure these links through the PaperCut admin interface. Any links configured in this way will always open in a new browser tab or windows, which is ideal if you want to guide students to open the learning portal for instance.

But sometimes you want the link to open in the same browser tab and have the user return to PaperCut MF/NG later when they have finished some workflow function, for example when a library user needs to top up their PaperCut MF/NG balance via the library management system payment portal.

The good news is that there is a way to configure this, but this is an advanced ninja level technique that needs to be used with care. So if you have completed your daily nunchuck practice, read on.

In order to follow along you will need to use a command shell prompt (PowerShell on Windows, or sh/Bash on Linux and macOS. Special note for Windows users, it’s unlikely this will work using cmd.exe) on a PaperCut MF/NG application server. You will need enough privilege to run the server-command utility from your shell. You can download PaperCut NG from here and set up a test system on your local workstation.


When you configure a custom link via our admin GUI the settings are stored in an advanced config key. For example

PaperCut admin screen to manage custom links

Run the the following server-command example

server-command get-config user.web.custom-links

and get|Custom Link|_blank

You can also enable/disable the custom links feature with the user.web.custom-links.enabled advanced config key (Set to “Y” to switch on, and “N” to switch off)

If you log into the PaperCut MF/NG (on your test system) as a user (not the admin account) then you should see the “Custom Link” button. When you select the button a new browser tab or window (depends on browser configuration) open to the PaperCut Software website, welcome!.

So let’s make that link open in the same browser tab by changing the targte from _blank to _self

server-command set-config user.web.custom-links||Custom Link|_self

Now when you open the user web interface you get an error message, because I made a deliberate mistake to show what can go wrong. NOTE: This also breaks the PaperCut MF/NG admin interface. Luckily it’s easy to fix, all you need to do is run server-command again with the correctly formatted setting. Before we fix it let’s look at the format of the link specification string when you configure a “ ”single″ link.

<URL>|Label Text|<Target>, where <Target> is the HTML [ [ | target ]] attribute. In this context only the _self, _blank make sense.


  1. The target _self opens the link in the same broweser tab or window, _blank opens the link in a new tab or browser window
  2. The | (pipe) character is special and separates the three fields in the link config string.

So let’s configure it properly

server-command set-config user.web.custom-links "|Custom Link|_self"

And now test the link in the PaperCut user interface, and then hit the back button to return back to PaperCut MF/NG. Success!

Note: Keep this command handy so we can reset back to a good state if we break something later.

So now we can add a single custom link with the _self attribute

If that is all you want to do then you can also edit the user.web.custom-links attribute in the PaperCut MF/NG admin interface, but now (with server-command) we can add multiple custom links with different targets. You can also use the web services API if that rocks your boat.

The user.web.custom-links config attribute does support multiple link config strings, each one separated by a new line (that is a single “\n” character, not the Windows style “\r\n” end of line sequence). Doing this on the command line needs some care to make sure the shell does not mangle the new line character, and it’s slightly different in each shell


In PowerShell the newline character is represented by the sequence `n, and if you look carefully at the next example you see those characters have been added between each link specification

server-command set-config user.web.custom-links `
"http://localhost:8081/simpleTopUpBalance/?user=%user%&return_url=%return_url%|Add Credit|_self`n|CS Courses|_self`n|PaperCut Website|_blank"

Note the “Add Credit” button will get “This site can’t be reached” error message unless you are running this example code.

And of course you can switch the links off (and on) with this

server-command set-config user.web.custom-links.enabled "N"
server-command set-config user.web.custom-links.enabled "Y"

Linux and macOS Example

The POSIX style shells (for example Bash) behave differently. The new line character is literally the “enter” key on your keyboard, but normally the shell usually interprets it as a magic “execute this command” instruction. So we have to type the escape character (\) immediately before we hit the <enter> key and then make sure the whole string is protected with single quotes (‘…’).

./server-command set-config user.web.custom-links \
'http://localhost:8081/simpleTopUpBalance/?user=%user%&return_url=%return_url%|CAdd Credit|_self\|CS Courses|_self\|PaperCut Website|_blank'

So there you have it. Any questions? Please head over to our Google Web Services API integration group

Categories: TODOFirstCategory, TODOSecondCategoryIfNeeded

Keywords: User Interface, Customization, Links, Custom