Muokkaa

Jaa

Confluence Cloud Microsoft Graph Connector

  • Artikkeli

The Confluence Cloud Microsoft Graph connector allows your organization to index Confluence content. After you configure the connector and index data from the Confluence site, end users can search for those contents in Microsoft Search and Microsoft 365 Copilot.

This article is intended for Microsoft 365 administrators and who are responsible for configuring, running, and monitoring the Confluence Cloud Microsoft Graph connector. It supplements the general instructions provided in setup Microsoft Graph connectors in the Microsoft 365 admin center.

Benefits

  • Enhanced Search Capabilities: Users can ask natural language questions about Wiki content in Copilot, such as:
    • Summarize the architecture document
    • How to get access to a portal
  • Semantic Search Support: Users can perform natural language queries for accurate responses.

Prerequisites

  1. You must be the admin for your organization's Microsoft 365 tenant and the admin for your organization's Confluence site.
  2. Authentication: Ensure that you have authentication credentials with right access.

Limitations

  • Doesn't index attachment files, or comments.

Important

  • Atlassian is deprecating a set of Confluence cloud APIs (V1 version) and releasing new APIs (V2 version). You may read about their announcements here or here. Some of these deprecating v1 APIs are used by the connector for OAuth connections only. Hence, post this change your existing Confluence connection(s) may stop working. This change is scheduled for Jan’24.
  • The change to migrate to new v2 APIs was released to all customers in December 2023. Post this release, your existing connections need to be reauthenticated. The new v2 APIs also require some more scopes (as compared to previous v1 APIs) which need to be provided during re-authentication. A new set of scopes required (complete list) – read:group:confluence, read:user:confluence, read:content-details:confluence, Read:space:confluence, Read:permission:confluence, read:audit-log:confluence, read:content.metadata:confluence and read:page:confluence.

Get Started

1. Display name

A Display name is used to identify each reference in Copilot, helping users easily recognize the associated file or item. Display name also signifies trusted content. Display name is also used as a content source filter. A default value is present for this field, but you can customize it to a name that users in your organization recognize.

2. Confluence Cloud URL

To connect to your Confluence site, use your site URL. A Confluence cloud site URL typically looks like https://<organization_name>.atlassian.net/.

3. Authentication type

To authenticate and synchronize content from Confluence On-prem, choose one of two supported methods:

Tip

Make sure the service account has view access to the Confluence content you want to index.

a. Basic authentication
Enter your account's username (usually email ID) and API token to authenticate using basic auth. To learn more about generating an API token, refer to Atlassian's documentation on how to manage API tokens for your Atlassian account.

b. OAuth 2.0 (recommended)
Register an app in Confluence Cloud so that the Microsoft Search app and Microsoft 365 Copilot can access the instance. To learn more, see Atlassian Support documentation on how to Enable OAuth 2.0.

The following steps provide guidance on how to register the app:

  1. Sign in to Atlassian Developer console with your Atlassian Confluence admin account.
  2. Click on Create and select OAuth 2.0 integration.
  3. Provide an appropriate name for the application and create the new app.
  4. Navigate to Permissions from the navigation pane on the left. Click Add for Confluence API. Once added, click on Configure, and Edit scopes and select the following scopes.
Scope name Code Description
View content details read:content-details:confluence Crawl content satisfying criteria.
View groups read:group:confluence To access group permissions of content.
View user details read:user:confluence To access individual user details to support permissions.
  1. Click Save.
  2. Navigate to Authorization from the navigation pane on the left. Add the callback URL, for Microsoft 365 Enterprise: https://gcs.office.com/v1.0/admin/oauth/callback, for Microsoft 365 Government: https://gcsgcc.office.com/v1.0/admin/oauth/callback and save the changes.
  3. Navigate to Settings from the navigation pane on the left. You get the Client ID and Secret from this page.

Complete the connection settings step using the Client ID and Secret.

6. Rollout to limited audience

Deploy this connection to a limited user base if you want to validate it in Copilot and other Search surfaces before expanding the rollout to a broader audience. To know more about limited rollout, click here.

At this point, you are ready to create the connection for ServiceNow Knowledge. You can click on the "Create" button and the Microsoft Graph connector starts indexing page from your Confluence account.

For other settings, like Access Permissions, Data inclusion rules, Schema, Crawl frequency etc., We set defaults based on what works best with Confluence data. The default values are as follows:

Users  
Access permissions Only people with access to content in Data source.
Map Identities Data source identities mapped using Microsoft Entra IDs.
Content  
Include/Exclude space All
Manage Properties To check default properties and their schema, click here
Sync  
Incremental Crawl Frequency: Every 15 mins
Full Crawl Frequency: Every Day

If you want to edit any of these values, you need to choose the Custom Setup option.

Custom Setup

Custom setup is for those admins who want to edit the default values for settings listed in the default table. Once you click on the Custom Setup option, you see three more tabs – Users, Content, and Sync.

Users

Access Permissions

Confluence Cloud Microsoft Graph connector supports search permissions visible to Everyone or Only people with access to this data source. If you choose Everyone, indexed data appears in the search results for all users. If you choose Only people with access to this data source, indexed data appears in the search results for users who have access to them. In Confluence Cloud, security permissions for users and groups are defined using space permissions and page restrictions. Page-level restrictions, if present, take precedence over space permissions.

If there are no page restrictions, the connector checks for space-level permissions -

  • In case the space has 'anonymous users' access enabled, the content is visible to all users within your tenant.
  • In case 'anonymous access' isn't enabled, the space-level permissions are not honored.
  • In case space level permissions are not defined, the content is not visible to any user in your tenant.

Important

Permissions are managed at the space and page level only, and parent page permissions are not taken into consideration.

If you choose Only people with access to this data source, you need to further choose whether your Confluence site has Microsoft Entra ID provisioned users or non-AAD users.

To identify which option is suitable for your organization:

  1. Choose the Microsoft Entra ID option if the email ID of Confluence users is same as the UserPrincipalName (UPN) of users in Microsoft Entra ID.
  2. Choose the non-AAD option if the email ID of Confluence users is different from the UserPrincipalName (UPN) of users in Microsoft Entra ID.

Note

  • If you choose Microsoft Entra ID as the type of identity source, the connector maps the email IDs of users obtained from Confluence directly to UPN property from Microsoft Entra ID.
  • If you chose "Non-AAD" for the identity type see Map your non-Azure AD Identities for instructions on mapping the identities. You can use this option to provide the mapping regular expression from email ID to UPN.
  • Updates to users or groups governing access permissions are synced in full crawls only. Incremental crawls do not currently support the processing of updates to permissions.

Content

Include or exclude data which you want to index

With a Confluence Query Language (CQL) string, you can specify conditions for syncing pages. It's like a Where clause in a SQL Select statement. For example, you can choose to index only the pages that have been modified in the last two years. To learn about creating your own query string, see Advanced Searching using CQL. All blogs and pages are indexed by the connector by default.

Tip

You may use the CQL filter to index content modified after a certain time using, lastModified >= "2018/12/31"

Use the preview results button to verify the sample values of the selected properties and CQL string.

Manage Properties

In this step, you can add or remove available properties from your Confluence data source. Microsoft 365 has selected a few properties by default. The list of properties that you select here, can impact how you can filter, search and view your results in Microsoft 365 Copilot.

Source property Label Description
Authors authors Name of people who participated/collaborated on the item in the data source.
CreatedByName createdBy Name of the person who most recently edited the item in the data source.
CreatedOn createdDateTime Date and time that the item was created in the data source.
IconUrl iconUrl The associated icon URL of the item.
Title title The title of the item that you want to be shown in search and other experiences.
UpdatedByName lastModifiedBy Name of the person who most recently edited the item in the data source.
UpdatedOn lastModifiedDateTime Date and time the item was last modified in the data source.
Url url The target URL of the item in the data source.

Preview Data

Use the preview results button to verify selected properties and filters.

Sync

The refresh interval determines how often your data is synchronized between the data source and the Graph connector index. There are two types of refresh intervals – full crawl and incremental crawl. For more details, click here. You can change the default values of refresh interval from here if you want to.

Review and Test your connection

For MS Search, if you need to customize the search results page. To learn about customizing search results, see Customize the search results page.

If you have issues or want to provide feedback, contact Microsoft Graph | Support.