Skip to navigation
App Reference

App Manifest Reference

A tenant-independent definition of a Benchling app, containing everything required to install it. Unlike apps created “from scratch,” apps created from a manifest can support custom configuration, interactive components, and more.

There are a number of important fields that can be included in an app manifest:

  • A manifest’s info field contains metadata about an app like name, version, and description
  • A manifest’s settings field contains technical details related to app installation and webhooks
  • A manifest’s configuration field contains configuration options to be configured by a tenant admin
  • A manifest’s features field contains interactive components through which Benchling users can interact with the app
  • A manifest’s security field contains keys used to encrypt app config values

In this reference, we’ll cover all of the supported fields and values an app manifest can have for these components, as well as some other minor components of the manifest. For more detailed information on these component’s functionality, check out the corresponding guides for Managing and Sharing Benchling Apps and App Canvas.

App info

The info field of an app manifest contains basic information about the app. Right now, info contains the name, description, and version fields:

FieldDescription
nameThe name of the app
descriptionA brief description of the app and its functionality
versionThe version number of the manifest; supports semantic versioning

App configuration

The configuration field of an app manifest contains the set of configuration options used by the app. The full list of all supported config types can be found in the Benchling reference documentation; click the “Schema” view to see details on the config field types:

The Benchling API reference showing the app configuration item schema, with the config item subtypes expanded
The OpenAPI schema for Benchling app configuration

App configuration items are more complex than the key-value pairs of previous fields; app configuration items are grouped into the types below, with some (like EntitySchemaAppConfigItem) having multiple subtypes.

Config Item TypeDescriptionExample Value
DateAppConfigItemA date value; YYYY-MM-DD format2022-01-01
DatetimeAppConfigItemA datetime value; YYYY-MM-DDTHH:SS format2022-01-01T12:30
JsonAppConfigItemA JSON object{"abc": "123"}
EntitySchemaAppConfigItemAn entity schema in Benchling; can have subtype any of aa_sequence, dna_sequence, custom_entity, mixture, molecule, dna_oligo, rna_oligo, rna_sequencets_e59sjL23
FieldAppConfigItemAn entity schema field; sub-field of an entity schema config itemtsf_e59a3b23
BooleanAppConfigItemA boolean valuetrue
IntegerAppConfigItemAn integer value1
FloatAppConfigItemA float value1.0
TextAppConfigItemA text valueuser configured text
GenericApiIdentifiedAppConfigItemAn entity instance in Benchling; can have subtype any of container_schema, plate_schema, location_schema, box_schema, run_schema, result_schema, request_schema, entry_schema, workflow_task_schema, dropdown, dropdown_option, registry, folder, entry, worklist, project, workflow_task_status, dna_sequence, dna_oligo, aa_sequence, custom_entity, mixture, molecule, rna_oligo, rna_sequence, box, container, location, platebfi_HtrsAIid
SecureTextAppConfigItemAn encrypted secure value; must include publicKey (see below)eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...

App features

The features field of an app manifest contains information related to the app’s interactive components, currently limited to App Canvases that can appear in notebook entries, Connect runs, and on the app homepage.

FieldDescriptionExample Value
nameThe feature nameCodon optimization
idAn externally defined unique identifier for the featurecodon_optimization_1234
typeWhat type of feature the app is exposing and whereCANVAS

Learn more about App Canvas, including the blocks a canvas can contain.

Subscriptions

The subscriptions field of an app manifest holds the app’s subscriptions to webhooks. Most events need to be explicitly subscribed to via the app manifest, including app lifecycle events and canvas interaction events. Currently, the only exception is the v2.app.installed event, which all apps with a valid webhook url receive regardless of whether a subscription to it is specified in the app manifest.

FieldDescriptionExample Value
deliveryMethodCurrently, always WEBHOOKWEBHOOK
messagesThe list of messages that the app should receive
typeThe type of messages that the app should receivev2.canvas.initialized

App security

The security field of an app manifest contains information related to app security and encryption. Right now, this includes the publicKey field:

FieldDescriptionExample Value
publicKeyA public key corresponding to a public-private key pair; used to encrypt secure_text configuration values-----BEGIN PUBLIC KEY----- … MIIBIjANBgkqhkiG9w0BAQEFAAOC … -----END PUBLIC KEY-----