Skip to content

Commit 4770c98

Browse files
waleedlatif1waleedlatif1
committed
feat(search): document connector setup and harden source access
1 parent b939801 commit 4770c98

63 files changed

Lines changed: 2460 additions & 119 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/docs/content/docs/knowledgebase/connectors.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import { Step, Steps } from 'fumadocs-ui/components/steps'
88
import { Image } from '@/components/ui/image'
99
import { FAQ } from '@/components/ui/faq'
1010

11+
For workspace Search with each person's source permissions, use the [Search connector guides](/search). This page covers connectors inside general knowledge bases.
12+
1113
Connectors continuously sync documents from external services into your knowledge base, so you never have to upload files manually. New content is added, changed content is re-processed, and deleted content is removed — all automatically.
1214

1315
## Available Connectors

‎apps/docs/content/docs/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
"workflows",
1111
"agents",
1212
"---Workspace---",
13+
"search",
1314
"knowledgebase",
1415
"tables",
1516
"files",

‎apps/docs/content/docs/search/confluence.mdx‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
title: Confluence
3+
description: Connect Confluence Cloud spaces and set up each teammate's search access
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout'
7+
import { Step, Steps } from 'fumadocs-ui/components/steps'
8+
import { Image } from '@/components/ui/image'
9+
10+
Search pages and blog posts from selected Confluence Cloud spaces. A Sim workspace admin configures the source, and each teammate connects their Confluence account.
11+
12+
Search indexes each page's own text, including supported local callouts and code blocks. It does not expand Include Page, Excerpt Include, or third-party macros into that page. Referenced pages can be indexed separately with their own access rules.
13+
14+
## Choose a connection method
15+
16+
| Method | Who supplies the content? | What teammates do |
17+
| --- | --- | --- |
18+
| **Admin or service account** | One account syncs content, space permissions, page restrictions, and group membership. | Connect their own Confluence account so Sim can match their Atlassian identity to those permissions. |
19+
| **Member accounts** | Sim syncs content separately through connected members' accounts. | Connect their own Confluence account to establish which pages they can access. |
20+
21+
Use **Admin or service account** when you have a dedicated account that can read the intended spaces and their permissions. Use **Member accounts** when each person should supply their own connection. Available methods depend on your workspace's enabled features.
22+
23+
**Everyone still connects in both methods.** With a central account, teammates supply their identity; they do not configure another central crawl or choose spaces again.
24+
25+
## Before you start
26+
27+
- Be a **Sim workspace admin** to add the source.
28+
- Use a Confluence Cloud site such as `your-team.atlassian.net`. This connector does not connect to Server or Data Center.
29+
- Each teammate needs a verified Sim email matching their active Atlassian account's email.
30+
- For a central crawl, grant its account access to Confluence, the chosen spaces, and any restricted pages you want indexed. Admin status alone does not bypass page restrictions. It also needs permission to read space permissions and the user/group directory.
31+
32+
On hosted Sim, personal connections authorize the existing Sim app. Teammates do not create OAuth apps or service-account tokens. Self-hosted deployments need the [shared OAuth configuration](#self-hosted-operator-setup) even when a service account supplies the content.
33+
34+
## Set up the source
35+
36+
<Steps>
37+
<Step>
38+
39+
### Choose Confluence
40+
41+
Open **Search**, click **Add source**, and choose **Confluence**. Click **Set up** or **Continue setup** if prompted. Select your **Connection method**.
42+
43+
</Step>
44+
<Step>
45+
46+
### Select an account
47+
48+
For **Admin or service account**, open **Account** and select an existing account, choose **Connect Confluence account** for OAuth, or add a service account using the [steps below](#using-a-service-account).
49+
50+
For **Member accounts**, **Browse with** supplies an account for the space picker only. Select or connect an account, or switch **Spaces** to manual input to enter space keys without a browsing account. Browsing does not connect that account to Search or share its access with teammates.
51+
52+
</Step>
53+
<Step>
54+
55+
### Select the spaces
56+
57+
Enter **Confluence Domain**, then choose one or more **Spaces**. The picker shows spaces accessible to the selected account. Use the switch beside the field to enter comma-separated **Space Keys**, such as `ENG, PRODUCT`.
58+
59+
Keep **Content Type** at its default for pages, or choose blog posts or both. Leave **Filter by Label** empty unless you want a smaller scope. **Document details (optional)** contains metadata tag settings.
60+
61+
<Image
62+
src="/static/search/confluence-setup.jpg"
63+
alt="Confluence Search source configuration showing connection method, account, domain, and spaces"
64+
width={1280}
65+
height={720}
66+
/>
67+
68+
</Step>
69+
<Step>
70+
71+
### Save and connect your identity
72+
73+
Click **Connect & Sync** for a central account, or **Create & Invite** for member accounts. Back in Search, click **Connect account** on the Confluence row and finish the connection in the new tab. Sign in using the Atlassian email that matches your verified Sim email, and authorize the configured site.
74+
75+
Each teammate completes this last step. A previously authorized account may already be connected. Return to Search to see indexing status and your searchable document count.
76+
77+
</Step>
78+
</Steps>
79+
80+
## Using a service account
81+
82+
Sim's Atlassian service account form accepts a **scoped API token** and **site domain**.
83+
84+
<Steps>
85+
<Step>
86+
87+
### Give the service account Confluence access
88+
89+
Have an Atlassian organization admin create a service account under **Directory → Service accounts** in [Atlassian Administration](https://admin.atlassian.com/). Give it Confluence access on the intended site. A space admin must also grant access to the chosen spaces and any restricted pages the source should index. See [Atlassian's service-account setup](https://support.atlassian.com/user-management/docs/manage-your-service-accounts/).
90+
91+
</Step>
92+
<Step>
93+
94+
### Choose API token authentication
95+
96+
Select the service account, then **Create credentials → API token → Next**. This is the credential type accepted by Sim's service-account form.
97+
98+
<Image
99+
src="/static/credentials/atlassian/admin-auth-type-picker.png"
100+
alt="Atlassian Administration authentication selector with API token selected"
101+
width={1334}
102+
height={1050}
103+
/>
104+
105+
Atlassian Administration's credential selector. See the [current Atlassian instructions](https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/).
106+
107+
</Step>
108+
<Step>
109+
110+
### Select Confluence scopes
111+
112+
Name the token and choose an expiry between 1 and 365 days. In the scope picker, choose **Confluence** and add the scopes below; the list includes both classic and granular scopes. Review and create the token, then copy it for the next step. Atlassian only reveals the token once.
113+
114+
Use these scopes for Confluence Search content and permission reads:
115+
116+
```text
117+
read:confluence-content.all
118+
read:page:confluence
119+
read:blogpost:confluence
120+
read:space:confluence
121+
read:label:confluence
122+
search:confluence
123+
read:confluence-space.summary
124+
read:content.metadata:confluence
125+
read:space.permission:confluence
126+
read:confluence-user
127+
read:user:confluence
128+
read:group:confluence
129+
```
130+
131+
</Step>
132+
<Step>
133+
134+
### Add the token to Sim
135+
136+
In the Search setup's **Account** menu, choose the service-account option. Paste the **API token** and enter **Site domain**. Optionally add a display name and description, then click **Add service account**. Continue in the original source modal, using the same domain in both forms.
137+
138+
</Step>
139+
</Steps>
140+
141+
Scopes do not grant access to spaces or pages by themselves. Keep the account's Confluence permissions and its token scopes aligned. When a token expires or needs different scopes, create a replacement in Atlassian. In Sim, open **Integrations**, select the saved service account, and click **Reconnect** to enter the new token and the same site domain.
142+
143+
<Callout type="info">
144+
Personal OAuth uses Sim's shared Confluence integration and requests a broader set of permissions, including writes. Search reads content and permissions; it does not edit your Confluence pages. Older OAuth connections need to reconnect to grant the group-read permission used by central permission syncing.
145+
</Callout>
146+
147+
## Configuration
148+
149+
| Setting | What it controls |
150+
| --- | --- |
151+
| **Confluence Domain** | The Cloud hostname, such as `your-team.atlassian.net`. Do not paste a page URL or `/wiki` path. |
152+
| **Spaces / Space Keys** | Required spaces to index. The picker and manual key input are two ways to set the same scope. |
153+
| **Content Type** | **Pages only** by default. **All content** means pages and blog posts; it does not include comments or attachment contents. |
154+
| **Filter by Label** | Optional comma-separated labels. Content can match any listed label. |
155+
| **Document details** | Optional labels, version, and last-modified metadata tags. |
156+
157+
Search manages the schedule and hides item limits. Published/current content is indexed; archived and trashed content is excluded.
158+
159+
## Teammates and ongoing sync
160+
161+
Existing workspace members see the configured Confluence source and their own **Connect account** or **Reconnect** action. Add new teammates through your usual Sim workspace or SSO onboarding, then have them connect Confluence from Search. Connecting a Confluence account does not add someone to the Sim workspace.
162+
163+
With a central account, Sim applies space access together with the page's restrictions and inherited ancestor restrictions. Group membership is refreshed in the background. With member accounts, each person's provider listing determines the pages available to them. A Sim workspace admin does not automatically receive access to every Confluence document.
164+
165+
New content and permission changes require a sync and processing before Search reflects them. Open **Manage** on the source to inspect errors, edit its configuration, or trigger a sync. If your own account needs authorization again, use **Reconnect** on the source row.
166+
167+
## Troubleshooting
168+
169+
| What you see | What to check |
170+
| --- | --- |
171+
| **Connect & Sync** is disabled | Select a central account, enter the domain, and choose at least one space. |
172+
| Space picker is empty | Connect an account, enter the correct domain, and verify its space access. You can also switch to manual space keys. |
173+
| Service-account validation fails | Check the token's expiry, site, Confluence app access, and scopes. Use a scoped API token from an Atlassian service account. |
174+
| Content syncs but central search returns nothing | Connect your personal Confluence identity. Ask the admin to check directory/permission sync errors and group-read scopes. |
175+
| A restricted page is missing | Ensure the crawling account can view that page and its ancestors, and that your own account has the required access. |
176+
| Included or embedded content is missing | Add the referenced page's space to the source if appropriate. Search indexes pages separately; remote macro output, comments, and attachment contents are excluded. |
177+
| **Reconnect** or an email mismatch | Reauthorize with the Atlassian account matching your verified Sim email and grant all requested permissions. |
178+
179+
### Check access in Confluence
180+
181+
Open a missing page in Confluence with the affected teammate's account. On the page, **Share → General access** shows whether access comes from the space, a parent, or an explicit restriction. A space admin can inspect restricted pages under **Space settings → Content → Restricted**. Check both the teammate and central crawling account when using **Admin or service account**. See Atlassian's [content access guide](https://support.atlassian.com/confluence-cloud/docs/add-or-remove-page-restrictions/).
182+
183+
On Confluence Premium, **Inspect permissions** can show where a user's access is denied across the page, its ancestors, the space, and the product. Check **Can view**, resolve the relevant permission, then run a sync in Sim. See [Atlassian's permission inspection guide](https://support.atlassian.com/confluence-cloud/docs/inspect-a-users-permissions/).
184+
185+
## Self-hosted operator setup
186+
187+
Configure one shared Confluence OAuth integration for your deployment. This powers personal identity connections in both Search methods and the optional central OAuth account.
188+
189+
1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), select or create your deployment's **OAuth 2.0 integration**.
190+
2. Under **Authorization → OAuth 2.0 (3LO)**, add `https://<your-sim-domain>/api/auth/oauth2/callback/confluence` to **Callback URLs**, keep existing callbacks used by the deployment, and save.
191+
3. Under **Permissions**, add the Confluence API and configure the full `confluence` scope list for your release in [Sim's OAuth configuration](https://github.com/simstudioai/sim/blob/staging/apps/sim/lib/oauth/oauth.ts), including `read:group:confluence`. Also add **User Identity API** with `read:me`. Sim requests `offline_access` for refresh tokens. The service-account read scopes above do not replace the broader shared OAuth scope set.
192+
4. Enable sharing under **Distribution**. Set `CONFLUENCE_CLIENT_ID` and `CONFLUENCE_CLIENT_SECRET` from the app's **Settings**, verify `NEXT_PUBLIC_APP_URL`, and restart Sim.
193+
5. Start authorization from Search and select the configured site. Reconnect old accounts after adding scopes so the new permission grant takes effect.
194+
195+
A callback mismatch needs a corrected callback URL; a connection that works only for the app owner needs sharing enabled. See Atlassian's [OAuth configuration guide](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) and Sim's [deployment reference](/platform/self-hosting/integrations-oauth).

‎apps/docs/content/docs/search/connect-your-account.mdx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Connect your account
3+
description: Join your team's Search sources and finish connecting your own accounts
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout'
7+
import { Step, Steps } from 'fumadocs-ui/components/steps'
8+
import { Image } from '@/components/ui/image'
9+
10+
Your admin configures the source once. You connect your own account so Sim can establish what you are allowed to search.
11+
12+
<Steps>
13+
<Step>
14+
15+
### Join your workspace
16+
17+
Accept your Sim workspace invitation and sign in. Use a verified Sim email that matches your account at the source. If your company uses SSO, follow its sign-in process; SSO provisioning alone does not grant workspace access.
18+
19+
</Step>
20+
<Step>
21+
22+
### Open Search
23+
24+
Find the source under **Sources** and select **Connect account**. If it is missing, ask a workspace admin to add it.
25+
26+
<Image src="/static/search/connect-account.png" alt="Google Drive source row with Connect account" width={1280} height={720} />
27+
28+
</Step>
29+
<Step>
30+
31+
### Authorize your account
32+
33+
In the new tab, select **Connect** and complete the provider's authorization. Choose the account associated with your verified Sim email. The provider may require your organization's SSO or app approval.
34+
35+
Return to Search when the connection completes. Keep the original tab open; **Open again** resumes the connection if a popup was blocked or closed.
36+
37+
</Step>
38+
<Step>
39+
40+
### Start searching
41+
42+
The source row shows indexing status and how many documents are available to you. Search for something you can already open in the source. The first sync may take time, especially for large accounts.
43+
44+
</Step>
45+
</Steps>
46+
47+
## Do I always need to connect?
48+
49+
| Source setup | Your next step |
50+
| --- | --- |
51+
| Member accounts | Connect your own account, including when you are the admin. |
52+
| Confluence admin/service account | Connect Confluence to verify your identity; the administrator's account handles the crawl. |
53+
| Google Drive delegated service account | No personal connection is needed for that source. Your verified Sim email is matched to Drive permissions. |
54+
| GitLab instance administrator | No personal connection is needed. Your verified Sim email must match a confirmed GitLab email. |
55+
56+
Connecting one Google service does not connect all of them. Gmail, Calendar, and Drive each have their own Search connection.
57+
58+
## If you get stuck
59+
60+
| Status | What to do |
61+
| --- | --- |
62+
| **Connect account** | Complete the connection in the new tab. |
63+
| **Reconnect** | Authorize the same source account again. |
64+
| **Finish connecting in the other tab** | Finish authorization, or use **Open again**. Allow popups for Sim. |
65+
| No results | Check the source's filters and sync status with your admin. Confirm you can open the document at the source. |
66+
| Needs admin attention | Ask the workspace admin to inspect **Manage** for the source error. |
67+
68+
<Callout type="info">
69+
Your Sim workspace role does not override document access at the source. Connecting a different account or receiving a Search link does not share someone else's mailbox, private calendar, or restricted documents with you.
70+
</Callout>

0 commit comments

Comments
 (0)