administration.pngApplication for administrating wiki features like users, groups, rights etc.
Developed by

XWiki Development Team

1 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager

Installable with the Extension Manager


The administration application allows you to administrate an XWiki instance. It offers both a generic framework for allowing other applications to register administration screens and also provides several screens itself (see below).

If you're installing this application on an existing XWiki installation you should be very careful. If you're using the Distribution Wizard you should be safe as it'll check do an automatic merge and warn you in case of conflicts. However if you're doing a manual import then make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care: 

  • XWiki.XWikiPreferences: This page contains the configuration of your wiki (it overrides the configuration defined in xwiki.cfg). If you import a new version of this page you'll lose any customization you may have made such as the skin to use, the rights for your wiki, etc.
  • XWiki.XWikiAllGroup (list of registered users) and XWiki.AdminGroup (list of Admins): If you have existing users and import a new version of these pages, you'll find that your users do not belong to these groups anymore and thus may not be able to edit pages, log in, etc. You'll need to add them again to the right groups.
  • XWiki.RegistrationConfig: Contains your registration settings. Overwrite it will go back to using the defaults.
  • Any other page from the Administration application that you have modified, such as XWiki.DefaultSkin.

Provided Features

This is what you see when you go the global Administration page:


Some of the Admin Categories are provided by the Administration Application itself (described below) and others are contributed by other extensions using the Configurable Class mechanism (described in the contributing extension).

Edit Mode Settings


See also:



See also:



See also:

Page Elements








See also:



These settings control the Registration process and also the L&F and the behavior of the Registration page you get when you click on the Register button in the XWiki UI (top right part of the screen).

Registration page:


The registration page supports image captchas supplied by the captcha module and also validating the input fields both on the server side and in Javascript using LiveValidation.

The Registration page does not require programming rights to operate so you can configure it even if you are administrating a virtual wiki on a wiki farm.

Activating captchas

In order for the registration page to require a captcha to be solved for registration, you will have to activate it. You can do this from the Registration section of the wiki administration interface.

Options you can set from the Registration section of the Administration Interface

  • Use Email Verification. If set to "Yes" then an email will be sent to the email address used when filling the Registration page.
  • Authentication Active Check. If set to "Yes" it will prevent the users from logging in without entering the token which was previously sent in the email.
  • Validation Email Content. The email template that corresponds to the mail that is sent when "Use Email Verification" is active. The template is in MIME format. For example this allows to send HTML emails; here's an example:
    #set ($wikiname = $request.serverName)
    #set ($host = ${request.getRequestURL()})
    #set ($host = ${host.substring(0, ${host.indexOf('/', ${mathtool.add(${host.indexOf('//')}, 2)})})})
    Subject: Validate your account on ${wikiname}
    Content-type: text/html; charset=iso-8859-1

    <p>Hello <b>${xwiki.getUserName("XWiki.$xwikiname", false)}</b>,</p>
    <p>This email address was used to register a new account on ${wikiname}. If you did not make the request, please ignore this message.</p>
    <p>In order to activate your account, please follow this link:
    ${host}${xwiki.getURL('XWiki.AccountValidation', 'view', "validkey=${validkey}&xwikiname=${xwikiname}")}</p>
  • Confirmation Email Content. The email template that corresponds to the mail that is sent when the user validates his account by clicking in the validation link in the first email he received (i.e. the mail corresponding to the "Validation Email Content" template). Similarly to the "Validation Email Content" this field can contain any valid content in MIME format.
  • Registration page heading
    • This is the line at the top of the page which is shown to people who are registering and when they have just registered.
  • Welcome Message
    • This is only shown when people are filling out the form.
  • Enable Javascript field validation (Default: Yes)
    • Set this to false and LiveValidation javascript will not be generated (fields will still be validated at the server side.)
  • Default field okay message (Default: 'Ok.')
    • LiveValidation shows a message to indicate to users that they have filled in the field satisfactorily. This is the message they will get if it is not overridden for a particular field.
  • Enable login button (Default: Yes)
    • When the user has registered, we provide a button for them to click which will post their username and password to the login action and get them logged in right away. This however causes the username and password to be passed back in the HTML which may be unacceptable depending on your security needs.
  • Enable automatic login (Default: No)
    • If login button is enabled, then you can have a piece of Javascript push the login button for the user.
  • Redirect here after registration (Default: Main.WebHome)
    • This is the page which the user will be redirected to after pushing the login button if the xredirect parameter is not specified.
  • Require captcha to register (Default: No)
    • Set this true to require the user to solve a captcha in order to register.

Things which you may configure by editing XWiki.Registration

In XWiki.Registration, the fields are defined separately from the code which generates the HTML. You can add or remove fields simply by modifying the configuration. Fields are defined as maps. The maps are each required to have a 'name' key which must map to a string. This string will be the id and name of the field when it is rendered into HTML.

label (string)
This is what the user is prompted with above the field for their input.
tag (string)
Usually a field is an input field but if you specify a different tag (eg: textarea) then it will not be an input type field. You can even specify non field tags such as <img> or <div> but it may cause invalid HTML to be generated.
params (map)
This map corresponds to the HTML parameters of the tag. If you specify params to be { 'class' : 'someclass', 'style' : 'color:red;' } then the HTML tag will read <input class="someclass" style="color:red;">
noReturn (boolean)
If this is specified, the field will not be filled in if there is an error and the user has to fix their registration information. If you don't want a password to be passed back in html then set this true for the password fields. Used for the captcha because it makes no sense to pass back an incorrect captcha answer.
doAfterRegistration (string)
Some Velocity code which will be executed after a successful registration. This is used in the favorite color example. Remember to put the code in single quotes (' ') because you want the 'code' entry to equal the literal code, not the output from running it.
validate (map)
This map is the most complex and is covered later on in this section.

Here is the definition of a field which is used in the registration page:

## The user name field, mandatory and programmatically checked to make sure the username doesn't exist.
#set($field =
  {'name' : 'xwikiname',
    'label' : $msg.get('core.register.username'),
    'params' : {
      'type' : 'text',
      'onfocus' : 'prepareName(document.forms.register);',
      'size' : '20'
    'validate' : {
      'mandatory' : {
        'failureMessage' : $msg.get('XWiki.Registration.fieldMandatory')
      'programmaticValidation' : {
        'code' : '#nameAvailable($request.get("xwikiname"))',
        'failureMessage' : $msg.get('core.register.userAlreadyExists')
#set($discard = $fields.add($field))

Line by line it is:

  • A comments and the beginning of a set directive.
    • name is set to 'xwikiname'
    • label is set to 'User Id:' or translation there of.
    • params is set to a new map
      • params map gets type set to 'text'
      • params map gets onfocus set to some Javascript
      • params map gets size set to '20'
    • End of params map
    • validate is set to a new map.
      • validate map gets mandatory set to new map.
        • validate.mandatory gets failureMessage set to 'this field is mandatory' or translation there of.
      • validate.mandatory is ended.
      • validate gets programmaticValidation set to new map
        • validate.programmaticValidation gets 'code' set to a macro call which will check if the username is taken.
        • validate.programmaticValidation gets 'failureMessage' set to a message telling the user that the name is taken.
      • validate.programmaticValidation map is closed.
    • validate map is closed.
  • Map for this field is closed and set directive ends.
  • This field is added to the fields array and the output from the add function is set to discard to avoid having it print on the page.

Validation Constraints

The validate field configuration key is itself a map which allows a number of parameters to be defined. Validation is done in the order of mandatory, then regex, then mustMatch, then programmatic validation so if nothing is entered and the mandatory constraint is not in place then the entry will be accepted and if a entry fails the regex test then it will not be evaluated programmatically.

  • mandatory (Optional)
    • Will fail if the field is not filled in.
    • failureMessage (Required)
      • The message to display if the field is not filled in.
    • noscript (Optional)
      • Will not be validated by Javascript, only on the server side.
  • regex (Optional)
    • Will validate the field using a regular expression. because of character escaping, you must provide a different expression for the javascript validation and the server side validation. Both javascript and server side validation are optional, but if you provide neither, then your field will not be validated.
    • failureMessage (Optional)
      • The message to display if the regex evaluation returns false, note that this is sent in HTML so &lt; will display as <
    • jsFailureMessage (Optional)
      • The message for Javascript to display if regex fails. If jsFailureMessage is not defined Javascript uses failureMessage. NOTE: Javascript injects the failure message using createTextNode so &lt; will be displayed as &lt;
    • pattern (Optional)
      • The regular expression to test the input at the server side, it's important to use this if you need to validate the field for security reasons, also it is good because not all browsers use javascript or have it enabled.
    • jsPattern (Optional)
      • The regular expression to use for client side, you can use escaped characters to avoid them being parsed as Javascript code. To get javascript to unescape characters use: "'+unescape('%5E%5B%24')+'"
        • NOTE: If no jsPattern is specified, the jsValidator will try to validate using 'pattern'.
    • noscript (Optional)
      • Will not be validated by Javascript, only on the server side.
  • mustMatch (Optional)
    • Will fail if the entry into the field is not the same as the entry in another field. Used for password confirmation.
    • failureMessage (Required)
      • The message to display if the field doesn't match the named field.
    • name (Required)
      • The name of the field which this field must match.
    • noscript (Optional)
      • Will not be validated by Javascript, only on the server side.
  • programmaticValidation (Optional)
    • This form of validation executes a piece of Velocity code which you give it and if the code returns the word "failed" then it gives the error message. Remember to put the code in single quotes because you want the value of 'code' to equal the literal code, not the output from running it (Velocity parses code in double quotes)
    • code (Required)
      • The code which will be executed to test whether the field is filled in correctly.
    • failureMessage (Required)
      • The message which will be displayed if evaluating the code returns "false".
  • fieldOkayMessage (Optional)
    • The message which is displayed by LiveValidation when a field is validated as okay. If not specified, will be the LiveValidation default field ok message

User Profile







It's possible for users and applications to provide pages that can be used as template when creating new pages.

Creating Templates

  • A template is a wiki page. If you want to make an existing page a template then skip to the next section. Otherwise, let's create a new template page. Go to the wiki home page and click on the create page button (the "+" button).
  • As you can see the Create Page dialog lists the available templates that can be used to create new pages. We want to add our template there. But first we need to create it so select "Blank page".
  • Write the template content and save.
  • This is what you will see at this stage:
  • Note that advanced users can edit the template page in object mode and add meta data that will be copied along with the page content when the template is used. Of course, if you add an object that has a dedicated sheet then the template will look different in view mode, depending on the sheet.

Create the Template Provider

To do this go to the administration and click on the "Templates" link from the "Content" category.

From the "Templates" administration section you can:

  • View the list of Available Template Providers
  • Create a Template Provider


A template provider is a wiki page whose main role is to expose the template on the Create Page dialog so that the users can create new pages based on the template. To create a template provider specify the title and location fields then hit the Create button (see image above). Naming the template provider after the template you've just created is a good practice.

Next you will need to fill in the template provider form. Make sure the following fields are filled in:

  • The provider name - the name displayed in the list of available template providers, in the Templates section, in Administration (e.g. My Template Provider)
  • The template name - the name displayed in the list of available templates, in the Create Page form (e.g. My Template)
  • The template to use - the page that will be used as template when this template provider is used to create a new page (e.g. Main.MyTemplate)


Until 7.3M2 there was also a Template Type configuration (with Page and Space options) which was removed since it was not really used.

Location Restrictions

Since 8.3M2 there are 2 types of location restrictions that you can enforce:

  • Visibility restrictions
  • Creation restrictions

Visibility restrictions specify the list of locations where the template provider will be visible to an user that is creating a new page. This allows you to control what type of content you are proposing your users to create, depending where they are trying to create it from. E.g.: propose to create expense reports only when creating a page from the "Expense Reports" location.

A provider that specifies no visibility restrictions is visible, in the Create Page dialog, from any page inside the wiki.

In order to add a visibility restriction you need to edit the template provider and click on the "+" icon below "List of locations where the template must be available". This will open a popup with the page tree from which you can select one or multiple locations. For instance, if you select the "Home" page then your template will be available only when you create a page from the "Home" page or one of its child pages.

Creation restrictions, as the name implies, specify the list of locations where the template provider allows the creation of pages. This allows you to control where your users are allowed to create various types of content. E.g.: restrict the creation of "Evaluations" only to the "HR" location (i.e. as direct or indirect children of the "HR" page).

A provider that specifies no creation restrictions can be used to create pages anywhere in the wiki.

Specifying a creation restriction also has the effect of prefilling the destination location on the Create Page form. When switching between template types on the creation form, if the newly selected template has a creation restriction, the parent location field will be prefilled with one of the template's restrictions. However, if such a template provider has additionally checked the Creation restrictions as suggestions option, then the creation restrictions will not be enforced and will only be used for identifying the default parent location which is prefilled in the creation screen, while the user is still being able to change the parent to something else, outside those restrictions.

In order to add a creation restriction you need to edit the template provider and click on the "+" icon below "Creation restrictions". This will open a popup with the page tree from which you can select one or multiple locations. The creation restrictions are used on the Create Page form to validate the location field.


Before 8.3M2 there was a single spaces property specifying both the places where the template was visible and also where the template could be used to create pages, but it was split into the 2 above described restrictions to allow more flexibility and visibility of the templates feature. We are still supporting old (pre 8.3M2) template providers by reading from their spaces property, but if both the new restrictions and the spaces property are used, the new restriction properties will have priority.

Advanced: Creating terminal pages with template providers

Since 7.3RC1, when you create or edit a template provider, as an advanced user, you can also specify if the pages that will be created with it should be terminal or not.


If the Terminal Page option is set to Yes, then when you select the template provider in the create page step:

  • If you are an advanced user, the Terminal Page checkbox will be checked by default. You can still override the template provider's option and uncheck it manually so that the page is created as non-terminal instead.
  • For regular users, the Terminal Page checkbox is not displayed in the create page step, so the page that will be created will respect the preference specified in the template provider's terminal xproperty.

Using the templates

  • After you have created the template and the template provider you can go back to the home page and start creating pages from this template:


  • We can see that the content of the new page has been copied from the selected template.


  • This example shows that you are offered the choice to create a new page from the available template ("My Template" template in the image below) for broken links:


Using a hierarchy of Nested Pages as template

Since 7.4M2, when the template document specified by the template provider is a Non-Terminal document which, in turn, has several descendant documents under its path, a template document hierarchy is established. Whenever creating a new document using this template, the entire template hierarchy will be copied over to the location of the new document.

To create a template hierarchy, simply create a hierarchy of documents and select the root of the hierarchy as template document, when creating your template provider.


  • The available "MyTemplate" document hierarchy to use:


  • We create a template provider with the display name "My Template" and set "MyTemplate.WebHome" as the template document to use.
  • Creating a new document called "MyNewDocument" by using the template "My Template" will result in the following new document hierarchy being created:


Note: when saving the newly created document for the first time, a notification will be displayed at the bottom of the edit form, displaying progress information (and the form will be disabled when pressing Save & View):

Google Analytics

XWiki provides a built-in integration for Google Analytics. To use it simply choose the Analytics mode (Universal or Classic - Check the Google documentation to decide which one is best for you) and fill in your tracking id:


If you have multiple subwikis in your wiki, you'll need to configure each subwiki that you wish to track with a tracking id (it can be the same one across wikis). There's currently no way to specify the tracking id once for all subwikis.

Making your application configurable with ConfigurableClass

So you have created the best application since sliced bread and like a good application designer you made it extensible, and configurable. At the last moment you realize most people don't want to edit configuration files in order to configure an application, what are you to do? You could create a class with properties for each of the configuration options. You could even create a page with an easy to use form but that's a bunch of HTML to write for an application which now has a configuration page that nobody will ever find. There must be an easier way.

What you have to do is:

  • create a custom configuration class for your application (say MyAppCode.CustomConfigurationClass)
  • create a page that will hold the configuration of your application (Say MyApp.Configuration)
  • add an object of your custom configuration class (MyAppCode.CustomConfigurationClass) to the previous document (MyApp.Configuration)
  • add an object of the XWiki.ConfigurableClass to the same document (MyApp.Configuration)
  • set up the XWiki.ConfigurableClass object (see below) and voila!

Your application has now its own configuration form in the administration application where it belongs to.

The current user does not have edit access to any of the applications in the section at the bottom left so it displays "No Access".

How it works

You add an XWiki.ConfigurableClass object to your configuration document and add to it an object of the configuration class (your custom class) which you just defined. You also have to define the section in the administration application where your form should be displayed. When administrators go to the administration application, they will see your configuration form right where it ought to be. This is because the administration application queries the database for XWiki.ConfigurableClass objects and puts them at the right place. Administration application also takes care of generating the HTML form for you so all you have to do is define the custom configuration class.

What happens if I add more than one XWiki.ConfigurableClass object?

By using multiple ConfigurableClass objects which list different custom configuration classes but are set to display in the same section, you can make a single form with settings from multiple custom configuration objects. If instead you add multiple ConfigurableClass objects which are set to be configured in different sections, you can allow your application to be configured in different sections. You can even use the propertiesToShow field to determine which properties should be shown and which should be hidden in the form displayed by a given ConfigurableClass object.


Here you see the result of a single application with two ConfigurableClass objects. Each object is set to display in the same section (the section you see) and they both are set to use the same custom configuration class. Each object only displays two of the custom configuration class's four properties because they have propertiesToShow set. The values of the heading property for the two objects are set to "Section 1" and "Section 2". Also where it says "Test section" is customizable by adding a language pack.

Fields you can define

  • displayInSection (String) - Which section should your application be configured in General? Registration? Rights? You can even define a section which doesn't already exist and a new icon will be displayed in the administration main page.
  • heading (String) - You can add multiple ConfigurableClass objects to your document with different headings and the properties of each will be displayed under the heading. If you are only using a single ConfigurableClass object for your application, then you should leave this blank. Also note that this field is evaluated, so if you need to translate a heading you can directly use $services.translation.render('someKey') as value.
  • configurationClass (String) - This is the name of the custom configuration class which you defined to hold the configuration parameters. If you leave this blank then no form will be created.
  • configureGlobally (boolean) - Set this true if your application should be configured in the global administration page and false if it should be configured in the administration page for the space which the application resides in.
  • linkPrefix (String) - The pretty names of the properties in your custom configuration object will be displayed on the administration page but most of the time those names are not enough of a description, if this is filled in, then each name will be a link to a page, the link will be the value of this field with the name appended (the name not the pretty name). If you set linkPrefix to and the name of one of the configuration options is 'some_config_option' then the pretty name for that option will be a link to This field is evaluated so you may use velocity code eg: $xwiki.getURL('Space', 'Page') .
  • propertiesToShow (List) - If your custom configuration class contains properties which you don't want to display on the form, or if you need more than one ConfigurableClass object which point to the same custom configuration object, then you can fill this in with the names of the properties which should be displayed in the form. The properties will be displayed using their (translatd) pretty names. Since 7.1M1 you can also specify hints / descriptions to better document your displayed fields by adding a translation key of the following format: Space.ConfigurationClass_propertyName.hint. See the Localization Module for more details on translations.
  • codeToExecute (TextArea) - Suppose a simple form just isn't enough for your needs, you can enter Velocity script here and it will be executed. If you leave configurationClass blank, then this is the only code that will be executed and you are free to design your own form. It is important to know that if you do use the default form, codeToExecute is executed before the form is begun, however if you have multiple ConfigurableClass objects in the same application which are also shown in the same section of the administration application (perhaps with different headers) then codeToExecute of any ConfigurableClass object after the first will be executed inside of the form. This is because the administration application tries to do all configuration for one document in a single form to reduce the number of save buttons.
  • iconAttachment (String) - If your application is going to be configured in it's own section of the administration application and you want your own custom icon for that section, you simply attach the icon to the document which has the ConfigurableClass object and set this to the filename of the attachment.
  • displayInCategory (String) - Which category should your application be configured in. This allows to add a new section to an existing category or to create a new category altogether.
  • displayBeforeCategory (String) - Where to locate your new category (if it doesn't already exist). Your category will be displayed before the specified existing category.
  • categoryIcon (String) - The name of the icon to use when displaying the category in the vertical menu. The name should be a valid icon name in the Silk icon set.
  • sectionOrder (Number) - Since XWiki 6.4 RC1 Control the order of the sections. Put a small number to be on the first sections displayed, or a big number to be at the end.

Accessing your configuration

  • In Groovy:
    Groovy example:
    def customObject = xwiki.getDocument("MyApp.Configuration").getObject("MyApp.ConfigurationClass")
    def myAppUrl= customObject.getProperty("myAppUrl").value

    println "$myAppUrl"

The value of myAppUrl would be the value set in the configuration page, for example:


Things to watch out for

  • If you save the configurable application page but you don't have access to the administration page, then your configurable application will not be displayed, instead an error message will tell the administrator that it couldn't be displayed because you couldn't be trusted to run code in the administrator's security context.
  • If somebody has administration access but does not have access to save the configurable application, they will get an error message telling them so.
  • If somebody has administration access but does not have access to view the configurable application then they will receive an error message on the front page of the administration application. This is because it is possible that not all of the icons could be displayed.
  • Documents are locked using Javascript, if the administrator has Javascript turned off then they will receive a warning that the configurable application could not be locked for editing.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions


Created by Jean-Vincent Drean on 2008/06/25 12:33

Get Connected