-
Notifications
You must be signed in to change notification settings - Fork 15
Upgrade scripts
Over time you will add new functionality to your module. Sometimes, this can involve changing how existing actions or feedbacks are implemented.
A common example is changing a on/off option to be an on/off/toggle option.
When this happens, existing usages of the action or feedback will become broken. The job of the upgrade script is to fix up the actions and feedbacks to handle the changes.
Each upgrade script will only get run once for each action and feedback, but it is good practise to write the scripts so that they can be executed multiple times. This will help you when testing your script, or if jumping between versions of companion.
It is recommended to put them in an upgrades.js
file, and to import them into index.js
with the following:
const upgradeScripts = require('./upgrades')
The second parameter to the runEntrypoint()
method in your index.js
is an array of upgrade scripts. So it should be added there
It is intentional that the script is a method that is unrelated to your Instance class. They previously were part of the class, but that limtied when they could be run and could lead to unpredictable behaviour that depended on the current state of the class.
A minimal example of a script is:
module.exports = {
example_conversion: function (context, props) {
const result = {
updatedConfig: null,
updatedActions: [],
updatedFeedbacks: [],
}
// write your script in here
return result
},
// more will be added here later
}
The script gets fed the bits of data you may need to do the upgrades.
This is a collection of methods that may be useful for your script. There aren't currently any, some will be added here later on
This is all the data that needs upgrading. It contains a few properties
Sometimes, the config of your module may be provided here, in case it needs upgrading.
You can change anything you like here. To save the change, set the new value as updatedConfig
in the result.
Warning: Often this value will be null. Make sure you don't throw an error when that happens!
This is an array of the actions that may need upgrading to the new version.
Note: This may not be all of the actions that exist. Sometimes it will be called with actions that have been imported from a page from an older version of companion
Any changed actions should be added to the updatedActions
array in the result.
This is an array of the feedbacks that may need upgrading to the new version.
Note: This may not be all of the actions that exist. Sometimes it will be called with actions that have been imported from a page from an older version of companion
Any changed feedbacks should be added to the updatedFeedbacks
array in the result.
This tells Companion what had changed in your script. Anything changes made to actions or feedbacks not listed in the result object will be discarded.
Getting Started
- Home
- Module development 101
- Git crashcourse
- Upgrading a module built for Companion 2.x
- Companion module library versioning
- Releasing your module
Development
- File Structure
- manifest.json
- Logging
- Module packaging
- Actions
- Feedbacks
- Presets
- Input Field Types
- Module configuration
- Upgrade scripts
- Variables
Code quality
Advanced functionality