Permissions and plugin events
v0.0.3
This page lists the permissions that gate the migration and the events an import fires. A permission decides who can start and follow a run, and who can write each kind of record. An event lets a plugin convert a piece of content, change or skip an item, or react when an import ends.
What it moves and how it works, on one page: Mishka CMS Migration.
Permissions of the migration
| Permission | Opens |
|---|---|
admin:dashboard:migration | Reading, creating, starting and cancelling a run in the admin, and a run's Items page. |
admin:api:migration | The same over the admin API. |
Setting the extension up on a site creates both names. A run belongs to a site. A master reaches the runs of every site, and a site admin only their own site's. See Sites, masters and global records.
Permissions an import needs
An import writes each record as the admin who pressed Import, so the CMS's policies decide. A kind the admin may not write is skipped with You may not change and the kind's name. The permission for each kind is in What moves where. A wildcard such as admin:dashboard:blog:* covers the Blog's. See Permission names.
Events
An import fires three Mishka Installer events. A dry run fires none of them, because it writes nothing and asks no plugin. Each event carries the run it belongs to and a meta map with the actor and the site.
| Event | Fired | A plugin can |
|---|---|---|
migration:content:convert | For each piece of an item's content the source could not convert, before the item is written. The payload holds the piece's name, attrs and raw text, and html, starting nil. | Answer with html set to the markup the piece becomes. A piece nobody converts is kept as escaped text. |
migration:item:before_import | For each item about to be written, after its content is converted. The payload holds the item, the outcome the import will record, :created or :updated, and a reason. | Answer with a changed item, or with outcome: :skipped and a reason to leave the item out. The kind and source_id stay as they were. |
migration:import:finished | Once an import is done and its run is saved. The payload holds the run's report with its counts, kinds and entries. | React, for example to notify a team. What a plugin answers is not used. |
The first two events decide what is written, so they fail closed. When one of their plugins raises, or answers something other than a reply, the plugins after it do not run, and the item is skipped as A plugin failed on it. While one of the plugins of an event is not loaded, the item is skipped as A plugin it needs is not loaded. Either way nothing is written behind a plugin that would have changed the item. See Mishka Installer documentation for how to write a plugin.