# 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](https://docs.pandium.com/integration-hub/setting-up-your-first-integration-tile) 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.

<figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FtpCHMrtEnj3cwDG7Bzgh%2FRepoSettingsImage.png?alt=media&#x26;token=4b8a4751-b01d-4a95-b7bb-d1bd56c766a4" alt="" width="563"><figcaption><p>Repository Settings</p></figcaption></figure>

## Structure

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

```yaml
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`.
  * Please note we also support `0.5` and `0.8`
    * Starting in 0.8, stdout capture now preserves JSON formatting to prevent parsing issues in downstream tools.
* **base:** Use this property to tell us what language and version you have coded your integration in. Format should be `<language>:<version>`&#x20;
  * acceptable values include:`closure`, `kotlin`, `node`, `python`, `ruby`, `java`, `php`, `.net` &#x20;
  * The version of the language should follow the the language using a colon.
    * Examples `python:3.7` or `java:11`

{% hint style="success" %}
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.
{% endhint %}

* 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](https://docs.pandium.com/integration-hub/managing-and-updating-tenants-in-the-admin-portal).

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](https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/schema) 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](https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/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](https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/uischema) 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. &#x20;

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](https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/schema) and [UISchema](https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/uischema) along with the props each type can take.

```yaml
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:

<figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FBR8QedoHmIUAU7Lx9sTk%2FpuWcoQJrZf7rzLJJ8sPYqRJ7kiDMh5qKBB_PIs0UGrM8EFySDQ9_Wmsx5gtaUh8gcDHcPAYBbQoPUcTA4kF0_SgUtg5-BDGDZDT_x53vA8dxgLCv6h1HO1BqgVUB.png?alt=media&#x26;token=ea8bd3b4-d0a3-42a2-828f-2d3033f90bd8" alt=""><figcaption><p>PANDIUM.yaml in the Connections Settings Page</p></figcaption></figure>

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](https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dynamic-configurations) to learn how the PANDIUM.yaml and the standard out of an init sync can be set up to create dynamic configurations.