Map the columns of an import
Editor and above, or an API key with the import scope (ADR-026), while the import is not being
processed or committed. Each target at most once; unit is the unit a column's numbers are
written in when it differs from the field's. With preset (an import preset of the ERP
registry) the mapping is taken from the preset by the file's headers and mapping must be
empty. A validated import must be validated again.
apiKeyAuthorizationBearer <token>Organisation API key sent as Authorization: Bearer bp_live_… (ADR-017). Accepted only by the
operations that list this scheme, with the scope in their x-api-key-scope.
importId*stringuuidIf-Match*stringThe row_version the client last read, as a quoted string, e.g. "3".
^"[1-9][0-9]{0,17}"$application/json- body
Either mapping or preset; a preset maps the columns it knows by their headers.
mapping?array<>items <= 200options?preset?ImportPresetIdAn import preset of the ERP registry (getErpRegistry, ADR-026): which column header of an ERP
export maps to which registry field.
^[a-z0-9]+(-[a-z0-9]+)*$length <= 60The import.
application/json- response
Either created_by (a member uploaded the file) or created_by_api_key (an integration staged
it with an API key of scope import, ADR-026) is set.
approved_at?stringdate-timeapproved_by?stringuuidcommitted_at?stringdate-timecreated_at*stringdate-timecreated_by?created_by_api_key?An organisation API key (ADR-017) that reported an event (source api) or staged an import (ADR-026).
filename*stringformat*ImportFormat"csv""xlsx"headers*array<string>id*stringuuidmapping*array<>options*preset?ImportPresetIdAn import preset of the ERP registry (getErpRegistry, ADR-026): which column header of an ERP
export maps to which registry field.
^[a-z0-9]+(-[a-z0-9]+)*$length <= 60row_count*integerData rows (empty rows are left out).
row_version*RowVersionOptimistic-concurrency version; send it back as If-Match when updating.
int641 <= valuesample_rows*array<array<string>>The first data rows of the file as read (at most 5), to show example values while mapping.
sheet?stringThe XLSX worksheet that was read.
size_bytes*integerint64status*ImportStatusuploaded (mapping can change) → validating → validated → committing → committed;
failed when the file could not be validated (validate again). A changed mapping sends a
validated import back to uploaded.
"uploaded""validating""validated""committing""committed""failed"summary?updated_at*stringdate-timevalidated_at?stringdate-timecurl -X PUT 'https://example.com/api/v1/imports/497f6eca-6276-4993-bfeb-53cbbbba6f08/mapping' \ -H 'If-Match: string' \ -H 'Content-Type: application/json' \ -d '{}'{ "approved_at": "2019-08-24T14:15:22Z", "approved_by": "02030314-b162-4b4d-8af1-88eabdcc615d", "committed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "created_by": { "display_name": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "created_by_api_key": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string" }, "filename": "string", "format": "csv", "headers": [ "string" ], "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mapping": [ { "auto": true, "column": 0, "header": "string", "target": "string", "unit": "string" } ], "options": { "battery_model_id": "6a002912-62a3-4058-99d0-53cbf87e9e1c", "facility_id": "82d24387-b696-4928-8926-f6f7f16d3353" }, "preset": "string", "row_count": 0, "row_version": 1, "sample_rows": [ [ "string" ] ], "sheet": "string", "size_bytes": 0, "status": "uploaded", "summary": { "approved": 0, "created": 0, "duplicates": 0, "errors": 0, "not_approved": 0, "rows": 0, "valid": 0, "warnings": 0 }, "updated_at": "2019-08-24T14:15:22Z", "validated_at": "2019-08-24T14:15:22Z"}Imports of the active organisation, newest first GET
Any member, or an API key with the `import` scope (ADR-026). An import staged with a key names the key in `created_by_api_key` instead of `created_by`.
Start validating every row of an import POST
Editor and above, or an API key with the `import` scope (ADR-026). A job reads every row with the mapping, validates it with the editor's validators and finds duplicate serial numbers in the file and in the database (after removing surrounding spaces and invisible characters). Requires a serial number column and a model column or `options.battery_model_id`. Follow the import with `getImport` until its status is `validated` or `failed`.