Confluence On-premises Microsoft Graph Connector
The Confluence On-premises Microsoft Graph connector allows your organization to index Confluence server or data center 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 On-premises 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
- Summarize the architecture document
- Semantic Search Support: Users can perform natural language queries for accurate responses.
- Compatibility: Supports Confluence versions above 8.0.
Prerequisites
- Install the GCA [Graph connector agent]: Ensure that the GCA is installed on a Windows machine within the same network as the data source, accessible via the Confluence URL. You can find more information Microsoft Graph connector agent
- Install plugin: Download and install the confluence on-prem plugin from Atlassian marketplace on your confluence setup. Get the plugin from Microsoft Graph Connectors Confluence On-prem Plugin | Atlassian Marketplace
- Authentication: Ensure that you have authentication credentials with right access.
Important
Recommended : The Confluence Global Administrator should create the connection
Who is the confluence global administrator?
A Confluence Administrator is a user who has been granted full administrative permissions.
- To check this: Go to Administration > General Configuration > Global Permissions
- Look for the group Confluence-administrators, which has all permissions enabled, including - Can Use, Personal Space, Create Space(s), Confluence Administrator, and System Administrator.
- Any user creating a token must be a member of this group
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 on-premises URL
To connect to your Confluence On-premises data, you need your organization's Confluence instance URL. Your organization's Confluence instance URL typically looks like 'https://contoso.atlassian.net'.
3. Graph connector agent (GCA)
To index your Confluence server or data center content, you must install and register the connector agent. See Install the Microsoft Graph connector agent for details. You must be the administrator for your organization's Microsoft 365 tenant and the administrator for your organization's Confluence site.
Note
GCA can be installed on a different Windows machine and need not be on the same machine as that of the On-premises server. The machine can help generate App ID and secret which can be used for the setup. You must ensure that the GCA machine is on during the crawling. You may find answers to common GCA realted questions in FAQ section .
4. Install the Confluence on-premises plugin
Verify that the Microsoft Graph Connectors Confluence On-prem Plugin is installed. You do not need to install the plugin for each confluence connector; if it's already installed in your Confluence instance, you can skip this step for subsequent Confluence on-prem connections.
- Download the app from Microsoft Graph Connectors Confluence On-prem Plugin | Atlassian Marketplace.
- Log in to your confluence system
- Click on settings icon -> Click on manage apps
- Click on upload app
- Choose the downloaded file and proceed
Note
Plugin is supported for confluence version above 8.0.
5. Authentication type
To authenticate and synchronize content from Confluence On-prem, choose one of three supported methods:
a. Basic authentication
To authenticate to your instance, enter the username and password of Confluence account.
b. OAuth1.0a
Generate a public/private key pair and create an application link in the Confluence On-premises site so that the connector agent can access the instance. To learn more, see step 1 in Atlassian developer documentation on how to configure OAuth 1.0a.
c. OAuth 2.0 (recommended)
The following steps provide guidance on how to register the app Configure an incoming link.
- Go to Administration > General configuration > Application links.
- Select Create link
- Select External application, and then choose Incoming as the direction.
- Fill in the
- Redirect URL:
https://gcs.office.com/v1.0/admin/oauth/callback - Scope:
a) If you are a Confluence Global Administrator, either of the following scopes is supported: Admin or Read.
b) If you are any other type of Confluence Administrator, provide the Admin scope
- 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 |
| Synchronization | |
|---|---|
| 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
The Confluence On-premises 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 On-premises, security permissions for users and groups are defined using space permissions and page restrictions. The Confluence On-premises Microsoft Graph connector applies effective permissions provided by Content restrictions API
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:
- 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.
- Choose the non-AAD option if the email ID of Confluence users is different from the UserPrincipalName (UPN) of users in Microsoft Entra ID.
Important
- 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
In this step, you can add or remove available properties from your Confluence data source. Microsoft 365 selects a few properties. By default, the connector will index all spaces. However, you can choose to include or exclude specific spaces using the space filter option.
Enter the list of space keys you wish to include or exclude, and you see a preview of the results. Enter Space key: Each Confluence space has a space key, which is a short, unique identifier that forms part of the URL for that space. To get the space key, contact confluence admin. For more information visit: Space Keys
Page filter
In this step, you can specify the date range for indexing your documents. The parameters are as follows:
- Last Created Date: The date when a document was created. Only documents modified after this date are indexed.
- Last Modified Date: The date when a document was modified. Only documents modified after this date are indexed.
Important
- Ensure that the dates are in chronological order. The "Last Created Date" should not be later than the "Last Modified Date."
- If no dates are specified, all documents will be considered for indexing.
Manage Properties
Here, you can add or remove available properties from your Confluence On-prem data source. Assign a schema to the property (define whether a property is searchable, queryable, retrievable or refinable). Additionally you can change the semantic label and add an alias to the property. Default properties are as follows:
| Source Property | Label | Schema |
|---|---|---|
| Author | authors | Query, Retrieve |
| Content | Search | |
| CreatedByName | Created by | Search, Query, Retrieve |
| CreatedOn | Created date time | Query, Retrieve |
| Id | Query, Retrieve | |
| PageTree | Retrieve | |
| SpaceName | Search, Query, Retrieve | |
| Title | title | Search, Retrieve |
| UpdatedByName | lastModifiedBy | Retrieve |
| UpdatedOn | lastModifiedDateTime | Query, Retrieve, Refine |
| URL | url | Retrieve |
Preview Data
Use the preview results button to verify selected properties and filters.
Note
Note that the preview only respects space-level filtering.
Synchronization
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 testing, you can choose publish to limited audience.
- Search and validate your indexed content and permissions using Index browser.
- Find answers to common questions in our FAQ section.
For MS Search, if you need to customize the search results page. To learn about customizing search results, see Customize the search results page.
Limitations
- Doesn't index blogs, attachment files, or comments.
- Only indexes current pages; archived pages are excluded.
- CQL[Confluence Query Language] isn't supported for Confluence on-premises howevere we support a space and page level filter
Troubleshooting
After publishing your connection, you can review the status under the Data sources tab in the admin center. To learn how to make updates and deletions, see Manage your connector. You can find troubleshooting steps for commonly seen issues here.
If you have issues or want to provide feedback, contact Microsoft Graph | Support.