System Connections¶

A SystemConnection represents a link between a Tenant and an external system account. It holds the credentials and configuration required for Conflux to communicate with that account on the tenant's behalf. See Tenant Model for how connections, tenants, and adapters relate.

Model attributes¶

system_id and base_url can both be null simultaneously — this happens for a tenant-initiated connection that has not yet been finalized by the plugin (see Connection Flow). The API resource returns "system": null for these until a plugin supplies system_slug via /register.

Status¶

status is a spatie/laravel-model-states state. The abstract base is App\States\SystemConnection\SystemConnectionState, and each concrete state is a final class next to it. Each state stores its $name alias in the column, so the stored values are plain strings, never class names. See ADR-0039 for why.

The label is the capitalised stored value. SystemConnectionState::options() returns every stored value mapped to its label, for select filters.

Transitions¶

A status changes only through $connection->status->transitionTo(Target::class). The library resolves the transition class from the current and the target state. Every transition class lives in App\States\SystemConnection\Transitions, and the table is declared in SystemConnectionState::config().

Reconnect::canTransition() allows the move only while the connection is within its grace period; past it, transitionTo(Active::class) throws Spatie\ModelStates\Exceptions\TransitionNotAllowed.

Every other move is refused. In particular, nothing leaves Uninstalled, and Inactive has no way back to Active other than a fresh handshake, which creates a new row.

Every transition extends SystemConnectionTransition. Its final handle() does the following, in one transaction:

1. Throws a LogicException if the model has unsaved changes. Save other fields first, then transition.
2. Reloads the row into the same instance with refreshForUpdate(), which selects it with lockForUpdate().
3. Returns without saving if the stored state already is the target.
4. Calls refused() if the stored state may not move to the target. It also calls refused() when the table resolves the stored move to a different transition class than the one running. By default that throws App\Exceptions\StaleConnectionStatus, a Spatie\ModelStates\Exceptions\CouldNotPerformTransition. RecordError overrides it to log at info and keep the stored state, because a connection that ended while a sync was probing the shop is an expected race.
5. Saves the target state and runs the side effects.

Synchronous side effects roll back together with the status. Jobs are dispatched with ->afterCommit(), so they wait for the outermost transaction to commit and are discarded on rollback.

The table has no ignoreSameState(). A transitionTo() into the state the instance already holds throws CouldNotPerformTransition before the transition runs. A caller that can repeat a move returns early when $connection->status instanceof Target.

Creation is not a transition. A new row defaults to Pending, and a row may be created in any state: the tenant bootstrap and SyncRuleSeeder create Active rows, and factories create any state.

SystemConnectionObserver::saving() throws App\Exceptions\StatusChangeRequiresTransition when an existing row's status changes outside a transition. A transition lifts the guard only for its own save, through SystemConnection::allowingStatusChange(), and an architecture test keeps the base transition its only caller. Query-builder updates, saveQuietly() and withoutEvents() bypass that guard, so never use them to write the column.

To query by status, use whereState('status', Active::class). To compare, use $connection->status instanceof Active. $connection->status->getValue() returns the stored string.

Grace period¶

disconnected_at is an invariant of the state rather than something a caller sets: SystemConnectionObserver::saving() stamps it when a connection enters disconnected without a timestamp, keeps a timestamp that was supplied, and clears it when the state is left. A reconnect therefore clears the deadline by itself.

$connection->graceDeadline();       // ?CarbonImmutable, null unless disconnected
$connection->isWithinGracePeriod(); // bool

The deadline is derived, never stored. The window defaults to 30 days and is configurable via config/conflux.php (disconnected_connection_grace_period_days, env DISCONNECTED_CONNECTION_GRACE_PERIOD_DAYS). See ADR-0013 for the model and the deletion rules that follow from it.

Relations and derived state¶

outgoingSyncRules() / incomingSyncRules()¶

HasMany SyncRule, keyed on source_connection_id and target_connection_id respectively — every rule that moves data out of, or into, this connection, active or not.

activeOutgoingSyncRules() / activeIncomingSyncRules()¶

Derived from the two relations above with is_active = true baked into the query, so no call site can forget it. Eager-load activeOutgoingSyncRules with with('activeOutgoingSyncRules') whenever pullInCapabilities() is called for more than one connection.

outgoingCoverageGap() / incomingCoverageGap()¶

$connection->outgoingCoverageGap(); // list<SystemCapability>
$connection->incomingCoverageGap(); // list<SystemCapability>

The data domains this connection could hand off (or receive) but no active rule in that direction covers, narrowed to domains for which a rule could actually be created: some eligibleCounterparts() connection accepts the domain in that direction per the direction matrix (ADR-0005). A domain no counterpart could ever route in that direction is left out — reporting it would make the warning permanent and unactionable. Read by the connection's flow overview in the admin panel; see System Connections admin resource.

eligibleCounterparts()¶

$connection->eligibleCounterparts(); // Collection<int, SystemConnection>

The active connections in this connection's tenant that a SyncRule may pair it with: exactly one side must be an internal consuming platform (ADR-0008), the same classification SyncRuleBlueprintService applies when deriving a tenant's default rules. Deliberately not narrowed by who is asking — outgoingCoverageGap() and incomingCoverageGap() read it as a statement about the connection itself, independent of the viewer.

pullInCapabilities()¶

$connection->pullInCapabilities(); // list<SystemCapability>

The data domains this connection may pull in right now: the capabilities its System declares, narrowed by configuredCapabilities() when the connection carries a connector-widget opt-in, and narrowed again to the data_domains of its active outgoing SyncRules. Returns [] when no System is linked. The result is ordered like System::capabilities, not like the rule rows.

Because it reads activeOutgoingSyncRules only, it answers the pull-in question exclusively — hence the name. Push-out is a delivery layer CFX-206 is specifying, and no code delivers yet. activeIncomingSyncRules() still exists only to back incomingCoverageGap()'s reporting, rather than a delivery. See Outbound Delivery for the design.

This is the single source for both dispatch paths — sync:dispatch and the panel's Bulk Sync action. See Sync Rules — Who reads the rules.

configuredCapabilities()¶

$connection->configuredCapabilities(); // list<SystemCapability>|null

The connector-widget opt-in from configuration.data_types, mapped through SyncDataType::toCapability(). null means the connection carries no opt-in and is therefore unrestricted; [] means the customer has selected nothing.

Scopes¶

scopeForTenant¶

SystemConnection::query()->forTenant($tenant)->get();

Filters to system connections owned by the given Tenant instance or tenant UUID. Applied by the list endpoint against the authenticated connection's tenant, so a caller only ever sees its own tenant's connections.

scopeForSystem¶

SystemConnection::query()->forSystem($system)->get();

Filters to system connections targeting the given System instance or system UUID.

scopeActive¶

SystemConnection::query()->active()->get();

Filters to rows where status = active.

scopeAccessibleBy¶

SystemConnection::query()->accessibleBy($user)->get();

Filters to connections whose tenant the given admin User may reach — a SuperAdmin short-circuits to everything, anyone else goes through Tenant::scopeAccessibleBy. This is the status-only set: it includes a platform-support user's sibling connections, which the admin panel surfaces read-only.

scopeFullyAccessibleBy¶

SystemConnection::query()->fullyAccessibleBy($user)->get();

Filters to a connection when either: its own System is one the user actually supports (System::scopeSupportedBy() — the system satisfies canHaveSupportUsers() and lists the user in system_user), or its system cannot have support users at all (System::scopeCannotHaveSupportUsers() — a shop adapter) and a sibling connection of the same tenant points at a system the user does support. SuperAdmin short-circuits again.

This scope carries no tenant restriction of its own. It is used as a per-record predicate on rows that already passed accessibleBy (the admin resource applies that in getEloquentQuery()), which together yield "own systems, plus any shop connection reached through a sibling own system, under accessible tenants" — the set a support user may see in full, as opposed to the status-only siblings that remain (another internal/consuming platform's connection). See ADR-0007 for the original two-tier split, ADR-0008 for why shop adapters never have their own support members, and ADR-0030 for the sibling-cascade exception that follows from that. For the concept, see Admin access model.

API endpoint¶

See the auto-generated API docs for the full endpoint specification, query parameters, and response shape.

Cleanup¶

A SystemConnection left in pending status with no way to ever complete its handshake (for example, repeated tenant-initiated /connect calls that are never finished by a plugin — see Connection Flow) is abandoned and safe to remove. The abandoned-connections:prune Artisan command hard-deletes every SystemConnection where:

• status = pending,
• created_at is older than a configurable grace period, and
• there is no valid (non-expired, unused) SystemConnectionToken still associated with it.

Connections in any other status (active, inactive, error, disconnected, uninstalled) are never touched, regardless of age.

The grace period defaults to 24 hours and is configurable via config/conflux.php (pending_connection_grace_period_hours, env PENDING_CONNECTION_GRACE_PERIOD_HOURS).

Because system_connection_tokens.system_connection_id uses restrictOnDelete, the command first hard-deletes the connection's own (already-invalid) tokens, then hard-deletes the connections themselves — bypassing SoftDeletes on SystemConnection, the same precedent set by connection-tokens:prune (see Pruning).

It is scheduled to run daily (registered in routes/console.php) and can also be run manually:

docker compose exec php php artisan abandoned-connections:prune

Deactivation¶

A connection moves to Inactive through the Deactivate transition, from Pending, Active or Error. Two callers use it: the DeactivateConnectionAction (see System Connections admin resource), and SystemConnectionService::activate() retiring a sibling connection on reconnect (see Connection Flow: Why Reconnection Must Retire the Old Connection). The edit form cannot set the status. The transition runs for any path that lands the connection on Inactive, not a single specific endpoint or action. It first cancels the connection's in-progress bus batches, then runs three independent clean-up steps:

1. Tokens are revoked immediately and irrecoverably. SystemConnectionService::revokeAllTokens() hard-deletes every SystemConnectionToken belonging to the connection — both handshake tokens and widget access tokens (see Connection Widget). This bypasses SoftDeletes — the same precedent as connection-tokens:prune (see System Connection Tokens — Pruning). Once deactivated, a connection's old tokens cannot be restored; a subsequent reactivation does not reissue them. Credentials themselves (the credentials column) are not cleared — only tokens are revoked.
2. The plugin is notified, best-effort. App\Jobs\NotifyConnectionDeactivatedJob is dispatched and, if the connection's integration implements App\Contracts\CanNotifyDeactivation, calls its notifyDeactivated() method so the plugin can update its own local state. Failures are logged, not retried.
3. Business data is soft-deleted asynchronously. App\Jobs\CleanupConnectionDataJob is dispatched (queue: rabbitmq) and soft-deletes every Customer, Order, LineItem, Product, and CustomerConsent row belonging to the connection, since the shop no longer authorises Conflux to hold or serve that data. This uses the same bulk soft-delete pattern described in Sync Batches, and, unlike token revocation, is recoverable at the database level — the rows are soft-deleted, not hard-deleted. Sync rules and batches are left untouched.

There is no grace period and no disconnected_at timestamp for a plain deactivation, and there is no admin action to move an Inactive connection back to Active (Reactivate applies only to Error, see Reactivation from Error). Reactivating requires completing a fresh handshake (see Connection Flow), which does not reissue the old tokens or restore the soft-deleted business data; it is repopulated by the next bulk or delta sync instead.

See Connection Flow — Deactivation and Reconnection for the wider narrative.

Reactivation from Error¶

A connection lands on Error through the RecordError transition, when the circuit breaker opens during BulkSyncJob or FetchBulkPageRangeJob. FetchBulkPageRangeJob also records Error when the connection's integration cannot export in bulk. If the connection left Active while the job was probing the shop, RecordError logs at info and keeps the stored state.

The circuit breaker closes after its cooldown, but the status stays Error. The way back is the admin panel's ReactivateConnectionAction, which runs the Reactivate transition from Error to Active:

1. The circuit breaker is reset, so the next sync is let through.
2. Missing default sync rules are generated, the same way an activation generates them.

Tokens, credentials and business data are untouched: Error removes none of them. Reactivation starts no sync itself. The next scheduled delta sync picks the connection up, and the Bulk Sync action starts one immediately.

Disconnect¶

POST /api/system-connections/disconnect is how the plugin reports, from its own admin UI, that the shop has disconnected. It is authenticated by the widget token, deliberately POST rather than DELETE (a business event, not a resource removal). The admin panel offers the equivalent DisconnectConnectionAction (see System Connections admin resource). Both set status = Disconnected on the connection and start a 30-day grace period, rather than ending the connection outright.

The Disconnect transition runs from Pending, Active or Error. It cancels in-progress bus batches and dispatches App\Jobs\DisconnectConnectionDataJob. The endpoint returns early when the connection already is Disconnected, so repeating the call is harmless and queues the job once. That job:

1. Soft-deletes business data, exactly as deactivation's CleanupConnectionDataJob does — every Customer, Order, LineItem, Product, and CustomerConsent row belonging to the connection.
2. Soft-deletes the connection's SyncRules too — unlike deactivation, which leaves sync rules untouched, so nothing tries to sync a connection that is no longer serving data during the grace period. Soft-delete rather than is_active = false: that flag is an independent, admin-toggleable setting, and a rule an admin turned off before the disconnect must stay off on reconnect.

Credentials and tokens are kept, not revoked — a reconnect within the grace period needs no new credentials from the operator. disconnected_at is maintained as an invariant of the state by SystemConnectionObserver::maintainDisconnectedAt() (a saving() hook): stamped when the connection enters Disconnected without a timestamp, kept if one is already present, and cleared as soon as the status changes away from Disconnected. SystemConnection::graceDeadline() / isWithinGracePeriod() derive the deadline from it without ever persisting it separately — see Grace period above.

Reconnecting within the grace period. SystemConnectionService::activate() reactivates the existing Disconnected row itself, rather than activating a freshly created one, whenever a sibling with the same tenant_id/system_id/external_user_id is Disconnected. Moving it back to Active runs the Reconnect transition, which does what Activate does and additionally dispatches App\Jobs\RestoreConnectionDataJob with the disconnected_at the row held before the move. It restores only rows whose deleted_at is at or after disconnected_at (rows a reconcile run legitimately removed before the disconnect stay gone) and restores the connection's sync rules the same way, so a rule an admin had already turned off stays off.

Grace period expiry. SystemConnection implements Laravel's Prunable: prunable() selects Disconnected connections whose disconnected_at is older than the configured grace period, and pruning() — the same FK-safe cascade delete App\Jobs\PurgeConnectionJob uses for uninstall — hard-deletes everything belonging to the connection before prune() force-deletes the row itself. The daily model:prune --model=SystemConnection schedule entry (routes/console.php) runs this in chunks of 1000 with per-row fault isolation, so one connection failing to purge does not stop the rest. pruning() re-reads the connection's own state first and refuses (throwing ConnectionNotPurgeable) a connection that is Disconnected and still within its grace period, so a reconnect racing the batch is handled safely — the same guard PurgeConnectionJob relies on for the uninstall path, where it never fires because nothing transitions a connection away from Uninstalled.

Difference from Deactivation and Uninstall¶

See Connection Flow — Deactivation and Reconnection for the wider narrative and ADR-0013 for why disconnect and uninstall are modelled as distinct states.

Uninstall¶

POST /api/system-connections/uninstall is the plugin's signal that it has been physically removed from the merchant's store and Conflux must not retain any of the operator's personal data. It is authenticated by the widget token (the same credential POST /api/system-connections/disconnect uses) and deliberately uses POST rather than DELETE — it reports a business event, not a REST resource removal. The admin panel offers the equivalent UninstallConnectionAction.

The endpoint moves the caller's own connection to Uninstalled through the Uninstall transition and returns immediately. It returns early when the connection already is Uninstalled, so repeating the call is harmless. The transition runs from every state but Uninstalled. It cancels in-progress bus batches and runs two steps synchronously, before dispatching an asynchronous purge:

1. Tokens are revoked and credentials are cleared immediately and irrecoverably, synchronously. SystemConnectionService::revokeAllTokens() hard-deletes every SystemConnectionToken for the connection, and SystemConnectionService::clearCredentials() wipes the credentials column via updateQuietly. Both complete before the endpoint returns a response.
2. All personal data is hard-deleted asynchronously. App\Jobs\PurgeConnectionJob is dispatched and permanently removes, using withTrashed() so already-soft-deleted rows are included too, every LineItem/Order, CustomerConsent/Customer, Product, SyncBatch, and SyncRule belonging to the connection, then its SystemConnectionTokens and WebhookCalls, and finally the SystemConnection row itself — an FK-safe order, since every foreign key uses restrictOnDelete and there are no cascades.

PurgeConnectionJob is the single shared hard-delete mechanism for both uninstall and grace-period expiry (see Disconnect above): it re-checks the connection's status when it runs and only proceeds for Uninstalled connections or Disconnected ones past their grace deadline, so Uninstalled is intentionally short-lived — the connection row itself is gone once the job completes.

Difference from Deactivation and Disconnect¶

See Difference from Deactivation and Uninstall under Disconnect above for the full three-way comparison.

See Connection Flow — Uninstall for the wider narrative and ADR-0013 for why disconnect and uninstall are modelled as distinct states.

Source files¶

See also¶

• Inactive-Connection Data-Flow Gating: how isHealthy() is used at every data-flow entry point and how the transitions cancel in-progress batches on status change
• Connection Flow — how plugin-initiated and tenant-initiated registration work and why the endpoint is unauthenticated
• API Authentication — the connection guard, bearer token setup, EnsureSystemConnectionIsActive middleware, test helpers
• Systems — system slugs used in the system filter
• System Connection Tokens — short-lived tokens used to finalize a system connection, and its own connection-tokens:prune command
• System Connections admin resource: Filament admin panel view of the same model, including the Reactivate, Deactivate, Disconnect, and Uninstall actions
• Sync Batches — the bulk soft-delete pattern CleanupConnectionDataJob follows
• ADR-0013 — why disconnect and uninstall are modelled as distinct states
• ADR-0039: why the status is a state machine with its own row lock and guard