You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 10
Next »
A short introduction to manage (add, alter, remove) userscripts with the Userscripts for Confluence App.
The Userscripts for Confluence add-on requires a basic configuration by the userscripts administrators to serve the appropriate userscripts for the users. This configuration requires two steps:
- Manage userscripts in a script repository
- Configure userscripts for activation
This short introduction shows you how to setup a script repository and how to configure your first userscript.
Manging a Script Repository
The userscript code is typically stored on remote server or on a collection of Confluence pages as attachments.
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 activation record.
The remote repository may be a Git server or any other server that can be connected to Confluence and server files.
To provide access to a remote server this server probably needs to be on the Confluence Whitelist. If there is authentication involved, the remote repository must be configured with 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.
Using a Confluence Space
If the userscripts administrator team does not want to use a remote repository, the scripts can be served from Confluence pages, too.
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 activation record.
Managing Userscripts in Confluence
The userscripts resource manages metadata and a reference to the userscript code. Therefore it provides operations to add, remove, and alter userscripts.
The userscript consists of
- an identifier consisting of
namespace, name, and version - a reference to the userscript code (
script) - metadata, like a
description, a reference to further information (documentation), and an support - an activation record (
activation) that defines when the userscript is actually executed
The following fragment shows the basic structure of a userscript in JSON.
{
"namespace": "...",
"name": "...",
"version": "...",
"script": "...",
"description": "...",
"documentation": "...",
"support": "...",
"activation": {
"space": ["...", ...],
"category": ["...", ...],
"label": ["...", ...],
"group": ["...", ...],
"user": ["...", ...]
}
}
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.
Then the userscript configuration would look something like this:
{
"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",
"author": "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 confluence administrators or the userscripts administrators.
To create a new userscript post the JSON representation to the server with Create Userscript by JSON.
