Integrations
What an integration is
An integration is a named group of the scripts and workflows that do one job together, watched as one. "Plex to EDI 856 for Acme" might be a scheduled script that pulls shipments from Plex, a workflow that builds the ASN, and a webhook script Acme calls to confirm receipt. On their own they are three entries in Executions; as an integration they share one page with one health status, one success rate, their failures grouped, their schedules and the partner's API keys.
Integrations live under Script Engine › Integrations. Anyone with DataMagik - Builder or DataMagik - Viewer can look at them. Defining, changing and deleting an integration, and the actions on its page (rerun, pause a schedule, disable a key), need DataMagik - Builder.
An integration only groups and watches. Adding a script to one, or deleting the integration, does not change how the script runs.
Defining an integration
Click New integration, fill in Define an integration, and click Save integration.
| Field | What it does |
|---|---|
| Name | Required, up to 100 characters, and unique in your company. |
| Success target (%) | Between 50 and 100; starts at 99. Below it, the integration shows as Degraded. See Health. |
| Description | Optional, up to 500 characters. Shown under the name. |
| Email when the health changes | Up to 20 addresses, separated by commas. The screen notes that health emails start in a later release; the addresses are kept until then. |
| Add scripts | Type a script's or workflow's name, ID or tag and pick it. Up to 200 scripts. |
| Also include any script tagged | Tick it and enter a tag, such as acme. Every script with that tag belongs to the integration, including scripts tagged later. Such scripts are marked via tag. |
| Webhook callers | Tick the API keys a partner uses to call these scripts. Runs started with them count as this integration's webhook traffic. You can choose the company's keys and your own; keys made by the system and expired keys are not listed. |
Each script in the list has two more settings:
- Values shown in the live feed: + Value adds a Label and a Path in the output, such as
Orderand$.order_id, orLinesandlines.length. Each run in the live feed then shows that value from the script's return value, so you can see which order or shipment a run handled. - Alert if it runs less than expected: for a script that should be busy, such as a partner's webhook. Set At least so many runs every so many minutes (up to 7 days), optionally only between two times in a time zone, such as 06:00 to 22:00 America/Chicago for a partner that only sends during the day. A window that crosses midnight, such as 22:00 to 06:00, is allowed. Fewer runs than that marks the integration Degraded.
To change an integration, open it and click Edit. Delete integration asks you to click again to confirm.
Adding a script or workflow from the Script Engine
In the Script Engine, a script's Script Settings panel has a Part of section listing the integrations the script belongs to, with this script's success rate and runs in the last hour. Choose an integration and click Add to integration, or choose New integration with this script….
Workflows are added the same way as scripts, by name in Add scripts. Every workflow is tagged workflow when it is created, so Also include any script tagged workflow brings in every workflow, including new ones.
The Integrations screen
Across the top: how many integrations and scripts there are, how many Need attention (Degraded or Failing), runs in the last 24 hours, and the success rate over the last 24 hours. Each integration then has a card with its health, its success rate and runs per hour, its last run, runs in flight, and a chart of runs per hour over the last 48 hours with failures in red. Click a card to open the integration.
If scripts that ran in the last 24 hours are not in any integration, a note says how many, with Create an integration.
Health
Every integration has one of four health statuses. Each script gets a status, and the integration takes the worst of them, with the script's name and the reason.
| Status | Colour | Meaning |
|---|---|---|
| Healthy | Green | Runs in the last hour, and no check below has tripped. |
| Degraded | Amber | Something needs a look, but most runs are working. |
| Failing | Red | Runs are failing. |
| Quiet | Grey | Nothing ran in the last hour, and nothing says it should have. |
The checks, run every minute:
| Check | Trips when | Status |
|---|---|---|
| Failing runs | Success in the last hour is under 90%, or every run in the script's last 3 active minutes failed. | Failing |
| Below success target | Success in the last hour is under the integration's success target. | Degraded |
| Quieter than expected | A script ran less than its Alert if it runs less than expected setting, inside its active hours. | Degraded |
| Missed schedule | An enabled schedule for one of the scripts has stopped firing: it is overdue by more than 15 minutes, or has no next run. | Degraded |
| Near timeout | 2 of the script's last 3 runs (in the last 6 hours) used over 75% of its timeout. | Degraded |
| Worse since new version | In the hour after a new version of a script was saved, its success rate fell by 10 points or more compared with the hour before, with at least 5 runs on each side. | Degraded |
A run counts as a failure if it ended failed, timeout or cancelled, or if it completed but returned success: false. See Executions and Monitoring.
An integration's page
The page updates itself while it is open. Pause updates freezes it; the buttons 1h, 24h, 7d and 30d choose the time range for the numbers and chart. View runs opens Executions filtered to this integration. TV mode opens a dark, full-screen view of the last hour without buttons, for a wall display.
| Section | Shows |
|---|---|
| Top numbers | Runs / min over the last 5 minutes, Success and failures, In flight, p95 run time, Runs and runs per hour over the range, and Open issues in the last 24 hours. |
| Flow | What started each script and which systems it called over the last hour, such as Plex or a partner's server. A running script lights up. |
| Runs over time | Runs per bar, failures in red. Click a bar to open those runs in Executions. A marker shows each new version of a script; click it to compare runs, median time and top errors before and after that version. |
| Live runs | Each run as it finishes, with what started it, its values, and its error. Details opens the run in Executions. A failed run has Rerun, which runs it again with the same input after you confirm. Open in Executions opens the full list. |
| Scripts | One row per script: the last 30 minutes (each mark is a minute; red means a run failed in it), Success, Runs / hour, p95 and Last run. |
| Health checks | Each check that has tripped, by script, with the reason. Hidden when nothing has tripped. |
| Needs attention | The last 24 hours' failures, grouped by error code and script, with the first and last time each happened and View runs. |
| Running now | Runs in flight, with how long each has run against its timeout. |
| Started by | The scripts' schedules, with their next run and Pause / Resume; the Webhook callers; and what started the recent runs. |
Pause on a schedule is the same as turning its Status switch off on the Schedules screen. Disable on a webhook caller turns that API key off, after you confirm, so further calls with it are refused; it is for stopping a partner whose calls are flooding the integration. You can disable only keys that are yours; the owner of any other key can disable it from their profile.
Related
- Executions and Monitoring: every run, and alerts when one fails.
- Script Schedules and Script Webhooks: the usual ways an integration's scripts start.
- Workflows in Production: workflows in integrations.
- EDI: trading partners, mapping and the EDI console.