Settings store

6 min

Store settings form data in the settings store. Like the secrets store, it is encrypted in-flight and at rest using AES 256-bit encryption and is a safe place to store passwords and API keys/tokens. When a user configures your app through the settings form, you can read and update the data backing the form by writing it to the settings store.

For more information, see the App SDK documentation.

Important Do not write sensitive data such as usernames, passwords, API keys, or API tokens to any store other than the secrets or settings store.

Write to the settings store

When your app handles a settings form submission, make any necessary modifications, then write the user data to the settings store. Any data you write to the settings store is available to the form user interface (UI), so you can display it or use it to determine what to display or hide on your app's Settings tab of the ODP App Directory.

import * as App from '@zaiusinc/app-sdk';
import {storage} from '@zaiusinc/app-sdk';
// ...
public async onSetupForm(section: string, action: string, formData: App.ValueHash): Promise<App.Response> {
  // validate formData and make any changes necessary
  // then save the data for this section to the settings store:
  await storage.settings.put(section, formData);
  return new App.Response(200);
}

Update data in the settings store

Most of the time, you write to the settings store when your app handles a settings form submission, but you can also write to it any time you want to update the data for that form. For example, to make it clear to the user a historical import was previously run:

const update = {complete: true, completed_at: new Date().toISOString()};
await storage.settings.patch('importSection', update);

Your settings form can then display this information to the user instead of showing a button to start the import or a notification the import is running.

Get settings form data

When you need to access user-provided configuration, such as in a job to decide which list to import or to use the user's credentials, you can read the desired form from the settings store.

import {storage} from '@zaiusinc/app-sdk';
const credentials = await storage.settings.get('authentication');
reauthenticate(credentials.user_name, credentials.password);

While rare, there may be cases where you want to delete a configuration, such as if the user changes the mode of your app and you want to clear the configuration relevant to the previous mode. To do this, you should delete each section you want to clear.

await storage.settings.delete('authentication')
await storage.settings.delete('list_options')

When a user uninstalls your app, all settings data is deleted. If a user reinstalls the app, the settings store is empty.