89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
# Converting Open Collective CSV
|
|
|
|
Here are notes on Open Collective's CSV (as of 2025-12, based on hledger's open collective).
|
|
|
|
On the Transactions screen, first remove any filters so that all transactions will be exported, including:
|
|
|
|
- Contribution (incoming or outgoing)
|
|
- Expense
|
|
- Host fee
|
|
- Payment processor cover
|
|
- Payment processor fee
|
|
|
|
Eg: <https://opencollective.com/hledger/transactions?kind=ALL>
|
|
|
|
When you click the Export CSV button, two CSV formats are offered:
|
|
|
|
- Legacy Platform Default (Pre-2024) (we'll call it Legacy)
|
|
- Platform Default (we'll call it Default)
|
|
|
|
Each has three options:
|
|
|
|
- Selected fields for export - about 25 reorderable fields; we'll assume the default order.
|
|
(It says "out of 85", suggesting there might be more available, but if so they're not accessible to a normal collective admin.)
|
|
- Use field IDs as column headers instead of field names - normally on for Legacy and off for Default.
|
|
- Export taxes and payment processor fees as columns - ditto.
|
|
|
|
Additionally, the data available varies by era:
|
|
|
|
- Host fee records start in 2021-06.
|
|
- With the "as columns" option on, payment processor fees are available for all eras. Otherwise, processor fee records start in 2024-01.
|
|
- Payment processor cover records start in 2024-01.
|
|
|
|
In eras where fees are not available, contribution amounts can be under-reported.
|
|
Eg, a $10 contribution with a $1 host fee and $0.59 payment processor fee might be reported as just a $8.41 contribution.
|
|
|
|
Here are the formats we provide rules for, and their limitations:
|
|
|
|
| format | accurate contribution amounts? | host fees? | processor fees? | processor covers? | balances? | notes | rules file |
|
|
|---------------------------|-------------------------------------|---------------------------------------|-----------------|-------------------|---------------------|---------------------------------------------|------------------------------|
|
|
| Legacy | yes | from 2021/06 (inferrable before then) | yes | from 2024 | yes; some are wrong | provides the most data across all eras | opencollective-legacy.rules |
|
|
| Default + fees as columns | from 2024 (inferrable from 2021/06) | from 2021/06 | yes | from 2024 | no | simplest if you have no data before 2021-06 | opencollective-columns.rules |
|
|
| Default | from 2024 | from 2021/06 | from 2024 | from 2024 | no | simplest if you have no data before 2024 | opencollective-default.rules |
|
|
|
|
Note to get accurate pre-2024 contributions and fees, or balance information, the Legacy format is needed.
|
|
opencollective-legacy.rules is the best-tested of these rules files.
|
|
|
|
## How to test your conversion
|
|
|
|
### CSV balance column
|
|
|
|
If you are using the legacy format, you can use the balance column to generate hledger balance assertions.
|
|
Though in some record types (eg contributions after 2021-06, and expenses) the balance values may be out of sequence; those should be ignored.
|
|
|
|
Then, hledger should agree with Open Collective's balances; check with `hledger check assertions` or `hledger check -s`.
|
|
|
|
### Budget stats
|
|
|
|
In the Budget section on the collective's page (eg <https://opencollective.com/hledger#category-BUDGET>),
|
|
you can see some calculated values (and a few more if you mouse over), listed below.
|
|
Some of these can be reproduced by the hledger reports shown.
|
|
(If you have used the legacy format and the provided rules; or if your data begins in 2024 or later.
|
|
Tested with the hledger collective.)
|
|
|
|
#### Today's balance
|
|
|
|
`hledger bs`
|
|
|
|
#### Total consolidated including Projects and Events
|
|
|
|
#### Total raised
|
|
|
|
`hledger is not:disbursed` *? not reproduced yet*
|
|
|
|
#### Total contributed before fees
|
|
|
|
`hledger is revenues`
|
|
|
|
#### Total disbursed
|
|
|
|
`hledger is disbursed` *? not reproduced yet*
|
|
|
|
#### Estimated annual budget
|
|
|
|
#### Monthly recurring
|
|
|
|
#### Total received in the last 12 months
|
|
|
|
`hledger is revenues -b $(date -I -d '-12 months')`
|