Folder Sync

Sync folders from SharePoint, Google Drive, OneDrive, or Confluence Cloud to keep agent and project knowledge current.

Folder Sync enables you to attach entire folders from SharePoint, Google Drive, OneDrive, or Confluence Cloud to your agents and projects. Confluence Cloud Folder Sync imports pages from named folders, not files attached to those pages. Their content appears in the agent's Folders row or the project's Context section and updates daily.

How Folder Sync Works

Unlike direct file attachments, Folder Sync uses semantic search to identify relevant sections from synced text documents. Synced spreadsheets use complete file reading instead.

• Processing method: Semantic search for text documents; complete file reading for spreadsheets
• File limit: Up to 200 files per folder in Cloud workspaces
• Best for: Large document collections, FAQ agents, department knowledge bases
• Updates: Daily automatic synchronization
• Context: Only relevant sections sent to model
• Processing method: Preview in context with up to 20 Agent knowledge documents. Above the threshold, text documents remain available through file lists and file tools, while spreadsheets stay available for direct reading
• File limit: Up to 50 files per Agent
• Best for: Small, frequently referenced documents
• Updates: Local uploads need manual replacement; integration files update daily and can be refreshed manually
• Context: Text documents remain available through file listing and reading above the preview threshold. Spreadsheets remain available for direct reading

Setting Up Folder Sync

Navigate to your agent or project

Open the agent where you want to attach a synced folder and go to the Folders row. In a project, open the Context section.

Start the attachment process

Click Add folders in the Folders row and search for your folder by name. In a project, choose Select file or folder and search the same way.

Review sync limitations

Before attaching, you'll see a dialog showing the sync parameters for your selected folder:

• Daily synchronization: Files sync once per day for up-to-date content
• File maximum: Up to 200 files per folder in Cloud workspaces. Dedicated deployments support up to 1,000 files per folder.
• File type restrictions: Images are excluded
• Initial sync duration: First sync can take up to one hour

Confirm and attach

Review the folder contents and click Attach folder to begin the initial synchronization.

Folder Sync Limitations

Understanding these technical constraints helps you optimize your folder structure and content strategy:

File and Folder Limits

• Per Agent or Project Limit — Maximum of 5 synced folders per agent or project to maintain optimal performance and response quality.
• Per Folder Limit — Up to 200 files per folder are processed in Cloud workspaces. Dedicated deployments support up to 1,000 files per folder. Files beyond the applicable limit are automatically excluded.

File Type Restrictions

ajan reads spreadsheets in synced folders directly through the same read tool used for directly attached spreadsheets. You can open and query specific sheets and cells on demand. ajan retrieves text documents through semantic search. Images remain excluded because Folder Sync does not support their processing methods.

Subfolder Handling

Subfolders count toward the 200-file limit in Cloud workspaces. Dedicated deployments use a 1,000-file limit. Attaching subfolders directly as separate synced folders often provides better results:

• Reduced file skipping: Direct subfolder attachment decreases the probability of important files being excluded
• Better organization: Separate synced folders for different topics or departments improve content relevance
• Clearer context: Focused folder scope helps the semantic search identify more relevant content sections

Sync Behavior and Timing

Automatic Updates

Your synced folders refresh once daily to ensure agents and projects have access to the latest document versions. This automatic process:

• Detects new files added to the folder
• Updates existing files that have been modified
• Removes files that have been deleted from the source folder
• Maintains the applicable file limit by processing files in the order they appear in the source system

Initial Sync Duration

During the initial sync, the system:

1. Downloads and processes each supported file. It embeds text documents for semantic search and prepares spreadsheets for direct reading.
2. Creates searchable indexes for content discovery
3. Validates file formats and applies restrictions
4. Establishes the synchronization schedule

Manual Refresh

In addition to automatic daily syncs, you can manually refresh a synced folder at any time to get the latest updates immediately:

1. Open the agent's Folders row
2. Click Refresh on the synced folder you want to update

In projects, the same Refresh and Delete controls appear on synced folders in the Context section.

The manual refresh triggers an immediate sync, which is useful when:

• You've just added important files that need to be available right away
• You want to verify that recent changes have been synchronized
• You're troubleshooting sync issues and want to force an update

Connection Ownership and User Removal

When you attach a folder from an integration to an Agent or Project, ajan uses your personal OAuth connection to authenticate and synchronize the files. This connection is tied to your user account.

What Happens When a User Is Removed from ajan

When a user is deleted from ajan:

1. Files remain attached: The documents that were already synced stay attached to the agent or project. Users with access can continue reading them when they have source permissions and their own integration connection
2. Syncing stops: The OAuth connection that was used to refresh and sync the folder is deleted along with the user account
3. No automatic recovery: The system cannot automatically reconnect to the source folder

How to Restore Syncing

To resume synchronization after the original connector is removed:

Remove the broken folder

Open the agent's Folders row or the project's Context section and remove the folder that is no longer syncing.

Re-add the folder

Have another user with access to the same source folder re-attach it.

Verify the new connection

The new user's OAuth connection will now be used for all future synchronization.

Access Control and Permissions

Workspace Configuration

Admins control Folder Sync availability with the Attach integration folders role permission, which sets who can attach integration folders to agents and projects. To change it:

1. Navigate to Settings > Roles in your workspace
2. In the Files section, enable or disable Attach integration folders for each role

Users also need editor access to the agent or project they attach a folder to.

Agent Sharing and Permissions

How permission inheritance works:

• When a user queries the agent, ajan verifies their access to each file using their connected account
• Files a user doesn't have permission to view in the source system are hidden from that user's file listings and search results
• Users must have their own integration connection to access synced folder content

Best practices for sharing agents with synced folders:

• Ensure users have appropriate permissions in the source system for the content they need
• Users should connect their own accounts to the relevant integration
• Regularly audit which agents have access to synced folders

Optimizing Folder Sync Performance

Folder Structure Recommendations

For best results, organize folders within the 200-file limit in Cloud workspaces. Dedicated deployments support up to 1,000 files per folder.

• Organize by topic: Create focused folders for specific subjects or projects
• Use descriptive filenames: Clear names help semantic search identify relevant content
• Regular cleanup: Remove outdated or irrelevant files to maximize the value of your file allocation
• Consider subfolder strategy: Attach important subfolders separately rather than relying on the parent folder

Content Quality Tips

• Consistent formatting: Well-structured documents improve search accuracy
• Clear headings: Proper document structure helps identify relevant sections
• Avoid duplicates: Multiple versions of the same content can confuse the semantic search
• Update frequency: More frequently updated folders benefit most from daily synchronization

Troubleshooting Common Issues

Possible causes:

• Integration not enabled in workspace
• Insufficient permissions to access the folder
• Folder contains no supported file types

Solutions:

• Verify the relevant integration is active
• Check folder permissions in the source system
• Ensure folder contains at least one supported file format

Possible causes:

• Folder exceeds the 200-file Cloud limit or the 1,000-file Dedicated limit
• Files are unsupported formats
• Sync still in progress

Solutions:

• Review folder contents and remove unnecessary files
• Wait for initial sync to complete (up to one hour)

Possible causes:

• Source folder permissions changed
• Integration connection issues
• Workspace sync settings modified

Solutions:

• Verify continued access to source folder
• Check integration status in workspace settings
• Contact admin to review sync configuration

Cause: The user who originally connected the folder has been removed from the ajan workspace. When a user is deleted, their OAuth connection is also deleted, breaking the sync.

Solutions:

• Remove the folder from the agent's Folders row or the project's Context section
• Have another user with access to the source folder re-add it
• The new user's connection will be used for future synchronization

See Connection Ownership and User Removal for more details.

FAQ

Folder sync connects a source folder to ajan so files can be processed and made available as knowledge. ajan uses the synced content for retrieval after files are accessible and processed.

New or changed files may take time to sync and process before they are searchable. The exact timing can depend on source size, file count, provider availability, permissions, and processing status.

Direct uploads are usually used for a specific chat or task. Synced folders are reusable knowledge sources. Text documents are searched for relevant chunks, while spreadsheets are read directly. Synced content is better for ongoing retrieval, while direct uploads are better when the current chat needs a specific file.

The connected account must be able to access the source folder and files. If files are missing, verify the account permissions in the source system, the selected folder, admin consent if required, and whether the integration connection is still valid.

Check whether the folder is connected, whether the files are supported, whether processing has completed, whether the connected account can access the files, and whether the files were recently moved, renamed, or deleted.