Dynamic Configurations

Traditionally when creating your integration configurations, most fields will be static values, booleans, or strings. However, for selectable choices you may wish to populate the values from an API or Database. You are able to set placeholders in your Schema that will later get populated with data via end user action. 
For example, if we are integrating to Mailchimp, we may want to give our end users the option to select from a list of audiences (fetched from the Mailchimp API) to sync their contacts to.
configs:
  schema:
    name: pandium_configs
    properties:
      log_level:
        enum:
          - INFO
          - DEBUG
          - WARNING
          - ERROR
        type: string
        default: INFO
      mailchimp_audience:
        "$ref": "#/definitions/audiences"
        type: string
    definitions:
      audiences:
        enum:
          - placeholder
  uischema:        
    type: VerticalLayout
    elements:
      - type: Control
        admin: true
        label: Log Level (INFO)
        scope: "#/properties/log_level"
     - type: Control
        label: Audience
        scope: "#/properties/mailchimp_audience"   
Schema
The first piece to set up dynamic configs starts in the schema with the definitions field. This is where the developer can set default or placeholder values until there is an action via the end user to populate with values from you API/DB.
    definitions:
      audiences:
        enum:
          - placeholder
This definition field will then be referenced in the properties section of the schema:
mailchimp_audience:
    "$ref": "#/definitions/audiences"
    type: string
Integration Script (Init mode)
Now that the schema is prepared to receive dynamic data, the integration script needs to present that data when there is an init sync. In your script you can determine the run mode by accessing the context environment variable: PAN_CTX_RUN_MODE . If the value of this environment variable is 'init', then your script can add logic to populate your dynamic configs. 
Pandium will load the last line of output to stdout during an  init sync in order to populate the dynamic config options in the UI for your end user.
Script Example:
 if (pandium.context.runMode === 'init') {
        const mcAudiences = await mcClient.getMany('audience');
        const stdout = {
            // Whatever values you want to pass into the next run should be logged to stdout as a string encoded json object.
            // Each key will be presented as a variable in the context.
            // Also if a variable matches with one of the configs.schema.definitions in the PANDIUM.Yaml it will be used as selected values in a dropdown.
            'audiences': mcAudiences.map(({ name }) => name)
        };
 
        // Print json string to stdout and end the script.
        console.log(JSON.stringify(stdout));
        return
    }
​
In the above example, the developer adds custom logic to determine if the PAN_CTX_RUN_MODE is init and then gathers a list of MailChimp audiences by calling their api. With the updated list of audiences, the developer creates a json string which is then printed to the stdout and the script ends.
Sync (Init mode)   
In order to populate the dynamic configs for the end user, an init sync must be triggered. There a multiple ways in which this can happen:
Marketplace - Initial Install:
When the end user installs an integration that uses dynamic configs via the i-framed marketplace , if the integration uses dynamic configs, Pandium will automatically run an init sync before the user is able to fill out their configuration data.
Marketplace - Refresh Button
An end user can trigger an init sync by clicking the 'refresh configs' button while trying to configure their app via the i-framed marketplace.
Admin Dashboard - Init Sync
An init sync can also be triggered by an admin via the Admin Dashboard when viewing a tenant.
Marketplace Refresh Button (right)
Admin Dashboard Init Sync Button (right)
End User View
Following this example, prior to an init sync being triggered, the end user would see this in their configuration section:
Audience select box with only placeholder data
Once the init sync has finished and succeeded, following the scripts output, the end user would then see a populated select box in their configuration section:
Dynamically populated select box of MailChimp Audiences
To achieve these options, the last line of stdout from the integration script would print:
[OUT] {"audiences": ["orange", "purple", "green", "red", "blue", "pandium"]}
UiSchema
Custom Configurations
Last modified 2yr ago