PANDIUM.yaml

The PANDIUM.yaml provides information to build and execute an integration script on the Pandium platform. It also defines the configuration options and UI, via the configs section, where tenant end users will input information vital to the integration run.

Name and Location

When setting up an internal integration on the Integration Hub, it will ask for a Repository Path. Specify the name and location of the file with respect to the root of your integration code repository. If not set, by default, Pandium will look for a file named PANDIUM.yaml in the root directory.

Structure

All Pandium.yaml files are required to start with the following 5 mappings.

version: 0.4
base: python:3.7 # Node, Ruby, PHP, Java, GO
build: pipenv install 
run: pipenv run python -m hubspot2s3

configs: {} # details to follow

  • version: This should be at the top of the file. Currently this should always be set to 0.4.

  • base: Use this property to tell us what language and version you have coded your integration in. Format should be <language>:<version>

    • acceptable values include:closure, node, python, ruby, java, php, .net

    • The version of the language should follow the the language using a colon.

      • Examples python:3.7 or java:11

We strive to support all commonly used languages and at least the long-term supported version of the language if such a version is defined. If you don't see your preferred language or version, please let your Technical Account Manger know and we will work on getting support built out right away.

  • build: This should be set to how this integration packages its code and gets all of its dependencies installed. Pandium strives to support all common packing and dependency management tools. This includes pip (python), npm (node), composer (php), maven (java), etc.

  • run: This property tells Pandium how to run the integration’s code at run time. This should be the same command used to invoke the integration script on a local command line. For example, if an integration had a script named “main.py” python -m main.py would be used to execute it both locally and on Pandium.

Configs

The connections setting page is used to configure an integration tenant to run according to its end user’s needs. The selections made by a tenant end user on that page are passed to the integration in each run as environmental variables. To learn more about how and why Integration Hub users can configure a tenant, review this article.

The options displayed to an Integration Hub user on the connections settings page are determined by the configs of the PANDIUM.yaml. The configs property needs to include both the schema and uischema.

Each of the connection settings’ configurations must be defined under schema properties as a string to object mapping.

  • The string specifies the configuration’s name. The name of the environmental variable used to pass a configuration to an integration’s run is the property name prefixed with PAN_CFG_. For example, if the property name is config_name, then the integration will be able to access the tenant end user’s selection for config_name with PAN_CFG_CONFIG_NAME.

  • The object to which the property name is mapped must contain the type prop. Depending on a property’s type, other props could be specified, but none are required. Review this article to learn about different types of schema properties and additional props they can be given.

Each of the connection settings’ configurations must also be listed in the uischema elements. The uischema determines how and where each configuration is displayed on the connection settings page. Some UISchema elements only serve formatting purposes, while others display a specific configuration defined under schema properties. The scope of such UISchema elements must reference the name of the corresponding schema property. Review this article to learn about different types of UISchema elements and additional props they can be given.

Below is an example of the rest of a PANIDIUM.yaml with four static configs (not including the required information in example code above)

In the connections settings page, the end user will be presented with the four configurations defined under the schema properties.

The configurations will be labeled as described under the uischema.

Notice that this example includes schema properties and uischema elements with props that have not yet been discussed (e.g default and admin). To learn more about those and other props, review the reference guides on the different types for entries of the schema and UISchema along with the props each type can take.

version: 0.4
base: python:3.7 # Node, Ruby, PHP, Java, GO
build: pipenv install
run: pipenv run python -m hubspot2s3
configs:
  schema:
    properties:
      s3_bucket_name:
        type: string
      s3_file_name:
        type: string
      make_contact:
        type: boolean
        default: true
      make_company:
        type: boolean
    type: object
  uischema:
    elements:
    - label: S3 Bucket Name
      scope: '#/properties/s3_bucket_name'
      type: Control
    - label: S3 File Name
      scope: '#/properties/s3_file_name'
      type: Control
    - label: Make Contact?
      scope: '#/properties/make_contact'
      type: Control
      admin: true
    - label: Make Company?
      scope: '#/properties/make_company'
      type: Control
    type: VerticalLayout

These options would be displayed on the connections settings page inside the Integration Hub like this:

The configs in the example are all static, meaning the options for every tenant will be the same. Dynamic configs have options populated from an API or database, so they are different for each tenant. Review this article to learn how the PANDIUM.yaml and the standard out of an init sync can be set up to create dynamic configurations.

Last updated