Exports
Riseact exports supporters, donations and payments to CSV or Excel: a flat table of the records that match a filter, with the columns you choose.
Principles
- You choose the columns. The initial selection matches the columns of previous exports: press Export right away and you get the usual file.
- The identifier is always there, as the first column, even if you do not select it.
- The file is downloaded from Settings > Exports. It is not sent by email.
- Only administrators download. Anyone with the export permission can request an export, but only an administrator of the organization can download the file.
- The file lasts 30 days. The export stays in the list with the filters and columns used and cannot be deleted: it is the log of who took data out of the platform.
- One export at a time per organization.
Formats and limits
| Format | Maximum rows |
|---|---|
| Excel (XLSX) | 100,000 |
| CSV | 1,000,000 |
The limit is checked when you request the export, not at the end. Above one million rows, contact technical support.
The CSV is UTF-8 with BOM (so Excel reads accented letters), comma separated.
Filters and segments
You can export all records, the ones selected by hand, the ones matching the active filters, or a saved segment.
The filters are copied into the export when you request it: changing the segment later does not affect exports already made. You can see them on the detail page.
Export models
An export model is a named selection of columns for one kind of export (supporters, donations or payments).
In the export dialog, above the columns, there is the model dropdown:
- Default fields is the initial selection;
- picking a model sets the columns to the model's;
- if you then change a column, the dropdown switches to Custom model.
Models are managed in Settings > Exports > Export models. To create one, choose kind, name and columns; with the Post-process the export switch you can attach a post-processing script. The kind cannot be changed after creation: for another kind, duplicate the model.
A model holds only columns and optionally a script, no data or filters. Editing or deleting it does not affect exports already made. The identifier column is not saved in the model, since it is always written.
Creating and editing models requires the export permission for that kind.
Post-processing scripts
A CSV export can go through a Python script you write before it is published, for example to capitalize names. See Post-processing scripts.
Column names
The file header is the column key, not the translated label, so the file is the same whatever the language of whoever exports it. Labels appear in the selection dialog and, on each export's page, in the "Name in Riseact" column.
Names follow the importer convention: lowercase, words separated by spaces. Columns
that also exist in the importer have the same name; the others carry the prefix of
their source entity (donation , campaign , payment method , payment ,
payments , last payment ).
The supporter prefix depends on the file:
- in the supporters export supporter columns have no prefix, except the statistics, which have the same name in every file;
- in the donations and payments exports all supporter columns are prefixed.
Only custom_<key> and privacy_<code> use underscores, as in the importer, and
they never have the supporter prefix, in any file.
The page of each export (supporters, donations, payments) lists every available column, with the ones selected by default.
Value formats
The same formats as the importer, so you can export, fix in Excel and re-import.
| Type | Format |
|---|---|
| Amounts | x.xx, dot as decimal separator, two decimals |
| Dates | YYYY-MM-DD |
| Date and time | ISO 8601, YYYY-MM-DDTHH:MM:SS+00:00 |
| Booleans | true / false, empty if not set |
| Tags and other multi-value fields | comma separated in the same cell |
| Enumerations (donor type, state, frequency) | the stored value, not the label |
Booleans are no longer SI / NO as in the old exports: the importer does not
accept them.
Re-importing an exported file
It works for the supporters export, if it contains only columns the importer
knows (listed in Imports). An unknown column makes the
upload fail. Identifier columns (id, supporter id, donation id) can stay: the
importer ignores them.
Donations and payments exports cannot be re-imported as they are: supporter
columns are prefixed and the donations importer does not recognize them. Only the
donation columns match (campaign name, donation external ref, payment method,
amount, payment date, donation tags). Also, the payments file has one row per
installment, while the importer creates one donation per row.
No results
A search with no results produces a completed export with only the header row.
From the API
Exports can also be made through the API, with the same rules and permissions as the platform: requesting one needs the export permission of the kind, listing the exports and downloading the file needs an administrator.
| Operation | REST (/admin/api/v1/exports/...) | GraphQL |
|---|---|---|
| Available columns | GET /{kind}/fields | supporterExportFields, donationExportFields, paymentExportFields |
| Request an export | POST /{kind}/ | supporterExportCreate, donationExportCreate, paymentExportCreate |
| List the exports | GET / | exportRuns |
| State of an export | GET /{id} | exportRun |
| Download the file | GET /{id}/download | downloadUrl of ExportRun, with __access_token |
| Models of a kind | GET /{kind}/models | supporterExportModels, donationExportModels, paymentExportModels |
| One model | GET /models/{id} | exportModel |
| Create, update, delete a model | POST /models/, PUT /models/{id}, DELETE /models/{id} | exportModelCreate, exportModelUpdate, exportModelDelete |
{kind} is supporters, donations or payments. The keys to pass in fields are
the ones in the Column column of each export's page, or the ones returned by
"Available columns".
The flow is always the same: request the export, which comes back straight away in
PENDING state; poll its state until it is COMPLETED (or FAILED, with the reason
in error_code and error_message); download the file. Enumerations (SUPPORTERS,
CSV, PENDING...) have the same values in REST and GraphQL.
In REST the filters go in filters, with the same keys as the GraphQL filters
input (SupporterFilters, DonationFilters, PaymentFilters), in camelCase or
snake_case. Alternatively pass the ids in ids or a segment in segment_id.
Validation errors come back with status 422 and the same list of code, field
and message as the GraphQL userErrors.
The details of each call are in the REST and GraphQL references.