Confluence Task

The confluence task supports operations on the popular content collaboration tool Atlassian Confluence.

• Usage
• Overview

Possible operations are:

• Create a Page
• Update a Page
• Add a comment
• Upload an Attachment
• Create a Child Page
• Delete a Page
• Get page content

Usage

To be able to use the confluence task in a Concord flow, it must be added as a dependency:

configuration:
  dependencies:
  - mvn://com.walmartlabs.concord.plugins:confluence-task:2.5.0

This adds the task to the classpath and allows you to invoke the Confluence task.

Overview

The confluence task allows users to trigger operations on a Confluence server as a step of a flow. It uses a number of required input parameters that are common for all operations:

• apiUrl - URL to the API endpoint of the Confluence server, e.g https://confluence.example.com/rest/api/
• action - determines the operation to be performed with the current invocation of the confluence task
• userId - identifier of the Confluence user account to use for the interaction
• password - password for the user account to use, typically this should be provided via usage of the Crypto task to access a password stored in Concord or decrypt an encrypted password string.
• ignoreErrors - boolean value, if true any errors that occur during the execution are ignored and stored in the result variable. Defaults to false.

The apiUrl configures the URL to the Confluence REST API endpoint. It is best configured globally as default process configuration with a confluenceParams argument:

configuration:
  arguments:
    confluenceParams:
      apiUrl: "https://confluence.example.com/rest/api/"

A minimal configuration taking advantage of a globally configured API URL includes the userId, the password, the desired action to perform and any additional parameters need for the action:

flows:
  default:
  - task: confluence
    in:
      action: createPage
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}

All operations are subject to the security configuration of your Confluence and the userId performing the actions. For example, if you attempt to delete a page without the correct rights to delete pages, the action of the task fails.

Create a Page

The createPage action can be used to create a new page with content in a specific space.

flows:
  default:
  - task: confluence
    in:
      action: createPage
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      spaceKey: "MYSPACEKEY"
      pageTitle: "My Page Title"
      pageContent: "<p>This is <br/> my page content</p>"
  - log: "Page Id is ${result.pageId}"
  - if: ${!result.ok}
    then:
    - throw: "Something went wrong: ${result.error}"
    else:
    - log: "Here is Page view info URL: ${result.data}"

Additional parameters to use are:

• spaceKey - string, Required - identifying key for a Confluence space.
• pageTitle - string, Required - title of a page.
• pageContent - string, optional - content to be added to a page.
• template - string, optional - the task supports the use of a separate file for longer content.

As an alternative to pageContent, specify template and point to a file in your project that contains the content text.

template: page.mustache

The template engine Mustache is used to process content template files, so you can use any variables from the Concord process context in the message.

When creating content in a template file, you can reference any variable that is defined in the flow using double open { and closing curly braces } in the template file. You can also pass additional variables as a part of templateParams parameter as shown below

flows:
  default:
  - task: confluence
    in:
      action: createPage
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      spaceKey: "MYSPACEKEY"
      pageTitle: "My Page Title"
      template: content.mustache
      templateParams:
        myVariable1: "content variable 1"
        myVariable2: "content variable 2"
        myVariable3: "content variable 3"

The output of the action is stored in a result variable that has the following structure:

• ok - boolean value, true if the execution is successful;
• data - string value, contains the page view info URL.
• pageId - integer value, contains the id of confluence page created.

Update a Page

The updatePage action can be used to update (append/overWrite) the content of an existing page. By default this action appends text to existing content.

flows:
  default:
  - task: confluence
    in:
      action: updatePage
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      spaceKey: "MYSPACEKEY"
      pageTitle: "My Page Title"
      pageUpdate: "This is an update to an existing content"

Additional parameters to use are:

• spaceKey - string, Required - identifying key for a Confluence space.
• pageTitle - string, Required - title of a page that you intend to update.
• pageUpdate - string, Required - content used to update an existing page.
• overWrite: boolean, if set to true overwrites the existing content. Defaults to false.

The output of the action is stored in a result variable that has the following structure:

• ok - boolean value, true if the execution is successful;
• data - string value, contains the page view info URL.

Add a comment

The addCommentsToPage action can be used to add a comment to an existing page.

flows:
  default:
  - task: confluence
    in:
      action: addCommentsToPage
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      pageId: 32432235
      pageComment: "<p>This is a comment to an existing page</p>"

Additional parameters to use are:

• pageId - integer, Required - Id of a confluence page to which comments are added.
• pageComment - string, Required - comments added to an existing page.

The output of the action is stored in a result variable that has the following structure:

• ok - boolean value, true if the execution is successful;
• data - string value, contains the page view info URL.

Upload an Attachment

The uploadAttachment action can be used to upload an attachment to a specific page.

- task: confluence
    in:
      action: uploadAttachment
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      pageId: 32432235
      attachmentComment: "My attachment comments"
      attachmentPath: path/to/the/attachment.txt

Additional parameters to use are:

• pageId - integer, Required - Id of a confluence page to which file is attached.
• attachmentComment - Required - string, comments added to an attachment.
• attachmentPath - Required - string, path to an attachment file.

The output of the action is stored in a result variable that has the following structure:

• ok - boolean value, true if the execution is successful;
• data - string value, contains the page view info URL.

Get Page Content

The getPageContent action can be used to get the content of a page.

  - task: confluence
    in:
      action: getPageContent
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      pageId: 32432235

Additional parameters to use are:

• pageId - interger, Required - Id of a confluence page

The output of the action is stored in a result variable that has the following structure:

• ok - boolean value, true if the execution is successful;
• data - string value, contains the page content

Create a Child Page

The createChildPage action can be used to create a new page, with content, as a child of another page.

- task: confluence
    in:
      action: createChildPage
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      spaceKey: "MYSPACEKEY"
      parentPageId: 32432235
      childPageTitle: "My Child Page Title"
      childPageContent: "<p>This is <br/> child page content</p>"
- log: "Child Page Id is ${result.childId}"

Additional parameters to use are:

• parentPageId - integer, Required - id of parent page.
• childPageTitle - string, Required - title of child page.
• childPageContent - string, optional - content added to child page.
• template - string, optional - task supports the use of a separate file for longer content. As an alternative to childPageContent, specify template and point to a file in your project that contains the content text.
• templateParams - map, optional - parameter used to define additional variables that can be used when creating content in a template file

The output of the action is stored in a result variable that has the following structure:

• ok - boolean value, true if the execution is successful;
• data - string value, contains the page view info URL.
• childId - integer value, contains the id of child page.

Delete a Page

The deletePage action can be used to delete an existing page.

flows:
  default:
  - task: confluence
     in:
      action: deletePage
      userId: myUserId
      password: ${crypto.exportCredentials('Default', 'mycredentials', null).password}
      pageId: 32432235

Additional parameters to use are:

• pageId - integer, Required - id of page that you intend to delete.

The output of the action is stored in a result variable that has the following structure:

• ok - boolean value, true if the execution is successful;