Rolling back nodes and media
In the create
and create_from_files
tasks, Workbench generates a configuration file and accompanying input CSV file in the format described in "Deleting nodes" documentation. These files allow you to easily roll back (i.e., delete) all the nodes and accompanying media you just created. Specifically, this configuration file defines a delete
task. See the "Deleting nodes" section for more information.
Warning
The rollback configuration file contains the username and password used in the create
or create_from_files
task that generates it.
By default, the configuration file is named "rollback.yml" and is written into the Workbench directory. The input CSV file is named "rollback.csv" and is written into the directory defined in your input_dir
configuration setting. If either of these files exist, they are overwritten during the next create
or create_from_files
task.
To roll back all the nodes and media you just created, run ./workbench --config rollback.yml
.
There are several configuration settings that let you control the names of these two files, and there is also an option to include comments in the files.
Note
When secondary tasks are configured, each task will get its own rollback file. Each secondary task's rollback file will have a normalized version of the path to the task's configuration file appended to the rollback filename, e.g., rollback.csv.home_mark_hacking_islandora_workbench_example_secondary_task
. Using these separate rollback files, you can delete only the nodes created in a specific secondary task.
Setting the directory where the rollback CVS file is written
You can determine where the rollback CSV file is written by including the rollback_dir
in your configuration. This overrides the default location defined in input_dir
.
The rollback configuration file is always written to the Workbench working directory.
Using rollback filename templates
For both the rollback config file and the rollback CSV file, you can define a template that provides two placeholders, $config_filename
and $input_csv_filename
, which contain the names of the create
(or create_from_files
) configuration file and the name of the input CSV file used in create
tasks. You can embed these two placeholders in your template, which is then used to create the names of the two files. The templates for the two filenames are defined in two separate configuration settings:
For the rollback configuration file:
rollback_config_filename_template: my-custom_filename_$config_filename_$input_csv_filename
Assuming the configuration file for the create
task that generates this rollback configuration has the name "mjtest.yml", and the input_csv
filename has the filename "sample.csv", this template will result in a configuration file named my-custom_filename_mjtest_sample.yml
. Note that the ".yml" extension is added automatically; you do not need to include it in your template.
For the rollback CSV file:
rollback_csv_filename_template: my_custom_rollback_filename_$config_filename_$input_csv_filename
Using the same create
task configuration filename and input CSV filename as in the previous example, this template will result in a CSV file named my_custom_rollback_filename_mjtest_sample.csv
. The ".csv" extension is added automatically; you do not need to include it in your template.
Warning
Python's built-in templating system has a quirk where when a character that is valid in a Python variable name follows a template placeholder, that character is added to the template placeholder. If this happens to you, Workbench will exit with the error message "One or more parts of the configured rollback configuration filename template ([your template here]) need adjusting."
You can work around this behavior by wrapping your template variable in {}
. The example rollback config filename template above (my-custom_filename_$config_filename_$input_csv_filename
) will trigger this error because the _
following the $config_filename
placeholder is valid in Python variable names. If you see this type of message, adjust your template to my-custom_filename_${config_filename}_$input_csv_filename
.
Adding a timestamp to the rollback filenames
By default, Workbench overwrites the rollback configuration and CSV files each time it runs, so these files only apply to the most recent create
and create_from_files
runs. If you add timestamp_rollback: true
to your configuration file, a (to-the-second) timestamp will be added to the rollback.yml
and corresponding rollback.csv
files, for example, rollback.2024_11_03_21_10_28.yml
and rollback.2024_11_03_21_10_28.csv
. The name of the CSV is also written to workbench.log
. Running ./workbench --config rollback.2024_11_03_21_10_28.yml
will delete the nodes identified in input_data/rollback.2024_11_03_21_10_28.csv
.
Timestamps are added in the same way to custom rollback configuration and CSV filenames create using templates.
Adding custom comments to your rollback configuration and CSV files
Workbench always adds to lines of comments to rollback configuration and CSV files, indicating when the files were generated and the names of the configuration and input CSV files they were generated from, like this:
# Generated by a "create" task started 2024:11:10 09:52:57 using
# config file "mjtest.yml" and input CSV "sample.csv".
You can add additional, custom comment lines by including the rollback_file_comments
configuration setting in your create
or create_from_files
configuration, like this:
rollback_file_comments:
- Keep this file! It might be useful if something goes wrong with this job.
- Have a nice day!
This will result in the following comments in your rollback configuration and CSV files:
# Generated by a "create" task started 2024:11:10 09:52:57 using
# config file "mjtest.yml" and input CSV "sample.csv".
# Keep this file! It might be useful if something goes wrong with this job.
# Have a nice day!