Skip to content

Latest commit

 

History

History

Quickstart

README.md

Azure Health Data Services Toolkit Azure Function Custom Operation Quickstart

This quickstart will walk you through creating a simple custom operation on top of the FHIR Service using Azure Functions. We'll cover everything from deploying infrastructure, debugging locally, and deploying to Azure.

This sample has QuickstartFilter, which is an input filter, it does a preprocessing on PUT and POST requests on patient resources. In case request body for PUT and POST request does not have "Communication" and "meta.security" objects, filter would add these objects in requests using json transform feature. QuickstartFilter also implements extension to handle exceptions. In case of an exception it logs the details ad sets the error body in context as part of post process.

This sample does not address authorization for simplicity - the endpoint is open to anyone with the address. Please only use test or sample data for this quickstart.

Prerequisites

  • An Azure account with an active subscription.
    • You need access to create resource groups, resources, and role assignments in Azure
  • .NET 8.0
  • Azure Command-Line Interface (CLI)
  • Azure Developer CLI
  • Visual Studio or Visual Studio Code
    • For Visual Studio, you will need the Azure Functions Tools. To add Azure Function Tools, include the Azure development workload in your Visual Studio installation.
    • For Visual Studio Code, you will need to install the Azure Function Core Tools.

Prerequisite check

  • In a terminal or command window, run dotnet --version to check that the .NET SDK is version 6.0 or later.
  • Run az --version and azd version to check that you have the appropriate Azure command-line tools installed.
  • Login to the Azure CLI

Setting up

This quickstart will create the below resources. These will be used both for local development and the Azure deployment.

  • Azure Health Data Services workspace
  • FHIR Service
  • Function App (and associated storage account)
  • APIM - Azure API Management (for Function App and Fhir Service)
  • Log Analytics Workspace (for FHIR Service, Function App and APIM logs)
  • Application Insights (for monitoring your custom operation)

Deploy Quickstart

  1. Make sure you have this repository cloned and up to date on your local system. Open the samples/Quickstart directory from this repository on your local system.

  2. If you want to use an existing FHIR Service, you need to open infra/main.parameters.json in a code editor and change the following settings:

    • existingResourceGroupName: The name of an existing resource group if you want to deploy your Function App there.
    • existingAzureHealthDataServicesWorkspaceName: The name of your existing Azure Health Data Services workspace.
    • existingFhirServiceName: The name of your existing FHIR Service.

  3. By default, APIM is enabled for use. if you do not want to use APIM then pass useAPIM value as false Or Open infra/main.parameters.json in a code editor and set the value of the parameter named useAPIM to false.

  4. Next, you will need to deploy the infrastructure and code. Open a terminal/command prompt into the samples/Quickstart folder in the context of this repository. NOTE: This may take 10-20 minutes if you are deploying a new FHIR Service.

    azd up

Note: For more information for developing on the Azure Health Data Services Toolkit, check out the concepts document.

Testing locally

Visual Studio Code

  1. Open this folder in Visual Studio Code (samples/Quickstart).
  2. You may be asked to install recommended extensions for the repository. Click "Yes" to install the needed tools
    1. Relaunch Visual Studio Code if this is your first time working with the Azure Function Tools.
  3. Start the Azurite emulator by clicking Azurite Blob Service in the bottom blue bar or selecting Azurite: Start from the command palate.
  4. Start the Quickstart function app by going to "Run and Debug" and selecting the play button (or hit F5 on your keyboard).
  5. You can now test your code locally! Set a breakpoint and go to http://localhost:7071/Patient in your browser or API testing tool.

Visual Studio

  1. Open the QuickstartSample.sln project inside of Visual Studio.
  2. Debug the custom operation inside of Visual Studio.
  3. You can now test your code locally! Set a breakpoint and go to http://localhost:7256/Patient in your browser or API testing tool.

Deploying to Azure

  1. Once you are ready to deploy to Azure, we can use azd. Run azd deploy from your terminal or command prompt.
  2. The command will output an endpoint for your function app. Copy this.
  3. Test the endpoint by going to <Endpoint>/Patient in your browser or API testing tool.
  4. For APIM endpoint, get APIM Gateway URL from section Get the deployment details and test endpoint in API testing tool.

Get the deployment details

To get the deployed APIM Gateway URL variable named APIM_GatewayUrl Run the below command:

azd get-values

If you don't want to use APIM and are planning to call the Azure function instead, please follow the below steps to get the function url and key.

  1. Run the below command to get the deployed Azure function URL variable named Azure_FunctionURL.

     azd get-values

  2. Run the below command to get the default key from the deployed Azure function.

     az functionapp keys list --name
                     --resource-group

    As output, it will return the default key and master key.

    Please check here to read more about the function key.

Usage details

Quickstart function app

  • Program.cs outlines how to use Azure functions for simple custom operations using various types of services like authenticator, headers and filters.
    • UseCustomHeaders() : Used for custom headers setup. Using this service we can add custom headers; here we have added a custom header with name X-MS-AZUREFHIR-AUDIT-USER-TOKEN-TEST.
    • UseAzureFunctionPipeline() : Sets up pipeline for Azure function.
    • AddInputFilter(typeof(QuickstartFilter)) : Adds input filter with name QuickStart which in turn is used to modify patient data using JsonTransform.
    • Add binding to pass the call to the FHIR service.
    • UseAuthenticator(): Configures the binding to use an Azure.Identity DefaultAzureCredential.
  • Please refer to the QuickstartFilter.cs file for input filter modifications in the Patient Data.
    • Add language to resource as ‘en’ (English)
    • If there is no Patient.meta.security label, add HTEST
  • Custom operation QuickstartSample end point methods listed below.
    • GET: used to get the patient details using patient id.
    • POST: creates new patient record with updated filter data which is given above, to verify the new created record use GET method and pass created id.
    • PUT: updates the patient data. You need to pass the patient id. To verify the updated record use GET method and pass updated id.
    • DELETE: used to delete the patient record from FHIR server by passing patient id, to verify the record got deleted use GET method and pass deleted id.

APIM- Azure API Management

  • APIM supports the complete API lifecycle, this template was prepared using APIM for FHIR Service and Function App endpoints.
  • In given APIM, all the operations related to Patient are routed to QuickStart function app and for FHIR Service endpoints we have four methods like GET, POST, PUT, DELETE.

Calling the Azure Function

Please follow the below instructions if you want to perform operations using the Azure function instead of APIM.

For POST,

 url : <QuickStartFunctionURL>/Patient?Code=defaultkey

For GET/PUT/DELETE,

 url : <QuickStartFunctionURL>/Patient/{id}?Code=defaultkey

  • Please copy the quickstartfunction URL from the above command and replace it with QuickStartFunctionURL.

  • Copy the default key value from the above command and replace it with 'defaultkey'. Remove the ?Code='defaultkey' from the URL if AuthorizationLevel is Anonymous as it does not require any authorization.

Generate Postman Collection for Quickstart function app

Overview

This PowerShell script is designed to generate a Postman collection for the deployed Quickstart Function App. It extracts the necessary details from the provided Function App Resource ID and creates a Postman collection with GET, POST, PUT, and DELETE requests for the "Patient" Resource.

Prerequisites

Instructions to run the script

  1. Download the script

    • Click on this GitHub link Github Link
    • Browse to the folder under this path and download the script (..\script\GeneratePostmanCollection.ps1)

  2. Launch PowerShell on your system

  3. Run the Script

    • Navigate to the directory where the script is downloaded. Execute the script as below:

      PowerShell

    • It will prompt to enter the Function App Resource ID.

      PowerShell

  4. Get the Function App Resource ID

    To get the Function App Resource ID, follow these steps:

    • Log in to the Azure Portal

    • Go to "Resource Groups" and select the Resource Group where your Quickstart Function App is deployed. Click on the Function App.

    • Click on the "JSON View" for the Function App as shown below.

      FunctionApp

    • Copy the Resource ID (Highlighted in green box in below image).

      FunctionApp

  5. When prompted by the script, paste the copied Resource ID and press Enter.

Post-Execution

  • The Postman collection will be saved as PostmanCollection.json in the same directory from where the script is executed.

  • Open Postman and import the PostmanCollection.json file to start using the generated API requests. The collection will be named as "Quickstart Collection".

  • You will find following URL templates, where QuickStartFunctionURL and defaultkey will be automatically configured for you.

    For POST,

    url : <QuickStartFunctionURL>/Patient?Code=defaultkey

    For GET/PUT/DELETE,

    url : <QuickStartFunctionURL>/Patient/{id}?Code=defaultkey

  • In above URL's,

    • QuickStartFunctionURL will be replaced with the base URL of your Function App
    • defaultkey will be replaced with the master key provided by the Function App.
    • Enter the desired patient ID where {id} is indicated in the request URL.

Troubleshooting

  • Missing Azure CLI - Ensure that the Azure CLI is installed on your system. After installation, restart your PowerShell session and re-run the script.
  • Invalid Function App Resource ID - Verify the format of the Function App Resource ID.
  • Script execution policy - Ensure that the PowerShell execution policy allows running the script. You may need to adjust the execution policy using 'Set-ExecutionPolicy'.
  • Script execution errors - If you encounter any errors, check the error messages displayed in PowerShell. The script includes error handling that will provide information on what went wrong.

Monitoring

Dashboard Monitoring

Architecture

Dasboard contain below details.

Gateway.

  • Api call distribution - This pie chart includes the number of requests routed to the toolkit and the number of requests routed to the FHIR service.

  • Backend duration (FHIR)- This time chart includes response time in seconds for FHIR requests.

  • Backend duration (Toolkit)- This Time chart includes respose time in seconds for Toolkit requests.

Reliability.

  • Failed requests - This metric provides a summarized view of the number of failed requests for a specific service or resource.

  • Server expectations and dependency failures -

    • "Server Expectations" displays metrics related to server performance and health.
    • "Dependency failures" provides insights into failures or issues with external dependencies.

  • Average process I/O rate - This metric displays the average rate of input/output operations per second for a specific process, offering insights into its disk usage and performance.

  • Availability test results count - This metric provides a count of the results from availability tests, offering insights into the overall health and reliability of monitored services or endpoints.

Responsiveness.

  • Server response time - This metric displays the average time taken by the server to respond to requests.

  • Average processor and process CPU utilization - This metric provides insights into the average CPU usage for both the overall system processor and specific processes.

  • Average available memory - This metric displays the average amount of memory that is available across monitored resources or systems.