Managing Userscripts

...

Section

title	Managing a Script Repository

The userscript code is typically stored on remote server or on a collection of Confluence pages as attachments.

Section

title	Using a Remote Repository

A remote repository is a service connected to the web so that the Confluence server can access the resources via the Hypertext Transfer Protocol (HTTP). All the remote server must be capable of is to serve userscript files referenced by an Uniform Resource Locator (URL) via HTTP. The URL will then be added to the resource and enriched with metadata and an

Static Document Link

document	Activation Record
to-lower-case	true

.

The remote repository may be a Git server or any other server that can be connected to Confluence and server files.

Note Box

title	Remote Access Configuration

To provide access to a remote server this server probably needs to be on the

Static Document Link

document	Confluence Whitelist

. If there is authentication involved, the remote repository must be configured with

Static Document Link

document	Confluence Application Links

.

Once the remote repository is configured to be accessed from the Confluence server, you need to add the JavaScript files to be used as userscripts.

Caution Box

title	Security Alert!

Since these scripts will be executed in the browser of the Confluence users, you need to protect these code files from being changed by anyone but your userscript team.

In case an attacker manages to change these files, this will wreak havoc since users execute malignant code in a trusted environment!

Section

title	Using a Confluence Space

If the

Static Document Link

document	Userscripts Administrator
label	userscripts administrator team

does not want to use a remote repository, the scripts can be served from Confluence pages, too.

Tip Box

title	Script Repository Space

The

Static Document Link

document	PDAPP:Doctypes for App User Manuals

provide a space names

Static Document Link

document	PDAPP:Script Repository

to manage userscripts in Confluence.

Simply add the JavaScript file as an attachment to a page and copy the Uniform Resource Locator (URL) to this attachment. The URL will then be added to the resource and enriched with metadata and an

Static Document Link

document	Activation Record
to-lower-case	true

.

Caution Box

title	Security Alert!

Since these scripts will be executed in the browser of the Confluence users, you need to protect these code files from being changed by anyone but your userscript team.

In case an attacker manages to change these files, this will wreak havoc since users execute malignant code in a trusted environment!

Please note that the access privileges on the Confluence pages having the userscripts attached are not checked by the userscript activation process! This is necessary since scripts may need to be executed by anonymous users without giving everyone access to the script code.

...

Section

title	Managing Userscripts in Confluence

The

Static Document Link

document	Userscripts
label	userscripts resource

manages metadata and a reference to the

Static Document Link

document	Userscript (Glossary)
to-lower-case	true

code. Therefore it provides operations to add, remove, and alter userscripts.

Tip Box

This shows how to use the REST service via the REST API Browser directly.

An alternative way to administrate userscripts is the use of the

Static Document Link

document	Userscript Admin Tool

. The tool provides a simpe simple GUI to create, search, edit, and save userscripts.

Transclusion

document	Userscript (Glossary)
ids	anatomy-of-userscript

Section

title	Add Userscript

Suppose you want to add a script named hello-world.js, stored on a remote server and accessible by the URL https://example.com/userscripts/hello-world.js.

Code Block

language	js
title	Hello World! Userscript

"use strict";

console.log("Hello World!");
alert("Hello World!");

Then the userscript configuration would look something like this:

Code Block

language	js
title	Userscript Descriptor in JSON

{
  "namespace": "org.example.scripts",
  "name": "hello-world",
  "version": "1.0",

  "script": "https://example.com/userscripts/hello-world.js",

  "description": "Displays an alertbox with the text 'Hello World!'.",
  "documentation": "https://example.com/userscripts/hello-world.html",
  "support": "Scripts Team",

  "activation": {
    "space": ["UES"],
    "group": ["userscripts-evaluation-team"]
  }
}

In this example the hello world script will be executed on each page within the Userscripts Evaluation Space (with space key UES) if the user is member of the Group userscripts-evaluation-team.

To access this resource users require to be a member of the

Static Document Link

document	Confluence Administrator
label	confluence administrators

or the

Static Document Link

document	Userscripts Administrator
label	userscripts administrators

.

Transclusion

document	Userscripts
ids	Operations

To create a new userscript post the JSON representation to the server with

Static Document Link

document	Create Userscript by JSON

.

Tip Box

Any REST client can interact with the REST API of the Userscripts for Confluence app. The

Static Document Link

document	Atlassian REST API Browser
label	${Short Name}

may be convenient for administrators that want to use the API once in a while via a user interface from within Confluence.

Screenshot showing the userscript in the user interface of the REST API Browser on Confluence.

After creating the userscript, check if it is accessible.

Screenshot shows the REST API Browser with the Userscript Identifier to check if it is accessible.

If everything is configured successfully, you should get a HTTP response with status code 200 and the listing of the hello world userscript code.

To test which userscripts are actually activated, you could use the

Static Document Link

document	Userscripts Context Service

. Currently it is only possible to use this service for the currently logged in user. So if there is a space with space key UES and you are member of the Confluence group names userscripts-evaluation-team, then provide the page identifier to the service. The service returns a list of URLs to activated scripts. The hello world userscript should be member of this list.

And whenever member if the group visits the space, there is log message in the browser's console and an alert box popping up.

Section

title	Update Userscript

To update a userscript simply load the current userscript, alter the properties, and store it back using PUT.

Warning Box

title	Scripts are cached

Please note that for better performance the scripts are cached. Scripts are identified via HTTP by their namespace, name, and version.

Therefore the version of the userscript requires to be altered whenever the code of the userscript is changed.

If the version is not altered, the browser will execute a cached (old) version of the script.

...

Section

title	Resources

Tour

render-no-hits-as-blank	true
render-as-definition-list	true
marker-column-property-name	Title
replace-title-with-name	true

Title	Short Description
Userscript Admin Tool

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 24

New Version Current

Key

About

Keep up-to-date!

Powered by