Bulk actions allow you to execute custom logic on large sets of documents. They can be triggered from all sorts of context (while browsing, on search results, during a workflow) and are meant to be used on tens of thousands of documents at once or even more. This includes offering Bulk Editing of Documents as a Bulk action.
Enabling Bulk Actions
Bulk actions were introduced to LTS 2021 with Web UI 3.0.6. To prevent bringing any breaking change through an update, you need to enable this feature explicitly by adding the following property to your nuxeo.conf file:
nuxeo.selection.selectAllEnabled=true
Bulk edit was introduced to LTS 2021 with Web UI 3.0.9. No additional property is needed to enable it, as it relies on configuration done through Studio. See how to create a bulk edit form for additional information.
Using Bulk Actions
Once enabled, users can select all documents in a result listing and execute an action on them. A selection can be done while browsing content and in the context of search results. It is possible to select all documents after using filters as well to fine-tune the results first. Note that adding filters, changing the display or the sort order for the results causes the current selection to be lost: this results in sending a different query to the server and we cannot keep track of the difference between the two without hurting performance.
Clicking on the checkbox of the header selects all documents at once, both the visible ones and the ones that are not currently displayed on screen. Clicking it again deselects all documents.
Starting from Web UI 3.0.15, it is possible to deselect documents individually. These documents won't be processed when executing the bulk action.
Available Default Bulk Actions
Once the selection is made, the following default actions are available as bulk actions:
- Add to collection
- Remove From Collection (when viewing a collection)
- Bulk Edit (if enabled using Studio configuration, see below)
- Publish
- Delete (send to trash)
- Untrash (in trash view)
- Delete permanently (in trash view)
The following default actions are NOT available as bulk actions:
- Download all as zip. This action would not be scalable. To download files in large numbers, we recommend using Nuxeo Drive instead.
- Compare. This action is handled on the client side and does not make use of the bulk action framework. Web UI and Nuxeo Server provide the capacity to compare two documents or versions at this stage.
- Add to clipboard. This action is handled on the client side and does not make use of the bulk action framework. If you want to integrate an action that allows you to do this at scale, you can take inspiration from our copy / move cookbook entry and adapt it, knowing that you can create your custom bulk actions using Nuxeo Studio.
- Move Document Up and Down (in the context of ordered folders). This would only cause useless processing since moving all documents up or down would yield the same result.
You can create additional bulk actions using Nuxeo Studio as well:
Bulk Actions Notifications Management
When launching a bulk action, a notification is updated regularly in Web UI, providing its current state and allowing the user to abort it.
A bulk action starts in the scheduled state, meaning that it is added to a queue, waiting to be executed. During that state, clicking the abort button in the notification will only remove the bulk action from the queue. No processing has happened yet.
While the action is running, clicking the abort button in the notification will stop any processing currently occurring. No rollback will happen on documents that have been already processed.
Once the action is completed, the notification will remain until the user decides to dismiss it. If an error happened, the user will be informed in the notification. Administrators can gather further information about the error from the application logs.
To avoid cluttering the UI when executing many bulk actions in parallel, three (3) notifications maximum will be displayed at a time. Each bulk action counts for one notification. If more notifications have to appear in the UI, the oldest notification will be removed.
Enabling the Default Bulk Edit Form
The default bulk edit form is disabled by default as most of our customers tend to prefer configuring custom forms instead. To enable it and its related button, you can enable the bulkEditResultsAction in the Buttons menu of Nuxeo Studio Designer.
Configuring a Custom Bulk Action
Custom bulk actions and bulk edit forms can be configured using Nuxeo Studio. For more information, please refer to our tutorials:
Questions and Answers
In Which Context Can Users Trigger Bulk Actions?
They can be launched from any results listing, e.g. when browsing a document or when doing a search.
Can I Have Multiple Bulk Edit Forms / Multiple Bulk Actions?
You can configure as many bulk actions and bulk edit forms as you desire.
On How Many Documents Can I Launch a Bulk Action?
Bulk actions were tested on sets of 150 000 documents; however there is no limit implemented in the software currently. We recommend being thoughtful when designing your bulk actions (how many documents can be impacted, how many of them could run in parallel) and considering your architecture needs.
How Do I Deal With Errors?
When an error happens, the user receives a notification once the action completes. It is possible for them to copy the error message and the bulk command id in order to contact an administrator. An administrator can have a detailed look at the situation by looking at the information related to this bulk command id.
Known Limitations
Support for One Repository at a Time
Bulk actions are compatible with documents located inside a single repository at a time at this stage.
- Using the select all functionality and triggering a bulk action will result in this action being applied only on documents located in the current repository.
- Manually selecting a range and triggering a bulk action will result in a visible error.