Key-Value Storage

The key-value storage feature provides configurable named string values that are maintained by an administrator in the OmniFi Administration application, and are transparent to the end user.

Storage values are stored in the OmniFi database of the current system, which means that different values can be configured per system. This makes it useful for storing values that vary between different instances of a target system, for example API URLs.

Enable the Key-Value Storage feature

To enable the Key-Value Storage feature, configure it in the extension .pyplugin or .netplugin header file:

Features=KvStorage

In the same header file, declare the required storage keys:

StorageKey=API_URL

You can include as many storage keys as needed:

Features=KvStorage
StorageKey=API_BASE_URL
StorageKey=API_SLUG

Storage values are transparent to the user, which means they are suitable for information that the user shouldn't have access to, e.g. API tokens and organization keys. To further enhance protection of these values they can be declared as secret, further enhancing security by blanking them in OmniFi Administration and storing them encrypted in the OmniFi database. To declare a secret storage value, add the secretkeyword to the declaration:

Features=KvStorage
StorageKey=API_URL
StorageKey=API_KEY secret

📘

The same storage keys can be required by several extensions. If these extensions are installed in the same folder structure, the administrator can chose to supply a single storage value for that key on the common root folder of those extensions. This is very useful for extension packages that supply several extensions based on the same underlying API/system, but if multiple packages require the same storage key, e.g. API_URL, there is a risk that the appropriate values are manually mixed up between the different packages.

If you are supplying an extension package for a system, consider introducing a unique prefix for the package, e.g. StorageKey=XY_API_URLto avoid confusion.

Implement the Key-Value Storage feature

Storage values are provided to the extension by implementing the SetKvStorageValues()method. When key-value storage is enabled, this method is called once immediately after the constructor every time the extension is instantiated.

def SetKvStorageValues(self, StorageValues):
    self.api_url = StorageValues["API_URL"]
    self.api_token = StorageValues["API_TOKEN"]

protected override void SetKvStorageValuesImpl(IDictionary<string, string> Values)
{
    this.api_url = Values["API_URL"];
    this.api_token = Values["API_TOKEN"];
}

The Key-Value Storage feature is available on all extension types, query, data processing and result reporting.

Configure storage values

Values are configured in the OmniFi Administration application. Navigate to the Extensions tab and select the extension.

Configure the appropriate values in the Key-Value Storage panel.

You can also configure the values on a parent folder of the extension by selecting that folder instead.

This is convenient for extension packages with several extensions that target the same underlying data source.