Overview

Documentation

Purpose

This module allows you to connect your Mendix application with Confluence in order to view and manage content on Confluence.

Typical usage

Using the Confluence Connector, you can make certain pages that are managed in Confluence, available directly in your Mendix app. This means you can bring data that is in your Mendix system in direct contact with any pages or blogs that are managed outside of the app. It can be used to easily combine different sections of the business process with one another and to make all information readily available in one place.

Dependencies

The Confluence Connector is dependent on a number of modules that are all widely used and platform supported, being: 

• Deep link module
• Encryption 
• Community Commons 

How to use

The Confluence Connector comes with a number of different REST-calls to implement in your project. It is based on the documentation of the Confluence REST API, which can be found here. For each REST-call, two authentication methods are supported. These are explained below. In either case, make sure to read the ReadMe snippet in the Docs folder of the module and setup your application accordingly.

Authentication to Confluence

The Confluence Connector module supports two forms of authentication with Confluence: Basic Authentication and OAuth 2.0 (3LO) . Hereby, OAuth is the more secure, and therefore preferred, way of setting up the connection. In either case, a number of things will also need to be configured in Confluence, either in the user’s profile settings (BasicAuth) or in the Atlassian developer console (OAuth). All the steps needed to obtain the required information are explained during the configuration of the module in runtime. The choice of authentication method is also to be made during configuration.

Basic Authentication

If you choose BasicAuth, each user in the system must enter its own Confluence details (including a Personal Access Token). Each user will have the same permissions in the Mendix app as he/she has in Confluence, in order to view and edit items. The Personal Access Token will be stored encrypted in the database. This token can be created by a user in his own Confluence profile and is always created for the purpose and usage of one specific app, in this case our Mendix app.

OAuth

If you choose OAuth, the authentication will be setup using a specific Confluence account that manages external apps in Confluence as well. It is advised to use a team or company-wide account for this and not a personal user account. In the Mendix app, all users share the same access to Confluence items, which is based on the permissions (scopes) set for the integration. The setup of the OAuth connection can be done from the configuration snippet in runtime and only has to be done once for the entire Mendix app. It requires the following items:

• A new external app in Atlassian. Sign in to your Atlassian account that will manage the external Mendix application and go to your Atlassian developer console. Create a new app and select OAuth 2.0 Integration as the type. Make sure to give it a recognizable name. 
• A Redirect URI for the callback. The redirect URI must be equal to '[YourBaseURL]/link/oauth' in order for the Deep link to work properly. The base URL can be found by opening your app in the browser and inspecting the URL. When deployed to the Mendix cloud, it will look like 'https://[YourDomain].mendixcloud.com'. Make sure to also enter the exact same value for the Callback URL in the Atlassian developer console, on the Authorization tab.
• A Client ID and Client Secret. The client Id and client secret can be found in the Atlassian developer console, on the Settings tab. Note: both of these values will be stored encrypted in the Mendix database.
• The required scopes for the connection. Scopes are the permissions of your connection and determine which REST-calls are allowed to be executed. In the list of supported REST-calls below, you can find which scope is required for which REST-call. The required scopes for your connection can be selected during the OAuth configuration wizard. Note that all selected scopes in the Mendix app should also be selected in the Atlassian developer console on the Permissions tab. A list of all possible scopes can be found here, under the Confluence Cloud header.

Implementing REST-calls

The Confluence Connector module offers a number of REST-calls to Confluence out-of-the-box. A list of supported REST-calls can be found below. They can be used to retrieve and manipulate items from Confluence. The REST-calls can be found in the REST-calls folder of the UseMe folder of the module. When implementing these microflows, make sure to include them as sub-microflows in your own logic, rather than using them directly. Each microflow is aimed at a specific Confluence-endpoint and returns a specific piece (or list) of data. Also, it can take one or more of the following input parameters:

• ID: A unique ID that identifies a piece of Confluence Content, such as a page or a blog. It can be retrieved by executing a REST-call that returns a list of Content items.
• QueryParams: This contains all the URL parameters that you want to include in the REST-call. Depending on the endpoint that will be called, the list of possible query parameters varies. Make sure to properly check the Confluence documentation on the endpoint to make sure you have the correct query parameters. The format of the String should be: next=true&limit=25, so without a question mark at the start.
• SpaceKey: A unique key that identifies a Confluence space. It can be retrieved by executing a REST-call that returns a list of Confluence spaces.
• ContentType: Specifies the type of content you want to find. Possible values: page, blogpost.
• BodyString: Contains the body of the request that needs to be sent out. This depends on the type of request you want to execute. Make sure to properly check the Confluence documentation on the endpoint to make sure the BodyString is properly set up.
• ConversionType: Specifies the content type you want to convert a content body to. The possible values are linked to the values of the body query parameter and can be found in the documentation of the endpoint here.

Pagination

When retrieving a list of objects, the Confluence REST API returns a limited set of results and support pagination to make sure all possible results can be retrieved. This speeds up the execution of the REST-call and allows you to improve the performance of your app, as it can be detrimental to retrieve hundreds of objects into memory at once. The pagination mechanism of the Confluence API is not implemented by default in the Confluence Connector module, as the implementation can vary based on your own specific needs. Therefore, it is up to you to implement the pagination mechanism in the way that you need it.

Of course, we did provide an example to get you started. Have a look in the Examples folder to see how the pagination mechanism can be implemented. 

Supported REST-calls

Below you can find a list of all the supported REST-calls to Confluence. More information on how to implement the microflows that make these REST-calls, including the required input(s) and output, can be found in the microflow itself. Each REST-call has a required scope, which is necessary in order to be able to execute the REST-call. The required scope is twofold: on app level and on OAuth level. The app level scope is linked to the Basic Authentication method (see above) and tells you which permission the user needs in Confluence. The OAuth level is linked to the OAuth authentication method (see above) and tells you which scopes need to be selected for the API. 

• GET Spaces: Returns a list of all Confluence spaces. Required scope: App - READ; OAuth - read:confluence-space.summary. More information on this endpoint can be found here.
• GET Space (by SpaceKey): Returns the details of a single Confluence space, based on the provided SpaceKey. Required scope: App - READ; OAuth - read:confluence-space.summary. More information on this endpoint can be found here.
• GET Contents: Returns a list of all Content in the entire Confluence instance. Required scope: App - READ; OAuth - read:confluence-content.summary. More information on this endpoint can be found here.
• GET Contents (by SpaceKey): Returns a list of all Content in a Confluence space. Required scope: App - READ; OAuth - read:confluence-space.summary. More information on this endpoint can be found here.
• GET Contents (by SpaceKey and ContentType): Returns a list of all Content of a specific type (page or blog) in a Confluence space. Required scope: App - READ; OAuth - read:confluence-space.summary. More information on this endpoint can be found here.
• GET Content (by ID): Returns a single piece of Content, based on the provided ID. Required scope: App - READ; OAuth - read:confluence-content.summary. More information on this endpoint can be found here.
• POST Content: Creates a new piece of Content. Required scope: App - WRITE; OAuth - write:confluence-content. More information on this endpoint can be found here.
• PUT Content (by ID): Updates a piece of Content, based on the ID. Required scope: App - WRITE; OAuth - write:confluence-content. More information on this endpoint can be found here.
• DELETE Content (by ID): Moves a piece of Content to the trash of the Confluence space, based on the ID. Required scope: App - DELETE; OAuth - write:confluence-content. More information on this endpoint can be found here.
• GET Search contents: Searches for content using the Confluence Query Language (CQL). Required scope: App - READ; OAuth - search:confluence. More information on this endpoint can be found here.
• POST Body Convert: Converts a content body from one format into another format. Required scope: App - READ; OAuth - read:confluence-content.all. More information on this endpoint can be found here.

Viewing Confluence content

Viewing Confluence content in your Mendix app is not completely straightforward, as the body of the Content you want to view is not a simple string of text. Instead, Confluence can return the body in a number of different ways.

The recommended way of viewing the content body is to add the query parameter ‘expand=body.export_view’ to your request when retrieving a piece of content. Then, take the attribute Value of the entity ExportView and show this attribute in the Text Template widget. It cannot be shown in a standard Text widget, as the returned body from Confluence is HTML and not a simple string.

Feedback

If you have any feedback on the module, please reach out to the developers.