Part III: Connectors
This is the connector home page. It explains the common lifecycle and access rules. Use the dedicated guide for the provider you want to connect.
Open Connectors at /app/connectors or open Add Connector at /app/admin/add-connector.
Connector lifecycle
Every indexed connector follows this path:
- Create. Choose a provider, enter the form fields, and authorize the provider or save customer credentials.
- Source sync. Nous reads the provider and discovers the selected items.
- Search indexing. Nous processes and indexes supported items.
- Ready. Search can return the indexed items. New and changed items are picked up on later refreshes.
- Reconnect, reindex, or remove. Use the connector detail page when a credential expires, a scope changes, or the connector is no longer needed.
Source sync and search indexing are separate. A connector can show that source sync is complete while some documents still wait for search indexing. Check both statuses before testing a new connector.
Waiting for indexing capacity
Busy workspaces share indexing time equally. Each workspace shares its time among connectors with work ready to process. A large import does not need to finish before a new connector can start.
When a required AI service is busy or unavailable, affected documents wait and resume automatically from saved progress. Other documents can continue when the services they need are available. Large scanned files may need several processing turns. Their remaining pages, text recognition, visual content, and metadata still need to finish before indexing is complete.
Leave the connector in place while it waits. Repeated restarts or reindexing do not add capacity. Check the document counts and errors on its detail page. If a document reports a failure that needs action, resolve the stated cause before retrying it.
When the detail page says Waiting for model capacity, the pending count shows documents waiting for a shared model service. The page identifies the waiting steps in plain language, such as text indexing, text recognition, metadata extraction, or image indexing. Retrying automatically means the connector will continue from its saved progress when capacity returns. Pausing the connector removes that automatic-retry guidance until you resume it.
If a file makes no indexing progress for two hours while waiting for model capacity, automatic retries stop. Resolve the issue, then retry indexing from the connector page.
Access and sharing
Choose the document access that matches the business need:
| Access | Result |
|---|---|
| Everyone in the workspace | Every workspace member can search the indexed content. |
| Specific Teams | The content is available only to the selected active Portal Teams. |
| Sync permissions | Supported SharePoint and Google Drive credentials copy source permissions into search. |
Manage Team membership in Portal. Manage the connector and its Team bindings in Nous. Choosing Specific Teams does not make a connector public. A document set can narrow access, but it cannot bypass the connector access rules. See Document Sets.
For SharePoint, permission sync starts after the first document batch is indexed. It continues in saved batches while content indexing is still in progress. Documents that are not indexed yet stay unavailable. When content indexing finishes, Nous runs a final pass for files that were not covered by an earlier permission batch.
Indexing status and testing
Indexed connections no longer have a shared indexing start date. After the upgrade, connections that used that setting discover older content in the background, within their existing source selection and permissions. You do not need to request a full reindex. This discovery does not force unchanged content to be processed again; subsequent refreshes remain incremental.
Paused connections wait until you resume them. Reconnect invalid credentials before discovery can continue. If a source cannot be fully read, its sync history keeps the failure visible. Correct the source problem and resume the connection to retry. Provider-specific retention and selection rules still apply, and live-app connections are not added to the index.
Open the connector detail page and check:
- the source-sync state;
- the search-indexing state and document counts;
- the last successful refresh;
- the Last completed permission sync when Sync permissions is enabled;
- the Current access in Nous sample for a quick check of stored document access.
Queued means the refresh is scheduled and waiting to begin. It is not a stalled scan, so do not reindex or remove the connector while it is queued. Nous shows a stalled warning only after an older refresh can be confirmed as no longer waiting or running. If that check is temporarily unavailable, the state stays unknown instead of showing a false warning.
After the states are ready, search for a known item in Knowledge Search. Test once as a member who should have access and once as a member who should not have access. A private connector must fail closed for the second member.
Connector comparison
The current customer setup flow supports these 18 sources. The old internal Craft catalog and other legacy source types are outside this guide.
| Guide | Indexed or live | Customer setup |
|---|---|---|
| SharePoint | Sites, libraries, folders, files, and supported pages are indexed. | Sophea-managed OAuth. Customer certificate credentials are an alternate path only for permission sync. |
| Google Drive | Selected Drive files, folders, shared drives, and shared files are indexed. | Sophea-managed OAuth. |
| Microsoft Teams | The member’s chats and visible team channel messages are searched live for the signed-in member. Nothing is indexed. | Sophea-managed OAuth. |
| Slack | The member’s visible channels and messages are searched live for the signed-in member. Nothing is indexed. | Sophea-managed OAuth. |
| Confluence | Pages, attachments, comments, and selected spaces are indexed. | Sophea-managed OAuth. |
| Notion | Authorized pages and child pages are indexed. | Sophea-managed OAuth. |
| Dropbox | Selected Dropbox folders and files are indexed. | Sophea-managed OAuth. |
| Gmail | Personal mailbox messages are searched live for the signed-in member. They are not copied into the workspace index. | Sophea-managed OAuth. |
| Microsoft Outlook | Personal mailbox messages are searched live for the signed-in member. They are not copied into the workspace index. | Sophea-managed OAuth. |
| Microsoft Outlook Calendar | Personal calendar events are searched live; nothing is indexed. | Sophea-managed OAuth. |
| ClickUp | Tasks and Docs in one personal workspace are read live. Clear current-message requests can directly update supported task and Doc page fields with audit and replay protection; nothing is indexed. | Customer personal API token. |
| Jira | Issues, comments, and supported project data are indexed. | Customer Jira account and API token. |
| Linear | Issues, projects, teams, and supported comments are indexed. | Sophea-managed OAuth. |
| HubSpot | Personal deals, companies, contacts, and tickets are searched live; nothing is indexed. | Personal Sophea-managed OAuth. |
| Salesforce | Selected Salesforce objects and records are indexed. | Customer Salesforce credentials. |
| Amazon S3 | Objects in the selected bucket and prefix are indexed. | Customer AWS access keys. |
| Google Cloud Storage | Objects in the selected bucket and path prefix are indexed. | Customer HMAC access key and secret. |
| Web | Pages from a public website are indexed. | No credentials. |
Sophea-managed OAuth means that Sophea operates the provider app. The customer authorizes access in the provider consent screen. The customer does not create or paste an OAuth client secret into Nous. Customer credentials mean that the customer creates and rotates the provider credential and enters it in the setup form.
Microsoft Teams, Slack, Gmail, Microsoft Outlook, Microsoft Outlook Calendar, and ClickUp are personal live-app connections. They use the signed-in member’s account at question time. They do not add content to the workspace index, Knowledge Search, or document sets.
Choose a connector guide
Use the guide that matches the source:
File connectors
A file connector holds documents you upload instead of reading a provider, so it is not in the comparison table above. Both admins and members can create one.
PNG, JPEG, WebP, BMP and TIFF images are searchable through visual indexing. Multi-page TIFF files include every page. If an image is damaged, its document shows an error instead of being marked indexed. Each image or TIFF page can contain up to 16,777,216 pixels. If indexing stops during a temporary service outage, it resumes from saved work.
PDFs that require a password cannot be indexed. Upload a copy that opens without a password. Retrying the same protected file will not resolve the error.
| Role | Where | Access |
|---|---|---|
| Admin | Connectors, then File | Only you, Specific teams, or Workspace |
| Member | Connectors, then File | Private to the member, or shared with Teams the member belongs to |
For an admin, Only you keeps the files personal, Specific teams gives access only to the Teams you select, and Workspace lets everyone in the workspace search the files. Only you uses the personal limits below, even for an admin. Team and Workspace connectors do not use the personal quota. All uploads still use the workspace per-file limit and the same PDF and ZIP checks. A ZIP may contain up to 3,000 entries and expand to at most 1 GB. If an archive exceeds a safety limit, extract it on your computer and select the files directly.
A member cannot share a connector with a Team they do not belong to, and cannot make one available to the whole workspace. Ask an admin to create the connector if the whole workspace needs it.
Personal File connectors work within these limits:
| Limit | Value |
|---|---|
| File connectors per person | 10 |
| Files per connector, including extracted ZIP entries | 3,000 |
| Total upload size per person | 1 GB |
Per-file size uses the workspace upload limit in Settings, the same limit as every other upload.
An automation does not check these limits when it adds a file to a connector. The files it added still count: the next time the member adds or removes a file themselves, the 3,000 file limit is checked against everything the connector holds. The total upload size counts only what members upload in Nous.
Each upload sends up to 3,000 selected files in one request. ZIP contents count against the stored-file limit after extraction. The selection shows its file count and total size, with filenames in a scrollable list so the form actions stay reachable. Remove files from an over-limit selection before uploading. For an oversized or unreadable file, choose a smaller or repaired copy; for a protected PDF, choose a copy that opens without a password.
If an upload is interrupted, use Retry without changing the selection. The files are sent again. If the upload had already completed, Retry returns the same result without adding duplicates. Keep the page open to retain that Retry operation. Changing the selection starts a new operation. Upload completion means the files were accepted; indexing can continue before they appear in search.
Add or remove files later on the connector page. Removing a file deletes the stored copy and removes the content from search on the next refresh.
To use uploaded files in a scoped set, add the connector to a Document Set.
Sync history and documents needing attention
The Portal connector page keeps the history of every sync, not only the latest one, and lists the documents that could not be added to search.
History shows one row per run: when it started, what kind of run it was, how long it took, how many documents it checked, and the outcome. Read the outcomes this way:
- Succeeded: every document the run checked is in search.
- Completed with errors: the run finished and some documents failed. The row counts the errors that run recorded; the documents that still need attention are listed on the Overview tab, since a later retry can already have fixed some of them.
- Failed: the run itself could not finish. The row carries the reason, for example an expired credential or a source that could not be reached.
- Canceled: something replaced the run, usually a full re-index.
- Running: the run is still going. The Overview tab shows how many documents it has found so far and how far through the source it is.
Documents needing attention on the Overview tab lists each document that failed, with what would fix it: a full re-index, a correction in the source system, or a closer look. Retry failed documents fetches those documents again and reports progress while it runs. It reaches every failed document on the connector, not only the ones shown on the page.
Search readiness counts the documents that were fetched but never became searchable. Retry documents that are not searchable processes them again. Unsupported file types are counted separately, and a retry does not change them.
Starting a full re-index cancels a document retry that is running; see Common recovery actions.
Common recovery actions
Full reindex processes missing, failed, and changed content first, then rebuilds healthy unchanged content. This applies to both files and text. Starting full reindex again while it is running keeps the same run and its saved progress. Starting it during a retry of failed or selected documents cancels that retry and preserves work already completed.
After an interruption, processing resumes from saved progress. Some sources need to scan their content again before continuing.
- Reconnect when OAuth authorization expires. Reconnect the same provider account and keep the existing scope where possible.
- Rotate credentials in the provider first. Test the new credential, then remove the old credential according to the provider’s security policy.
- Reindex after a provider scope or content selection changes. Reindexing does not grant access that the connector ACL does not allow.
- Remove a connector only after checking document sets, agents, and Teams that use it. Removing it also removes its indexed content from those scopes.
Personal connection pause and resume
A personal (member-private) connection, such as a personal Sophea Meet connection, pauses automatically after five sync failures in a row. In Connectors, the Your private connectors table shows the connection as Paused together with the last sync error. Only the connection’s owner sees the Resume action. Resume releases the pause and requests an immediate sync; it does not wait for the next scheduled refresh. If the source still fails, the connection pauses again after another five failures; fix the cause before resuming again. Raw provider error details are never shown to members; the error line always carries a reviewed safe message.
If a provider rejects the connection, open its dedicated guide for the exact permission and recovery action.