BETA: Tenant Metadata

Learn how to store tenant specific information for your customers.

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).

• schema is a standard json schema. For more information, please see here - https://json-schema.org/understanding-json-schema/reference

• uischema is not currently used in Pandium. However, including it is useful if you are building your own UI on top of the metadata.

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

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

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.

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:

• GET - https://docs.pandium.com/reference/pandium-api#get-v2-tenants-tenant_id-metadata

• PATCH - https://docs.pandium.com/reference/pandium-api#patch-v2-tenants-tenant_id-metadata

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