System Overview

Confluence Cloud is Atlassian’s collaborative workspace that enables teams to create, organise, and share knowledge at scale. From an enterprise search perspective, it serves as a central knowledge repository, where content is structured in spaces and pages, making it a key source of organisational knowledge to index and surface in Moveworks’ enterprise search.

Authentication

Moveworks supports two authentication methods. You will configure one Confluence connector using either method based on your requirements.

Forge App Method (Recommended)

Uses the Moveworks Forge App installed via the Atlassian Marketplace to securely access Confluence data.

• Installed directly at the Confluence site level via the Atlassian Marketplace with admin approval.
• Public spaces are ingested by default; restricted content is ingested only when the app is explicitly granted access.
• Reduces operational overhead by avoiding manual user provisioning, credential rotation and access management
• Ensures a more secure integration model by avoiding exposure of static credentials (such as API tokens)
• Aligns with Atlassian’s recommended app development and authentication framework for cloud integrations

Service Account Method

Uses a dedicated Confluence user with API token-based authentication to access Confluence data via REST APIs.

• Requires creation and management of a Service Account (email address) within Atlassian
• Requires generation and secure storage of an API token, which is used for Basic Authentication
• The Service Account must have read (view) access to all Confluence spaces where end-user knowledge articles reside
• Access to restricted pages, blog posts, and attachments depends on whether the Service Account has been explicitly granted permission
• Introduces additional operational overhead due to dependency on manual access management and credential handling

Permissions Enforcement

• Moveworks honours all user access controls, ensuring that individuals only see search results for content they are permitted to view.

API Usage

• Moveworks uses Atlassian’s standard REST API for Confluence to ingest all data

Content Types

The Confluence connector for Moveworks supports the following content types:

• Pages: All Confluence pages within accessible spaces
• Blog Posts: All blog posts within accessible spaces
• Attachments: Files attached to pages and blog posts
• Supported file formats:
  • Forge App: PDF

• Service Account: PDF, doc, docx, ppt, txt, html

• Macros: Wide range of static and dynamic macros
• Restricted Pages:
  • Forge App: Available if the app is explicitly granted access
  • Service Account: Available if shared with the service account

Moveworks delivers comprehensive data coverage—including metadata, identity data, permissions data, and activity data—and keeps content in sync in real time, ensuring that updates and permission changes are immediately reflected in search results.

Access Requirements

Moveworks requires a Service Account to connect with your Confluence instance. First, you’ll need to create a Service Account by going to the admin portal of your Atlassian instance. Moveworks uses Basic Authentication to authorize with the API and requires the Username (email address of your Service Account) and Password (API token generated for your Service Account). Make sure the Service Account has read access to all spaces you want to ingest into Moveworks and has access to all users and relevant permissions.

Pre-requisites

Before you get started, make sure you have everything you need:

1. Admin permissions
   1. Org/Site admin access in Atlassian Admin so you can create or invite a user and assign a Confluence license.
   2. Space admin access (or help from the space owners) to give the service account view permissions across the spaces you want to index.
2. Environment details
   1. The base URL of your Confluence instance—for example: https://<your-site>.atlassian.net/wiki if you’re using the standard Confluence Cloud setup.
3. List of spaces to ingest
   1. Put together a list of all the Confluence spaces you want Moveworks to index, including any with page restrictions. This makes it easier to give the service account “View” access to all of them in one go.

Setup Service Account in Confluence

You’ll need to create a new Service Account within your domain and ensure you have access to its email inbox. This inbox will be used later to onboard the Service Account to your Confluence instance.

Once the initial setup for the Service Account is complete, let’s proceed with the onboarding to Confluence.

1. Visit the https://admin.atlassian.com page and ensure the correct organisation is selected.
2. Navigate to Directory → Users and click on the “Invite users” button. Enter the email address of the Service Account and assign the Confluence application to it. By default, the user will be added to the standard users group in your Confluence instance. If your instance uses a specific group with access to certain spaces, make sure the Service Account is added to that group as well. Click on the “Send invite” button once done.
3. Go the Service Account email inbox and accept the invite. This will ask the user to setup the Full name and Password - Complete all the necessary steps. Once done you can now visit this URL : https://id.atlassian.com/manage/api-tokens as Service Account and generate the API key (Refer to the below section for detailed steps)

Generating API token

1. Log in to https://id.atlassian.com/manage/api-tokens using the Service Account, and click on “Create API token.” This token will be associated with the Service Account in your Confluence instance.
2. Once you’ve created the API token, it will be displayed for you to copy and save. Please note that this is a one-time view, so make sure to record it and store it securely for future use.
3. While creating the connector you will need to use this credential - Record the Service Account email address and this API token.

Testing your generated API token (Optional)

It’s a good practice to verify that your generated token has access to all the APIs needed for Moveworks ingestion. You can do this in Postman or any tool that supports CURL commands. Use Basic Auth for authentication, with the service account email as the username and the API token from the previous step as the password.

• Content

  1
  curl --location 'https://testing-permissions-content.atlassian.net/wiki/rest/api/content' \
  2
  --header 'Accept: application/json' \
  3
  --header 'Authorization: Basic {your-credentials}'
• Permissions
  • Once you have successfully hit the content API get a content ID and parse in the following CURL request

  1
  curl --location --globoff 'https://testing-permissions-content.atlassian.net/wiki/rest/api/content/{id}/restriction' \
  2
  --header 'Accept: application/json' \
  3
  --header 'Authorization: Basic {your-credentials}'
• Groups

  1
  curl --location 'https://testing-permissions-content.atlassian.net/wiki/rest/api/group' \
  2
  --header 'Accept: application/json' \
  3
  --header 'Authorization: Basic {your-credentials}'
• Users

  1
  curl --location 'https://testing-permissions-content.atlassian.net/wiki/rest/api/user/current' \
  2
  --header 'Accept: application/json' \
  3
  --header 'Authorization: Basic {your-credentails}'

Setup in Moveworks

Connector Creation

1. Log in to your org’s MyMoveworks portal
2. Navigate to Moveworks Setup > Connectors > Built-in Connectors
3. Click Create New
4. Search and Select Confluence (Next Gen)
5. Click on Next: Add Creds
6. Input the following details
   1. Connector Name : Name this connector for your future reference. Once set, this name cannot be changed.
   2. Username: Enter the email address of the service account, that you are using for this connector.
   3. API Token: Enter the API token that you have generated in the previous step.
   4. Base URL: Enter the URL of your Atlassian instance.
      1. Common Base URL: If you are using Confluence Cloud, select this option. This field requires the URL of your Atlassian instance. Open the Confluence application in your preferred browser and copy the URL. For Confluence Cloud, the URL follows this pattern: https://your-instance-name.atlassian.net/wiki/home Copy your instance name from this URL and paste it into the text field provided.
         
      2. Custom Base URL: If you are using Confluence Data Center or Server, your Atlassian URL will vary based on your specific configuration. In this case, you’ll need to provide the full URL domain. Open Confluence in your browser and copy the complete URL from the address bar.
   5. Click Save.
      This connector will now be used to configure content ingestion from Confluence (cloud). Refer to the steps mentioned below.

Configuring Confluence (Cloud) for Enterprise Search

Initialising setup

1. Log in to your org’s MyMoveworks portal
2. Navigate to Moveworks Setup > Search > Configure Search > Max Capacity
3. Click on Create New or Get Started
4. Select Confluence (cloud) from the dropdown list and click on Get Started
5. You will be redirected to the Confluence ingestion overview page. In the overview page, you will find few info blocks and few configuration blocks.
   1. System Overview: This presents an overview of Confluence (cloud) support from Moveworks
   2. Ingestion Summary: This provides information on the count of records that has been ingested and serving. The values will appear after the first successful ingestion run.
   3. Connector Selection: In this configuration block, you are required to select the required connector to enable Moveworks to connect and fetch data
   4. Content Selection: In this configuration block, you are required to define the content that should be ingested within Moveworks

Connector selection and validation

1. Once you click on Select Connector, a connector setup screen will appear as follows

2. Select the connector (from the dropdown) that you have created in the Connector Creation step.

   Please note: Only the Confluence (Next Gen) connectors will appear in this list.

3. Once the connector is selected, you need to click on Start Validation to validate the connector credentials and required scope.

   Connector Validation

   This is a mandatory step in order to save the configuration and move to the next step.

   Moveworks validates the selected connector to check:

   • Auth: Moveworks validates if the connector has right credentials to authenticate
   • Content: Moveworks validates if connector has right scopes to fetch content
   • Permissions: Moveworks validates if connector has right scopes to fetch user permissions
   • Users: Moveworks validates if connector has right scopes to fetch user data
   • Groups: Moveworks validates if connector has right scopes to fetch user groups data

   

4. If the connector is validated successfully, you will see a green info banner as follows.

   1. If there are any credentials or scope issues, you will receive an error message as follows. Click on View Details to identify the issue. Refer to this step-by-troubleshoot guide (link to be added) to rectify any validation errors.

5. Once the connector is validated successfully, you will be able to Save the configuration.

6. Input the unique configuration name and Save.

   At this stage, only the configuration entry is created. Ingestion doesn’t start immediately after this step. You need to configure the Content Selection step to complete the journey. Refer to the next section for details.

7. Once the configuration is saved, you can view the unique configuration name at the top of the screen. You can also click the pencil 🖊️ icon to edit the configuration name.

8. Additionally, you will start seeing an entry of your configuration in the Enterprise Search home page. You can click on your configuration to go to edit/ complete the configuration.

Content Selection

Once the connector selection step is complete and the configuration is saved, you will now be required to define the scope of content that will be ingested in Moveworks.

1. Once you click on Select Content, a content selection screen will appear as follows.
2. In this screen, you are required to define the Spaces from which Moveworks will ingest content and apply filters (optionally) to filter down the content further.
3. Space Selection: This is a mandatory configuration. This configuration defines which spaces Moveworks will crawl and ingest content from. As an admin, you get three options

   1. Only selected spaces (Recommended): Moveworks will only ingest content from specified spaces.

      When to choose this option? Choose this option if you want content to be served only from a subset of spaces that are accessible to the service account. For example - Let’s assume, Service Account has access to 15 spaces, but you want content to be served only from 5 spaces, then you choose this method.

      Important Note: The Service Account must have access to the specified spaces in order for Moveworks to crawl all spaces successfully.

      How to configure? Enter comma separated Space Key(s).

   2. All except selected: Moveworks will ingest content all except specified spaces.

      When to choose this option?

      Choose this option if you want content to be served from all except few spaces. For example - Let’s assume, Service Account has access to 60 spaces, but you want content to be served from 58 spaces, then you choose this method and specific the 2 spaces from which Moveworks should not ingest.

      Important Note: The Service Account must have access to the specified spaces in order for Moveworks to crawl all spaces successfully.

      How to configure? Select this option and enter comma separated Space Key(s).

   3. All spaces: Moveworks will ingest content all applicable spaces

      When to choose this option?

      Choose this option if you want content to be served from spaces that service account has access to. For example - Let’s assume, Service Account has access to 20 spaces, and you want content to be served from all 20 spaces, then you choose this method.

      Important Note: The Service Account must have access to the specified spaces in order for Moveworks to crawl all spaces successfully.

      How to configure? Select this option. You are not required to specify the Space Keys in this scenario.

4. Additional Filters: Use these filters to narrow the content ingestion scope further. Only records matching ALL of the the specified criteria will be included.
   This is an optional configuration. Moveworks recommend using these filters only if your dataset is very large (i.e. >1million records) so that only relevant content is ingested and served to your employees.

   Currently following filters are supported:
   1. Modified date: Use this filter to include only those content records whose Modified date is after a specified date.
   2. Created date: Use this filter to include only those content records whose Created date is after a specified date.
      Note: We support absolute dates only. Relative ranges (e.g., “last 7 days,” “older than 1 year”) are not supported.

   

Save and Start Ingestion

Once Space selection is configured, you have two options:

• Save: Clicking this will just save the configuration and not initiate the first ingestion crawl. Use this option, if you would want to complete your configuration in multiple sessions/ sittings.

  • Once you click on Save, you will be redirected to the Confluence overview screen
  • You will notice a banner that prompts you to Start Ingestion
  • Once you are satisfied with your configuration, you can click on Start Ingestion
  • A confirmation popup will come that provides a summary of the configuration
  • Click on Confirm
  • After you click on Confirm, ingestion will start shortly.
  • For the first crawl to complete, this generally takes anywhere from few hours to 48 hours depending upon the size of the data.

• Save and Start Ingestion: Click this option if you have completed and validated your content selection configuration and you are ready to initiate the first ingestion crawl.

  • A confirmation popup will come that provides a summary of the configuration
  • Click on Confirm
  • After you click on Confirm, ingestion will start shortly.
  Important Note for Admins:

  • It generally takes anywhere from few hours to 48 hours for the first crawl to complete depending upon the size of the data.
  • You can review the status of ingestion via Data Ingestion Viewer and view ingested record in the Indexed Content > Files and Indexed Content > Internal Knowledge screens.

Troubleshooting Connector Validation Failures

This section helps you resolve common issues when validating your Confluence connector in Enterprise Search Configuration. Follow the steps below based on the error message(s) you’re experiencing.

Error Message(s):

• “Validation failed: Invalid credentials or missing required scopes.”

Possible Causes:

• Service Account is not part of any groups or belongs to groups that lack space access
• API token is expired
• Incorrect authentication credentials (email or API token)
• Connector is not setup correctly

Resolution Steps:

1. Check whether the Confluence connector is setup correctly
   1. The Base URL is correct and valid of the desired instance and in the format: https://{your_domain}.atlassian.net/wiki
   2. The email provided is valid
   3. API token is valid
2. Verify whether API token is not expired
   1. Go to Atlassian Account Settings → Security → API Tokens
   2. Confirm the token is active and hasn’t expired
   3. If not, generate a new API token and provide it in the Confluence connector
3. Check Access to Confluence Spaces
   1. Log into Confluence with your credentials in {yourdomain}.atlassian.net
   2. Navigate to the spaces you want to bring in
   3. Confirm whether the desired group is added in the space, has view access and Service account is also present in the group (see via admin.atlassian.com)
   4. Contact your Confluence admin if you need help
4. Try accessing the Confluence REST API directly
   1. Go to Moveworks Setup > Connectors > API Playground
   2. Import the Confluence connector you’re using for Enterprise Search
   3. Test the relevant API endpoint for resources you got the error:
      1. Content
         1. Test: /rest/api/content API
            cURL request for reference:

            curl --location 'https://{{org_domain}}.atlassian.net/wiki/rest/api/content' \
            --header 'Authorization: Basic {{api_key}}'
         2. Verify the expected result: list of content items returned in the API response
      2. Permissions
         1. Test /rest/api/content and copy contentId from any content item in the API response
            cURL request for reference:

            curl --location 'https://{{org_domain}}.atlassian.net/wiki/rest/api/content' \
            --header 'Authorization: Basic {{api_key}}'
         2. Test /rest/api/content/{contentId}/restriction using the copied ID
            cURL request for reference:

            curl --location 'https://{{org_domain}}.atlassian.net/wiki/rest/api/content/{{content_id}}/restriction' \
            --header 'Authorization: Basic {{api_key}}'
         3. Verify the expected result: restriction details returned for the content item in the API response
      3. Groups
         1. Test: /rest/api/group

            curl --location 'https://{{org_domain}}.atlassian.net/wiki/rest/api/group' \
            --header 'Authorization: Basic {{api_key}}'
         2. Verify the expected result: List of groups returned in the API response
      4. Users
         1. Hit /wiki/rest/api/user/current and copy the accountId
            cURL request for reference

            curl --location 'https://{{org_domain}}.atlassian.net/wiki/rest/api/user/current' \
            --header 'Authorization: Basic {{api_key}}'
         2. Hit /wiki/rest/api/user/memberof?accountId={{account_id}} using the copied account ID and then copy groupId from any group item in the API response

            curl --location 'https://{{org_domain}}.atlassian.net/wiki/rest/api/user/memberof?accountId={{account_id}}' \
            --header 'Authorization: Basic {{api_key}}'
         3. Test /wiki/rest/api/group/{groupId}/membersByGroupId
            cuRL request for reference

            curl --location 'https://{{org_domain}}.atlassian.net/wiki/rest/api/group/{{account_id}}/membersByGroupId' \
            --header 'Authorization: Basic {{api_key}}'
         4. Verify the expected result: list of group members returned in the API response
5. Contact Moveworks Support
   Reach out to Moveworks Support if the validation error(s) still persist.