Introduction to App Status

Keeping users informed about ongoing processes and providing descriptive messaging in the event of errors is a crucial component to effective app design. Users interacting with app canvases might need in-place feedback regarding actions they’ve taken with the app, while admins debugging apps may instead require a historical log of app processes. In many cases, this information can be found in the user interface or logs of an external system. But for simpler scripts or integrations where Benchling is the system of record, App Status provides a standardized way for app developers to communicate this and other status information to users in Benchling.

Key Concepts

The two most important concepts to understand how to work with App Status are Sessions and Messages:

• Sessions are the ‘unit of work’ for an app operating on a specific tenant. Think of sessions as individual “jobs” or “tasks” that an app is performing for a specific tenant. Time-bounded and discrete, an app can have concurrent sessions representing distinct operations the app is performing.
• Messages are user-facing communications attached to a specific session. Messages are appended to a session as the app performs a task, and the session’s messages create an immutable log. While sessions can be used alone, messages allow app developers to communicate more granular and descriptive updates for tasks that are in process.

Working with App Status

Before diving into an example of using app status, we’ll first cover the key concepts in more detail. While the use cases for app status vary widely, these concepts are broadly relevant and provide a foundation for building robust applications.

Sessions

A session represents a unit of work performed by an app for a tenant. The size and scope of this “unit of work” will vary from app to app based on the different actions being performed. A session might correspond to a small, short task, or a long-lived task like a legacy data import. In either case, the most important consideration is that sessions have a duration and clear endpoint.

Sessions do not need to be uniform in duration, and an app can have multiple concurrent sessions at any given time. The following are some examples of “units of work” that are a good fit for a single session:

• An interactive wizard using app canvas, allowing a scientist to select a set of codons to be optimized
• A legacy notebook import script that imports data over the course of several days
• A single stage of an NGS pipeline, each stage corresponding to a discrete session

Using Sessions

Apps can create and manage their own Sessions using the Sessions API. An example JSON request body to create a session might look like this:

{
  "appId": "app_197264",
  "messages": [
    {
      "content": "Transferring 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
      "style": "INFO"
    }
  ],
  "name": "Transfer Reagents",
  "timeoutSeconds": 2592000
}

In this example, creating a session involves the following fields (in addition to appId):

Newly created sessions have additional fields that are set by Benchling:

In addition to the createdAt and modifiedAt fields, which are set automatically by Benchling when a session is created and/or updated, the status field is set to IN_PROGRESS by default when a new session is created. An app will later update the session with a terminal status when the session is complete.

Messages

A message represents a discrete update related to a particular session; messages are an optional component of app status that can provide clarity and specificity to users. A message is always tied to a specific Session, and should be used to provide more granular detail on the processes or tasks that the app is completing as a part of a session. Messages are particularly useful for communicating to the user when a process includes a number of small steps, or to provide updates on the status of a long-running task.

A given session can support an unlimited number of messages, though a maximum of 10 messages can be included in a single PATCH request made to update a session. Messages are immutable and will always appear in reverse chronological order. Messages can contain a maximum of 200 characters and can include a maximum of 10 linked Benchling entities (see below). An app canvas will only show the most recent message for a session, while the Benchling admin UI will show up to 100 recent messages.

Using Messages

Up to 10 messages can be included at a time when creating or updating a session; an individual message looks like this:

{
  "content": "Transferred 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
  "style": "SUCCESS"
}

A single message must include a content field, and can optionally include a style field:

Associating a Session to a Canvas

For apps that use app canvas for user interactions, session information can optionally be shown in place on the canvas.

This can be accomplished using the Update canvas endpoint and setting the canvas's sessionId to the associated session:

{
  "sessionId": "sesn_nTUPej8K"
}

As changes are made to the session, such as its overall status or updating messages, they will automatically be shown to a user viewing the associated canvas.

The association can be removed by updating the canvas to set sessionId to null.

Example

Here, we’ll walk through an example of how we can leverage app status to provide information to users. The relevant “unit of work” in this case is completing a transfer of some material into a container. We’ll start by creating a session using the request body from earlier:

{
  "appId": "app_197264",
  "messages": [
    {
      "content": "Transferring 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
      "style": "INFO"
    }
  ],
  "name": "Transfer Reagents",
  "timeoutSeconds": 2592000
}

The session created using the above request looks like this:

{
  "appId": "app_197264",
  "createdAt": "2023-05-22T19:40:52.022Z",
  "id": "string",
  "messages": [
    {
      "content": "Transferring 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
      "style": "INFO"
    }
  ],
  "modifiedAt": "2023-05-22T19:40:52.022Z",
  "name": "Transfer Reagents",
  "status": "IN_PROGRESS",
  "timeoutSeconds": 2592000
}

After a session has been created, it can be updated using the Update session endpoint; updating a session might involve increasing the timeout value, appending new messages based on the updates, or updating the session status.

Once the transfer we’ve initiated is complete, updating our session might look like this:

{
  "messages": [
    {
      "content": "Successfully transferred 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
      "style": "SUCCESS"
    }
  ],
  "status": "SUCCEEDED",
  "timeoutSeconds": 2592000
}

This updates the session to reflect that the session has completed successfully with a status of SUCCESS and a new message with additional details. The final state of the session looks like this:

{
  "appId": "app_197264",
  "createdAt": "2023-05-22T19:40:52.022Z",
  "id": "string",
  "messages": [
    {
      "content": "Successfully transferred 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
      "style": "SUCCESS"
    },
    {
      "content": "Transferring 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
      "style": "INFO"
    }
  ],
  "modifiedAt": "2023-05-22T19:45:52.022Z",
  "name": "Transfer Reagents",
  "status": "SUCCEEDED",
  "timeoutSeconds": 2592000
}

Using app status, we were able to provide real-time updates on the status of the transfer to the user in Benchling. If instead the transfer failed, we might have made a different update to the session:

{
  "messages": [
    {
      "content": "Could not transfer 4ml of {id:ent_a0SApq3z} to {id:con_ae92kBv9}.",
      "style": "ERROR"
    }
  ],
  "status": "FAILED",
  "timeoutSeconds": 2592000
}