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.
Status:	DEPRECATED. Starting from Confluence 5.5 menu has been changed, this feature is no longer applicable.

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

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

1
2
<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.	Yes. Optional	Yes. Mandatory
Title	Bold line of text.	Yes	Yes. Use <label>
Description	Gray text under the title.	Yes	Yes. Use <description>
Current Value	Some tasks are associated to one or several values which are displayed under the description.	Yes	No. 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.	Yes	Yes. 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.	Yes	Yes. 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:

1
2
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

1
2
<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

1
2
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

1
2
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!

Plugin Metadata Files used by UPM and Marketplace

Web UI Modules
Conditions for WebItems