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 page, search file names and file content, and preview files. Agent 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.

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.

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 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:

   .\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. 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. 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 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.

Next steps

• Your file server: what your team can do with the connected shares.

• Agent can search and read these files when someone asks it a question.

• Privacy and confidentiality