How to integrate with Confluence APIs

2022-06-21, by Dariusz Suchojad

In a previous article, I talked about Jira, and if you are a Jira user, chances are that you also use Confluence as they often go hand in hand, Jira as a ticketing application and Confluence as an enterprise knowledge management system.

From the perspective of integrations, connecting to Confluence and invoking its APIs looks and feels practically the same as with Jira:

You need an API token
You fill out a form in Zato Dashboard
You create a Python service that offers methods such as get_page_by_title, attach_file, update_page_property and similar.

Let's go through it all step-by-step, starting off with the creation of an API token.

Creating an Atlassian API token

To invoke Confluence, you use an API token that can be shared with other Atlassian products, such as Jira. If you do not have one already, here is how to create it:

Log in to Confluence or Jira
Visit the address where API tokens can be managed: https://id.atlassian.com/manage-profile/security/api-tokens
Click "Create API Token" and provide a name for the token, such as "Zato Integrations"
Copy the token somewhere as, once it has been created, you will not be able to retrieve it later on. The only way to change a token is to revoke it and create a new one.

Creating a Confluence connection

In your Zato Dashboard, go to Cloud -> Atlassian -> Confluence:

Click "Create a new connection" and fill out the form below. The username is the same as the email address that you log in to Confluence or Jira with.

Now, click "Change API Token" and enter the token created in the previous section:

Invoking Confluence

Authoring a Zato service that invokes Confluence follows a pattern that will feel familiar no matter what kind of an API you integrate with:

Obtain a connection to remote resource
Invoke it
Process the response the resource returned

In the case of the code below, we are merely logging the response from Confluence. In a bigger integration, we would process it accordingly, e.g. parts of the output could be synchronized with Jira or another system.

Note the 'client.get_all_pages_from_space' method below - the client will offer other methods as well, e.g. get_space, get_page_as_pdf or ways to run CQL (Confluence Query Language) directly. Use auto-completion in your IDE to discover all the methods available.

# -*- coding: utf-8 -*-

# Zato
from zato.common.typing_ import cast_
from zato.server.service import Service

# ###########################################################################

if 0:
    from zato.server.connection.confluence_ import ConfluenceClient

# ###########################################################################

class GetAllPages(Service):

    def handle(self):

        # Name of the Confluence space that our pages are in
        space = 'ABC'

        # Name of the connection definition to use
        conn_name = 'My Confluence Connection'

        # .. create a reference to our connection definition ..
        confluence = self.cloud.confluence[conn_name]

        # .. obtain a client to Confluence ..
        with confluence.conn.client() as client: # type: ConfluenceClient

            # Cast to enable code completion
            client = cast_('ConfluenceClient', client)

            # Get all pages from our space
            pages = client.get_all_pages_from_space(space)

            self.logger.info('Pages received -> %s', pages)

# ###########################################################################

That is all - you have create an Atlassian API token, a Zato Confluence connection and you have integrated with Confluence in Python!