Tenant status

•

Environment: cloud

• 3 minutes to read

The state of the tenant indicates if a tenant is available to receive requests, and it is recommended you always know the state of the tenant before sending any requests to the API. There are two ways to know the tenant status, either by checking its status through the API (Pull) or receive notifications when a tenant changes status (Push). These options are fundamentally different, proactive vs reactive, and its up to the developer to decide which option(s) makes the most sense for the application.

Checking tenant status (Pull)

This is a proactive means to determine the current status of a tenant. Your application precedes each API request with a call to the state endpoint to ensure the tenant is in a Running state.

sequenceDiagram
    participant Client
    participant SuperOffice

    Client->>SuperOffice: GET ../api/state/CONTEXTID
    SuperOffice-->>Client: HTTP Response (200 OK, JSON)
    Client-->>Client: Check state
    Client->>SuperOffice: Business Logic

The state signals wether the tenant is available for handling API requests.

Receive tenant status (Push)

Subscribing to a webhook is a more reactive flow that sends notifications each and every time a tenant state changes. SuperOffice sends out a notifications payload and gives you a chance to manage tenant customer states better.

To receive notifications, application vendors must provide a State Change URL that specifies where SuperOffice sends notifications. This can be done through the developer portal, and is described further down in this document.

Notifications ensure that vendors are aware when the states of their customers change, for example, their SuperOffice subscription and that they know when tenants are unable to respond to requests.

When SuperOffice upgrades a tenant, for example, SuperOffice looks at each application approved by the tenant and sends out a notification to each one to indicate that the tenant is about to be upgraded. This provides the application an opportunity to know when a tenant going to be unavailable and why communications with that tenant cease until further notice.

sequenceDiagram
    participant SuperOffice
    participant Client

    SuperOffice->>Client: POST (JSON)
    Client-->>Client: Check state (Pause/Stop?)

Not only does that provide advanced notice when tenants are upgraded to new versions of SuperOffice, but it can signal whenever a customer has canceled a subscription (Delete).