OpenAPI Plugins

Important

This feature is currently in Public Preview

OpenAPI plugins enhance the capabilities of the Healthcare Orchestrator by providing integration with other services. By using these plugins, healthcare organizations can utilize external services to interact with the healthcare Orchestrator.

OpenAPI, also known as Swagger, is a specification for building APIs that allows both humans and computers to understand the capabilities of a service without accessing its source code or its documentation. OpenAPI plugins are extensions or add-ons that enhance the functionality of an API by providing extra features, improving integration, and facilitating various tasks such as validation, security, and documentation.

The OpenAPI Plugins page in the healthcare agent service allows users to integrate their OpenAPI Plugins, enabling the healthcare agent service to interface with external healthcare applications and services. Users can add, manage, and configure their plugins to enhance the bot's orchestrator capabilities in interacting with various systems.

Register OpenAPI Plugins

You can register their OpenAPI plugins via the OpenAPI Plugins page.

When adding a new OpenAPI plugin, you need to provide the yml endpoint in combination with the authentication mechanism. Currently we support None and Header, where header requires a Header Key and a Header value.

Important

When adding an new OpenAPI plugin you need to enable CORS to make sure we can validate the endpoint

Before creating a new OpenAPI plugin, you need to Fetch the information to get insights into the description, input parameters, and output parameters.

• The description is an important field, as it's used by the orchestrator to determine when to trigger the APIs.
• The input parameters are used by the orchestrator to determine if all parameters are met, before sending a request to the API.
• The output parameters are used by the orchestrator to determine the next step in the plan, or provide an answer based on the returned information.

Below you can find an example OpenAPI specification

openapi: 3.0.1
info:
  title: Azure Health Insights - Clinical Trial Matcher
  description: Azure Health Insights API's that can run Trial Matcher
  version: v1
servers:
  - url: https://clinicaltrial-contoso.com
paths:
  /ClinicalTrialMatcherPlugin:
    get:
      summary: 'This OpenAPI plugin helps users find healthcare clinical trials tailored to their needs. It requires the patient''s age and the targeted condition or disease they wish to address with a trial. Optionally, it can consider the patient''s gender, the country where the trial is conducted, and any pre-existing medical conditions or current medications. If the optional parameters are not provided, they will not be prompted for.'
      description: 'This OpenAPI plugin helps users find healthcare clinical trials tailored to their needs. It requires the patient''s age and the targeted condition or disease they wish to address with a trial. Optionally, it can consider the patient''s gender, the country where the trial is conducted, and any pre-existing medical conditions or current medications. If the optional parameters are not provided, they will not be prompted for.'
      operationId: ClinicalTrialsPlugin
      parameters:
        - name: age
          in: query
          description: The age of the patient who is seeking to participate in the clinical trial. This parameter is required.
          required: true
          schema:
            type: string
        - name: targetedConditionForTrial
          in: query
          description: The specific condition or disease for which the patient is seeking clinical trial. This parameter is required.
          required: true
          schema:
            type: string
        - name: gender
          in: query
          description: The gender of the patient seeking to participate in the trial. Acceptable values are 'male' or 'female'. This parameter is required.
          required: true
          schema:
            type: string
        - name: country
          in: query
          description: The country where the clinical trial is being conducted. This parameter is optional. Do not ask if not provided
          schema:
            type: string
        - name: historicalConditions
          in: query
          description: Any optional pre-existing medical conditions the patient has or medications the patient is currently taking. This parameter is optional. Do not ask if not provided
          schema:
            type: string
      responses:
        '200':
          description: found clinical trials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/foundTrials'
components:
  schemas:
    contact:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        phone:
          type: string
    foundTrials:
      type: object
      properties:
        trialUrl:
          type: string
        trialDescription:
          type: string
        trialContact:
          $ref: '#/components/schemas/contact'
        trialSponsor:
          type: string

You can then fetch the OpenAPI details within healthcare agent service via the fetch button.

When the OpenAPI capabilities are successfully fetched, you can create the OpenAPI plugin.

Register to the Orchestrator

When navigating to the Healthcare orchestrator, you can new connect your registered OpenAPI plugin. Under Registered Plugins select on New , select OpenAPI in the type field and select your OpenAPI Plugin.

Your orchestrator is now using the capabilities of the plugin in its reasoning and plan.

Next steps

Healthcare Orchestrator