dataroomHQ

View saved version →

---
name: generating-reports
description: Use when asked to produce, check on, read, file or delete a data room's generated report - an investment memo, pitch deck, business report, data deck, category summary or the company profile. Covers that generation is asynchronous and the order of calls from generating one to saving it into the room.
---

# Generating reports

The generator descriptions cover each kind and its arguments; this covers
the order of calls and what not to do while one runs.

## BEFORE GENERATING

A memo, business report, board deck or company profile may already be on its
way: a room created with a website builds them itself. If `get_dataroom`'s
`onboarding_status` is `IN_PROGRESS` or `DOCUMENTS_READY`, don't generate
those - wait for the room's own.

## THE SEQUENCE

1. `generate_<kind>` - returns at once; nothing is finished.
2. `list_generated_reports` - each report's `id` and generation status.
3. `read_generated_report(kind, report_id)` - once it is ready.
4. `copy_generated_report_to_documents(kind, report_id)` - files it into the
   room's documents.

## WHILE IT RUNS

- Tell the user it is running and let them come back. Generation takes
  minutes.
- Don't loop on `list_generated_reports` waiting for a status to change.
- Don't call a generator again because nothing appeared - a second call
  starts a second report.
- Don't say a report is ready without checking `list_generated_reports`.

## DON'T

- Don't delete a report to retry it. A new `generate_<kind>` call is the
  retry; deleting first only loses the old one.
- A refusal naming the plan means the feature is not in the room's plan. Say
  so and stop - don't reach for a different kind instead.

View saved version →

---
name: setting-up-a-dataroom
description: Use when creating a new data room and getting it ready - creating it, adding its documents, and having its reports produced. Covers the order to do it in, and the reports a room produces on its own so you don't generate them a second time.
---

# Setting up a data room

## THE SEQUENCE

1. `create_dataroom` with the company's `website_url`.
2. Upload the documents.
3. Let the room produce its reports.
4. Share it.

When `onboarding` in step 1's reply is `started`, steps 2 and 3 are linked:
the memo, business report and board deck are built only once every uploaded
document has finished processing. Uploading is what moves it forward; a room
with nothing uploaded waits indefinitely.

## WHILE THE ROOM PRODUCES ITS OWN REPORTS

While `get_dataroom`'s `onboarding_status` is `IN_PROGRESS` or
`DOCUMENTS_READY`, don't call `generate_memo`, `generate_business_report`,
`generate_data_deck` or `generate_company_profile`. Each starts a second
report alongside the one the room is already building.

Tell the user they are on the way. Once it is `COMPLETED`, they are in
`list_generated_reports`.

If `onboarding` was anything but `started`, or the status is `FAILED` or
null, nothing is coming - generate what the user asks for.

View saved version →

---
name: sharing-a-dataroom
description: Use when giving someone access to a data room or to particular documents in it, changing or removing access they already have, or explaining what a role or member can currently see. Covers which tools to combine for each kind of grant, and how roles, overrides, hidden folders and links interact.
---

# Sharing a data room

Grant the narrowest access that satisfies the request. The tools' own
descriptions cover each call; this covers how they combine.

## CHOOSING THE GRANT

- Specific files -> a document share; the recipient sees only those files.
  - One file: `share_document`.
  - Several files, one link: `create_role(hidden=True)` -> one
    `set_document_override` per file -> `create_share_link(role_id=...,
    email=...)`. One link, not several. Leave `keep_watermark` at its
    default on each override; it matches `share_document`'s.
- The whole room -> `invite_member` (a participant) or `create_share_link`
  (an email invite carrying a role).
- A role with nobody to send it to -> `create_role`, plus an override per
  file if it should reach only some. Leave `hidden` off: it belongs in the
  role picker. `hidden=True` is only for the throwaway role behind a
  document share.
- Changing what someone has -> `assign_role`, or a new role shaped with
  `create_role` + overrides.

## BEFORE CREATING ANYTHING

- `list_members` first. If they already have access, say so rather than
  creating a duplicate; if they are a member, ask before changing their role.
- If they already hold a document share (`list_document_shares`), add the new
  file to that share's role with `set_document_override`. It appears on the
  link they already have.

## HOW THE PIECES INTERACT

- A document share works because `create_role` starts with `doc_view` off
  and each override then opens one file. Turning `doc_view` on to share a
  few files hands over the whole room, including documents added later.
- Claiming several document links MERGES their grants, and a full-access
  role always beats a hidden one. A smaller link cannot narrow access - to
  reduce it, change the role.
- A role grants nothing until a link or a member points at it.
- To withhold one document from a role that sees everything, set an override
  with `can_view=False`. Removing an override is a different act: it
  restores the role's blanket rule for that file.

## REPORTING WHAT SOMEONE CAN SEE

Read it from the role's flags, its overrides (`get_role`) and its hidden
folders together. Any one alone gives the wrong answer: an override changes
the blanket rule per file, and a hidden folder beats both.

## DON'T

- Don't send a second, smaller link to reduce access.
- Sharing emails the recipient by default. Say so when reporting back; pass
  `notify=False` only when asked to share quietly.