Introduction

What is a plugin?

Envoy plugins are self-contained applications that interact with Envoy via either (or both) of the following:

  • listening for and reacting to events within Envoy

  • making calls to the Envoy API

Plugins can be installed by an Envoy customer through the Integrations page in the dashboard. They can be installed either at the company or location level.

How are plugins built?

The original (V1) plugins were built as Node.js Lambda functions, and relied heavily on a custom SDK to wrap the Lambda-specific architecture and to interact with Envoy. Deploying these plugins relied on a custom CLI to perform the various operations.

The new (V2) plugins are built as web apps, which can be written in any language. Plugins are defined and registered with Envoy via the Integration Builder in the Envoy Dashboard. They can be deployed on any platform, so long as the URLs to their various endpoints are defined in the Integration Builder.

Key Concepts

  • Job - A combination of an event + plugin. E.g. when an "entry sign in" event is fired, each plugin listening for that event has a "job" created for it. This entity allows us to attach metadata to that event on a plugin-by-plugin basis. Jobs have a status, message, and attachments (optional), all of which can be updated by the plugin.

  • Worker - a plugin endpoint, used to respond to a Job. They are the Job's event handlers.

  • Route - a plugin endpoint, used to send or receive data. These endpoints are proxied though Envoy Web. For V1 plugins, routes were mostly used to supply data during the installation process, though other routes could be used as webhooks, or even to serve front-ends. For V2 plugins, routes are limited to being used to supply installation data, since V2 plugins are web apps anyway, negating the need for the Envoy Web proxy, except during setup.

  • Release - each time a plugin is updated, a release is created. Each release encompasses the current definition of that plugin. This definition is called a manifest.

  • Manifest - a JSON object that defines a plugin. It describes things such as setup steps, what events the plugin listens for, and what routes are available. For V1 plugins, this was a physical file included in the plugin repo. For V2 plugins, the manifest is created by the Integration Builder UI.

  • Installation - an entity representing the installation of a plugin at a specific company or location. This entity is useful for storing and isolating plugin config data as well as plugin storage.

  • Config/env - during installation, customers are typically asked to input data or log in to some external system. This data is stored in the plugin config, and is made available to the plugin on each invocation (either a route or worker invocation). The variable that typically represents this config is called env.

  • Storage - a back-end key/value storage that plugins can use to save data. This storage is not visible anywhere except to plugins, which makes it a good choice for sensitive data like passwords. While it is mostly used by workers to store data, routes may opt to use it to store passwords instead of saving them in the config, which is visible to the Envoy dashboard.

  • Attachment - useful data that can be tied to a job. They show up on the right-hand sidebar in the Envoy dashboard when viewing a visitor or invite. E.g. wi-fi plugins often attach the generated password to "entry sign in" jobs so that they are visible to administrators.