Add or edit a Confluence Cloud source

Confluence is a cloud-based knowledge sharing tool that enables users to create and share content. Members of a Coveo organization with the required privileges can add the source to index the content of their Confluence Cloud instance.

Note

For clients migrating from Coveo Enterprise Search 7.0 (CES 7), the Confluence Cloud source has the same specifications as the Confluence V2 connector.

Tip
Leading practice

The number of items that a source processes per hour (crawling speed) depends on various factors, such as network bandwidth and source configuration. See About Crawling Speed for information on what can impact crawling speed, as well as possible solutions.

Source key characteristics

Features Supported Additional information

Confluence Cloud version

Latest cloud version

Searchable content types

check

Spaces, pages (such as Wiki pages), blog posts, comments on pages and blog posts (included as metadata), and attachments (in pages, blog posts, and comments).

Content update operations

refresh

check

A refresh won’t take account of deleted, restored, and moved items, and items with modified comments or permissions. Therefore, a rescan or a rebuild is recommended.

rescan

check

Takes place every day by default. If you change the name of a space in Confluence Cloud, the rescan detects the change only for pages created or modified following the change. You must therefore rebuild the source to get the space name changed on all space pages.

rebuild

check

Content security options

Same users and groups as in your content system

check

Requires installing the Coveo User Sync app in your instance. See About the Coveo User Sync App for details.

Specific users and groups

check

Everyone

check

Note

Q&A in Confluence is an external plugin that must be installed on the instance, and isn’t indexed by the Confluence connector. In order to index Q&A, you must use a Generic REST cloud source.

Add or edit a Confluence Cloud source

When adding a source, select the Confluence Cloud option.

To edit a source, on the Sources (platform-ca | platform-eu | platform-au) page, click the desired source, and then click Edit in the Action bar.

A Confluence Cloud source indexes cloud content. If you want to retrieve on-premises (server) content, see Add or Edit a Confluence Server Source instead.

"Configuration" tab

In the Add/Edit a Confluence Cloud Source panel, the Configuration tab is selected by default. It contains your source’s general and authentication information, as well as other parameters.

General information

Source name

Enter a name for your source.

Tip
Leading practice

A source name can’t be modified once it’s saved, therefore be sure to use a short and descriptive name, using letters, numbers, hyphens (-), and underscores (_). Avoid spaces and other special characters.

Instance URL

Enter the address of the Confluence Wiki site or space that you want to make searchable. Ensure to include the protocol (http:// or https://).

Optical character recognition (OCR)

If you want Coveo to extract text from image files or PDF files containing images, check the appropriate box. OCR-extracted text is processed as item data, meaning that it’s fully searchable and will appear in the item Quick View. See Enable Optical Character Recognition for details on this feature.

Note

Contact Coveo Sales to add this feature to your organization license.

"Authentication" section

Atlassian account

Enter an email address corresponding to a dedicated Atlassian account that has access to all the content that you want to index. See Source Credentials Leading Practices.

API token

Enter an API token created with the specified Atlassian account.

"Content to Include" section

Consider changing the default value of the parameters in this section to fine-tune how your Confluence Cloud site is crawled.

Space type

Select which spaces you want to index. By default, global space content is indexed and personal space content isn’t.

Space status

Select which spaces should be indexed, depending on their status. Options are:

  • Current (non-archived spaces)

  • Archived

Space Filter

If you want to index only a subset of a Confluence site, enter a regex that the desired spaces match. This parameter is especially useful when you want to index spaces that have an element in common in their space keys.

Example

You want to index all spaces with keys starting with an uppercase letter followed by a number, so you enter the following regex:

^[A-Z][0-9].*$

Options

Select the items to index:

  • Attachments (binary files attached to a page, blog post, or comment)

  • Comments (on blog posts and pages)

Note

Comments are indexed as page metadata rather than as items.

"Content Security" tab

Select who will be able to access the source items through a Coveo-powered search interface. For details on this parameter, see Content Security.

Note

The Same users and groups as in your content system option requires you to install the Coveo User Sync app in your instance. Install the version of the app that corresponds to the region of your Coveo organization, or install the HIPAA version for Coveo HIPAA environments. See About the Coveo User Sync App for details.

"Access" tab

In the Access tab, set whether each group and API key can view or edit the source configuration (see Resource Access):

  1. If available, in the left pane, click Groups or API Keys to select the appropriate list.

  2. In the Access Level column for groups or API keys with access to source content, select View or Edit.

Completion

  1. Finish adding or editing your source:

    • When you want to save your source configuration changes without starting a build/rebuild, such as when you know you want to do other changes soon, click Add Source/Save.

      Note

      On the Sources (platform-ca | platform-eu | platform-au) page, you must click Launch build or Start required rebuild in the source Status column to add the source content or to make your changes effective, respectively.

    • When you’re done editing the source and want to make changes effective, click Add and Build Source/Save and Rebuild Source.

      Back on the Sources (platform-ca | platform-eu | platform-au) page, you can review the progress of your source addition or modification.

      Once the source is built or rebuilt, you can review its content in the Content Browser.

  2. Optionally, consider editing or adding mappings once your source is done building or rebuilding.

  3. To ensure that new items are indexed with the next refresh operation, edit the JSON configuration of your source so that the source uses the same time zone as your Confluence Cloud instance:

    1. On the Sources (platform-ca | platform-eu | platform-au) page, click your source, and then click More > Edit JSON in the Action bar.

    2. In the parameters object, add the following object:

      "LocalServerTimeOffsetForIncrementalRefresh": {
        "sensitive": false,
        "value": "<TIME_ZONE_OFFSET>"
      }
    3. Replace <TIME_ZONE_OFFSET> with the time offset from UTC required to match the time zone of your Confluence Cloud instance. For example, if your Confluence instance uses UTC-04:00 time, enter -04:00.

Source update best practice

You can get the CONFLUENCE_UNREACHABLE_SERVER error message when your Confluence Cloud source rebuilds or is scheduled to perform a rescan during the daily Atlassian Cloud maintenance window (1 AM to 3 AM, in your server’s time zone). During this period, Atlassian may block access to the API while performing maintenance tasks.

If possible, schedule your source’s rescans so that they’re completed outside of the daily maintenance window. If not possible, ignore the errors. The next scheduled rescan outside the maintenance window shall complete normally.

Indexing page properties

By default, Coveo doesn’t index pages or blog post properties (metadata.properties). To do so, you must edit your source’s JSON configuration to specify the desired page properties.

In the Configuration tab of the Edit a Source JSON Configuration panel, add "MetadataPropertiesToExpand": "<VALUES>", where <VALUES> are the properties you want to index, separated by commas.

Example: "MetadataPropertiesToExpand": "owner,status"

To refer to a property nested within another, concatenate their names with a dot (.) separator.

Example: "MetadataPropertiesToExpand": "owner.lastname,status"

About the Coveo User Sync App

Installing Coveo’s User Sync app in your Atlassian instance is required to replicate your instance’s content access permissions in your search interface. This lets users see in their Coveo search results the content that their role allows them to see in your Atlassian instance.

To replicate your instance’s permission system, Coveo must associate user email addresses with user roles. Atlassian’s API doesn’t provide this information, but provides the roles assigned to each user account ID. So, Coveo built the User Sync app to retrieve the email address corresponding to each user account ID. It can then combine this information with the roles and account IDs provided by Atlassian’s API.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo Management of Security Identities and Item Permissions.

Note

Coveo doesn’t support the global permission allowing Jira Service Management (JSM) users to use Confluence (Settings > Global permissions > JSM access). As a result, JSM users who have access to your Confluence content through this global permission can’t access this content in their Coveo search results.

What’s next?