Migration tool

When the serialization of the widgets changes or an older version of the editor has serialized widgets incorrectly, you may need to perform a migration.

If those widgets have been saved in the Resource Watch API, the widget-editor provides a command line tool (CLI) to perform the changes for you.

Table of content

• Overview
• Running a migration
• Creating migrations

Overview

The widget-editor includes an easy-to-use CLI that runs widget migrations. Once you've selected the version you want to migrate to, the CLI gives you 3 choices:

• Get the list of the widgets that need migration
• Perform a dry-run of the migration
• Perform the migration

Then, the migration tool will ask you for information such as which applications or which environments are targeted. If you want to perform the migration, you'll also have to provide your token (you need admin privileges).

Independently from which option you select in the first screen, a complete report of the action will be generated in the folder you execute the command from.

Running a migration

To run a migration, you need to clone the repository on your computer:

git clone https://github.com/Vizzuality/widget-editor.git

Then, you need to install the dependencies:

cd widget-editor
yarn

Finally, execute the following command:

$ yarn migrate

The CLI will guide you step by step to the desired action.

Creating migrations

If you want to contribute to the migration scripts, please read the contributing guide first.

Once the environment is set up, open the widget-editor/migrations/migrations.js file. You will see that it exports an array of migrations. This is where you need to make the modifications. For example, if you want to add a new migration, add a new object at the beginning of the array.

Each migration object has a specific format. Below you can find the description of each key:

Key	Description
version: string	The version of the widget editor that corresponds to this migration. Usually, a migration is needed when changes occur in the editor, thus each migration is linked to a specific version.
description: string	A brief description of what the migration does to the widgets.
needsMigration: (widget: APIWidgetPayload) => boolean	A function that receives a widget and returns whether it needs migration or not.
migrate: (widget: APIWidgetPayload) => APIWidgetPayload	A function that receives a widget to migrate and returns the widget after its migration has been performed.

If you decide to create a new migration, please make sure to make a dry run of it before permanently altering the database's data.