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

### 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="/files/r5i6k85aNH85kVQrmZMI" 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="/files/yZ0QVA6crUfgk1L9PXn7" 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="/files/8wVzLhehq7VbFKCepYf7" 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="/files/RonDT78ylFJMtE9BK19d" 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="/files/Q7KyziyaqiwUpoTmg6DX" 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="/files/1TmAY9Uj98Gjq5J4a61M" 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="/files/me4brs97ae4uAuiFEL6A" 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="/files/Nb00dmTzaXt4563Ctux7" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aisera.com/aisera-platform/adding-data-to-your-tenant/integrations-and-data-sources/connectors/confluence-connector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.