API - Confluence - Creating and Modifying Pages

Assumptions

This guide assumes that the target audience understands the basics of plugin development in Confluence, and thus will focus on how the API can be used to create pages programmatically via the Confluence API.

Description

This guide describes the steps in order to dynamically create and modify Confluence pages through the standard Confluence API.

Architecture

The basic architecture of a page in Confluence is that it is a single entity which is located as part of a Space, has at most 1 parent page, and may have as many children pages under it as you want. It has a set of attributes such as permissions, labels, attachments, content, title, etc.

Sample Code

Note that the following code sample is valid for Confluence 2.9, there might be differences when using different versions of the Confluence API.

Useful Classes/Managers

PageManager

• Used to obtain Page objects by id/space key and page name
• Used to persist updates to pages to the database
• Can be obtained either via Spring's auto injection

  public void setPageManager(PageManager pageManager)
  {
      this.pageManager = pageManager;
  }
  

  or via the ComponentManager

  PageManager pageManager = ContainerManager.getComponent("pageManager");
  

Creating a Page

To create a page simply create a Page object, set the required parameters (title, space and content), and then using the PageManager to save these changes to the database.

public void createPage(Space space, String title, String content) 
{
    Page page = new Page();
    page.setTitle(title);
    page.setSpace(space);
    page.setContent(content);
    ....
    //You may set the other attributes for the page here using the page.setXXX and page.addXXX methods
    ....
    pageManager.saveContentEntity(target, null);
}

Updating a Page

Updating a page is fairly simple as long as you can get the correct Page object and remember to use the PageManager to save the changes that were made.

In order to get the right page, you will need one of 2 things:
1. The page id (this is an unique number given to a Page object when it is created in the database)
2. The key for the space the page is in, and the name of the page
Then simply use either:

pageManager.getPage(id); //id is a long

or

pageManager.getPage(spaceKey, pageName); //both spaceKey and pageName are String objects

There is a special case for pages which can be obtained differently, this is the HomePage of the space, which can be gotten from the Space object, simply just call

 space.getHomePage(); 

method.

public void updatePage(Page page, String content) throws CloneNotSupportedException
{
    Page originalPage = page.clone();
    page.setContent(content);
    ....
    //You may set the other attributes for the page here using the page.setXXX and page.addXXX methods
    ....
    pageManager.saveContentEntity(page, originalPage, null);
}

As you may have notice, here we created a clone of the page and stored it as the original page, this retains the original state of the page prior to modifying it, this is used to maintain the page history. Also note that we use a different version of the saveContentEntity method, this one accepts 3 parameters, the first is the modified page, the second is the original page, and the third is the save context (which can be null).

Modifying the Hierarchy

This is fairly simple to modify as each Page object contains references to 0 to multiple children Page(s) and a link to the parent Page, the thing to be careful of is the referencing between the pages, when setting the children pages of a page, it is always good to ensure that the children point back to the parent so all the references are valid.

To add a child:

page.addChild(childPage);

To remove a child:

page.removeChild(childPage);

To update the reference to the parent:

page.setParentPage(parentPage);

Please note that you can also set the parent use page.setParent(parentPage) to set the parent, however in Confluence 2.9 this method is deprecated in the API so it is best to use the setParentPage method instead.

Restrictions

Page titles should NOT contain the following characters:

or start with:

Related Material