Simulation Controls¶
Eight controls drive a simulated contract through everything a real marketplace does to one. Every control drives the production state machine — none of them writes a fulfillment state, a subscription status or a usage row directly. That is the whole value: a control that took a shortcut would certify nothing, because what you rehearsed would not be what happens when a real buyer arrives.
Two consequences worth stating plainly, because they surprise people:
- Simulating a purchase really does create a buyer organization, a synthetic root user and a subscription request in
PENDING. You approve it like any other. - Simulating a cancellation really does tear the simulated tenant down.
The Controls¶
| Control | What it simulates | Where it applies |
|---|---|---|
purchase | A buyer completing a checkout | Arms one on the channel; creates nothing until they arrive |
plan_change | The buyer moving to a different plan | A contract past AWAITING_ISV |
quantity_change | The buyer adding or removing seats | A contract past AWAITING_ISV |
suspend | The marketplace suspending, usually non-payment | An active contract |
reinstate | The suspension being lifted | A suspended contract |
cancel | The buyer cancelling or the term expiring | Any live contract |
release_usage_gate | The marketplace licensing usage | A hard-gated contract |
stall_handoff | Nobody confirming, past the SLA | A contract in AWAITING_ISV |
Every control except purchase names the contract it acts on. purchase is the one that brings a contract into being, so there is nothing to name yet.
purchase¶
Arms a purchase on the simulated marketplace and creates nothing in Omnistrate — exactly as a real marketplace holds a checkout a buyer has not completed.
What comes back is a checkout link. Following it runs the real landing route, and that is what creates the contract and starts fulfillment.
Why arming and arriving are separate
An earlier version created the contract at arming time and started fulfillment immediately. That rehearsed a sequence that does not exist: fulfillment beginning with nobody having arrived, and the landing route — the handler every real buyer goes through — never running at all. Separating them means the rehearsal walks the production path instead of a shortcut around it.
plan_change and quantity_change¶
The buyer changed what they bought. Both re-read the entitlement and adjust the contract, and both emit entitlement.updated to a registered receiver.
Use these to check that your integration adjusts limits rather than re-provisioning, and that it tolerates a change arriving for a tenant it already serves.
suspend and reinstate¶
suspend moves the contract to suspended, which blocks deployments. It is what non-payment looks like. reinstate puts it back.
Your integration should restrict access on a suspension and not delete data — a suspension is frequently temporary, and a reinstatement follows.
cancel¶
The contract is cancelled or expired. Fulfillment drives to CLOSED and the simulated tenant is torn down. This is the control to use when you are finished with a rehearsal contract, and it is the only thing that ends one: there is no delete for a contract, deliberately, because the mirror is a record of what a channel said.
release_usage_gate¶
Opens the usage gate, through the same activity a real AWS License Updated event uses. That shared path is what makes rehearsing the hard-gated case a test of the production gate rather than of the console.
Only meaningful on a channel whose usage gate is HARD. On a SOFT gate, usage is reported from activation and there is nothing to release.
stall_handoff¶
The contract sits in AWAITING_ISV past its SLA, so you can watch the orphan alarm fire and see the paying-and-cannot-use-it quadrant light up on the contracts strip.
This is the control that rehearses your failure rather than the marketplace's: what an operator sees when your confirm never arrives. A contract in that state emits fulfillment.failed.
fulfillment.failed does not carry the handoff token
The token only ever rides on contract.discovered. The token outlives the deadline, so if you still hold it you can confirm after a stall — but a failure event alone will not give you one.
Driving them from the console¶
Each control appears on the simulated contract itself rather than on the sandbox page, because every one of them except purchase acts on a contract that already exists. Open the contract from Marketplace Contracts and the channel controls sit beside the fulfillment actions.
That placement is deliberate: it puts what the marketplace does next beside what you do next, on the one screen that shows the consequences of both.