punchout-simulator — Operations & Usage Guide

Getting started

Run the tool with no installation:

npx punchout-simulator

It binds to loopback, seeds a demo Buyer, Supplier, Connection and a sample product list on first run, and opens the browser. Useful flags:

Environment variables

Every flag default can also come from the environment, which is convenient for services and CI:

The workspace

The SPA is split into two areas in the left navigation:

• Run — the Sessions tab, where you do PunchOut work.
• Configure — Connections, Buyers, Suppliers, Products, and Buyer Profiles, where you set up the entities a session uses.

Configure the entities once; spend your time in Sessions.

Configuring entities

Buyers and Suppliers

A Buyer is the procurement-platform side: a credential identity, an optional Buyer profile, and optional default ship-to / bill-to addresses and an end-user contact. A Supplier is the catalog side: a credential identity, its punchoutUrl / orderUrl endpoints, the product lists it serves in Mode B, and an allowMixedCurrency flag.

Connections

A Connection binds one Buyer to one Supplier and is the thing a session runs against. It fixes:

• Mode — A (virtual buyer drives the real supplier) or B (virtual supplier serves a mock catalog to the real buyer).
• Shared secret and optional sender identity override.
• Deployment mode and attachment encoding (binary or base64) for OrderRequest attachments.

Buyer profiles

A Buyer profile captures procurement-platform quirks so a buyer emits platform-shaped documents: cXML version, address mode (id-only / full / both), whether ship-to and contact appear in the setup request (shipToInSetup / contactInSetup), and extrinsics. Built-in presets ship for the major platforms — you can clone and customize any of them:

Product lists

A product list is a reusable, named set of catalog items served by Mode-B suppliers. The served catalog is the union of a supplier's assigned lists. Items carry rich fields:

• description, supplierPartId, optional supplierPartAuxiliaryId
• one or more classifications (domain + value, e.g. UNSPSC)
• uom, unitPriceAmount, currency
• allowFractional — when set, the catalog accepts fractional quantities (e.g. 1.5); otherwise quantities are floored to whole numbers.

You can load the built-in sample assortment as a preset, or import items from CSV (header aliases, decimal-comma tolerant). A list that is referenced by a supplier cannot be deleted (the API returns 409).

Running a session

A session is one PunchOut conversation. Start one from the Sessions tab with New session, which asks for:

1. a Connection (which fixes the mode), and
2. an operation — create, edit, or inspect.

For edit and inspect you also pick a source session to take prior cart items from (and inspect can be narrowed to a single item).

Fig. 1: The New-session dialog picks a connection, an operation, and (for edit/inspect) a source cart.

Each session has its own message log — every request and response in that conversation, viewable as raw cXML. This replaced the old global firehose, so parallel sessions no longer interleave.

Every cXML editor and viewer field carries a small Copy + Prettify toolbar: Copy puts the field's content on the clipboard, and Prettify re-indents the XML locally — on read-only fields the formatting is display-only and never mutates the logged document.

Mode A walk-through (virtual buyer)

1. New session on a Mode-A connection, operation create.
2. The setup request is built and shown in Monaco. Click Validate to check it before sending.
3. Send the PunchOutSetupRequest. The real supplier returns a PunchOutSetupResponse with a StartPage link.
4. Open the StartPage and shop on the real supplier's site. On checkout the supplier posts the cart back to the tool's /punchout callback; it appears in the session as a PunchOutOrderMessage.
5. Build and Send the OrderRequest (optionally with attachments). The supplier replies with an OrderResponse.

Mode B walk-through (virtual supplier)

1. Configure a Mode-B connection and assign the supplier one or more product lists.
2. Point the real procurement platform at the tool's supplier endpoint (/sim/:supplierId/...).
3. The platform sends a PunchOutSetupRequest; the tool replies with a StartPage that opens the themed mock catalog.
4. The user shops and checks out; the tool builds a PunchOutOrderMessage and auto-POSTs it to the platform's BrowserFormPost URL.

Operations explained

The operation you choose sets the operation attribute on the outbound PunchOutSetupRequest and what it carries:

What "edit" actually does — both ends

edit is, first, about the outbound document. The buyer-side PunchOutSetupRequest you send declares operation="edit" and includes the prior cart items as ItemOut blocks. A real supplier honours this by pre-loading its cart to that state so the user can adjust it.

The Mode-B mock supplier now honours it too. When it receives an operation="edit" request, it reads the carried ItemOut items (from the session's setup request) and pre-loads the catalog:

• Items the buyer already had that exist in the supplier's catalog show with their quantities pre-filled — change them and return the revised cart.
• Items the buyer had that the catalog doesn't list appear as extra "from cart" rows so the edit round-trips faithfully.

For inspect, the mock supplier shows the carried item(s) read-only and returns them unchanged on checkout — matching the "view this item" intent.

Validation

Every outbound document can be validated before sending with the Validate button next to Send. Validation is bidirectional and field-level; it surfaces typed errors and warnings:

Addresses and contact

A buyer carries optional default ship-to, bill-to, and an end-user contact. The address editor enforces real-world structure:

• Country first — chosen from the ISO 3166-1 list, which sets both the ISO code and the country name.
• State / province — a dropdown for US/CA, free text elsewhere.
• Postal code — format-validated per country where a pattern is known.

How addresses appear on the wire is profile-driven via the address mode (id-only, full, or both) and the shipToInSetup / contactInSetup flags. Order requests default to the buyer's addresses.

Attachments

OrderRequest can carry attachments. The tool assembles a multipart/related body by hand; the attachment encoding (binary or base64) is set per Connection. Many real Ariba/Coupa receivers expect base64; binary is more compact and valid over HTTP. Attachments are stored content-addressed and referenced from the session log rather than inlined.

Managing sessions

• Per-session log — select a session to see only its messages.
• Resume — a historical Mode-A session can be resumed; the tool reconstructs the flow state (StartPage, last status) from the session's records.
• Export PDF — capture the whole flow as test evidence: every exchanged message with its validation result, HTTP status, timestamps, and attachment list. The export opens a print-ready report and hands it to the browser's native "Save as PDF" (no PDF library involved); the paper size follows your locale (Letter in the US/CA region, A4 elsewhere).
• Delete — remove a session and its log. Deletion is path-guarded so only files inside the sessions directory can be removed.

Data and storage

Everything lives under the data directory:

• config.json — the normalized entities (buyers, suppliers, connections, profiles, product lists). Migrations run automatically at boot.
• sessions/<sessionId>.jsonl — one append-only log per conversation.
• attachment blobs — content-addressed, referenced from records.

To start clean, stop the tool and delete the data directory (or point --data-dir somewhere fresh). To archive a conversation, copy its .jsonl file.

Corporate proxies

On a locked-down corporate network (commonly Windows), direct outbound connections are often black-holed: every browser works (it uses the OS proxy), but a server-to-server PunchOutSetupRequest hangs and dies as "HTTP 0 / operation aborted". Node's fetch does not honour proxy environment variables on its own — unlike curl or Postman — so the tool wires them in explicitly.

Routing outbound cXML through a proxy

Set the standard variables before starting the tool:

HTTPS_PROXY=http://proxy.corp.example:8080 npx punchout-simulator

• HTTP_PROXY / HTTPS_PROXY (upper- or lower-case) route the outbound Mode-A traffic (SetupRequest, OrderRequest).
• NO_PROXY lists hosts that bypass the proxy. Loopback (localhost, 127.0.0.1, ::1) is always added automatically, so the tool's own self-calls and any localhost supplier never go through the proxy.
• Credentials in a proxy URL (http://user:pass@host:port) are redacted everywhere the URL is displayed or logged.

Knowing what is in effect

The startup banner always prints a proxy: line with one of three findings:

For the third case the tool reads the OS-level configuration (best-effort, read-only): the Windows registry, macOS network settings (scutil), GNOME settings, and KDE's kioslaverc — including PAC scripts and WPAD auto-detect. A PAC/WPAD setup hides the concrete proxy host inside the script, so the banner points you at the PAC URL (or IT) to find the value for HTTPS_PROXY.

The same status appears as a proxy badge in the app header, so it stays visible when the banner has scrolled away or the tool runs as a service.