BioT Interceptor Plugins

BioT Interceptor plugins are lambda code that is called before or after an API call and lets the plugin modify the call request or response accordingly. The plugins are useful when you want to modify an API request before it is processed by BioT or modify the response before it arrives to the UI.

Flow Example

Types of interceptions

There are 3 types of interceptions:

PRE_REQUEST - intercept before executing the API code (before the request reachs the controller). Here you will be able to change the request JSON body, the query parameters, the headers, the path (which means you can navigate the call to a different API on the same service) and also fail the API call
POST_REQUEST - intercept after executing the API code (after the controller has sent a response). Here you will be able to change the response JSON body and the http status code
ADAPT_ENTITY - same as POST_REQUEST but this interception type is not per API but per entity. All of the APIs related to this entity (create,update,get,search,more..) that return the entity object will be intercepted if there is a subscription for this entity. Here you will be able to customize the entity(ies) that will be returned and the http status code. For CRUD or operation APIs the entities array will contain 1 object, for search API the entities array may contain zero or more objects

Subscribing to Events

To subscribe a BioT plugin to interception events, configure the interceptions array as part of the plugin creation or update. Alternatively, you can manage plugin subscriptions directly via the BioT Console. For full details on both options, see Custom Plugin Deployment and Plugin Configuration Management.

📘
Possible interceptions
Not all API calls can be intercepted. To find out which can, please use this API call.
When the apiId contains a path parameter, you can substitute a specific value to scope the interception to that value only. For example:

To intercept events only for the "nurse" caregiver template: POST/organization/v1/users/caregivers/templates/nurse

To intercept events only for a specific generic entity template: POST/generic-entity/v3/generic-entities/thisisthetemplatename

To intercept events only for a specific patient: PATCH/organization/v1/users/patients/11111

This can be useful for testing and debugging a plugin against a specific entity.

Blocking a Requests/Responses

Interceptor plugins can also block the normal flow of a request or response.
To modify the response, instead of returning a success code (2XX) in the HTTP response, return a client error code (4XX) or server error code (5XX) along with the following response structure:

{
  "code": "ENTITY_NOT_FOUND",
  "message": "Entity with id [c36cca98-29b1-41a7-90a7-91d2540c4e2d] not found",
  "serviceName": "XYZ Plugin",
  "traceId": "a07a7e532f3541d8",
  "environment": "develop",
  "details": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

BioT will intercept the response. If the response code doesn't belong to the 2XX family (indicating success), BioT will halt the normal flow and replace the response with the interceptor's response.