Creating an Admin Task

This is a Confluence 5.0 feature. See Preparing for Confluence 5.0 for details.

Applicable:

This tutorial applies to Confluence 5.0.

Level of experience:

Intermediate. Our tutorials are classified as 'beginner', 'intermediate' and 'advanced'. This one is at 'intermediate' level. If you have never developed a plugin before, you may find this one a bit difficult.

An Admin Task is visible on the console when the admin clicks the cog, then Administration:

On this page:

Required Knowledge

If you are unfamiliar with plugin development, we recommend that you read the guide to developing with the Atlassian Plugin SDK before you read this document. You may also want to read Common Coding Tasks for an overview of the plugin framework. Some experience with Maven is assumed for plugin development. If you haven't used Maven before, you may want to read the Maven documentation to familiarise yourself with it.

General Information

An admin task is configured like this:

atlassian-plugin.xml
    <resource type="i18n" name="i18n" location="plugin-i18n"/>

    <web-item key="plugin-admin-task" section="system.admin.tasks/general" weight="150">
        <label key="plugin.admin.task.title"/>
        <description key="plugin.admin.task.description"/>
        <link id="configure-mail">/admin/mail/viewmailservers.action</link>
        <condition class="com.atlassian.examples.DefaultMailServerExistsCondition" invert="true"/>
    </web-item>

Please use the <condition>

To ensure a smooth experience for admins, please do not surcharge the admin console. In particular, please make use of the <condition> to automatically dismiss the task as soon as it seems the users knows how to configure your plugin.

Is an Admin Task the best medium for your information?

 The most common admin task for add-ons is to let the administrator discover and configure your features. UPM has a specific plugin point for this usecase. Please look at the details for post.install.url and post.update.url on the following page: Plugin metadata files used by UPM and Marketplace.

Admin tasks have a few components:

Component Description Available for core tasks

Available for plugins

See example below and on Web Item Plugin Module for details about each tag

Checkbox The administrator can mark tasks as viewed, so they appear in "View all completed tasks". Some tasks should not be dismissed and have no checkbox. (tick) Optional (tick) Mandatory
Title Bold line of text. (tick) (tick) Use <label>
Description Gray text under the title. (tick) (tick) Use <description>
Current Value Some tasks are associated to one or several values which are displayed under the description. (tick) (error) Plugins can't display the current value of the task.
Configure An edit icon with a link labelled "Configure". The url is chosen by the plugin. (tick) (tick) Plugins can't rename the title of the link. Alternatively, plugins can use the description to redirect to their screen and not use the link. Use <link>.
Condition The task only appears on the Admin Console if some conditions are fulfilled. (tick) (tick) If the condition is false, the task is not displayed at all, even in "completed tasks". Use <condition>.

Download the example from BitBucket

The source for this tutorial is available on BitBucket: https://bitbucket.org/atlassianlabs/confluence-5.0-plugin-points

Create a Confluence plugin

Create a Confluence plugin using the SDK:

atlas-create-confluence-plugin
cd my-plugin
atlas-run

If you encounter issues creating the Confluence plugin, please review the Beginner tutorials and/or submit issues to the AMPS bugtracker.

Add the WebItem for the task

In atlassian-plugin.xml, add the following item:

atlassian-plugin.xml
    <resource type="i18n" name="i18n" location="plugin-i18n"/>

    <web-item key="plugin-admin-task" section="system.admin.tasks/general" weight="150">
        <label key="plugin.admin.task.title"/>
        <description key="plugin.admin.task.description"/>
        <link id="configure-mail">/admin/mail/viewmailservers.action</link>
        <condition class="com.atlassian.examples.DefaultMailServerExistsCondition" invert="true"/>
    </web-item>

Add the translations in plugin-i18n.properties:

plugin-i18n.properties
plugin.admin.task.title=Did you know you could let Confluence send e-mail notifications?
plugin.admin.task.description=The Mail Notification plugin hasn''t been configured yet. Check it out!

Write a condition for your task

In the file src/main/java/com/atlassian/examples/DefaultMailServerExistsCondition.java, add the following code:

DefaultMailServerExistsCondition.java
public class DefaultMailServerExistsCondition implements Condition
{
    final MailServerExistsCriteria mailServerExistsCriteria;
    public DefaultMailServerExistsCondition(MailServerExistsCriteria mailServerExistsCriteria)
    {
        this.mailServerExistsCriteria = mailServerExistsCriteria;
    }
    @Override public void init(Map<String, String> params) throws PluginParseException
    {
        // Do nothing
    }
    @Override public boolean shouldDisplay(Map<String, Object> context)
    {
        return mailServerExistsCriteria.isMet();
    }
}

Launch your plugin

After running atlas-run, Confluence should start with the new Admin Task. You're done!

Related Content

Plugin Metadata Files used by UPM and Marketplace

Web UI Modules

Conditions for WebItems

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport