Confluence Connector

Overview

The purpose of the Confluence connector is to retrieve pages from Confluence as Knowledge Base Articles.

Prepare

Before proceeding with the Confluence integration setup, ensure you gather the necessary credentials and set the required permissions. There are two supported authorization types: OAuth 2.0 and Basic. See also: Content Access Control via 3rd Party APIs

OAuth 2.0

OAuth 2.0 is a protocol which enables you to grant third-party applications access to your company's Confluence. Follow the steps at OAuth 2.0 (3LO) apps to create an OAuth 2.0 application on your company's Confluence. Use the following options as you create the app in Confluence.

Callback URL: https://<VANITY_URL>/?id=aisera.oauth.oauthCommand

Permissions:

• read:confluence-space.summary

• read:confluence-content.all

• read:confluence-content.summary

• readonly:content.attachment:confluence

• search:confluence

You will also need to acquire the Cloud Id for your site. The steps to do this can be found at the previous link.

After creating the OAuth 2.0 app, you will have the following necessary credentials:

• Authorization URL

• Client Id

• Client Secret

• Cloud Id

Basic Authentication

Basic Authentication uses an account's username and API key for authentication. You will need a username and password for this form of authentication. It is common practice to create a dedicated service account for this authentication type.

Using the desired account, you can also generate an API token which will act as a replacement for the account password. Go to id.atlassian.com/manage-profile/security/api-tokens to create an API token. To learn more about these tokens, go to the Manage API tokens for your Atlassian account page.

Integration Setup

To create the Confluence integration:

1. In the Aisera Admin UI navigate to Settings > Integrations

2. Click on + New Integration

3. In the menu, select Confluence and click Next

   
4. Give the integration a Name and provide the base wiki URL for the Endpoint. Then click Next. If you are using Basic Authentication you will use the link to your company's Confluence Site as the endpoint. This ill look like https://<YOUR_DOMAIN>.atlassian.net/wiki If you are using OAuth 2.0 you will use the Atlassian API URL as the endpoint. This is constructed using your Cloud Id. This will look like https://api.atlassian.com/ex/confluence/<CLOUD_ID>

   
5. On the Step 3: Authentication screen, select the prepared Authentication Type from the dropdown.

   

OAuth2

If the prepared form of authentication is OAuth 2.0 fill in the Authorization URL, Client Id, and Client Secret fields with the credentials provided by confluence. Use https://auth.atlassian.com/oauth/token for the Access Token URL. Click OK to complete the integration step.

Basic Authentication

If the prepared form of authentication is Basic Authentication, fill in the Username with the username of the account being used to access confluence. Then fill in the Password field with either the account password or the generated API key. Click OK to complete the integration step.

Data Source Setup

To create a Confluence Data Source:

1. In the Aisera Admin UI navigate to Settings > Data Source

2. Click + New Data Source

3. In the menu, select Confluence and click Next

   
4. Under the Functions dropdown, select Knowledge Base Learning

5. Fill in the General information and select Next

   Field

   Description

   Name

   The name you will give to the data source

   Integration

   The integration with necessary information for data retrieval.

   Schedule

   How frequently the data source will request new information

   Data Retrieval

   How you would like the data to be retrieved.

   Incremental - Will retrieve only the articles which have been created or updated since the last data ingestion

   Date Range - Will pull data from Confluence from a specified Date Range. If the end date is left blank it will pull all articles after the specified start date.

   Language

   The preferred language

   Public Domain

   If a data source is public, related Knowledge Base Articles will show as hints for question to the bot.

   Description

   A short description of the data source

   

6. On the Step 3 of 6: Configuration page, click on Spaces and choose the space with the data you want to ingest from the list that appears. You may add multiple spaces by clicking the + Add Project button.

1. You may also further refine your data source by selecting directories

2. The remaining fields are optional configurations. Fill in any remaining configuration as desired and select Next If you have set up your integration with OAuth 2.0, the request URL will reflect an API request rather than a link to the Confluence article itself. To remedy this, use the following custom script in the Custom Script field:

   Copy

   function transform (jsonObject) {
      var baseURL = "https://<YOUR_ADDRESS>.atlassian.net/wiki";
      var links = jsonObject._links;
      if (links) {
         var webui = links.webui;
         if (webui) {
            jsonObject.customUrl = baseURL + webui; 
         }
      }
      return jsonObject;
   }

3. Select Next until the New Data Source window closes to complete the creation of the Data Source.

Optional Configurations

Custom Script

This option allows you to transform the data as it is being ingested into the Aisera Platform. This includes, adding, editing, or removing fields from the ingested content.

Additional CQL Query

Conditions added to the Confluence Query Language query being made to ingest the data.

Additional Fields to Expand

A comma separated list of fields that will be placed in the expand http query.

Custom Pagination Limit

Selects the size of the page. If left blank, the field will default to 50.

Additional Query Params

Additional query parameters that will be sent in the request. This will be added to the request in the form of a JSON object, containing key value pairs.

Post-Connection Actions

Support for Confluence Offset-Based Connector

The external Confluence data source uses cursor-based pagination, and therefore our Aisera connector for Confluence also uses cursor-based pagination by default. But some of our customers use the previously supported offset-based pagination that has since been deprecated by Confluence.

If you’re using an older version of Confluence as your Data Source, you can now enable an offset-based pagination version of the Aisera Confluence connector.

To Enable Offset-Based Pagination:

1. In the Aisera Admin UI, navigate to Settings > Data Source

2. Select the desired Data Source

3. Choose the pencil icon to edit the Data Source

4. Check the Enable offset-based pagination box in the Configuration tab of the Data Source details

   
5. Run the Data Source.

6. Ask your Aisera Team to tail the conn-ds pod log and verify that the connector requests are paginated using start and limit.

Correcting KB article URL Links

In the case you have used OAuth 2.0 for your integration, the articles will be retrieved by the article reference in the Confluence API rather than an article URL. To correct for this, you need to request a custom script from your Aisera team and paste it into the Custom Script field. You must then create a Custom Field Map to finish the process of correcting the link to the articles.

To correct the reference to Confluence articles:

1. Request a custom script from your Aisera team.

2. Navigate to Settings > Data Sources in the Aisera Admin UI and click on your data source.

3. On the Data Source Details window, choose the pencil icon to open the Edit window.

4. Paste the new script into the Custom Script field, on the Configuration tab.

   
5. Click OK.

6. Now back on the Data Source Details screen click the New Field Mapping button.

   
7. Select URL as the Field value.

8. Type customURL as the Confluence Field value.