Connect Magento

Bring Magento orders, line items, status changes, and proof approvals into Fibric as governed events, read incrementally from a cursor so a restart never re-reads the store. This guide covers creating a REST integration token, scoping it, installing the cn-magento connector, verifying the event streams, and diagnosing the failures you are most likely to hit.

The cn-magento connector runs in production today under BearScope, Fibric's flagship product, on live specialty-commerce orders. It senses orders and line items as they are placed and change status, proof approvals with their revisions and customer responses, and invoice and shipment records tied back to the originating order. Its writes are deliberately few: order comments and status updates within the transitions you allow, both idempotent, so a retry is a safe no-op. See Connectors for the general model.

#Prerequisites

In the Magento admin, go to System → Extensions → Integrations and choose Add New Integration. Name it so its purpose survives an audit, for example fibric-connector-prod, then open the API tab and set Resource Access to Custom. Do not grant All: the connector needs sales resources, not your catalog, customers, or configuration.

#Required resource scopes

Save, then choose Activate on the integration's row and approve the resource list. Magento shows four credentials; the connector uses the Access Token, which it sends as a bearer token on every request. Copy it now, it is only shown while the dialog is open.

Add cn-magento from the marketplace and bind it to the commerce role. Operators ask for commerce capabilities such as order.read, never for Magento by name, so moving storefronts later is a rebinding, not a rewrite. The CLI prompts for the access token and stores it in your tenant's secret store; it never writes it to disk.

# find the connector, then install it bound to the commerce role
fibric connectors search magento
fibric connectors add cn-magento --as commerce \
    --connection magento-prod \
    --config '{"base_url":"https://store.example.com","store_code":"default"}'

#Configuration parameters

Non-secret configuration is passed with --config and lands in the connector's ctx.config. Credentials never go here.

Installing a connector exposes capabilities; it grants nothing. An operator gets exactly the capabilities you list in its manifest, and the deterministic executor blocks anything else by omission. List what the connection now exposes:

fibric capabilities ls

An order-risk operator senses through order.read and proof.read and typically writes only order.comment.write. Status writes are the sharper tool: they are constrained twice, once by allowed_transitions in the connector config and once by trust policy. See Capabilities for the indirection and Catch order risk early for the worked example against this connector.

# governs writes back into Magento. default is deny.
policy: commerce-writes
rules:
  - allow: order.comment.write
    limit:
      per: hour
      max: 100
    single_flight: order_id   # one write in flight per order
  - allow: order.status.write
    limit:
      per: hour
      max: 25
default: deny

fibric policy apply ./policy.yaml
fibric policy validate commerce-writes

Magento does not push. The connector's event streams are declared poll, and each stream keeps a cursor: the updated_at high-water mark of the last record it turned into an envelope. On every cycle it queries the REST API with search criteria filtered above the cursor, emits one envelope per changed record, and advances the cursor only after the envelope is durably written. A restart resumes from the stored cursor, so it never re-reads the whole store and never drops an order that changed while the connector was down.

Two consequences worth knowing. First, the first sync is shaped by backfill_since: set it to ingest history, leave it unset to start from install time. Second, because updated_at has one-second granularity, the connector re-reads the boundary second on each cycle and relies on envelope-level deduplication to keep the stream exact. Duplicate suppression is by record identity and change time, not by hoping the clock cooperates.

#Event streams and emitted event types

Every event is a tenant-scoped event envelope with source: "magento", a dotted event_type as above, and a correlation_id that ties an order's events together across streams.

Place a test order, or edit any existing order, then tail the event stream. With the default poll_interval of 60s, expect the envelope within about a minute of the change.

fibric events tail --source magento

Then confirm the write path with a dry run. Side-effecting tools dry-run by default: input validation and the trust evaluation execute, the handler does not.

fibric connectors test cn-magento order.comment.write \
    --connection magento-prod \
    --args '{"order_id":"SO-10944","comment":"connectivity check"}'

#Common failures

Every failure below is visible in fibric connectors test output or in receipts; the connector's probe reports the first three on install.

#Next steps

• Catch order risk early: the operator this connector was built to feed.
• Connect Kustomer: pair order state with the support conversations about those orders.
• Build an ops analyst: an operator that reads across both sources and reports.
• Write guardrails that hold: the trust policy patterns behind step 3.
• Events API: the same stream, programmatically. Governance & trust covers the decision model end to end.