Concepts
The customer lifecycle
The states a customer goes through, what each means for its employees, and what you can do in it.
The states
status |
Means | Employees | You can |
|---|---|---|---|
draft |
Saved, not submitted. Nothing is set up. | No access | change, submit, delete (cancel) |
provisioning |
Monotree is setting the company up, usually about a minute. | No access yet | change (all but the company ID), cancel |
live |
In use. The admin has an invitation. | Sign in | change (all but the company ID), suspend, cancel, resend the invite |
failed |
The setup stopped. provisioning.failure_reason says why. |
No access | change (the company ID too), retry, cancel |
suspended |
Access paused, for example while your customer has not paid you. | Cannot sign in; data kept | change, resume, cancel |
cancelled |
Access ended. Deleted once delete_after has passed, 30 days later. |
Cannot sign in | ask Monotree to undo |
deleted |
The company and its data are gone. | – | – |
draft ──submit──▶ provisioning ──▶ live ◀──resume── suspended
│ │ ╲──suspend──▶
▼ ▼
failed ──retry──▶ provisioning
any state ──cancel──▶ cancelled ──30 days──▶ deletedA customer is created provisioning, or draft when you send draft: true. A draft is a sign-up that is not finished: it needs only a company_name, so its company_id, url, country, employees, default_language, admin.name and admin.email can be null and its languages empty. Submitting it checks that everything is there and that the terms are accepted (422 with the missing fields otherwise); from provisioning on a customer always has them all. Each call answers 409 invalid_state when the customer is not in a state it works from:
| Call | Works from | Leads to |
|---|---|---|
| Submit a draft | draft |
provisioning |
| Suspend | live |
suspended |
| Resume | suspended |
live |
| Retry a failed setup | failed |
provisioning |
| Resend the admin invitation | live |
live |
Cancel (DELETE) |
draft |
deleted, at once |
provisioning, live, failed, suspended |
cancelled, then deleted after 30 days |
|
cancelled, deleted |
no change; answers 200 |
|
Change (PATCH) |
every state but cancelled and deleted (409 customer_closed) |
the same state |
Monotree itself moves a customer from provisioning to live or failed, and from cancelled to deleted.
Setup steps
Provisioning is Monotree setting the company up. While a customer is provisioning, provisioning.step names the step it is on and steps_done counts the ones behind it. Each finished step sends a customer.step event: its details.step is the step that finished, and the customer in it is already on the next one.
step |
What happens |
|---|---|
reserve |
A place is reserved for the company on Monotree's platform |
install |
The company is set up with its name and country |
brand |
The logo and colours are applied |
languages |
The languages are switched on |
admin |
The admin is created and invited by email |
checks |
Final checks that everything answers |
When a setup fails
A customer in failed has a provisioning.failure_reason written for a person, for example The company could not be set up. Monotree has been alerted and will look at it. The same sentence is in the customer.failed event, and Monotree is alerted as well. Fix what the reason names, often with a PATCH, then call Retry a failed setup: the setup goes on from the step that stopped, and nothing done before that step is lost. A failed customer is the only submitted one whose company ID can still change, as the ID can be what the setup stopped on.
New steps may be added later: treat a step you do not know as one more step.
Suspending and cancelling
- Suspend when access should pause but the customer may come back. Their data and settings stay; resume gives everything back as it was.
- Cancel when the customer leaves. Access ends at once, and the company with all its data is deleted after 30 days. Until then Monotree can undo it on request. A draft is deleted straight away. A customer can be cancelled while it is still
provisioning: the setup is not finished and it never goes live.
The deletion is not at the stroke of delete_after: once a day, at 03:00 UTC, Monotree takes the customers whose 30 days are over and deletes them. When it is done the customer's status is deleted and a customer.deleted event is sent. Cancelling a customer that is already cancelled or deleted changes nothing and answers 200 with the customer, so a DELETE is safe to repeat.
What deletion removes
When a customer becomes deleted (a draft at once, any other customer when its 30 days are over), the portal removes what it holds about the customer's people and keeps what the statement needs:
| Removed | Kept |
|---|---|
The admin's name, email address and phone: admin is { "name": null, "email": null, "phone": null } from then on |
The customer itself: id, company_name, country, employees, external_ref, seller and its dates |
| Its support threads, with their messages, notes, drafts and files, and the people who wrote | Its daily numbers and adoption alerts, which hold no names |
The text of its escalations to Monotree (description) |
The escalations themselves: title, category, status |
Email addresses inside its events: details.email and details.admin_email are gone, and data.customer.admin is nulls, in List events and in the delivery log |
The events of its timeline: what happened and when |
Its support.* events and their deliveries, which held what was written |
|
| Its logos and, where there was one, the key of its scheduling integration |
The company ID is free to use again. The customer.deleted event already has admin as nulls. Your own system may hold copies of what the events told it: customer.deleted is the moment to remove them.
Two calls at the same moment cannot both act: of two submits (or suspends, resumes, retries) only one goes through, and the other gets 409 invalid_state.
The monthly statement says how suspended and cancelled customers are counted.