tenant metadata.md

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

Tenant Metadata

{% hint style="info" %} Tenant Metadata is available on PANDIUM.yaml manifest version 1.0 and above. {% endhint %}

What is Tenant Metadata?

Tenant metadata lets your integration store data that it discovers at runtime (i.e. information that wasn't provided during tenant configuration). This is useful when your integration fetches data from a remote system (such as user IDs, warehouse locations, or sync cursors) and needs to persist it for future runs.

How does Tenant Metadata Work?

Existing metadata is exposed to the integration code during a run as an environment variable. Metadata is updated at the end of every run from the last run stdout. If the last run stdout on a tenant with metadata on its integration release does not conform to the metadata schema, the run will fail.

Adding Metadata to your Integration Release

To turn on the tenant metadata feature, make sure to add metadata_schema as a top level scope in Pandium.yaml. metadata_schema should have two keys: schema (required) and uischema (optional).

When adding metadata to your Pandium YAML, make sure to add this as a top level scope similar to your schema.

{% code expandable="true" %}

metadata_schema:
  schema:
    name: metadata_schema
    properties:
      product_sync:
        type: boolean
      update_sync:
        type: boolean
      warehouse_location:
        type: string

uischema:
    type: VerticalLayout
    elements:
      - title: Sync Products
        type: Label
      - label: Enable
        scope: '#/properties/product_sync'
        type: Control
      - title: Sync Updates
        type: Label
      - label: Enable
        scope: '#/properties/update_sync'
        type: Control
      - label: 'Warehouse Location'
        scope: '#/properties/warehouse_location'
        type: Control

{% endcode %}

Updating Tenant Metadata at the End of a Run

Metadata is updated at the end of every run from the last run stdout. If the last run stdout on a tenant with metadata on its integration release does not conform to the metadata schema, the run will fail. At the end of every run, with the addition to writing stdout to the run, if there is a metadata schema available on the release, the Pandium platform will validate the entire stdout against the schema. Additional fields are allowed. If validation fails, the run will be marked as a failure with a special status, Failed (Metadata Validation) and the tenant's metadata will not be updated. If the schema passes validation, the metadata will be updated, not replaced.

Additional fields follow standard JSON Schema behavior. By default they are permitted unless the schema explicitly sets additionalProperties: false.

Using Metadata to Populate Dynamic Configs

On manifest version 1.0, tenant metadata is the source for dynamic configurations and dependent selectors. A config field references a metadata key with #/metadata/<key>, and Pandium resolves the reference against the tenant's current metadata when it renders the Connection Settings page.

Each referenced key must be declared in metadata_schema.schema.properties and populated from a run's stdout. Because the form resolves these references when it renders, the options must already be in metadata before the form is shown. When a user connects a new tenant in the In-App Marketplace, Pandium runs an init sync (run mode init) before displaying the Connection Settings form — so an integration can populate option metadata in an init branch. Values that rarely change (for example, a list of channels or warehouses) can be fetched once during the init sync and left untouched on later syncs, rather than refetched on every run.

Simple dynamic config — reference the metadata key with $ref. If the metadata value is an array of strings it becomes an enum; an array of {const, title} objects becomes a oneOf.

configs:
  schema:
    properties:
      colors:
        $ref: '#/metadata/available_colors'
metadata_schema:
  schema:
    type: object
    properties:
      available_colors:
        type: array
        items:
          type: string

Dependent selector — reference the parent options with $ref and the child map with optionsMapPath, and point parentField at the parent config.

configs:
  schema:
    properties:
      food_type:
        $ref: '#/metadata/food_types'
      food_item:
        type: string
        optionsMapPath: '#/metadata/food_items_map'
        parentField: '#/properties/food_type'

Until a run has written metadata for a referenced key, the field is shown in an unsynced state and its options are disabled.

Reading Tenant Metadata During a Run

Tenant metadata is written in JSON to a temporary file, the path which is exposed in a run as an environment variable. For example, in a Python integration, you could use the following code to read and log tenant metadata:

def main():
      tenant_metadata_file_path = os.getenv('PAN_CTX_TENANT_METADATA_FILE')
      if not tenant_metadata_file_path:
          logger.debug("no metadata file path set")
          return

try:
          with open(tenant_metadata_file_path) as file:
              metadata = json.load(file)
          logger.debug(metadata)
      except FileNotFoundError:
          logger.debug("no metadata file found")
      except json.JSONDecodeError as e:
          logger.error(f"invalid metadata JSON: {e}")

Updating & Reviewing Tenant Metadata Using the Pandium API

GET and PATCH endpoints are available for your team using the following links:

Reviewing Tenant Metadata in the Pandium Integration Hub

If your tenant is on a release that is using tenant metadata, you can review the last stdout by doing the following steps:

  1. Pull up the tenant in question
  2. Navigate to Details > Select Show next to Tenant Metadata a