Edit in bulk with Excel
Editors often need to change many entities at once: new prices for a season, translated names for a new market, or a custom action for a few hundred products. Vox lets them export a selection to an Excel workbook, edit it in Excel and import it again. The import is checked and previewed before any entity is changed, and every change runs through the entity's normal actions, validation and permissions.
Excel export and import work for entity types that Vox owns (IVoxEntity). External entities are changed through
their import API instead. You need permission to run at least one action of the entity type.
Export a selection
- Select entities in the list. Tick the rows you want, or select every entity that matches the current filters and search, and untick the ones to leave out.
- Choose Export Excel. Ordinary editable properties are included automatically: one column per field, and one
column per field of an object, eg
Pricing / List price. - Choose the context values. For a property that varies by context, you get one column per selected member, eg
one column per language or market, and
Invariant (*)for the value that applies everywhere. Leave out the languages or markets you don't edit to keep the workbook small. - Choose custom actions, if any. A selected custom action gets a
Run?column and one column per field of its command. The action only runs for rows whereRun?is true. - Choose how blank custom-action cells are treated: Ignore them, or Send an empty value.
The workbook has an Entities sheet with two header rows, the ID and version of each entity, and the editable
columns. It also has two hidden sheets, _vox_baseline and _vox_manifest, which Vox uses when you import. Don't
delete them, and don't add, remove or reorder columns.
Edit in Excel
Change the cells you want to change. Only the cells that differ from the exported values are imported, so you can leave the rest as they are. Clearing a property cell clears that value. A context column only changes its own context, eg the Swedish name, and never the other languages.
Import the workbook
- Choose Import Excel in the list of the same entity type, and choose the workbook.
- Check the preview. Vox reads the workbook and shows how many entities and actions it would change, row by row, without saving anything.
- Confirm the import. The admin saves every change together: either all entities are saved, or none of them.
For an entity type that uses drafts, the changes are saved where you're working in the admin, eg in a draft or a content release. Other entity types are saved directly.
Conflicts and validation
Every row carries the version of the entity when it was exported. If someone has changed an entity since, the import is rejected with a version conflict instead of overwriting their change. Export again and redo your changes.
Each change runs the entity's normal actions, so validation, unique values, permissions and history apply exactly as when you edit one entity. A field you aren't allowed to change can't be changed through Excel either.
Limits
| Limit | Value |
|---|---|
| Entities per workbook | 10,000 |
| Workbook size | 25 MB |
| Columns | Excel's limit of 16,384. Select fewer contexts if you reach it. |
Use the API
The admin uses three endpoints, which you can call from your own tools.
Export a selection to a workbook:
POST /api/products/batch/excel/export
Content-Type: application/json
{
"selection": { "ids": ["1001", "1002"] },
"valueContexts": { "Language": ["sv", "en"] },
"actions": ["Discontinue"],
"blankMode": "Ignore"
}
Instead of ids, a selection can use "allMatching": true with the list's filters and search, and excludedIds
for the entities to leave out.
Import a workbook as multipart/form-data with the file in file:
POST /api/products/batch/excel/import?dryRun=true
| Query parameter | Meaning |
|---|---|
dryRun | true returns the preview without saving. |
mode | Atomic (default) saves every entity or none. PerEntity saves each entity on its own and returns the errors per row. |
blankMode | Overrides the workbook's treatment of blank custom-action cells: Ignore or Clear. |
scope | Where to save, eg draft. Without it, the workbook's own scope is used. |
waitForSearchIndex | Wait until the changes are searchable before responding. Default true. |
Run actions on many entities without a workbook:
POST /api/products/batch/actions
Content-Type: application/json
{
"mode": "Atomic",
"items": [
{ "id": "1001", "version": 7, "actions": [{ "action": "SetName", "values": { "name": "Coffee mug" } }] },
{ "id": "1002", "version": 3, "actions": [{ "action": "Discontinue", "values": {} }] }
]
}
The response has one result per item, with the saved entity or its error.