# Overview If you run complex, multi-stakeholder projects, as an architect, engineer, consultant, or builder, Cogram keeps your project information organized across every tool you use and every site visit. ## Capabilities Cogram can: * draft professional minutes in virtual meetings (Teams, Zoom, Google), using your custom templates * automatically file emails from Outlook into project directories * [create field reports](/field/field-reports) via voice dictation and photos with Cogram's mobile field management app * draft project reports or accelerate e-discovery across project meetings, emails, and field reports * summarize RFPs and draft full-scale project proposals grounded in your past experience ## Get started Continue to our [Quickstart Guide](/quickstart) below. # Quickstart Create a Cogram account, run through setup, and use Cogram in a first in-person or virtual meeting to draft minutes. ## Before you start Make sure your company has an active Cogram trial or subscription. Contact if you're new to Cogram, and we'll get you set up with a free trial. ## Getting Started ### 1. Create your Cogram account [Register your account](https://app.cogram.com/auth/register) using your business email. Your email should match the email that you use to schedule meetings in your Outlook or Google calendar. Signups with personal emails are not supported. After clicking "Sign Up", Cogram will send you a confirmation email to verify your email. Click on the link in the email to confirm your account and sign in. If you do not receive a confirmation email within a few minutes after registering, contact . ### 2. Connect your calendar After signing in the first time, enter your first and last name and click continue. Cogram will then prompt you to connect a Google or Outlook calendar. You can also use the drop-down to enable Cogram to automatically join your meetings for note-taking. Select the calendar you use and sign in to your calendar to confirm the integration. If you need IT permissions to connect a calendar, follow these [instructions](/meetings/authorizing-calendar-integration). ### 3. Go through Cogram's Quickstart Tutorial Follow the on-screen tooltips to learn how to invite Cogram for note-taking in a virtual meeting and how to view Cogram's notes after a meeting. ### 4. Invite Cogram to a first virtual meeting To invite Cogram to a virtual meeting for note-taking, open **Meetings** in the left sidebar and go to the [Invite Cogram page](https://app.cogram.com/dashboard/meetings/schedule). Click on any blue calendar event and toggle "Attend". When a meeting starts, Cogram joins and transcribes the conversation. When your meeting ends, Cogram creates a meeting summary, bullet points, and action items and sends them to your email inbox. You can also invite Cogram to meetings by adding to any event in your Outlook or Google calendar, or by forwarding a meeting invite to that email. ### 5. Export Cogram's meeting minutes To view Cogram's notes after a meeting, open **Meetings** in the left sidebar and head to Cogram's [Meetings page](https://app.cogram.com/dashboard/meetings). Open a meeting to view Cogram's Executive Summary, meeting attendees and invitees, a detailed Summary, structured Bullet Point notes, and action items. Click "Download" at the top right hand side to select a Word (.docx) template to export Cogram's notes into. ### 6. Download Cogram's mobile app for in-person/on-site meetings To record in-person meetings and create field reports on site visits, head to the iOS App Store or Google Play store and search for "Cogram". You can also open the **Help** menu at the bottom of the left sidebar and select "Get the mobile app" to scan a download QR code. Sign in with your account and you are ready to [record in-person meetings](/meetings/in-person-meetings) and [create field reports](/field/field-reports) with observations, photos, and drawing pins. See [Cogram on your phone](/get-started/mobile-app) to get oriented. *** \ To get help as you're getting started with Cogram, reach out to . We'll respond within 24 hours. # Signing up and signing in Follow these instructions to get set up when you're just starting out with Cogram. ## Signing Up If you don't yet have a Cogram account, create an account [on Cogram's Sign Up page](https://app.cogram.com/auth/register/).
The Cogram sign up page with email, password, and confirm password fields, plus Google and Microsoft sign-up options

The sign up page

{% hint style="warning" %} Sign up with the same email you use in your calendar to schedule and join meetings. Personal email addresses (Gmail, Yahoo, etc.) aren't supported, so use your work email. {% endhint %} After clicking "Sign Up", Cogram will send you a confirmation email to verify your email. Click on the link in the email to confirm your account. If you do not receive a confirmation email within a few minutes after registering, contact . Head to the [Sign In](https://app.cogram.com/auth/login) page to log in. ## Signing In
The Cogram sign in page with email and password fields, plus Google, Microsoft, and SSO sign-in options

The sign in page

To sign in, enter the email and password you used to sign up. On your first login, Cogram walks you through basic setup and a short tutorial. Follow the on-screen tooltips to learn how to invite Cogram for note-taking in a virtual meeting and how to view Cogram's notes after a meeting. # Configuring your Cogram account Set your Cogram basics, like your notetaker's name and meeting language. ## Changing your notetaker name Open the avatar menu in the bottom of the left sidebar and head to [**Account Settings → Meetings**](https://app.cogram.com/dashboard/settings/account-settings/meetings) to change the name that Cogram displays in Zoom, Microsoft Teams, or Google meetings.

Configuring your notetaker's name

## Changing meeting language In [**Account Settings → Meetings**](https://app.cogram.com/dashboard/settings/account-settings/meetings) use the "Transcription language" drop-down to set the language or dialect that you speak in meetings. # Cogram on your phone Install the Cogram mobile app, sign in, and find your way around the five tabs you use on site. The Cogram mobile app is built for site visits: record in-person meetings, capture observations with photos, create field reports, and carry your drawings with you, even without signal. This page gets you signed in and oriented. ## Installing the app Search for "Cogram" in the App Store (iPhone and iPad) or Google Play Store (Android) and install it. ## Signing in Sign in with the same account you use on the web: * With your work email and password, tap **Login** after entering them. Turn on **Remember me** to stay signed in. * If your firm uses Single Sign-On, enter your enterprise email on the SSO screen and tap **Sign in**. You are taken to your firm's usual login. **Other sign-in options** switches between the two screens. {% hint style="info" %} If your firm uses Single Sign-On, always sign in through it. Signing in with a password on a Single Sign-On organization can leave the app unable to load your license. {% endhint %} ## Finding your way around The app has five tabs along the bottom: * **Home**: the three big actions, **Start Field Report**, **Quick Observation**, and **Record Meeting**, plus your project picker. * **Reports**: your field reports, including drafts you can resume. * **Observations**: everything captured on site, with search and filters. * **Drawings**: your project drawings, ready to download for offline use. * **Meetings**: your recorded in-person meetings. Pick a project on the Home tab and every other tab scopes to it. Pick **All Projects** to see everything. You can also create a new project right from the picker when you are starting work on a new site.
The Home tab with the Start Field Report, Quick Observation, and Record Meeting actions, the project picker, and the five tabs along the bottom

The Home tab and the five tabs along the bottom

## If a tab says it isn't available A tab showing "\[Module] isn't available" means your account does not have a seat for that module. Tap **Ask my admin** to request one from your Cogram admin. If your whole team lacks the module, talk to your Cogram contact. ## Settings Tap your profile to open Settings: * **Save photos to camera roll**: also keep a copy of captured photos in your phone's photo library. * **Check for updates**: fetch the latest app version. * **Delete local data**: clear everything stored on the phone. Only use this when nothing shows **Awaiting Upload**, or you will lose unsynced work. * **Log out**: if anything is still uploading, the app warns you first. Unsynced items stay on the device and finish uploading after you sign back in. ## Related * [Create a field report on site](/field/field-reports): the main field workflow, start to finish. * [Capture observations](/field/observations): notes, photos, and drawing pins. * [Working offline](/field/working-offline): what happens when you have no signal. # Privacy and confidentiality Cogram is committed to safeguarding the confidentiality of meetings and user privacy. ## **What data does Cogram process and store?** * When you use Cogram in a meeting, the meeting audio is temporarily stored by Cogram for transcription. * No audio recording is stored after transcription completes. * No video recording is stored. Cogram's meeting transcript is used to create a meeting summary, bullet-point notes, and a list of action items. Transcripts and meeting notes are stored after meetings. Optionally, organizations can configure Cogram so that no transcripts are stored after notes and summaries are generated. To do so, reach out to . ## **Who can view Cogram's meeting notes?** * By default, Cogram's meeting notes are only visible to the Cogram user that invited Cogram to the meeting. * Notes are never automatically shared with meeting participants or anyone else. ## **Should I obtain consent from meeting participants when using Cogram?** Yes. Even though Cogram stores no audio or video after transcription, you're responsible for getting participants' consent before using it. {% hint style="info" %} **You can use the following overview to describe what Cogram does:** Cogram is a software application that transcribes, summarizes, and takes notes in meetings. No audio or video recordings are stored after a meeting. {% endhint %} Alternatively, Cogram's [Meeting Privacy](https://www.cogram.com/meeting-privacy) page provides a good overview. ## **Can I customize data retention?** Yes. Please reach out to to configure a custom data retention timeline for your account. ## **What security measures does Cogram take?** For a detailed overview of Cogram's security measures please visit Cogram's [Security Overview](https://www.cogram.com/security). # Getting help For help with Cogram, or to share feedback, please reach out to or use your company's dedicated communications channel with the Cogram support team. We'll get back to you within 24 hours. You can also open the **Help** menu at the bottom of the left sidebar to reach Support, the User Guide, the Setup Guide, and instructions for getting the mobile app. # Projects If you're using Cogram for client or project work, Cogram's Projects feature is a great way to organize minutes, emails, and reports, and to collaborate with coworkers. To get started with Projects, head to Cogram's [Projects page](https://app.cogram.com/dashboard/projects/). ## Creating a new Project 1. Go to the [Projects page](https://app.cogram.com/dashboard/projects/) and click **New Project**. 2. In **Basics**, enter a project name, client, address, and project number. 3. In **Details**, add a description. If email filing is enabled, this helps Cogram match incoming emails to the project. 4. In **Members**, invite team members by email (individually or in bulk) and assign roles. You can also assign groups. This step is optional; you can always add members later from project settings. 5. In **Review**, confirm the details and click **Create Project**.
The project wizard Basics step showing the Start from template dropdown, Project Number, Project Name, Client, and Address fields

The project wizard, with the Start from template picker at the top

## Setting automatic filing rules for meetings and emails ### Automatically add future meetings to a project Next, Cogram will prompt you to set up rules to automatically add future meetings to the project, based on keywords in the meeting title, or meeting invitees. **Based on invitees** For example, if you're working with a client on a project, add that client's email domain under **Add Meetings based on Invitees**. Any meeting with an invitee that matches the specified domain will automatically be added to the project. **Based on Keywords in the Meeting Title** Similarly, you can specify a project name or keyword, so that any future meeting that contains the keyword in the meeting title is automatically assigned to the project. ### **Automatically add emails to a project** Next, Cogram will prompt you to set up rules to automatically add future Email Threads to the project, based on keywords in the subject line, or recipients. Click **Save** to finish. Your project is ready. Next, invite members or file your first meeting. ## Inviting Members You can invite coworkers during project creation (the **Members** step) or at any time afterward. **During project creation**: In the **Members** step, search by email to invite individuals or switch to **Add Multiple** to paste a list of emails. You can also assign groups in the **Group Access** section. All invites are sent after the project is created. **After project creation**: Open the project from the [Projects page](https://app.cogram.com/dashboard/projects/), go to the **Access** tab (or **Settings > Members and Groups**), and search by email to invite individuals. Assign each person a role (Owner, Lead, Member, or Viewer). See [Project Roles](https://docs.cogram.com/administration/project-roles) for what each role can do. **Assigning a group**: Select a [group](/organization-administration/groups) in the **Group Access** section (available during creation or under the project's **Access** tab / **Settings**). All group members get the role the group was given: **Lead**, **Member**, or **Viewer** (Lead only if your organization has that role turned on). Group-assigned users are shown in a **Via groups** section and their access is managed through the group. See [Project Roles](https://docs.cogram.com/administration/project-roles#group-access) for details. ## Project discoverability When creating a project or under the project's **Settings**, you can make the project **discoverable**. **Discoverable projects** are listed in the organization-wide project directory. Other organization members can see them in the project list. Non-members can request access (approved by project owners, org admins, or org owners). Org admins and org owners can open and edit discoverable projects directly without requesting access. **Hidden projects** do not appear in the org project directory; only people who are already members or who have a direct link can find them. > **A note on naming:** a project that isn't discoverable is called **Hidden** throughout Cogram: in [Project templates](/projects/project-templates), in the org admin discoverability tools, and in Project Settings. It means "not listed in the organization-wide project directory." ### Browsing discoverable projects To browse projects shared across your organization, go to the [Projects page](https://app.cogram.com/dashboard/projects/) and select the **Organization Projects** tab. This tab lists all discoverable projects in your organization, including projects you are not yet a member of. From here you can request access to any project. ### After you request access While your request is pending, the button shows **Cancel request**; select it to withdraw the request (you can ask again later). The outcome depends on how the request is resolved: * **Approved**: the button changes to **Access granted** and the project opens for you. * **Declined**: you get an email letting you know, and the button returns to **Request Access** so you can ask again if you still need it. A request you never hear back on expires on its own after 7 days, with no email either way, and the button returns to **Request Access**. ### Org-wide discoverability settings Organization admins and owners can set a default discoverability policy and control whether project owners can override it. See [Project Management Permissions](https://docs.cogram.com/administration/project-management-permissions#project-discoverability) for details. ## Project types You can categorize projects by type, for example Residential, Commercial, or Infrastructure. Assign a type during project creation or from the project list. Types are defined by org admins under [Organization Settings > Projects > Project Types](https://app.cogram.com/dashboard/settings/admin/projects/project-types). See [Project Types](https://docs.cogram.com/administration/project-types) for full details. ## Manually adding meetings to a project You can manually file meetings into a project by opening the project and clicking the "Add" button, or by clicking "Add to Project" from any meeting. When you move a recurring meeting to a project and choose to include the whole series, Cogram remembers that choice: future occurrences of the series are filed to the same project automatically as they appear in your calendar. Removing the series from the project clears this again. *** ## Using Agent with Projects Open a project and click **Agent** (top right) to start a session with full context on the project's meeting minutes and emails. Use it to draft reports, status updates, ask questions, or list open action items. # Project chat Talk to your project team inside the project. Channels keep the conversation organized, @mentions get someone's attention, and files shared in chat can become project Documents. {% hint style="info" %} Project Chat is in beta and is being rolled out gradually, so it is not yet available to every organization. If you would like to use it, write to to join the beta. Once your organization has it, chat is still off by default and is turned on project by project — see [Setting up project chat](/projects/project-chat-setup). {% endhint %} Project Chat is a conversation space that lives inside a project, next to its meetings, reports, and documents. Use it for the day-to-day back-and-forth that doesn't belong in an email thread: a quick question about a detail, a photo from site, a heads-up before an OAC meeting. Everyone with access to the project sees the same channels and the same history. Project Viewers can read everything but cannot post. ## Before you start * Chat must be turned on for the project. If you don't see a **Chat** entry in the project sidebar, ask a project owner or an organization admin to turn it on. See [Setting up project chat](/projects/project-chat-setup). * Chat is part of the web app at [app.cogram.com](https://app.cogram.com/dashboard/projects/). It is not part of the Cogram mobile app. ## Opening chat 1. Open your project from the [Projects page](https://app.cogram.com/dashboard/projects/). 2. Select **Chat** in the project sidebar. The chat pane has a list of channels down the left and the selected channel's conversation on the right. The channel name (for example `#general`) appears at the top, with the search box beside it.
The Chat pane of a project: the channel list on the left, the #general conversation open with messages, reactions, and an attachment, and the search box in the header.

The Chat pane: channels on the left, the conversation on the right

Every chat-enabled project starts with a `#general` channel. A project owner can add more channels for separate conversations, for example `#site-updates` or `#curtain-wall`. See [Setting up project chat](/projects/project-chat-setup). ## Posting a message 1. Select a channel. 2. Type in the box at the bottom (**Message #channel-name**). 3. Press **Enter** to send, or select **Send**. Press **Shift + Enter** for a line break within the same message. While a colleague is composing, a line above the box tells you so ("Kate is typing…", or "Several people are typing…" once four or more people are at it). An empty channel shows "No messages yet. Start the conversation." ### Formatting Messages accept a small amount of Markdown: | To get | Type | | ------------- | ----------------------------------------------------------------- | | **Bold** | `**bold**` | | *Italic* | `*italic*` | | `Inline code` | `` `code` `` | | A code block | Three backticks on their own line, the code, then three backticks | | A link | `[label](https://example.com)` | Web addresses and email addresses you type are turned into links automatically. Anything else, such as a `#` heading or a `|` table, stays exactly as you typed it, because chat is prose. ### Emoji Type a colon followed by at least two letters, for example `:sweat`, and a list of matching emoji opens. Use the arrow keys to choose, then **Enter** or **Tab** to insert; **Esc** dismisses the list. Typing a complete shortcode such as `:tada:` converts it in place without the list. You can also select the **Add emoji** button under the message box to browse or search the full set. ### Mentioning someone Type `@`, or select the **Mention someone** button under the message box, and pick the person from the list that opens. Only a name picked from the list counts as a mention: typing `@Kate` by hand is plain text and notifies nobody. Anyone with access to the project can be mentioned, including Viewers and colleagues from another firm who were given access to the project. Mentioning yourself does not notify you. A mention reaches the person in two places: * **Notification bell**: a notification that opens the message when selected. See [Notification bell](/your-account/notifications). * **Email**: on by default. Mention emails are batched rather than sent one per mention, and are skipped entirely if you have already read the channel in the meantime. Turn the email off under [Account Settings > Notifications](https://app.cogram.com/dashboard/settings/account-settings/notifications), in the **Mentions** category. See [Notification preferences](/your-account/notifications-1). Reading the channel clears your mention notifications for it. ### Pointing to another channel Type `#`, or select the **Reference a channel** button under the message box, and pick a channel from the list. In the posted message the reference becomes a chip that opens that channel when selected — handy for "let's take this to `#site-updates`". Unlike mentions, a channel name typed out by hand works too, as long as it matches one of the project's channels. A channel reference notifies nobody; it is a signpost, not a mention. ## Reacting to a message 1. Hover over the message and select **Add reaction**. 2. Pick an emoji, or search for one by name. Your most recently used emoji appear under **Recently used** at the top of the picker. Reactions gather into chips under the message with a count. Select an existing chip to add your own reaction to it, and select it again to take yours away; the chip disappears when the last person removes theirs. Chips you are part of are outlined. Hover a chip to see who reacted. ## Editing and deleting your messages Hovering over your own message shows a small toolbar with **Add reaction**, **Edit**, and **Delete**: * **Edit** opens the message for editing in place. Select **Save** to confirm. Edited messages are marked "(edited)"; the previous wording is not kept. * **Delete** removes the message from the channel. Deletion cannot be undone. If the message carried files, the confirmation says how many go with it. You can only edit your own messages. Project owners and organization admins or owners can delete anyone's message. ## Sharing files Attach files to a message with the paperclip button (**Attach files**), or drag them onto the chat pane and drop them. * Up to **10 files** per message. * Up to **100 MB** per file. A file that is too large is left behind with a note under the box, and the rest still attach. The same happens when you pick more than ten files at once. Images and PDFs show a preview under the message. Select the preview, or the attachment itself, to open the file full size — PDFs open in a viewer with pages and zoom, and Word (.docx) and text files open as a readable preview. For other file types, selecting the attachment downloads it. **Download** is always available in the attachment's actions menu. ### Adding a chat file to project Documents A file shared in chat stays in chat unless you promote it. Promoting puts it in the project's **Documents** list without making a second copy. 1. Select the actions button beside the attachment (**Actions for *****filename***). 2. Select **Add to project documents**. The attachment then carries an **In documents** badge, and the file appears in the project's Documents list with a chat icon next to its filename. Hovering that icon shows **View in #channel**; selecting it jumps to the original message. To reverse this, select **Remove from project documents** on the same menu. The file stays in chat; only the entry in Documents goes away.
A chat message with two attached files. The actions menu of one file is open, showing Download, Add to project documents, and Delete file; the other file carries the In documents badge.

The attachment's actions menu; the file already promoted carries the In documents badge

### Deleting a file, and what happens to the document You can delete a single file from your own message with **Delete file**, without deleting the message. If the file is also a project document, Cogram asks what should happen to the document. Each promoted file gets its own choice: | Choice | Result | | ---------------------------------- | --------------------------------------------------------------------------------------- | | **Keep as document** (the default) | The file leaves chat and stays in the project's Documents list as an ordinary document. | | **Delete the document too** | The file leaves both chat and Documents. | The same question appears when you delete a whole message that carries promoted files: the dialog lists each promoted file with its own choice, so you can keep one and delete another. Files that were never promoted are simply deleted with the message. Because **Keep as document** is preselected, confirming without changing anything never removes a document. The reverse also holds: deleting a promoted file from the Documents list does not touch the message in chat, and the file remains downloadable there. ## Keeping up with what's new Cogram tracks where you left off in each channel, so you don't have to. * The channel list shows a **count** beside any channel with messages you haven't seen. * The **Chat** entry in the project sidebar shows a **dot** when any channel of the project has something new. * The project's **Overview** page has a **Chat** section that counts your unread messages, with **Open chat →** taking you straight in. * Opening a channel with unread messages takes you to the **New messages** line rather than to the bottom, so you pick up where you stopped. Messages count as read as they scroll into view, so a long backlog is not marked read just because you opened the channel. Posting a message marks the channel read up to your own message. To go further back in a channel, select **Load earlier messages** at the top of the conversation. History is kept in full.
A channel opened at the New messages divider, with unread counts beside the channels in the channel list.

Unread counts beside the channels, and the New messages divider in the conversation

## Searching the conversation 1. Select the search box in the channel header, or press **/** to jump to it. 2. Type at least two characters. Results appear below the box, each showing the channel, the author, when it was posted, and a snippet with your search term highlighted. Select a result to jump to that message in its channel; the message is briefly tinted so you can spot it. Search covers every active channel in the project, not just the one you have open. Archived channels are not searched. Select **Load more** for further results, or press **Esc** to close the results. If nothing matches, the panel says "No messages found." ## Who can do what | | Viewer | Member | Owner | Org admin or owner | | ---------------------------------------------- | :----: | :----: | :---: | :----------------: | | Read channels, history, and search | ✓ | ✓ | ✓ | ✓ | | Be mentioned and notified | ✓ | ✓ | ✓ | ✓ | | Post messages | | ✓ | ✓ | ✓ | | React to messages | | ✓ | ✓ | ✓ | | Attach files | | ✓ | ✓ | ✓ | | Add files to project Documents, or remove them | | ✓ | ✓ | ✓ | | Edit own messages | | ✓ | ✓ | ✓ | | Delete own messages | | ✓ | ✓ | ✓ | | Delete anyone's message | | | ✓ | ✓ | | Create, rename, or archive channels | | | ✓ | ✓ | | Turn chat on or off for the project | | | ✓ | ✓ | Viewers see the conversation, the files, and the search box, but no message box and no reaction buttons. See [Project roles](/projects/project-roles). ### Colleagues from another firm On a project shared with another organization, guests take part according to the project role they were granted: a guest with Member access posts, reacts, and attaches files; a guest with Viewer access reads. Turning chat on or off, and managing channels, stay with the project's own owners and their organization's admins. An admin at the guest firm gets no extra powers on your project. To bring someone from another firm into the conversation, project owners see an **Invite a collaborator** button at the bottom of the channel list. See [Inviting external collaborators](/projects/inviting-external-collaborators). ## Troubleshooting **There is no Chat entry in the project sidebar** * Likely cause: chat has not been turned on for that project, or the project you're looking at isn't the one you think it is. * Fix: confirm the project in the sidebar header, then ask a project owner or organization admin to turn chat on. See [Setting up project chat](/projects/project-chat-setup). **You typed `@Kate` but Kate wasn't notified** * Likely cause: the name was typed rather than picked from the list, so it is plain text. * Fix: delete it, type `@`, and select the person from the list that opens. **You can read the channel but there is no message box** * Likely cause: your role on the project is Viewer, which is read-only. * Fix: ask a project owner to change your role. See [Project roles](/projects/project-roles). **A channel you used before is gone** * Likely cause: it was archived. Archived channels leave the chat pane and are excluded from search; nothing is deleted. * Fix: a project owner or organization admin can unarchive it from project settings. See [Setting up project chat](/projects/project-chat-setup). **A file you shared is no longer in chat, but colleagues still find it in Documents** * Likely cause: the file had been added to project Documents, and whoever deleted it chose **Keep as document**. * Fix: nothing to do; that is the intended outcome. Delete the document from the Documents list if it should be gone entirely. **A search finds nothing you know was posted** * Likely cause: the message is in an archived channel, or was deleted. * Fix: ask a project owner to unarchive the channel, then search again. **Chat doesn't appear in the mobile app** * Chat is a web-app feature. Open the project at [app.cogram.com](https://app.cogram.com/dashboard/projects/) from a browser. ## Next steps * [Setting up project chat](/projects/project-chat-setup): turn chat on and manage channels * [Notification bell](/your-account/notifications): what arrives in the bell and how to act on it * [Notification preferences](/your-account/notifications-1): turn mention emails on or off * [Project roles](/projects/project-roles): what Owners, Members, and Viewers can do # Directory Manage the people and companies you work with (clients, consultants, subcontractors) in one place. Use them as recipients on transmittals, RFIs, submittals, and external shares. The Directory is your organization's shared address book of external **Contacts** (people) and **Companies**. Add someone once, then reuse them as a recipient anywhere in Cogram, without re-typing their name and email. The Directory lives at [Directory](https://app.cogram.com/dashboard/directory). It has two tabs: **Contacts** and **Companies**. ## Contacts Open [Directory > Contacts](https://app.cogram.com/dashboard/directory/contacts) to see everyone you've added. ### Adding a contact 1. Go to [Directory > Contacts](https://app.cogram.com/dashboard/directory/contacts) and click **New contact**. 2. Enter at minimum a **primary email address**. Add first name, last name, title, phone, and address as available. 3. Optionally pick a **Company**: this links the contact to a Company record so you can see all that company's people in one view. 4. Click **Save**.
The New contact dialog with fields for first name, last name, email, title, discipline, phone numbers, company, and address

The New contact dialog

Each email address can appear at most once in your organization's Directory. ### Searching and filtering Use the search box at the top of the Contacts list to find a contact by name, email, or company. Toggle **Show archived** to include archived contacts in the results. ### Editing a contact Click any contact row to open the contact detail page. From there you can: * Update name, email, title, phone, address. * Reassign or clear the Company. * Change the **Source** — where the contact came from, for example an import run. Choose one of the sources your organization already uses. Contacts that Cogram syncs from your organization's members show "Automatic" and you cannot change them. * See linked projects and recent shares. To correct the source of many contacts at once, select them in the Contacts list and click **Set source**. Cogram skips any selected contact that it syncs from a member. ### Archiving Archive a contact you no longer collaborate with by clicking the archive icon on the contact row, or from the contact detail page. Archived contacts: * Disappear from the default Contacts list and the recipient picker. * Are still visible when **Show archived** is toggled on. Archived contacts stay viewable with **Show archived** on. Restoring an archived contact from the UI isn't available in this release. ## Companies Open [Directory > Companies](https://app.cogram.com/dashboard/directory/companies) to see the firms you work with: clients, GCs, subs, consultants, and so on. ### Adding a company 1. Go to [Directory > Companies](https://app.cogram.com/dashboard/directory/companies) and click **New company**. 2. Enter the **Name**. 3. Optionally fill in: * **Aliases**: alternative names you'll use to find this company. * **Email domains**: the domains the company's employees use (e.g., `acme.com`). * **Types**: multi-select from Client, GC, Subcontractor, Consultant, Owner, and so on. * **Trades** and **Disciplines**: multi-select. * Website, phone, address. 4. Click **Save**.
The New company dialog with fields for name, website, phone, email domains, company type, disciplines, and address

The New company dialog

### Linking contacts to companies Open any contact and set its **Company** field. The contact will then appear under the company's detail page. ### Archiving Archive a company from the company list (archive icon) or from the company detail page. Linked contacts remain in the Directory; their Company field stays set but the company won't appear in new searches. ## Recipient picker Anywhere in Cogram that needs an external recipient (sharing a meeting, composing a transmittal, RFI, or submittal) uses the same picker. * Start typing a name or email. The picker searches your Directory. * Pick from suggestions. Selected recipients appear as chips. Click the **x** on a chip to remove. * If you type a new email that doesn't match any contact, the picker offers **Add as new contact**: pick that to create the contact inline. The new contact lands in your Directory immediately. ## Where contacts are used * **Transmittals**: `Recipient` field uses the picker. The recipient name and company are read from the contact, not re-typed per transmittal. * **RFIs and submittals**: same picker on the recipient field. ## Adding missing people to a project directory with Agent Someone you pick as a recipient on an RFI, submittal, or transmittal is added to that project's directory automatically. Items created before Cogram did this, and contacts brought in by an import, can leave a person on the item but missing from the directory. [Agent](https://app.cogram.com/dashboard/agent) can find and add them. **Prerequisites** * Any member can ask for the list. * Adding the people requires an organization admin or owner. **Steps** 1. Open [Agent](https://app.cogram.com/dashboard/agent) and ask, for example, "Who is on the Riverside Library RFIs and submittals but missing from its project directory?" For the whole organization, ask "Which project directories are missing people?" 2. Review the list. Agent shows each person's email and the project they belong on. 3. Tell Agent which people to add, or ask it to add all of them. Agent reports what it added. **Expected result** Each added person appears in the project's directory. If their company was not yet on the project, it is added too. **What Agent does not add** * Members of your own organization. Colleagues reach a project through project access, not the directory. * Archived contacts. * Automated senders, such as no-reply addresses. * People on archived projects or personal workspaces. Agent only adds a missing link. It never removes or reassigns anyone, so asking again is safe. ## Troubleshooting **Symptom**: "This email is already in your Directory." **Likely cause**: Each email is unique per organization. Someone already added that contact. **Fix**: Search for the email in [Contacts](https://app.cogram.com/dashboard/directory/contacts) and edit the existing record instead of creating a new one. **Symptom**: A contact I just archived still appears in the recipient picker. **Likely cause**: A cached copy of the picker was open when you archived. **Fix**: Close and reopen the picker, or refresh the page. **Symptom**: I can't find a contact I added last week. **Likely cause**: Either the Show archived filter is off, or the contact was added under a different organization. **Fix**: Toggle **Show archived** on. If still missing, check that you're signed in to the correct organization (open the avatar menu at the bottom of the left sidebar). # External collaborators You were invited to Cogram by someone outside your organization. Learn what you'll see, what you can do, and how to grow into a full Cogram account. Someone outside your organization invited you into Cogram. This page is for you. There are two kinds of invitation: * **A shared project** — a firm invited you to collaborate inside one of their projects (its chat, meetings, and documents). See [Working in a shared project](#working-in-a-shared-project). * **A shared asset** — a firm sent you a single meeting, transmittal, RFI, or submittal. The rest of this page covers this flow. ## What just happened A collaborator at another firm used Cogram to send you something. To preserve your control over your own data, Cogram created a **new, separate account for your email address** rather than dropping you into their organization. Your account is yours; their account is theirs; the share lets you receive their asset into yours. ## What you'll see when you sign in Your account starts in **invitee** mode, which has a focused, read-receive-respond experience: * **Inbox**: the share that was sent to you, plus any future shares to the same email address. * **Directory**: your address book of Contacts and Companies. Empty by default; add people as you collaborate. * **Account Settings**: name, password, two-factor authentication, notifications. The full Cogram experience (Field Reports, Email Management, Workflows, Templates, organization-wide settings) is **not** part of invitee mode. Invitee mode is a scoped surface: you can review and accept incoming shares without taking on the full setup of an AEC project record. ## Accepting your first share 1. Sign in via the link in the notification email or at [app.cogram.com](https://app.cogram.com/auth/login). 2. Open [Contract Admin > Inbox](https://app.cogram.com/dashboard/correspondence/inbox). The pending share is at the top. 3. Click the share to open it. 4. Pick the project to accept the share into. (If your account has no project yet, create one first from the Projects page, then accept.) 5. Click **Accept**. A copy of the asset's key details is created in your project. From then on it's yours: edit, comment, file follow-up emails, generate reports. Attachments and source documents are not copied yet; ask the sender to transmit files directly if you need them. ## Previewing without signing up If the sender enabled the **preview link**, the notification email contains a link you can open without signing up. The preview is read-only. You can read the asset's details, but accepting, declining, or commenting requires signing in. ## Signing up 1. Click **Sign up** on the preview page or follow the link in the notification email. 2. Your email is pre-filled. Pick a password. 3. Confirm. Your invitee account is ready, with the pending share waiting in your Inbox. There is no payment, trial setup, or team-invite step in invitee onboarding. ## Growing into a full account Invitee mode is suitable indefinitely if you only ever receive shares. If you want to use Cogram for your own project record-keeping (running your own meetings, sending your own transmittals, managing your own field reports), your account can be upgraded to a full Cogram organization. This upgrade is **operator-driven**: contact [hi@cogram.com](mailto:hi@cogram.com?subject=Upgrade%20invitee%20account) and the Cogram team will provision your subscription, run any setup, and enable the full UI on your existing organization. Your data, users, and accepted shares stay where they are. ## What "good" looks like * You can sign in within a minute of receiving the invitation email. * The pending share is the first thing you see. * After Accept, the new asset opens in your project. ## Troubleshooting **Symptom**: I clicked the email link and was asked to sign up, but the email is already mine. **Likely cause**: Your email isn't in Cogram yet, even if you have other accounts elsewhere. **Fix**: Sign up; it's a short flow. After sign-up the share is automatically waiting in your Inbox. **Symptom**: I can see the preview but the **Accept** button is disabled. **Likely cause**: You're not signed in. **Fix**: Click **Sign in** in the top right and sign in (or sign up) with the email the share was sent to. **Symptom**: I want to invite my own teammates. **Likely cause**: Invitee accounts don't include teammate management. **Fix**: Email [hi@cogram.com](mailto:hi@cogram.com?subject=Upgrade%20invitee%20account) to upgrade to a full account. Once upgraded, you can add teammates from organization settings. **Symptom**: I lost the email and can't find the share. **Likely cause**: The preview link expired, but the share itself is still valid. **Fix**: Sign in at [app.cogram.com](https://app.cogram.com/auth/login) and check [Inbox](https://app.cogram.com/dashboard/correspondence/inbox). ## Working in a shared project A firm can invite you into a whole project rather than a single asset. The invitation email says who invited you and links you into Cogram; signing in with the invited email address sets up your account if you do not have one. 1. Sign in via the link in the invitation email. 2. On the Projects page, a banner shows the pending invitation. Review it and choose **Accept** or **Decline**. 3. On accept, the shared project appears in your project list. Two things to know before you accept: * **The project lives in the host firm's workspace.** Everything you post, upload, or edit in it belongs to the project's record in their organization. Your own projects and data stay separate and private. * **Your role is set by the host.** As a Member you post in the project chat, upload files, and take part in the day-to-day; as a Viewer you read. The host's project owners and admins keep control of settings, channels, and membership — see [Project chat](/projects/project-chat). Colleagues joining later: if the host invites more people from your firm onto the same project, there is nothing for them to accept — your firm already agreed — and they are added directly. The host can end the share at any time, and the project then leaves your list. Anything in your own projects is unaffected. ## Privacy Your account, your projects, and your data are entirely separate from the sender's organization. The sender sees that you accepted or declined; they do not see anything you do inside your own projects after accept. For full privacy details see [Privacy and confidentiality](/get-started/privacy-and-confidentiality). # Inviting external collaborators Share a project with a consultant, contractor, or client at another firm: invite a Directory contact, get the share approved, and manage their access. Share a project with people at another firm — a structural consultant, a GC, an owner's rep — so you work in one project record instead of forwarding files. When you finish this guide, the person you invited can open your project in their own Cogram account, with the role you chose. ## When to use this * A consultant needs to follow the project's meetings, chat, and documents as the work happens. * A contractor should post updates in the project chat rather than email them. * A client or owner's rep needs read access to the project record. For sharing a single asset (one meeting, transmittal, RFI, or submittal) rather than a whole project, see [External collaborators](/projects/external-collaborators). ## Prerequisites * You are an owner of the project, or an admin or owner of your organization. * The collaborator is a contact in your [Directory](/projects/directory), with their **work email address**. Personal addresses (Gmail, Outlook.com, and similar) are not accepted — sharing is firm-to-firm. ## Invite a collaborator You invite a Directory contact, not a bare email address — the invitation is tied to a person your firm already tracks. Start from whichever surface you are on; all three open the same dialog: * **Directory**: open [Contacts](https://app.cogram.com/dashboard/directory/contacts) and select **Invite to *****project*** on the contact's row or on their contact page. Under **All Projects**, the button reads **Invite to project**, and the dialog asks which project to share. * **Project chat**: select **Invite a collaborator** at the bottom of the channel list. * **Project overview**: go to **Overview → Access**, scroll to **External collaborators**, and select **Invite a collaborator**. Then, in the dialog: 1. Confirm the **Contact**, or search for one if it isn't filled in already. 2. Pick a **Role**: * **Member** — posts in chat, uploads files, takes part in the project's day-to-day work. * **Viewer** — read-only. External collaborators can never be project owners. 3. Select **Send invite**. The confirmation tells you what happened: the invite went out at once, it is waiting for an admin's approval, or the person was added directly because their firm already collaborates on this project. ### If the contact cannot be invited The dialog (and the grayed-out button in the Directory) states the reason: | Reason | What to do | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | The contact is in your organization, or their email is on your organization's domain | Add them to the project as a member instead — they are not external. | | The contact has a personal email address | Ask for their work address and update the contact. Sharing across firms needs a work email. | | The contact is already on this project, or already has an invite on it | Nothing to do; check the invite's status under **Overview → Access**. | | The contact is archived | Restore the contact in the Directory first. | ## Approval Cross-firm shares are a governance decision, so they need an **organization admin or owner** to approve them: * If you are an org admin or owner yourself, your invite is approved automatically and the invitation email goes out at once. * If you are a project owner, the share appears under **Overview → Access → External collaborators** with an **Awaiting Approval** badge, and your organization's admins and owners are notified. One of them opens the same section and selects **Approve**. The collaborator receives their invitation email only after approval. ## What the collaborator sees The invitation email links them into Cogram, where they accept or decline the share. If they do not have a Cogram account yet, signing in with the invited email address sets one up. On accept, your project appears in their project list — the project and everything they add to it stay in your firm's workspace. Their side of the flow is described in [External collaborators](/projects/external-collaborators). ## Managing and revoking access The **External collaborators** section under **Overview → Access** lists every share with its role and status. To end a share, select the remove (trash) icon on its row — access ends immediately, and the person disappears from the project's member list. Project owners and org admins/owners can revoke. If you invite a second person from a firm that already collaborates on the project, there is nothing new to accept: their firm already agreed, so on approval the person is simply added under the existing share's role. ## Expected result * **Overview → Access → External collaborators** shows the share as **Accepted**, and the collaborator appears in the project's members. * In project chat, they take part according to their role — see [Project chat](/projects/project-chat). ## Troubleshooting **The share sits at Awaiting Approval and nothing happens** * Likely cause: no organization admin or owner has approved it yet. * Fix: your org's admins and owners were notified when you invited; follow up with one of them, or have them open the project's **Overview → Access** tab and select **Approve** under **External collaborators**. **The contact cannot be invited because their email is a personal address** * Likely cause: the contact's email is on a consumer domain (Gmail, Outlook.com, and similar). * Fix: update the contact in the [Directory](/projects/directory) with their work email address. Sharing is firm-to-firm. **The invited person says they never received an email** * Likely cause: the share has not been approved yet — the email goes out on approval. * Fix: check the status in the Team tab. If it shows **Awaiting Approval**, an org admin needs to approve first. ## Next steps * [Project chat](/projects/project-chat) — how guests take part in the conversation * [Project roles](/projects/project-roles) — what Member and Viewer mean * [External collaborators](/projects/external-collaborators) — the collaborator's side of the flow # Inbox Receive meetings, transmittals, RFIs, and submittals shared with you by collaborators outside your organization, and accept them into one of your projects. The Inbox is where items shared with you by people in **other** organizations land. When a collaborator shares a meeting, transmittal, RFI, or submittal with your email address, you'll see it in your Inbox. The Inbox lives under the **Contract Admin** module in the left sidebar, at [Contract Admin > Inbox](https://app.cogram.com/dashboard/correspondence/inbox). ## What's in the Inbox Each row is one **share**: a single asset (meeting, transmittal, RFI, or submittal) that someone outside your organization sent to you. Rows show: * **Type**: what kind of asset it is. * **Message**: the sender's optional note. * **Received**: the date the share was created. Click a row to open the share detail dialog with the full message and sender info. The Inbox has three tabs: **Pending**, **Accepted**, and **Declined**. ## Accepting a share 1. Open [Contract Admin > Inbox](https://app.cogram.com/dashboard/correspondence/inbox), click the share you want to accept. 2. Pick a **target project** in your organization from the project picker. 3. Click **Accept**. When you accept a share: * A copy of the asset's key details (title, number, status, summary text) is created in the project you picked. The copy is yours; the sender can't revoke it after accept. * Attachments and source documents are not copied yet; ask the sender to transmit files directly if you need them. * The share moves from **Pending** to **Accepted**. After accept, the new asset opens in your project. Treat it like any other asset in that project: edit the body, add comments, file follow-up emails, generate reports. ## Declining a share If a share isn't relevant (wrong project, sent in error, already have a copy), click **Decline** in the share detail dialog. The share moves to **Declined** and the sender is notified. Declining is reversible only by the sender (who would need to send a new share); your decline doesn't delete the original asset in their organization. ## Pre-accept preview Some shares include a tokenized **preview link** in the notification email. Anyone with the link can read a sanitized version of the asset before signing in. Useful for forwarding to a colleague to confirm relevance. The preview is read-only. Accepting, declining, or commenting always requires you to sign in. The sender controls the preview: * Sender can **disable** the preview entirely (the email arrives with no preview link; you must sign in to see anything). * Sender picks an **expiry**: 24 hours, 7 days (default), 30 days, 90 days, or none. * Sender can **revoke** a pending share, which immediately invalidates the preview link. ## What "good" looks like * Pending shares appear within seconds of the sender clicking Share. * After Accept, the new asset opens directly in your chosen project. ## Troubleshooting **Symptom**: I got an email saying "X shared a meeting with you" but my Inbox is empty. **Likely cause**: You signed in as a different user. The share is bound to the email address it was sent to. **Fix**: Check the email's "to" header matches the address you're signed in as. Sign in to the matching account. **Symptom**: The preview link in the email shows "Preview not available." **Likely cause**: The sender revoked the share, the preview expired, or the sender chose **Require sign-in to view**. **Fix**: Sign in to Cogram and check your [Inbox](https://app.cogram.com/dashboard/correspondence/inbox). Pending shares appear there even if the preview link is invalid. **Symptom**: I can't find the project I want to accept into. **Likely cause**: You're not a member of that project, or it's archived. **Fix**: Ask the project owner to add you as a member. The project picker only lists active projects you can write to. **Symptom**: I accepted a share but don't see the new asset in my project. **Fix**: Refresh the project page. If it still doesn't appear, contact support. ## Notes for AI-generated content Shared meetings, RFIs, and transmittals may contain AI-generated summaries, action items, or extracted data. Before relying on accepted content for contractual, scheduling, or technical decisions, verify: * Names, dates, and attendees. * Action items and decisions. * Technical values and units. * Contractual language. # Your file server Browse, search, preview, and upload files on your organization's own file server, without leaving Cogram or mapping a drive. If your organization connects its file server to Cogram, those files appear under **Files**. You browse the same shares you see in Windows Explorer, and you see exactly the files your own account can open there. The files stay on your organization's server. Cogram reads them when you ask for them. ## What you can do * Browse shares and folders, with sizes and dates * Search the whole file server by file name and by text inside documents * Preview a file without downloading it * Upload files into a folder, if your organization has turned that on * Export a project's completed items into a folder, if a project lead has set that up ## Finding a file ### Browsing Go to [Files](https://app.cogram.com/dashboard/files) in the left navigation. You start at the list of shares, for example Engineering, Finance, and Shared. Click a folder to open it, and use the trail at the top or your browser's Back button to go back up. Each folder shows its total size and how many files it holds, counting only the files you can read. ### Searching Type in the search box on the Files page to search the whole file server. Cogram searches file names and the text inside documents, so "curtain wall" finds a specification that mentions it even when the file is named `07-5400.docx`. Files also appear in the global search you open with **⌘K** (**Ctrl+K** on Windows), under **File server**. Select a result to open its preview. ## Previewing a file Select any file to open it. PDFs and images render in full. Word documents, Excel workbooks, CSVs, and text files show their extracted text, which is enough to confirm you have the right file before you open it properly. The panel on the right shows the file's name, type, size, created and modified dates, and its full location on the server. Use the location when you need to tell a colleague where a file lives. ## Uploading files Uploading is available only if your organization has enabled it. If you do not see an **Upload** button, it is off, or you are at the top level. You can only upload into a folder, not into the list of shares. 1. Open the folder you want the file to go into. 2. Select **Upload**, or drag files onto the file list. 3. Watch the progress under the toolbar. The file appears in the list when it is saved. Cogram writes the file to your file server only where your own account could have written it. If you cannot save a file to that folder from Windows Explorer, the upload is refused too. ### What good looks like The upload row shows a check mark, then disappears, and the file is in the list with its size and today's date. You can find it in search straight away. ## Exporting a project to your file server Cogram can copy a project's completed items into one folder on your file server. Project owners and leads set this up, and organization admins can set it up for any project. Cogram only adds files. It never overwrites or deletes them. 1. Open the project, then go to **Overview → Settings → File server export**. 2. Select **Choose folder**, open the folder the project should write into, then select **Use this folder**. 3. Turn on each type of item you want on the file server. One folder holds one project. If the folder is already linked to another project, Cogram tells you before you save. Each type writes a different file into its own subfolder: | Type | What Cogram writes | | --------------- | ----------------------------------------------------------------------------- | | Meeting minutes | One Word file for each completed meeting, in a folder named after the meeting | | Emails | The original message for each email filed to the project | | Field reports | One Word file for each completed field report | | Photos | Photos, next to the meetings and field reports they belong to | | RFIs | One PDF cover sheet for each RFI that has an answer | | Submittals | One PDF cover sheet for each submittal that has a response | | Transmittals | One PDF cover sheet for each closed transmittal | When you turn on a type, Cogram also exports the items that are already complete. A large backlog can take a few hours to finish. The settings section counts what is still waiting. Exports run as the person who last saved these settings. Cogram writes only where that person could write from Windows Explorer. ### What good looks like The project's start page shows the folder under **File server**, with **Up to date** next to it. Open the folder in **Files** and the subfolders are there, with the exported files inside. ## Troubleshooting **Symptom:** Files does not appear in the navigation. **Likely cause:** Your organization has not connected a file server. **Fix:** Ask an administrator to connect it under [Organization Settings → Integrations → File Server Connectors](https://app.cogram.com/dashboard/settings/admin/integrations#connectors). Setup is covered in [Connecting your file server](/integrations/connecting-your-file-server). **Symptom:** A folder is empty, but you know it has files in it. **Likely cause:** Your account does not have read access to those files on the file server. **Fix:** Ask whoever administers the file server for access. Permissions come from the file server, not from Cogram, so changing your Cogram role does not help. **Symptom:** "The file server is unavailable." **Likely cause:** The connector on your organization's server is not running. **Fix:** Ask an administrator to check it. Your files are unaffected. **Symptom:** "*name* already exists in this folder." **Likely cause:** A file of that name is already there. **Fix:** Cogram never replaces a file on your server. Rename your copy, or upload it to a different folder. **Symptom:** "You do not have permission to add files to this folder." **Likely cause:** Your account has read access to that folder, but not write access. **Fix:** Ask whoever administers the file server to give you write access to that share. **Symptom:** Field reports are counted as failed, with "no template". **Likely cause:** The report's type has no default export template, so Cogram cannot build the Word file. **Fix:** Ask an administrator to set a default template for that report type. **Symptom:** The export settings say the connector is read-only. **Likely cause:** The connector was installed without writes. **Fix:** Ask an administrator to reinstall it with writes enabled. See [Connecting your file server](/integrations/connecting-your-file-server). ## Things to know * Uploaded files are owned by the Cogram connector's service account on the file server, not by you. Cogram records who uploaded each file. * Cogram does not scan uploads for viruses. Upload only files you trust, exactly as you would when saving to a shared drive. * Cogram never deletes, renames, or overwrites anything on your file server. * Cogram exports each item once. If you unlink a folder and link it again, Cogram does not export those items a second time. * A folder that a project exports into is marked in **Files**, so you can see which folders Cogram writes to. ## Next steps * [Agent](/agent/agent) can search and read these same files when you ask it a question. * [Privacy and confidentiality](/get-started/privacy-and-confidentiality) # Project roles Understand the project roles in Cogram (Owner, Lead, Member, and Viewer) and what each role can do. Every member of a Cogram project has a role: **Owner**, **Lead**, **Member**, or **Viewer**. Roles control what a user can see and do within a project. Project roles are separate from [Organization roles](/organization-administration/organization-roles), which control what a user can do across the entire organization, including creating and managing projects. ## Role Overview | Permission | Owner | Lead | Member | Viewer | | -------------------------------------- | :---: | :--: | :----: | :----: | | View meetings, reports, and files | ✓ | ✓ | ✓ | ✓ | | Download files and export reports | ✓ | ✓ | ✓ | ✓ | | View project members | ✓ | ✓ | ✓ | ✓ | | Create meetings, reports, observations | ✓ | ✓ | ✓ | | | Upload and delete files | ✓ | ✓ | ✓ | | | Edit drawings | ✓ | ✓ | | | | Update project settings | ✓ | ✓ | | | | Add and remove project members | ✓ | | | | | Delete project | ✓ | | | | ## Roles in Detail ### Owner Full control over the project. Owners can manage project settings, add or remove members, and create or edit any content. ### Lead A management role for people who run a project day to day without owning it. Leads can do everything a Member can, plus edit and delete drawings and change project settings. In **Owner** asset-visibility mode, Leads see all project content, just like Owners. Leads cannot add or remove members, respond to access requests, or delete the project. Those actions stay with Owners. > **Availability**: The Lead role is available to organizations that have it turned on. If you don't see it in the role list, it isn't enabled for your organization yet. ### Member Can view all project content and create new content (meetings, reports, observations, files). Cannot manage project settings or membership. ### Viewer Read-only access. Viewers can view and download content but cannot create, edit, or delete anything. Useful for external stakeholders or clients who need visibility without edit access. > **Note on meeting visibility**: What meetings a Viewer can see also depends on the project's **asset visibility** setting. In **Full** mode, Viewers see all project meetings. In **Owner** or **Restricted** mode, Viewers only see meetings they own or participated in. See [Asset visibility](/projects/asset-visibility) for details. > **Viewer is not the same as View & Respond.** The project **Viewer** role (above) controls what a user can do inside one project. **View & Respond** is an organization-level access level that controls which modules a user is licensed for. See [Licensing](/organization-administration/licensing). ## Assigning Roles Owners assign roles when inviting a user to a project, or change them later in **Project Settings > Members**. Leads, Members, and Viewers can't change roles. ## Group Access You can assign an entire [group](/organization-administration/groups) to a project in **Project Settings > Members and Groups**. Choose the role the group grants: **Lead**, **Member**, or **Viewer**. Every member of the group gets that role on the project. **Owner** can only be assigned to a person directly, never through a group. > **Availability**: Granting **Lead** through a group needs the Lead role turned on for your organization, the same as assigning it to a person. If the group's role list offers only Member and Viewer, it isn't enabled yet. Group-assigned users appear in a separate **Via groups** section in the members list. Their access is managed through the group; to remove a user's access, remove them from the group rather than from the project directly. If a user is both directly added to a project and a member of an assigned group, their effective role is the higher of the two: a user directly added as **Owner** keeps the Owner role even if their group only grants Member access, and a direct **Member** who is in a group that grants **Lead** is raised to Lead. # Project management permissions Control project creation, archiving, and deletion permissions, and manage organization-wide project discoverability defaults. By default, any user who owns a project can create new projects, archive their projects, and delete them. The **Project Management Permissions** setting lets you restrict those actions to organization Admins and Owners only. ## Enabling the restriction 1. Go to [Organization Settings > Projects > Project Permissions](https://app.cogram.com/dashboard/settings/admin/projects/project-permissions). 2. Toggle **Restrict project management to admins and owners** to on. Once enabled, the following actions are restricted to org Admins and Owners: | Action | Admins & Owners | Members (project owners) | | ------------------- | :-------------: | :----------------------: | | Create new projects | ✓ | | | Archive a project | ✓ | | | Delete a project | ✓ | | Members who own projects will no longer see the **New Project** button, the archive toggle in project settings, or the delete option in the project list. > **Note:** Org Admins and Owners always retain full project management access regardless of this setting. ## When to use this Use this to keep project creation and removal in the hands of designated administrators. *** ## Project Discoverability Any organization member can browse discoverable projects in the **Organization Projects** tab on the [Projects page](https://app.cogram.com/dashboard/projects/) and request access. Org admins and owners can configure the default discoverability behavior for all projects. ### Configuring the org default 1. Go to [Organization Settings > Projects > Project Permissions](https://app.cogram.com/dashboard/settings/admin/projects/project-permissions). 2. Under **Project Discoverability**, use the following toggles:
The Project Discoverability section in Organization Settings, showing the Enable discoverability by default and Allow project owners to override toggles

The org-wide Project Discoverability defaults

| Setting | Effect | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Enable discoverability by default** | When on, new projects are discoverable to all organization members by default. When off, new projects are hidden from the organization directory by default. | | **Allow project owners to override** | When on, project owners can change the discoverability of their own projects in Project Settings. When off, only org admins and owners can change it. | ### Applying the default to existing projects Below the toggles, click **Apply to all existing projects** to set every project (excluding archived projects) to the current org default. A confirmation dialog will appear because this action cannot be undone. > **Note:** If "Allow project owners to override" is turned off and you apply to all, project owners will not be able to change the setting back on their own projects afterward. ### Setting discoverability on selected projects When you want to update only a subset of projects (for example, to make a few specific projects discoverable without changing the rest) use **Set discoverability on selected projects** next to "Apply to all". 1. Go to [Organization Settings > Projects > Project Permissions](https://app.cogram.com/dashboard/settings/admin/projects/project-permissions). 2. Under **Project Discoverability**, click **Set discoverability on selected projects**. 3. In the dialog: * Choose **Discoverable** or **Hidden** as the target value. * Search by project name and tick the projects you want to update. * Use **Select all on page** to quickly tick every visible project, or **Deselect all on page** to clear them. 4. Click **Apply to N projects** to save. Personal projects and archived projects are not eligible and won't appear in the picker. The dialog lists up to 500 projects at a time; refine the search to find more. ### Per-project discoverability Individual projects can be toggled between discoverable and hidden in **Project Settings > Project discoverability**, as long as the organization allows overrides. If the override is locked by the org admin, a warning is shown explaining that discoverability is controlled by the organization. See [Projects: Project discoverability](/projects/projects#project-discoverability) for more details on what discoverable and hidden mean for project members. # Project types Categorize projects by type: Residential, Commercial, Infrastructure, or any classification your firm uses. Project types appear in the project list, card view, and project sidebar. As an org admin, you can create a shared set of project types (for example Residential, Commercial, or Infrastructure) that everyone uses to classify projects. Once created, any project owner or org admin can assign a type to a project. ## Who can manage project types | Action | Required role | | --------------------------------- | -------------------------------------- | | View available types | Any org member | | Assign or change a project's type | Project Owner, Org Admin, or Org Owner | | Create, edit, or delete types | Org Admin or Org Owner | ## Creating a project type 1. Go to [Organization Settings > Projects > Project Types](https://app.cogram.com/dashboard/settings/admin/projects/project-types). 2. Click **Add Type**. 3. Enter a name (e.g., "Residential"). 4. Optionally pick a color. The color appears as a badge in the project list. 5. Click **Add**. You can assign the new type to any project right away. ## Bulk uploading project types If you already maintain your project taxonomy in another system, you can upload it instead of creating each type by hand. 1. Go to [Organization Settings > Projects > Project Types](https://app.cogram.com/dashboard/settings/admin/projects/project-types). 2. Click **Bulk upload**. 3. Drop a **CSV**, **Excel** (`.xlsx`, `.xls`), or **JSON** file (up to 5 MB), or click the drop zone to browse. 4. Click **Next**. Cogram parses the file and shows a preview. 5. In the preview, deselect any rows you don't want to import, and edit names or colors inline if needed. Rows flagged **Will skip (exists)** match a type that already exists; rows flagged **Duplicate in file** repeat another row in the upload. 6. Click **Create N types** to finish. **File format:** * Cogram looks for a column named `name` (or `type`, `project_type`). If no column matches, the first column is used as the name. * An optional `color` column (or `hex`) sets the badge color: use a hex code like `#3B82F6`. * Click **Sample CSV** in the upload dialog to download an example. Existing types with the same name are skipped, not overwritten. Cogram reports how many types were created, skipped, or errored after submission. ## Editing a project type 1. Go to [Organization Settings > Projects > Project Types](https://app.cogram.com/dashboard/settings/admin/projects/project-types). 2. Click the pencil icon next to the type you want to edit. 3. Change the name or color. 4. Click **Save**. If the type is already assigned to projects, Cogram shows a confirmation dialog listing how many projects will be affected by the rename. ## Deleting a project type 1. Go to [Organization Settings > Projects > Project Types](https://app.cogram.com/dashboard/settings/admin/projects/project-types). 2. Click the trash icon next to the type, or select multiple types and click **Delete**. 3. Confirm the deletion. Projects that were using a deleted type will have their type cleared (set to none). No other project data is affected. ## Assigning a type to a project You can assign a type when creating a project or at any time afterward. **During project creation:** 1. Go to [Projects](https://app.cogram.com/dashboard/projects/) and click **New Project**. 2. In the **Basics** step, select a type from the **Project Type** dropdown. 3. If the type you need does not exist, click **Create new type** to add one inline (requires Org Admin or Org Owner role). **On an existing project:** * **From the** [**Projects**](https://app.cogram.com/dashboard/projects/) **list:** In the **Type** column, click the type badge to change it, or hover an empty cell and click the **+** to set one. Choose **None** to clear it. (The card view shows a project's type when set, but you set or change it from the list.) * **From the project sidebar:** Open the project, then click the type badge under **Project Type** in the sidebar. * **From Project Settings:** Open the project and go to **Settings** (Org Admins/Owners can also reach it from the project's **Project Settings** action in the admin [Projects](https://app.cogram.com/dashboard/settings/admin/projects) table). Pick a type from the **Project Type** dropdown and save. Org Admins and Org Owners can click **Create new type** at the bottom of the picker dropdown to add a new type inline without leaving the project. ## Assigning a type to multiple projects at once Org Admins and Org Owners can bulk-assign a project type from the admin [Projects](https://app.cogram.com/dashboard/settings/admin/projects) table: 1. Select the projects you want to update using the row checkboxes. 2. Click **Set type** in the bulk-actions bar. 3. Pick a type from the list, or choose **Clear type** to remove the type from every selected project. Cogram updates each project and shows a confirmation toast. If any updates fail, the selection is kept so you can retry the failed ones. ## Filtering projects by type On the [Projects](https://app.cogram.com/dashboard/projects/) page, click **Filters** to open the filters popover. Under **Project Type**, check one or more types to narrow the list. You can also search for projects by type name using the search bar. Typing a type name (e.g., "Residential") returns projects assigned to that type. ## Searching by project type Project type names are included in search results across Cogram: * **Project list search**: type names to find projects of that type. * **Global search** (Cmd+K / Ctrl+K): project results include the type name as metadata. * **Agent resource picker**: type a type name to find matching projects when adding context. # Project templates Save reusable project setups that pre-bind groups, project type, email filing, discoverability, and a default description, so you don't reconfigure the same fields every time you create a project. Project templates capture the parts of a project that are the same across many projects: group access, project type, email filing, discoverability, and a starting description. Once a template exists, anyone creating a new project can pick it from the wizard's first step and skip straight to **Create Project** without configuring those fields by hand. Templates are created and managed in [Organization Settings → Projects → Project Templates](https://app.cogram.com/dashboard/settings/admin/projects/project-templates). ## Who can manage project templates | Action | Required role | | -------------------------------------------- | -------------------------------- | | Pick a template when creating a project | Any user who can create projects | | Create, edit, duplicate, or delete templates | Org Admin or Org Owner | Members see existing templates in the project-creation wizard but do not see the **+ Create new template** link or the empty-state nudge if no templates exist yet. ## What a template includes Each template stores: * **Name**: shown in the wizard's template picker. 1–100 characters, unique within the organization (case-insensitive). * **Description**: optional. Pre-fills the project's description field. Treat it as a starting point; specific projects usually need their own details added on top. * **Default project type**: optional. See [Project types](/projects/project-types). * **Email filing default**: whether projects created from this template have email filing enabled out of the box. * **Discoverability**: whether projects created from this template are listed in the organization-wide project directory. Choose **Organization default**, **Discoverable**, or **Hidden**. See [Discoverability](#discoverability) below for exactly what each one does. * **Groups**: one or more groups to grant access to, each with a role of **Lead**, **Member**, or **Viewer**. **Lead** is offered only to organizations that have the Lead role turned on. See [Project roles](/projects/project-roles) for what those roles can do. Templates do not store a project name, project number, client, or address. Those are unique to each project and must be entered each time. ### Discoverability
The Discoverability dropdown in the project template editor, open to show Organization default, Discoverable, and Hidden

The Discoverability setting in the project template editor

This setting controls whether projects created from the template are listed in the organization-wide project directory (the **Organization Projects** tab on the [Projects page](https://app.cogram.com/dashboard/projects/)). The three options map exactly to the dropdown above: | Option | What the template forces | What it means for people | If the org default changes later | | ------------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **Organization default** | Nothing: the project inherits your org's discoverability default **at the moment it's created**. | Whatever your org's default is today (Discoverable or Hidden; see [Project Management Permissions](/projects/project-management-permissions#project-discoverability)). | Projects already created keep the value they were given. Only future projects pick up the new default. | | **Discoverable** | The project is always **listed** in the org-wide project directory. | Every org member can see the project exists and can **request access**; project owners, org admins, and org owners approve requests. Org admins and owners can open and edit it directly. | No effect: the template overrides the org default, so these projects stay discoverable. | | **Hidden** | The project is always **kept out** of the org-wide project directory. | Only people who are already members (or who have a direct link) can find or open it. Non-members can't see it and can't request access; an admin must add them manually. | No effect: the template overrides the org default, so these projects stay hidden. | "Discoverable" and "Hidden" affect only **who can find and request access to** the project. They do **not** change what a member can see *inside* a project once they're in. That's governed separately by [Asset visibility](/projects/asset-visibility). For the full member-facing explanation, see [Projects: Project discoverability](/projects/projects#project-discoverability). ## Creating a project template 1. Go to [Organization Settings → Projects → Project Templates](https://app.cogram.com/dashboard/settings/admin/projects/project-templates). 2. Click **Add Template**. 3. Enter a **Name** (e.g., "Healthcare – Tier 1"). 4. Add a **Description** that explains when this template should be used. 5. Toggle **Enable email filing by default** on or off. 6. Optionally pick a **Default project type**. 7. Choose a **Discoverability** setting: Organization default, Discoverable, or Hidden. 8. Under **Groups**, click **Add group** to bind groups to the template. For each group, pick a role (Lead, Member, or Viewer; Lead only if your organization has that role turned on). Use the search field in the picker to find groups in large orgs. 9. Click **Save**. The template is immediately available in the project-creation wizard for everyone in the organization. ## Editing a project template 1. Go to [Organization Settings → Projects → Project Templates](https://app.cogram.com/dashboard/settings/admin/projects/project-templates). 2. Click the row of the template you want to edit. 3. Change any field: name, description, defaults, or group bindings. 4. Click **Save**. Editing a template affects future projects only. Projects already created from the template are not modified. ## Duplicating a project template Use duplicate when you want a new template that's close to an existing one, for example a "Healthcare – Tier 2" that starts as a copy of "Healthcare – Tier 1". 1. Go to [Organization Settings → Projects → Project Templates](https://app.cogram.com/dashboard/settings/admin/projects/project-templates). 2. On the template's row, click the **⋯** menu and choose **Duplicate**. 3. The copy is created immediately with the name suffixed by "(Copy)" (or "(Copy 2)", "(Copy 3)", etc., if a "(Copy)" already exists). All group bindings and settings are preserved. 4. Click the new row to rename it and tweak the bindings. ## Deleting a project template 1. Go to [Organization Settings → Projects → Project Templates](https://app.cogram.com/dashboard/settings/admin/projects/project-templates). 2. On the template's row, click the **⋯** menu and choose **Delete**. 3. Confirm the deletion. Deleting a template does not affect any project that was previously created from it. Those projects keep all their groups, settings, and members. ## Using a template when creating a project Anyone who can create a project can use a template. The template picker lives at the top of the wizard's first step. 1. Go to [Projects](https://app.cogram.com/dashboard/projects) and click **New Project**. 2. In the **Basics** step, open the **Start from template** dropdown and pick a template. 3. The wizard pre-fills: * Description * Project type * Email filing default * Discoverability * Groups (and their roles) 4. Enter a **Project name** and **Project number**. These are always required and unique to the project. 5. Click **Create Project**. When a template is selected, the wizard skips ahead: the **Details**, **Members**, and **Review** steps still appear in the stepper for context but are greyed out. You create the project from step 1 in a single submit. To start from scratch instead, pick **No template** from the dropdown. The wizard restores the four-step flow and clears any values the template had pre-filled. The **(i)** icon next to the **Start from template** label opens a short explanation and a link back to this page if you need a reminder of what templates do. If you're an Org Admin or Owner, a **+ Create new template** link sits below the dropdown so you can jump straight into the template editor without leaving the wizard. When the org has no templates yet, the dropdown is replaced by a one-line **Create a template** nudge that links to the same place. ### What's not pre-filled Templates intentionally don't carry per-project information. You always enter: * **Project name** * **Project number** * **Client** (optional) * **Address** (optional) ### Adding members and groups not in the template The template's groups are applied automatically on create. To add individual users or extra groups that aren't part of the template, open the project after it's created and use **Project Settings → Members**. ## Searching and sorting templates The [Project Templates](https://app.cogram.com/dashboard/settings/admin/projects/project-templates) list supports: * **Search** by template name or description (case-insensitive). * **Sort** by Name, number of bound Groups, or Last modified: click the column header. # Project import Import projects in bulk from a CSV, Excel, or JSON file with AI-assisted column mapping. Organization admins can import projects in bulk from a spreadsheet or JSON export. Cogram auto-detects and maps the columns in your file, so you don't have to match them up by hand. Go to [Organization Settings > Projects](https://app.cogram.com/dashboard/settings/admin/projects) and click **Import**. ## Supported file formats CSV (`.csv`), Excel (`.xlsx`), and JSON (`.json`). A downloadable example template is available on the upload page. ## Import steps ### 1. Upload Drag a file onto the upload area or click to browse. Once a file is selected, click **Continue**. ### 2. Map Columns Cogram auto-suggests which columns in your file correspond to Cogram project fields. Review the mappings and adjust as needed using the dropdowns. A confidence indicator shows how confident the AI is in each suggestion. Available target fields: | Field | Required | | ---------------- | -------- | | Name | Yes | | Project Number | Yes | | Description | No | | Client Name | No | | Address | No | | Owners | No | | Members | No | | Project Metadata | No | You can also set any column to **Skip** to ignore it. Click **Review** once the required fields are mapped. ### 3. Review A preview shows how many projects will be created, updated, or skipped, and lists any errors. You can also: * **Pre-create users**: if owner or member email addresses are not yet in your organization, select which ones to pre-create and optionally send invitation emails. * **Set a fallback owner**: assigned to new projects when no owner column is mapped or when mapped owners are not being pre-created. * **Auto-file incoming emails**: optionally enable automatic email filing for imported projects. Click **Import N projects** to proceed. ### 4. Import complete A summary shows the number of projects created, updated, skipped, and any errors. Click **Import More** to start another import. # Asset visibility Control which project members can see meetings, emails, and reports within a project. Asset visibility determines which project members can see content (meetings, emails, reports) within a project. Org owners and admins set a default at the organization level; individual projects can optionally override it. ## Visibility Modes | Mode | What members see | | -------------- | ------------------------------------------------------------------------------------ | | **Full** | All members see all content in the project. | | **Owner** | Project owners and leads see all content. Other members see only their own. | | **Restricted** | Everyone (including owners and leads) sees only content they own or participated in. | The default mode is **Full**. ## Org-Level Setting Org owners and admins can set the default visibility mode for all projects in the **Asset Visibility** section of [Organization Settings > Projects](https://app.cogram.com/dashboard/settings/admin/projects#asset-visibility). This applies to all projects unless a project-level override is set. ## Project-Level Override If the org allows overrides, project owners can set a different visibility mode for their individual project under **Project Settings > Asset Visibility**. ## Viewer Role The asset visibility mode also applies to [Viewers](/projects/project-roles). In **Full** mode, Viewers see all project content. In **Owner** or **Restricted** mode, Viewers only see content they own or participated in, the same rules as any other member who isn't an owner or lead. # Access requests Review and approve project access requests, choose who can grant access, and route new requests to an external email such as a ticketing system. When a project is **discoverable**, any organization member can find it in the **Organization Projects** tab on the [Projects page](https://app.cogram.com/dashboard/projects/) and request access to it. Access requests are managed in [Organization Settings > Projects > Access Requests](https://app.cogram.com/dashboard/settings/admin/projects/request-access). This page covers three things: reviewing pending requests, choosing who can grant access, and routing new requests to an external email. ## Reviewing pending requests Open requests appear under **Pending requests** at the top of the Access Requests section. For each request you can: * **Approve**: adds the requester to the project as a member. * **Decline**: rejects the request. You can include a reason. The requester is emailed that their request was declined. Pending requests always appear here for anyone who can grant access, regardless of the notification settings below. Turning notifications off never causes a request to be lost. If a requester gains access another way before you act on it (for example, you add them to the project directly or add them to a [group](/organization-administration/groups) that already has access), their pending request clears automatically and its notification is removed. There's nothing left to approve. Requests you never act on expire on their own after 7 days and drop off the list, so the inbox doesn't fill up with stale entries. Expired requests send no email either way. ## Who can grant access By default, only org Admins and Owners can approve or decline access requests. To let project owners handle requests for their own projects: 1. Go to [Organization Settings > Projects > Access Requests](https://app.cogram.com/dashboard/settings/admin/projects/request-access). 2. Toggle **Allow project owners to grant access** to on. | Setting | Effect | | ----------------- | ---------------------------------------------------------------------------------------------------------- | | **Off** (default) | Only org Admins and Owners can grant access and receive new-request notifications. | | **On** | Project owners can also grant access to their own projects and receive new-request notifications for them. | ## Access request routing By default, each new access request notifies your org Admins and Owners. If you manage access through an external workflow (for example, a ticketing system), you can route requests to an email address and, optionally, stop notifying Admins and Owners. ### Send requests to an external email 1. Go to [Organization Settings > Projects > Access Requests](https://app.cogram.com/dashboard/settings/admin/projects/request-access). 2. Under **Access request routing**, enter an address in **Routing email**, for example your ticketing system's intake inbox. 3. Select **Save**. Each new access request is then emailed to that address. Most ticketing systems turn an inbound email into a ticket automatically, so requests land directly in your queue. Leave the field blank to disable routing. Once your team grants access outside Cogram, the Cogram-side request stays under **Pending requests** until it's resolved. If granting access adds the person to the project or to a [group](/organization-administration/groups) that has it, the request clears itself. Otherwise, leave it and it expires on its own after 7 days. Cogram sends these emails from its notification address, `noreply@email.cogram.com`. Make sure your ticketing system accepts mail from that sender, otherwise requests may be filtered as spam. ### Notify org admins and owners The **Notify org admins and owners** toggle controls whether Admins and Owners are alerted about new requests. | Toggle | Result | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **On** (default) | Admins and Owners receive an in-app notification and an email for each new request. | | **Off** | Admins and Owners receive neither. Requests still appear under Pending requests, and are still sent to the routing email if one is set. | > **Note:** The toggle covers both the in-app notification and the email. When it is on, an individual admin still only receives the email if they have not muted "Approvals & Requests" emails in their personal [Notification preferences](/your-account/notifications-1). The org toggle is the master switch. ## Next steps * [Project management permissions](/projects/project-management-permissions): set project discoverability defaults. * [Organization notification settings](/organization-administration/notifications): control notifications across your organization. # Setting up project chat Turn Project Chat on for a project and manage its channels: adding, renaming, archiving, and bringing archived channels back. {% hint style="info" %} Project Chat is in beta and is being rolled out gradually, so it is not yet available to every organization. If you would like to use it, write to to join the beta. Once your organization has it, chat is still off by default on every project — this page shows how to turn it on for a project. {% endhint %} Chat is off for new projects. A project owner, or an organization admin or owner, turns it on per project and manages the channels the team talks in. Once chat is on, everyone with access to the project gets a **Chat** entry in the project sidebar. For how the team uses it, see [Project chat](/projects/project-chat). ## Turning chat on for a project 1. Open the project from the [Projects page](https://app.cogram.com/dashboard/projects/). 2. Go to **Settings > Chat**. 3. Turn on **Enable chat for this project**. The first time you do this, Cogram creates a `#general` channel for you. A **Channels** section appears below the toggle so you can add more.
The Chat page of project settings: the Enable chat for this project toggle turned on, the channels table with rename and archive buttons, and an archived channel with an Unarchive button.

Settings > Chat: the chat toggle, the project's channels, and an archived channel

If the toggle is not editable, you are not a project owner and not an organization admin or owner. The page says so. There is a shortcut from the chat pane itself: if you can manage channels, a **Manage channels** link at the bottom of the channel list takes you to this page. ## Adding a channel 1. In **Settings > Chat**, select **Add channel**. 2. Type the name. The `#` is added for you. 3. Select **Create**. Give each channel a job, so people know where to post: `#site-updates`, `#curtain-wall`, `#rfi-tracking`. ### Channel naming rules * Lowercase letters, digits, and single hyphens, for example `site-updates`. * Up to 80 characters. * Unique within the project. Archived channels still hold their names, so you cannot reuse one until it is renamed. A leading `#`, stray spaces, and capital letters are cleaned up as you type rather than rejected. Anything that still breaks the rules is flagged under the box before you can create the channel. ## Renaming a channel 1. In **Settings > Chat**, select the rename button on the channel's row. 2. Edit the name and select **Save**. Renaming is safe at any time. Links to messages in that channel, including the ones in mention notifications, keep working. ## Archiving a channel Archiving retires a channel without losing anything. 1. In **Settings > Chat**, select the archive button on the channel's row. 2. Confirm with **Archive channel**. An archived channel leaves the chat pane and is excluded from search. Its messages and files are kept. **A project with chat always keeps at least one active channel.** The archive button on the last remaining channel is disabled; add another channel first if you want to retire it. Channels cannot be deleted. Archive is the way to take one out of use. ## Bringing an archived channel back Archived channels are listed in their own **Archived channels** section at the bottom of the page, each marked **Archived**. Select **Unarchive** on the row. The channel returns to the chat pane with all of its history, and is searchable again. ## Turning chat off Turning off **Enable chat for this project** hides the **Chat** entry from the project sidebar. Nothing is deleted: channels, messages, and files are kept, and turning chat back on restores the project's chat exactly as it was. ## Who can do what | Task | Project Owner | Organization admin or owner | Member | Viewer | | ------------------------------------------- | :-----------: | :-------------------------: | :----: | :----: | | Turn chat on or off for the project | ✓ | ✓ | | | | Add, rename, archive, or unarchive channels | ✓ | ✓ | | | | Delete anyone's message | ✓ | ✓ | | | | Post, react, attach files | ✓ | ✓ | ✓ | | | Read the conversation and search it | ✓ | ✓ | ✓ | ✓ | See [Project roles](/projects/project-roles) for the wider picture of what each project role can do. On a project shared with another organization, these controls stay with the host project: its owners and the admins of its organization. Guests take part in chat according to the project role they were granted, but cannot turn chat on or off or manage channels, whatever their role in their own organization. ## Troubleshooting **There is no Chat page in project settings** * Likely cause: Project Chat is not yet available to your organization. * Fix: contact Cogram support. See [Getting help](/get-started/getting-help). **The Enable chat toggle is visible but you cannot change it** * Likely cause: you are a project Member, not an Owner, and not an organization admin or owner. * Fix: ask a project owner or your organization admin to turn chat on. **You cannot archive a channel** * Likely cause: it is the project's only active channel. * Fix: add another channel, then archive this one. **A channel name is rejected as already taken, but you cannot see it** * Likely cause: an archived channel already has that name. * Fix: rename the archived channel, or pick a different name. ## Next steps * [Project chat](/projects/project-chat): how the team uses channels, mentions, files, and search * [Project roles](/projects/project-roles): Owner, Member, and Viewer * [Organization notification settings](/organization-administration/notifications): defaults and locks for mention emails # Documents One register for every project file: upload, file into folders, track revisions, and send documents in transmittals with a full audit trail. Documents is your project's document register. Every file lives in one place with its folder, revision, status, and history, and everything the project produces elsewhere in Cogram (meeting minutes, filed emails, chat attachments, transmittal packages) is filed here automatically. Open it from **Documents** in a project's sidebar, or see every project at once at [All documents](https://app.cogram.com/dashboard/documents).
A project's Documents register showing the folder rail, several rows, and Rev and status badges.

The register: one row per document, with folder, revision, and status.

## The register Each row is one document: its name, folder, revision (**Rev**), status, latest change note, size, and who updated it last. Click a row to open the document page, with a preview of the file and its full history. Drawings appear in the register too, marked with a drawing icon, so the register is the complete picture of what the project holds. Their sheets, sets, and markups live in [Drawings](/field/drawings); the register shows each drawing's current revision and lets you download or send it. **All documents** shows the same register across every project you can access, with a project column. Uploads, moves, and transmittals from there work per project, exactly as they do inside one. ## Folders Create folders with **New Folder** and file documents the way your office structures a project: for example `01 Correspondence`, `02 Design`, `03 Contracts`. Folders can nest. Cogram maintains a few folders for you: * **Meetings**: minutes and meeting attachments * **Email**: filed email attachments * **Field**: field report exports * **Transmittals**: what each transmittal sent, filed under its number * **Chat**: files shared in project chat These fill automatically as the project works. You cannot move other files into them; everything else is yours to organize. ## Uploading Click **Upload** and pick one or more files, or drop files anywhere on the page. Before anything uploads, Cogram checks each filename against the project: * A new name becomes a **new document**, starting at version 1. * A name that already exists is offered as a **new version** of that document, so a re-issued file extends the history instead of creating a duplicate. Pick a destination folder in the dialog, or pick none and the file shows under All documents. You can also set a revision code for the whole upload (for example `P01` for an issue package); leave it blank and set codes per document later. See [Revisions and versions](/documents/revisions-and-versions). Files up to **5 GB** each can be uploaded, so models, point clouds, and large scan sets go in the register like any other file. The dialog shows each file's progress as it goes up. If the browser tab closes part way through, add the same file again and the upload continues from where it stopped. Uploading from **All documents** adds a **Project** field at the top of the dialog: choose the project first, then the folder and revision follow for that project. If what you are uploading is sheets rather than files, the dialog offers a way out below the staged files: **Uploading drawing sheets? Upload as Drawings** hands them straight to the drawings upload, which reads the title blocks. See [Drawings](/field/drawings). {% hint style="info" %} Uploading from a document's own page always adds a version to that document. If the file's name belongs to a different document in the project, Cogram points that out before you save. {% endhint %} ## Finding documents Search covers names and numbers (and drawing numbers and titles) from the search box above the register. Inside a project, search also matches parts of a name; across all projects it matches from the start of the name. ## Moving, downloading, and deleting Hover a row for quick actions: **Download**, **Move to folder**, and **Delete**. Select several rows and the same actions appear for the whole selection, along with [**Send in Transmittal**](/documents/document-transmittals). Moving a document changes its folder only. The version history and revisions are untouched. Deleting a document deletes every version with it, and Cogram asks first, listing exactly which files the action covers. ## The document page Open any document to see the file itself alongside **History**: one timeline of everything that ever happened to it. The current revision leads the timeline, tagged **Current**, with its declared code, status, latest note, and audit line (`v7 · who · when · size`). Every revision below it is a dot on the same vertical rail, newest first. Click any entry to load that exact file in the preview; the blue dot marks the version you are looking at. A revision that collected several uploads before it moved on shows **N earlier versions**, which expands them as smaller dots on the same rail, so nothing is hidden and nothing is nested away. Download and restore are per-row: hover any entry in the timeline and the two icons appear on the right. Restore brings the old file back as a new current version, and the history keeps everything. See [Revisions and versions](/documents/revisions-and-versions) for how restore interacts with issued revisions.
A document page with the PDF open on the left and the History timeline on the right, the current revision tagged Current.

The document page: file preview beside one History timeline, current revision first.

Below History, **Used in** lists every transmittal that carried this document, with the purpose, date, and precisely which revision and version was sent. ## Next steps * [Revisions and versions](/documents/revisions-and-versions): the model behind the Rev column * [Transmittals](/documents/document-transmittals): issue documents with a formal record * [Drawings](/field/drawings): sheets, sets, and title blocks # Revisions and versions Versions are the automatic audit trail; revisions are the codes you declare and issue. How the two work together, and what issuing a revision freezes. Every document in Cogram carries two kinds of history. They answer different questions, and keeping them separate is what makes the register trustworthy. ## What is a version? A version is a system-generated number that increases each time a file arrives: an upload, or a restore of an older file. You never set it, and it never repeats. For example: 1. You upload `Commissioning Plan.pdf`. It begins as version 1. 2. A colleague uploads a corrected file. The document is now version 2. 3. You restore version 1 to make it current again. Its file comes back as version 3. Versions are the audit trail: every file the project has ever held stays in the history, viewable and downloadable, with who added it and when. Nothing is ever overwritten. {% hint style="info" %} Versions count files, not edits to details. Renaming a revision code or a status change does not create a version. Only a file arriving does. {% endhint %} ## What is a revision? A revision is a code you declare against a document: `P01`, `C01`, `Rev B`, whatever your project's convention is. For a drawing, it should match the revision in the title block, and Cogram reads it from there automatically on drawing uploads. Cogram does not force a format: the code is your project's language. A revision can span several versions. If `P01` had a corrected file uploaded over it before it was ever sent anywhere, both files sit under `P01` in the history. The revision is the name, and the versions are the audit beneath it. Documents without a revision code show a dash in the **Rev** column. That is a perfectly good way to work: if your team does not run formal revisions, versions alone give you the full history, and the Rev column simply stays out of the way. ## Setting and changing a revision * **On upload**, type a code in the upload dialog to apply it to that upload, for example `P02` across an issue package. * **On the document page**, use **Set Revision…** on the current version, or the edit control next to an existing code. * **When uploading to one document**, choose whether the file is **an update to the current revision** (a corrected file under the same code) or **a new revision** with a new code. ## Issuing freezes a revision When a transmittal is sent carrying a document, the exact revision and version that went out become part of the record of what the recipient holds. From that moment the code is frozen, permanently: * The issued version cannot be renamed to a different code. * No new file can be uploaded under that code, and the code cannot be reused later. A changed file needs a new revision. * The register shows a lock next to issued revisions; the tooltip names the transmittals that froze them. This is the core doc-control guarantee: `C01` always means the file that was issued as `C01`. ## Restoring an old version Restore brings a past version's file back as a new current version. The history is never rewritten. When you restore, Cogram asks the same question an upload does: is the returning file an update to the current revision, or the start of a new one? If the current revision was already issued, it stays frozen and the restored file starts a new revision. Set a code on it before the next issue.
The restore dialog with the revision-intent radio buttons and a What changed field.

Restoring a version: choose whether it updates the current revision or starts a new one.

## Statuses Sending a transmittal stamps a status on the exact version it carried, for example **Issued for review** or **Issued for construction**, matching the transmittal's purpose. The status names the last issuance; the full issuance history, with every purpose and date, is on the document page under **Used in**. ## Next steps * [Documents](/documents/documents): the register, folders, and uploads * [Transmittals](/documents/document-transmittals): issuing documents formally # Transmittals Issue documents and drawings with a formal, numbered record of exactly what was sent, to whom, for what purpose, and when. A transmittal is the formal act of issuing documents: a numbered package recording exactly which files (down to the revision and version) left the project, who received them, for what purpose, and when. It is the difference between "I emailed you the plan" and a record you can stand on. Each transmittal gets the next number in the project's sequence, for example `TRA-008`. ## Creating a transmittal Start from wherever the documents are: * **From the register**: select documents (and drawings), then click **Send in Transmittal**. * **From a document's page**: click **Send in Transmittal** to issue that document. * **From the** [**Transmittals tab**](https://app.cogram.com/dashboard/email-inbox/transfers): click **Send files** and add documents in the composer. In the composer, add recipients, a subject (for example *Structural drawings for Building A*), the **Purpose**, an optional due date, and a cover letter or notes for the recipient. You can also drop files from your computer straight into the composer. Each file can be up to **5 GB**, so a full model or a large scan set can go out in a transmittal. The composer shows the file going up and how much of it has been sent; the transmittal is saved as a draft first, so a failed upload can be retried without losing anything.
The Send in Transmittal composer with the project, a recipient, a subject, and two attachments.

Composing a transmittal: project, recipients, subject, and attachments. Purpose and due date sit below.

The purpose states why the package is going out: * Issued for review * Issued for approval * Issued for information * Issued for construction * Issued as requested * Resubmitted ## What sending does Sending is the moment of record: * Each attached document is **pinned at its current revision and version**. The transmittal permanently records, for example, that it carried `C01 · v5`. * That version is **stamped with a status** matching the purpose, shown in the register and on the document page. * The issued revision's code is **frozen**: no new file can ever carry it. See [Revisions and versions](/documents/revisions-and-versions). * Recipients receive the package by email. They do not need a Cogram account. * A copy of what was sent is filed in the project's **Transmittals** folder, under the transmittal's number. {% hint style="info" %} A transmittal that has not been sent is a draft. Drafts pin nothing and freeze nothing. The record is created by sending. {% endhint %} ## Tracking what was issued Two views answer "what did they get": * **The transmittal's page** lists everything the package carried, with each document's pinned revision and version. * **A document's page** shows **Used in**: every transmittal that ever carried it, with purpose, date, and the exact revision and version sent, for example `TRA-009 · Issued for review · Sent as C01 · v5`.
A document page's Used in section listing a sent transmittal with its purpose and the revision and version issued.

Used in: every transmittal that carried this document.

If the same document is issued again later, each issuance keeps its own entry, and the document's status shows the words of the latest one. ## Downloading a transmittal On a transmittal's page, click **Download** and choose: * **PDF**: the cover sheet, for filing and forwarding. * **DOCX**: the same cover sheet as an editable Word document. * **Files (zip)**: the attached documents, with the cover sheet alongside them. Both the PDF and the DOCX render from your organization's transmittal template. Org Admins set one up under [Organization Settings > Templates](https://app.cogram.com/dashboard/settings/admin/templates#transmittals); see [Word templates](/meetings/templates#transmittal-templates). Without a template, both use Cogram's built-in cover sheet. ## Importing transmittals from Newforma If a project moves to Cogram mid-way, the transmittals your team already sent can stay part of the project record. Cogram's numbering then carries on from where the previous system stopped. Upload the transmittal record PDFs that Newforma produced for each transmittal. You need permission to edit the project's settings. 1. Open the project from the [Projects page](https://app.cogram.com/dashboard/projects/), then open its **Settings** tab and choose **Import transmittals** in the left menu. 2. Click **Choose PDFs** and select the transmittal record PDFs. You can upload up to 100 files at a time, each up to 50 MB. 3. Review the preview. Each row shows the transmittal's number, subject, and status. A transmittal the project already holds cannot be selected, and its status says so; click its number to open the one the project already has. A PDF that Cogram cannot read as a transmittal record cannot be selected either. 4. Uncheck anything you do not want, then click **Import**. The button shows how many transmittals you selected. Each imported transmittal keeps its original number, date, subject, purpose, and recipients. It is marked as sent, with the record PDF attached as a project document. Nothing is emailed to the people listed on it. The next transmittal you create continues the sequence. If the highest imported number is `00052`, the next one is `…-TRA-053`. Importing the same PDFs again is safe: every transmittal already in the project is reported as skipped, and nothing is duplicated. If every file you pick is already in the project, Cogram says so instead of offering the import. **View all transmittals** next to the Choose PDFs button opens the register for the project you are in, where the imported transmittals live. ## Troubleshooting **A document I want to send is grayed out in the register selection.** Transmittals send from one project at a time. If your selection spans projects, the send button explains this. Narrow the selection to one project. **I need to send a corrected file for a revision that already went out.** The issued code is frozen. Upload the corrected file as a new revision (for example `C02`) and issue that. The record of what `C01` was stays intact. ## Next steps * [Documents](/documents/documents): the register and folders * [Revisions and versions](/documents/revisions-and-versions): what issuance freezes and why # Virtual meetings Learn how to use Cogram in virtual meetings in Microsoft Teams, Zoom, or Google Meet. Cogram distinguishes between: * **scheduled** meetings, that are upcoming * **live** meetings, that are ongoing * **processing** meetings, for which Cogram is currently drafting notes * **completed** meetings, that are finished ### Reading the calendar colors On your [Meetings dashboard](https://app.cogram.com/dashboard/meetings), each event is color-coded so you can see its state at a glance: | Color | Meeting state | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | ![](https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-4aa5bcf6d8a5eb66b0a5aa52dfc428851b55cdef%2Fswatch-lightblue.png?alt=media) Light blue | Upcoming: Cogram is not scheduled to attend | | ![](https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-1ba7da956025a47d7cba5b14078282313999b413%2Fswatch-blue.png?alt=media) Blue | Scheduled: Cogram will attend and take notes | | ![](https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-c34ed92498803e6b81ed03da15ea1adf2a94dcbe%2Fswatch-teal.png?alt=media) Teal | Live: Cogram is recording or drafting notes | | ![](https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-7e8a19093a17ae882fc291de4def3edcf37ae721%2Fswatch-green.png?alt=media) Green | Completed: notes are ready | | ![](https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-7378b5dcf248497a8e6a761f847c3a00a554d9f5%2Fswatch-gray.png?alt=media) Gray | Not recorded: a past meeting with no notes, or Cogram could not join. A struck-through title means every invitee declined | > **Note**: On the dark theme these appear as lighter tints, but the meanings are the same. ## To Schedule Cogram for Meetings You can schedule Cogram to draft minutes in a virtual meeting by either > **Heading to your** [**Meetings**](https://app.cogram.com/dashboard/meetings) **dashboard in the left sidebar, clicking on an event, and toggling "Attend"** or from your own Outlook or Google Calendar application by > **Forwarding any meeting invite to ****.** Finally, you can also add Cogram to a live meeting by pasting the meeting URL into the form at the top of your [Meetings](https://app.cogram.com/dashboard/meetings) dashboard, and clicking "Attend Now". ### Inviting Cogram by Email When you send a meeting to ****, two things need to be true for Cogram to attend the meeting: 1. The address the email is sent *from* must belong to a Cogram user, or be registered as an *authorized email invite user* on a Cogram user's account. 2. The email must include the original calendar invitation as an attachment, so that Cogram can read the meeting link, organizer, and attendees. The most reliable ways to add Cogram to a meeting by email are to add **** as an attendee directly on the meeting and send the update, or, in Outlook, to use **"Forward as iCalendar"** rather than the standard "Forward" option. > **Note**: Outlook's standard "Forward" on a meeting often sends the message as plain text and removes the calendar attachment. Server-side Outlook or Exchange auto-forward rules typically strip calendar attachments as well. If the attachment is missing, Cogram will not receive a valid invitation. If you would like to schedule Cogram for many meetings on an ongoing basis, we recommend [connecting your calendar](/meetings/connecting-your-calendar) instead. With the calendar connected, Cogram joins meetings based on your calendar events and you do not need to forward invitations. #### Authorized email invite users If you would like someone else (for example, an executive assistant, a shared mailbox, or an automation account) to invite Cogram on your behalf, add their email address under **Authorized email invite users** in [**Account Settings → Notetaker**](https://app.cogram.com/dashboard/settings/account-settings/meetings). Once added, emails from that address to **** will be processed as if you sent them. #### Microsoft Bookings and Power Automate To automatically schedule Cogram for all meetings created through Microsoft Bookings, we recommend [connecting the Bookings host's calendar](/meetings/connecting-your-calendar) to Cogram. Cogram will then join meetings based on calendar events without any manual forwarding. If you prefer to use Power Automate to add **** as an attendee on Bookings meetings, make sure that: * The Bookings host has a Cogram account, or their email address is added as an authorized email invite user on a Cogram user's account. * The Power Automate flow explicitly sends a meeting update after adding the attendee. Adding an attendee silently, without sending an update, will not deliver an email to Cogram. #### Organization restrictions If your organization has the **Only Event Organizers Can Add Cogram** setting enabled, only the meeting organizer can invite Cogram by email. Forwards or invitations sent by attendees who are not the organizer will be rejected. Org Admins can review this setting in [**Organization Settings → Notetaker**](https://app.cogram.com/dashboard/settings/admin/meetings). *** ## **Live Meetings** Head to your [Meetings dashboard](https://app.cogram.com/dashboard/meetings/schedule/) in the left sidebar and click on a blue event for which you have scheduled Cogram to take notes, then click "View Details", to open the page for that meeting. At the top of the page, you will see an overview of the meeting, showing the title, date and time, duration, and participants of the meeting. If the meeting is live, you will see the status indicator displaying "Live". The "Transcript" tab will show a live speaker timeline. ### Pausing, Resuming, and Ending note-taking You can pause/resume note-taking by clicking the pause/resume icon in the status indicator, and can end note-taking by clicking "Leave" next to the status indicator. ### My Notes Click on the "My Notes" tab, below the "Transcript" tab, to take manual notes. Hit the tab key to create different levels of indentations for bullet point notes. *** ## **Completed Meetings** After the meeting ends, Cogram will summarize the meeting, create detailed bullet point notes that are structured by topics, and identify action items. All of Cogram's meeting insights can be edited and formatted. ### Managing Action Items To mark an action item as done, click the "Done" indicator, to the left of the item. To delete an item permanently, click the **Trash** icon to the right. Marking an item **Done** only hides it on reload; deleting removes it for good. All action items from your meetings are also stored on the [Action Items page](https://app.cogram.com/dashboard/meetings/action-items). ## Post-Meeting Summary Email Cogram can automatically send you a summary email after each meeting ends. This is toggled in [**Account Settings → Meetings**](https://app.cogram.com/dashboard/settings/account-settings/meetings). > **Note**: If your organization has locked this setting, the toggle will appear grayed out with a lock icon and cannot be changed. Contact your Org Admin if you need it changed. ### Setting a default for your organization (Admins) Org Admins and Owners can set and lock the post-meeting email default for all members in [**Organization Settings → Meetings**](https://app.cogram.com/dashboard/settings/admin/meetings). | State | What the end user sees | | ------------ | --------------------------------------------------------------------- | | **Unlocked** | The default is pre-set, but the user can toggle it on or off. | | **Locked** | The toggle is grayed out with a lock icon. The user cannot change it. | # In-person meetings Record in-person meetings with the Cogram mobile app or from your browser, and get drafted minutes when you end the meeting. Record a site meeting or OAC meeting on your phone or laptop, and Cogram drafts the minutes when you end it. On mobile you can also take photos during the recording, and the recording keeps working with poor signal. ## Recording on your phone 1. On the **Home** tab of the [mobile app](/get-started/mobile-app), tap **Record Meeting**. 2. Enter a title, pick the **Project** and language, and tap **Start Meeting**. While recording, the screen shows a timer and a live waveform, and stays awake: * Tap the camera to take photos during the meeting. They attach to the meeting and appear on its page afterward. * Pause and resume whenever you step out. * Tap **End Meeting** when you are done. The recording uploads and Cogram drafts the minutes; with no signal, the upload waits until you are back online (see [Working offline](/field/working-offline)). If the app closes mid-recording, nothing is lost: on reopening it shows "Unsaved recording", and you choose **Keep & Save** or **Discard**.
A meeting being recorded on mobile, with the timer, live waveform, camera and pause buttons, and End Meeting

Recording an in-person meeting

Once processed, the meeting's page on your phone shows the summary and bullet notes, and the full minutes are on the [Meetings page](https://app.cogram.com/dashboard/meetings/) on the web. **Save Recording** on the meeting page shares the raw audio file if you ever need it. {% hint style="info" %} Cogram detects different speakers by voice and labels them "Speaker 1", "Speaker 2", and so on. It typically needs at least 30 seconds of speech from a person to identify them reliably. You can name the speakers afterward (below). {% endhint %} ## Recording from your browser Meeting in a conference room with a laptop? Open [Meetings > In Person](https://app.cogram.com/dashboard/meetings/in-person) in the web app, set the meeting name and language, and click **Start Meeting**.
The In Person meeting start form with Meeting Title, Project, and Meeting Language fields and a Start Meeting button

Starting an in-person meeting from the web app

Grant Cogram microphone access when your browser asks. Cogram transcribes the conversation and drafts minutes when you click **End Meeting**. ## Naming speakers After a meeting is completed, open it on the web and scroll to **Participants** in the Overview section. Click a speaker's name to rename them. Cogram then offers **Regenerate Notes** to update the minutes and summaries with the real names. ## Related * [Cogram on your phone](/get-started/mobile-app): installing the app and signing in. * [Create a field report on site](/field/field-reports): documenting a site visit with observations and photos. * [Downloading, sharing, and templates](/meetings/downloading-sharing-and-templates): exporting the finished minutes. # Audio upload Upload a meeting recording to generate a transcript, summary, and action items, even if Cogram was not in the meeting. If Cogram did not attend a meeting live, you can upload a recording afterward to generate a full transcript and meeting notes. ## Uploading a recording 1. Go to [Meetings > Audio Upload](https://app.cogram.com/dashboard/meetings/audio-upload). 2. Fill in the required fields: * **Meeting Title**: a descriptive name for the meeting. * **Meeting Language**: the language spoken in the recording. Defaults to your account transcription language preference. * **Recording Audio File**: click to browse and select an audio file. Any standard audio format is accepted. * **Meeting Datetime**: the date and time the meeting took place. Defaults to now. 3. Click **Upload**.
The Audio Upload form with Meeting Title, Project, Meeting Language, Recording Audio File, and Meeting Datetime fields and an Upload button

The Audio Upload form

A progress bar shows the upload status. Once complete, a success message appears with a link to the newly created meeting. The meeting is then processed in the background: transcription and note generation typically take a few minutes depending on the recording length. ## After uploading The uploaded recording appears in your [Meetings list](https://app.cogram.com/dashboard/meetings/all) with the source label "Audio Upload". Open it to view the transcript, summary, and action items, just like any other meeting. You can upload another recording as soon as the first finishes. Once processing completes, open the meeting to review its summary and action items. # Downloading, sharing, and templates Learn how to share, export, or download Cogram's meeting notes. From your [Meetings](https://app.cogram.com/dashboard/meetings) page, click on a meeting to open the page for that meeting. ### Template Download Click the "Download" button at the top right to download Cogram's meeting minutes into a Word (.docx) template. Out of the box you get Cogram's default template, **Default Cogram Concise Minutes**, and you can pick any template your organization has added. Your organization's Cogram administrators may have provisioned custom templates for meeting minutes or field reports in Cogram. Field reports are downloaded the same way: open the report on the web and click **Download** to export it against a template. See [Create a field report on site](/field/field-reports). To add a custom template or change an existing one's style, format, or components, see [Word templates](/meetings/templates). ### Condense the minutes On a meeting page, use the **Condense** button (top right) to switch to a shorter version of the minutes, grouped by discipline. Select **Show full** to switch back. Condensing never changes the underlying minutes; you can toggle it at any time. Condense affects two insights only: * **Minutes** — the `{{minutes}}` placeholder in your templates * **Bullet points** — the `{{bullet points}}` placeholder Every other insight is unchanged, including Summary, Executive Summary, Key Points, Tabular Minutes, action items, and any custom insights your organization has added. Tabular Minutes is a table, so it always renders in full. The switch applies on screen and to anything you download: while a meeting is condensed, templates fill those two placeholders with the shorter version, and the rest of the template is unaffected. *** ### Share Click the "Share" button at the top right to generate a unique sharing link. Anyone with the link can open a read-only version of the meeting page, which excludes your own manually written notes. Share it only with people you trust. ### Automatic share-link emails to invitees Organization admins can turn on share-link emails under [Organization Settings > Meetings](https://app.cogram.com/dashboard/settings/admin/meetings) (the **Minutes Sharing** section). When enabled, Cogram emails a link to the draft meeting minutes to all calendar invitees who are members of your organization, as soon as the minutes are ready. Invitees receive a single email from Cogram, with the meeting host in Cc; replies go to the host. External invitees never receive these emails. Unlike the link from the **Share** button, the emailed link is internal to your organization: recipients sign in to their Cogram account to open it, and only members of your organization can view it. Invitees can view the meeting even before it is filed to a project. Emailed links expire after 30 days; if a link has expired, ask the meeting host to share the meeting again. Recipients can opt out under [Account Settings > Notifications](https://app.cogram.com/dashboard/settings/account-settings/notifications) with the **Shared meeting minutes** setting. Revoking a meeting's share access (click **Share**, then **Revoke link**) invalidates the public share link and all previously emailed links for that meeting. ### Sharing via Email After every meeting, your notetaker emails you a follow-up with the summary and notes. You can forward this email to other participants from the meeting. {% hint style="info" %} Unless your organization has enabled share-link emails to invitees, Cogram never automatically emails other meeting participants. {% endhint %} If you would no longer like to receive Cogram's follow-up email, please send an email with the subject line "unsubscribe" to [hi@cogram.com](mailto:hi@cogram.com?subject=unsubscribe). ### Export To export Cogram's transcript, notes, action items, or meeting summary, click "Export" at the top right. This will open a modal and allow you to select what to include in the export. Click "Copy to Clipboard" to export, and paste into tools like Word, Email, or your Project Management platform to import. The pasted text keeps basic meeting write-up formatting and starts with the meeting overview. # Connecting your calendar Connect your Google or Outlook calendar so you can invite Cogram to meetings in one click and have it join recurring meetings automatically. To do so, head to [**Account Settings → Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations) and select the calendar you would like to connect. Next, choose if you want Cogram to * join all meetings on your Calendar automatically * join only meetings that you host automatically * or not join any meetings automatically. Then authenticate using your Google or Microsoft account to approve Cogram's calendar connection. > **Note**: If your organization has locked this setting, the attendance behavior dropdown will appear grayed out with a lock icon. You will not be able to change it. Contact your Org Admin if you need it changed. ## Setting a default for your organization (Admins) Org Admins and Owners can set a default attendance behavior for all members in [**Organization Settings → Integrations**](https://app.cogram.com/dashboard/settings/admin/integrations). This pre-fills the dropdown for every user in the organization. | State | What the end user sees | | ------------ | ----------------------------------------------------------------------- | | **Unlocked** | The default is pre-selected, but the user can change it. | | **Locked** | The dropdown is grayed out with a lock icon. The user cannot change it. | {% hint style="info" %} In some cases, your IT organization may require you to request approval from an IT administrator to complete the integration. Documentation on how administrators can approve Cogram's calendar integration is available at [Authorizing calendar integration](/meetings/authorizing-calendar-integration). {% endhint %} After connecting your calendar, head to your [Meetings dashboard](https://app.cogram.com/dashboard/meetings/schedule) to invite Cogram for note-taking in virtual meetings. # Creating a contact for your Notetaker Save a contact for Cogram in your Outlook or Google Calendar so you can invite it to meetings just by forwarding an event to . **To do so:** 1. Create a new contact in your Outlook or Google Calendar 2. Assign it the same name that you've selected for your Cogram notetaker, or just "Cogram" 3. Assign the email "" **You can now schedule Cogram to join any meeting by** * forwarding Email invites to your Cogram contact * or by adding your Cogram contact as a meeting invitee, when you schedule meetings. When you schedule Cogram to join meetings, those meetings will be visible in your [Invite Cogram](https://app.cogram.com/dashboard/meetings/schedule/) dashboard. # Renaming your Notetaker The name that your Cogram Notetaker displays when joining a virtual meeting can be changed under [Account Settings > Meetings](https://app.cogram.com/dashboard/settings/account-settings/meetings). This applies to Zoom, Microsoft Teams, and Google Meet meetings. Webex does not support custom notetaker names. ## Setting a default for your organization (Admins) Org Admins and Owners can set a default Notetaker name that applies to all members of the organization. This is configured under [Organization Settings > Meetings](https://app.cogram.com/dashboard/settings/admin/meetings). The name supports two template variables that are replaced automatically per user: * `{{first name}}`: the user's first name * `{{organization name}}`: the name of your organization For example, `{{first name}}'s {{organization name}} Notetaker` would render as **Alex's Acme Corp Notetaker** for a user named Alex. When saving the organization default, you can choose to **lock** or **leave unlocked**: | State | What the end user sees | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | **Unlocked** | The default value is pre-filled in their settings, but they can edit and save their own name. | | **Locked** | The field is grayed out with a lock icon. They cannot edit it. Hovering shows "Notetaker name is set and locked by your organization." | > **Note**: If your organization has locked this setting, you will not be able to edit the Notetaker name field. Contact your Org Admin if you need the name changed. # Transcription language Request early access to use Cogram in non-English languages By default, Cogram works only in English. If you would like early access to other languages, please reach out to . Once multi-lingual functionality is enabled for your account: * head to [Account Settings > Meetings](https://app.cogram.com/dashboard/settings/account-settings/meetings) and use the "Transcription language" drop-down to select a language. * Then click "Save" to update the language. Change the transcription language before you invite Cogram to a meeting; the change takes effect for meetings Cogram joins afterwards. # Invitee domain lists Control which participant email domains Cogram is allowed or blocked from joining meetings with. Cogram can be configured to only join (or never join) meetings that include participants from specific email domains. This is useful for enforcing privacy boundaries, such as preventing Cogram from recording meetings with external parties. These settings are under [Account Settings > Meetings](https://app.cogram.com/dashboard/settings/account-settings/meetings). ## Allow List When an allow list is set, Cogram will only join meetings where all participants are from one of the listed domains. Meetings that include participants outside the listed domains will not be attended. Leave the allow list empty to place no domain restrictions on who Cogram can join meetings with. ## Block List When a block list is set, Cogram will not join any meeting that includes a participant from one of the listed domains, even if you have scheduled it to attend. ## Setting defaults for your organization (Admins) Org Admins and Owners can set and lock domain lists for all members under [Organization Settings > Meetings](https://app.cogram.com/dashboard/settings/admin/meetings). This is useful for enforcing a consistent privacy policy across the organization. | State | What the end user sees | | ------------ | -------------------------------------------------------------------------- | | **Unlocked** | The org default is pre-filled, but the user can add or remove domains. | | **Locked** | The field is grayed out with a lock icon. The user cannot modify the list. | > **Note**: If your organization has locked these settings, you will not be able to edit the domain lists. Contact your Org Admin if you need them changed. # Cogram for Zoom This page walks you through how to enable Cogram for your Zoom meetings, how to use Cogram in a Zoom meeting, and how to remove Cogram again. ### Requirements 1. An active Cogram account. If you don't have an account, reach out to . ### Enabling Cogram for Zoom The Cogram Zoom app is not publicly listed on the Zoom Marketplace. To get access, contact our support team at and we'll provide you with an install link to connect Cogram to your Zoom account. Once you receive the link: 1. Click the install link provided by the Cogram team. 2. Authorize Cogram to access your Zoom account when prompted. 3. You'll be taken to the Cogram web app and are now ready to use Cogram in your Zoom meetings. ### Using Cogram in Zoom Meetings 1. Start or join the Zoom meeting you'd like Cogram to join. Copy the meeting URL. 2. Visit the Cogram app. If you've connected your calendar, click "Attend" on the relevant event. Alternatively, paste the meeting URL into the field near the top of the page and click "Attend Now". 3. Admit "Cogram Notetaker" to your meeting and grant recording permissions once requested. 4. Complete your meeting. 5. Cogram will now generate a summary, bullet point notes, a list of action items, and other meeting insights for you. ### Removing Cogram from Zoom Cogram is not permanently linked to your Zoom account. To remove it, stop inviting Cogram to your Zoom meetings. # Word templates Upload Word (.docx) templates so your team can export meeting minutes and field reports in your organization's own layout. Templates let your team download meeting minutes as a Word document in your organization's layout: your letterhead, your styles, and exactly the sections you want. Org Admins manage them under [Organization Settings > Templates](https://app.cogram.com/dashboard/settings/admin/templates). The Templates page also holds templates for Field Reports (covered in [Field Report templates](#field-report-templates) below) and, depending on your organization's licensed modules, Transmittals, RFIs, and Submittals.
Organization Settings Templates page showing the Meetings template list with a Cogram Default badge and the New Meeting Template button

Meeting templates in Organization Settings > Templates

## How templates work A template is a regular `.docx` file containing **placeholders**: markers like `{{summary}}` that Cogram replaces with generated content when a member downloads the minutes. Everything else in the file (headers, logos, styles, static text) is kept as-is. * The exported document only contains the content whose placeholders appear in the template. To leave a section out (for example the summary), don't include its placeholder. * Placeholders are case-sensitive and must match exactly, including both curly braces. * Your [Custom insights](/meetings/custom-insights) are available as placeholders too, so a template can export any output you've defined. Organization-level insights carry an `(Org)` suffix in their name, and the placeholder must include it, for example `{{Consolidated Minutes (Org)}}`. * Two newer building blocks are `{{key points}}`, a condensed one-line-per-point version of the meeting notes (used by the Concise Minutes template below), and `{{meeting number}}`, the meeting's sequential number within its project. To see every placeholder available to your organization (meeting details, generated sections, and your Custom Insights), click **New Meeting Template** under [Organization Settings > Templates](https://app.cogram.com/dashboard/settings/admin/templates), then **View all elements**. Click any element to copy it. You can also click **Download Sample Template** on the same page to start from a working example. ## Cogram-provided templates Cogram ships ready-made meeting templates you can use as a starting point. Find them in the **Provided by Cogram** section at the top of [Organization Settings > Templates](https://app.cogram.com/dashboard/settings/admin/templates): * **Default Cogram Concise Minutes**: short bullet-style notes: attendance, executive summary, key points, and proposed actions. This is Cogram's default (see [Set an organization default](#set-an-organization-default)). * **Cogram Detailed Minutes**: formal project minutes: attendance and distribution, numbered minutes with status, action items, and a corrections notice. * **Cogram Tabular Minutes**: minutes as a numbered items table (Item Number, Description, Action By), alongside attendance. For the Detailed and Tabular templates, select **Add to my templates** to place an editable copy in your organization's templates. Cogram then asks whether to set the copy as your organization default. Use **Download** on any row to save the `.docx` as-is. ## Preview a template To see what a template produces before you use it, click its row in the template list, or in the **Provided by Cogram** section. Cogram shows a page-accurate preview of the Word document. Placeholders appear as their `{{markers}}`; they fill in with a meeting's content when someone exports that meeting. ## Add a meeting template (Org Admins) 1. Prepare a `.docx` document with your layout, and insert placeholders where Cogram content should go. 2. Go to [Organization Settings > Templates](https://app.cogram.com/dashboard/settings/admin/templates) and click **New Meeting Template**. 3. Enter a template name (this is what members see when picking a template) and select your `.docx` file. 4. Click **Save Template**.
The Create new meeting template page with the Template Name and Template File fields, and the template guide with Download Sample Template and View all elements buttons

The Create new meeting template page

Cogram validates the file on upload: it must be a valid `.docx`, contain at least one placeholder, and use only recognized placeholders. If validation fails, the error message tells you what to fix. To swap the file behind an existing template, use its **Replace** action in the template list. The new file is validated the same way, and the template keeps its name and default status. To rename a template, use its **Rename** action. The Cogram-provided template cannot be renamed. A template that is currently the organization default cannot be renamed in place: clear its default first, rename it, then set it as the default again. ## Set an organization default In the template list, use a template's **Set as Organization Default** action to make it the preselected choice for everyone in your organization. Only validated templates can be set as the default. Clearing the default reverts to Cogram's provided default, **Default Cogram Concise Minutes**. The previous default, **Default Cogram Provided Template**, is deprecated and scheduled for deprecation on October 1, 2026. If your organization still relies on it, add and set your own default before then. ## Download minutes with a template On a completed meeting page, any member clicks **Download** at the top right and selects a template. Cogram fills the placeholders with that meeting's content and downloads the Word document. See [Downloading, sharing, and templates](/meetings/downloading-sharing-and-templates) for the full download and sharing options. ## Field Report templates Field Report templates work the same way: a Word document with placeholders, used when exporting a field report. The form fields available as placeholders come from the report's [Report Type](/field/report-types). ### Add a Field Report template (Org Admins) 1. Go to the [Field Reports section](https://app.cogram.com/dashboard/settings/admin/templates#field-reports) of the Templates page. 2. Click **New Report Template**. 3. Enter a **Template Name** and select your `.docx` file. 4. Click **Save Template**. The create page lists every placeholder available to you. Click **View all elements**, then click any element to copy it.
The Field Reports section of the Templates page showing the template list and the New Report Template button

Field Report templates in Organization Settings > Templates

Cogram checks that the file is a valid Word document when you upload it. To also check the placeholders, use the **Validate** action on the template's row: it points out any placeholder that does not match a builtin or one of your [Custom fields](/field/custom-fields). By default, every Field Report template is offered when downloading any report. To narrow the choice for a specific Report Type, link templates to it in the Report Type's **Linked Templates** section. See [Report types](/field/report-types). ### Field Report placeholders You can use three kinds of placeholder in a Field Report template. **Builtins.** Cogram fills these in automatically: | Placeholder | What it fills in | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `{{ title }}` | The report's title | | `{{ author }}` | The email address of whoever created the report | | `{{ project name }}` | The project's name | | `{{ project id }}` | Your own project number, as set on the project | | `{{ status }}` | The report status, for example "DRAFT" or "FINAL" | | `{{ date }}` | The date the report was created, for example 07/30/2026 | | `{{ time }}` | The date and time the report was created, for example 2026-07-30 14:05:00 | | `{{ dotw (english) }}` | The day of the week, for example "Monday" | | `{{ address }}` | The site address, from the report's location | | `{{ weather }}` | The weather at the report's location | | `{{ executive summary }}` | A summary of the observations, written by Cogram | | `{{ metadata }}` | A table of all the report's custom field values | | `{{ total observations }}` | The number of observations on the report | | `{{ total photos }}` | The number of photos across all observations | | `{{ observations }}` | The full observations section, laid out per the Report Type's [Format the Export](/field/report-types#format-the-export) settings | **Custom field placeholders.** Every custom field on the report's Report Type is available under its Template Placeholder name: a field named `client_firm` fills `{{ client_firm }}`. See [custom fields](/field/custom-fields). **Table placeholders.** For a Table field, put the placeholder in one row of a Word table. On export, that row repeats for every entry your team added, keeping your styling. For example, for a `persons_present` field with columns Name, Role, and Company: | Name | Role | Company | | ----------------------- | ---- | ------- | | `{{ persons_present }}` | | | If someone enters three people on the report form, the exported table shows three rows. {% hint style="info" %} If a placeholder comes through unfilled in the export, Word may have split it into pieces while you typed. Select the placeholder in Word, retype it in one go, save, and upload the file again. {% endhint %} ## Transmittal templates If your organization licenses Transmittals, the **Transmittals** section of [Organization Settings > Templates](https://app.cogram.com/dashboard/settings/admin/templates#transmittals) holds one cover-sheet template for your organization. One template covers both download formats. When a member downloads a transmittal as **PDF** or as **DOCX**, both come from the template you upload here, so the PDF you file and the Word document you edit are the same cover sheet. Until you upload one, transmittals use Cogram's built-in cover sheet, which carries the logo from your [navigation bar branding](/organization-administration/navigation-bar-branding). ### Add a transmittal template (Org Admins) 1. Click **Download sample** in the Transmittals section to start from Cogram's own cover sheet. 2. Edit the `.docx` in Word: apply your letterhead and styles, and keep or move the placeholders you want. 3. Click **Upload template**, enter a name, and select your file. Cogram validates the file on upload. A template that fails validation is not used: transmittals fall back to the built-in cover sheet until you replace it. ### Expected result Open any sent transmittal, click **Download**, and choose **PDF**. The cover sheet is your layout, with this transmittal's number, recipients, and documents filled in. Choosing **DOCX** gives you the same sheet as an editable Word file. ### Transmittal placeholders | Placeholder | What it fills in | | -------------------------- | ------------------------------------------------------------------ | | `{{ transmittal number }}` | The transmittal's number, for example TRA-078 | | `{{ date }}` | The date the transmittal was sent | | `{{ subject }}` | The transmittal's subject | | `{{ purpose }}` | Why it was issued, for example "Issued for construction" | | `{{ status }}` | The current status, for example "Sent" | | `{{ due date }}` | The response due date, when one is set | | `{{ project name }}` | The project's name | | `{{ project number }}` | Your own project number, as set on the project | | `{{ sender name }}` | The full name of whoever sent the transmittal | | `{{ sender company }}` | The sending organization's name | | `{{ sender email }}` | The sender's email address | | `{{ to recipients }}` | A table of the To recipients: name, company, email | | `{{ cc recipients }}` | A table of the copied recipients: name, company, email, discipline | | `{{ documents }}` | A table of the documents issued: quantity, dated, title, notes | | `{{ remarks }}` | The remarks entered on the transmittal | ### Troubleshooting **Symptom.** Cogram rejects the file when you upload or replace a template. **Likely cause.** The file is not a valid `.docx`, or it uses a placeholder that is not in the table above. **Fix.** The error appears in the upload dialog as soon as you select the file, and it names what to correct. Fix the file in Word and select it again — a rejected template is never saved, so there is no row to revisit later. **Symptom.** A field on the cover sheet is blank. **Likely cause.** The placeholder is spelled differently from the table above, or Word split it into pieces while you typed. **Fix.** Select the placeholder in Word, retype it in one go, save, and upload the file again. # Insight preferences Tell Cogram how to write your AI-generated insights: tone, length, level of detail, and language. Insight Preferences tell Cogram how to write your AI-generated insights: the tone, length, level of detail, and language used in summaries, bullet points, minutes, and your Custom Insights. Preferences change **how existing insights are written**. To add a new output (a follow-up email, a translated summary), use [Custom insights](/meetings/custom-insights) instead. ## When to use this * Your minutes are too long, too short, or too informal for your client * You want consistent terminology across a project team * You want insights written in another language * One insight type needs different treatment from the rest ## Set your own preferences 1. Open the avatar menu at the bottom of the left sidebar and go to [Account Settings > Meetings](https://app.cogram.com/dashboard/settings/account-settings/meetings). 2. Select **Insight preferences** in the left column. 3. Under **All insights**, describe how you want insights written. For example: `Write in a formal tone. Use UK spelling. Keep summaries under 200 words and lead with decisions.` 4. Select **Save**. Each preference holds up to 4,000 characters. **Expected result:** meetings processed from now on follow the preference. Meetings Cogram has already processed keep the insights they have. ## Set a preference for one insight type Use this when only one output needs to change: for example, minutes must stay formal while bullet points stay terse. 1. In the same section, go to **Per-insight preferences**. 2. Select **Add preference for...** and choose the insight type. 3. Enter the instruction and select **Save**. Per-insight preferences apply on top of your **All insights** preference. ## Organization and group preferences Preferences exist at three levels, and a meeting uses all of them together: | Level | Who sets it | Where | | ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | Organization | Admins | [Organization Settings > Meetings](https://app.cogram.com/dashboard/settings/admin/meetings) → **Insight preferences** | | Group | Group Admins | [Group Settings](https://app.cogram.com/dashboard/settings/group/all) → your group → Meetings → **Insight preferences** | | Personal | Each user | [Account Settings > Meetings](https://app.cogram.com/dashboard/settings/account-settings/meetings) → **Insight preferences** | Cogram sends all applicable preferences to the AI together, in the order organization, then group, then personal. They combine rather than replace each other, so keep them short and avoid contradicting a level above you: if the organization asks for formal language and you ask for casual, the result is unpredictable. Preferences you inherit are listed read-only under **Inherited preferences**, so you can see what already applies before adding your own. Group preferences reach a user through their **settings group**: the one group whose settings cascade to them. See [Groups](/organization-administration/groups). > Cogram's insights are AI-generated drafts. Always review names, dates, decisions, action items, and technical values before issuing minutes, whatever preferences you set. ## Troubleshooting **An existing meeting still shows the old wording** *Likely cause:* preferences apply when insights are generated. Saving a preference does not rewrite meetings Cogram has already processed. *Fix:* apply the preference to future meetings, or copy the insight and edit it by hand for this one. **A colleague's meeting ignores my personal preference** *Likely cause:* Cogram applies the preferences of the meeting's owner, not the person reading or downloading it. *Fix:* set the preference at organization or group level so it applies to everyone's meetings. **Emptying the box does not clear the preference** *Likely cause:* **Save** stays unavailable while the field is empty. *Fix:* select **Remove** to delete the preference. **The preference seems to be ignored** *Likely cause:* preferences at all three levels are combined, and a long organization preference can crowd out shorter ones. *Fix:* shorten the instruction, make it specific ("Use UK spelling"), and check **Inherited preferences** for a conflicting instruction set above you. ## Next steps * [Custom insights](/meetings/custom-insights): create new AI outputs rather than reshaping existing ones * [Word templates](/meetings/templates): control which insights appear in your exported minutes # Custom insights Custom Insights let you control your meeting notes’ length, tone, format, or language, draft follow-up emails, or automate other post-meeting outputs.\ \ To get started, open the avatar menu at the bottom of the left sidebar and go to [Account Settings > Meetings > Custom Insights](https://app.cogram.com/dashboard/settings/account-settings/meetings#custom-insights). Create a new insight, or use one of the existing templates. To change how your existing insights are written (tone, length, or language), see [Insight preferences](/meetings/insight-preferences) instead. A Custom Insight needs to have a title and a prompt. A prompt tells Cogram what to do with your meeting: its transcript, details, or other insights like the summary. Write a prompt and add **Elements**. Elements are dynamic placeholders for key information from your meeting that Cogram processes to create your insight. For example, for Cogram to write a meeting summary we provide it with the `{{meeting title}}` and meeting `{{transcript}}`. When a meeting completes, Cogram replaces these placeholders with the relevant information from the meeting, and then generates your Custom Insight.\ \ After writing your prompt, save and activate your Custom Insight. Cogram then generates it for every future meeting it attends. It won't run on meetings that already ended, and you can deactivate it any time to stop. **Below are four example Custom Insights for different use cases, with their example outputs. Copy one of them, head to Custom Insights, click "New Custom Insight" and paste the copied prompt. Then save and activate the insight.**

Image 1

When your next meeting ends, you can view the Custom Insight by opening the meeting and selecting it in the meeting sidebar, under the **Custom** group. {% content-ref url="/pages/iwPo3bfQcZ35jSQKTTam" %} [Summary and next steps](/meetings/custom-insights/summary-and-next-steps) {% endcontent-ref %} {% content-ref url="/pages/mReEezUMRuIjDGFSraON" %} [Follow-up email](/meetings/custom-insights/follow-up-email) {% endcontent-ref %} {% content-ref url="/pages/PLg6tmLUYMcPhzkaS18J" %} [Board meeting minutes](/meetings/custom-insights/board-meeting-minutes) {% endcontent-ref %} {% content-ref url="/pages/RZa5T8S81wkocDGPRvPY" %} [Summary translation](/meetings/custom-insights/summary-translation) {% endcontent-ref %} # Summary and next steps Use this example to have Cogram draft a summary and next-steps list after each meeting. Copy it as-is, or adjust the prompt to fit your needs. To set this up, see [Custom Insights](/meetings/custom-insights). {% tabs %} {% tab title="Custom Insight Prompt" %} Using the provided transcript of a virtual meeting, first, write a professional executive summary. The summary must be under 50 words and provide a concise overview of the key meeting outcomes. Use the past tense and a professional tone. Then write a concise list of key next steps for the meeting participants with assignees. Meeting title:\ `{{meeting_title}}` Invitees:\ `{{invitees}}` Meeting transcript:\ `{{transcript}}` Now, first, write a concise, high-quality executive summary based on the meeting transcript, that focuses on key discussions and outcomes. Then write a concise list of the most important next steps with assignees. {% endtab %} {% tab title="Example Output" %} During the meeting, May provided an update on the progress of the teamwork, stating that the structural work is nearly complete despite weather delays. They are adjusting shifts to mitigate further delays. May also mentioned that materials have been sourced for the updated specifications, but there have been quality issues with the new glass. The interior construction is on schedule, with a focus on plumbing and electrical infrastructure. May proposed discussing intricate lighting designs for the communal area and setting up a technical meeting. May reminded Alexander to finalize the landscapes by next Friday. The meeting concluded with plans to reconvene at the same time. **Next Steps:** 1\. Coordinate a technical meeting to confirm the electrical load capacity for the intricate lighting designs in the communal area on the 125th floor. * Assignee: Arun Lynn * Deadline: Coordinate and send time slots for the meeting by end of day Friday 2\. Finalize landscapes to stay on schedule with the outdoor areas. * Assignee: May Roark (to relay to landscape team) * Deadline: Provide landscape plans by next Friday {% endtab %} {% endtabs %} # Follow-up email Use this example to have Cogram draft a follow-up email after each meeting. Copy it as-is, or adjust the prompt to fit your needs. To set this up, see [Custom Insights](/meetings/custom-insights). {% tabs %} {% tab title="Custom Insight Prompt" %} Use the provided meeting summary of a virtual meeting to write a short, professional follow-up email that recaps the key meeting outcomes and next steps. Meeting title:\ `{{meeting_title}}` Invitees:\ `{{invitees}}` Meeting summary:\ `{{summary}}` Professional follow-up email (< 100 words), to recap the meeting and outline next steps, if any were agreed on: {% endtab %} {% tab title="Example Output" %} Hi Arun, Brief recap of our meeting just now, written by Cogram. • Structural framework progress at 75% is impressive, despite weather delays. • Facade materials, including glass panels, are set for delivery next week. • Interior construction is on track, with a focus on the electrical infrastructure. • We need to schedule a technical meeting to discuss the 125th-floor lighting design and confirm electrical loads. Please coordinate with your team for this. • Ensure the outdoor landscapes are finalized by next Friday as discussed. Let's touch base next week for more updates. Best regards, May {% endtab %} {% endtabs %} # Board meeting minutes Use this example to have Cogram draft board meeting minutes automatically after each meeting. Copy it as-is, or tweak the prompt to fit your requirements. To set this up, see [Custom Insights](/meetings/custom-insights). {% tabs %} {% tab title="Custom Insight Prompt" %} Using the provided transcript of a virtual board meeting, write a professional set of board meeting minutes. Use the past tense and a professional, neutral tone. Only refer to participants by name where strictly necessary. Be concise but comprehensive. Meeting title:\ `{{meeting_title}}` Meeting invitees:\ `{{invitees}}` Meeting transcript:\ `{{transcript}}` Now write a high-quality, professional board meeting minutes. Use the past tense and a professional, neutral tone. Only refer to participants by name where strictly necessary. Be concise but comprehensive. Minutes of the board meeting: {% endtab %} {% tab title="Example Output" %} Minutes of the board meeting:
Meeting Title: Quarterly Financial Review and Strategic Planning Meeting Invitees: * Mr. John Smith - CEO * Ms. Susan Johnson - CFO * Mr. Richard Brown - CTO * Mr. James Wilson - Legal Counsel **1. Financial Performance Review:** The CFO presented the financial statements, highlighting a 15% increase in revenue compared to the previous year. CFO explained key financial indicators, including profit margins and cash flow. Board members engaged in a discussion on market trends and potential areas for improvement. **2. Strategic Planning for the Next Quarter:** CTO led a discussion on upcoming strategic initiatives and goals. The board reviewed and approved the proposed budget for the next quarter. **3. Legal Matters:** Legal Counsel briefed the board on any pending legal issues and compliance updates. The board discussed risk mitigation strategies and reviewed the company's legal position. {% endtab %} {% endtabs %} # Summary translation Use this example to have Cogram translate your meeting summaries into another language automatically. The prompt below targets Spanish, so swap in whichever language you need. To set this up, see [Custom Insights](/meetings/custom-insights). {% tabs %} {% tab title="Custom Insight Prompt" %} The following summary of a virtual meeting may be in English or another language. Ensure that this summary is in Spanish, ie. translate if required. Meeting Title:\ `{{meeting_title}}` Summary in English or non-English:\ `{{summary}}` Now translate to Spanish. The translation needs to be high-quality, accurate, and professional. Maintain the same format. Spanish Summary: {% endtab %} {% tab title="Example Output" %} Durante la reunión de revisión del Proyecto Skyrise, May Roark de Ethereal Architects y Arun Lynn de Saturnian Construction discutieron varios temas clave. Arun proporcionó una actualización sobre el progreso del marco estructural, indicando que está 75% completo con algunos retrasos debido a las condiciones climáticas. Sin embargo, se han ajustado los turnos de trabajo para mitigar cualquier retraso significativo. Los materiales de la fachada, específicamente los nuevos paneles de vidrio, han sido adquiridos y están programados para ser entregados la próxima semana. Arun aseguró a May que no habría problemas de calidad con este lote. La construcción interior está en marcha, con un enfoque en la infraestructura eléctrica. El principal desafío ha sido coordinar entre los subcontratistas, pero el equipo de Arun lo está gestionando. May enfatizó la importancia de alinear la construcción interior con las especificaciones de diseño, especialmente en las áreas comunes y servicios. Acordaron organizar una reunión técnica para discutir los intrincados diseños de iluminación propuestos para el área comunal del piso 125 y confirmar la capacidad de carga eléctrica. Arun coordinará con su equipo para programar la reunión. Por último, Arun recordó a May que finalice los paisajes para las áreas exteriores antes del próximo viernes para mantenerse en el cronograma. May le aseguró que transmitiría esto al equipo de paisajismo y se aseguraría de que los planes se proporcionen a tiempo. La reunión concluyó con planes de volver a reunirse a la misma hora la próxima semana. {% endtab %} {% endtabs %} # Authorizing calendar integration Connecting an Outlook calendar to Cogram may require a request for administrator consent. This page describes how IT administrators can approve such requests. {% hint style="info" %} When your users connect their calendars, they can invite Cogram to meetings straight from their own schedule, with no manual steps at meeting time. {% endhint %} #### Permissions Cogram receives and data it processes When Cogram is connected to your users' calendars, Cogram receives permission to read their calendar information. This allows Cogram to display their calendar events in Cogram’s calendar interface and makes it easy for your users to invite Cogram to meetings for note-taking. Cogram does not have the ability to modify your users' calendars. #### Administrator Consent When a Cogram user attempts to connect their Outlook calendar with Cogram this may require consent from an IT administrator, depending on your organization’s IT settings. {% hint style="info" %} The general setting that controls if administrator approval is required for users to give consent for third-party app connections in Microsoft 365 is documented [here](https://learn.microsoft.com/en-GB/microsoft-365/admin/misc/user-consent?view=o365-worldwide\&WT.mc_id=365AdminCSH_inproduct). For many organizations, the default setting is that administrator approval is required. {% endhint %} In this case, when a Cogram user attempts to connect their Outlook calendar, Cogram redirects to Microsoft’s OAuth screen and the user will be prompted to request administrator consent. ## Granting Consent to User Requests For the administrator to approve this request, the following steps are required: 1. Sign in to the [Azure portal](https://portal.azure.com/) as one of the registered reviewers of the admin consent workflow. 2. Search for and select Azure Active Directory. 3. From the navigation menu, select Enterprise Applications. 4. Under Activity, select Admin consent requests. 5. Select the My Pending tab to view and act on the pending requests. 6. Select the application that is being requested from the list. 7. Approve the request. To approve a request, grant admin consent to the application. Once a request is approved, all requestors are notified that they have been granted access. {% hint style="info" %} Approving a request allows all users in your tenant to access the application unless otherwise restricted by user assignment. {% endhint %} #### Managing App Permissions Documentation on how to manage permissions granted to applications is available [here](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/manage-application-permissions?pivots=portal). For support, contact . # Enabling Cogram to join Zoom meetings Depending on the Zoom settings of your organization, Cogram may be unable to join meetings. In your Zoom account settings, turn off **Only authenticated users can join meetings** (or add an authentication exception for Cogram) so the notetaker isn't blocked. This can be set at the account, group, or individual meeting level, documented by Zoom [here](https://support.zoom.us/hc/en-us/articles/360060549492-Allowing-only-authenticated-users-in-meetings). # Organization learn words Teach Cogram organization-wide vocabulary so proper nouns are transcribed correctly for all members. Organization admins can add learned words that apply to all members' transcriptions. This is useful for company names, client names, or industry terms that Cogram's default transcription might misspell. Go to [Organization Settings > Meetings](https://app.cogram.com/dashboard/settings/admin/meetings) and scroll to the **Learn Words** section. ## Adding words 1. Type a word into the input field. 2. Click **Add word**. Words appear as pills in the list. Click the **X** on any word to remove it. Up to 50 words can be added. For names, add first and last names separately. Do not add acronyms. ## Organization words vs. personal words | Level | Who can edit | Applies to | | ---------------- | --------------------- | ------------------------------- | | **Organization** | Org admins and owners | All members' transcriptions | | **Group** | Group admins | Members of that group | | **Personal** | Individual user | That user's transcriptions only | All three levels are combined during transcription. Members can manage their personal learned words under [Account Settings > Meetings](https://app.cogram.com/dashboard/settings/account-settings/meetings). # Emails Integrate Cogram with your email inbox to summarize email threads or draft project reports based on meetings and emails. Cogram can receive emails from your inbox and use them as source material: summarize a thread, generate a status report, or combine emails with meeting notes into a single project update.
Filed Emails page showing filed email threads

The Filed Emails page in Cogram

Emails you send to Cogram are processed securely and are only accessible to members of your Cogram workspace. They are not used to train AI models. ## Receiving Emails in Cogram To include an email in Cogram, forward the thread to ****, or CC when composing a new email. Emails Cogram has received appear under the **Emails** module on the [Filed Emails page](https://app.cogram.com/dashboard/email-inbox), where you can see the subject, sender, and date for each received thread. The Emails module has two tabs: **Email** (your filed inbox, described on this page) and **Transmittals** (sending files with tracked delivery, described below). ## Sending files (Transmittals) To send drawings, specifications, or other documents to anyone (inside or outside Cogram) with a tracked record of what was sent and to whom, use **Send Files**. Each send creates a **transmittal**: the project record of that file transfer. Transmittals are also part of the document register — what each one pins, stamps, and freezes is covered in [Transmittals](/documents/document-transmittals). 1. Open the [Emails page](https://app.cogram.com/dashboard/email-inbox) or the [Transmittals tab](https://app.cogram.com/dashboard/email-inbox/transfers) and click **Send Files**. 2. Follow the composer steps: add details, attach documents, pick recipients from your [Directory](/projects/directory), then review and send. Recipients get an email with a secure link to view and download the files. No Cogram account is required to receive a transmittal. The transmittal record tracks delivery and acknowledgment on the [Transmittals tab](https://app.cogram.com/dashboard/email-inbox/transfers). ### Adding a recipient after sending If someone was missed, you can send an already-sent transmittal to additional people: 1. Open the transmittal from the [Transmittals tab](https://app.cogram.com/dashboard/email-inbox/transfers). 2. Click **Send to…**, add the recipients, and optionally include a message. 3. Click **Send**. The transmittal's files are included automatically, and each new recipient appears as a new send in the transmittal's **Thread**. There is no resend action for someone who already received the transmittal. To send the same package again to an existing recipient, create a new transmittal. ### Viewing a transmittal's history Open a sent transmittal from the [Transmittals tab](https://app.cogram.com/dashboard/email-inbox/transfers). Its **Thread** shows the full history: every send, including recipients added later, plus when each recipient viewed, downloaded, or acknowledged the files. ## Enabling auto-forwarding (Outlook) Instead of forwarding emails one by one, you can create an Outlook rule to automatically forward matching emails to Cogram: 1. Open Outlook and go to the **Home** tab. 2. Select **Rules** > **Manage Rules & Alerts**. 3. In the **Rules and Alerts** dialog, click **New Rule**. 4. Choose **Apply rule on messages I receive**, then click **Next**. 5. Check the criteria you want (e.g., messages from a specific sender or containing certain words) and click **Next**. 6. When asked what to do with the messages, select **forward it to people or public group**. 7. Click the underlined "people or public group" link, enter ****, and click **OK**. 8. Click **Next**, optionally add any exceptions, then click **Finish** to finalize the rule. Matching emails now forward to **** automatically. ## Working with multiple emails On the Filed Emails page, you can select multiple emails at once to perform bulk actions. Click the checkbox on any email row to start a selection, and a bulk action toolbar appears at the top of the list.
Filed Emails page with emails selected and a bulk action toolbar showing Change Project, Unfile emails, Export, and Agent buttons

Selecting multiple emails reveals bulk actions

| Action | What it does | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Change Project** | Reassign all selected emails to a different project. | | **Unfile emails (N)** | Remove the selected emails from their projects. The count of selected emails is shown in parentheses. | | **Export (N)** | Download the selected emails as `.eml` or `.msg (Outlook)` files in a ZIP archive. To export a single email, open it and select **Export** in the email header. See [Exporting emails](/email/exporting-emails). | | **Agent** | Open the AI agent with all selected emails as context, useful for generating a combined summary or report across multiple threads. | To select all emails on the current page at once, click the checkbox in the column header. ## Opening and replying in Outlook From the Emails page you can jump back to the original message in Outlook, or start a reply, without leaving Cogram. 1. Open the [Emails page](https://app.cogram.com/dashboard/email-inbox) in Cogram and select an email to preview it. 2. In the email header, click the **Outlook** icon.
The Emails page with an email open and the Outlook icon highlighted in the email header

Click the Outlook icon in the email header

3. Choose the action you need from the menu.
The Outlook menu open, showing Open, Reply, and Reply all

The Outlook menu: Open, Reply, and Reply all.

| Action | What it does | | ------------- | ----------------------------------------------------------------------------------- | | **Open** | Opens the original email in Outlook on the web, in a new browser tab. | | **Reply** | Creates a draft reply in Outlook, addressed to the sender. | | **Reply all** | Creates a draft reply in Outlook, addressed to the sender and all other recipients. | ### Open **Open** opens the original message in Outlook on the web, in a new browser tab. If the message is no longer in your mailbox (for example it was moved or deleted), Outlook still opens, but shows that the message cannot be found.
Outlook on the web showing the message might have been moved or deleted

Outlook shows this when the original message is no longer in your mailbox

### An email doesn't show Open at all **Likely cause**: the email was imported into Cogram (for example from a `.msg` or `.eml` file) rather than filed from Outlook, so there is no Outlook message to open. **Fix**: none needed. Read the email directly in [**Emails**](https://app.cogram.com/dashboard/email-inbox). ### Reply and Reply all **Reply** and **Reply all** open Outlook on the web in compose mode, in a new browser tab, with the original message quoted and the recipients filled in. The draft is ready to edit; review and send it from Outlook. > **Reply and Reply all require a connected Outlook account.** If your Outlook is not connected to Cogram, you are prompted to connect it. Set this up in [**Account Settings > Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations). **Open** does not require a connection. If the original message was deleted from your mailbox, Cogram still creates the draft from the archived email it has on file. In that case the draft may start a new conversation rather than thread into the original. ## Auto-filing emails to projects Cogram can automatically file incoming and outgoing emails to projects, without you needing to forward them manually. This is configured under [**Account Settings > Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations) in the **Email** section. * **Auto-file incoming emails**: Cogram automatically files emails sent to you into the matching project. * **Auto-file outgoing emails**: Cogram automatically files emails you send into the matching project. Both toggles can be enabled or disabled independently. > **Note**: If your organization has locked either of these settings, the toggle will appear grayed out with a lock icon and cannot be changed. Contact your Org Admin if you need it changed. ### Setting defaults for your organization (Admins) Org Admins and Owners can set and lock the auto-file defaults for all members in [**Organization Settings > Emails**](https://app.cogram.com/dashboard/settings/admin/email). | State | What the end user sees | | ------------ | --------------------------------------------------------------------- | | **Unlocked** | The default is pre-set, but the user can toggle it on or off. | | **Locked** | The toggle is grayed out with a lock icon. The user cannot change it. | ## Summarizing emails and drafting reports Once emails are in Cogram, Agent can summarize a thread, extract action items, or generate a draft status report that combines emails with meeting notes from across a project. See the [Agent](/agent/agent) page to learn how. ## Importing historical emails If you have project emails that predate your Cogram connection, in an Outlook archive (`.pst`), individual email files (`.eml`), or Outlook message files (`.msg`), Cogram can import them into a project on your behalf. See [Importing historical emails](/email/importing-emails) to learn what to prepare and how to submit a request. # Outlook add-in: email filing Connect Microsoft Outlook to Cogram to automatically file project emails, review AI filing decisions, and track email status with Outlook category labels. Connect your Outlook account to automatically file project emails and review decisions without leaving your inbox. Manage your email connection in [**Account Settings > Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations). ## Prerequisites * A Cogram account with at least one project * A Microsoft 365 / Outlook account * The Cogram Add-In installed in your Outlook. If you don't see it, send your IT administrator [Installing the Outlook add-in](/email/installing-the-outlook-add-in). ## Connecting your Outlook account 1. Go to [**Account Settings > Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations). 2. Under **Email Connection**, click **Connect** next to Microsoft Outlook. 3. Sign in and grant the requested permissions. Cogram begins processing new emails immediately. Emails already in your inbox are not retroactively filed. > Your IT organization may need to approve the integration. Contact your administrator if the authentication step fails. ## How filing works When an email arrives or is sent, Cogram checks it against your active projects and assigns a decision: | Decision | Meaning | | ------------- | ------------------------------------------------ | | **Filed** | Matched to a project and filed automatically. | | **Pending** | A project is suggested; needs your confirmation. | | **Not Filed** | No matching project found. | Filed emails appear in the **Emails** tab of the matched project. Review and act on decisions in the **Cogram Add-In panel**, a sidebar inside Outlook. Open it via the Cogram icon in your toolbar or ribbon. > **Pin the Add-In panel, recommended on first use.** Click the **pin icon** (thumbtack) in the top-right corner of the panel. The panel stays open as you click between emails and updates automatically, so there is no need to reopen it each time. Without pinning, **Outlook automatically closes the panel whenever you click on another email**. This is Outlook's default behavior for any add-in, not a Cogram limitation. The pin only needs to be set once per account. | Action | What it does | | ----------- | --------------------------------------------------- | | **Confirm** | Accept the suggested project; status becomes Filed. | | **Reject** | Decline; status becomes Not Filed. | | **Remove** | Remove a previously confirmed filing. | ## Filing settings Go to [**Account Settings > Integrations > Email Connection**](https://app.cogram.com/dashboard/settings/account-settings/integrations) to control what gets filed. ### Auto-file incoming emails Toggle on to automatically file emails you **receive** to matching projects. When off, incoming emails are not processed unless you file them manually from the Add-In panel. ### Auto-file outgoing emails Toggle on to automatically file emails you **send** to matching projects. This is independent of the incoming toggle, and useful if you only want to track sent correspondence. ### File from folder Designate an Outlook folder as a manual filing trigger. Any email moved into that folder is sent to Cogram for matching, regardless of the auto-file toggles above. Enable the **File from folder** toggle in [**Account Settings > Integrations > Email Connection**](https://app.cogram.com/dashboard/settings/account-settings/integrations):
Email Connection settings with File from folder toggle highlighted

Enable the File from folder toggle to open the folder picker

A folder picker opens. Select an existing Outlook folder, or click **Create "File to Cogram"** to let Cogram create a dedicated folder. You can also type any name to create a custom folder:
Choose a filing folder dialog with folder list and Create File to Cogram option

Pick an existing folder or create a new one with any name

The selected folder appears at the top with a checkmark. Click **Confirm** to save:
Choose a filing folder dialog with File to Cogram selected and a checkmark

Confirm your selection: emails moved to this folder will be filed automatically

### Apply category labels Cogram writes a color-coded Outlook category to each processed email: **Filed** (green), **Pending** (yellow), **Not Filed** (gray). Labels update automatically as decisions change. Turn off if you use Outlook categories for other purposes. > **Organization admins** can set defaults and lock all three auto-filing toggles (incoming, outgoing, apply category labels) for the entire organization. Go to [**Organization Settings > Emails > Auto-Filing**](https://app.cogram.com/dashboard/settings/admin/email). Each setting can be left **Unlocked** (users override freely) or set to **Locked** (your org default applies to everyone and cannot be changed by individual users).
Email Auto-Filing settings in Organization Settings showing incoming and outgoing auto-file toggles (Inactive, Unlocked) and Apply Outlook category labels toggle (Active, Locked)

Organization Settings > Emails > Auto-Filing: admins can toggle and lock each setting org-wide

### Sender Blocklist: excluding senders from auto-filing **Admin-only.** Some senders should never have their emails auto-filed: HR communications, personal contacts copied in on project threads, automated notification services. Org admins can maintain a **Sender Blocklist** of sender addresses that are excluded from auto-filing for the entire organization. Go to [**Organization Settings > Emails > Sender Blocklist**](https://app.cogram.com/dashboard/settings/admin/email) and add the addresses to the **Sender Blocklist** field. Separate multiple addresses with commas or semicolons, or press Enter after each. Changes save automatically. Enter full email addresses only (for example `alice@example.com`); domains and misspellings won't match, so double-check each entry. How it works: * **Sender match only.** Cogram compares the **From** address of incoming email against the list. Strict, full-address match (`alice@example.com`), lowercased. Domains (`example.com`) and partial matches are not supported; add each address individually. * **Auto-filing only.** Excluded senders still show up in your inbox and you can still file their emails manually from the Add-In. Only automatic filing is skipped. * **Outgoing mail is unaffected.** Filing sensitivity is applied to incoming mail based on the sender. Emails you send to a listed address are filed normally. * **Visible to admins only.** The list is never shown to non-admins or included in auto-filing decision explanations. ## Bulk-filing emails from the Add-In > **Outlook version requirement:** Bulk-filing requires **Outlook with a Microsoft 365 subscription** (desktop or web). It is not available on perpetual / volume-license Outlook (Office 2016, 2019, 2021, or 2024 LTSC), Outlook for iOS and Android, or Outlook on the web connected to an on-premises Exchange Server. On unsupported versions the multi-select option does not appear in the Add-In panel; single-email filing works normally. You can file or remove multiple emails at once directly from the Cogram Add-In panel in Outlook. 1. Select two or more emails in your Outlook folder (hold **Ctrl** or **Shift** to multi-select), then open the **Email Management** Add-In from the toolbar or the action menu.
Outlook inbox with 2 emails selected and the Email Management button highlighted in the toolbar

Select emails, then open Email Management from the toolbar or action menu

2. The Add-In shows the count of selected emails. Pick one or more projects to file them to. You can search or scroll the project list.
Cogram Add-In panel showing 2 emails selected, project picker with Building Cogram selected, and File button

Select a project (or multiple), then click File

3. Click **File N emails to N project**. The Add-In confirms the count of filed emails.
Cogram Add-In panel showing Filed 2 of 2 with checkmarks and a Done button

Confirmation: emails are now in the project record

To remove a batch from a project, select the emails, open the Add-In panel, and click **Remove**. ## Disconnecting Go to [**Account Settings > Integrations > Email Connection**](https://app.cogram.com/dashboard/settings/account-settings/integrations) and click **Disconnect**. Existing filed emails remain in your projects; no new emails will be processed. ## Troubleshooting **Emails not filing automatically.** Check that auto-file toggles are on and the account shows as connected. Reconnect if needed. **Category labels not appearing.** Enable the **Apply category labels** toggle. If labels still don't appear, ask your IT administrator to confirm Cogram has the required Microsoft Graph permissions. **Add-In panel not visible.** Your administrator has not deployed the Cogram Add-In yet, or the rollout is still propagating. Send them [Installing the Outlook add-in](/email/installing-the-outlook-add-in). **Panel closes when switching emails.** The panel is not pinned. Click the **pin icon** (thumbtack) in the top-right corner of the panel to keep it open as you navigate between emails. **Label shows wrong status.** Refresh the Cogram Add-In panel. The label updates once Cogram processes the change. **Bulk-filing (multi-select) option not visible.** Your Outlook version does not support multi-select in add-ins. Bulk-filing requires a Microsoft 365 subscription version of Outlook (desktop 2301+ or Outlook on the web against Exchange Online). It is not available on perpetual Office licenses (2016/2019/2021/2024 LTSC), Outlook mobile, or Outlook on the web connected to on-premises Exchange. Use single-email filing until you upgrade. ## Next steps * [Projects](/projects/projects): how emails appear in the project record * [Emails](/email/emails): forward emails for summarization or report drafting # Importing historical emails Import historical project emails from an Outlook archive (.pst), individual email files (.eml), or Outlook message files (.msg) into a Cogram project. Cogram can import existing project emails into a project on your behalf. Imported emails appear in the project's **Emails** tab alongside any live-filed correspondence and are available as context for the AI agent. ## Supported formats | Format | Extension | | ------------------ | --------- | | Outlook archive | `.pst` | | Email message file | `.eml` | | Outlook message | `.msg` | A `.pst` archive is the most efficient format for large imports. ## How to request an import Contact your Cogram representative or email **** with: * The email files (attached or as a secure download link) * The Cogram project name or project ID * Your Cogram user email address One import request = one project. For multiple projects, submit one request per project. Emails already in the project (matched by Message-ID) are skipped automatically. ## Exporting a PST from Outlook 1. Go to **File → Open & Export → Import/Export**. 2. Select **Export to a file → Outlook Data File (.pst)**. 3. Select the account or folder to export. Check **Include subfolders** for a full export. 4. Choose a save location and click **Finish**. ## After the import Cogram will confirm when the import is complete and provide a summary of imported, duplicate, and skipped messages. Imported emails are identical to live-filed emails: searchable, available to Agent, and part of the project record. ## Next steps * [Emails](/email/emails): forward or auto-file ongoing project correspondence * [Outlook add-in: email filing](/email/outlook-add-in-email-filing): connect Outlook to file emails automatically going forward * [Agent](/agent/agent): use imported email history to generate summaries and reports # Exporting emails Download filed emails from Cogram as .eml or Outlook .msg files, with attachments included. Exporting saves one or more filed emails to your computer as standard email files. Attachments are included. Use exports for project closeout archives, audit trails, or sharing correspondence with contacts who are not on Cogram. ## Prerequisites * At least one email filed in Cogram * Email export enabled for your organization: if the **Export** button is not visible, contact your Org Admin ## Exporting a single email 1. Open [Filed Emails](https://app.cogram.com/dashboard/email-inbox) (under the **Emails** module) and select an email to preview it. 2. In the email header, select **Export**. 3. Choose a format from the dropdown: * **.eml**: works with most email clients (Outlook, Apple Mail, Thunderbird, Gmail import) * **.msg (Outlook)**: native Outlook format; best for recipients using Outlook on Windows 4. Your browser downloads a single file named after the email subject. ## Exporting multiple emails 1. Open [Filed Emails](https://app.cogram.com/dashboard/email-inbox) under the **Emails** module. 2. Click the checkbox on any email row to start a selection. The bulk action toolbar appears at the top of the list. * **Select a range**: click one checkbox, hold **Shift**, then click another to select all emails in between. * **Select the page**: click the checkbox in the column header to select all emails on the current page. 3. Select **Export (N)** in the toolbar, where N is the number of selected emails. 4. Choose **.eml** or **.msg (Outlook)** from the dropdown. 5. Cogram packages the selected emails into a ZIP archive and downloads it. **ZIP file name**: `{project-name}_emails_{YYYY-MM-DD}_{format}.zip` If the selected emails span more than one project, the filename is `emails_{YYYY-MM-DD}_{format}.zip`. ## What is included | Content | Included | | ----------------------------------- | ------------------------------------------- | | Email body (plain text and HTML) | Always | | To, From, Cc, Date, Subject headers | Always | | Attachments | When available | | Inline images | When available, linked within the HTML body | The exported file is a copy of the email as received by Cogram. No AI-generated content is included. ## Choosing a format | | .eml | .msg (Outlook) | | ----------------- | ---- | --------------- | | Outlook (Windows) | ✓ | ✓ native | | Outlook (macOS) | ✓ | Limited support | | Apple Mail | ✓ | ✗ | | Gmail import | ✓ | ✗ | | Thunderbird | ✓ | With add-on | Use **.eml** unless the recipient specifically requires Outlook `.msg` format. ## Troubleshooting **The Export button is not visible** Email export must be enabled for your organization. Contact your Org Admin to request access. **A ZIP archive is missing some attachments** Attachments that could not be retrieved at export time are skipped. The email body and any other attachments are still included. **The .msg file does not open correctly** Outlook 2016 or later on Windows is required. The macOS Outlook app has limited `.msg` file support; use `.eml` instead. ## Next steps * [Emails](/email/emails): how to file emails and use them as source material for Agent * [Agent](/agent/agent): summarize threads or generate reports from filed emails # Installing the Outlook add-in How a Microsoft 365 Global Administrator deploys the Cogram Email Management add-in to Outlook, grants organization-wide consent, applies updates, and removes the add-in. Cogram Email Management is an Outlook add-in. It files incoming and outgoing project email, with attachments, into the right Cogram project, and it gives your team a panel inside Outlook to review and correct those decisions. This page is for the IT administrator who deploys the add-in. For what your team sees day to day, read [Outlook add-in: email filing](/email/outlook-add-in-email-filing). ## Prerequisites * Microsoft 365 (Exchange Online). The add-in does not work on on-premises Exchange. * A **Global Administrator** account in your Microsoft 365 tenant. * A Cogram organization admin account. This is usually the same person. ## What you will do Two one-time steps, in this order: 1. Deploy the add-in to your tenant from Microsoft Marketplace. Microsoft can take up to 72 hours to roll it out to users, though it is often much faster. 2. In Cogram, connect Outlook and consent on behalf of your organization, so your colleagues can connect their own mailboxes without raising an approval request each time. ## 1. Deploy the add-in from Microsoft Marketplace > **Who:** a Microsoft 365 **Global Administrator**. 1. Open the [**Cogram Email Management** listing on Microsoft Marketplace](https://appsource.microsoft.com/en-us/product/saas/wa200008856?tab=overview) and click **Get it now**.
Cogram Email Management listing on Microsoft Marketplace with the Get it now button

The Cogram Email Management listing, with Get it now

2. Microsoft redirects you to **Integrated apps** in the Microsoft 365 admin center and starts the deployment wizard. 3. Choose who gets the add-in: the entire organization, specific groups, or specific users. Click **Next**. 4. Click **Accept permissions**. Sign in with the Global Administrator account if prompted, review the permissions, and accept them. 5. When **Permissions accepted** shows a green checkmark, click **Next**. 6. Click **Finish deployment**, then **Done**. **What good looks like:** Cogram Email Management is listed under [**Settings → Integrated apps**](https://admin.microsoft.com/#/Settings/IntegratedApps) with a status of **Deployment completed**, and the Cogram button appears in the Outlook ribbon or toolbar for the users you selected. Allow up to 72 hours for Microsoft to propagate the add-in to every mailbox. ## 2. Connect Outlook in Cogram and consent for your organization > **Who:** a **Cogram organization admin**. 1. Go to [**Account Settings → Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations) in Cogram. 2. Under **Email**, click **Connect** next to **Microsoft Outlook**. A Microsoft sign-in window opens.
Email section of Cogram Account Settings Integrations, with a Connect button next to Microsoft Outlook

Account Settings → Integrations → Email → Connect

3. Sign in with your Microsoft 365 admin account and review the permissions. 4. Check **Consent on behalf of your organization**, then click **Accept**. Do not skip that checkbox. Without organization-wide consent, every colleague who connects their mailbox raises a separate admin approval request for you. This completes the IT setup. Your Cogram contact runs onboarding and a walk-through of email filing with your team separately. ## Managing who has the add-in Go to [**Settings → Integrated apps**](https://admin.microsoft.com/#/Settings/IntegratedApps) in the Microsoft 365 admin center and select **Cogram Email Management**. **Assigned users** shows who has it today. Click **Edit users** to switch between the whole organization, specific groups, and specific users. This is the same flow that controls automatic rollout to new starters.
Cogram Email Management detail pane with Assigned users showing Entire organization and the Edit users link highlighted

Assigned users and Edit users in the app detail pane

## Applying updates Cogram Email Management comes from Microsoft Marketplace, so ordinary updates need nothing from you. Microsoft applies the new version the next time each user restarts Outlook. You only act when a new version asks for **new permissions**. Then the add-in's status in [**Settings → Integrated apps**](https://admin.microsoft.com/#/Settings/IntegratedApps) reads **Updates pending**, and your users stay on the previous version until an administrator consents.
Integrated apps list showing Cogram Email Management with the status Updates pending highlighted

Settings → Integrated apps: Updates pending means a permission approval is waiting

If you see **Updates pending**, contact and we will tell you which permission the release adds and walk you through granting it. Users keep working on the previous version in the meantime. ## Removing the add-in > **Who:** a Microsoft 365 **Global Administrator**. 1. Go to [**Settings → Integrated apps**](https://admin.microsoft.com/#/Settings/IntegratedApps) in the Microsoft 365 admin center. 2. Find **Cogram Email Management** and select it. 3. Under **Actions**, click **Remove app** and confirm for all users.
Cogram Email Management detail pane with the Remove app action highlighted under Actions

Actions → Remove app, in the app detail pane

Two things to expect afterwards: * **Propagation takes around 24 hours** before the add-in disappears from every user's Outlook. * **The Marketplace listing stays up.** Users can add the add-in back themselves, so block acquisitions under **Integrated apps → Settings** if you want the removal to stick. Removing the add-in stops Outlook filing. Emails already filed stay in your Cogram projects. ## Troubleshooting **The Cogram button does not appear in Outlook.** Microsoft has not finished rolling out the deployment, or the user is outside the assignment you chose. Check the assignment under [**Settings → Integrated apps**](https://admin.microsoft.com/#/Settings/IntegratedApps) and allow up to 72 hours after deployment. **Users are asked for admin approval when they connect their mailbox.** Organization-wide consent was not granted in step 2. Repeat the Cogram connection flow as an admin and check **Consent on behalf of your organization**. **The add-in stopped updating, or a feature Cogram announced is missing.** The add-in is in **Updates pending**. Follow [Applying updates](#applying-updates). **Category labels do not appear on filed emails.** Confirm the deployment's permissions were accepted in full. Cogram needs Microsoft Graph permission to write Outlook categories. **A screen does not match what you see.** Microsoft changes the admin center and the Marketplace regularly. Email with a screenshot and we will confirm the current steps. ## Next steps * [Outlook add-in: email filing](/email/outlook-add-in-email-filing): what your team does with the add-in, and the org-wide auto-filing settings * [Authorizing calendar integration](/meetings/authorizing-calendar-integration): the equivalent admin consent for Outlook calendars # Create a field report on site Create a field report on your phone during a site visit: capture observations, fill in the report details, and finalize it for export. A field report collects everything from a site visit in one place: your observations with photos, the site conditions, and the details your firm's report format asks for. You create it on your phone during the visit, finalize it when you are done, and download the finished Word document from the web afterward. ## Starting a report To start one: 1. On the **Home** tab, tap **Start Field Report**. 2. Enter a report title, pick the **Project**, and pick the **Report Type**. The Report Type decides which details the form asks for; your admin sets these up under [Report types](/field/report-types). 3. Tap **Start Report**. The report editor opens. Everything you enter is saved on your phone as you go, so losing signal never loses work. ## Adding observations A report is built from observations: individual findings, each with its own notes and photos. In the report editor: * Tap **Add Observation** to capture a new one. See [Capture observations](/field/observations) for the full flow. * Tap **Link Existing** to pull in observations you captured earlier, for example with **Quick Observation** while walking the site. Swipe an observation to remove it from the report.
The report editor with linked observations, the Add Observation and Link Existing buttons, and the Finalize Report button

The report editor. Everything keeps working offline.

## Filling in the report details Below the observations, the form shows the fields your Report Type asks for, like the client firm or persons present. Required fields are marked with `*`. Table fields, like an attendance list, take one row per entry: tap the add row button, fill in the columns, and tap **Save**. The report also records the site location and pulls the weather for it automatically. ## Finalizing the report When the visit is done, tap **Finalize Report**. Finalizing uploads the report and makes it available to your team. If the button is not available, the editor tells you exactly what is missing, for example "Add an observation to start", "Each observation needs a type and status", or "Complete required field: Client Firm". Fix what it names and finalize again. {% hint style="info" %} A report you back out of stays as a **Draft** on the Reports tab. Drafts live only on your phone and do not upload until you finalize them. Tap a draft to pick up where you left off. {% endhint %} If an admin changed the Report Type while you were drafting, the app shows "Report template was updated" and lists any new required fields. Tap **Review form**, fill in what is new, and finalize. ## After finalizing The report uploads and shows **Uploaded** once it is safely on the server (see [Working offline](/field/working-offline) for what the statuses mean). From then on: * On your phone, open the report to review its details, weather, observations, and Cogram's summary of the findings.
A finalized report page showing the project, location, summary, and linked observations

A finalized report on your phone

\- On the web, open the report and click \*\*Download\*\* to export it as a Word document in your firm's layout. See \[Field on the web]\(field-on-the-web.md) for the full review and export workflow. Exporting is a web feature. The mobile report page points you to the web app for the full details. ## Deleting a report The trash icon in the report editor deletes the report and all of its observations and photos permanently. There is no undo. ## Related * [Capture observations](/field/observations): notes, dictation, photos, and drawing pins. * [Working offline](/field/working-offline): drafts, upload statuses, and weak-signal behavior. * [Report types](/field/report-types): how admins set up the report forms and export layouts. # Capture observations Capture observations on site with notes, voice dictation, photos, and drawing pins, then group them into field reports. An observation is a single finding on site: a defect, progress on a trade, a safety issue, anything worth recording. Each one carries a type, a status, notes, photos, and optionally a pin on a drawing. You capture them fast on your phone and group them into [field reports](/field/field-reports). ## Capturing an observation Start one from **Quick Observation** on the Home tab, or from **Add Observation** inside a report. Then: 1. Pick the **Type** (what it is, like "Defect") and **Status** (where it stands, like "Open"). Your admin manages these lists under [Observation types and statuses](/field/observation-types-and-statuses). 2. Add your notes. Type them, or tap the mic and dictate; dictated notes are added as bullet points. 3. Add photos and, if useful, pin the observation to a drawing (both below). 4. Tap **Save & Next** to save and immediately start the next observation. That is the rhythm for walking a site: capture, next, capture, next. If saving is not available, the editor tells you what is missing, like a note or photo, a type, or a project.
The observation editor with the Type and Status dropdowns, the Notes field, and the Drawing Location section

The observation editor

## Photos Tap the camera button to take photos, or pick them from your photo library. The camera has a torch, a grid, and pinch to zoom. After taking a photo you can mark it up: draw on it freehand (pick a color and brush size, undo if needed) and add a caption by typing or tapping **Record** to dictate it. Markups are saved into the photo, so they appear in the exported report. {% hint style="info" %} Photos can only be added while an observation is still on your phone. Once it has uploaded, create a new observation for additional photos. {% endhint %} ## Pinning to a drawing A pin shows exactly where on the plans the observation sits, and the pinned drawing snippet appears in the exported report. * From the observation, tap **Tap to add drawing location**, pick the drawing, then long-press on the spot to drop the pin. * Or start from the drawing itself: open it from the **Drawings** tab and long-press anywhere to create a new observation pinned right there. Existing observations show as red pins; tap one to open it. If pinning is unavailable, the app tells you why: the observation needs a project first, or the project has no drawings yet. See [Drawings](/field/drawings) for getting drawings onto your phone.
A drawing open on mobile with observation pins and the hint to long-press anywhere to add an observation

Observation pins on a drawing

## Finding observations later The **Observations** tab lists everything, with search and filters for project, status, type, and report. Tap an observation to review it, or the pencil to edit. Admins can also update the type and status from the web after capture. ## Grouping observations into a report Captured a batch with **Quick Observation** and want them in a report? 1. On the **Observations** tab, tap **Select** (or long-press an observation). 2. Pick the observations. They must all belong to the same project. 3. Tap **Add to Report** to add them to an existing report, or **Create Report** to start a new one from them. If some already belong to another report, the app warns you that they will be moved. The same works in reverse from a report's editor with **Link Existing**.
The Observations tab with search, the Select button, and a list of observations showing their type and status

The Observations tab

## Related * [Create a field report on site](/field/field-reports): turning observations into a finished report. * [Drawings](/field/drawings): downloading drawings for offline use and browsing them on site. * [Observation types and statuses](/field/observation-types-and-statuses): how admins manage the Type and Status lists. # Drawings Upload and organize drawings on the web, then download them to your phone so the plans are with you on site, even without signal. Drawings live under the **Field** module. You upload and organize them on the web at [Field > Drawings](https://app.cogram.com/dashboard/reports/drawings), and your team downloads them to their phones to browse on site and pin [observations](/field/observations) to them. ## Managing drawings on the web ### Uploading drawings Click **Upload Drawings** on the Drawings page and pick your files. Cogram reads each sheet's title block and fills in the drawing number, date, [discipline](/field/drawing-disciplines), and revision code automatically. You can also type a revision code in the upload dialog to apply one code to the whole upload, useful when a package all goes out at the same revision. A sheet without a readable code has no revision until you set one; see [Revisions and versions](/documents/revisions-and-versions). Uploading the same drawing number again creates a new revision, so the current sheet stays on top and older revisions remain available. A revision code that was already issued on a sent [transmittal](/documents/document-transmittals) is frozen: a re-upload carrying it lands as an unnamed revision instead, keeping the issued record intact. ### Organizing with drawing sets Drawing sets group sheets into packages, like "Bid Set 2026" or "IFC Set". Click **Manage Sets** to create sets and assign sheets. Sets are what your team downloads to their phones, so group sheets the way people will need them on site. A set belongs to one project. ### Bulk-editing drawings When several drawings need the same discipline, drawing set, or date, update them in one step: 1. Select the drawings with the checkboxes in the first column. 2. Click **Edit (N)** in the toolbar that appears above the table. 3. Fill in any combination of **Discipline**, **Drawing Date**, and **Drawing Set**. 4. Click **Save**. Fields you leave blank are left alone on every selected drawing, not cleared. To remove a value from a drawing, open that drawing individually and clear the field there. If your selection spans multiple projects, the Drawing Set field is disabled ("Selected drawings span multiple projects"); discipline and date still work across projects. If some drawings cannot be updated, the dialog keeps the successful ones saved and lists the failures so you can fix and retry only those. ### Who can manage drawings Editing (bulk and single) is available to project Owners and Leads in their projects, and to Org Admins and Org Owners across all projects. Deleting is stricter: only a project Owner or Lead can delete a drawing. Members and Viewers can view and download. See [Project roles](/projects/project-roles). ## Drawings on your phone ### Downloading sets for offline use Signal is unreliable on site, so download what you need in advance: 1. Open the **Drawings** tab in the mobile app and pick the project. 2. Tap the download icon on a drawing set. A progress bar shows how many sheets are done. 3. Downloaded sets offer **Refresh** (fetch the latest revisions) and **Remove from offline**. You can also open a set and long-press sheets to select several and download only those. Each sheet shows its state at a glance: a green check (downloaded), a refresh icon (a newer revision exists), a cloud icon (not downloaded), or a cloud-off icon (not downloaded while you are offline). {% hint style="info" %} The app manages its own storage. If space runs low, it removes older unpinned sets and tells you how much it freed. Sets you keep downloaded stay put. {% endhint %} ### Browsing on site Inside a set, filter sheets by discipline with the chips at the top, switch between list and grid view, or search. Open a sheet to pan and zoom. Red pins on a sheet are existing observations; tap one to open it. Long-press anywhere on the sheet to capture a new observation pinned to that spot. See [Capture observations](/field/observations). ## Drawings in the document register Drawings also appear as rows in [Documents](/documents/documents), next to the project's files, with their current revision and status. From the register you can download them or select them into a [transmittal](/documents/document-transmittals), the formal, numbered record of what was issued. The register's rail has a **Drawings** node. Open it and the whole page accepts drops: drag PDFs anywhere onto it and the drawings upload dialog opens with those files already staged, title blocks read as usual. The document scopes in the rail behave the same way for ordinary files. ## Related * [Capture observations](/field/observations): pinning findings to drawings on site. * [Working offline](/field/working-offline): what else works without signal. * [Drawing disciplines](/field/drawing-disciplines): the discipline list admins manage, used for filtering and automatic classification. * [Project roles](/projects/project-roles): what each role can do with drawings. # Field on the web Review field reports and observations in the web app, export them as Word or CSV files, and extract observations from meeting recordings. Capture happens on your phone; review and export happen at your desk. The Field module in the web app's left sidebar holds your reports, observations, and drawings, and this is where the finished documents come out. ## Reviewing reports Open [Field > Reports](https://app.cogram.com/dashboard/reports) and click a report to review it. The report page has tabs for the overview, its observations, and its drawings, and shows Cogram's summary of the findings. To export the report, click **Download** and pick a template under **Select a template**. Your organization's layouts appear under **My Templates**. The Word document fills in the report's details and observations per its [Report Type](/field/report-types). To export several reports at once, select them in the list and use **Download selected reports**.
A field report on the web with the Download template picker open, showing My Templates and the Add templates option

Exporting a report: Download, then pick a template

Your admin manages the layouts under [Word templates](/meetings/templates). ### Changing a report's type Picked the wrong report type in the field? On the report page, click **Change type** and select the correct one. Fields with the same name keep their values, and the export switches to the new type's templates. Values that don't exist on the new type are kept but hidden, and they come back if you switch the report back to its old type. The report's creator and organization admins can change the type at any time, even after the report is completed. ## Reviewing observations Open [Field > Observations](https://app.cogram.com/dashboard/reports/observations) for every observation across your projects, with filters. Click one to review or edit it: the type, status, notes, and photo captions can all be updated after capture, so cleaning up field notes at your desk is normal. Two exports live on this list: * **Download CSV**: the observation list as a spreadsheet, for tracking in Excel. * **Export DOCX**: select observations first, and the toolbar offers **Export DOCX** (a Word document of the selection) alongside **Add to report**, which groups the selection into a field report from your desk.
The web Observations list with rows selected and the Add to report, Export DOCX, and Delete actions in the toolbar

The Observations list with a selection: Add to report and Export DOCX

## Extracting observations from a meeting Walked the site while recording a [meeting](/meetings/in-person-meetings)? Cogram can turn what was said into observations. On the meeting's page, click **Extract** and choose: * **Report with all observations**: creates a field report with the extracted observations already linked. * **Freestanding observations**: creates the observations on their own, for you to review and group later. Extraction is AI-powered: review the extracted observations for accuracy, especially names, technical values, and units, before finalizing or sharing a report. ## Drawings and pins Drawings are managed on the web too: uploads, drawing sets, and bulk edits are covered in [Drawings](/field/drawings). On a drawing, you can move an existing observation pin with **Move pin**; placing new pins happens on mobile. ## Related * [Create a field report on site](/field/field-reports): the mobile capture workflow that feeds these pages. * [Word templates](/meetings/templates): the Word layouts reports export against. * [Drawings](/field/drawings): uploading and organizing drawings on the web. # Working offline What the Cogram mobile app can do without signal, what the upload statuses mean, and how to make sure nothing gets lost. Job sites have bad signal. The Cogram mobile app is built for that: everything you capture is saved on your phone first and uploaded when a connection is available. This page explains what works offline, what the statuses mean, and the one habit that keeps your work safe. ## What works without signal * Capturing observations, photos, and notes: fully. * Creating and finalizing field reports: fully. They upload once you are back online. * Recording in-person meetings: fully. The recording uploads later. * Viewing drawings: only the ones you downloaded beforehand. See [Drawings](/field/drawings) for downloading sets before you head out. When the app is offline it shows a banner: "Your device is offline. New data will be uploaded for processing once you're online." Keep working; nothing is lost.
The report editor with the offline banner at the top, still fully usable

Offline on site: the banner shows, and everything keeps working

## What the statuses mean Reports, observations, and meetings show a status badge: | Status | Meaning | | ---------------- | ------------------------------------------------------------------------------------- | | Draft | Still being edited, only on your phone. Drafts do not upload until you finalize them. | | Awaiting Upload | Finalized and queued. It uploads at the next opportunity. | | Uploading | On its way to the server right now. | | Uploaded | Safely on the server and visible to your team. | | Failed to Upload | The upload hit a problem. The app keeps retrying on its own. | | Processing | (Meetings) uploaded, and Cogram is writing the summary and notes. | Uploads run automatically: when you finalize, about every minute in the background, and whenever the connection comes back. Pull down on any list to refresh it. {% hint style="warning" %} A **Draft** never uploads. Before you wipe the app, switch phones, or hand a device back, check that nothing on the Reports or Observations tabs says **Draft** or **Awaiting Upload**. {% endhint %} ## If an upload keeps failing The app retries failed uploads on its own, so **Failed to Upload** usually resolves itself once you have a solid connection. If it persists, open the item and use **Copy Error Details** to send the details to your admin or to . Two cases cannot be retried, and the app says so: the item was deleted from another device, or the recording's audio file is no longer on the phone. ## Logging out with unsynced work If you log out while items are still waiting to upload, the app warns you: they stay on the device and finish uploading after you sign back in. They are not lost, but they are also not on the server yet, so finish the upload before deleting the app or resetting the phone. ## Before you leave the office A 30-second checklist for a site day with poor signal: 1. Open the app and sign in while you still have connection. 2. On the **Drawings** tab, download the drawing sets you will need. 3. Confirm yesterday's work shows **Uploaded**, not **Awaiting Upload**. ## Related * [Drawings](/field/drawings): downloading drawing sets for offline use. * [Create a field report on site](/field/field-reports): drafts, finalizing, and what happens after. * [Cogram on your phone](/get-started/mobile-app): signing in and finding your way around. # Report types Set up the kinds of field reports your team creates, like a Site Visit Report or a Punch List, each with its own form fields and Word templates. Report Types let you set up different kinds of field reports for your organization, like a Site Visit Report, a Field Observation Report, or a Punch List. Each Report Type has its own form fields, its own export layout, and its own Word templates, so your team always fills in the right details and the exported report comes out in your layout. {% hint style="info" %} You need to be an Org Admin or Org Owner to manage Report Types. Everyone on your team can pick from them when creating a report. {% endhint %} ## Creating a report type To create one: 1. Go to [Organization Settings > Field > Report Types](https://app.cogram.com/dashboard/settings/admin/field-reports#report-types). 2. Click **Create a Report Type**. 3. Enter a name (e.g., "Site Inspection" or "Safety Audit"). 4. Click **Create**. The new Report Type appears in the list, and your team can use it right away.
The Report Types list in Organization Settings, showing a report type with a Default badge and the Create a Report Type button

The Report Types list under Organization Settings > Field

## Setting a default report type The default Report Type is pre-selected whenever someone creates a new report. To set it, hover over a type in the list and click the star that appears. The type then shows a **Default** badge, like in the screenshot above. Click the star again to clear it. Only one type can be the default at a time. ## Editing a report type Click a Report Type in the list to open it. The page has three sections: * **Set Up Mobile Fields**: every report already asks for a title, project, location, observations, and drawings. Add [custom fields](/field/custom-fields) here for anything else your reports need, like the client's firm or the weather. * **Linked Templates**: the Word templates for this type. All of your organization's report templates are available by default. Link specific ones here to narrow the choice, and star one to make it this type's default. Click **Link Template** to add one. * **Format the Export**: how observations look in the exported report. See the next section. To rename the type, click the pencil icon next to the page title.
The Linked Templates section of a report type page, showing a linked template with a Default badge and the Link Template button

Linked Templates on the Report Type page

## Format the Export This section controls how each observation (the notes and photos your team captures on site) appears in the exported Word report. The quickest way to set it up is with the **Apply preset** buttons: **Compact photo card**, **Field note**, **Photo first**, or **Legacy table (default)**. Click **Preview** to see the result on a sample observation, and **Save** when you are happy. **Reset to defaults** takes you back to the standard layout.
The Format the Export section showing the Apply preset buttons, the layout editor with the Add Elements menu, and the Preview and Reset to defaults actions

The Format the Export section on the Report Type page

To fine-tune the layout, edit it directly. The layout repeats once for every observation, and you can insert these placeholders from the **Add Elements** menu: | Placeholder | What it shows | | ------------------- | ---------------------------------------------------------------- | | `{{ obs.index }}` | The observation's number in the report (1, 2, 3, and so on) | | `{{ obs.type }}` | The observation type, for example "Defect" | | `{{ obs.status }}` | The observation status, for example "Open" | | `{{ obs.title }}` | The title captured on site | | `{{ obs.note }}` | The written note from the field | | `{{ obs.photos }}` | The photos, laid out per the settings below | | `{{ obs.drawing }}` | The drawing pin image, if the observation is pinned to a drawing | Under **Advanced layout settings** you can also adjust the photos and drawing pins: * **Photos per row**: 1 to 6 photos side by side (default 3). * **Aspect ratio**: **Auto (source orientation)**, **Portrait (3:4)**, **Landscape (4:3)**, or **Square (1:1)**. * **Photo caption template**: the text under each photo. The default is `Picture {{ photo.index }}: {{ photo.note }}`, and `{{ photo.taken_at }}` is also available. * **Drawing width (px)** and **Drawing caption template**: the size and caption of the drawing pin image. Changes apply to the next export. You do not need to re-upload your Word templates. ## Deactivating or deleting a report type To hide a type from the new-report picker, click the **Deactivate** icon on its row. Existing reports keep their type, and you can reactivate it at any time. Deactivating the default type also clears the default. To remove a type completely, click the **Delete** icon. Deleting also removes the type's custom fields and template links. Existing reports keep their data, but new reports can no longer use the type. ## Related * [Create a field report on site](/field/field-reports): what your team sees on mobile when they use these report types. * [Custom fields](/field/custom-fields): the form fields you add to a Report Type. * [Word templates](/meetings/templates): how to build the Word templates your reports export against. * [Observation types and statuses](/field/observation-types-and-statuses): the Type and Status options your team picks when capturing observations. # Custom fields Add form fields like client firm, weather, or persons present to a report type, so your team fills them in on site and they appear in the exported report. Custom fields are the extra details your team fills in when creating a field report, like the client's firm, the weather, or who was present on site. Each field appears on the report form, and its value lands in the matching spot of the exported Word report. Custom fields belong to a [Report Type](/field/report-types), so each kind of report can ask for different details. {% hint style="info" %} You need to be an Org Admin or Org Owner to manage custom fields. {% endhint %} ## Adding a custom field To add one: 1. Go to [Organization Settings > Field > Report Types](https://app.cogram.com/dashboard/settings/admin/field-reports#report-types) and click the Report Type you want to change. 2. Under **Custom Fields**, click **Add Field**. 3. Fill in the dialog: * **Label**: the name your team sees on the form (e.g., "Client Firm"). * **Template Placeholder**: the name used in your Word template, written there as `{{ name }}`. Use lowercase letters, numbers, and underscores, like `client_firm`. * **Helper Text** (optional): a short instruction shown under the field on mobile. * **Field Type**: how the value is entered. See [Field types](#field-types) below. * **Required**: check this if a report cannot be finalized without the field. 4. Click **Add Field**.
The Add Field dialog with the Label, Template Placeholder, Helper Text, Field Type, and Required inputs

The Add Field dialog

The field appears on the report form right away. Its placeholder shows on the field's row; click it to copy it for your Word template.
The Set Up Mobile Fields section listing custom fields with their placeholder chips, field types, and reorder arrows

The custom fields list on the Report Type page

## Field types | Field type | What your team sees | Good for | | ----------- | ---------------------------------------- | ----------------------------------------------------------- | | Single line | A one-line text box | Short answers: firm name, temperature, project number | | Multi-line | A larger text box that keeps line breaks | Longer answers: materials, comments, summaries | | Table | A table where each entry is a row | Lists: persons present, equipment on site, inspection items | ## Setting up a table field A **Table** field collects a list, one row per entry, like everyone present on site. When you pick **Table** as the field type, a **Columns** section appears in the dialog: 1. Click **Add Column** and enter the column's header (e.g., "Name", "Role", "Company"). 2. Use the **M** toggle to allow multiple lines in a column, and the **R** toggle to make it required. 3. Reorder columns with the up and down arrows. This is the column order in the exported report. A table field needs at least one column. In the exported report, the table grows to fit however many rows your team entered. See [Word templates](/meetings/templates#field-report-placeholders) for how to place it in your Word template. ## Matching placeholder names The placeholder in your Word template must match the field's **Template Placeholder** exactly. If the template says `{{ Client Firm }}` but the field is named `client_firm`, the value will not fill in, and the export shows the literal text `{{ Client Firm }}`. Names like `client_firm`, `temperature`, or `persons_present` work. Names with spaces, capitals, or punctuation (like `Client Firm` or `temp.`) are not accepted. ## Reordering, editing, and deleting fields The **Order** column controls the field order on the mobile form and in the exported report. Use the up and down arrows on each row to reorder. To edit a field, click the pencil icon on its row, make your changes, and click **Save**. To delete a field, click the trash icon. Existing reports keep any values they already had; the field is only removed from new reports. {% hint style="warning" %} If you change a field's **Template Placeholder**, update and re-upload every Word template that uses the old name. {% endhint %} ## Related * [Create a field report on site](/field/field-reports): how your team fills these fields in on mobile. * [Report types](/field/report-types): the report setup each set of custom fields belongs to. * [Word templates](/meetings/templates): builtin placeholders, table placement, and tips for building your Word templates. # Drawing disciplines Choose the disciplines (Architectural, Structural, Civil, and so on) Cogram uses to organize your drawings and to classify new uploads automatically. Drawing disciplines organize your drawings by trade or scope, like Architectural, Structural, or Civil. When someone uploads a drawing, Cogram reads its title block and assigns the best-matching discipline automatically, and your team can filter the Drawings list by discipline. Cogram comes with the 21 standard NCS Level-1 disciplines (from the U.S. National CAD Standard) already set up. These can be switched off but not deleted or renamed. You can add your own disciplines for anything your firm uses beyond the standard. {% hint style="info" %} You need to be an Org Admin or Org Owner to manage the discipline list. {% endhint %} ## Adding a custom discipline To add one: 1. Go to [Organization Settings > Field > Drawing Disciplines](https://app.cogram.com/dashboard/settings/admin/field-reports#drawing-disciplines). 2. Type the name in the input (e.g., "BIM Coordination") and click **Add**. The new discipline is available right away, both in the discipline picker and to the automatic classification. Each discipline name can only be used once.
The Drawing Disciplines section showing the add-discipline input and the list of NCS Level-1 disciplines with active toggles

Drawing Disciplines under Organization Settings > Field

## Deactivating or deleting a discipline To retire a discipline you do not use, click the toggle on its row. It disappears from the picker and from automatic classification, but drawings that already have it keep showing it. Switch the toggle back on to bring it back. To remove a custom discipline completely, click the trash icon on its row. {% hint style="warning" %} Deleting a discipline clears it from any drawings tagged with it. {% endhint %} ## Changing a drawing's discipline Cogram assigns a discipline automatically when a drawing is uploaded. To change it: 1. Open [Field > Drawings](https://app.cogram.com/dashboard/reports/drawings). 2. Click the drawing's **Discipline** cell in the list. 3. Pick the right discipline. The change saves immediately. To update many drawings at once, use bulk edit. See [Drawings](/field/drawings). ## Related * [Drawings](/field/drawings): uploading and organizing drawings on the web, and using them on site. * [Report types](/field/report-types): how drawing pin images appear in exported reports. # Observation types and statuses Choose the Type and Status options your team picks from when capturing observations on site. When your team captures an observation on site, they tag it with a Type (what it is, like a Defect or a Hazard) and a Status (where it stands, like Open or Closed). You choose the options they can pick from, so the whole organization uses the same vocabulary. Both lists live together under [Organization Settings > Field > Observation Options](https://app.cogram.com/dashboard/settings/admin/field-reports#observation-options). {% hint style="info" %} You need to be an Org Admin or Org Owner to manage these options. {% endhint %} ## Adding a type or status To add one: 1. Go to [Organization Settings > Field > Observation Options](https://app.cogram.com/dashboard/settings/admin/field-reports#observation-options). 2. Click **Add Status** in the Statuses list or **Add Type** in the Types list. 3. Enter a name (e.g., "In Review" or "Hazard") and, if you like, a short description. Only admins see the description. 4. Click **Create**. New options are added to the end of the list and show up in the mobile picker right away. To change one later, click the pencil icon on its row and then **Save**.
The Observation Options section with the Statuses and Types lists, default stars, reorder arrows, and the Add Status and Add Type buttons

Observation Options under Organization Settings > Field

## Setting the defaults The default Type and Status are pre-filled whenever someone captures a new observation, saving a tap on site. Hover over an option and click the star to make it the default. Only one Type and one Status can be the default at a time; starring another option moves it. ## Reordering options Use the up and down arrows on each row to reorder. Your team sees the same order in the mobile picker. ## Deactivating or deleting an option To retire an option without touching past observations, click the toggle on its row. It disappears from the picker, and observations that already use it keep it. Switch the toggle back on to bring it back. Delete (the trash icon) only works while no observations use the option. If some do, deactivate it instead. ## Related * [Capture observations](/field/observations): how your team uses these options when capturing on site. * [Report types](/field/report-types): how observation types and statuses appear in exported reports. * [Drawing disciplines](/field/drawing-disciplines): the other list you manage on this page, for classifying drawings. # Agent Cogram comes with an AI agent that has context on your meeting minutes, field reports, and emails. Open Cogram's [Agent](https://app.cogram.com/dashboard/agent) from the left sidebar. Agent can take action across your projects, meetings, and emails. ## Starting a conversation Type a question or instruction in the message composer at the bottom and press **Enter** to send. You can ask Agent to: * draft a follow-up email to meeting participants * summarize a meeting in a custom style * create a project report based on multiple meetings and emails * search for emails about a specific topic * list open action items from recent meetings * find people who are on a project's RFIs, submittals, or transmittals but missing from its directory, and add them (see [Directory](/projects/directory#adding-missing-people-to-a-project-directory-with-agent)) After Agent responds, continue the conversation with follow-up questions. ## Adding context Click the context button (circle icon) in the composer toolbar to scope Agent to specific projects, meetings, or emails. Selected items appear as blue chips above the composer. This helps Agent focus on the right content. You can also **drag and drop files** directly onto the page to attach them to your message. Supported file types include images, PDFs, Office documents, spreadsheets, and plain text files. ## Connected data sources Beyond your meetings, emails, and reports in Cogram, Agent can read from external systems your organization has connected, for example [Autodesk Construction Cloud](/integrations/connecting-autodesk-construction-cloud). Agent only reads what your account can already see, and never changes anything in a connected system. With Autodesk Construction Cloud connected, you can ask Agent about your ACC projects, files and versions, document contents, model properties, issues, RFIs, submittals, forms, photos, sheets, assets, locations, and cost data. See [Connecting Autodesk Construction Cloud](/integrations/connecting-autodesk-construction-cloud) to set it up. With [Deltek VantagePoint](/integrations/connecting-vantagepoint) connected, you can ask about your VantagePoint projects and their teams, contracts and fees, milestones, proposals and awards, plus firms, contacts, and CRM activities. Answers cover the projects you are a member of in Cogram. This capability is enabled per organization by Cogram support: see [Asking Agent about VantagePoint data](/integrations/connecting-vantagepoint#asking-agent-about-vantagepoint-data). ## Threads Conversations are saved as threads. The sidebar on the left lists your threads, organized by **Pinned** and **Recent**. * **Pin** a thread to keep it at the top of your list. * **Archive** a thread to remove it from the list. * **Search** threads using the search bar at the top of the sidebar. * Click **New Thread** to start a fresh conversation. ## Using prompts Prompts are reusable instructions you can save and quickly insert into a conversation. Click the **+** button in the composer toolbar, then choose **My prompts** or **Organization prompts** to browse your prompt library. Clicking a prompt inserts its text into the composer. You can manage your prompts under [Account Settings > Agent Prompts](https://app.cogram.com/dashboard/settings/account-settings/prompts). See [Agent prompts](/agent/agent-prompts) for details. ## Keyboard shortcuts | Shortcut | Action | | ----------------- | -------------------------------------------------------- | | **Enter** | Send message | | **Shift + Enter** | New line | | **Arrow Up** | Recall previous sent message | | **Arrow Down** | Navigate forward through message history | | **Escape** | Stop a running response (only while Agent is generating) | ## In Microsoft Teams You can ask Agent the same project questions inside Microsoft Teams. Mention **@Cogram** in any chat and it answers in a reply thread, using your own project data. See [Cogram for Microsoft Teams](/agent/microsoft-teams) to set it up and start chatting. ## Project Reports Use Agent for project reports or status updates based on multiple meetings and email threads associated with a project. Continue to [Projects](/projects/projects) to learn more. # Workflows Set Cogram to write a recurring project report from your meeting minutes, emails, and field reports, or to draft an RFI or submittal response when one is filed. A workflow puts Cogram to work on its own. There are two kinds: * A **scheduled report** reads the projects you pick and writes a report on a schedule, then emails it to you. * An **email-filed draft** watches your projects and drafts a response whenever an RFI or submittal email is filed. Typical uses: * A Monday morning owner update covering last week's meetings and correspondence * A daily brief for the project team on an active site * A month-end summary for each project you run * A draft RFI response, ready the moment an RFI email is filed to a project Workflows are in [Agent → Workflows](https://app.cogram.com/dashboard/agent/workflows). What they produce is under [Agent → Workflow runs](https://app.cogram.com/dashboard/agent/workflows/runs). ## Start from a template When you create a workflow, Cogram offers ready-made templates. Each one fills in the trigger, data sources, prompt, and output for a common job, so you can use it as-is or adjust it. Select **Blank workflow** to start from scratch instead. ### Report templates These write a report on a schedule. | Template | Who it's for | What it produces | | ------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Weekly Owner Update** | Client or owner | A short weekly summary of progress, decisions, and items needing the owner's attention. | | **Daily Team Brief** | Internal team | A morning brief of action items, open questions, and watch items from the last day. | | **Weekly PM Report** | Project manager | A full weekly status report: decisions, action items, risks, and schedule. | | **Team Lead Weekly Review** | Team or discipline lead | A weekly roll-up across all the projects you oversee, grouped by theme, with blockers and where your attention is needed. | | **Executive Portfolio Brief** | Firm leadership | A weekly portfolio read: each project's health, the top risks across the book, and the decisions that need leadership. | | **RFI & Submittal Log Digest** | PM or coordinator | A weekly status of open RFIs and submittals: what's overdue, who owes the next move, and what is aging. | The **Team Lead Weekly Review** and **Executive Portfolio Brief** templates report across several projects at once, and come pre-set to **Combined report** (one report covering the whole set). Switch to **Separate reports** if you would rather get one per project. ### Draft templates These draft a response when an email is filed. They appear where email filing is enabled for your organization. | Template | Who it's for | What it produces | | -------------------- | ------------ | ------------------------------------------------------------------------------ | | **RFI Intake** | Project team | Drafts a response when an RFI email is filed to a watched project. | | **Submittal Intake** | Project team | Drafts a review response when a submittal email is filed to a watched project. | See [Draft RFIs and submittals from filed email](#draft-rfis-and-submittals-from-filed-email). ## Creating a workflow 1. Go to [Agent → Workflows](https://app.cogram.com/dashboard/agent/workflows) and select **New workflow**. 2. Choose a template, or select **Blank workflow** to start from scratch. See [Start from a template](#start-from-a-template). 3. Give the workflow a name. 4. Work through the steps on the canvas. Select any step to configure it: **Trigger**, **Data sources**, **Prompt**, **Report output**, and **Notifications**. 5. Select **Save**. A new workflow is saved as **Draft**. It does not run until you activate it. ### Trigger The trigger decides what starts the workflow. Where email filing is available, a **Trigger type** step offers two choices: * **Schedule (generate a report)**: run on a schedule. Set a **Frequency** (Daily, Weekly, Every 2 weeks, or Monthly), a **Day of week** where the frequency needs one, and a **Time**. * **Email filed (draft an RFI/submittal)**: run whenever a matching email is filed to one of the workflow's projects. Choose the **Record type**, RFI or Submittal. See [Draft RFIs and submittals from filed email](#draft-rfis-and-submittals-from-filed-email). If email filing is not enabled for your organization, every workflow runs on a schedule and this step shows only the **Frequency**, **Day of week**, and **Time** fields. ### Data sources This step decides which projects the report covers and what it reads. Under **Input projects**, choose one of: * **Specific projects**: pick the projects yourself * **Projects I'm an owner of** * **Projects I'm a member of** * **Projects I'm an owner or member of** The three role-based options are re-checked on every run, so a project you join later is picked up without editing the workflow. See [Choosing input projects](#choosing-input-projects) below. Under **Include data from**, select any combination of **Meeting minutes**, **Emails**, and **Field reports**. Under **Time range**, choose how far back each run reads: Last 24 hours, 3 days, 7 days, 14 days, or 30 days. Match this to your frequency. A weekly report that only reads the last 24 hours will miss most of the week. When a workflow covers more than one project, choose a **Report mode**: * **Separate reports**: one report per project, sent as separate emails * **Combined report**: one report covering all projects ### Prompt Write the instructions for the report: what to cover, how to structure it, and who it is for. Be specific about what matters to the reader. For an owner update, for example, you might ask for progress since the last report, decisions taken, outstanding RFIs, and items awaiting the owner's response. ### Report output Set the **Report title**. Titles support a date, so a recurring report is easy to tell apart in a list. **Include source references** links report sections back to the documents they came from. Leave this on when someone will need to check a statement against the original minutes or email. ### Notifications Turn on **Email notification** to get an email when the report is ready. The email includes a link to the full report in Cogram. ## Draft RFIs and submittals from filed email Where email filing is enabled, a workflow can draft a response the moment a matching RFI or submittal email is filed, so a first draft is waiting for you instead of a blank page. Start from the **RFI Intake** or **Submittal Intake** template, or create a workflow and set its **Trigger type** to **Email filed (draft an RFI/submittal)**: 1. In the **Trigger** step, choose the **Record type**: **RFI** or **Submittal**. 2. In **Data sources**, choose the projects to watch. The workflow runs whenever a matching email is filed to one of them. 3. In **Prompt**, set how the draft should read. The template drafts a grounded response that cites project documents; adjust it to your firm's wording. 4. Save and activate the workflow. When a matching email is filed, Cogram matches it to an existing RFI or submittal (or creates one) and drafts a response against it. The draft appears as a run under [Agent → Workflow runs](https://app.cogram.com/dashboard/agent/workflows/runs); open it to review and edit. As with every Cogram draft, check it before it goes out. Filing only triggers a draft when an active RFI Intake or Submittal Intake workflow is watching that project. Without one, the email is filed as usual and nothing is drafted. ## Activating a workflow A workflow only runs once it is **Active**, whether it runs on a schedule or on a filed email. Open the workflow and select **Activate**. To stop it without deleting it, select **Pause**. A paused workflow keeps its configuration and stops running. To test a workflow before you rely on it, select **Run now**. This runs it immediately against the current data, which is the fastest way to check that your prompt produces what you want. ## Choosing input projects **Specific projects** is the right choice when the workflow covers a fixed set of projects that does not change. The role-based options suit people who run many projects and do not want to revisit the workflow every time their portfolio changes. Cogram resolves them fresh on each run, using your project roles at that moment. Two rules apply to the role-based options: * **A workflow covers at most 20 projects.** If more than 20 match, Cogram uses the 20 most recently active and tells you in the builder how many were left out. * **Dormant projects are left out.** A project with no meetings, emails, or field reports in the last 90 days is skipped. A project you created recently counts as active even before anything is filed to it. The builder shows which projects match right now, so you can check the list before saving. That preview is a snapshot: the projects are worked out again on every run, so the set can change. Role-based selection follows the roles of the person who created the workflow, not whoever is looking at it. If you open a colleague's workflow, the projects shown are the ones their roles resolve to. ## Owner project Every workflow belongs to a project, shown as its **Owner project**. This controls who can see and change it: * Members of the owner project can see the workflow and its runs * Owners of that project can edit it * Only the person who created the workflow can move it to another project Leave the owner project as your **Personal workspace** to keep a workflow to yourself. Set it to a shared project when the team should see it. The owner project is separate from the input projects. A workflow can sit in one project and report on others. ## Reading the results Go to [Agent → Workflow runs](https://app.cogram.com/dashboard/agent/workflows/runs) to see every run, its status, and the report or draft it produced. A run is **Completed** when the report or draft is ready. **Failed** means the run did not finish; open it to see the error. Reports are drafts written by AI. Before sending one to an owner, a client, or a contractor, check it against the source material: names, dates, decisions, action items, numbers, and anything contractual. Keep **Include source references** on to make that check quick. ## Troubleshooting **The report is empty or thin** *Likely cause:* The time range is shorter than the gap between runs, or the selected data sources hold nothing for the period. *Fix:* Widen the **Time range** to at least cover the interval between runs, and confirm that the projects have meetings, emails, or field reports filed for that period. **A project is missing from a role-based selection** *Likely cause:* The project has had no activity for 90 days, you do not hold the required role on it, or more than 20 projects matched and this one fell outside the 20 most recently active. *Fix:* Check your role on the project under [Projects](/projects/projects). If more than 20 projects match, switch to **Specific projects** and pick the ones that matter, or narrow the role you select on. **"Nothing to run" when using Run now** *Likely cause:* No project currently matches the role-based selection, so there is nothing to report on. *Fix:* Confirm you hold the selected role on at least one project with recent activity. Nothing is wrong with the workflow; it will run as soon as a project matches. **The workflow never runs on its own** *Likely cause:* It is still in **Draft** or has been **Paused**. *Fix:* Open the workflow and select **Activate**. **The report does not cover what you asked for** *Likely cause:* The prompt is too general, or the data source the content lives in is not selected. *Fix:* Make the prompt specific about sections and audience, and confirm **Include data from** covers the right material. Use **Run now** to test each change. ## Next steps * [Agent](/agent/agent): ask questions across your projects on demand * [Projects](/projects/projects): project roles and membership * [Notification bell](/your-account/notifications): control the emails Cogram sends you # Cogram for Microsoft Teams Chat with Cogram in Microsoft Teams: mention @Cogram in any chat to ask about your projects. Includes the one-time admin setup. Bring Cogram into Microsoft Teams. Once installed, mention **@Cogram** in any chat to ask questions about your projects in plain language (meetings, action items, emails, and documents) and get answers based on your project data. > **Just want to chat with Cogram?** The setup steps further down are a one-time job for your IT admin. If Cogram already appears in your Teams, jump straight to [**Talking to @Cogram**](#talking-to-cogram). That's all you need. ## What the Teams app does Cogram is an AI platform for the architecture, engineering, and construction (AEC) industry. It organizes your projects' meetings, emails, documents, and field reports, and automates project admin. The Teams app puts that same Q\&A inside Microsoft Teams. Mention **@Cogram** in any chat and it answers in a reply thread, using your own Cogram project data, so you can stay in Teams instead of switching to the web app. > Cogram answers using the **signed-in user's own** Cogram project data. Each person only sees the projects they already have access to in Cogram. ## Talking to @Cogram 1. Go to [**Microsoft Teams**](https://teams.cloud.microsoft/). 2. Open the **Cogram** chat, or any chat where the app is installed. 3. Type **@** and pick **Cogram** from the list, then type your question and send. Cogram replies in a thread on your message. The first time you open Cogram (or any time you type **help**) it shows a welcome card with what it can do, example prompts, and the AI-generated-content notice:
Cogram welcome card in Teams reading Hi, I'm Cogram, with command descriptions and example prompt buttons

The Cogram welcome card: type help to show it again

Example questions: * "What are my available projects?" * "Provide an overview of all my projects as a table: name, owner, when it was last updated, and how many action items there are." * "When did we agree on the price with John Smith?" You can also message Cogram directly in a 1:1 chat, or mention it in a channel where it is installed. ## Installation Getting Cogram into Teams is a two-part, one-time job: an admin makes the app available to your organization, then each person adds it in their own Teams. ### Setting up Cogram for your organization > **For admins.** These are one-time steps done by an admin. Regular users can skip them and go to [Talking to @Cogram](#talking-to-cogram). Two one-time admin steps before anyone can use Cogram in Teams: connect Microsoft Teams in Cogram, then make the Cogram app available in the Teams admin center. #### 1. Connect Microsoft Teams in Cogram > **Who:** a **Cogram organization admin**. In Cogram, go to [**Organization Settings → Integrations → Microsoft Teams**](https://app.cogram.com/dashboard/settings/admin/integrations#teams) and click **Connect**. Sign in with a Microsoft 365 admin account and grant the requested permissions. This links your Microsoft 365 tenant (your organization's Microsoft account) to your Cogram organization so Cogram can respond to messages in Teams. You only do this once per organization: no per-user setup is needed afterward.
Microsoft Teams integration card in Cogram Organization Settings with a Connect button

Organization Settings → Integrations → Microsoft Teams → Connect

#### 2. Find the Cogram app in the Teams admin center > **Who:** a **Microsoft Teams administrator**. Go to the [**Cogram app** in the Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps/02ae177c-b63f-4700-8f4f-06d327bc7147/users-and-groups), or search for **Cogram** in [**Teams admin center → Manage apps**](https://admin.teams.microsoft.com/policies/manage-apps) and open it. The app page shows the version, who it's installed for, and who it's available to.
Cogram app page in the Teams admin center showing the About tab and availability

The Cogram app page in the Teams admin center

#### 3. Install the app Open the [**Users and groups**](https://admin.teams.microsoft.com/policies/manage-apps/02ae177c-b63f-4700-8f4f-06d327bc7147/users-and-groups) tab and click **Install app**.
Cogram app Users and groups tab with the Install app button highlighted

On the Users and groups tab, click Install app

Under **Install to**, choose who gets Cogram: * **Everyone**: everyone in your Microsoft organization, including guests and external users. * **Specific users or groups**: search for and select individual users or groups.
Edit installs panel with the Install to dropdown open, showing Everyone, Specific users or groups, and No one

Under Install to, choose Everyone or specific users or groups

Click **Apply**. ### Add Cogram in Teams Once your administrator has made Cogram available (see [Setting up Cogram for your organization](#setting-up-cogram-for-your-organization) above), each person adds it in Teams: 1. Go to [**Microsoft Teams**](https://teams.cloud.microsoft/). 2. Open **Apps** (the **+** button in the left sidebar), find **Cogram** under **Added by your org**, and click **Add** (or **Open** if it's already there for you).
Teams Apps page with the Apps (+) button in the sidebar and the Cogram app under Added by your org

Open Apps, then add or open Cogram from Added by your org

## Troubleshooting **Cogram doesn't appear in Teams:** Your administrator hasn't made the app available to you yet, or installed it only for specific users. Ask your Teams administrator to install Cogram for your account (see [Setting up Cogram for your organization](#setting-up-cogram-for-your-organization)). **Cogram doesn't respond at all:** Your Cogram organization may not be connected to Microsoft Teams yet. A Cogram org admin needs to connect it at [Organization Settings → Integrations → Microsoft Teams](https://app.cogram.com/dashboard/settings/admin/integrations#teams). **Cogram replies that it can't find your account:** The Teams app only answers people who have a Cogram account in an organization that uses Cogram. Ask your Cogram organization admin to invite you by your email. **No response when you mention @Cogram:** Make sure you selected **@Cogram** from the mention suggestions, and that the app has been added in Teams. ## Next steps * [Agent](/agent/agent): the same project Q\&A inside the Cogram web app * [Projects](/projects/projects): how your project data is organized # Agent prompts Create and manage reusable prompts for Agent, and browse prompts shared across your organization. Prompts are reusable instructions you can save and quickly insert into an Agent conversation. Open the avatar menu at the bottom of the left sidebar and go to [Account Settings > Agent Prompts](https://app.cogram.com/dashboard/settings/account-settings/prompts) to manage your prompt library. (If your organization is still on the classic Assistant, this tab is labeled **Assistant Prompts**.) ## My Prompts vs. Organization Prompts * **My Prompts**: private to you. * **Organization Prompts**: shared across your entire organization. Any member can use them, but only admins can create them. Non-admins can copy an organization prompt into their personal library. ## Creating a prompt Click **New Prompt**, enter a title and prompt text, optionally add tags, and click **Add to library**. Admins can toggle **Make this prompt visible organization-wide** to share a prompt with all members. ## Using a prompt Click the **+** button in Agent's message composer and select **My prompts** or **Organization prompts**. Click any prompt to insert its text into the composer. ## Editing and deleting prompts For personal prompts, only the creator can edit or delete them. For organization prompts, the creator and any org admin or owner can edit or delete them. Deleting an organization prompt removes it for everyone, and this can't be undone. # Changing your password or email To change your email or password, log into Cogram, open the avatar menu at the bottom of the left sidebar, and go to [Account Settings > Account](https://app.cogram.com/dashboard/settings/account-settings/security). # Two-factor authentication (2FA) To enable two-factor authentication, log into Cogram, open the avatar menu at the bottom of the left sidebar, and go to [Account Settings > Account](https://app.cogram.com/dashboard/settings/account-settings/security).\ \ Then click "Set up 2FA" and use a phone app like [Google Authenticator](https://support.google.com/accounts/bin/answer.py?hl=en\&answer=1066447), [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app), or [1Password](https://1password.com/) to scan the QR code, or to enter the secret code for 2FA set-up.\ \ You can now use your authenticator app to get 2FA codes when prompted during sign-in. **Keep your authenticator app safe.** If you lose access to it, you'll need it to sign in, so set up your codes on a device you'll keep. If you're locked out, contact to regain access. # Notification bell Use the notification bell to stay on top of task assignments and project access requests, and act on them without leaving your current page. The notification bell in the header collects what needs your attention in Cogram, for example a task assigned to you, or a request to join a project you manage. You can act on many notifications directly from the bell. ## The notification bell Select the bell in the header (the top row that runs across the content area) to open your notifications. A badge on the bell shows how many notifications you haven't dealt with yet. Each notification shows what happened and when. Selecting a notification takes you to the related item; for example, a task notification opens that task on the project board. Opening the panel does not clear the badge. The badge clears as you deal with items: * Acting on a notification (for example, approving an access request) clears it. * Opening the related item (from the bell, from the email, or by navigating there yourself) clears the notification for it. When there is nothing left, the panel shows "You're all caught up." ## What arrives in the bell | Notification | When you receive it | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | **Task assignments** | A task or action item on a project board is assigned to you. | | **Approvals & requests** | Someone requests access to a project you can grant access to (organization admins and owners). | | **Mentions** | Someone @mentions you in a [project chat](/projects/project-chat) channel. Selecting the notification opens that message. | All three also send an email by default. You can turn the email off per category. See [Notification preferences](/your-account/notifications-1). Other Cogram notifications (post-meeting summaries, meeting failure alerts, and similar) are email-only today. ## Approve or decline an access request from the bell When someone requests access to a discoverable project, organization admins and owners receive a notification with inline actions. 1. Select the bell to open your notifications. 2. On the access request, choose the role to grant from the dropdown (Lead, Member, or Viewer; Lead only if your organization has that role turned on). 3. Select **Approve** to grant access, or **Decline** to reject the request. The requester is notified of the outcome by email, and the notification clears for everyone who received it. If a colleague resolves a request first, it disappears from your bell too. If you'd rather review requests in one place, admins can select **Manage in settings** at the bottom of the panel to open the full request list under [Organization Settings → Projects](https://app.cogram.com/dashboard/settings/admin/projects?tab=request-access). ## Troubleshooting **A notification email arrived, but the bell shows nothing** * Likely cause: someone already resolved the item, or you already visited it. Both clear the notification. * Fix: nothing to do; the item itself remains available (for example, the request list under Organization Settings → Projects). **You expected an access-request notification but didn't receive one** * Likely cause: access-request notifications go to organization admins and owners. * Fix: check your role with your organization admin. **Notifications older than about three months are gone** * Notifications are a short-lived feed and are removed after 90 days. The underlying items (tasks, requests, meetings) are not affected. ## Next steps * [Notification preferences](/your-account/notifications-1): choose where each category reaches you * [Projects](/projects/projects): project access and discoverability # Notification preferences Choose where Cogram notifies you (in the notification bell, by email, or both), including task assignments, access requests, and meeting emails. Go to [Account Settings > Notifications](https://app.cogram.com/dashboard/settings/account-settings/notifications) to control how Cogram notifies you. Notifications reach you on up to two channels: * **In-app**: the [notification bell](/your-account/notifications) in the header row * **Email**: sent to your account email address ## Tasks & approvals These notifications appear in the bell and, by default, also send an email. The in-app channel is always on. Turning email off never removes the item from your bell. Toggle the **Email** column per category: | Category | When it fires | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Task assignments** | A task or action item is assigned to you. | | **Approvals & requests** | Someone requests access to a project you can grant access to. | | **Mentions** | Someone @mentions you in a [project chat](/projects/project-chat) channel. Emails are batched, and skipped entirely if you have already read the channel. | ## Email-only notifications These notifications are sent by email only (shown with a dash in the In-app column): | Setting | What it does | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Post-meeting summary email** | Automatically send a summary email after a meeting ends. | | **Shared meeting minutes** | Receive an email with a link to the draft meeting minutes when a colleague shares them with you. Only sent if your organization has enabled share-link emails to invitees. | | **Pre-meeting briefing emails** | Receive a briefing email before recurring meetings with context from previous meetings. | | **Meeting failure** | Receive an email when Cogram is unable to join or transcribe a meeting. | | **Added to project** | Receive an email when you are added to a project. | | **Workflow reports** | Receive scheduled workflow report emails. | ## Locked settings Your organization or group admin may lock certain notification settings. When a setting is locked, the toggle is disabled and a lock icon appears with a message explaining who locked it (e.g., "Locked by your organization."). Contact your admin if you need a locked setting changed. > **Note:** Organization admins can manage notification defaults and locks for all members under [Organization Settings > Notifications](https://app.cogram.com/dashboard/settings/admin/notifications). See [Organization notification settings](/organization-administration/notifications) for details. # Appearance Switch Cogram between light, dark, and system appearance. Open the avatar menu at the bottom of the left sidebar and select the appearance control. Each click cycles through three modes: * **Light**: the standard light theme. * **Dark**: easier on the eyes in low light. * **System**: follows your operating system, switching when it switches. The control's label and icon show your current choice: **Light theme** (sun), **Dark theme** (moon), or **System theme** (monitor). New users start on **System**. Your choice is saved in your browser rather than your account, so set it again on another browser or device. # Organization roles Understand the three organization-level roles in Cogram (Owner, Admin, and Member) and what each role can do. Every user in a Cogram organization has one of three organization-level roles: **Owner**, **Admin**, or **Member**. These roles control what a user can do across the entire organization, including creating and managing projects. Organization roles are separate from [Project roles](/projects/project-roles), which control what a user can do within a specific project. ## Role Overview | Permission | Owner | Admin | Member | | -------------------------------------- | :---: | :---: | :----: | | Access and view their own projects | ✓ | ✓ | ✓ | | Create new projects | ✓ | ✓ | ✓ ¹ | | View any project in the organization | ✓ | ✓ | | | Update settings on any project | ✓ | ✓ | | | Archive or delete their own projects | ✓ | ✓ | ✓ ¹ | | Delete any project | ✓ | ✓ | | | Create, edit, or delete project types | ✓ | ✓ | | | Invite and remove organization members | ✓ | ✓ | | | Manage SSO, billing, and integrations | ✓ | ✓ | | | Assign and remove the Admin role | ✓ | | | ¹ Members can create, archive, and delete their own projects by default. An org Admin or Owner can restrict these actions to Admins and Owners only. See [Project management permissions](/projects/project-management-permissions). ## Roles in Detail ### Owner Full control over the organization. Owners can manage all projects, invite or remove members, configure integrations, and assign or revoke Admin roles. There is typically one Owner per organization. ### Admin Organization-wide administrator. Admins can create, update, and delete any project in the organization, even projects they are not a member of. Admins can also invite members and manage organization settings, but cannot assign or revoke Admin roles. This role is suited for project managers or operations leads who need to oversee the full project portfolio. ### Member Standard organization user. Members can create new projects and access any project they have been added to. They cannot view, modify, or delete projects they have not been invited to, and have no access to organization administration settings. An org Admin or Owner can optionally [restrict project creation, archiving, and deletion](/projects/project-management-permissions) to Admins and Owners only. ## How Organization Roles Interact with Project Roles When an Owner or Admin accesses a project, they have full administrative rights over that project regardless of whether they have been explicitly added as a project member. This allows Owners and Admins to manage the project portfolio without needing to be listed on every project. For Members, access to a project's content is governed entirely by their [Project Role](/projects/project-roles) (Owner, Lead, Member, or Viewer) within that project. ## Groups Groups let you organize users by team, department, or office location and assign project access in bulk. See [Groups](/organization-administration/groups) for full details on creating groups, managing membership, and how group-based project access works. ### Group Admin is not an organization role The **Group Admin** badge is a per-group capability, not an organization role. It can be granted to any user in the organization (including Members, Admins, and Owners) and the user keeps their existing org role. A Group Admin can manage members and settings for the specific groups they administer, but has no organization-wide authority. See [Group Admin Role](/organization-administration/groups#group-admin-role) for details. ## Assigning Organization Roles Organization roles are managed in [Organization Settings > Users](https://app.cogram.com/dashboard/settings/admin/users). Only Owners can assign or remove the Admin role. # Groups Organize users into groups for easier project access management and team structure. Groups let you organize users within your organization, for example by team, department, or office location. Instead of adding users to projects one by one, you can assign an entire group to a project and all group members automatically get access. Groups are created and managed in [Group Management](https://app.cogram.com/dashboard/settings/group/all), reached from the avatar menu under **Group Settings**. ## What Groups Are For * **Project access**: Assign an entire group to a project so all members get access at once. See [Project Roles > Group Access](/projects/project-roles#group-access) for details. * **Team structure**: Reflect your organization's structure (offices, departments, disciplines) so admins can manage users by team rather than individually. * **Settings and insights**: Group Admins can manage notification locks and custom insight preferences at the group level. ## How Groups Work Each group has a name, an optional description, and one or more members. **A user can belong to multiple groups at the same time**: for example, a user can be in both an "Engineering" group and a "London Office" group. Adding a user to a group is additive: their other group memberships are unchanged. One group can be marked as the **default group**. New members added to the organization are automatically placed in the default group. Both the default flag and the settings-group flag are set per group on the group's **Overview** tab, in the **Settings** section. ## Setting the Default Group The **default group** is where every new organization member lands automatically. Exactly one group is the default at any time. To change which group is the default: 1. Go to [Group Management](https://app.cogram.com/dashboard/settings/group/all) and open the group you want to make the default. 2. On the **Overview** tab, find the **Settings** section. 3. Turn on **Set as default group for organization**. 4. If another group is currently the default, confirm the swap in the **Change the default group?** dialog. The flag is moved to the new group and cleared from the old one.
The Default group's Overview tab, with the Settings section and the "Set as default group for organization" toggle

The Set as default group for organization toggle, in the Settings section of a group's Overview tab

**Expected result:** the chosen group is now the default; new members are added to it automatically. Note: you cannot turn the default flag *off* directly; an organization must always have exactly one default group. To move it, turn the flag *on* for a different group, which clears it from the current one. ## Settings Group A user's **settings group** determines which group's settings (notification locks and custom insight preferences) apply to them. A user can belong to many groups, but **only one of those groups may be marked as a settings group**: this avoids ambiguity over which group's settings cascade to the user. In the [Group Management](https://app.cogram.com/dashboard/settings/group/all) table, the **Settings Group** column marks which groups are configured as a settings group. To set or unset a group as a settings group: 1. Go to [Group Management](https://app.cogram.com/dashboard/settings/group/all) and open the group. 2. On the **Overview** tab, find the **Settings** section. 3. Turn **Use this group for member settings** on or off.
The Default group's Overview tab, with the Settings section and the "Use this group for member settings" toggle

The Use this group for member settings toggle, in the Settings section of a group's Overview tab

**Expected result:** when on, this group's settings cascade to all of its members. If turning it on would put any member in two settings groups at once, the change is rejected with a conflict. Resolve it by removing the affected user from one of the conflicting groups first, then try again. ## Creating and Managing Groups To create a group, go to [Group Management](https://app.cogram.com/dashboard/settings/group/all) and click **Add Group**. From there you can: * Set the group name and description * Add or remove members * Assign group admins After the group is created, open it to set its default and settings-group flags on the **Overview** tab (see [Setting the Default Group](#setting-the-default-group) and [Settings Group](#settings-group)) and to assign it to projects.
The Add Group dialog with fields for group name, group description, group admins, and group members

The Add Group dialog

## Group Admin Role A **Group Admin** is a user who has been granted scoped admin authority over one or more specific groups. It is not an [organization role](/organization-administration/organization-roles): a Group Admin keeps whatever org role they already have (Member by default), and the badge can be assigned to any user in the organization, including Owners and Admins. The same user can administer multiple groups. Within the groups they administer, a Group Admin can: * Add or remove members * Edit the group name, description, and group-level settings (notification locks, custom insight preferences, learned words) A Group Admin **cannot** create or delete groups, and cannot grant or revoke the Group Admin badge for other users. Those actions are reserved for Owners and Admins. To assign or remove the Group Admin badge, open a group from [Group Management](https://app.cogram.com/dashboard/settings/group/all) and edit its admins list. Granting and revoking the badge is restricted to Owners and Admins. ## Managing Group Membership Anyone who can manage a group's membership can add or remove **any user in the organization**, regardless of that user's organization role. Adding an Owner or Admin to a group does not change their org-wide authority; the membership row is purely about group association. | Action | Owner | Admin | Group Admin | | --------------------------------------------- | :---: | :---: | :---------: | | Create or delete groups | ✓ | ✓ | | | Add or remove users in a group | ✓ | ✓ | ✓ ¹ | | Edit group name, description, and settings | ✓ | ✓ | ✓ ¹ | | Grant or revoke the Group Admin badge | ✓ | ✓ | | | Mark a group as the default or settings group | ✓ | ✓ | ✓ ¹ | ¹ Group Admins can only act on groups they administer. To manage a group's membership, go to the group's members page in [Group Management](https://app.cogram.com/dashboard/settings/group/all) and use the **Add members** button. ## Syncing Membership from Microsoft Entra ID Organizations that connect Microsoft group sync (under **Admin → Integrations → Microsoft**) can map a Cogram group to a group in their Microsoft Entra ID directory. Once mapped, the Cogram group's membership mirrors the Microsoft group: members added or removed in Microsoft are added or removed in Cogram on the next sync. A few things to know: * Sync is **one-directional and membership-only**. Cogram never changes anything in your Microsoft directory, and the group's name, settings, admins, and project assignments stay managed in Cogram. * Cogram syncs every mapped group **automatically about once an hour**. A member you add to (or remove from) the Microsoft group gains (or loses) their Cogram group access, including access to any projects the group is assigned to, on the next sync, usually within an hour. To apply a change immediately, an Owner or Admin can open the group's **Microsoft Sync** tab and choose **Sync now**. * Only **direct members** of the Microsoft group are synced. Users who belong via a nested group are not included; they appear the same way on the group's **Members** page in the Azure portal. * Microsoft members are matched to Cogram users **by email address**. Members without a matching Cogram user are counted as skipped; no account is created for them. * While a group is mapped, its membership **cannot be edited in Cogram**: the Members page is read-only for that group. Remove the mapping to edit members manually again; existing membership is kept. * Mapping a group, running a sync, and removing a mapping are restricted to **Owners and Admins**. The group's **Microsoft Sync** tab shows the sync status and a history of recent runs. Expand any run in that history to see exactly which members it added or removed. * If a sync fails (for example the Microsoft group was deleted or admin consent was revoked), syncing pauses and existing membership is preserved until the issue is resolved. ## Groups and Project Access When a group is assigned to a project, every member of the group gets access to that project with the role the group was given: **Lead**, **Member**, or **Viewer**. **Owner** is never granted through a group. Group-assigned users appear in a separate **Via groups** section in the project's members list. > **Availability**: **Lead** appears in the group's role list only for organizations that have the Lead role turned on. See [Project roles](/projects/project-roles#lead). If a user is both directly added to a project and a member of an assigned group, their effective role is the higher of the two. With a group that grants Member: a direct **Owner** keeps Owner; a direct **Viewer** is elevated to **Member**; a direct **Member** stays at Member. With a group that grants Lead, that same direct **Viewer** or **Member** is raised to **Lead**. Because a user can belong to multiple groups, project access via groups is a union: a user keeps access as long as they are in **any** assigned group. To revoke a user's group-based access to a project, either remove them from every assigned group that grants that access, or unassign the group from the project in [Group Management](https://app.cogram.com/dashboard/settings/group/all). # Licensing How Cogram licensing works: module entitlements, seats, and the two access levels (Full access and View & Respond). Licensing controls which module features each person in your organization can use. It is a separate axis from [Organization roles](/organization-administration/organization-roles) and [Project roles](/projects/project-roles): roles decide what you can reach and do within the organization and its projects, while licensing decides which **modules** you can act in. ## How licensing works Cogram licensing has two layers: * **Module entitlements**: which modules your organization's plan includes. Entitlements are set by Cogram when your plan is configured. A module your plan doesn't include shows as **Disabled** and can't be assigned to anyone. * **Seats**: within an entitled module, each person given access consumes one seat. Seat counts are managed by Cogram; your admins assign the seats you hold to specific users. ### Licensed modules Cogram has six licensable modules: * **Meeting Minutes** * **Field Reports** (includes observations and drawings) * **Email Management** (includes transmittals) * **RFI / Submittals** * **Transmittals** (legacy standalone module; new plans get transmittals through Email Management) * **Assistant** ## Access levels Each member has one of two access levels, derived from the module licenses they hold: * **Full access**: holds one or more module licenses. Can create, edit, delete, and export in the modules they're licensed for. * **View & Respond**: holds no module licenses. Read-only access to the projects they belong to, on both web and mobile. ### What View & Respond includes A View & Respond member, in the projects they belong to, can: * Open and read content across the licensed modules below. * Download files and export reports. * Take part in the project task board. The board is not a licensed module, so licensing never blocks it. What you can do on the board depends on your [project role](/projects/project-roles), not your access level. They cannot create, edit, delete, or take other write actions in the licensed modules. | Module | View & Respond can | Full access adds | | ---------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Meeting Minutes | Browse meetings, open detail and minutes, download and export | Schedule, record, and upload meetings; edit, delete, and share meetings; extract observations | | Field Reports | Open reports, observations, and drawings; download drawings and templates | Create and finalize reports; add, edit, delete observations; upload and edit drawings; manage drawing sets | | Email Management | Browse and search filed emails, open detail, download attachments | File, unfile, and re-file emails; export; bulk actions | | RFI / Submittals | Browse lists and boards, open detail, download packages | Respond; manage reviewers; sync to Procore | | Transmittals | Open transmittals and their attached files | Create, edit, send, close, acknowledge; export | | Assistant | No access | Use the Assistant | An **Email Management** seat also covers all transmittal write actions. A separate Transmittals seat is only relevant on legacy plans that hold Transmittals as a standalone module. > **View & Respond is not the same as a project Viewer.** "View & Respond" is an organization-level access level (which modules you're licensed for). A project **Viewer** is a [project role](/projects/project-roles) (what you can do inside one project). The two are independent. ## Managing licenses Owners and Admins manage licenses in [Organization Settings > Licenses](https://app.cogram.com/dashboard/settings/admin/licenses). The page shows: * A **seat-usage strip** for each module: seats used out of your total. If a module goes over its seat count it keeps working for everyone already assigned; contact Cogram to adjust seats. * A members table with a per-module switch for each user, plus an always-on **View & Respond** column that every member has by default. ### Set the default for new members The **New members get Full access by default** toggle controls what newly joined members receive: * **On**: new members are granted Full access to every module the organization has enabled. * **Off**: new members join as View & Respond, with no module licenses. The organization Owner is always Full access, regardless of this setting. ### Choose an access level when inviting When you add users in [Organization Settings > Users](https://app.cogram.com/dashboard/settings/admin/users), the **Access level** selector sets what the invited users receive: * **Organization default**: follows the toggle above. * **Full access (all modules)** * **View & Respond** ### Change a member's access On the Licenses page: * Toggle a single module on or off for one member using the switch in that member's row. * Select one or more members, then use **Assign module…** or **Revoke module…** to change specific modules in bulk, or **Grant Full access (all modules)** / **Revoke all access** to change everything at once. Revoking every module license leaves a member as View & Respond. Enabling a new module organization-wide grants it only to members who already hold at least one license; View & Respond members do not receive the new module automatically. # Single sign-on (SSO) SAML-based SSO is supported as part of Cogram's Enterprise plan. Includes the service provider details and the Microsoft Entra ID (Azure AD) setup steps. Cogram supports user authentication through SAML 2.0. Single Sign-On lets your team sign in to Cogram with your existing identity provider, under your own password, MFA, and conditional access policies. Setup is a joint exercise: you configure Cogram as an application in your identity provider, send Cogram the resulting metadata, and Cogram registers your domain. Email to start, and we will confirm each step with you. ## Service provider details Cogram is the service provider. Use these values wherever your identity provider asks for them. | Field | Value | | -------------------------------------------- | -------------------------------------------------------------- | | Identifier (Entity ID) | `https://prod1.us-east-1.cogram.com/auth/v1/sso/saml/metadata` | | Reply / Assertion Consumer Service (ACS) URL | `https://prod1.us-east-1.cogram.com/auth/v1/sso/saml/acs` | | Metadata URL | `https://prod1.us-east-1.cogram.com/auth/v1/sso/saml/metadata` | | NameID format | `emailAddress` or `persistent` | ## Microsoft Entra ID (Azure AD) > **Who:** an administrator who can create enterprise applications in your Microsoft Entra ID tenant. ### 1. Create the application 1. Open the [Microsoft Azure portal](https://portal.azure.com/). 2. Go to [**Enterprise applications**](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview) and click **New application**.
Enterprise applications page with the New application button highlighted in the toolbar

Enterprise applications → New application

3. Click **Create your own application**. 4. Name the application, for example `Cogram SAML SSO`, choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**.
Create your own application panel with the name field and the Non-gallery option highlighted

Name the app and pick Non-gallery

### 2. Configure SAML 1. On the application's landing page, click **Set up single sign on** → **Get started**. If that tile is not there, open **Manage** → **Single sign-on** in the left sidebar. 2. Choose **SAML**. 3. Under **1. Basic SAML Configuration**, click **Edit** and enter the [service provider details](#service-provider-details): the Entity ID as **Identifier**, and the ACS URL as **Reply URL**. Click **Save**. **Sign on URL**, **Relay State**, and **Logout Url** stay empty.
Basic SAML Configuration card showing the Cogram Identifier and Reply URL, with the optional fields left blank

Basic SAML Configuration, filled in with Cogram's Entity ID and ACS URL

### 3. Map the attribute claims Cogram reads the user's email address and name from the assertion, so these four claims have to be present. Some are mapped by default. 1. Under **2. Attributes & Claims**, click **Edit**. 2. Open **Required claim** → **Unique User Identifier** and confirm the **Name identifier format** is **Email address**. 3. Check the following under **Additional claims** and add anything missing: | Claim name | Source attribute | | -------------------------------------------------------------------- | ------------------------ | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.givenname` | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | `user.userprincipalname` | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.surname` | Entra shortens the claim names in the summary card. A correct configuration looks like this:
Attributes and Claims card listing givenname, surname, emailaddress, name, and Unique User Identifier with their source attributes

Attributes & Claims: four additional claims plus the Unique User Identifier

### 4. Send Cogram your metadata Under **3. SAML Certificates**, download the **Federation Metadata XML** and send the file to . Cogram uses it to register your identity provider and link it to your email domain.
SAML Certificates card with the Federation Metadata XML download link highlighted

SAML Certificates → Federation Metadata XML → Download

### 5. Assign users Go to **Manage** → **Users and groups** and assign the people and groups who should have Cogram. Add yourself at minimum, so you can test the connection before rolling it out. ## Testing the connection Once Cogram confirms your identity provider is registered, go to [**Sign in**](https://app.cogram.com/auth/login) and click **SSO**.
Cogram sign-in page with the SSO button below the Google and Microsoft options highlighted

The SSO button on the Cogram sign-in page

Enter a work email address on your SSO domain and click **Sign in**. Cogram reads the domain, redirects you to Microsoft, and returns you to your Cogram dashboard after you authenticate. ## Troubleshooting **Sign-in fails with an assertion or audience error.** The Identifier in Entra ID does not match Cogram's Entity ID exactly. Copy it again from [Service provider details](#service-provider-details), including the trailing path. **Sign-in succeeds at Microsoft but Cogram shows an error.** An attribute claim is missing or empty. Check the four claims in step 3, and confirm the user account has a value in `user.mail`. **A user gets "you do not have access to this application".** They are not assigned to the enterprise application. Assign them under **Manage** → **Users and groups**. **Users still sign in with a password.** Cogram can enforce SSO for your organization so password sign-in is refused. Ask to turn this on once your rollout is complete. ## Next steps * [Organization roles](/organization-administration/organization-roles): what each role can do once users are signed in * [Groups](/organization-administration/groups): syncing group membership from Microsoft Entra ID # Subscription and billing ## Updating your subscription To add users, remove users, or cancel your subscription, email and we'll take care of it. Seats are counted per module. Members with no module licenses have the **View & Respond** access level, with read-only access. See [Licensing](/organization-administration/licensing) for how module entitlements, seats, and access levels work. ## Billing Cogram sends you automatic emails after processing payments. To view invoices and receipts, please locate this email by searching for "Your receipt from Cogram" in your inbox, or "@stripe.com" (the domain from which these emails are sent). Then click "Download invoice" or "Download receipt" in the email. For help, contact . # Organization notification settings Set default notification preferences for all organization members and lock settings to enforce them, including the new in-app and email channels. Organization admins and owners can control notification defaults for all members and optionally lock settings so members cannot change them. Go to [Organization Settings > Notifications](https://app.cogram.com/dashboard/settings/admin/notifications). ## How it works Each notification setting has two controls: | Control | What it does | | ----------------- | -------------------------------------------------------------------------------------------------------- | | **Active switch** | Sets the default on/off value for all members. | | **Lock button** | When locked, members cannot change the setting on their own. The lock icon shows "Locked" or "Unlocked". | When a setting is locked at the organization level, it is also locked for group admins; they cannot override or unlock it. ## Tasks & approvals These categories reach members in the [notification bell](/your-account/notifications) and by email. The **In-app** channel is always on; locking or disabling email never removes items from the bell. The **Email** column sets the org-wide default and can be locked: | Category | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Task assignments** | Email members when a task or action item is assigned to them. | | **Approvals & requests** | Email members when someone requests access to a project they can grant access to. Access-request notifications go to organization admins and owners. | ## Email-only notifications | Setting | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Post-meeting email** | Automatically send a summary email to the meeting host after a meeting ends. | | **Pre-meeting briefing emails** | Send a briefing email before recurring meetings. | | **Shared meeting minutes** | Email users a link to the draft meeting minutes when a colleague shares them. Only sent if the organization has enabled share-link emails to invitees under [Organization Settings > Meetings](https://app.cogram.com/dashboard/settings/admin/meetings). | | **Meeting failure notifications** | Email users when Cogram is unable to join or transcribe a meeting. | | **Added to project** | Email users when they are added to a project. | | **Workflow reports** | Email scheduled workflow reports to the recipients configured on each workflow. | ## Locking a setting Click the lock icon next to any setting to toggle between **Locked** and **Unlocked**. When locked: * Members see the toggle grayed out with a lock icon and the message explaining who locked it. * Group admins also cannot change or unlock the setting. > **Note:** Group admins can independently set defaults and locks at the group level for their group members, as long as the organization has not already locked them. Open your group from [Group Management](https://app.cogram.com/dashboard/settings/group/all) and go to its **Notifications** tab. # Navigation bar branding Customize the navigation bar with your organization's logo or name instead of the default Cogram mark. Organization admins and owners can replace the Cogram logo in the navigation bar with a custom logo or organization name. Go to [Organization Settings > General](https://app.cogram.com/dashboard/settings/admin/overview#branding) and find the **Branding** section. ## Branding options Choose one of three options: ### Cogram logo (default) The standard Cogram mark appears in the navigation bar. This is the default for all organizations. ### Organization name Your organization name is displayed as text in the navigation bar. 1. Select **Organization name**. 2. Enter the name to display (up to 60 characters). 3. Click **Save**. ### Custom logo Upload your own logo to replace the Cogram mark. 1. Select **Custom logo**. 2. Click **Upload logo** and choose a PNG or JPG file (max 2 MB). 3. Click **Save**. A live preview bar at the top of the page shows how your selection will appear to members before you save. ## Changing or removing a custom logo To replace an existing logo, click **Change logo** and upload a new file. To remove it entirely, click **Remove logo**. The navigation bar will revert to the Cogram mark until you choose another option. # Data exports Request a multi-part zip export of your organization's data (projects, meetings, emails, documents, drawings, reports, observations, and transmittals) for backup, audit, or migration. As an admin, you can export a snapshot of your organization's data (projects, meetings, emails, documents, drawings, reports, observations, and transmittals) as multi-part zip files. Exports run asynchronously in the background; once complete, every part is available to download from the same screen. Common reasons to run a Data Export: * Periodic offline backups outside Cogram. * Audit trails for a specific project or time window. * Bulk handover at the end of a project or engagement. Data Exports live in the **Data Exports** section of [Organization Settings → General](https://app.cogram.com/dashboard/settings/admin/overview#data-exports). Only **organization administrators and owners** can see the section and create exports. ## Choosing a meeting template before exporting Exports ship meeting minutes as `.docx` files. Cogram ships with a built-in template (**Cogram Default**), but you can upload your own organization-branded template and mark it as the **Organization Default**. Every meeting `.docx` in subsequent exports will then use your layout. Go to [Organization Settings → Templates](https://app.cogram.com/dashboard/settings/admin/templates), upload your `.docx`, open the row menu (`⋯`), and choose **Set as Organization Default**:

The row menu on the Templates page exposes a "Set as Organization Default" action.

Once applied, the row gets an **Organization Default** badge. The built-in template still shows its **Cogram Default** badge; it remains available as a fallback if your custom template is ever removed.

A custom template marked as Organization Default sits alongside the built-in Cogram Default.

> Set the Organization Default **before** kicking off an export: exports use the template that's marked default at the moment the worker renders each meeting's `.docx`. ## The Data Exports section This section lists every export your organization has created, with its status, scope, time window, who requested it, and when the download links expire.

The Data Exports section lists every past and active export.

Each row shows: * **Status**: `Pending`, `Running`, `Cancelling`, `Cancelled`, `Completed`, `Failed`, or `Expired`. * **Requested by**: the user who clicked **New Data Export**, or an `API Key` chip when the export was created via the [Cogram API](/integrations/cogram-api). * **Scope**: `Org-wide`, `Single Project`, or `N Projects`; hover for the project names, or open the row for the full list. Multi-project exports are created through the [Cogram API](/integrations/cogram-api); the dialog here covers org-wide and single-project. * **Time window**: the date range, or `All time` for project-scoped exports. * **Created**: when the export was requested. * **Expires**: when the download links will be removed (7 days after completion). ## Creating an export Click **+ New Data Export** in the top-right. The dialog asks for two things: a **scope** and a **time window**. ### Scope: org-wide or a single project The **Scope** selector lets you target either your entire organization or one project.

Choose between an org-wide export or a single project.

### Time window The available time-window options depend on the scope you picked. #### Org-wide → date range only (max 6 months) For org-wide exports, the time window is a **date range**, and capped at **6 months**. This keeps the package size predictable and the build time bounded.

Org-wide exports always require a date range.

The dialog reminds you about the cap inline:

The 6-month cap is enforced for org-wide exports. To cover a longer span, run several back-to-back exports.

#### Project-scoped → All time or a date range For project-scoped exports, the cap is lifted and an **All time** option is available alongside **Date range**, useful for handovers or full archives of a single project.

Project-scoped exports offer the "All time" option.

### Rendered documents Every export ships JSON metadata, `meeting.md`, `meeting.docx`, and the raw files. Select **Include rendered documents** to also get a `.docx` for each field report, and for every observation its report does not already show. Leave it off when you want the data, the original files, and the meeting minutes only. Rendering reports makes the build slower and the zip larger, and each field report needs the default template of its report type. A report with no template still gets its `.json`. Observations use Cogram's built-in observations template rather than one of yours, and an observation is skipped only when its field report's `.docx` already lays its observations out. Click **Create Data Export** to start the build. The dialog closes and the new export appears at the top of the list in `Pending` status. It will transition through `Running` and into `Completed` (or `Failed`) as the worker progresses. > Only **one** export can be active per organization at a time. If a `Pending`, `Running`, or `Cancelling` export already exists, the **+ New Data Export** button will be rejected until it finishes. This keeps the worker queue fair across orgs. ## Downloading a completed export Once an export reaches `Completed`, a **download icon** appears in its row's **Actions** column.

Click the download icon on any completed row to inspect and download the parts.

Clicking the icon (or the row itself) opens the **Data Export details** dialog with a per-part download list:

Each export is split into one or more zip parts. Click "Download" to grab a part.

The detail dialog shows: * The export's status, scope, time window, who requested it, when it was created, and when its links expire. * The list of **zip parts**, each with its size and a **Download** button. Large exports are split into multiple parts so each zip stays a manageable size. Download every part and unzip them into the same folder to reconstruct the full package. For what's inside (the folder structure, file types, and how to tell Cogram's example/demo data apart from your own), see [Data Export Package Layout](/organization-administration/data-export-package-layout#identifying-example--demo-data). > Each **Download** link is a short-lived signed URL valid for **one hour**. If a link expires before you click it, just reopen the detail dialog; fresh links are minted every time you load it. ## Lifecycle and retention * **Build time** scales with the volume of meetings, emails, and documents in scope. Most exports finish within minutes. * **Download links expire one hour after generation**: reopen the detail dialog to mint fresh links. * **Parts are retained for 7 days after completion**, then transition to `Expired`. The row stays in the list for audit purposes, but the zips are deleted from storage and the **Download** buttons disappear. * **Cancellation**: `Pending` exports cancel immediately; `Running` exports finish the part they're on and then stop, so cancellation can take a few seconds to settle. ## API access Everything on this page is also available via the [Cogram API](/integrations/cogram-api#data-exports). Use the API if you want to schedule recurring exports, drop the resulting zips into your own backup pipeline, or run an export from your own internal tools. # Data export package layout What's inside a Cogram Data Export zip: top-level folders, per-entity layout, file types, and naming conventions. A Cogram [Data Export](/organization-administration/data-exports) is delivered as one or more zip files. This page documents what's inside them, so you know exactly where to find every kind of data after unpacking. The layout is **stable and self-describing**: every entity has a predictable folder, every binary lives next to its metadata, and customer-uploaded filenames are preserved (sanitized for filesystem safety). If you script downstream processing of the package, you can rely on the paths below. ## Multi-part zips Large exports are split into multiple parts so each zip stays a manageable size. Each part is delivered with a filename like: ``` Cogram_data_export__part_NNN__.zip ``` * ``: when the export was requested (UTC). Different invocations of the same scope/window never overwrite each other on disk. * `NNN`: zero-padded part index (`000`, `001`, …) so parts sort in build order. * ``: `all_projects` for org-wide exports, your project's `customer_project_id` (falling back to the sanitized project name) for a single-project export, or `_projects` when the export covers several projects. * ``: `all_time` or `YYYY-MM-DD_to_YYYY-MM-DD`. To reconstruct the full package, **unzip every part into the same directory**. The folder structure below is shared across parts; extracting all of them merges into one coherent tree. No single entity is split across parts. ## Top-level structure After unzipping every part into the same folder, you get: ``` projects/ workflows/ ← only present if there are workflows in scope ``` * **`projects/`**: every entity lives under here, grouped by project. Every meeting belongs to a project; a meeting that isn't filed into a shared team project lives under its owner's personal **"My Workspace"** project folder (identifiable by `is_personal: true` in that project's `project.json`). * **`workflows/`**: workflows sit at the root, not under any single project, because a workflow can target multiple projects. Each `workflow.json` carries a `project_ids[]` field to cross-reference back. ## Per-project folder Each project gets its own folder under `projects/`, named: ``` projects/____/ ``` For example: ``` projects/prj_2abc123…__Skyrise-Tower-Phase-2__SRT-002/ ``` * The **leading KSUID** is the project's unique Cogram ID: your stable identifier for joining back to the API. * The **sanitized name** and **customer project ID** are included purely for human navigation. The `customer_project_id` is *not* unique inside an org (it's a label, not an identifier), so always disambiguate via the KSUID. * The `__` (double underscore) separator visually marks the boundary between the KSUID and the human-readable suffix. Inside each project folder, you'll find one subfolder per entity type that has any data in scope (subfolders are omitted when empty): ``` projects// ├── project.json ├── meetings/ ├── emails/ ├── documents/ ├── drawings/ ├── drawing_sets/ ├── reports/ ├── observations/ ├── transmittals/ ├── submittals/ └── rfis/ ``` `project.json` holds the project's metadata (name, address, members, custom fields, etc.). ## Report and observation renderings are optional Every export ships the JSON metadata, `meeting.md`, `meeting.docx`, and the raw binaries. When the export also asks for rendered documents (the **Include rendered documents** checkbox in the dialog, or `document_formats: ["docx"]` on the API request), the build writes a `.docx` next to the JSON for each field report, and for every observation its report does not already show. Rendering reports and observations makes the build slower and the zip larger, so it is opt-in. The `.json` files are written either way: an export that asks for no rendered documents is still a complete export. Every `.docx` is best-effort. When no template is configured, or one render fails, that single file is skipped and the build continues. ## Per-entity layout With one exception (emails), every entity gets its own folder, named: ``` __/ ``` Inside that folder are the entity's JSON metadata file and an optional `attachments/` subfolder for binaries: ``` projects///__/ ├── .json └── attachments/ └── …binaries… ``` `KSUID` stable IDs let you join entities back to the API or to each other (e.g. a meeting referenced from a transmittal). The trailing name suffix is truncated to \~20 characters and sanitized: slashes, NULs, and other unsafe characters are collapsed to dashes, so a customer-uploaded title can never escape its folder. ### Meetings ``` meetings/__/ ├── meeting.json ← metadata only (no transcript) ├── transcript.json ← only when transcripts are enabled AND present ├── meeting.md ← always written, human-readable rendering ├── meeting.docx ← always written, rendered from your org template └── attachments/ ├── attachment-001-<original-filename> ├── attachment-002-<original-filename> ├── photo-001.jpg └── photo-002.jpg ``` * **`meeting.docx`** is written for every export. It uses your organization's default `.docx` template (see [Setting a meeting template before exporting](/organization-administration/data-exports#choosing-a-meeting-template-before-exporting)), and it's best-effort: when no template is configured or a single render fails, the `.docx` is skipped and the build keeps going. The `.json` and `.md` siblings are always written. * **`transcript.json`** is a sibling of `meeting.json` rather than a section inside it, so a directory listing immediately answers "is there a transcript?" with no JSON parsing required. * **`attachments/`** holds uploaded meeting attachments and in-meeting photos only. Attachments and photos are indexed (`attachment-001-…`, `photo-001.jpg`) so two files with the same original name never collide. * **Audio recordings are not exported.** Meeting audio stays inside Cogram by policy; the exported transcript, `meeting.md`, and `meeting.docx` are the user-facing meeting payload. A meeting that isn't filed into a shared project lives under its owner's personal **"My Workspace"** project folder (`projects/<workspace-folder>/meetings/…`), the same internal layout as any other meeting. ### Emails: flat `.eml` files Emails are the **one exception** to the per-entity-folder rule. They ship as flat RFC-822 `.eml` files inside `emails/`, with **attachments embedded inline** in the message body: ``` emails/<YYYY-MM-DD>_<HHMMSS>_<safe-subject>_<email_KSUID>.eml ``` Each `.eml` opens in any standard mail client (Outlook, Apple Mail, Thunderbird) with all original headers, body, and attachments intact. The filename leads with the date+time so a directory listing sorts chronologically. There is **no JSON sidecar** for emails: the `.eml` is the complete record. (This mirrors how email is universally archived elsewhere.) ### Documents ``` documents/<doc_KSUID>__<title>/ ├── document.json └── attachments/ └── <original-filename> ← the document binary itself ``` The single binary under `attachments/` keeps its original filename (sanitized). ### Drawings ``` drawings/<drw_KSUID>__<title>/ ├── drawing.json └── attachments/ ├── revision-001.pdf ├── revision-002.pdf └── revision-003.pdf ``` One file per revision, numbered so revisions sort and are unambiguous. Cogram prefers the original PDF when available, falling back to a rendered image for legacy revisions. **Thumbnails are not exported**: they're a UI optimization, not customer data. A separate `drawing_sets/` folder lists Cogram's customer-defined drawing groupings: ``` drawing_sets/<set_KSUID>__<name>/ └── drawing_set.json ``` ### Reports ``` reports/<rpt_KSUID>__<title>/ ├── report.json └── report.docx ← only when rendered documents were requested ``` Reports have no binary attachments: the JSON is the whole record. Custom field values are inlined into `report.json` rather than living in a sibling folder. `report.docx` uses the default export template of the report's type. A report whose type has no template gets `report.json` only. ### Observations ``` observations/<obs_KSUID>__<title>/ ├── observation.json ├── observation.docx ← only when rendered documents were requested, │ and only when no report.docx already carries it └── attachments/ ├── photo-001.jpg ├── photo-002.jpg └── … ``` `observation.docx` is skipped only when the observation's field report got a `report.docx` that lays its observations out: that file already contains it. A standalone observation gets its own file, and so does one whose report shipped without a `.docx` (its type has no template) or whose report template does not show observations at all. Photos are exported at full resolution. Indexed filenames (`photo-001.jpg`, `photo-002.jpg`, …) avoid collisions with camera-default filenames. ### Transmittals ``` transmittals/<tmt_KSUID>__<subject>/ └── transmittal.json ``` Transmittals reference documents by their KSUID. The actual document binaries live under `projects/<prj-folder>/documents/`; no copies are made. ### Submittals and RFIs (Procore-synced) When your project is connected to Procore, submittals and RFIs are included with both Cogram's wrapper metadata (workflow status, AI checks, response state) and the verbatim Procore raw object: ``` submittals/<sub_KSUID>/ ├── submittal.json └── attachments/ ├── submittal-attachment-001-<filename> ├── approver-<approver_KSUID>-attachment-001-<filename> └── external-review-<inv_KSUID>-attachment-001-<filename> rfis/<rfi_KSUID>/ ├── rfi.json └── attachments/ ├── question-<q_KSUID>-attachment-001-<filename> ├── answer-<a_KSUID>-attachment-001-<filename> └── external-review-<inv_KSUID>-attachment-001-<filename> ``` The filename prefix (`submittal-`, `approver-`, `question-`, `answer-`, `external-review-`) tells you exactly which part of the submittal or RFI lifecycle each binary belongs to. The owning parent's KSUID is embedded in the filename for full traceability. Cogram only ships attachment binaries that it actually downloaded from Procore. If a Procore-only attachment was never mirrored locally, its metadata still appears in the parent JSON but no binary file is written. ### Workflows ``` workflows/<wf_KSUID>__<name>/ └── workflow.json ``` Workflows sit at the root because a workflow targets one or more projects via `project_ids[]`. Workflow runs are inlined into `workflow.json` rather than written as sibling files. ## Identifying example / demo data Every new Cogram organization is seeded with an **example project**, *"Example Project: Skyrise Tower"*, plus sample meetings, emails, drawings, reports, and observations, so you can explore the product before your real data lands. This example data **is included in exports**. To tell it apart from your real data (and filter it out), use the `is_dummy` flag: * **JSON entities** carry an **`is_dummy`** boolean: `true` means Cogram-generated example data, `false` means your own data. It's present in `project.json`, `meeting.json`, `drawing.json`, `report.json`, and `observation.json`. * **`project.json`** additionally carries **`is_personal`**: `true` for a personal workspace (e.g. your default *"My Workspace"*) as opposed to a shared team project. This is independent of `is_dummy`: a personal project can be real (`is_dummy: false`). * **Emails** have no JSON sidecar, so the same signal rides as an RFC-822 header: every `.eml` carries **`X-Cogram-Is-Dummy: true`** or **`false`** (alongside other `X-Cogram-*` metadata headers such as `X-Cogram-Email-Id`). To exclude all example data in one pass, drop any entity where `is_dummy` is `true` (or, for emails, where `X-Cogram-Is-Dummy` is `true`). Because example data is grouped under the example project's folder, you can also skip that project's folder wholesale, but the per-entity flag is the reliable signal. ## Filename and path safety Cogram aggressively sanitizes customer-uploaded names before they become parts of a path: * Anything outside `[A-Za-z0-9._-]` is collapsed to a single dash. * Leading and trailing dots/dashes are stripped (so `../foo` and `..` can never reach a parent directory). * The human-readable suffix on each entity folder is truncated to \~20 characters (30 for project names) so deeply nested paths stay under typical filesystem limits when extracted. The stable **KSUID** at the start of each entity folder is the part you should rely on programmatically; the sanitized name suffix is purely for human navigation. ## Putting it together A complete export of a single project named "Skyrise Tower" with one meeting and one drawing, requested **with** rendered documents, might look like: ``` Cogram_data_export_2026-05-20_14-32-15_part_000_SRT-002_2026-01-01_to_2026-05-20.zip └── projects/prj_2abc…__Skyrise-Tower__SRT-002/ ├── project.json ├── meetings/mtg_3def…__Weekly-OAC-2026-/ │ ├── meeting.json │ ├── transcript.json │ ├── meeting.md │ ├── meeting.docx │ └── attachments/ │ ├── attachment-001-agenda.pdf │ └── photo-001.jpg └── drawings/drw_4ghi…__A-101-Floor-Plan/ ├── drawing.json └── attachments/ ├── revision-001.pdf └── revision-002.pdf ``` Every path is deterministic from the entity's type and KSUID, so once you've unpacked a few exports the layout becomes second nature, and trivial to drive from a script. # Connecting Procore Connect Cogram to Procore to sync RFIs and Submittals between a Cogram project and a Procore project. Connect Procore to keep RFIs (Requests for Information) and Submittals in sync between your Cogram and Procore projects. Once connected, items created or updated in Procore are automatically available in your Cogram project. ## Prerequisites {% hint style="warning" %} Installing the Cogram app in Procore is a **company-level** action. It must be performed by a **Procore Company Admin** on the account that owns the project. Cogram is a Procore Custom App, not a Marketplace app. Do **not** search the Procore Marketplace for Cogram. {% endhint %} Before you begin, confirm the following: * You have a Cogram account and at least one Cogram project. * A **Procore Company Admin** on the relevant Procore account is available to install the Cogram app. This is required even if you are the one who will use the integration day-to-day. ### If you don't own the Procore company account If your firm is an external collaborator (for example, an architect or consultant invited into projects owned by a General Contractor), the GC's Procore Company Admin must install the Cogram app on their account. You can share the following with the GC's admin: > We use Cogram to manage meeting minutes, RFIs, and submittals. To enable the integration with your Procore project, we need the Cogram app installed on your Procore company account. This is a one-time setup that takes about five minutes. The steps are below. Once the GC's admin completes the installation and grants the app access to the relevant project, you can connect and use the integration from your Cogram account using the project-level permissions you already have. ## Step 1: Install the Cogram app in Procore These steps must be performed by a **Procore Company Admin**. 1. Sign in to Procore at [app.procore.com](https://app.procore.com/). 2. Open the **Company-level Admin** tool. 3. Under **Company Settings**, select **App Management**. 4. Click **Install App**. 5. Select **Install Custom App**. 6. Enter the following **App Version ID**: ``` 4b3e8d37-8ec4-4493-a845-0266c119f7dd ``` 7. Click **Install**, then confirm the installation. {% hint style="info" %} Do not select a project during this step. The project search does not work reliably at this point in Procore's install flow. You will configure project access in the next step. {% endhint %} ## Step 2: Configure project permissions Still in Procore as a Company Admin: 1. In the **Company-level Admin** tool, under **Company Settings**, select **App Management**. 2. Find the **Cogram** app in the list and click **View**. 3. Go to the **Permissions** tab. 4. Under **Permitted Projects**, select every project you want to sync with Cogram. 5. Save your changes. After installation, the Company Admin must grant the Cogram app permissions to the relevant projects. This grants the app access to RFI and Submittal data for those projects. ## Step 3: Connect the project in Cogram Once the Procore app is installed and the project is permitted: 1. Go to the [Projects page](https://app.cogram.com/dashboard/projects) and open the project you want to connect. 2. Open the project's **Settings**. 3. Select the **Procore** tab. 4. Follow the prompts to authenticate and link the Procore project. {% hint style="success" %} When the connection is complete, the **Connection Details** section will show that both **RFI** and **Submittal** permissions are active. {% endhint %} ## Troubleshooting | Problem | Cause | Solution | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Install App** or **Install Custom App** is not available | You are not a Procore Company Admin, or you are an external collaborator on the project. | Ask the Procore Company Admin on the account that owns the project to install the Cogram Custom App through **Company-level Admin** → **Company Settings** → **App Management**. Do not search the Procore Marketplace. | | Project not appearing in Permitted Projects | The app was just installed and the project list hasn't refreshed. | Refresh the page. If the project still doesn't appear, confirm the project is active in Procore. | | Connection Details not showing permissions | The Procore admin hasn't granted the Cogram app access to the project. | Ask the admin to add your project under Permitted Projects in App Management. | ## FAQ **Can I install the Cogram app if I only have project-level access in Procore?** No. Procore restricts app installation to Company Admins. If you are an architect, consultant, or subcontractor invited into a GC's Procore project, the GC's Company Admin must install the app. Once installed, you can use the integration with your existing project-level permissions. **Does the GC's admin need to do anything after the initial install?** Only if you need to connect additional projects. The admin must add each new project to the Cogram app's Permitted Projects list. The initial install and first project setup is a one-time process. **Is my data shared between the GC and my firm?** The Procore integration syncs RFI and Submittal data that is already visible to both parties in Procore. Cogram does not expose any data beyond what you can already see in your Procore project. For support, contact <support@cogram.com>. # Connecting AI apps Connect ChatGPT, Claude, or another AI app to Cogram and ask about your projects — meeting minutes, emails, RFIs, submittals, drawings, and field reports. Connect your AI app to Cogram once, and from then on you can ask it about your projects directly — "what did we decide about the curtain wall in last week's OAC meeting?", "list open RFIs on the Riverside project", "summarize this month's field reports". The connection is safe by design: * **It is read-only.** The AI can search, read, and summarize. It cannot create, change, or delete anything in Cogram. * **It acts as you.** The AI sees exactly what you can see in Cogram, and nothing more. This page covers ChatGPT and Claude step by step, but any AI app that supports MCP connectors works the same way — see [Other AI apps](#other-ai-apps). ## Before you start You need your own Cogram account, in an organization where an administrator has turned on MCP access. If the connection is refused, ask your administrator — the setup is described in [MCP Server](/integrations/mcp-server). ## Connect ChatGPT In a ChatGPT workspace, Cogram is installed as a plugin. A workspace admin must publish the **Cogram MCP** plugin to the workspace first — send them to [MCP Server](/integrations/mcp-server). Then each user installs it once: 1. In the ChatGPT sidebar, select **Plugins**. 2. Select your workspace's tab, next to **Public** — it carries your company's name. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-524391632fae5b811cf209615de5c991470717fe%2Fchatgpt-plugins-cogram.png?alt=media" alt="ChatGPT Plugins page with the workspace tab selected, showing the Cogram MCP plugin" width="700"><figcaption><p>Plugins → your workspace's tab. Cogram MCP is listed there once your admin has published it</p></figcaption></figure> 3. Select **Cogram MCP**, then select **Install plugin**. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-f4a734ad52f09d6d9a05e0372e5d7fd966bc3cdb%2Fchatgpt-cogram-mcp-install.png?alt=media" alt="Cogram MCP plugin page in ChatGPT with an Install plugin button" width="700"><figcaption><p>Select <strong>Install plugin</strong></p></figcaption></figure> 4. In the **Connect Cogram MCP** dialog, select **Continue to Cogram MCP**. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-4201d421041392197099e27b7eb8229e47d0f50e%2Fchatgpt-connect-dialog.png?alt=media" alt="ChatGPT Connect Cogram MCP dialog with a Continue to Cogram MCP button" width="700"><figcaption><p>Select <strong>Continue to Cogram MCP</strong></p></figcaption></figure> 5. A Cogram tab opens. Sign in as you normally do, including through your identity provider if your organization uses SSO, and on the approval screen — **Allow ChatGPT to access Cogram?** — select **Allow**. If you have signed in and approved before, this step completes on its own. **Expected result:** ChatGPT shows **Cogram MCP is installed**, and the plugin page now offers **Try in chat**. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-466bb7e7f0b2ed41eda431a3460d4bdc4e36eef9%2Fchatgpt-cogram-installed.png?alt=media" alt="Cogram MCP plugin page in ChatGPT after installation, with a Try in chat button" width="700"><figcaption><p>Installed: the plugin page now offers <strong>Try in chat</strong></p></figcaption></figure> To use it, select **Try in chat**, or in any chat select **Plugins** under the message box and pick **Cogram MCP**. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-d852e8d7a9b5ceaac59e9d589c65bae5315ba543%2Fchatgpt-plugins-picker.png?alt=media" alt="ChatGPT chat composer with the Plugins picker open, listing Cogram MCP" width="700"><figcaption><p>In a chat: <strong>Plugins</strong> under the message box → <strong>Cogram MCP</strong></p></figcaption></figure> ## Connect Claude (claude.ai) In a Claude workspace, Cogram is a custom connector. An owner must publish the **Cogram MCP** connector to the organization first — send them to [MCP Server](/integrations/mcp-server). Then each user connects it once: 1. In the claude.ai sidebar, select **Customize**, then **Connectors**. 2. Find **Cogram MCP** in the list and select **Connect**. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-17cd13c4054e923c78e7f051de955c0e23dfd324%2Fclaude-connectors-list.png?alt=media" alt="Claude Customize → Connectors list showing the Cogram MCP connector with a Connect button" width="700"><figcaption><p>Customize → Connectors: select <strong>Connect</strong> on Cogram MCP</p></figcaption></figure> 3. A Cogram tab opens. Sign in as you normally do, including through your identity provider if your organization uses SSO, and on the approval screen — **Allow Claude to access Cogram?** — select **Allow**. **Expected result:** you land back on the connector in claude.ai, which now shows Cogram's tools and a **Disconnect** button. On this page you can also set per-tool permissions — by default Claude asks for your approval before each tool call. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-f9b542e6457c7697d51bdcf8c4677b939b20650b%2Fclaude-connected.png?alt=media" alt="Cogram MCP connector page in claude.ai after connecting, showing tool permissions and a Disconnect button" width="700"><figcaption><p>Connected: the connector page lists Cogram's tools</p></figcaption></figure> To use it in a conversation, open the plus menu in the chat box, select **Connectors**, and check that **Cogram MCP** is turned on — it is on by default after connecting. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-cc9c73394e2fd808f176d6fb57cfd3d003864892%2Fclaude-chat-connectors.png?alt=media" alt="Claude chat composer plus menu with the Connectors submenu open, showing the Cogram MCP toggle turned on" width="700"><figcaption><p>In a chat: plus menu → <strong>Connectors</strong> → <strong>Cogram MCP</strong></p></figcaption></figure> **If you use a personal Claude account** (Free, Pro, or Max), add Cogram yourself: 1. Go to **Customize → Connectors** and select **Add custom connector**. 2. Name it **Cogram** and enter the server URL `https://mcp.cogram.com/mcp`. Leave the advanced OAuth fields empty. 3. Select **Add**, then **Connect**, and complete the same sign-in and approval as above. Claude caveats: custom connectors work on the web, in the desktop app, and in Cowork. The Free plan allows one custom connector. ## Other AI apps Cogram's MCP server is a standard MCP server, so any AI app that can add a custom MCP connector can connect — for example Grok, Microsoft Copilot Studio, or an agent your own team builds. The menu names differ per app, but the shape is always the same: 1. In the app, add a custom connector (sometimes called an MCP server, app, or tool) with the server URL `https://mcp.cogram.com/mcp`. 2. Sign in to Cogram in the browser window that opens, and select **Allow**. For agents your team builds itself, see [MCP Server](/integrations/mcp-server). ## Check that it works Ask the AI application: "list my active Cogram projects". It should call Cogram tools such as `search_projects` and answer with your projects. ## What the AI can see The AI reads Cogram through a fixed set of read-only tools: projects, meetings, emails, documents, RFIs, submittals, drawings, field reports, observations, transmittals, boards, workflows, and the directory. Which tools are offered depends on your organization's [licensing](/organization-administration/licensing); what each tool returns is limited by your own project membership and [asset visibility](/projects/asset-visibility). The full tool list is in [MCP Server](/integrations/mcp-server#what-data-an-agent-can-reach). Anything the AI writes from Cogram data is an AI draft. Check names, dates, decisions, action items, technical values, and any contractual wording before you rely on it. ## Troubleshooting **Symptom**: The AI reports "MCP access is not enabled for your organization", or the approval screen offers no **Allow** button. **Likely cause**: MCP access is off for your organization. **Fix**: Ask an administrator to turn it on — see [MCP Server](/integrations/mcp-server). **Symptom**: **Cogram MCP** does not appear under **Plugins** on your workspace's tab in ChatGPT. **Likely cause**: A workspace admin has not published the Cogram MCP plugin to your workspace yet — users cannot add it themselves. **Fix**: Ask a workspace admin to publish it — see [MCP Server](/integrations/mcp-server). **Symptom**: The AI sees fewer projects or meetings than you expect. **Likely cause**: The AI has exactly your own access. You are not on those projects, or asset visibility hides those records from you. **Fix**: Ask to be added to the projects. Nothing about the connection itself can widen what the AI sees. **Symptom**: A working connection suddenly asks you to sign in again. **Likely cause**: The stored sign-in expired or was revoked. **Fix**: Run the connection again — sign in and approve. **Symptom**: You want to disconnect the AI from Cogram. **Fix**: Remove the Cogram connector or app in the AI application. That ends its access immediately. ## Next steps * [Agent](/agent/agent) — Cogram's own built-in agent, which needs no setup. * [MCP Server](/integrations/mcp-server) — administrator setup, the full tool list, and rate limits. Questions? Email <support@cogram.com> or use the in-app Help menu. # Connecting Autodesk Construction Cloud Why connecting Autodesk Construction Cloud is useful (ask Cogram about your ACC projects, files, issues, RFIs, submittals, and more in plain language) and how an admin sets it up. Connect Autodesk Construction Cloud (ACC) so you can ask Cogram about your ACC projects, files, issues, RFIs, submittals, and more in plain language: read-only, and always within your own Autodesk permissions. ## Why connect Autodesk Construction Cloud Cogram is an AI platform for the architecture, engineering, and construction (AEC) industry. Connecting ACC lets you ask the Cogram [Agent](https://app.cogram.com/dashboard/agent) about your Autodesk project data in plain language, alongside your meetings, emails, and reports in Cogram, without switching to Autodesk or digging through folders. Cogram reads live from Autodesk when you ask. Nothing is synced or stored, and every read happens as the signed-in user, so you only ever see what your own Autodesk account is already permitted to see. That keeps the integration safe to roll out across a whole organization: no shared credentials, no copied data, no new permissions to manage. > Cogram's access is **read-only**. It reads the projects, folders, files, and metadata your Autodesk account can see. It cannot create, edit, move, or delete anything in Autodesk. ### What you can ask about * **Projects**: the ACC projects and accounts (hubs) you can access. * **Files and folders**: the document tree in a project, and previous versions of a file. * **File details**: metadata and model properties for a document. * **Document contents**: Cogram can read a PDF, Office, or text document from ACC (up to 25 MB) and answer questions about it. Model files (RVT, DWG, NWD) can be listed and downloaded, but not read. * **Issues**: issues logged on a project. * **RFIs**: RFIs on a project, with their status and details. * **Submittals**: submittal items and their review status. * **Forms**: filled project forms, such as daily reports and checklists. * **Photos**: photos captured on a project. * **Sheets**: published sheets in a project. * **Assets**: assets and their status. * **Locations**: a project's location breakdown (buildings, levels, areas). * **Cost**: cost data on a project. * **Downloads**: a link to open or download a specific file. {% hint style="info" %} **Revit and other model files.** For a model file such as an `.rvt`, you can find it in the project folders, list its version history (who published each version, when, and the file size), ask for its model properties (the element data ACC extracts for its viewer), and get a download link. The model file itself can't be read as a document; ask for its properties or download it instead. {% endhint %} ### Example prompts * "List the projects in our Autodesk Construction Cloud account." * "What's in the Drawings folder of the \[project name] project?" * "Find the latest version of the curtain wall shop drawings in \[project name]." * "Summarize the open issues on \[project name]." * "What's the status of the open RFIs on \[project name]?" * "Show me the submittals under review on \[project name]." * "Get me a download link for the door hardware submittal." * "What are the model properties of \[drawing or model file]?" * "Who published the latest version of the \[model file] model, and when?" Naming the project (and the folder or file, if you know it) gets you a faster, more precise answer. If Agent can't find something, it's usually a permissions or naming difference in Autodesk: confirm your Autodesk account can see it. ## Setting up the Autodesk connection Two one-time steps make ACC data available: a Cogram user connects their own Autodesk account, and an Autodesk admin approves Cogram once for the whole account. > The **Connect** and **Approve** steps live on [Organization Settings → Connectors](https://app.cogram.com/dashboard/settings/admin/connectors), which is available to **Cogram organization admins**. Other users don't open this page; when they first ask Agent for ACC data, it prompts them to connect their own Autodesk account (the same sign-in as Step 1). ### Prerequisites * An Autodesk Construction Cloud account on a **full ACC subscription** (Custom Integrations is not available on Trial / Essentials tiers). * For the one-time approval: an **Autodesk admin** (Hub Admin) for your account. * In Cogram, an organization admin opens [Organization Settings → Connectors](https://app.cogram.com/dashboard/settings/admin/connectors) and selects the **Autodesk Construction Cloud** connector. ### 1. Connect your Autodesk account > **Who:** each Cogram user, for their own account. On the Connectors page an org admin connects their own account; everyone else connects from Agent. 1. Open [Organization Settings → Connectors](https://app.cogram.com/dashboard/settings/admin/connectors) and select the **Autodesk Construction Cloud** connector. 2. Under **Step 1 · Connect your Autodesk account**, select **Connect**. 3. Sign in to Autodesk and approve the access request. <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-db34bc6b1f664aee22e31b2aa9f00772162ceb7a%2Fautodesk-step1-connect.png?alt=media" alt="Cogram Organization Settings → Connectors, Autodesk Construction Cloud connector, showing the Step 1 Connect your Autodesk account card with a Connect button" width="700"><figcaption><p>Step 1: select <strong>Connect</strong></p></figcaption></figure> <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-5c60401e9b03e0ef94bde98a4d7590d7e786c312%2Fautodesk-authorize.png?alt=media" alt="Autodesk Authorize application screen listing the permissions Cogram requests, with an Allow button" width="420"><figcaption><p>Sign in to Autodesk, then select <strong>Allow</strong></p></figcaption></figure> When the window closes, Step 1 shows **Connected as `<your Autodesk email>`**. {% hint style="info" %} You can connect before your Autodesk admin has finished Step 2. Until the approval is in place, the connection succeeds but returns no project data. Complete Step 2, then verify. {% endhint %} <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-14834a9d83ef5b4587d853e65ede55be6e921b9c%2Fautodesk-connected-step2.png?alt=media" alt="Cogram showing Step 1 connected with a green Connected badge, and the Step 2 Approve Cogram card with Client ID, App name, and Description fields" width="700"><figcaption><p>Once connected, Step 2 shows the values to approve in Autodesk</p></figcaption></figure> ### 2. Approve Cogram in your Autodesk account > **Who:** an **Autodesk admin** (Hub Admin), once per Autodesk account. This authorizes Cogram's application to read data the connected users can access. The **Step 2** card appears once you have completed Step 1; once approval is confirmed it collapses to a short confirmation. > If your company has more than one Autodesk account (hub), approval is per account. An admin repeats these steps in each account you want Cogram to read. Cogram then reads across every approved account at once — you do not select one, and you do not need to switch accounts in Autodesk. 1. In the **Step 2** card, copy the three values Cogram shows: **Client ID**, **App name**, and **Description** (each has a copy button). 2. Select **Open Autodesk** to open Autodesk Construction Cloud in a new tab. This lands you on your ACC home; from there, open **Hub Admin**. 3. In Autodesk, go to **Hub Admin → Custom Integrations** and select **+ Add custom integration**. 4. In the dialog, paste your copied values into the matching fields (the field names differ slightly from Cogram's): * **Autodesk Platform Services Client ID** ← Cogram's **Client ID** * **Custom integration name** ← Cogram's **App name** * **Description** ← Cogram's **Description** (optional free-text; safe to skip) 5. Save the integration and make sure it is **Active**. 6. Back in Cogram, select **Verify connection**. Once approval is confirmed, the **Not approved yet** status clears and Step 2 collapses to **Cogram is approved — you can access your ACC data**. ### Expected result * Step 1 shows **Connected as `<your Autodesk email>`**. * Step 2 reads **Cogram is approved — you can access your ACC data** (it collapses to this one-line confirmation; the button there becomes **Re-verify**). * Cogram can now read your ACC projects, files, and metadata on demand: ask the [Agent](https://app.cogram.com/dashboard/agent) using the [example prompts](#example-prompts) above. ## Troubleshooting **Symptom**: **Verify connection** stays on **Not approved yet** even though you just approved the integration in Autodesk. **Likely cause**: Verify checks ACC using your connection, so it needs Step 1 completed first; or the Custom Integration was added but not set to **Active**, or the values were mistyped. **Fix**: Confirm Step 1 shows **Connected as …**, then in Autodesk confirm the Custom Integration uses the exact **Client ID** Cogram shows and is **Active**. Re-paste from the copy buttons and select **Verify connection** again. **Symptom**: "Not approved yet" and you are on an Autodesk Trial or Essentials plan. **Likely cause**: Custom Integrations requires a full ACC subscription; the setting is unavailable on Trial / Essentials tiers. **Fix**: Upgrade to a full ACC subscription, then complete Step 2. **Symptom**: Agent returns projects from only some of your Autodesk accounts (hubs). **Likely cause**: Cogram is approved in those accounts but not the others. Approval is granted per Autodesk account. **Fix**: In each missing account, complete Step 2 as an Autodesk admin for that account. Your Cogram connection covers them all — you do not reconnect in Step 1. **Symptom**: Cogram says your Autodesk connection has expired. **Likely cause**: The stored authorization lapsed (for example, after a long period of no use). **Fix**: In **Step 1**, select **Connect** again to re-authorize. ## Disconnecting To remove the connection, in **Step 1** select **Disconnect**. Cogram immediately loses the ability to read your ACC data until you reconnect. Disconnecting does not change anything in Autodesk. ## Next steps * [Agent](/agent/agent): how to work with the Cogram Agent across all your project data, including your connected ACC data. For support, contact <mark style="color:blue;"><support@cogram.com></mark>. # Connecting Deltek VantagePoint Sync projects and team members from Deltek VantagePoint into Cogram, invite your organization's users in bulk, and ask Agent about your VantagePoint data. Cogram imports projects and team members from Deltek VantagePoint and keeps them in sync. Sync is one-way: Cogram reads from VantagePoint and never writes back. > **End user?** Your synced projects are already in Cogram. Skip to [Using synced projects](#using-vantagepoint-synced-projects-end-users). ## Before you begin Setup is two parts: 1. **In VantagePoint**: create a role, user, and API authorization (produces six credentials). 2. **In Cogram**: paste the credentials into Integrations and start syncing. If your VantagePoint admin (or Deltek support) will hand you the six credentials, skip to [Part 2](#part-2-set-up-in-cogram). **You need:** * Owner or Admin role in Cogram * Admin access to VantagePoint, or credentials from someone who has it * A password manager: you'll generate a password and a Client Secret that both need saving * A dedicated VantagePoint user for the integration (created in Part 1). Don't use a personal account, so the integration keeps working if that person leaves the firm <details> <summary>How the integration works</summary> ```mermaid flowchart LR VP["Deltek VantagePoint<br/>(project registry)"] VP -->|"Daily sync + on-demand"| CG["Cogram<br/>(collaboration workspace)"] CG --> PR["Projects<br/>name · client · address"] CG --> TM["Team members<br/>per project"] CG --> EF["Email filing<br/>auto-enabled on import"] ``` Cogram imports one Cogram project per top-level VantagePoint project, assigns the Project Manager (or a fallback you configure) as owner, syncs team members, and optionally enables email filing on each synced project. You can invite internal users to Cogram from the integration page: no CSV export. Only projects the configured VantagePoint user can access are imported. </details> ## Part 1: Set up in VantagePoint ```mermaid flowchart LR R["1. Role<br/>cogram_api"] --> U["2. User<br/>cogram_api"] U --> A["3. API Authorization"] A --> C["Six credentials"] C --> CG["Cogram form"] ``` > A **hub** is a top-level data module in VantagePoint (Projects, Employees, Contacts, etc.). ### Step 1: Create the `cogram_api` role In **Settings > Security > Roles**, create a new role named `cogram_api`. See Deltek's [Role Security docs](https://learning.deltek.com/bundle/Vantagepoint/page/cfsec_general_tab_of_role_security.html) for details. #### Hub read access | Hub | Why | | ----------------------------- | ------------------------------------------ | | **Projects** | Name, code, client, address, status, dates | | **Employees** or **Contacts** | Team member contact info | > **Planning to use Agent?** Sync needs only the hubs above, but [Agent questions](#asking-agent-about-vantagepoint-data) about firms and CRM activities need the **Firms** and **Activities** hubs too. You can add them later. #### Which projects get synced Under the role's **Record Access** tab, grant access to the projects you want synced. Scope to active projects only for a focused Cogram project list. > Read-only is sufficient. Don't grant Security access. > **API access.** Most VantagePoint versions grant this automatically with hub access, so you can skip it for now. If Cogram's Part 2 sync later fails with an auth error, return and look for **API Access**, **Web Services**, or **REST API** on the role's **General** or **Access Rights** tab. ### Step 2: Create the integration user In **Settings > Security > Users**, create a new user dedicated to the integration with these values: | Field | Value | | ------------ | ------------------------------------------------------ | | **Username** | `cogram_api` | | **Password** | Strong password: **save to your password manager now** | | **Role** | `cogram_api` | | **Status** | Active | You don't need to link an Employee record unless your tenancy requires it. See Deltek's [Create a User docs](https://help.deltek.com/Product/Vantagepoint/7.1/cfsec_create_new_user.html) for details. > **Verify login.** Sign in to VantagePoint as the new user once. If you get a "change password on first login" prompt, complete it now; Cogram's sync will fail otherwise. ### Step 3: Create the API authorization 1. In **Utilities > Integrations > API Authorization**, click **+ New API Authorization**. 2. Fill in: | Field | Value | | ---------------------- | ------------------------------------- | | **Authorization Name** | `Cogram Integration` | | **Database Name** | Your VantagePoint database identifier | The **Database Name** is usually visible on VantagePoint's login-screen database selector or in the URL. Ask your VP admin if unsure. 3. Check **Allow Password Grant Type** and **Scopes**. 4. Click **Save**. The generated **Consumer Key** is your **Client ID**. 5. From the row's **Actions** menu, pick **Generate Secret**. **Copy immediately to your password manager**: this is your **Client Secret**. It's shown once. > Client ID ≠ Client Secret. Cogram rejects the form if they match. See Deltek's [API Authorization docs](https://learning.deltek.com/bundle/Vantagepoint/page/st_util_int_and_imp_api_tab.1.html) and the [Authentication guide](https://learning.deltek.com/bundle/VantagepointAPIOverview/page/VPAPIOverviewAuthentication.html) for the token flow. ### Step 4: Note your Base URL Format: `https://<your-vp-domain>/<your-company-path>/Api` (e.g. `https://acme.vantagepointfirst.com/Acme/Api`). No trailing slash. Ask your VP admin if unsure. See Deltek's [REST API Overview](https://learning.deltek.com/bundle/VantagepointAPIOverview/page/VPAPIOverviewRESTfulAPIOverview.html). ### Checklist Before moving on, confirm you've saved: * [ ] Base URL * [ ] Username * [ ] Password * [ ] Database (the Database Name) * [ ] Client ID (the Consumer Key) * [ ] Client Secret Continue to [Part 2 →](#part-2-set-up-in-cogram) ## Part 2: Set up in Cogram ### Step 1: Open the integration Go to [**Organization Settings > Integrations**](https://app.cogram.com/dashboard/settings/admin/integrations) and click **Deltek VantagePoint**. ### Step 2: Enter your credentials | Cogram field | From Part 1 | | ----------------- | ------------------------------------------------------------------------------------------------- | | **Base URL** | [Part 1 · Step 4](#step-4-note-your-base-url), e.g. `https://acme.vantagepointfirst.com/Acme/Api` | | **Username** | [Part 1 · Step 2](#step-2-create-the-integration-user), e.g. `cogram_api` | | **Password** | [Part 1 · Step 2](#step-2-create-the-integration-user) | | **Database** | [Part 1 · Step 3](#step-3-create-the-api-authorization) Database Name | | **Client ID** | [Part 1 · Step 3](#step-3-create-the-api-authorization) Consumer Key | | **Client Secret** | [Part 1 · Step 3](#step-3-create-the-api-authorization) | <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-7a04902b25437e077a7df222f2e88e156573f68c%2Fvantagepoint-credentials-form.png?alt=media" alt="Deltek Vantagepoint Integration form" width="900"><figcaption><p>Organization Settings > Integrations > Deltek Vantagepoint</p></figcaption></figure> ### Step 3: Configure sync options #### Fallback project owner Select the Cogram user who'll own any imported project where no match is found. Cogram assigns project owners in this order: ```mermaid flowchart TD A["VantagePoint project synced"] --> B{"PM email matches<br/>a Cogram user?"} B -->|Yes| C["PM is owner"] B -->|No| D{"Supervisor email matches<br/>a Cogram user?"} D -->|Yes| E["Supervisor is owner"] D -->|No| F["Fallback owner"] ``` #### Enable email filing for new projects On by default. Turn off to configure per project. #### Sync project statuses Choose which VantagePoint project statuses are imported into Cogram: * **Active** (`A`): projects currently open and in progress * **Inactive** (`I`): projects that have been closed or completed * **Dormant** (`D`): projects temporarily suspended or on hold At least one status must be selected. **Active** is selected by default. Most organizations only need **Active**. Select additional statuses if your team needs to view historical or paused projects in Cogram. ### Step 4: Save and start syncing Click **Start syncing**. Initial sync takes 5–30 minutes for up to a few hundred projects; longer for larger accounts. On success, the page shows a green **Vantagepoint Integration Active** banner, the last-sync timestamp, and counts of projects and users imported. Sync runs automatically once per day. Click **Sync now** to pull changes immediately. Next: [invite users →](#after-setup-managing-synced-users) ## After setup: managing synced users The **VantagePoint Users** section on the integration page lists every employee pulled from your VantagePoint projects. * **Internal**: email domain matches your organization * **External**: consultant, client, or subcontractor * **Status:** **Has Account**, **Invited**, or **Not Invited** To invite an internal user: find them (use Search or the **Internal Only** / **Not Invited** filters) and click **Invite**. Status becomes **Invited**. Click **Resend Invite** to send again. External users can't be invited here; they appear only for visibility. ## Managing the integration ### Updating credentials Go to [**Integrations > Deltek VantagePoint**](https://app.cogram.com/dashboard/settings/admin/integrations/vantagepoint), update the changed fields, and click **Start syncing** if sync was stopped. Leave password or Client Secret blank to keep existing values. ### Stopping the sync Click **Stop syncing**. Existing Cogram projects and data are preserved; the daily sync pauses until you re-enable. ## Troubleshooting ### During setup (in VantagePoint) #### Can't find API Authorization under Utilities > Integrations Your account lacks Utilities access, or your VP edition doesn't include the REST API module. Ask your VP admin to do Part 1 for you, or contact Deltek support. #### Role doesn't have a Projects or Employees option The hubs available depend on your VP modules. Confirm with your VP admin that those hubs are licensed and visible to your account. #### Don't know what to put in "Database Name" Check VP's login-screen database selector, your VP URL, or ask your VP admin / Deltek support. ### After saving in Cogram #### Amber banner: "Check your credentials" VantagePoint rejected the login. Confirm the API user is active and unlocked, the password hasn't expired, the API Authorization still exists, **Allow Password Grant Type** is enabled, and the Client Secret hasn't been regenerated. Update and click **Start syncing**. #### "Client Secret must be different from Client ID" Copy-paste error. In VP's **Utilities > Integrations > API Authorization**: Consumer Key = Client ID; generated Secret = Client Secret. #### Projects not appearing Cogram imports only top-level projects (WBS level 1, Phase and Task blank). Confirm the expected projects are top-level in VP and the configured user has access via the role's **Record Access** tab. #### Project owner is the fallback, not the PM The Project Manager email in VP doesn't match a Cogram user. Invite the PM to Cogram; the next sync assigns them. #### "Invite" button missing for a user The user is External, or has no email in VP. If the classification looks wrong, contact <support@cogram.com> about your organization's registered domains. #### VantagePoint Users table is empty Sync hasn't succeeded yet, or your VP projects have no team members. Click **Sync now** and confirm team assignments in VP. *** ## Using VantagePoint-synced projects (end users) > **No action required.** Your VantagePoint projects are already in your [project list](https://app.cogram.com/dashboard/projects). * Projects appear with the VP code prepended, e.g. `00005167.00 - Skyrise Office Complex`, and a **VantagePoint** source label. * Core fields (name, client, address) are read-only: edit them in VP; they update in Cogram on the next sync. * Meeting notes, emails, field reports, and drawings work normally. * Emails on synced projects are filed automatically if your admin enabled email filing. * Renames, new members, and archives in VP propagate on the next daily sync. * In your project list, filter by source and select **VantagePoint projects** to narrow the view. * If your organization has it enabled, you can [ask Agent about your VantagePoint data](#asking-agent-about-vantagepoint-data). ## Asking Agent about VantagePoint data Customers with an enabled VantagePoint integration can ask the [Cogram Agent](https://app.cogram.com/dashboard/agent) questions about their ERP data in plain English. **Example prompts** * "Who is on the team for project X?" * "What stages do we have for project Y?" * "Which consultants are on my active projects, and who is the contact at each firm?" * "What is the contract fee on 1234.06.27?" **What Agent can read** Everything related to projects: team, contacts, contracts and fees, milestones, proposals, awards, descriptions, and project codes, plus firms, contacts, and CRM activities. **What Agent cannot read** Invoices, AP/AR, the general ledger, timesheets, payroll, employee records, and vendor banking. Access is read-only. Cogram never writes to VantagePoint. Answers are scoped to the projects you are a member of in Cogram; a VantagePoint project that was never synced is not readable. Answers are AI-generated. Verify fees, dates, and contract terms against VantagePoint before quoting them to a client or using them in a submission. ### Turning it on This is off by default and separate from the sync. To enable it for your organization, contact <support@cogram.com>. You need a connected integration ([Part 2](#part-2-set-up-in-cogram)) and at least one completed sync; after that the capability appears in Agent automatically, with nothing to configure per user. If Agent says a project isn't synced, it is outside your [sync statuses](#sync-project-statuses) or the `cogram_api` role's **Record Access**. If it says you aren't a member, ask a project admin to add you in Cogram. If it says it isn't permitted to read something, the role is missing that hub: VantagePoint grants API rights per endpoint, so other questions keep working meanwhile. ## Next steps **For admins:** [SSO](/organization-administration/single-sign-on-sso), [Outlook add-in: email filing](/email/outlook-add-in-email-filing) **For everyone:** [Projects](/projects/projects), [Emails](/email/emails) # Connecting Unanet ERP A/E Sync your firm's Unanet ERP A/E projects into Cogram, automatically and instantly. Cogram syncs your firm's **Unanet ERP A/E** (formerly Clearview InFocus) **projects and opportunities** into Cogram and keeps them up to date automatically. An admin sets it up once with a firm API key. Sync is **one-way**: Cogram reads from Unanet and never writes back. <details> <summary>How the sync works</summary> ```mermaid flowchart LR U["Unanet ERP A/E<br/>(project registry)"] U -->|"Firm API key<br/>~6h sync + instant webhook"| CG["Cogram"] CG --> P["Projects"] CG --> O["Opportunities"] CG --> R["Project roles<br/>owner + team members"] ``` Cogram uses one **firm API key** (org-level) to import projects and opportunities, assign project roles (owner plus team members, matched to existing Cogram users by email), and refresh them on a schedule and on live events. Imported projects are stored in Cogram. Cogram never writes back to Unanet. </details> ## Part 1: Set up the organization project sync (admin) > **You need:** Owner or Admin role in Cogram, your Unanet tenant's Base API URL, and a Unanet **API key** for your firm. ### Step 1: Get your Unanet API key In Unanet, go to **Administration → API Management → Manage Keys** and copy an API key for your firm. This key lets Cogram read your projects and opportunities. > Treat the API key like a password. Use a key dedicated to the integration if your Unanet setup allows it, so it keeps working if staff change. ### Step 2: Open the integration in Cogram Go to [**Organization Settings → Integrations**](https://app.cogram.com/dashboard/settings/admin/integrations) and click **Unanet ERP A/E**. ### Step 3: Enter the connection details | Field | Value | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Base API URL** | Your tenant address, usually `https://<your-firm>.infocusapp.com/platform`. Note the `/platform` suffix. Cogram warns you if it's missing. | | **Database** | Click **Detect** to look up the databases at that URL. If there's one, it's filled in; if there are several, pick the right one. | | **Firm API Key** | The key from Step 1. | > The Base URL must be **HTTPS**. Ask your Unanet administrator if you're unsure of your tenant address or which database to use. Click **Test** to confirm the API key works for that tenant and database before saving. ### Step 4: Turn on Project sync In the **Project sync** card, switch **on** *"Import this organization's Unanet projects and opportunities into Cogram."* Then pick a **Sync owner**. This Cogram user owns each synced project until Cogram matches the Unanet project manager or principal to a Cogram user by email on a later sync. To make imported projects easy to find, check **Make newly synced projects discoverable**. Projects the sync creates then appear in the organization-wide project directory, where members can find them and request access; see [Project discoverability](/projects/projects#project-discoverability). This applies only to projects imported after you turn it on; projects already in Cogram keep their current discoverability setting. Click **Save** to apply the sync settings. ### Step 5: Run the first sync Click **Sync now** to import immediately (otherwise the first sync runs on the next scheduled cycle). Projects appear in the background within a few minutes for typical firms; longer for large accounts. **What gets imported:** * One Cogram project per Unanet project, with its **name** and **project code**. * Opportunities alongside projects. * The project **owner**, matched from the Unanet project manager / principal by email, or the Sync owner as a fallback. * **Team members**: the project's Unanet team roster, added as project members. Owners and team members are matched to Cogram users **by work email**. Only people who are already Cogram users receive a role; Unanet sync never creates or invites accounts. Roles you set manually in Cogram are left untouched. After the first sync, Cogram refreshes automatically **about every 6 hours**. The card shows the last-sync time and a **Sync now** button to pull changes on demand. ## Part 2: Instant updates (webhook) The \~6h sync keeps Cogram current, but a new or edited project can take hours to appear. The **instant-updates webhook** closes that gap: Unanet notifies Cogram the moment a project changes, so updates land in **seconds**. The periodic sync stays on as a backstop that reconciles anything a webhook missed. Setup has two sides: enable it in Cogram (to get a URL), then register that URL in Unanet's Event Manager. ### Cogram side: enable and copy the URL > The **Instant updates (webhook)** card appears once **Project sync** is enabled (Part 1). 1. Switch **on** **Instant updates (webhook)**. 2. Copy the **Webhook URL**. It contains a secret token unique to your organization; treat it like a password. **Rotating and disabling:** * **Regenerate URL** issues a new URL and **invalidates the old one immediately**. Use it if the URL may have leaked, then update it in Unanet. * Turning the webhook **off** keeps the same token, so re-enabling later reuses the same URL, with no need to re-edit Unanet. ### Unanet side: register the URL in Event Manager Have your **Unanet administrator** do this in the Unanet desktop client. Follow the numbered steps in the screenshot: <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-92fbbd3d2a6f728d7feb9a21a1ca92d9d3fc2d43%2Funanet-event-manager-webhook-setup.png?alt=media" alt="Unanet ERP A/E Event Manager showing the Projects event list and the Settings/Webhooks tab, annotated with the five setup steps" width="900"><figcaption><p>Unanet Event Manager: the five-step webhook setup</p></figcaption></figure> 1. Open the **Administration** module (bottom-left). 2. Go to **Event Manager**. 3. In the category dropdown, select **Projects**. 4. For each of these five events, select it, check **Track Event** and **Process Webhooks**, and under the **Webhooks** tab add a row with Method **POST** and the Cogram Webhook URL: * `Project - Created` * `Project - Saved` * `Project - Activated` * `Project - Deactivated` * `Project - Deleted` 5. Click **Save** (top-left), **once for every event you changed**. This is the most-missed step: an unsaved event silently sends nothing. > **Additive.** Leave any existing webhooks (for example a Newforma integration) in place; add the Cogram row alongside them. An event can POST to more than one URL. ## Synced projects in Cogram Synced projects appear in everyone's [project list](https://app.cogram.com/dashboard/projects) automatically, with no per-user setup. Each shows its Unanet **project code**, **name**, and **team** (the project manager / principal as owner, plus the project members) for everyone matched to a Cogram user by email. Core details are managed in Unanet: edit them there and they update in Cogram on the next sync, or in seconds when instant updates are on. Meeting notes, emails, field reports, and drawings work as usual. The synced Unanet data (project id, lead stage, your user-defined fields, and the project's market sectors with their percentage split) is also readable through the [Cogram API](/integrations/cogram-api); see the [interactive API docs](https://api.cogram.com/v1/docs) for the project response fields, so your own integrations can join Cogram projects back to Unanet. ## Managing the connection ### Change or remove the org connection (admin) In [**Organization Settings → Integrations → Unanet ERP A/E**](https://app.cogram.com/dashboard/settings/admin/integrations), update the Base URL, database, or API key (leave the key blank to keep the stored one), or click **Remove** to delete the connection entirely. Removing it hides the integration for everyone in the organization. ### Stop syncing Switch **Project sync** off and **Save**. Existing Cogram projects are preserved; the scheduled sync pauses until you re-enable it. With sync off, the instant-updates webhook is ignored too: no sync fires. ## Troubleshooting #### Test fails: "API key not recognized" Unanet didn't accept the API key for that database. Re-check the key under **Administration → API Management → Manage Keys** in Unanet, and confirm the **Database** is correct. #### Detect finds no databases (admin) Double-check the Base URL. It should be your tenant address ending in `/platform` (e.g. `https://acme.infocusapp.com/platform`). Confirm the tenant is reachable, and ask your Unanet administrator if unsure. #### Projects aren't updating instantly Confirm the webhook is set up on the Unanet side: for **every** event, both **Track Event** and **Process Webhooks** must be checked **and** the event **Saved**. A missed event is still reconciled by the \~6h full sync. Also check that **Project sync** is on in Cogram; with sync off, the webhook is ignored. #### Project owner is the Sync owner, not the project manager The Unanet project manager / principal email doesn't match a Cogram user. Invite that person to Cogram; the next sync assigns them. #### A Unanet team member isn't on the project in Cogram Sync assigns roles only to people who are already Cogram users, matched by work email. Invite them to Cogram (and confirm their Unanet work email matches); the next sync adds their role. Unanet sync never creates accounts. #### I don't see "Unanet ERP A/E" in Organization Settings Your organization may not have the integration enabled. Contact <support@cogram.com>. ## Per-user agent (early access) > **Early access.** This is separate from project sync (above) and still evolving. It imports nothing. It lets Cogram Agent query Unanet **live and read-only**, scoped to what each person can see in Unanet. Once an admin has connected the organization (Part 1), each person can link their own Unanet login: 1. Go to [**Account Settings → Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations) and find **Unanet ERP A/E**. 2. Enter your Unanet **username** and **password**, then **Save**. Your password is encrypted at rest and never shown back to you. 3. Click **Test**: Cogram signs in to Unanet as you and confirms it works. Then ask Agent in plain language, for example *"List our Unanet projects"* or *"Show me our Unanet clients."* Results are fetched live and scoped to your Unanet account. **Troubleshooting:** * **I don't see "Unanet ERP A/E" in my Account Settings**: an admin hasn't connected the organization yet. Ask your admin to complete [Part 1](#part-1-set-up-the-organization-project-sync-admin). * **"Authentication failed" after Test**: Unanet rejected the sign-in. Confirm your username and password (try signing in to Unanet directly), re-enter your password in Cogram, and Test again. ## Next steps **For admins:** [Connecting Deltek VantagePoint](/integrations/connecting-vantagepoint), [Organization roles](/organization-administration/organization-roles) **For everyone:** [Projects](/projects/projects) # 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) 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). ## 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) 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): what your team can do with the connected shares. * [Agent](/agent/agent) can search and read these files when someone asks it a question. * [Privacy and confidentiality](/get-started/privacy-and-confidentiality) # Cogram API Integrate Cogram with your own systems: automate project management, sync user data, and build custom integrations against a stable REST API. ## Overview The REST API lives on its own subdomain (`api.cogram.com`), authenticates with API keys, and exposes stable, versioned endpoints built for third-party integrations. **Key features:** * **Stable versioned endpoints** - The API is versioned (`/v1/`) to ensure backwards compatibility * **Interactive documentation** - Explore and test endpoints directly at [api.cogram.com/v1/docs](https://api.cogram.com/v1/docs) * **External ID mapping** - Link Cogram resources to your own system's identifiers ## Authentication The Cogram API uses API key authentication. API keys are organization-scoped and can be created by organization administrators. ### Creating an API Key 1. Go to [Organization Settings → Integrations → API Keys](https://app.cogram.com/dashboard/settings/admin/integrations) in the Cogram app. 2. Click **Create API Key**. 3. Give your key a descriptive name and optionally set an expiration date. 4. Copy the key immediately. It will only be shown once. ### Using Your API Key Include the API key in the `Authorization` header as a Bearer token: ```bash curl -X GET "https://api.cogram.com/v1/projects" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Optional Headers > **X-Forwarded-User**: Identifier of the user in your system (e.g., user ID or email) who triggered this action. When provided, Cogram's audit logs will attribute the action to this user rather than just the API key. Omit for automated system tasks with no associated user. ## Base URL All API requests should be made to: ``` https://api.cogram.com ``` ## Available Endpoints ### Projects Manage projects within your organization. | Method | Endpoint | Description | | -------- | ------------------- | ---------------------- | | `GET` | `/v1/projects` | List all projects | | `POST` | `/v1/projects` | Create a new project | | `GET` | `/v1/projects/{id}` | Get a specific project | | `PATCH` | `/v1/projects/{id}` | Update a project | | `DELETE` | `/v1/projects/{id}` | Archive a project | Project create and update requests, and all project responses, include an **`is_public`** field. When `true`, the project is discoverable: it appears in the organization-wide project directory and non-members can request access. When `false`, the project is not listed in the directory. See the [interactive API docs](https://api.cogram.com/v1/docs) for full request/response schemas. #### Record counts per project Add **`?include=counts`** to either `GET /v1/projects` or `GET /v1/projects/{id}` to populate a `related_counts` object on each project: how many emails, documents, drawings, drawing sets, submittals, RFIs, meetings, reports, observations, and transmittals are filed under it. Every field is present and defaults to `0`, so a project with nothing filed returns zeros rather than omitting keys. To request more than one section at once, see [Members per project](#members-per-project) below. ```bash curl "https://api.cogram.com/v1/projects?include=counts&page_size=100" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Without the parameter, `related_counts` is `null` and no counting work is done; existing integrations are unaffected. The counts for a whole page cost one additional query regardless of `page_size`, so requesting them on a 100-project page is no more expensive than on one project. Counts are commonly used to notice that a project has changed since a previous poll: fetch a page, compare against the values you stored last time, and act on the projects that moved. Three kinds of change are invisible to them, because the number of records does not change: * An edit that leaves the record in place: a renamed document, a corrected email subject. * A new revision of an existing drawing, or action items generated for an existing meeting. Only the top-level record is counted, so `drawings` and `meetings` stay flat. * An addition and a deletion inside the same polling interval, which cancel out. Soft-deleted meetings are excluded, matching the rest of the API. Cogram's built-in example records are counted; they are real records in the project. #### Members per project Add **`?include=members`** to either `GET /v1/projects` or `GET /v1/projects/{id}` to populate a `members` array on each project. Every entry carries the member's `user_id`, `email`, and project `role` (`OWNER`, `LEAD`, `MEMBER`, or `VIEWER`), ordered by email so two polls can be compared without sorting first. `LEAD` is a management role (like `OWNER` but without the ability to add or remove members or delete the project) and appears only for organizations that have it enabled. Match on `user_id`, not `email`: two accounts can share an email address, and `user_id` is what the membership endpoints below are keyed by. Display names are not included; fetch `GET /v1/projects/{id}/members` when you need them. ```bash curl "https://api.cogram.com/v1/projects?include=members" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Without the parameter, `members` is `null` and no membership work is done; existing integrations are unaffected. A project that genuinely has no members returns `[]`, which is how you tell "nobody is on it" apart from "I didn't ask". `include` takes more than one section in a single request, spelled either way: repeat the parameter (`?include=members&include=counts`) or comma-separate the values (`?include=members,counts`). A name that matches no section is still rejected with a `422`, so a typo does not fail silently. Two things the array does not cover: * **Group-granted access is not listed.** Only direct per-user roles appear. Someone who can reach the project because their group was added to it is not a member here. * **Users banned from your organization are omitted**, matching `GET /v1/projects/{id}/members`. The roster for a whole page costs one additional query regardless of `page_size`, but unlike counts the response itself grows with every member it carries; a 100-project page returns the roster of all 100. If you only need one project's members, ask on `GET /v1/projects/{id}`. #### Polling for changed projects Add **`?updated_since=<timestamp>`** to `GET /v1/projects` to get only the projects that changed, instead of paging your whole organization to find out. Use it to keep an external system (a file server, a document store, a data warehouse) in step with Cogram. ```bash curl "https://api.cogram.com/v1/projects?include_archived=true&updated_since=2026-08-17T18%3A03%3A11Z" \ -H "Authorization: Bearer $COGRAM_API_KEY" ``` The timestamp must carry a UTC offset (`2026-08-17T18:03:11Z` or `2026-08-17T20:03:11+02:00`); one without an offset is rejected with `422`. Remember to URL-encode it: a raw `+` in a query string means a space. It answers **what changed, not what changed to what**. Each project comes back in its current state, so hold the values you care about and compare. That is what tells you a project was archived, renamed, or had a Unanet field rewritten. Four properties make it safe to build a loop on: * **It reports creations too.** A project created inside the window has no `updated_at` yet, so it is matched on `created_at` instead. One cursor covers both, and you do not need a second poll for new projects. * **Results are ordered oldest change first**, so a project modified while you are paging is appended rather than shifted into a page you already read. * **The bound is inclusive.** Store the newest `updated_at` (or `created_at`, for a project that has never been updated) you were served and pass it back next time. You may be served that one project again; you will not miss another that shares its timestamp across a page boundary. * **Archiving is a change, not a disappearance**, but only if you ask for it. Pass `include_archived=true`, or an archived project drops out of the response and reads as if it were deleted. Two limits to design around: * **Deletions are not reported.** A deleted project is absent from later responses. If that matters, reconcile against a full listing on a slower schedule. * **`updated_at` tracks the project record only**: its name, client, archive state, and Unanet fields. Filing an email or a drawing under a project does not change it. For that, use `?include=counts` above. ### Project Members Manage project membership and roles. | Method | Endpoint | Description | | -------- | ------------------------------------- | ---------------------- | | `GET` | `/v1/projects/{id}/members` | List project members | | `PUT` | `/v1/projects/{id}/members/{user_id}` | Add or update a member | | `DELETE` | `/v1/projects/{id}/members/{user_id}` | Remove a member | Assigning the `LEAD` role (on create-with-members or `PUT .../members/{user_id}`) requires the role to be enabled for your organization; otherwise the request returns `422`. `OWNER`, `MEMBER`, and `VIEWER` are always assignable. ### Project Types Manage the organization's project-type taxonomy (e.g. "Design-Build", "CM at Risk"). Project types are configured in the app at [Organization Settings → Projects → Project Types](https://app.cogram.com/dashboard/settings/admin/projects/project-types); the API exposes the same CRUD. | Method | Endpoint | Description | | -------- | ------------------------ | --------------------------- | | `GET` | `/v1/project-types` | List all project types | | `POST` | `/v1/project-types` | Create a new project type | | `GET` | `/v1/project-types/{id}` | Get a specific project type | | `PATCH` | `/v1/project-types/{id}` | Update a project type | | `DELETE` | `/v1/project-types/{id}` | Delete a project type | Deleting a type clears the type on any project that was using it (the project is not deleted). See the [interactive API docs](https://api.cogram.com/v1/docs) for full request/response schemas. ### Users Manage organization members. | Method | Endpoint | Description | | ------- | --------------------- | ------------------------- | | `GET` | `/v1/users` | List organization members | | `PATCH` | `/v1/users/{user_id}` | Update a user's role | ### Data Exports Request and download a multi-part zip export of your organization's data: projects, meetings, emails, documents, drawings, reports, observations, transmittals, and Procore-synced submittals and RFIs. Builds run asynchronously; once complete, each part is delivered via short-lived signed URLs (1-hour validity, regenerated on every status read). For an end-to-end walkthrough of what's inside each zip, see [Data export package layout](/organization-administration/data-export-package-layout). For the UI equivalent of these endpoints, see [Data exports](/organization-administration/data-exports). Data Exports are admin-equivalent: only admins or owners can issue API keys, and the endpoints can only be invoked by keys issued for the same organization. Manage keys at [Organization Settings → Integrations → API Keys](https://app.cogram.com/dashboard/settings/admin/integrations). | Method | Endpoint | Description | | ------ | ------------------------------ | -------------------------------------------------- | | `POST` | `/v1/data-exports` | Create a new data export (returns immediately) | | `GET` | `/v1/data-exports` | List data exports for the organization (paginated) | | `GET` | `/v1/data-exports/{id}` | Get one data export's status and download URLs | | `POST` | `/v1/data-exports/{id}/cancel` | Cancel a `pending` or `running` data export | `GET /v1/data-exports` returns the standard paginated envelope `{ "data": [...], "total": N, "page": N, "page_size": N }`. Use `?page=N&page_size=N` (defaults: `page=1`, `page_size=50`, max `page_size=100`) to walk through the audit trail. Meeting **audio recordings are never exported**. Each meeting in the zip ships as `meeting.json`, `meeting.md`, and `transcript.json` (when the meeting was transcribed). A rendered `meeting.docx` is added whenever your org has a default template (see [Data Exports → templates](/organization-administration/data-exports#choosing-a-meeting-template-before-exporting)). Photos and uploaded meeting attachments are included; audio is intentionally kept inside Cogram. #### Request body: `POST /v1/data-exports` | Field | Type | Description | | ------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `project_ids` | array\[string] \| null | Optional. Scope the export to these projects; list candidate ids with `GET /v1/projects` (add `?include_archived=true` to reach archived projects, which are still exportable). Org-wide exports (when omitted) must specify a time range under 6 calendar months. | | `time_filter` | object | Discriminated by `mode`. `{"mode": "range", "start": <iso>, "end": <iso>}` or `{"mode": "all_time"}`. `all_time` is project-only. | | `document_formats` | array\[string] | Optional, defaults to `[]`. Pass `["docx"]` to render a `.docx` per field report alongside the JSON, plus one per observation its report does not already show. Does not affect `meeting.docx`, which every export includes. Rendering makes the build slower and the zip larger. | #### Response fields | Field | Type | Description | | -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique identifier (`dex_...`) | | `organization_id` | string | Org the export belongs to | | `source` | string | `ui` or `api`: how the export was created | | `requester_user_id` | UUID \| null | User who triggered it (UI source only) | | `requester_api_key_id` | string \| null | API key that triggered it (API source only) | | `requester_forwarded_user` | string \| null | Value of the `X-Forwarded-User` header at create time (audit trail) | | `requester_display` | string | Human-readable attribution: user's name, `API key '<name>'`, or `<forwarded_user> (via API key '<name>')` when both are present | | `project_ids` | array\[string] | Scope as requested; empty for org-wide exports | | `projects` | array | Scope projects that still exist, with `id`, `name`, and `customer_project_id` | | `time_filter` | object | Echo of the requested filter | | `document_formats` | array\[string] | Echo of the requested rendered document formats | | `status` | string | `pending`, `running`, `cancelling`, `cancelled`, `completed`, `failed`, or `expired` | | `error` | string \| null | Failure reason when `status == "failed"` | | `requested_at` | datetime | When the export was created | | `started_at` | datetime \| null | When the build worker began | | `completed_at` | datetime \| null | When the build finished (success, failure, or cancellation) | | `expires_at` | datetime \| null | When the parts will be deleted from storage (7 days after `completed_at` for `completed`) | | `parts` | array | Empty until `status == "completed"`; one entry per zip part with a freshly-signed URL | Each entry in `parts` includes: | Field | Type | Description | | ------------ | ------- | -------------------------------------------------------- | | `id` | string | Unique part identifier (`dxp_...`) | | `part_index` | integer | Zero-indexed position within the multi-part set | | `size_bytes` | integer | Compressed part size | | `signed_url` | string | One-hour pre-signed download URL; re-fetch on every read | #### Polling pattern ```bash # 1) Create: returns 201 with status=pending curl -X POST "https://api.cogram.com/v1/data-exports" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"time_filter": {"mode": "range", "start": "2026-01-01T00:00:00Z", "end": "2026-04-01T00:00:00Z"}}' # 1b) Or scope it to specific projects, where any time range is allowed curl -X POST "https://api.cogram.com/v1/data-exports" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"project_ids": ["prj_...", "prj_..."], "time_filter": {"mode": "all_time"}}' # 2) Poll until status == "completed" curl "https://api.cogram.com/v1/data-exports/dex_..." \ -H "Authorization: Bearer YOUR_API_KEY" # 3) Download each part. The signed URLs are valid for 1 hour from the GET # above and serve a Content-Disposition header so the file lands with # a friendly name like # Cogram_data_export_2026-04-01_12-00-00_part_000_all_projects_2026-01-01_to_2026-04-01.zip # # With wget, use --content-disposition to honor the suggested filename: wget --content-disposition '<signed_url>' # # With curl, use -OJ (capital O capital J). Plain `curl -o name.zip` # forces a local name and bypasses the friendly filename entirely. curl -OJ '<signed_url>' ``` The zip's internal structure, including folders, file types, and how to identify Cogram's example/demo data (the `is_dummy` field on JSON entities, and the `X-Cogram-Is-Dummy` header on `.eml` files), is documented in [Data Export Package Layout](/organization-administration/data-export-package-layout#identifying-example--demo-data). > **Date ranges are inclusive of the `end` timestamp.** The backend filter is `<=` on the `end` value you supply. If you want "everything modified through May 31", send `end=2026-06-01T00:00:00Z` (the next-day UTC midnight). Sending `2026-05-31T00:00:00Z` would only capture exactly midnight on May 31, not the full day. The Cogram UI does this conversion for you when you pick a date in the date-picker; API callers must do it themselves. > **Cap rule**: Org-wide exports (no `project_ids`) are limited to a 6-month range and reject `all_time`. Project-scoped exports have no time-range limit. A violation returns `400` with `"error": "range_too_large"` (typed `ErrorCode`). > **Project scope**: A project id your organization doesn't own returns `404` with `"error": "not_found"`, the same response as an id that doesn't exist anywhere, so the API never reveals another organization's projects. One bad id rejects the whole request, so you never receive a zip that silently covers fewer projects than you asked for. The check runs before the export is accepted, so a rejected scope costs you nothing: no export row is created and the one-active-export slot stays free for an immediate retry. > **Deprecated `project_id`**: the original single-project field is still accepted and normalizes to a one-element `project_ids`. Sending both fields returns `422`. New integrations should use `project_ids`. > **Concurrency**: At most one active export (`pending`, `running`, or `cancelling`) per organization, enforced both at the application layer and by a Postgres partial unique index. A second `POST /v1/data-exports` while an active one exists returns `409` with `"error": "data_export_in_progress"` and the existing export's id woven into the message. Poll that id and re-issue once it terminates. > **Cancellation**: `pending` exports cancel immediately. `running` exports transition to `cancelling`; the worker stops between zip parts and the next status read reflects the terminal state. Terminal statuses (`completed`, `failed`, `cancelled`, `expired`) return `409 conflict`. > **Stuck-row recovery**: If a worker dies hard mid-build (rare), a periodic sweep transitions rows stuck in `running`/`cancelling` past the build-deadline cap (\~6 hours) to `failed` so the per-org concurrency slot doesn't stay blocked. Retry by creating a new export. ### Backup Runs Report each backup run performed by the LucidLink connector, so Cogram can tell you when backups stop. Cogram cannot detect a backup that never starts: a connector that has stopped cannot report that it stopped. Instead, the LucidLink connector tells Cogram when a run finishes and how often it is scheduled to run. If a scheduled run is missed (no successful run within that interval), Cogram emails the recipients configured at [Organization Settings → Integrations → LucidLink Backups](https://app.cogram.com/dashboard/settings/admin/integrations#backups). You get one email per outage, and it resets after the next successful run. You do not need to call this endpoint yourself if you use the LucidLink connector; it reports its own runs. | Method | Endpoint | Description | | ------ | ----------------- | ---------------------------------------- | | `POST` | `/v1/backup-runs` | Report that a backup started or finished | #### Request body: `POST /v1/backup-runs` | Field | Type | Description | | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------- | | `event` | string | `started` when a run begins, `finished` when it ends. | | `schedule_interval_hours` | integer | How often the backup is scheduled to run, in hours (1–8760). Cogram measures health against this. | | `status` | string \| null | `success` or `failed`. Required on `finished`, and must be omitted on `started`. | | `projects_synced` | integer \| null | Optional. Projects filed by this run. Zero is valid: a run with no changed projects is healthy. | | `error` | string \| null | Optional failure detail, up to 2000 characters. Only meaningful when `status` is `failed`. | #### Example ```bash # A run begins curl -X POST 'https://api.cogram.com/v1/backup-runs' \ -H 'Authorization: Bearer <api-key>' \ -H 'Content-Type: application/json' \ -d '{"event": "started", "schedule_interval_hours": 24}' # The same run finishes curl -X POST 'https://api.cogram.com/v1/backup-runs' \ -H 'Authorization: Bearer <api-key>' \ -H 'Content-Type: application/json' \ -d '{"event": "finished", "schedule_interval_hours": 24, "status": "success", "projects_synced": 12}' ``` > **Only successful runs count as healthy.** A `failed` run tells Cogram the connector is alive, but not that your data is backed up, so it does not clear a stale-backup alert. > **Alerts are off until you add recipients.** Configure them under [Organization Settings → Integrations → LucidLink Backups](https://app.cogram.com/dashboard/settings/admin/integrations#backups). An empty recipient list turns alerting off. ### Action Items Retrieve action items extracted from meetings within your organization. | Method | Endpoint | Description | | ------ | ------------------ | ----------------- | | `GET` | `/v1/action-items` | List action items | #### Filtering and search The list endpoint supports the following query parameters: | Parameter | Type | Default | Description | | ------------------ | ------- | ------------ | ---------------------------------------------------------------------------- | | `page` | integer | `1` | Page number (1-indexed) | | `page_size` | integer | `50` | Items per page (max 100) | | `status` | string | — | Filter by status: `SUGGESTED`, `ACCEPTED`, `REJECTED`, or `COMPLETED` | | `include_archived` | boolean | `false` | Set to `true` to include archived items | | `project_id` | string | — | Filter to items from meetings linked to this project | | `meeting_id` | string | — | Filter to items from a specific meeting | | `assignee` | string | — | Case-insensitive partial match on assignee name | | `q` | string | — | Case-insensitive search in item description | | `sort_by` | string | `created_at` | Sort field: `created_at`, `due_date`, `status`, `assignee`, or `description` | | `sort_dir` | string | `asc` | Sort direction: `asc` or `desc` | > When filtering by `project_id`, action items from meetings not linked to any project are excluded. Unknown `project_id` or `meeting_id` values return an empty list, not a 404 error. > Items with no value in nullable sort fields (`due_date`, `assignee`, `status`, `description`) are always placed at the bottom, regardless of sort direction. #### Response fields Each action item in the `data` array includes: | Field | Type | Description | | -------------- | ---------------- | --------------------------------------------------- | | `id` | string | Unique identifier | | `description` | string \| null | Action item text | | `assignee` | string \| null | Assigned person's name | | `status` | string \| null | `SUGGESTED`, `ACCEPTED`, `REJECTED`, or `COMPLETED` | | `origin` | string \| null | `AUTO` (AI-extracted) or `MANUAL` (user-created) | | `due_date` | datetime \| null | Due date in ISO 8601 format | | `completed_at` | datetime \| null | Timestamp when marked done | | `archived` | boolean | Whether the item has been archived | | `meeting_id` | string | ID of the meeting this item came from | | `meeting_name` | string \| null | Name of the meeting | | `project_id` | string \| null | ID of the project the meeting belongs to, if any | | `created_at` | datetime | Creation timestamp in ISO 8601 format | | `updated_at` | datetime \| null | Last update timestamp | ### Board Items Retrieve kanban board items: action items that have been promoted to a project's board, either manually by users or automatically via meeting reconciliation. Read-only in v1. | Method | Endpoint | Description | | ------ | ---------------------- | ------------------------------ | | `GET` | `/v1/board-items` | List board items | | `GET` | `/v1/board-items/{id}` | Get a single item with history | #### Filtering and search The list endpoint supports the following query parameters: | Parameter | Type | Default | Description | | -------------------- | ------- | ------------ | -------------------------------------------------------------------------------------------------- | | `page` | integer | `1` | Page number (1-indexed) | | `page_size` | integer | `50` | Items per page (max 100) | | `status` | string | — | Filter by status: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`, or `DISMISSED` | | `include_archived` | boolean | `false` | Set to `true` to include archived items | | `project_id` | string | — | Filter to items in this project | | `meeting_id` | string | — | Filter to items originated from this meeting (matches `source_meeting_id`) | | `meeting_series_uid` | string | — | Filter to items tied to a recurring meeting series | | `assignee` | string | — | Case-insensitive partial match on assignee name | | `q` | string | — | Case-insensitive search across `title` and `body` | | `sort_by` | string | `created_at` | Sort field: `created_at`, `updated_at`, `last_status_changed_at`, `status`, `title`, or `assignee` | | `sort_dir` | string | `asc` | Sort direction: `asc` or `desc` | > Unknown `project_id` or `meeting_id` values return an empty list, not a 404 error. > Items with no value in nullable sort fields (`assignee`, `last_status_changed_at`) are always placed at the bottom, regardless of sort direction. > The list endpoint excludes archived items by default. The get-by-id endpoint returns archived items. #### Response fields Each board item in the `data` array (and in the detail response) includes: | Field | Type | Description | | ------------------------ | ---------------- | -------------------------------------------------------------------- | | `id` | string | Unique identifier (`pbi_...`) | | `project_id` | string | ID of the project this item belongs to | | `project_name` | string | Name of the project, for convenience | | `title` | string | Short item title | | `body` | string \| null | Optional long-form markdown description | | `status` | string | `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`, or `DISMISSED` | | `priority` | string \| null | `URGENT`, `HIGH`, `NORMAL`, or `LOW`; `null` if unset | | `due_date` | date \| null | Calendar due date in ISO 8601 (`YYYY-MM-DD`); `null` if unset | | `assignee` | string \| null | Free-text assignee name (may differ from linked user's display name) | | `assignee_user_id` | UUID \| null | Cogram user the item is assigned to, if matched | | `source_meeting_id` | string \| null | Meeting this item was originated from, if any | | `source_meeting_name` | string \| null | Name of the source meeting | | `meeting_series_uid` | string \| null | Identifier of the recurring meeting series, if applicable | | `archived` | boolean | Whether the item has been archived | | `created_at` | datetime | Creation timestamp in ISO 8601 format | | `updated_at` | datetime \| null | Last update timestamp | | `last_status_changed_at` | datetime \| null | Timestamp of the most recent history entry, or `null` if none | #### History (detail endpoint only) `GET /v1/board-items/{id}` additionally returns a `history` array of timeline entries for the item, ordered oldest-first. Each entry represents a `BoardItemHistoryEntry` row, which may record a status transition, an assignee change, a priority shift, a due-date move, a comment, or any combination. | Field | Type | Description | | --------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique identifier (`bsc_...`) | | `changed_at` | datetime | When the change was applied | | `changed_by_user_id` | UUID \| null | Cogram user who made the change; `null` for automated (LLM) changes | | `changed_by_user_name` | string \| null | Display name of the user, for convenience | | `triggered_by_meeting_id` | string \| null | Meeting that triggered this change, if any | | `triggered_by_meeting_name` | string \| null | Name of the triggering meeting | | `previous_status` | string \| null | Status before the change (`null` on the initial creation entry, or on a non-status row) | | `new_status` | string \| null | Status after the change. `null` on rows that aren't status transitions (assignee, priority, due-date, or pure-comment rows) | | `previous_assignee` | string \| null | Free-text assignee before the change | | `new_assignee` | string \| null | Free-text assignee after the change | | `previous_assignee_user_id` | UUID \| null | Linked user before the change | | `new_assignee_user_id` | UUID \| null | Linked user after the change | | `previous_priority` | string \| null | Priority before the change (`URGENT`, `HIGH`, `NORMAL`, `LOW`, or `null`) | | `new_priority` | string \| null | Priority after the change | | `previous_due_date` | date \| null | Due date (ISO `YYYY-MM-DD`) before the change | | `new_due_date` | date \| null | Due date after the change | | `reason` | string \| null | LLM-authored justification (only set on reconciliation-triggered rows) | | `comment` | string \| null | User-authored comment, if any | To distinguish entry types from a single row: * **Status transition**: `previous_status != new_status` * **Assignee change**: `new_assignee != previous_assignee` (or the `*_user_id` equivalents) * **Priority change**: `new_priority != previous_priority` * **Due-date change**: `new_due_date != previous_due_date` * **Comment**: `comment` is set and there is no other delta * **Automated change**: `changed_by_user_id` is `null` and `triggered_by_meeting_id` is set ### Directory Cogram builds a company for a firm and a contact for each person you correspond with. A contact only gets its company automatically when a transmittal goes out. A contact added in the directory, imported from a file, or created by inbound email keeps an empty company, even when your directory already holds the firm that owns the email domain. These two endpoints close that gap. `GET` proposes a company for each such contact, and `POST` writes the proposals you accept. | Method | Endpoint | Description | | ------ | ------------------------------------- | --------------------------------------- | | `GET` | `/v1/directory/contact-company-links` | List proposed contact-to-company links | | `POST` | `/v1/directory/contact-company-links` | Apply proposed contact-to-company links | `GET` returns the standard paginated envelope and writes nothing. A contact appears only when it has no company and a company in your directory lists the domain of its primary email. Archived contacts are not listed, and an archived company proposes nothing. #### Response fields: `GET /v1/directory/contact-company-links` | Field | Type | Description | | --------------- | -------------- | ------------------------------------------------------------------------------------------------- | | `contact_id` | string | The contact that has no company (`ctc_...`) | | `primary_email` | string | The contact's primary email address | | `first_name` | string \| null | Given name, if the contact has one | | `last_name` | string \| null | Family name, if the contact has one | | `domain` | string | Domain of `primary_email`, lowercased | | `company` | object | The company `POST` would link: `{ "id": "cmp_...", "name": "..." }` | | `also_claiming` | array | Other companies that list `domain`. Usually empty. When it is not, two companies carry one domain | The proposal uses the oldest company that lists the domain, which is the same company a transmittal send would pick. Only the primary email decides. An address in a contact's additional emails is often a personal mailbox, so Cogram does not read a firm from it. #### Request body: `POST /v1/directory/contact-company-links` | Field | Type | Description | | ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | `contact_ids` | array\[string] \| null | Optional. Apply only the proposals for these contacts. Omit to apply all. Unknown or already-linked ids are ignored | #### Response fields: `POST /v1/directory/contact-company-links` | Field | Type | Description | | --------- | ------- | ----------------------------------------------------------------------------------------------------- | | `applied` | array | Every link the call wrote, as `{ "contact_id": "ctc_...", "company_id": "cmp_..." }` | | `linked` | integer | How many contacts were given a company | | `skipped` | integer | Proposals the call did not write, because the contact gained a company between the read and the write | Keep the `applied` list. It names the contacts that had no company before the call, so it is what you reverse a wrong run from — nothing else records that. Read the proposal before you apply it. If a company in your directory lists a consumer domain such as `gmail.com`, every personal address in your organization is proposed for that company, and Cogram cannot tell that apart from a real firm. A contact that already has a company is never changed, so an assignment made by a person always wins. ```bash # 1) Read the proposals curl "https://api.cogram.com/v1/directory/contact-company-links?page=1&page_size=100" \ -H "Authorization: Bearer YOUR_API_KEY" # 2) Apply all of them curl -X POST "https://api.cogram.com/v1/directory/contact-company-links" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' # 2b) Or apply only the contacts you reviewed curl -X POST "https://api.cogram.com/v1/directory/contact-company-links" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contact_ids": ["ctc_...", "ctc_..."]}' ``` ## Rate Limiting API requests are rate limited on a per-key basis. The default limit is **1000 requests per minute**. When you exceed the rate limit, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating when you can retry. ## Error Handling The API uses standard HTTP status codes and returns errors in a consistent JSON format: ```json { "error": "error_code", "message": "Human-readable description" } ``` ### Common Error Codes | HTTP Status | Error Code | Description | | ----------- | ------------------------- | ------------------------------------------------------------------ | | 400 | `range_too_large` | Org-wide Data Export exceeded the 6-month cap (or used `all_time`) | | 401 | `api_key_missing` | No API key provided | | 401 | `api_key_invalid` | API key not found or incorrect | | 401 | `api_key_expired` | API key has expired | | 404 | `not_found` | Resource does not exist | | 409 | `conflict` | Resource already exists | | 409 | `data_export_in_progress` | Org already has an active Data Export; poll its id and retry | | 422 | `validation_error` | Invalid request body | | 429 | `rate_limit_exceeded` | Too many requests | This is not an exhaustive list. For all possible error responses per each endpoint and all error codes, see the interactive documentation at [api.cogram.com/v1/docs](https://api.cogram.com/v1/docs). ## Pagination List endpoints support pagination using query parameters: | Parameter | Default | Max | Description | | ----------- | ------- | --- | ------------------------ | | `page` | 1 | - | Page number (1-indexed) | | `page_size` | 50 | 100 | Number of items per page | Example: ```bash curl "https://api.cogram.com/v1/projects?page=2&page_size=25" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Paginated response format: ```json { "data": [...], "total": 150, "page": 2, "page_size": 25 } ``` ## API Reference For detailed endpoint documentation, request/response schemas, error codes and an interactive API explorer, visit: [**api.cogram.com/v1/docs**](https://api.cogram.com/v1/docs) ## Security Best Practices * **Keep your API keys secret** - Never expose them in client-side code or public repositories * **Use environment variables** - Store API keys in environment variables, not in code * **Rotate keys regularly** - Create new keys and revoke old ones periodically * **Use descriptive names** - Name your keys by their purpose to track usage * **Revoke unused keys** - Delete keys that are no longer needed ## Support Questions or issues with the API? Email <support@cogram.com> or use the in-app Help menu. # MCP server Connect ChatGPT, Claude, or a custom AI agent to Cogram through the MCP server: read-only access, acting as the person who connected it. Cogram's MCP server lets a user connect an AI application to Cogram and then ask it questions about their projects — meeting minutes, emails, RFIs, submittals, drawings, field reports, and the directory. MCP (Model Context Protocol) is the open standard that AI applications use to reach outside systems. Any MCP client can connect: ChatGPT, claude.ai, or an agent your own team builds. **Server address:** `https://mcp.cogram.com/mcp` Two facts define what a connected agent can do: * **It is read-only.** The agent can search, read, and summarize. It cannot create, change, or delete anything in Cogram. * **It acts as one person.** The agent sees exactly what the user who connected it can see, and nothing more. This page covers setup for organization administrators. Users connecting ChatGPT, Claude, or another AI app follow [Connecting AI apps](/integrations/connecting-ai-apps) instead. You control MCP access in two places: in Cogram, where you allow connections at all, and — if your company runs a ChatGPT or Claude workspace — in that workspace, where you make Cogram available to its users. ## Step 1: Turn on MCP access in Cogram MCP access is **off by default** for every organization. An administrator turns it on once, for the whole organization. 1. Go to [Organization Settings → Integrations → MCP access](https://app.cogram.com/dashboard/settings/admin/integrations#mcp-access). 2. Turn on **Allow members to connect third-party AI agents**. The same page shows the **Server URL** with a copy button — this is the address users and AI applications need. Once MCP access is on, any user can connect an AI application for themselves. Users who connect nothing are unaffected. Turning it off again cuts off every agent already connected, and stops users connecting new ones. > **If you do not see MCP access** in Organization Settings → Integrations, MCP access is not yet available for your organization. Email <support@cogram.com>. If your users are on personal AI accounts, you are done — send them to [Connecting AI apps](/integrations/connecting-ai-apps). The rest of this page covers company-managed AI workspaces and custom agents. ## Step 2 (optional): Publish Cogram in your ChatGPT workspace On ChatGPT Business, Enterprise, and Edu, users cannot add custom MCP apps themselves — a workspace admin creates the Cogram app once and publishes it to the workspace. 1. As an admin or owner, enable developer mode for yourself under **Settings → Apps → Advanced settings → Developer mode**. Each admin enables it for themselves; it is also offered when you create an app. (On Enterprise and Edu, you can additionally grant developer mode to selected non-admin users under **Workspace Settings → Permissions & Roles → Connected Data**.) 2. Go to **Workspace settings → Apps → Create**. 3. Name the app **Cogram MCP** and enter the MCP server URL `https://mcp.cogram.com/mcp`. Choose **OAuth** as the authentication method. 4. Select **Scan Tools**. ChatGPT opens Cogram's sign-in — sign in as you normally do, including through your identity provider if your organization uses SSO, then select **Allow** on the approval screen. 5. Wait for the tool scan to finish, then select **Create**. The app is saved as a draft in **Workspace Settings → Apps → Drafts**. Optionally test it first: in a new chat, select the draft (labeled "Dev") from the tools menu and ask it about your Cogram projects. 6. Publish it: **Workspace settings → Apps → Drafts → Publish**, and confirm the review prompts. Every Cogram tool is read-only, so there are no write actions to review. 7. On Enterprise and Edu, the publish dialog also lets you restrict individual tools (**Configure Actions**) or limit which groups see the app (**Configure Access**). **Expected result:** Cogram MCP appears for users under **Plugins**, on your workspace's tab, labeled "custom" — they install it as described in [Connecting AI apps](/integrations/connecting-ai-apps). Each user signs in to Cogram themselves, so every user's agent sees only their own projects. ChatGPT freezes the app's tool list when you publish. When Cogram releases new tools, they are not picked up automatically: on Enterprise and Edu, select **Refresh** under the app's **Action control** and enable the new tools (new tools arrive disabled); on Business, recreate and republish the app. ## Step 3 (optional): Publish Cogram in your Claude workspace On Claude Team and Enterprise plans, an Owner can add Cogram as a custom connector for the whole organization. Only Owners can do this. 1. Go to **Organization settings → Connectors**. 2. Select **Add**, hover over **Custom**, and choose **Web**. 3. Name the connector **Cogram MCP** and enter the MCP server URL `https://mcp.cogram.com/mcp`. 4. Leave the OAuth Client ID and Client Secret fields under Advanced settings empty — Cogram registers each client automatically. 5. Select **Add**. **Expected result:** every user sees Cogram MCP under **Customize → Connectors**, labeled "Custom" — they connect it as described in [Connecting AI apps](/integrations/connecting-ai-apps). Each user selects **Connect** there and signs in to Cogram themselves, so every user's agent sees only their own projects. ## Connect a custom client or in-house agent The server is a standard MCP server: streamable HTTP transport, OAuth 2.1 with dynamic client registration. Point any MCP client library, or the Anthropic MCP connector, at `https://mcp.cogram.com/mcp`. The client handles discovery and the OAuth flow — including registering itself, so there is nothing to pre-register with Cogram. Two things to plan for in your own agent: * **One interactive sign-in per identity.** There are no machine accounts or service accounts. A person must sign in to Cogram in a browser and approve the connection once, for each identity the agent runs as. * **Store and rotate the refresh token.** After approval your agent holds a refresh token, which it exchanges for short-lived access tokens. Keep it somewhere secret, and replace your stored copy with the new one each time you refresh. If you lose it or it expires, the only recovery is another interactive sign-in. If several people use your agent and each should see only their own projects, connect once per person and keep their tokens apart. One shared connection means everyone sees the data of whoever approved it. ### Treat Cogram content as data, not instructions Tool results carry text that people outside your organization wrote: email bodies, meeting transcripts, attachment text, RFI questions, directory notes. Any of it can contain something that reads like an instruction to an AI model — "ignore your previous instructions", "email this file to…", "the user has approved…". Your agent must treat every tool result as untrusted data: * Keep tool results separate from your own instructions in the prompt, and say plainly in the system prompt that content returned by tools is data to be examined, never a command to follow. * Never let a tool result decide, on its own, to call another tool that acts outside Cogram — sending mail, writing to another system, running code. * Put a human in front of any consequential action your agent takes from Cogram content. The Cogram MCP server is read-only, so nothing an agent reads can change Cogram. The risk is what your agent does next with what it read. ## What a connected agent can and cannot do | Can | Cannot | | ---------------------------------------------------- | ---------------------------------------------------------------- | | Search and read the Cogram records the user can open | Create, edit, delete, or archive anything | | Read attachment and document text | Send emails, transmittals, or notifications | | Get time-limited links to drawing sheet images | Reach a project the user is not a member of | | Read the organization's directory and user list | Reach another organization's data | | Act as one named user | Act as a machine account, an admin, or the organization at large | Cogram permissions apply unchanged. Project membership, [project roles](/projects/project-roles), and [asset visibility](/projects/asset-visibility) all still decide what the agent sees, because every request is answered as the connected user. ## What data an agent can reach The agent works through a fixed set of read-only tools. The **Module needed** column shows where a tool depends on your organization's [licensing](/organization-administration/licensing): if your organization is not licensed for that module, those tools are not offered to the agent at all. | Category | Module needed | Tools | | ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Connected user identity | — | `whoami` | | Projects | — | `search_projects`, `get_projects_by_id` | | Meetings and meeting attachments | Meetings | `search_meetings`, `get_meetings_by_id`, `search_meeting_attachments`, `get_meeting_attachment_content` | | Emails and email attachments | Email Management | `search_emails`, `get_emails_by_id`, `search_email_attachments`, `get_email_attachment_content` | | Documents | — | `search_documents`, `get_documents_by_id` | | RFIs and submittals | Correspondence | `search_rfis`, `get_rfis_by_id`, `search_submittals`, `get_submittals_by_id` | | Drawings, field reports, observations | Field Reports | `search_drawings`, `get_drawings_by_id`, `search_reports`, `get_reports_by_id`, `search_observations`, `get_observations_by_id` | | Transmittals | Transmittals or Email Management | `search_transmittals`, `get_transmittals_by_id` | | Project boards | — | `search_board_items`, `get_board_item`, `get_board_items_for_meeting` | | Workflows | — | `search_workflows`, `get_workflows_by_id` | | People and companies | — | `search_org_members`, `search_directory` | | Organization overview | — | `get_org_data_summary` | Meeting audio recordings are not reachable through any tool. Transcripts are, for users who can already read them. Retrieval tools that take a list of IDs accept at most 100 IDs per call. An agent that asks for more gets a validation error, so have it work in batches. ## Rate limit Each user is allowed **50 requests per minute per connected application**. Two applications connected by the same person get their own allowance each, and two users never share one. Over the limit, the server answers `429` with a `Retry-After` header. A well-behaved MCP client waits and retries. If your work genuinely needs a higher limit, email <support@cogram.com> — the limit is not something you can change yourself. ## Troubleshooting **Symptom**: The agent reports "MCP access is not enabled for your organization", or the approval screen offers no **Allow** button. **Likely cause**: MCP access is off for your organization. **Fix**: Turn it on at [Organization Settings → Integrations → MCP access](https://app.cogram.com/dashboard/settings/admin/integrations#mcp-access). If the setting is not on that page, email <support@cogram.com>. **Symptom**: Cogram does not appear in ChatGPT's tools menu. **Likely cause**: On Business, Enterprise, and Edu, a workspace admin has not published the Cogram app yet — users cannot add it themselves. On Pro, developer mode is off. **Fix**: Publish the Cogram app (see [Step 2](#step-2-optional-publish-cogram-in-your-chatgpt-workspace) above) — users cannot add it themselves. On Pro, the user turns on developer mode under **Settings → Apps → Advanced settings**. **Symptom**: A whole category is missing from the agent's tool list, or a call answers "The Meetings module is not licensed for your Cogram account." **Likely cause**: Your organization is not licensed for that module. **Fix**: Check [Licensing](/organization-administration/licensing), then email <support@cogram.com> about the module. Afterwards, have the agent list its tools again — or reconnect it — so the new tools appear. In a ChatGPT workspace, an admin must also refresh and republish the app. **Symptom**: Calls fail with `429 rate_limit_exceeded`. **Likely cause**: More than 50 requests in one minute for that user and application. **Fix**: Wait the number of seconds given in the `Retry-After` header. Have the agent request fewer, larger pages instead of many small calls. Email <support@cogram.com> if the work genuinely needs a higher limit. **Symptom**: A working agent suddenly asks you to sign in again, or every call answers `401`. **Likely cause**: The refresh token expired, was revoked, or was overwritten by an older copy. **Fix**: Run the connection again — sign in and approve. For a headless agent, check that it saves the new refresh token after every refresh, and that only one process uses it. **Symptom**: The agent sees fewer projects or meetings than the user expects. **Likely cause**: The agent has exactly the user's own access. The user is not on those projects, or asset visibility hides those records from them. **Fix**: Add the user to the projects, or review [Asset Visibility](/projects/asset-visibility). Nothing about the connection itself can widen what the agent sees. **Symptom**: You need to cut off an agent that is already connected. **Likely cause**: Cogram has no per-agent disconnect screen. **Fix**: Remove the connector in the AI application that holds it. To stop every connected agent across the organization at once, turn off MCP access in [Organization Settings → Integrations](https://app.cogram.com/dashboard/settings/admin/integrations#mcp-access). ## Next steps * [Connecting AI apps](/integrations/connecting-ai-apps) — the user-facing connection steps. * [Cogram API](/integrations/cogram-api) — the REST API, for system-to-system integrations that need to write data. * [Licensing](/organization-administration/licensing) — which modules your organization is licensed for. * [Asset Visibility](/projects/asset-visibility) — how record-level visibility works. * [Agent](/agent/agent) — Cogram's own built-in agent, which needs no setup. Questions? Email <support@cogram.com> or use the in-app Help menu.