Skip to main content

​
About Confluence Data Center

The Confluence Data Center integration connects Serval to a Confluence instance you host yourself. It’s a separate integration from Confluence (Cloud): it talks directly to your own host and authenticates with a personal access token you provide instead of OAuth. Once connected, Serval mirrors your spaces and pages into its Knowledge Base, and workflows and Catalyst can call your instance’s API on demand. The integration is marked Beta in the connect UI. If your Confluence lives at yourcompany.atlassian.net, use the Confluence (Cloud) integration instead. Authentication: Personal access token. You supply your instance’s Base URL and a token; Serval stores the token securely server-side and attaches it to every request on your behalf, so workflows never see the raw token. Basic auth (username plus password) isn’t supported. Data sync: Confluence Data Center is a native knowledge source. Serval mirrors spaces and pages into the Knowledge Base in the background, including who-can-see-what permissions, so agents only answer from pages the requester is allowed to see. Workflow API requests run on demand.

​
What the Confluence Data Center integration enables

​
What syncs

  • Spaces the token’s user can view, and the pages in them, nested under their parent pages.
  • Space permissions: the users and groups that can view each space.
  • Page restrictions: the users and groups a restricted page (or a restricted ancestor) is limited to.
Serval matches Confluence users to Serval users by email. Confluence Data Center returns a user’s email only when your instance’s email visibility setting allows the token’s user to see it. If emails are hidden, Serval can’t match those users, and pages limited to them stay hidden from them in Serval. Data Center has no folders, so the tree is spaces and pages only.

​
Get your credentials

Personal access tokens are built into Confluence Data Center 7.9 and later. Atlassian’s guide is Using Personal Access Tokens. Serval sees exactly what the token’s user can see. Create the token from an account that can view every space you want to sync, for example a dedicated Serval service account.
1

Open your settings

In Confluence, select your profile picture at the top right of the screen, then select Settings.
2

Go to Personal Access Tokens

Select Personal Access Tokens in the left-hand menu.
3

Create the token

Select Create token and give it a name. You can optionally set an expiry - if you do, plan to rotate the token in Serval before it expires.
4

Copy the token

Copy the token immediately - Confluence shows it only once.

​
Connect in Serval

1

Select Confluence Data Center

In Serval, open your team’s integrations page and select Confluence Data Center. The integration is marked Beta.
2

Enter the Base URL (required)

Enter the address you open Confluence at, including its context path if it has one - for example https://wiki.example.com or https://example.com/confluence.The URL must start with https://. Serval removes the https:// prefix, a trailing slash, and anything after a ? or #, and keeps a port and the context path (entering https://Example.com:8443/confluence/ stores example.com:8443/confluence). An empty value is rejected with “Base URL is required”, an http:// address is rejected because Serval only connects over HTTPS, and a value Serval cannot read as a host and path is rejected.
3

Enter the Personal Access Token (required)

Paste the token you created into the password field. Serval rejects an empty value.
4

Submit and let the health checks run

Submit the form. Serval saves the connection and automatically runs the connection health checks.
5

Choose what to sync

Open the integration’s Knowledge tab, choose the spaces and pages to include, and start a sync.
When editing an existing connection, the Base URL field comes pre-filled with the stored address, and the token field shows a masked placeholder. Leaving the token untouched or blank keeps the stored token, and leaving Base URL blank keeps the stored address - you only need to fill in the field you are changing.

​
Verifying the connection

  • Validate Confluence Data Center API Connection - confirms Serval can reach your instance at the stored Base URL and sign in with the stored token by looking up the token’s user.
    • Success: “Successfully connected to Confluence Data Center as [name].”
    • Failure: “Unable to connect to Confluence Data Center. Please verify your base URL and personal access token are correct.”
  • List Confluence Data Center Spaces - confirms the token can read spaces by listing up to five.
    • Success: “Successfully listed [number] Confluence spaces.”
    • If the token’s user can’t see any space, the check still passes but tells you to grant it View permission on the spaces you want to sync.

​
Gotchas and troubleshooting

This integration is for self-hosted Confluence Data Center. If your Confluence lives at yourcompany.atlassian.net, use the Confluence (Cloud) integration instead. The two aren’t interchangeable.
Serval always connects to your configured address over HTTPS, so the instance must serve TLS - one that only speaks plain HTTP will not work. Serval also blocks requests to hosts that resolve to internal or private IP addresses, so an instance reachable only on a private network cannot be connected and the health checks will fail even with a valid token. Expose the instance on a publicly resolvable HTTPS address and allow inbound access from Serval before connecting.
If Confluence is served under a path such as /confluence, enter it as part of the Base URL. Leaving it off sends every request to the wrong address, and the health checks fail.
Serval only sees what the token’s user can see. Give that user View permission on the space, and make sure page restrictions don’t exclude it.
Serval matches Confluence users to Serval users by email. If your instance hides user emails, Serval can’t make that match. Allow the token’s user to see email addresses in Confluence’s user email visibility setting, then sync again.
Need help? Contact support@serval.com for assistance with your Confluence Data Center integration.