Run Triggers

Control how Pandium integrations sync data with cron, manual, webhook, and API run triggers, including payload handling and debouncing per tenant.

What Are Run Triggers?

End users can initiate syncs on a Pandium tenant in multiple ways: via a regular schedule, by clicking a button in the In-App Marketplace, or by sending a webhook. Pandium customers can also design their own mechanisms to trigger syncs by using the Pandium API.

Integration scripts can be written to handle one or more of these methods; it is possible for a single integration script to handle more than one trigger type. The code can even be customized to respond differently depending on the run trigger method.

Additionally, API and webhook triggers can contain information in the payload body that Pandium makes available to the integration code.

If planning for an integration to only ever run via scheduled job or be triggered manually, run triggers can safely be ignored.

Run Triggers In Depth

Pandium represents the four ways that users can trigger runs via four different modes: API, Webhook, Cron, and Manual.

Crons are scheduled syncs. Manual syncs are triggered after clicking a button within either the Integration Hub or In-App Marketplace. API and webhooks triggers are self-explanatory.

Pandium debounces triggers in order to prevent more than one sync happening per tenant at any given time. If a sync request comes in while the integration script is running for a tenant, Pandium will bundle the triggers and pass them into a new run that will start when the current run is completed.

Crons are scheduled in their own, discrete queue and given priority over other types of runs. This ensures scheduled syncs do not fall behind. Crons are only ever bundled with other cron jobs, but the other three trigger types can coexist on a single run trigger array.

On the other hand, if the integration is going to be receiving payloads when it is triggered by a webhook or API call, understanding run triggers and how to access them in your code is key.

Run Triggers in Integration Code

Within a run's context, the run triggers array is stored in the environment variable PAN_CTX_RUN_TRIGGERS. A trigger is a JSON object that contains information about how the run started, including run mode (init or normal), trigger source, and payload data as well as any headers it was sent with.

If you're writing an integration that is receiving webhooks or API requests with payloads, the payload data is stored in a file that can be accessed using your language's built-in file reading functionality.

As an example, below is a script in Javascript that gets the run triggers/payloads from the Pandium context inside an integration:

const runTriggers = JSON.parse(process.env.PAN_CTX_RUN_TRIGGERS)
const payloads = []
for (const trigger of runTriggers) {
      // Only webhooks and API triggers have payloads
      if trigger.mode === 'webhook') {
        const data = fs.readFileSync(trigger.payload.file, 'utf-8')
        // do something with data from payload
      }
}

Run Trigger Examples

The run triggers exposed to your integration via environment variables will have one of the following modes: cron, manual, webhook, or api.

Below is an example of a webhook trigger:

{
    "id": "4731234254284123",
    "source": "webhook",
    "payload": {
        "file": "sample/test_file.txt",
        "headers": {
            "User-Agent": "PostmanRuntime/7.29.0"
        }
    },
    "created_date": "2023-01-27T23:27:07Z",
    "mode": "webhook"
}

Below is an example of an API trigger:

{
    "id": "12345678",
    "source": "api",
      "payload": {
        "file": "sample/test_file.txt",
        "headers": {
            "User-Agent": "PostmanRuntime/7.29.0"
        }
    },
    "created_date": "2023-06-06T10:11:50-04:00",
    "mode": "normal"
}

Below is an example of a manual trigger:

{
    "id": "12345678",
    "source": "manual",
    "created_date": "2023-06-06T10:11:50-04:00",
    "mode": "init"
}

Below is an example using cron:

{
    "id": "example_id",
    "source": "cron",
    "created_date": "2023-06-06T10:11:50-04:00",
    "mode": "normal"
}