- Implement tests for `isOrgAdminProvider` to validate admin roles based on organization membership and role. - Create tests for `saved_views_provider` to ensure correct API interactions for saving, renaming, and deleting saved views. - Enhance ticket tree tests to accurately reflect inactive and merged ticket handling. - Update CSV import tests to verify error handling and file saving functionality. - Introduce tests for deal cards to ensure correct display of next steps and task statuses.
88 lines
5.9 KiB
Markdown
88 lines
5.9 KiB
Markdown
# CSV exports
|
|
|
|
Six lists download as a CSV file: leads, contacts, accounts, deals, tickets and invoices. Each is a
|
|
`GET` under the list's own root, served by a subclass of `RecordExportView`
|
|
(`backend/common/csv_export.py`). See [Conventions](conventions.md) for the query-string rules the
|
|
lists share and [Errors](errors.md) for the shapes a refusal comes back in.
|
|
|
|
| Endpoint | View | File name | Rows come from |
|
|
| --- | --- | --- | --- |
|
|
| `GET /api/leads/export/` | `LeadExportView` (`leads/views/export_views.py`) | `leads-YYYY-MM-DD.csv` | `lead_list_queryset` (`leads/views/lead_views.py`) |
|
|
| `GET /api/contacts/export/` | `ContactExportView` (`contacts/export_views.py`) | `contacts-YYYY-MM-DD.csv` | `contact_list_queryset` (`contacts/views.py`) |
|
|
| `GET /api/accounts/export/` | `AccountExportView` (`accounts/export_views.py`) | `accounts-YYYY-MM-DD.csv` | `account_list_queryset` (`accounts/views.py`) |
|
|
| `GET /api/opportunities/export/` | `DealExportView` (`opportunity/views/export_views.py`) | `deals-YYYY-MM-DD.csv` | `deal_list_queryset` (`opportunity/views/opportunity_views.py`) |
|
|
| `GET /api/cases/export/` | `CaseExportView` (`cases/export_views.py`) | `tickets-YYYY-MM-DD.csv` | `case_list_queryset` (`cases/views.py`) |
|
|
| `GET /api/invoices/export/` | `InvoiceExportView` (`invoices/export_views.py`) | `invoices-YYYY-MM-DD.csv` | `filter_invoices` over `visible_invoices_qs` (`invoices/api_views.py`) |
|
|
|
|
The date in the file name is the day in the org's timezone (`export_filename`).
|
|
|
|
## Who may export, and which rows
|
|
|
|
Any member of the org may export (`permission_classes = (IsAuthenticated, HasOrgContext)`), and
|
|
gets exactly the rows the matching list would show them for the same query string, every page of
|
|
it. That holds because each export's `get_queryset` calls the function its list view builds its
|
|
queryset with, the one named in the table above, and never filters on its own. So the read rule
|
|
that hides a colleague's lead from a member on `GET /api/leads/` hides it from their file too, and
|
|
a ticket the caller cannot open is not in `tickets-*.csv`.
|
|
|
|
For personal access tokens and the organization API key the export is part of the list's resource:
|
|
`GET /api/leads/export/` needs `leads:read`, the same scope as `GET /api/leads/`
|
|
(see [Tokens and API keys](tokens-and-api-keys.md#scopes)).
|
|
|
|
## Query parameters
|
|
|
|
An export takes its list's query parameters, with the list's meaning, and ignores paging: `limit`
|
|
and `offset` do not narrow a file, which always holds every matching row. For example,
|
|
`GET /api/cases/export/?status=New&status=Pending&priority=High` writes every high-priority ticket
|
|
in New or Pending that the caller can see. The parameters each list reads are listed on its own page
|
|
([Leads](leads.md#list-leads), [Contacts](contacts.md), [Accounts](accounts.md),
|
|
[Opportunities](opportunities.md), [Cases](cases.md), [Invoices and estimates](invoices.md)), and
|
|
are the same set a [saved view](saved-views.md) may hold.
|
|
|
|
Two lists answer in halves that a file does not have, so the half is named in the query instead:
|
|
|
|
- Leads: the list returns open and closed leads separately. `?open=true` exports only the open
|
|
ones, which is what the web list shows; without it both halves are written.
|
|
- Accounts and contacts: `?is_active=true` or `?is_active=false` exports one half. Without it,
|
|
active and inactive rows are both written.
|
|
|
|
A malformed filter value (an id that is not a UUID, a day that does not exist, a number that is not
|
|
a number) is a `400` naming the parameter, returned before any byte of the file:
|
|
|
|
```json
|
|
{"assigned_to": ["'x' is not a valid id."]}
|
|
```
|
|
|
|
## The response
|
|
|
|
A `200` is a streamed `text/csv; charset=utf-8` body with
|
|
`Content-Disposition: attachment; filename="<prefix>-<YYYY-MM-DD>.csv"`. Send `Accept: text/csv`
|
|
or no `Accept` at all; both are served (`CSV_RENDERERS`, `common/renderers.py`). The file:
|
|
|
|
- starts with a UTF-8 byte-order mark, so Excel reads accented names correctly;
|
|
- has one header row, then one row per record, in the list's own order;
|
|
- writes people as their email address and several values in one cell as a `; `-separated list
|
|
(owners, tags, linked accounts);
|
|
- writes dates as `YYYY-MM-DD` and timestamps as ISO 8601 in the org's timezone;
|
|
- prefixes any text cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return (also
|
|
after leading spaces) with `'`, so a record named `=HYPERLINK(...)` is text in a spreadsheet
|
|
rather than a formula (`safe_cell`). Numbers the server formats are written as they are.
|
|
|
|
The body is generated while it streams, after the request's middleware has finished, so the view
|
|
sets the org's row-level security context and timezone again for exactly as long as it runs
|
|
(`csv_response`).
|
|
|
|
## Columns
|
|
|
|
| File | Columns |
|
|
| --- | --- |
|
|
| Leads | ID, First name, Last name, Company, Job title, Email, Phone, Status, Source, Rating, Industry, Amount, Currency, Probability, Close date, Last contacted, Next follow-up, City, Country, Assigned to, Tags, Created |
|
|
| Contacts | ID, First name, Last name, Email, Phone, Title, Department, Organization, Account, Linked accounts, City, State, Country, Do not call, Active, Assigned to, Tags, Created |
|
|
| Accounts | ID, Name, Industry, Email, Phone, Website, City, State, Country, Employees, Annual revenue, Currency, Active, Assigned to, Tags, Created |
|
|
| Deals | ID, Name, Account, Pipeline, Stage, Amount, Currency, Probability, Close date, Type, Lead source, Assigned to, Tags, Created |
|
|
| Tickets | ID, Subject, Status, Priority, Type, Account, Assigned to, Tags, Created, First response, Resolved, Closed on |
|
|
| Invoices | ID, Number, Title, Status, Account, Client name, Client email, Issue date, Due date, Total, Paid, Due, Currency, Assigned to, Created |
|
|
|
|
Choice fields are written as their labels (`In Process`, not `in process`), and a deal's stage as
|
|
the label of that stage in the deal's own pipeline. The column lists are the `columns` method of
|
|
each view; those are the source of truth if this table and a file ever disagree.
|