Custom Plugin Deployment
Overview
To register for a callback from BioT, you (the developer) must supply BioT with a callback endpoint URL. The URL can be of an API that resides anywhere in the world and does not have to be hosted in AWS cloud.
You have 2 options to deploy a plugin.
- Using the BioT plugin deployment API which deploys your plugin in the same VPC as the platform.
- Deploy the plugin on your own and supply BioT with a URL to call when the plugin needs to be invoked.
To make sure the plugin responds quickly to BioT calls, it is recommended use the first option.
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 configuration will be handled by BioT.
The following restrictions apply when deploying under the BioT account:
- The solution must be compatible and based upon 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 Prerequisites
By default, BioT assumes several parameters about the plugin:
- Plugin Architecture: x86_64
- Ephemeral storage: The size of the function’s /tmp directory is set to 512 MB.
- Memory Size: 128 MB
- Runtime environment: nodejs16.x
- Timeout: Max execution time 3 seconds
- Main file name: index.js
- Main function name: handler()
You can update some of these values:
- The runtime engine can be set to one of the supported values.
Use the "Identifier" value from the list in the following link:
Lambda runtimes - The main function name can be changed from handler().
- The Lambda timeout can be changed from 3 seconds. Max value is 900 seconds.
First Time Deployment
If during the first plugin deployment you do not supply a zipped plugin code, the platform will use default plugin code that can be found here.
When you feel that you are ready to make modifications, clone this repository, modify it and zip it.
Supply the zip file during the plugin deployment and it will override the old deployed plugin.
Plugin Deployment
Plugin deployment is composed of the following stages:
- Make plugin deployment API call
- Clone our sample code
- Update the code with your required changes
- Zip the code
- Make an update plugin API call
Plugin API call
Make the following API call:
POST https://your-domain.com/settings/v1/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:
- "code": the binary zip file - this is optional and if not supplied the API will use the sample code as a default "seed" plugin.
- "configuration": 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.
-----------------------------285212099334590670861736535119
Content-Disposition: form-data; name="code"; filename="hw.zip"
Content-Type: application/x-zip-compressed
<ZIP_BINARY_DATA>
-----------------------------285212099334590670861736535119
Content-Disposition: form-data; name="configuration"
{
"name":"demo_plugin",
"displayName":"Demo Plugin",
"version":"2",
"timeout": 10,
"handler": "main",
"runtime": "python3.10",
"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>"
}
]
}
}
-----------------------------285212099334590670861736535119--
Parameter | Description | Format |
---|---|---|
name | Unique plugin name. A prefix "Plugin-" will be added to it. Mandatory. | String |
displayName | The display name of the plugin. It will be added to environment variables with a reserved key. Mandatory. | String |
version | The plugin version number. Mandatory. | Integer |
environmentVariables | A map that contains environment variables as key value pairs, keys starting with "BIOT_" are reserved for system use. Optional. | JSON |
interceptionOrder | The order in which this plugin will be executed if more than one interceptor exists for the API. This parameter applies for all interceptors and should be greater than 1. Mandatory. | Integer |
interceptions | A list of interceptors APIs that this plugin will handle. Optional. | JSON |
interceptions.type | The type of the interceptor: PRE_REQUEST POST_REQUEST * ADAPT_ENTITY Mandatory | String |
interceptions.apiId | The ID of the API that you want to subscribe to. This only applies to PRE_REQUEST & POST_REQUEST types. For possible values, see the API documentation for the service you are subscribing to. Optional. | String For example: POST/organization/v1/users/patients |
interceptions.entityTypeName | The entity name that you want to modify. Provided only if type=ADAPT_ENTITY. For possible values, see the API documentation for the service you are subscribing to. Optional | String For example: patient |
interceptions.order | Override for the interceptionOrder parameter.Optional. | Integer |
notifications | A list of notifications APIs that this plugin will handle. Optional. | JSON |
notifications.entityTypeName | The entity type that you would like to be notified about. See the API documentation for available values. Mandatory. | String |
notifications.actionName | The action performed on the entity that you would like to be notified about. See the API documentation for available values. Mandatory. | 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>"
}
]
},
"endpointUrl":"https://aws.....",
"linkToConsole":"https://aws.....",
"creationTime":"2022-11-09T14:22:01.879Z",
"lastModifiedTime":"2022-11-09T14:22:01.879Z"
}
Parameter | Description | Format |
---|---|---|
endpointUrl | The endpoint URL for the newly created plugin | String |
linkToConsole | Direct link to the AWS console where the plugin was deployed | String |
Clone our 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
Zip the code by zipping the root directory of the plugin. You need to omit the .git and git ignore files if the plugin code stored in a GIT repository.
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/v1/plugins/
The request body and response are exactly the same as in the plugin creation.
See here
Plugin Deletion
To delete a plugin make the following API call:
DELETE https://your-domain.com/settings/v1/plugins/
Note
When calling the DELETE plugin API you need to add "Plugin-" prefix to its name.
For example if the plugin name is "add_data", you need to pass "Plugin-add_data" to the API call.
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 the plugin to events see the notification and interceptors documentation.
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 plug. Refer to the service user documentation for more information.
Updated 13 days ago