documentation/user_account_reconciliation.md

Rama main · réplica de lectura del repositorio original.

# User account reconciliation

It is possible to merge user accounts based on their email addresses.

Docs does not have an internal process to requests, but it allows the import of a CSV from an external form
(e.g. made with Grist) in the Django admin panel (in "Core" > "User reconciliation CSV imports" > "Add user reconciliation")

## CSV file format

The CSV must contain the following mandatory columns:

- `active_email`: the email of the user that will remain active after the process.
- `inactive_email`: the email of the user(s) that will be merged into the active user. It is possible to indicate several emails, so the user only has to make one request even if they have more than two accounts.
- `id`: a unique row id, so that entries already processed in a previous import are ignored.

The following columns are optional: `active_email_checked` and `inactive_email_checked` (both must contain `0` (False) or `1` (True), and both default to False.)
If present, it allows to indicate that the source form has a way to validate that the user making the request actually controls the email addresses, skipping the need to send confirmation emails (cf. below)

Once the CSV file is processed, this will create entries in "Core" > "User reconciliations" and send verification emails to validate that the user making the request actually controls the email addresses (unless `active_email_checked` and `inactive_email_checked` were set to `1` in the CSV)

In "Core" > "User reconciliations", an admin can then select all rows they wish to process and check the action "Process selected user reconciliations". Only rows that have the status `ready` and for which both emails have been validated will be processed.

## Merging users from the admin

Duplicate accounts can also be merged without a request: in "Core" > "Users", select the users to merge
(selecting the user to keep as well is harmless) and run the action "Merge into another user". After choosing
the user to keep, which must be active, a reconciliation is created and processed right away for each other selected
user, without any confirmation email. Users without an email cannot be merged.

The filter "duplicate email" lists the users sharing their email with another one, case ignored.

## What is transferred

Processing a reconciliation moves to the active user:

- the document accesses of the inactive user, keeping the highest role when both users had one on the same document,
- the documents created by the inactive user, soft deleted ones included,
- the invitations issued by the inactive user,
- their favorites and link traces,
- their threads, comments and reactions.

The active user is then notified by email, and the inactive user is deactivated.

## Settings

If there is a problem with the reconciliation attempt (e.g., one of the addresses given by the user does not match an existing account), the email signaling the error can give back the link to the reconciliation form. This is configured through the following environment variable:

```env
USER_RECONCILIATION_FORM_URL=<url used in the email for reconciliation with errors to allow a new requests>
# e.g. "https://yourgristinstance.tld/xxxx/UserReconciliationForm"
```