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 complete the following steps you will need to gather proper permissions and credentials. 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://<Tenant Id>/?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 Configuration

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

1. 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>

1. 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.

Setting up 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

1. Under the Functions dropdown, select Knowledge Base Learning

2. Fill in the General information and select Next

• Name - The name of the Data Source

• Integration - Select the Integration created from the dropdown

• Schedule - When you would like data to be ingested into the Aisera Platform

• Data Retrieval

  • 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 - Select the preferred language

• Public Domain - Enter the public domain.

  • If a data source is public, related Knowledge Base Articles will show as hints for questions to the Bot.

• Description

1. 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. Fill in the remaining configuration options and select Next

• Custom Script - A JS transformation script

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 article itself. To remedy this, use the following custom script in the Custom Script field:

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

• 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.

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

Correcting KB article URL set up

In the case you have used OAuth 2.0 for your integration, the articles will be retrieved by referencing the API rather than the article link itself. To correct for this you must first have entered the provided custom script in the Custom Script field. You must then create a Custom Field Mapping to finish the process of correcting the link to the articles. To complete this process:

1. On the Data Sources screen, locate and click on your data source

2. Click on New Field Mapping

1. Select URL as the field, and input customURL for the Confluence Field