---
title: "Documents"
description: "Files and folders. A register of business documents with folder, kind, owner, expiry and confidentiality."
canonical: "https://obop.dev/apps/documents/"
lang: "en"
---

# Documents

## What it is for

A register of business documents with folder, kind, owner, expiry and confidentiality. It stores references to documents, not the file contents.

## What the package does and does not do

A register of business documents: folders, document records with kind, owner, expiry and confidentiality, and a draft, published and archived flow. It stores references and, when you upload one, the file itself. Confidentiality is enforced: confidential and restricted documents are visible only to their owner and to documents.manager; public and internal ones to everyone who may read documents.

## Module details

- **Version:** `0.3.0`
- **Author:** SpaceCorps
- **Licence:** [AGPL-3.0-or-later](https://spdx.org/licenses/AGPL-3.0-or-later.html)
- **Needs core:** `^0.2` (core 0.2.0 is current)
- **Maturity:** Beta
- **Categories:** Productivity

## Models

### `documents_folder`

A folder that groups documents

Read group: `documents.user`. Write group: `documents.manager`.

| Field | Kind | Data class | Personal data | Group | Agents see | Description |
|---|---|---|---|---|---|---|
| `name` | text | `none` | no | `documents.user` | in clear | Folder name |
| `parent_id` | ref → documents_folder | `none` | no | `documents.user` | in clear | The folder this one sits in |
| `description` | longtext | `none` | no | `documents.user` | in clear | What belongs in the folder |

### `documents_document`

A contract, policy, certificate or other document on record

Read group: `documents.user`. Write group: `documents.user`.

| Field | Kind | Data class | Personal data | Group | Agents see | Description |
|---|---|---|---|---|---|---|
| `title` | text | `none` | no | `documents.user` | in clear | Document title |
| `folder_id` | ref → documents_folder | `none` | no | `documents.user` | in clear | The folder the document is filed in |
| `kind` | select (contract, invoice, policy, report, certificate, other) | `none` | no | `documents.user` | in clear | Type of document: contract, invoice, policy, report, certificate, other |
| `confidentiality` | select (public, internal, confidential, restricted) | `none` | no | `documents.user` | in clear | Who may see it: public and internal documents everyone who may read documents, confidential and restricted ones only the owner and documents.manager |
| `open_to_all` | bool | `none` | no | `documents.user` | in clear | Whether everyone who may read documents can see this one: true for public and internal documents |
| `owner` | text | `internal` | yes | `documents.user` | masked | User name of the person responsible for the document; the person who creates it unless set otherwise. Owners see their confidential documents |
| `reference` | text | `none` | no | `documents.user` | in clear | Reference number, for example a contract number |
| `location` | text | `none` | no | `documents.user` | in clear | Where the file is stored, such as a link or archive box |
| `attachment` | file | `internal` | no | `documents.user` | in clear | The document file itself (PDF, image, text, spreadsheet or office document, up to 25 MiB); served only as a download to people who may read the record |
| `expires_on` | date | `none` | no | `documents.user` | in clear | Date after which the document is no longer valid (YYYY-MM-DD) |
| `summary` | longtext | `none` | no | `documents.user` | in clear | What the document says, in a few lines |
| `state` | select (draft, published, archived) | `none` | no | `documents.user` | in clear | Document status: draft, published, archived |

## Workflows

### `documents_document`

| Action | Moves | Who may run it | Approval |
|---|---|---|---|
| `documents_document.publish` | state: draft → published | `documents.user` | no |
| `documents_document.archive` | state: published → archived | `documents.manager` | no |

## Permission groups

Groups used by this app:

- `documents.manager`
- `documents.user`

## Approval steps

No step in this app needs an approval, apart from deleting records.

## What agents can and cannot do

An agent can read, search, create and update records of this app, and run the actions that need no approval, within the permission groups of its token.

It can only propose these steps, and a person must approve them: `documents_folder.delete`, `documents_document.delete`.

Personal data is masked as placeholder tokens: `documents_document.owner`.

## Dependencies

None.

## Install

Install it from the Customize app (Marketplace), or from the command line:

```bash
obop modules install-from documents
```

Needs a database and administrator rights.

## Build your own

[The module guide shows how apps like this one are written](/docs/reference/module-manifest/)