From 5f9f9f68465cea29069147edfe53790ef5bf90fe Mon Sep 17 00:00:00 2001 From: Karl Rankla Date: Fri, 30 Oct 2026 11:26:24 +0200 Subject: [PATCH] docs(integration-toolkit): sandbox organizations and the SANDBOX_LANE monitoring code --- .../integration-toolkit/monitoring/codes.md | 3 +- .../sandbox-organizations.md | 44 +++++++++++++++++++ 2 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 docs/integrations/integration-toolkit/sandbox-organizations.md diff --git a/docs/integrations/integration-toolkit/monitoring/codes.md b/docs/integrations/integration-toolkit/monitoring/codes.md index 7826bc3..44af282 100644 --- a/docs/integrations/integration-toolkit/monitoring/codes.md +++ b/docs/integrations/integration-toolkit/monitoring/codes.md @@ -15,7 +15,7 @@ Every monitoring event carries a **code** and a **level**. The code says what happened; the level says how much you should care. Both are filterable in the Integration Hub's [Monitoring tab](./overview.md) and through the events API. -There are 118 codes. You are most likely here because you saw one in a failed +There are 119 codes. You are most likely here because you saw one in a failed event — find it below. :::tip @@ -170,6 +170,7 @@ Lifecycle markers rather than outcomes: a message was queued, a duplicate was ig | `INTERACTIVE_NOT_ALLOWED` | Interactive processing was requested for a use case that is not configured for it, so the events were processed normally. Set `interactive` to `on_request` or `always` on the use case if the caller is meant to be able to wait for these events | | `MSG_ENQUEUED` | Outbound message enqueued to the poll queue, awaiting consumption by the ERP. When the use case maps the payload, the detail carries the mapped payload as delivered and its mapping_version (or payload_omitted when it exceeds 48 KiB) | | `ORG_DROPPED` | Events from this organization are configured to be dropped, so the event was consumed without being processed | +| `SANDBOX_LANE` | This organization is a sandbox, so its events are processed on the sandbox lane: isolated from production organizations and with a fixed, small capacity. Nothing is lost, but a large load takes proportionally longer than it would on a production organization. Use a production organization for full-volume migrations, or ask epilot for a time-boxed lift before a rehearsal. Reported at most once per hour per integration | | `WEBHOOK_SKIPPED` | The webhook was not delivered because its filters did not match the event | ## Status-code families diff --git a/docs/integrations/integration-toolkit/sandbox-organizations.md b/docs/integrations/integration-toolkit/sandbox-organizations.md new file mode 100644 index 0000000..77f3ad1 --- /dev/null +++ b/docs/integrations/integration-toolkit/sandbox-organizations.md @@ -0,0 +1,44 @@ +--- +sidebar_position: 8 +title: Sandbox Organizations +description: How the Integration Toolkit processes the events of sandbox organizations, and how to plan large data loads +slug: /integrations/integration-toolkit/sandbox-organizations +--- + +# Sandbox Organizations + +A sandbox organization is where you build and verify an integration: its mappings, its use cases and the real-time flows your end customers will use. The Integration Toolkit processes the inbound events of every sandbox organization on a dedicated **sandbox lane**, separate from production organizations and with a fixed, small processing capacity. + +:::info What this means for you +- **Nothing is rejected and nothing is lost.** Every event you send to a sandbox is processed. +- **Large loads take longer.** A full data load that a production organization processes in minutes can take hours in a sandbox. +- **Real-time flows are unaffected.** Events sent with [interactive registration](./interactive-registration.md) keep their own lane in a sandbox too. +::: + +## Which Organizations Are Sandboxes + +epilot sets an organization's type when it is created: a sandbox belongs to a production organization and is used to prepare changes before they go live. You do not configure anything in the Integration Toolkit. Every page of the Integration Hub shows a banner while you work in a sandbox organization. + +## What Runs on the Sandbox Lane + +- Events sent to the [inbound API](./inbound/getting-started.md), on every version of the endpoint. +- Rows of file imports. +- Everything these events lead to: entity writes, relations and meter readings. + +[Interactive](./interactive-registration.md) events are the exception. They run on the interactive lane exactly as in production, within the same [rate limits](./interactive-registration.md#rate-limits), so you can test registrations and contract additions end to end in a sandbox. + +## How You Notice It + +- A banner on every page of the Integration Hub, linking to this page. +- The monitoring code [`SANDBOX_LANE`](./monitoring/codes.md) (level `info`) on the integration while events arrive, at most once per hour per integration. +- Events are processed later than in a production organization when you send many of them at once. Their results are the same. + +## Planning Large Data Loads + +- **Test with a representative subset.** A few hundred to a few thousand records that cover your edge cases verify a mapping as well as the full data set does, and finish quickly. +- **Run full-volume loads in production.** Initial migrations and full resyncs belong in the production organization. +- **Ask for a time-boxed lift for a rehearsal.** If you need a full-volume dress rehearsal in a sandbox, for example before a go-live date, ask your epilot contact or epilot support in advance. For the agreed period the sandbox is processed like a production organization. + +## Why Sandboxes Have Their Own Lane + +Sandbox and production organizations share the same processing infrastructure. Keeping sandbox traffic on its own lane means a test in a sandbox can never slow down a production organization, including your own.