Overview

A plugin is code that BioT calls when an event it subscribes to occurs. You can deploy a plugin in one of three ways:

• Using the Plugin Configurations page in the BioT Console, which provides a UI for uploading, updating, and deleting plugins without API calls.
• Using the BioT plugin deployment API.
• Deploying the plugin under your own account and supplying BioT with a URL to call when the plugin needs to be invoked.

Deploying Under the BioT Account

Deploying under the same account that hosts the BioT platform has several benefits:

• Almost no latency between BioT and the implementation.
• You will not have to use two cloud accounts to manage your cloud solution.
• All security configurations will be handled by BioT.

The following restrictions apply when deploying under the BioT account:

• The solution must be compatible with and based on the AWS Lambda solution.
• The plugin will only have network access and will not be able to access other AWS services like RDS, S3, etc.

Plugin Deployment

Plugin deployment for a zip file is composed of the following stages:

1. Clone our sample code
2. Update the code with your required changes
3. Zip the code
4. Make a create plugin API call

Plugin deployment for Docker is composed of the following stages:

1. Call the /settings/v2/plugins/docker-repository/temp-credentials API and save the response. The credentials are valid for one hour.
2. Clone our sample code
3. Update the code with your required changes
4. Run login.bat/sh script
5. Run BuildAndPush.bat/sh script and keep the "imageTag"
6. Make a create plugin API call with the additional "imageTag": "string" and "deploymentPackageType":"IMAGE" keys added into the config parameter.

For a Docker image, the runtime and handler are taken from the Dockerfile, so they appear as null.

Plugin API call

Make the following API call:
POST https://your-domain.com/settings/v2/plugins

This is a "multipart/form-data" request that includes both the binary zip file and configuration information. See here for more details.

The form should include 2 parameters:

1. "code": the binary zip file - this is optional, and if not supplied, the API will use the sample code as a default "seed" plugin. For a Docker image, this is not relevant, and you don't need to pass this parameter.
2. "config": JSON configuration of the plugin.

This is an example of a multi-part call.
The first section describes the zip file and then passes the zip file content. The second part is the configuration.

-----------------------------
Content-Disposition: form-data; name="code"; filename="hw.zip"
Content-Type: application/x-zip-compressed

<ZIP_BINARY_DATA>
-----------------------------
Content-Disposition: form-data; name="config"

{
   "name":"demo_plugin",
   "displayName":"Demo Plugin",
   "version":"2",
   "timeout": 10,
   "handler": "index.main",
   "runtime": "python3.12",
   "environmentVariables":{
      "var1":"val1",
      "var2":"val2",
      "var3":"val3"
   },
   "subscriptions":{
      "interceptionOrder":"2",
      "interceptions":[
         {
            "type":"POST_REQUEST",
            "apiId":"POST/organization/v1/users/patients",
            "entityTypeName":"<String>",
            "order":"5"
         }
      ],
      "notifications":[
         {
            "entityTypeName":"<String>",
           	"actionName":"<String>",
						"templateName":"<String>"
         }
      ]
   }
}

If successful, the return value will be 201 Created with a JSON describing the newly created plugin.

{
   "name":"demo_plugin",
   "displayName":"Demo Plugin",
   "version":"2",
   "environmentVariables":{
      "var1":"val1",
      "var2":"val2",
      "var3":"val3"
   },
   "subscriptions":{
      "interceptionOrder":"2",
      "interceptions":[
         {
            "type":"POST_REQUEST",
            "apiId":"POST/organization/v1/users/patients",
            "entityTypeName":"<String>",
            "order":"5"
         }
      ],
      "notifications":[
         {
            "entityTypeName":"<String>",
            "actionName":"<String>"
         }
      ]
   },
  "enabledState": "DISABLED",
  "cronSchedule": "45 1/12 1-5 JAN,OCT ? *",
  "deploymentPackageType": "ZIP",
   "endpointUrl":"https://aws.....",
   "linkToConsole":"https://aws.....",
   "creationTime":"2022-11-09T14:22:01.879Z",
   "lastModifiedTime":"2022-11-09T14:22:01.879Z"
}

Clone our sample code

See plugin sample code

Update the code with your required changes

Use your favorite IDE to make modifications to the code.
We encourage you to use your own Git repository to track changes to the sample plugin and later on automate plugin deployment.

Zip the code or create Docker image

Zip the root directory of the plugin. If the code is stored in a Git repository, leave out the .git folder and the .gitignore file. For a Docker image, build and push the image, and use the returned imageTag in the create or update plugin API call.

Make an update plugin API call

Updating a plugin is very similar to creating it. Prepare your plugin code and zip in the same way you first created it.
Make the following API call:
PUT https://your-domain.com/settings/v2/plugins/{name}

The request body and response are the same as in the plugin creation. See the Create Plugin API reference.

Plugin Deletion

To delete a plugin, make the following API call:
DELETE https://your-domain.com/settings/v2/plugins/{name}

The deletion process will remove the code from the cloud and all the interceptors and notifications associated with it.

Deploying Under Your Own Account

If you decide to deploy your code under your own account, then there will be no restrictions on the way the callback should be implemented.
The only requirements are that the exposed URL is HTTPS and public, and that there are no security measures that will block BioT from reaching this endpoint URL.
Securing the communication between BioT and the function code will be done by utilizing JWT. BioT will send a signed token that will have to be verified by the function before executing its custom code.

To register your external service for BioT events, see Interception and Notification Subscription.
Also, for the plugin to be able to make API calls to BioT, you'll have to create a service user and use its credentials from inside the plugin. See Creating a Service User for Your Plugin.