Who acts next
A good deployment card answers two questions at a glance: can the customer use the service, and who must act next. These practices apply to every Deployment UX option that shows status in your product: a Deploy button and your own setup screen.
Example UI /Update needs the admin
Document processing
Settings · Deploy in your cloud
Version 13 needs your AWS admin
Version 12 keeps running. Version 13 adds a permission, so an admin must update the setup in AWS.
The card above answers both: version 12 still serves, and the AWS admin acts.
Show it when updateState.active.status is blocked and blocker.kind is setup, while status stays running.
- Read
updateState. A page that reads onlystatusshows "Running" and hides the wait. - No Retry. Only the admin rerunning initial setup moves the update.
- Hand off. Send to an admin shares the link to the portal's Continue update step.
{
"status": "running",
"updateState": {
"active": {
"status": "blocked",
"blocker": { "kind": "setup", "message": "Permission profile \"application\" was modified." },
"actionRequired": "Apply the updated setup to continue this update."
}
}
}Name the actor
Every state has one actor: the customer's admin, Alien, or your team. Put that in words. A customer who sees a spinner for an hour can't tell whether to wait, call their admin, or call you.
| Actor | States |
|---|---|
| The customer's admin | pending, initial-setup, waiting-for-secrets, a blocked update, teardown-required, retention-required, teardown-failed |
| Alien | provisioning, waiting-for-machines, update-pending, updating, delete-pending, deleting |
| Your team | Other failures, delete-failed, and running before your connection test passes |
A failure with an error.hint about a quota or permission belongs to the admin first. See the status map.
Hand off to the admin
The person who clicks Deploy is often not the person who can create IAM roles. A blocked champion abandons initial setup.
- Offer Send to an admin next to every action the admin must take.
- Send the link or the exact command, never a screenshot of your page.
- Say what the admin will do, in one line: "Creates an IAM role and a VPC in your AWS account. About 15 minutes."
- Show the link only to signed-in members of that organization: anyone with it can deploy for the customer.
See Add a Deploy button.
Keep the card honest
After initial setup, keep a compact card for the life of the deployment. A permanent green badge hides failed updates and lost connections.
runningisn't active. Keep your own Active flag, set when your connection test passes. See Verify and activate.- A stale heartbeat isn't an outage. Say "We can't confirm the current state", never Down.
- A blocked update keeps the old release. Say both halves: "Version 12 keeps running. Version 13 needs your AWS admin."
- Removal waits on the admin. Show Removed only at
deletedorretained. See Follow removal.
Test it
- Feed your page every response from Show deployment progress and Follow removal. Check each headline names who acts next.
- Send to an admin. Sign in as another organization and confirm it can't see the first organization's link.
Next
- Status messages: the words to use
- Links and branding: checks before your first customer