> For the complete documentation index, see [llms.txt](https://docs.cogram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cogram.com/integrations/connecting-your-file-server.md).

# Connecting your file server

How an admin installs Cogram Connector to make Windows file shares available in Cogram.

Cogram Connector is a small Windows service that you install in your own network. It connects your file servers to Cogram as an organization-level integration. After setup, your team can browse the shares on the [Files](https://app.cogram.com/dashboard/files) page, search file names and file content, and preview files. [Agent](/agent/agent.md) can also read these files to answer questions.

This page is for the organization admin and the IT administrator who do the setup. For what your team sees day to day, read [Your file server](/projects/file-server.md).

## How it works

* Cogram Connector runs on a Windows server in your network. It reads your shares with a service account that you select. Cogram never receives file-server credentials.
* Cogram Connector builds a search index locally, on that host. The index and your files stay in your network.
* Cogram Connector makes one outbound HTTPS connection (port 443) to Cogram. There are no inbound connections. You do not open firewall ports.
* Only the data that a user asks for goes to Cogram: search results, and the content of the files that they open. Diagnostic error reports are a separate opt-in.
* Permissions come from the file server. You map each Cogram user to their Active Directory account on the **Identity & access** page. Cogram Connector returns only the files that this account can read, under both the share permissions and the NTFS permissions. A user without a mapped AD account sees no files.
* Cogram Connector is read-only unless you enable uploads at install time. Refer to [Allowing uploads](#allowing-uploads-optional).

## Prerequisites

* You are a Cogram organization admin.
* You have a domain-joined Windows Server that can reach your file shares. The file server itself is a good host.
* You have a service account (a regular domain account or a gMSA) with read access to the shares.
* The server can make outbound HTTPS connections (port 443) to `app.cogram.com`.
* Your Cogram users sign in with the same email address that is on their AD account (the `mail` or `userPrincipalName` attribute). Cogram uses this address to suggest the mapping for each user. You confirm the suggestions.

## Set up Cogram Connector

1. Go to [Organization Settings → Integrations → File Server Connectors](https://app.cogram.com/dashboard/settings/admin/integrations#connectors) and select **Cogram Connector – File Server**.
2. Enter a name (for example "Engineering file server") and an optional description. Select **Create connector**.
3. Copy the **enrollment token** and store it in a safe place. Cogram shows the token only one time. If you lose the token, delete the connector in Cogram and create a new one.
4. Select **Download connector**. Copy the ZIP file to your Windows server.
5. Unzip the file. Open an elevated PowerShell window in the unzipped folder. Run the install command from the enrollment page. The token and the backend URL are pre-filled. Replace the share paths and the service account with your own values:

   ```powershell
   .\install.ps1 `
     -Token "cn_xxx.secret" `
     -BackendUrl "https://app.cogram.com" `
     -SharePaths "\\fs01\Engineering;\\fs01\Projects" `
     -ServiceAccount "DOMAIN\svc-cogram"
   ```
6. The script registers and starts the `CogramConnector` Windows service. The service starts to index your shares immediately.

### What good looks like

Go back to [Organization Settings → Integrations → File Server Connectors](https://app.cogram.com/dashboard/settings/admin/integrations#connectors). Cogram Connector shows **Connected** and **Building index…**. The list of crawled shares fills with file counts and sizes. When indexing completes, the status shows **Index ready**. The first pass on a large file server can take a while. Later passes read only the changed files.

## Map users to AD accounts

Cogram Connector runs every request as the AD account of the Cogram user who makes it. No user has access until you map them. Open **Identity & access** on the Cogram Connector page:

1. Each Cogram user shows one of five states. **Suggested**: exactly one AD account carries the user's email address. **Mapped**: you confirmed an account. **Multiple matches**: more than one AD account carries the email address. **No match**: no AD account carries it. **Account in use**: the matching account is already mapped to another user, or carries two users' addresses. Decide who gets it.
2. Select **Map all suggested** to confirm every suggestion in one step. Or select **Map** next to one user.
3. For a user with **Multiple matches** or **No match**, select **Choose** and pick the account from the directory. You can search by name, login, or email address.
4. To change a mapping, select **Change**. To remove one, select **Unmap**. An unmapped user sees no files.

A mapping is per connector. If you delete the connector and create a new one, map the users again. An AD account that is disabled cannot be mapped. If a mapped account is later disabled or deleted, the user shows **Account disabled** or **Account missing** and gets no files.

Project exports run as the user who saved the export settings for that project. If that user is not mapped, the export waits, and the project shows **Run-as user not mapped** on the File server export page.

## Verify what users can see

The Cogram Connector page has three checks. Use them before you roll out to your team:

* **Browse files** opens the file server as any user in your organization. Use it to make sure that a user sees only the folders and files that their own account can open.
* **Identity & access** shows each user's mapping and lets you change it.
* **Index health** shows how much of the server the search can read. Files without extracted text are findable by name only.

## Allowing uploads (optional)

By default, Cogram Connector never writes to your server. To let users upload files from the Files page, three conditions must all be true:

1. You installed Cogram Connector with the `-AllowWrites` switch.
2. The service account has write access to the share: Modify on the folder tree, and Change in the share permissions. Share permissions are separate from NTFS permissions. The stricter of the two applies.
3. The user who uploads the file has write access to the destination folder. Cogram Connector checks that user's access, not its own.

An upload never replaces an existing file. One upload has a limit of 2 GB. The service account owns the uploaded files on disk. Cogram records which user uploaded each file.

The same three conditions govern project export, where Cogram copies a project's completed items into a folder you choose. Project owners and leads link a project to a folder under the project's **Overview → Settings → File server export**. You can link any project, and see every mapping, under [Organization Settings → Integrations → File server export](https://app.cogram.com/dashboard/settings/admin/integrations#file-export). Exports run as the person who last saved those settings, so that account needs write access to the folder. Cogram creates one subfolder per type of item, and never overwrites a file. See [Your file server](/projects/file-server.md) for what each type writes.

## Updates

Cogram Connector keeps itself up to date. It downloads the version that Cogram recommends and verifies the code signature. A scheduled task on the host applies the update. If the new version does not start, the task restores the old version. You do not need to plan maintenance for updates.

To update manually, download the new version from the Cogram Connector page. Then run `update.ps1` from the unzipped folder on the host. The token, the configuration, and the service registration stay unchanged. The page shows an **Update available** or **Update required** badge when the installed version is behind.

To remove Cogram Connector, run `uninstall.ps1` on the host. Then delete the connector in Cogram. Add `-Purge` to also delete the local search index.

## Troubleshooting

**Symptom:** Cogram shows the connector as **Offline**. **Likely cause:** The `CogramConnector` service is stopped, or the host lost its outbound connection. **Fix:** On the host, check the service in `services.msc` and start it. Your files are not affected while Cogram Connector is offline.

**Symptom:** A user sees "Your account is not mapped yet". **Likely cause:** No admin has mapped this user to an AD account. **Fix:** Open **Identity & access** on the Cogram Connector page and map the user.

**Symptom:** A mapped user sees no files, or folders that they expect are empty. **Likely cause:** The mapped AD account has no read access on the server, or you mapped the wrong account. **Fix:** Check the account under **Identity & access**. Permissions come from the file server. Grant access there, not in Cogram.

**Symptom:** You lost the enrollment token. **Likely cause:** Cogram shows the token only one time, at creation. **Fix:** Delete the connector in Cogram and create a new one. Run the installer again with the new token.

**Symptom:** An upload fails with "You do not have permission to add files to this folder." **Likely cause:** One of the three write conditions is not met. A missing Change permission on the share is a frequent cause. **Fix:** Check all three conditions under [Allowing uploads](#allowing-uploads-optional).

## Next steps

* [Your file server](/projects/file-server.md): what your team can do with the connected shares.
* [Agent](/agent/agent.md) can search and read these files when someone asks it a question.
* [Privacy and confidentiality](/get-started/privacy-and-confidentiality.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cogram.com/integrations/connecting-your-file-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.