Moving / refactoring Formatting Settings while retaining values

[JSJB]

Is it possible to move/refactor formatting settings while retaining the individual settings' values?

The settings panel in our custom visual is very bloated and not intuitively organized. We want to refactor the menu by moving settings around, renaming them, and so on.

A major concern is the persistence of settings. Our initial tests reveal that moving a setting to another slice, whether or not the capabilities.json is updated to reflect this move, will revert the settings value to default. This is problematic for us as it seems we will be severely limited in what we can do if that is the case - essentially only being able to move and refactor settings within their slice.

Is there something to do here or are we out of luck? 

Thank you in advance!

[JSJB]

Hi @dm-p ,

As always, thank you for your extremely thorough solution.

Unfortunately we tested and could conclude that what you say is true. There is unfortunately no way to comfortably migrate over.

The solution we identified to cause the fewest issues while still allowing us to migrate to the new settings panel is to have a period where the capabilities file holds both the old and new capabilities and settings, only with the old one visually hidden. We will then migrate the settings from the old menu to the new, as you propose. Thankfully we have a notification system built into our visual, so we should be able to both identify reports that have not saved their settings and warn users that they should save the report if possible, and give them some grace period to do so.

Thank you for your help.

[dm-p · Accepted solution]

Hi @JSJB,

The capabilities indeed signal to Power BI (by object and property name) which properties should be retrieved from (and persisted to) the report. Without this, you can't read or write them.

Hypothetically, if you want to move settings elsewhere, you might have to consider a migration process in your visual logic when the visual updates for the first time after the changes have been applied. This should employ some additional properties that allow you to persist some kind of version number that you can check and whether the migration process has successfully persisted the new values to the visual's objects so that it doesn't needlessly do it on each update. These wouldn't be rendered in the properties pane.

Your migration process will need to consider which version(s) you are migrating from and the necessary changes to apply, which will involve mapping existing objects and properties to their new destinations using the persistProperties API on the visual host. As part of this persistence, you should ensure that the object's version and migration status are persisted also to avoid recursively processing the migration.

The other thing to consider is that to get the old values, you will need to keep the old objects and properties in your capabilities, as well as the new ones. If the old values are not present, then you cannot migrate them. This also applies to the settings classes used to hold them, so you will need to maintain this code and update the properties shown in the pane for the user so that only the new properties are visible (and updatable).

At a suitable point in the future, you will need to determine when might be a good time to remove the old properties from your capabilities and settings classes (but bear in mind that users may not update their reports for a long time).

Note that this migration would have to run each time a report is opened in view mode, as AppSource visuals are updated from the CDN if a report edited with the older version was published. Properties are not persisted in view mode, as a manual save of the report is required to make them stick (consider them applied for the viewing session but will revert to the originally persisted properties next time the report is opened for the same or any other user).

If this is a massively limiting factor, then you may need to consider publishing your updated visual as a brand new AppSource listing, deprecate your original one and direct your users to use the new one instead. Bear in mind that due to the mismatch in capabilities between visuals, you still wouldn't have a migration process from one visual to other, but this would prevent users from losing the functionality from their original visual. Again you may want to decide if and when to remove the original listing if you no longer want to support it after a time.

Regards,

Daniel