# 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**](https://docs.aisera.com/aisera-platform/adding-data-to-your-tenant/content-access-control/content-access-control-via-apis)

### Authentication

#### OAuth 2.0

Follow the steps at [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-) 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://<your_tenant>.aisera.<top_level_domain>/?id=aisera.oauth.oauthCommand`

Permissions:

* `read:confluence-space.summary`
* `read:confluence-content.all`
* `read:confluence-content.summary`
* `readonly:content.attachment:confluence`
* `search:confluence`
* `read:space:confluence`

You will also need to [acquire the **Cloud Id** for your site](https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/).

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

* Authorization URL - `https://auth.atlassian.com/authorize?
  audience=api.atlassian.com`
* Client Id
* Client Secret
* Access Token URL - `https://auth.atlassian.com/oauth/token`
* Cloud Id
* Scope
  * `offline_access`
  * `read:confluence-content.all`
  * `read:confluence-content.summary`
  * `readonly:content.attachment:confluence`
  * `search:confluence`
  * `read:space:confluence`

<div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FQTwuURg7hiQBSq61ykUt%2Fimage.png?alt=media&#x26;token=44d262db-935e-427b-90b7-56a3d8b33bd0" alt="" width="536"><figcaption></figcaption></figure></div>

#### Basic Authentication

Basic Authentication uses an account's **Username** and **Password** for authentication. It is common practice to create a dedicated service account for Aisera to access your Confluence with this method of authentication.

It is recommend that you generate an API token to act as *a replacement for the account password*. Go to [id.atlassian.com/manage-profile/security/api-tokens](https://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](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) page.

{% hint style="danger" %}
Be sure to keep your API token secure as it provides access to your company's Confluence data.
{% endhint %}

## 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**

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FIfutRRG0c1WHu4eUd1EG%2Fimage.png?alt=media&#x26;token=c223f1e8-ee34-44da-b8b4-e902455b076d" alt="" width="563"><figcaption></figcaption></figure></div>
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 will 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>` <br>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FcljtQSDXvF9ORjFHCZOE%2Fimage.png?alt=media&#x26;token=fad0af69-aa5c-4eee-a147-5b29d20dd3e2" alt="" width="431"><figcaption></figcaption></figure></div>
5. On the **Step 3: Authentication** screen, select the prepared **Authentication Type** from the dropdown.

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FCZXyJNSw8PpKO5aG1Bw9%2FConfluenceConnector-AuthDropdown.png?alt=media&#x26;token=8ceece49-79c6-449d-8fb3-9020ed180eb1" alt="" width="461"><figcaption></figcaption></figure></div>
6. Input the [prepared credentials](#authentication) and click **OK** to save the Integration.

## **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**

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FlRJgii0h3FttWwamrm8C%2FConfluenceConnector-DataSourceConfluence.png?alt=media&#x26;token=7234e6b5-e518-4744-aeed-26fc8308b72e" alt="" width="563"><figcaption></figcaption></figure></div>
4. Under the **Functions** dropdown, select **Knowledge Base Learning**
5. Fill in the General information and select **Next**<br>

   <table><thead><tr><th width="157">Field</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>The name you will give to the data source</td></tr><tr><td>Integration</td><td>The integration with necessary information for data retrieval.</td></tr><tr><td>Schedule</td><td>How frequently the data source will request new information</td></tr><tr><td>Data Retrieval</td><td><p>How you would like the data to be retrieved.</p><p><br><strong>Incremental</strong> - Will retrieve only the articles which have been created or updated since the last data ingestion</p><p><br><strong>Date Range</strong>  - 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.</p></td></tr><tr><td>Language</td><td>The preferred language</td></tr><tr><td>Public Domain</td><td>If a data source is public, related Knowledge Base Articles will show as hints for question to the bot.</td></tr><tr><td>Description</td><td>A short description of the data source</td></tr></tbody></table>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2F3g4xw8Fhpdcw6zSZCDtK%2FConfluenceConnector-DataSourceGeneral.png?alt=media&#x26;token=d5df8603-ec64-466b-a5a7-eeb21ae7e84c" alt="" width="423"><figcaption></figcaption></figure></div>
6. On the **Step 3 of 6: Configuration** page, click on S**paces** 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.&#x20;

{% hint style="danger" %}
If a list under **Spaces** does not automatically appear, it means that the **Integration** step has failed or has not been configured properly.&#x20;

* Check that your integration has been properly set up, and that the credentials are correct.&#x20;
* Because each user environment is different, you may need to increase the permissions for the Aisera Platform to properly detect the spaces.
* If trouble persists, contact your Aisera representative for further help.
  {% endhint %}

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

8. &#x20;The remaining fields are [optional configurations](#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:<br>

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

{% hint style="warning" %}
If you have used OAuth 2.0 to set up your integration, you will need to [Correct KB article URL Links](#correcting-kb-article-url-links).
{% endhint %}

## 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](https://developer.atlassian.com/server/confluence/advanced-searching-using-cql/) 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

   <figure><img src="https://docs.aisera.com/~gitbook/image?url=https%3A%2F%2F2983236984-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FiZkLJr3EjXkd2tHYiQJP%252Fuploads%252FUkVqbs3VeBPSu8pr4X0T%252F2.png%3Falt%3Dmedia&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=a901e1ac&#x26;sv=2" alt=""><figcaption></figcaption></figure>
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.&#x20;

To correct the reference to Confluence articles:

1. Navigate to **Settings >** **Data Sources** in the Aisera Admin UI and click on your data source.
2. On the **Data Source Details** window, choose the **pencil icon** to open the **Edit** window.
3. Under **Configurations** insert the following script into the **Custom Script** field.<br>

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Remember to edit the <code>baseURL</code> value in this script to match the base URL for your Confluence Instance.</p></div>

   ```javascript
   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;
   }
   ```
4. Click **OK**.
5. On the **Data Source Details** screen click the **New Field Mapping** butto&#x6E;**.**

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FknpWgafM9sgdsb1XaB92%2FConfluenceConnector-DataSourceDetials.png?alt=media&#x26;token=8bf933d9-2cb1-474b-8bf3-5c836e36d46e" alt=""><figcaption></figcaption></figure></div>
6. Select **URL** as the **Field** value.
7. Type **customURL** as the **Confluence Field** valu&#x65;**.**

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FwuipN006xyFdpZ7o6pkW%2Fnew_field_map.png?alt=media&#x26;token=1423b996-d2c6-428d-9f86-4c6bc897f4ca" alt=""><figcaption></figcaption></figure></div>