App Builder · Ep 10: port a small Adobe Commerce module to App Builder

Step 1 of 6

Every earlier episode was a building block. Now they go together on a module that sends new orders to an external fulfilment API. Most Adobe Commerce (Magento 2) projects have one like it. Plan on half a day.

I ran this port on a Commerce Cloud staging, with an App Builder Stage workspace next to it. The module is an observer on sales_order_place_after that POSTs the order to an ERP, with a cron job and a retry table for the calls that fail. The app version listens for the same event and sends the same order. Both pointed at one fake ERP, so I could compare what each one sent.

What the side-by-side run showed:

  • Payload: the order lines and the address were identical, once the subscription asked for order.addresses.
  • Timing: on a normal order the app delivered 9.1 s after the module. The module sends inside checkout; the app sends after it.
  • Retries: with the ERP address broken for both, both queued the order. The module's budget is 6 attempts, 10 minutes apart, and it delivered on attempt 6, its last one. The app resent from its 10-minute retry run.
  • Switch-over: with the module disabled, a new order reached the fake ERP from the app only.

You’ll need

Write down what the module does

Before moving anything, list its behaviour: which event triggers it, what data it sends, what it does on failure, which config it reads, what it shows in the admin. That list is your acceptance test, and the one place the two versions have to agree.

In the moduleIn App BuilderEpisode
Observer on sales_order_place_afterCommerce event subscription, with only the fields the API needs, handled by an action6
Cron job that retries failed callsAlarm trigger that runs the retry action3
Failed deliveriesThe export_runs collection; State keeps only the lock4
API keys in Commerce configThe action's environment, injected at deploy time
Status in the adminAdmin UI SDK page: recent deliveries, failures, a retry button9

Replace the observer with an event

Subscribe to the order event with only the fields the external API needs (episode 6). Fulfilment can’t ship without an address, so here the address is one of them. Your action receives the event and calls the fulfilment API. The order sits under order in this event, so every field starts with order.. --fields=order.items sends every field of every item; once you know which ones the API reads, list just those with order.items[].sku notation. A path that matches nothing is dropped without an error (episode 6), so place one test order and look at the payload before go-live. That check caught one for me: order.shipping_address arrived as null, because the order data has no such key. The addresses sit under order.addresses, and the mapper picks the shipping one from there.

bin/magento events:subscribe observer.sales_order_place_after \
  --fields=order.increment_id --fields=order.items --fields=order.addresses

If the project has two event providers, add --providerId with the one your registration listens on. Without it the subscription goes to the default provider, and the app never sees the event.

Move the retry logic

The module probably retried failed calls with a cron job. In App Builder, an alarm trigger from episode 3 runs the retry action, and failed deliveries live in the export_runs collection from episode 4, where the admin page can read them. State keeps only the lock. Keep every call idempotent, using the order number as the key.

The real run caught one bug here. With aio-lib-db 1.1.0, findOne does not return null when nothing matches. It throws a DbError ("Document not found"), so the first lookup for a new order made the action answer 500. I/O Events redelivers a 500, so the events went through once the fix was deployed. The fix is a small wrapper that treats exactly that error as null and rethrows the rest, so a real outage is not hidden:

const NOT_FOUND = /failed(?: with code 404)?: Document not found$/
async function findOneOrNull (runs, filter) {
  try {
    return await runs.findOne(filter)
  } catch (e) {
    if (e && e.name === 'DbError' && NOT_FOUND.test(String(e.message))) return null
    throw e
  }
}

Move the config and the status page

API keys move from Commerce config to the action’s environment, injected at deploy time. The admin page from episode 9 shows recent deliveries, failures and a retry button.

Run both side by side, then switch

Deploy the app with the external call pointed at a sandbox, and run it alongside the module for a few days. Compare what each one sent. When they match, disable the module’s observer and point the app at production.

On a shared staging, the app side exports every order, because it has no test filter. Mine exported an order that wasn't one of my test orders. Filter on your side, or use a staging of your own.

Weigh what you gained against what you added

Better: the module no longer blocks order placement, an upgrade can’t touch it, and the logic is testable on its own. Harder: another deployment pipeline, another place to look when things fail, and latency you now have to monitor. For a module like this, the trade is worth it. For a module that changes checkout totals, it wouldn’t be: episode 0 covers when to keep a module instead.

Tested on: a real Stage workspace, against a Commerce Cloud staging and a fake ERP. The export-order action, registered as the only consumer of sales_order_place_after, received real orders and sent them, with the nested --fields order.items and order.addresses. The export-order-retry alarm ran every 10 minutes. The export_runs collection recorded the sent rows. In the side-by-side run the lines and the address matched the module's, the app was 9.1 s behind the module on a normal order, and the failure test queued the order in both senders and delivered it from both. After the module was disabled, only the app sent.

Not tested: the dead state when either side runs out of retries, the admin Retry button, and extension packaging. The current list is in the repo README.

Done!

That’s the foundations, from a first action to a ported module. From here the series continues as a developer log.

> code for this episodeGitHub · ep10-port-a-module →Agent hand-off →

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More