Dynamic Configurations

Define dynamic configs in PANDIUM.yaml whose options are fetched per tenant from an API or database and stored in tenant metadata.

Typically when creating integration configurations, most fields will be static; that is, the options for the field will be the same for every tenant. However, it can be useful to include dynamic configurations, where the integration populates the options with values from an API or database, so they are different for each tenant.

To see an example of an integration that benefits from a dynamic config, and what it looks like for users on the Integration Hub or the In-App marketplace, review this article.

The per-tenant options live in tenant metadata, and a config references them with $ref: '#/metadata/<key>'.

Manifest versions below 1.0 used a definitions entry filled from the saved stdout of the tenant's last init sync instead. Those versions are deprecated. See Migrating to Manifest Version 1.0 to move an existing integration over.

How It Works

A dynamic config takes three things:

1. A property in metadata_schema.schema.properties to hold the fetched options.

2. A property in configs.schema.properties that references it with $ref: '#/metadata/<key>'.

3. A flow in the integration code that fetches the options and prints them to stdout under that same key.

Pandium validates the run's stdout against metadata_schema, merges it into the tenant's metadata, and resolves the reference against that metadata each time it renders the Connection Settings page.

Declaring the Metadata Property

Every metadata key a config references must be declared in metadata_schema before a tenant can save values under that key, since stdout is validated against that schema and undeclared keys are rejected (unless the schema explicitly allows additional properties). Declare it as an array:

metadata_schema:
  schema:
    type: object
    properties:
      audiences:
        type: array
        items:
          type: string

Referencing it from a Config

The config property points straight at the metadata key:

configs:
  schema:
    properties:
      mailchimp_audience:
        $ref: '#/metadata/audiences'

The shape of the metadata value determines the control that renders:

• An array of strings resolves to an enum, one option per string.

• An array of {const, title} objects resolves to a oneOf, where const is the value the integration receives and title is the label shown to the user.

Static option lists do not go through metadata. A field whose options are the same for every tenant should still list them inline or reference a definitions entry, and should not go through metadata.

Printing the Options from the Integration Script

The integration script provides the options by printing them to stdout as a JSON object. Any run can do this. The usual place is an init branch: when a user connects a new tenant through the In-App Marketplace, Pandium runs an init sync (run mode init) before showing the Connection Settings form, so options printed there are in metadata the first time the form renders. In the script, the run mode is available in the PAN_CTX_RUN_MODE context environment variable.

if (pandium.context.runMode === 'init') {
    const mcAudiences = await mcClient.getMany('audience');
    const kLists = await kClient.getMany('audience');
    const stdout = {
        // Each key matches a property in metadata_schema, which configs reference as '#/metadata/<key>'.
        'audiences': mcAudiences.map(({ name }) => name),
        'lists': kLists.map((list) => ({const: list.id, title: list.name}))
    };
    // Print json string to stdout and end the script.
    console.log(JSON.stringify(stdout));
    return
}

Options that rarely change can be fetched once and left alone afterwards. Because metadata is merged rather than replaced, a later run that prints only a sync cursor does not wipe out the option lists an earlier run wrote.

Until a run has written metadata for a referenced key, the field renders in an unsynced state with its options disabled.

Putting it All Together

Here is a full PANDIUM.yaml with one static config and two dynamic ones:

version: 1.0
base: node:20.9.0
build: npm install --production && npm i --save-dev @types/node && npm run build
run: node .

configs:
  schema:
    type: object

    definitions:
      log_level_options:
        enum:
          - INFO
          - DEBUG
          - WARNING
          - ERROR

    properties:
      log_level:
        $ref: '#/definitions/log_level_options'
        default: INFO
        type: string
      mailchimp_audience:
        $ref: '#/metadata/audiences'
      klaviyo_list:
        $ref: '#/metadata/lists'

  uischema:
    type: VerticalLayout
    elements:

    - type: Section
      label: First Section
      elements:
      - type: Control
        label: Log Level
        scope: "#/properties/log_level"
      - type: HorizontalLayout
        elements:
        - type: Control
          label: MailChimp Audience
          scope: "#/properties/mailchimp_audience"
        - type: Control
          label: Klaviyo List
          scope: "#/properties/klaviyo_list"

metadata_schema:
  schema:
    type: object
    properties:
      audiences:
        type: array
        items:
          type: string
      lists:
        type: array
        items:
          type: object

log_level is static and lists its options in a definitions entry. mailchimp_audience and klaviyo_list are dynamic and reference metadata keys.

The run that populates those keys prints:

[OUT] {"audiences":["Friends","Family","Acquaintances"],"lists":[{"title":"Prospective Customers","const":1},{"title":"One Time Customers","const":2},{"title":"Loyal Customers","const":3}]}

Once that metadata is written, this produces the following Connection Settings page on the Integration Hub:

For more detailed instructions on how to implement dynamic configurations review this tutorial.