+You should get the output as "Success ΓÇô Status Code 204". If you receive an error you may need to check that your account has Read/Write permissions for ServicePrincipalEndpoint. You can find this permission by clicking on the *Modify permissions* tab in Graph Explorer.

+The endpoints are in the `{host}/scim/` directory, and you can use standard HTTP requests to interact with them. To modify the `/scim/` route, see *ControllerConstant.cs* in **AzureADProvisioningSCIMreference** > **ScimReferenceApi** > **Controllers**.

+> [Tutorial: Configure provisioning for a gallery app](configure-automatic-user-provisioning-portal.md)

+2. The request goes through an Azure Load Balancer to determine which Application Proxy service instance should take the request. There are tens of instances available to accept the requests for all traffic in the region. This method helps to evenly distribute the traffic across the service instances.

+- [Learn how Azure AD architecture supports high availability](../fundamentals/active-directory-architecture.md)

+| Node.js |ADAL |[npm](https://www.npmjs.com/package/adal-node) |[GitHub](https://github.com/AzureAD/azure-activedirectory-library-for-nodejs) | [Node.js web app](https://github.com/Azure-Samples/active-directory-node-webapp-openidconnect)|[Reference](/javascript/api/overview/azure/active-directory) |

+ The **CloudKnox Onboarding - Summary** box displays.

+> Effective October 1, 2022, we will begin to permanently disable Basic Authentication for Exchange Online in all Microsoft 365 tenants regardless of usage, except for SMTP Authentication. Read more [here](/exchange/clients-and-mobile-in-exchange-online/deprecation-of-basic-authentication-exchange-online)

+If you do find yourself locked out[What to do if you are locked out of the Azure portal?](troubleshoot-conditional-access.md#what-to-do-if-youre-locked-out-of-the-azure-portal)

+Most organizations have a process in place for their employees to consent to their organization's terms of use policy and privacy statements. But how can you enforce the same consents for Azure AD business-to-business (B2B) guests when they're added via SharePoint or Teams? Using Conditional Access and terms of use policies, you can enforce a policy directly towards B2B guest users. During the invitation redemption flow, the user is presented with the terms of use policy.

+- **Require device to be marked as compliant** - For users that haven't enrolled their devices yet, this policy blocks all access including access to the Intune portal. If you're an administrator without an enrolled device, this policy blocks you from getting back into the Azure portal to change the policy.

+- **Require app protection policy** - This policy block access has also the potential to block access for all users in your organization if you don't have an Intune policy. If you're an administrator without a client application that has an Intune app protection policy, this policy blocks you from getting back into portals such as Intune and Azure.

+In the above error, the message states that the application can only be accessed from devices or client applications that meet the company's mobile device management policy. In this case, the application and device don't meet that policy.

+ 1. Information in the **Troubleshooting and support** tab may provide a clear reason as to why a sign-in failed such as a device that didn't meet compliance requirements.

+If the information in the event isn't enough to understand the sign-in results or adjust the policy to get desired results, the sign-in diagnostic tool can be used. The sign-in diagnostic can be found under **Basic info** > **Troubleshoot Event**. For more information about the sign-in diagnostic, see the article [What is the sign-in diagnostic in Azure AD](../reports-monitoring/overview-sign-in-diagnostics.md).

+If you need to submit a support incident, provide the request ID and time and date from the sign-in event in the incident submission details. This information will allow Microsoft support to find the specific event you're concerned about.

+## What to do if you're locked out of the Azure portal?

+If you're locked out of the Azure portal due to an incorrect setting in a Conditional Access policy:

+ :::image type="content" source="./media/consent-framework/permissions.png" alt-text="Permissions to other applications" lightbox="./media/consent-framework/permissions.png":::

+ :::image type="content" source="./media/consent-framework/usersignin.png" alt-text="User or administrator sign in to Azure AD":::

+ :::image type="content" source="./media/consent-framework/consent.png" alt-text="Shows an example of permissions displayed in the consent dialog":::

+ :::image type="content" source="./media/consent-framework/grant-consent.png" alt-text="Grant permissions for explicit admin consent" lightbox="./media/consent-framework/grant-consent.png":::

+Many browsers block _third-party cookies_, cookies on requests to domains other than the domain shown in the browser's address bar. This block breaks the implicit flow and requires new authentication patterns to successfully sign in users. In the Microsoft identity platform, we use the authorization flow with Proof Key for Code Exchange (PKCE) and refresh tokens to keep users signed in when third-party cookies are blocked.

+ Apple [describes a popup method](https://webkit.org/blog/8311/intelligent-tracking-prevention-2-0/) as a temporary compatibility fix to give the original window access to third-party cookies. While Apple may remove this transferral of permissions in the future, it will not impact the guidance here.

+

+ Here, the popup is being used as a first party navigation to the login page so that a session is found and an auth code can be provided. This should continue working into the future.

+### Using iframes

+A common pattern in web apps is to use an iframe to embed one app inside anotherd: the top-level frame handles authenticating the user and the application hosted in the iframe can trust that the user is signed in, fetching tokens silently using the implicit flow.

+Silent token acquisition no longer works when third-party cookies are blocked - the application embedded in the iframe must switch to using popups to access the user's session as it can't navigate to the login page.

+You can achieve single sign-on between iframed and parent apps with same-origin _and_ cross-origin JavaScript script API access by passing a user (account) hint from the parent app to the iframed app. For more information, see [Using MSAL.js in iframed apps](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/iframe-usage.md) in the MSAL.js repository on GitHub.

+For more information about authorization code flow and MSAL.js, see:

+If you are using SAML, do not specify that a password is required [using the RequestedAuthnContext element](single-sign-on-saml-protocol.md#requestedauthncontext).

+[Passwordless authentication options for Azure Active Directory](../../active-directory/authentication/concept-authentication-passwordless.md)

+ Title: 'Disable pass-through authentication by using Azure AD Connect or PowerShell | Microsoft Docs'

+description: This article describes how to disable pass-through authentication by using the Azure AD Connect Do Not Configure feature or by using PowerShell.

+# Disable pass-through authentication

+In this article, you learn how to disable pass-through authentication by using Azure Active Directory (Azure AD) Connect or PowerShell.

+## Prerequisites

+Before you begin, ensure that you have the following:

+- A Windows machine with pass-through authentication agent version 1.5.1742.0 or later installed. Any earlier version might not have the requisite cmdlets for completing this operation.

+ If you don't already have an agent, you can install it by doing the following:

+ 1. Go to the [Azure portal](https://portal.azure.com).

+ 1. Download the latest Auth Agent.

+ 1. Install the feature by running either of the following:

+ * `.\AADConnectAuthAgentSetup.exe`

+ * `.\AADConnectAuthAgentSetup.exe ENVIRONMENTNAME=<identifier>`

+ > [!IMPORTANT]

+ > If you're using the Azure Government cloud, pass in the ENVIRONMENTNAME parameter with the following value:

+ >

+ >| Environment Name | Cloud |

+ >| - | - |

+ >| AzureUSGovernment | US Gov |

+- An Azure global administrator account for running the PowerShell cmdlets.

+## Use Azure AD Connect

+If you're using pass-through authentication with Azure AD Connect and you have it set to **Do not configure**, you can disable the setting.

+>[!NOTE]

+>If you already have password hash synchronization enabled, disabling pass-through authentication will result in a tenant fallback to password hash synchronization.

+## Use PowerShell

+In a PowerShell session, run the following cmdlets:

+- [User sign-in with Azure AD pass-through authentication](how-to-connect-pta.md)

+ Title: 'What is Azure AD Connect V2.0? | Microsoft Docs'

+The first version of Azure Active Directory (Azure AD) Connect was released several years ago. Since then, we've scheduled several components of Azure AD Connect for deprecation and updated them to newer versions.

+Making updates to all these components individually requires a lot of time and planning. To address this drawback, we've bundled many of the newer components into a new, single release, so you have to update only once. This release, Azure AD Connect V2.0, is a new version of the same software you're already using to accomplish your hybrid identity goals, but it's updated with the latest foundational components.

+Earlier versions of Azure AD Connect shipped with the SQL Server 2012 LocalDB feature. V2.0 ships with SQL Server 2019 LocalDB, which promises enhanced stability and performance and has several security-related bug fixes. In July 2022, SQL Server 2012 will no longer have extended support. For more information, see [Microsoft SQL 2019](https://www.microsoft.com/sql-server/sql-server-2019).

+Earlier versions of Azure AD Connect shipped with the Azure Active Directory Authentication Library (ADAL). This library will be deprecated in June 2022. The V2.0 release ships with the newer Microsoft Authentication Library (MSAL). For more information, see [Overview of the MSAL library](../../active-directory/develop/msal-overview.md).

+### Visual C++ Redistributable 14 runtime

+SQL Server 2019 requires the Visual C++ Redistributable 14 runtime, so we've updated the C++ runtime library to use this version. The library is installed with the Azure AD Connect V2.0 package, so you don't have to take any action to get the C++ runtime update.

+The Transport Layer Security (TLS) 1.0 and TLS 1.1 protocols are deemed unsafe and are being deprecated by Microsoft. Azure AD Connect V2.0 supports only TLS 1.2. All versions of Windows Server that are supported for Azure AD Connect V2.0 already default to TLS 1.2. If your server doesn't support TLS 1.2, you need to enable it before you can deploy Azure AD Connect V2.0. For more information, see [TLS 1.2 enforcement for Azure AD Connect](reference-connect-tls-enforcement.md).

+### All binaries signed with SHA-2

+We noticed that some components have Secure Hash Algorithm 1 (SHA-1) signed binaries. We no longer support SHA-1 for downloadable binaries, and we've upgraded all binaries to SHA-2 signing. The digital signatures are used to ensure that the updates come directly from Microsoft and aren't tampered with during delivery. Because of weaknesses in the SHA-1 algorithm, and to align with industry standards, we've changed the signing of Windows updates to use the more secure SHA-2 algorithm.ΓÇ»

+No action is required of you at this time.

+### Windows Server 2012 and 2012 R2 are no longer supported

+SQL Server 2019 requires Windows Server 2016 or later as a server operating system. Because Azure AD Connect V2.0 contains SQL Server 2019 components, we no longer support earlier Windows Server versions.

+You can't install this version on earlier Windows Server versions. We suggest that you upgrade your Azure AD Connect server to Windows Server 2019, which is the most recent version of the Windows Server operating system.

+For more information about upgrading from earlier Windows Server versions to Windows Server 2019, see [Install, upgrade, or migrate to Windows Server](/windows-server/get-started-19/install-upgrade-migrate-19).

+The Azure AD Connect V2.0 release contains several cmdlets that require PowerShell 5.0 or later, so this requirement is a new prerequisite for Azure AD Connect.

+For more information, see [Windows PowerShell System Requirements](/powershell/scripting/windows-powershell/install/windows-powershell-system-requirements#windows-powershell-50).

+ >PowerShell 5.0 is already part of Windows Server 2016, so you probably don't have to take action as long as you're using a recent Window Server version.

+Next year, several components in your current Azure AD Connect server installations will go out of support. If you're using unsupported products, it will be harder for our support team to provide you with the support experience your organization requires. We recommend that you upgrade to this newer version as soon as possible.

+This upgrade is especially important, because we've had to update our prerequisites for Azure AD Connect. You might need additional time to plan and update your servers to the newest versions of the prerequisites.

+No, this release doesn't contain new functionality. It contains only updates of some of the foundational components on Azure AD Connect. However, later releases of Azure AD Connect V2 might contain new functionality.

+**Can I upgrade from earlier versions to V2.0?** </br>

+Yes, upgrading from earlier versions of Azure AD Connect to Azure AD Connect V2.0 is supported. To determine your best upgrade strategy, see [Azure AD Connect: Upgrade from a previous version to the latest](how-to-upgrade-previous-version.md).

+Yes, and it's a great way to migrate to Azure AD Connect V2.0, especially if you're also upgrading to a new operating system version. For more information, see [Import and export Azure AD Connect configuration settings](how-to-connect-import-export-config.md).

+**I have enabled the auto-upgrade feature for Azure AD Connect. Will I get this new version automatically?** </br>

+Yes. Your Azure AD Connect server will be upgraded to the latest release if you've enabled the auto-upgrade feature. Note that we have not yet released an auto-upgrade version for Azure AD Connect.

+**I am not ready to upgrade yet. How much time do I have?** </br>

+All Azure AD Connect V1 versions will be retired on August 31, 2022, so you should upgrade to Azure AD Connect V2.0 as soon as you can. For the time being, we'll continue to support earlier versions of Azure AD Connect, but it might be difficult to provide a good support experience if some Azure AD Connect components are no longer supported. This upgrade is particularly important for ADAL and TLS 1.0/1.1, because these services might stop working unexpectedly after they're deprecated.

+**I use an external SQL database and do not use SQL Server 2012 LocalDB. Do I still have to upgrade?** </br>

+Yes, you need to upgrade to remain in a supported state, even if you don't use SQL Server 2012, because of the TLS 1.0/1.1 and ADAL deprecation. Note that you can still use SQL Server 2012 as an external SQL database with Azure AD Connect V2.0. The SQL Server 2019 drivers in Azure AD Connect V2.0 are compatible with SQL Server 2012.

+**After I've upgraded my Azure AD Connect instance to V2.0, will the SQL Server 2012 components get uninstalled automatically?** </br>

+No, the upgrade to SQL Server 2019 doesn't remove any SQL Server 2012 components from your server. If you no longer need these components, follow the instructions in [Uninstall an existing instance of SQL Server](/sql/sql-server/install/uninstall-an-existing-instance-of-sql-server-setup).

+**What happens if I don't upgrade?** </br>

+Until a component that's being retired is actually deprecated, your current version of Azure AD Connect will keep working and you won't see any impact.

+We expect TLS 1.0/1.1 to be deprecated in January 2022. You need to make sure that you're no longer using these protocols by that date, because your service might stop working unexpectedly. You can manually configure your server for TLS 1.2, though, because that doesn't require an upgrade to Azure AD Connect V2.0.

+In June 2022, ADAL is planned to go out of support. At that time, authentication might stop working unexpectedly, and the Azure AD Connect server will no longer work properly. We strongly recommend that you upgrade to Azure AD Connect V2.0 before June 2022. You can't upgrade to a supported authentication library with your current Azure AD Connect version.

+**After I upgraded to Azure AD Connect V2.0, the ADSync PowerShell cmdlets don't work. What can I do?** </br>

+This is a known issue. To resolve it, restart your PowerShell session after you've installed or upgraded to Azure AD Connect V2.0, and then reimport the module. To import the module, do the following:

+ 1. Open Windows PowerShell with administrative privileges.

+ 1. Run the following command:

+## License requirements for using Azure AD Connect V2

+This series of articles offer guidance for employing Azure Active Directory (Azure AD) as a centralized identity management system for implementing Zero Trust principles as described by the US Federal GovernmentΓÇÖs Office of Management and Budget (OMB) [Memorandum M-22-09](https://www.whitehouse.gov/wp-content/uploads/2022/01/M-22-09.pdf). Throughout this document we refer to it as "The memo."

+> Starting in Kubernetes version 1.21, AKS will use CSI drivers only and by default. CSI migration is also turned on starting from AKS 1.21, existing in-tree persistent volumes continue to function as they always have; however, behind the scenes Kubernetes hands control of all storage management operations (previously targeting in-tree drivers) to CSI drivers.

+If you have created in-tree driver storage classes, those storage classes will continue to work since CSI migration is turned on after upgrading your cluster to 1.21.x, while if you want to use CSI features (snapshotting etc.) you will need to carry out the migration.

+Migration of these storage classes will involve deleting the existing storage classes, and re-creating them with the provisioner set to **disk.csi.azure.com** if using Azure Disks, and **files.csi.azure.com** if using Azure Files.

+ name: custom-managed-premium

+reclaimPolicy: Delete

+ storageAccountType: Premium_LRS

+ name: custom-managed-premium

+reclaimPolicy: Delete

+ storageAccountType: Premium_LRS

+## Migrating in-tree persistent volumes

+### Migrating in-tree Azure Disk persistent volumes

+If you have in-tree Azure Disk persistent volumes, get `diskURI` from in-tree persistent volumes and then follow this [guide][azure-disk-static-mount] to set up CSI driver persistent volumes

+### Migrating in-tree Azure File persistent volumes

+If you have in-tree Azure File persistent volumes, get `secretName`, `shareName` from in-tree persistent volumes and then follow this [guide][azure-file-static-mount] to set up CSI driver persistent volumes

+[azure-file-static-mount]: azure-files-volume.md#mount-file-share-as-a-persistent-volume

+You can continue to learn with the [OpenFaaS workshop](https://github.com/openfaas/workshop) through a set of hands-on labs that cover topics such as how to create your own GitHub bot, consuming secrets, viewing metrics, and auto-scaling.

+### JBoss EAP Data Sources

+## JBoss EAP

+### Clustering in JBoss EAP

+App Service supports clustering for JBoss EAP versions 7.4.1 and greater. To enable clustering, your web app must be [integrated with a virtual network](overview-vnet-integration.md). When the web app is integrated with a virtual network, the web app will restart and JBoss EAP will automatically startup with a clustered configuration. The JBoss EAP instances will communicate over the subnet specified in the virtual network integration, using the ports shown in the `WEBSITES_PRIVATE_PORTS` environment variable at runtime. You can disable clustering by creating an app setting named `WEBSITE_DISABLE_CLUSTERING` with any value.

+> [!NOTE]

+> If you are enabling your virtual network integration with an ARM template, you will need to manually set the property `vnetPrivatePorts` to a value of `2`. If you enable virtual network integration from the CLI or Portal, this property will be set for you automatically.

+When clustering is enabled, the JBoss EAP instances use the FILE_PING JGroups discovery protocol to discover new instances and persist the cluster information like the cluster members, their identifiers, and their IP addresses. On App Service, these files are under `/home/clusterinfo/`. The first EAP instance to start will obtain read/write permissions on the cluster membership file. Other instances will read the file, find the primary node, and coordinate with that node to be included in the cluster and added to the file.

+### JBoss EAP App Service Plans

+- Australia Central

+- Canada Central

+- Central India

+- East Asia

+- East US

+- East US 2

+- France Central

+- Germany West Central

+- Korea Central

+- Norway East

+- Switzerland North

+- UAE North

+- UK South

+- West Central US

+Get started with [Azure App Service](overview.md) by deploying an app to the cloud using an Azure Resource Manager template (ARM template) and [Azure CLI](/cli/azure/get-started-with-azure-cli) in Cloud Shell. Because you use a free App Service tier, you incur no costs to complete this quickstart.

+| language | string | ".net" | Programming language stack (.NET, php, node, html) |

+[Azure App Service](overview.md) provides pre-defined application stacks on Windows like ASP.NET or Node.js, running on IIS. However, the pre-configured application stacks [lock down the operating system and prevent low-level access](operating-system-functionality.md). Custom Windows containers don't have these restrictions, and let developers fully customize the containers and give containerized applications full access to Windows functionality.

+1. In **Target**, select **Docker Container Registry**, and then select **Next**.

+1. In **Specific Target**, select **Azure Container Registry**, and then select **Next**.

+1. In **Create new**, make sure the correct subscription is chosen. Under **Resource group**, select **New** and type *myResourceGroup* for the name, and select **OK**. Under **SKU**, select **Basic**. Under **Registry location**, select a location of the registry then select **Create**.

+ If you have a custom image elsewhere for your web application, such as in [Azure Container Registry](../container-registry/index.yml) or in any other private repository, you can configure it here. Select **Review + Create** to continue.

+1. Verify all the details and then select **Create** and wait for Azure to create the required resources.

+

+The streamed logs look like this:

+App Service on Linux provides pre-defined application stacks on Linux with support for languages such as .NET, PHP, Node.js and others. You can also use a custom Docker image to run your web app on an application stack that isn't already defined in Azure. This quickstart shows you how to deploy an image from an [Azure Container Registry](../container-registry/index.yml) (ACR) to App Service.

+Verify that you have Docker installed and running. The following command will display the Docker version if it's running.

+1. In the Activity Bar, click the **Docker** icon. In the **IMAGES** explorer, find the image you built.

+1. In the **REGISTRIES** explorer, expand the image, right-click the tag, and select **Deploy image to Azure App Service**.

+The **Output** panel shows the status of the deployment operations. When the operation completes, select **Open Site** in the pop-up notification to open the site in your browser.

+1. In a terminal window, run the following commands. It will clone the sample application to your local machine, and navigate to the directory containing the sample code.

+1. In the Cloud Shell, create a web app in the `myAppServicePlan` App Service plan with the [`az webapp create`](/cli/azure/webapp#az_webapp_create) command.

+ In the following example, replace `<app-name>` with a globally unique app name (valid characters are `a-z`, `0-9`, and `-`). The runtime is set to `PHP|7.4`. To see all supported runtimes, run [`az webapp list-runtimes`](/cli/azure/webapp#az_webapp_list_runtimes).

+ Here's what your new web app should look like:

+ The web app menu provides different options for configuring your app.

+<!

+ 1. Select the Browse tab and type Azure.AI.FormRecognizer.

+To interact with the Form Recognizer service, you'll need to create an instance of the `DocumentAnalysisClient` class. To do so, you'll create an `AzureKeyCredential` with your key from the Azure portal and a `DocumentAnalysisClient` instance with the `AzureKeyCredential` and your Form Recognizer `endpoint`.

+1. Delete the pre-existing code, including the line `Console.Writeline("Hello World!")`, and select one of the following code samples to copy and paste into your application's Program.cs file:

+ * [**General document model**](#general-document-model)

+ * [**Layout model**](#layout-model)

+ * [**Prebuilt model**](#prebuilt-model)

+> * Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. For more information, *see* Cognitive Services [security](../../../cognitive-services/cognitive-services-security.md).

+Analyze and extract text, tables, structure, key-value pairs, and named entities.

+> * For simplicity, all the entity fields that the service returns are not shown here. To see the list of all supported fields and corresponding types, see the [General document](../concept-general-document.md#named-entity-recognition-ner-categories) concept page.

+### Add the following code to the Program.cs file:

+using Azure;

+using Azure.AI.FormRecognizer.DocumentAnalysis;

+//set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal to create your `AzureKeyCredential` and `DocumentAnalysisClient` instance

+string endpoint = "<your-endpoint>";

+string key = "<your-key>";

+AzureKeyCredential credential = new AzureKeyCredential(key);

+DocumentAnalysisClient client = new DocumentAnalysisClient(new Uri(endpoint), credential);

+//sample form document

+### General document model output

+Visit the Azure samples repository on GitHub to view the [general document model output](https://github.com/Azure-Samples/cognitive-services-quickstart-code/blob/master/dotnet/FormRecognizer/v3-csharp-sdk-general-document-output.md).

+using Azure;

+using Azure.AI.FormRecognizer.DocumentAnalysis;

+//set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal to create your `AzureKeyCredential` and `DocumentAnalysisClient` instance

+string endpoint = "<your-endpoint>";

+string key = "<your-key>";

+AzureKeyCredential credential = new AzureKeyCredential(key);

+DocumentAnalysisClient client = new DocumentAnalysisClient(new Uri(endpoint), credential);

+//sample document

+### Layout model output

+Visit the Azure samples repository on GitHub to view the [layout model output](https://github.com/Azure-Samples/cognitive-services-quickstart-code/blob/master/dotnet/FormRecognizer/v3-csharp-sdk-layout-output.md).

+Analyze and extract common fields from specific document types using a prebuilt model. In this example, we'll analyze an invoice using the **prebuilt-invoice** model.

+using Azure;

+using Azure.AI.FormRecognizer.DocumentAnalysis;

+//set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal to create your `AzureKeyCredential` and `DocumentAnalysisClient` instance

+string endpoint = "<your-endpoint>";

+string key = "<your-key>";

+AzureKeyCredential credential = new AzureKeyCredential(key);

+DocumentAnalysisClient client = new DocumentAnalysisClient(new Uri(endpoint), credential);

+//sample invoice document

+### Prebuilt model output

+Visit the Azure samples repository on GitHub to view the [prebuilt invoice model output](https://github.com/Azure-Samples/cognitive-services-quickstart-code/blob/master/dotnet/FormRecognizer/v3-csharp-sdk-prebuilt-invoice-output.md).

+### Azure Confidential VM attestation

+Azure [Confidential VM](/azure/confidential-computing/confidential-vm-overview) (CVM) is based on [AMD processors with SEV-SNP technology](/azure/confidential-computing/virtual-machine-solutions-amd) and aims to improve VM security posture by removing trust in host, hypervisor and Cloud Service Provider (CSP). To achieve this, CVM offers VM OS disk encryption option with platform-managed keys and binds the disk encryption keys to the virtual machine's TPM. When a CVM boots up, SNP report containing the guest VM firmware measurements will be sent to Azure Attestation. The service validates the measurements and issues an attestation token that is used to release keys from [Managed-HSM](/azure/key-vault/managed-hsm/overview) or [Azure Key Vault](/azure/key-vault/general/basic-concepts). These keys are used to decrypt the vTPM state of the guest VM, unlock the OS disk and start the CVM. The attestation and key release process is performed automatically on each CVM boot, and the process ensures the CVM boots up only upon successful attestation of the hardware.

+- Arc machine is not connected. Learn more about the [Arc agent status](../azure-arc/servers/overview.md#agent-status) and [how to connect](../azure-arc/servers/deployment-options.md#agent-installation-details)

+Azure services are built for resiliency including high availability and disaster recovery. There are no services that are dependent on a single logical data center (to avoid single points of failure). Non-regional services listed on [Azure global infrastructure products](https://azure.microsoft.com/global-infrastructure/services/?products=all) are services for which there is no dependency on a specific Azure region. Non-regional services are deployed to two or more regions and if there is a regional failure, the instance of the service in another region continues servicing customers. Certain non-regional services enable customers to specify the region where the underlying virtual machine (VM) on which service runs will be deployed. For example, [Azure Virtual Desktop](https://azure.microsoft.com/services/virtual-desktop/) enables customers to specify the region location where the VM resides. All Azure services that store customer data allow the customer to specify the specific regions in which their data will be stored. The exception is [Azure Active Directory (Azure AD)](https://azure.microsoft.com/services/active-directory/), which has geo placement (such as Europe or North America). For more information about data storage residency, see the [Data residency map](https://azure.microsoft.com/global-infrastructure/data-residency/).

+ utc_now = str(datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S ")) + "GMT"

+The Azure Connected Machine agent enables you to manage your Windows and Linux machines hosted outside of Azure on your corporate network or other cloud providers.

+The Azure Connected Machine agent package contains several logical components, which are bundled together:

+* The Extension agent manages VM extensions, including install, uninstall, and upgrade. Extensions are downloaded from Azure and copied to the `%SystemDrive%\%ProgramFiles%\AzureConnectedMachineAgent\ExtensionService\downloads` folder on Windows, and to `/opt/GC_Ext/downloads` on Linux. On Windows, the extension is installed to the following path `%SystemDrive%\Packages\Plugins\<extension>`, and on Linux the extension is installed to `/var/lib/waagent/<extension>`.

+>[!NOTE]

+> The [Azure Monitor agent](../../azure-monitor/agents/azure-monitor-agent-overview.md) (AMA) is a separate agent that collects monitoring data, and it does not replace the Connected Machine agent; the AMA only replaces the Log Analytics agent, Diagnostics extension, and Telegraf agent for both Windows and Linux machines.

+Metadata information about a connected machine is collected after the Connected Machine agent registers with Azure Arc-enabled servers. Specifically:

+## Deployment options and requirements

+To deploy the agent and connect a machine, certain [prerequisites](prerequisites.md) must be met. There are also [networking requirements](network-requirements.md) to be aware of.

+We provide several options for deploying the agent. For more information, see [Plan for deployment](plan-at-scale-deployment.md) and [Deployment options](deployment-options.md).

+* To begin evaluating Azure Arc-enabled servers, see [Quickstart: Connect hybrid machines with Azure Arc-enabled servers](learn/quick-enable-hybrid-vm.md).

+* Review troubleshooting information in the [agent connection issues troubleshooting guide](troubleshoot-agent-onboard.md).

+- Extension operations will execute faster using a new notification pipeline. You may need to adjust your firewall or proxy server rules to allow the new network addresses for this notification service (see [networking configuration](network-requirements.md)). The extension manager will fall back to the existing behavior of checking every 5 minutes when the notification service cannot be reached.

+ Title: Azure Connected Machine agent deployment options

+description: Learn about the different options to onboard machines to Azure Arc-enabled servers.

+# Azure Connected Machine agent deployment options

+Connecting machines in your hybrid environment directly with Azure can be accomplished using different methods, depending on your requirements and the tools you prefer to use.

+## Onboarding methods

+ The following table highlights each method so that you can determine which works best for your deployment. For detailed information, follow the links to view the steps for each topic.

+| Method | Description |

+|--|-|

+| Interactively | Manually install the agent on a single or small number of machines by [connecting machines using a deployment script](onboard-portal.md).<br> From the Azure portal, you can generate a script and execute it on the machine to automate the install and configuration steps of the agent.|

+| Interactively | [Connect machines from Windows Admin Center](onboard-windows-admin-center.md) |

+| Interactively or at scale | [Connect machines using PowerShell](onboard-powershell.md) |

+| Interactively or at scale | [Connect machines using Windows PowerShell Desired State Configuration (DSC)](onboard-dsc.md) |

+| At scale | [Connect machines using a service principal](onboard-service-principal.md) to install the agent at scale non-interactively.|

+| At scale | [Connect machines by running PowerShell scripts with Configuration Manager](onboard-configuration-manager-powershell.md)

+| At scale | [Connect machines with a Configuration Manager custom task sequence](onboard-configuration-manager-custom-task.md)

+| At scale | [Connect machines from Automation Update Management](onboard-update-management-machines.md) to create a service principal that installs and configures the agent for multiple machines managed with Azure Automation Update Management to connect machines non-interactively. |

+> [!IMPORTANT]

+> The Connected Machine agent cannot be installed on an Azure Windows virtual machine. If you attempt to, the installation detects this and rolls back.

+Be sure to review the basic [prerequisites](prerequisites.md) and [network configuration requirements](network-requirements.md) before deploying the agent, as well as any specific requirements listed in the steps for the onboarding method you choose.

+## Agent installation details

+Review the following details to understand more about how the Connected Machine agent is installed on Windows or Linux machines.

+### Windows agent installation details

+You can download the [Windows agent Windows Installer package](https://aka.ms/AzureConnectedMachineAgent) from the Microsoft Download Center.

+The Connected Machine agent for Windows can be installed by using one of the following three methods:

+* Running the file `AzureConnectedMachineAgent.msi`.

+* Manually by running the Windows Installer package `AzureConnectedMachineAgent.msi` from the Command shell.

+* From a PowerShell session using a scripted method.

+Installing, upgrading, and removing the Connected Machine agent will not require you to restart your server.

+After installing the Connected Machine agent for Windows, the following system-wide configuration changes are applied.

+* The following installation folders are created during setup.

+ |Folder |Description |

+ |-||

+ |%ProgramFiles%\AzureConnectedMachineAgent |azcmagent CLI and instance metadata service executables.|

+ |%ProgramFiles%\AzureConnectedMachineAgent\ExtensionService\GC | Extension service executables.|

+ |%ProgramFiles%\AzureConnectedMachineAgent\GuestConfig\GC | Guest configuration (policy) service executables.|

+ |%ProgramData%\AzureConnectedMachineAgent |Configuration, log and identity token files for azcmagent CLI and instance metadata service.|

+ |%ProgramData%\GuestConfig |Extension package downloads, guest configuration (policy) definition downloads, and logs for the extension and guest configuration services.|

+* The following Windows services are created on the target machine during installation of the agent.

+ |Service name |Display name |Process name |Description |

+ |-|-|-||

+ |himds |Azure Hybrid Instance Metadata Service |himds |This service implements the Hybrid Instance Metadata service (IMDS) to manage the connection to Azure and the connected machine's Azure identity.|

+ |GCArcService |Guest configuration Arc Service |gc_service |Monitors the desired state configuration of the machine.|

+ |ExtensionService |Guest configuration Extension Service | gc_service |Installs the required extensions targeting the machine.|

+* The following virtual service account is created during agent installation.

+ | Virtual Account | Description |

+ |||

+ | NT SERVICE\\himds | Unprivileged account used to run the Hybrid Instance Metadata Service. |

+ > [!TIP]

+ > This account requires the "Log on as a service" right. This right is automatically granted during agent installation, but if your organization configures user rights assignments with Group Policy, you may need to adjust your Group Policy Object to grant the right to "NT SERVICE\\himds" or "NT SERVICE\\ALL SERVICES" to allow the agent to function.

+* The following local security group is created during agent installation.

+ | Security group name | Description |

+ ||-|

+ | Hybrid agent extension applications | Members of this security group can request Azure Active Directory tokens for the system-assigned managed identity |

+* The following environmental variables are created during agent installation.

+ |Name |Default value |Description |

+ |--|--||

+ |IDENTITY_ENDPOINT |<`http://localhost:40342/metadata/identity/oauth2/token`> ||

+ |IMDS_ENDPOINT |<`http://localhost:40342`> ||

+* There are several log files available for troubleshooting. They are described in the following table.

+ |Log |Description |

+ |-||

+ |%ProgramData%\AzureConnectedMachineAgent\Log\himds.log |Records details of the heartbeat and identity agent component.|

+ |%ProgramData%\AzureConnectedMachineAgent\Log\azcmagent.log |Contains the output of the azcmagent tool commands.|

+ |%ProgramData%\GuestConfig\arc_policy_logs\ |Records details about the guest configuration (policy) agent component.|

+ |%ProgramData%\GuestConfig\ext_mgr_logs|Records details about the Extension agent component.|

+ |%ProgramData%\GuestConfig\extension_logs\\\<Extension>|Records details from the installed extension.|

+* The local security group **Hybrid agent extension applications** is created.

+* During uninstall of the agent, the following artifacts are not removed.

+ * %ProgramData%\AzureConnectedMachineAgent\Log

+ * %ProgramData%\AzureConnectedMachineAgent and subdirectories

+ * %ProgramData%\GuestConfig

+### Linux agent installation details

+The Connected Machine agent for Linux is provided in the preferred package format for the distribution (.RPM or .DEB) that's hosted in the Microsoft [package repository](https://packages.microsoft.com/). The agent is installed and configured with the shell script bundle [Install_linux_azcmagent.sh](https://aka.ms/azcmagent).

+Installing, upgrading, and removing the Connected Machine agent will not require you to restart your server.

+After installing the Connected Machine agent for Linux, the following system-wide configuration changes are applied.

+* The following installation folders are created during setup.

+ |Folder |Description |

+ |-||

+ |/opt/azcmagent/ |azcmagent CLI and instance metadata service executables.|

+ |/opt/GC_Ext/ | Extension service executables.|

+ |/opt/GC_Service/ |Guest configuration (policy) service executables.|

+ |/var/opt/azcmagent/ |Configuration, log and identity token files for azcmagent CLI and instance metadata service.|

+ |/var/lib/GuestConfig/ |Extension package downloads, guest configuration (policy) definition downloads, and logs for the extension and guest configuration services.|

+* The following daemons are created on the target machine during installation of the agent.

+ |Service name |Display name |Process name |Description |

+ |-|-|-||

+ |himdsd.service |Azure Connected Machine Agent Service |himds |This service implements the Hybrid Instance Metadata service (IMDS) to manage the connection to Azure and the connected machine's Azure identity.|

+ |gcad.service |GC Arc Service |gc_linux_service |Monitors the desired state configuration of the machine. |

+ |extd.service |Extension Service |gc_linux_service | Installs the required extensions targeting the machine.|

+* There are several log files available for troubleshooting. They are described in the following table.

+ |Log |Description |

+ |-||

+ |/var/opt/azcmagent/log/himds.log |Records details of the heartbeat and identity agent component.|

+ |/var/opt/azcmagent/log/azcmagent.log |Contains the output of the azcmagent tool commands.|

+ |/var/lib/GuestConfig/arc_policy_logs |Records details about the guest configuration (policy) agent component.|

+ |/var/lib/GuestConfig/ext_mgr_logs |Records details about the extension agent component.|

+ |/var/lib/GuestConfig/extension_logs|Records details from extension install/update/uninstall operations.|

+* The following environmental variables are created during agent installation. These variables are set in `/lib/systemd/system.conf.d/azcmagent.conf`.

+ |Name |Default value |Description |

+ |--|--||

+ |IDENTITY_ENDPOINT |<`http://localhost:40342/metadata/identity/oauth2/token`> ||

+ |IMDS_ENDPOINT |<`http://localhost:40342`> ||

+* During uninstall of the agent, the following artifacts are not removed.

+ * /var/opt/azcmagent

+ * /var/lib/GuestConfig

+## Agent resource governance

+The Azure Connected Machine agent is designed to manage agent and system resource consumption. The agent approaches resource governance under the following conditions:

+* The Guest Configuration agent is limited to use up to 5% of the CPU to evaluate policies.

+* The Extension Service agent is limited to use up to 5% of the CPU to install and manage extensions.

+ * Once installed, each extension is limited to use up to 5% of the CPU while running. For example, if you have two extensions installed, they can use a combined total of 10% of the CPU.

+ * The Log Analytics agent and Azure Monitor Agent are allowed to use up to 60% of the CPU during their install/upgrade/uninstall operations on Red Hat Linux, CentOS, and other enterprise Linux variants. The limit is higher for this combination of extensions and operating systems to accommodate the performance impact of [SELinux](https://www.redhat.com/en/topics/linux/what-is-selinux) on these systems.

+## Next steps

+* Learn about the Azure Connected Machine agent [prerequisites](prerequisites.md) and [network requirements](network-requirements.md).

+* Review the [Planning and deployment guide for Azure Arc-enabled servers](plan-at-scale-deployment.md)

+* Learn about [reconfiguring, upgrading, and removing the Connected Machine agent](manage-agent.md).

+* Before you get started, be sure to review the agent [prerequisites](../prerequisites.md) and verify the following:

+ * Your target machine is running a supported [operating system](../prerequisites.md#supported-operating-systems).

+ * Your account is granted assignment to the [required Azure roles](../prerequisites.md#required-permissions).

+ * If the machine connects through a firewall or proxy server to communicate over the Internet, make sure the URLs [listed](../network-requirements.md#urls) are not blocked.

+* The list of supported operating systems with the Azure VM Custom Script extension is not applicable to Azure Arc-enabled servers. The list of supported OSs for Azure Arc-enabled servers can be found [here](prerequisites.md#supported-operating-systems).

+If they aren't already registered, follow the steps under [Register Azure resource providers](prerequisites.md#azure-resource-providers).

+Verify your machine matches the [supported versions](prerequisites.md#supported-operating-systems) of Windows and Linux operating system for the Azure Connected Machine agent.

+ Title: Connected Machine agent network requirements

+description: Learn about the networking requirements for using the Connected Machine agent for Azure Arc-enabled servers.

+# Connected Machine agent network requirements

+This topic describes the networking requirements for using the Connected Machine agent to onboard a physical server or virtual machine to Azure Arc-enabled servers.

+## Networking configuration

+The Azure Connected Machine agent for Linux and Windows communicates outbound securely to Azure Arc over TCP port 443. By default, the agent uses the default route to the internet to reach Azure services. You can optionally [configure the agent to use a proxy server](manage-agent.md#update-or-remove-proxy-settings) if your network requires it. Proxy servers don't make the Connected Machine agent more secure because the traffic is already encrypted.

+To further secure your network connectivity to Azure Arc, instead of using public networks and proxy servers, you can implement an [Azure Arc Private Link Scope](private-link-security.md) (preview).

+> [!NOTE]

+> Azure Arc-enabled servers does not support using a [Log Analytics gateway](../../azure-monitor/agents/gateway.md) as a proxy for the Connected Machine agent.

+If outbound connectivity is restricted by your firewall or proxy server, make sure the URLs and Service Tags listed below are not blocked.

+## Service tags

+Be sure to allow access to the following Service Tags:

+* AzureActiveDirectory

+* AzureTrafficManager

+* AzureResourceManager

+* AzureArcInfrastructure

+* Storage

+For a list of IP addresses for each service tag/region, see the JSON file [Azure IP Ranges and Service Tags ΓÇô Public Cloud](https://www.microsoft.com/download/details.aspx?id=56519). Microsoft publishes weekly updates containing each Azure Service and the IP ranges it uses. This information in the JSON file is the current point-in-time list of the IP ranges that correspond to each service tag. The IP addresses are subject to change. If IP address ranges are required for your firewall configuration, then the **AzureCloud** Service Tag should be used to allow access to all Azure services. Do not disable security monitoring or inspection of these URLs, allow them as you would other Internet traffic.

+For more information, see [Virtual network service tags](../../virtual-network/service-tags-overview.md).

+## URLs

+The table below lists the URLs that must be available in order to install and use the Connected Machine agent.

+| Agent resource | Description | When required| Endpoint used with private link |

+|||--||

+|`aka.ms`|Used to resolve the download script during installation|At installation time, only| Public |

+|`download.microsoft.com`|Used to download the Windows installation package|At installation time, only| Public |

+|`packages.microsoft.com`|Used to download the Linux installation package|At installation time, only| Public |

+|`login.windows.net`|Azure Active Directory|Always| Public |

+|`login.microsoftonline.com`|Azure Active Directory|Always| Public |

+|`pas.windows.net`|Azure Active Directory|Always| Public |

+|`management.azure.com`|Azure Resource Manager - to create or delete the Arc server resource|When connecting or disconnecting a server, only| Public, unless a [resource management private link](../../azure-resource-manager/management/create-private-link-access-portal.md) is also configured |

+|`*.his.arc.azure.com`|Metadata and hybrid identity services|Always| Private |

+|`*.guestconfiguration.azure.com`| Extension management and guest configuration services |Always| Private |

+|`guestnotificationservice.azure.com`, `*.guestnotificationservice.azure.com`|Notification service for extension and connectivity scenarios|Always| Private |

+|`azgn*.servicebus.windows.net`|Notification service for extension and connectivity scenarios|Always| Public |

+|`*.blob.core.windows.net`|Download source for Azure Arc-enabled servers extensions|Always, except when using private endpoints| Not used when private link is configured |

+|`dc.services.visualstudio.com`|Agent telemetry|Optional| Public |

+## Transport Layer Security 1.2 protocol

+To ensure the security of data in transit to Azure, we strongly encourage you to configure machine to use Transport Layer Security (TLS) 1.2. Older versions of TLS/Secure Sockets Layer (SSL) have been found to be vulnerable and while they still currently work to allow backwards compatibility, they are **not recommended**.

+|Platform/Language | Support | More Information |

+| | | |

+|Linux | Linux distributions tend to rely on [OpenSSL](https://www.openssl.org) for TLS 1.2 support. | Check the [OpenSSL Changelog](https://www.openssl.org/news/changelog.html) to confirm your version of OpenSSL is supported.|

+| Windows Server 2012 R2 and higher | Supported, and enabled by default. | To confirm that you are still using the [default settings](/windows-server/security/tls/tls-registry-settings).|

+## Next steps

+* Review additional [prerequisites for deploying the Connected Machine agent](prerequisites.md).

+* Before you deploy the Azure Arc-enabled servers agent and integrate with other Azure management and monitoring services, review the [Planning and deployment guide](plan-at-scale-deployment.md).

+* To resolve problems, review the [agent connection issues troubleshooting guide](troubleshoot-agent-onboard.md).

+Before you get started, be sure to review the [prerequisites](prerequisites.md) and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see [supported Azure regions](overview.md#supported-regions). Also review our [at-scale planning guide](plan-at-scale-deployment.md) to understand the design and deployment criteria, as well as our management and monitoring recommendations.

+Before you get started, be sure to review the [prerequisites](prerequisites.md) and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see [supported Azure regions](overview.md#supported-regions). Also review our [at-scale planning guide](plan-at-scale-deployment.md) to understand the design and deployment criteria, as well as our management and monitoring recommendations.

+Before you get started, be sure to review the [prerequisites](prerequisites.md) and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see [supported Azure regions](overview.md#supported-regions).

+Before you get started, review the [prerequisites](prerequisites.md) and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see [supported Azure regions](overview.md#supported-regions).

+Before you get started, be sure to review the [prerequisites](prerequisites.md) and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see [supported Azure regions](overview.md#supported-regions). Also review our [at-scale planning guide](plan-at-scale-deployment.md) to understand the design and deployment criteria, as well as our management and monitoring recommendations.

+Before you get started, be sure to review the [prerequisites](prerequisites.md) and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see [supported Azure regions](overview.md#supported-regions).

+* Azure Arc-enabled servers - Review the [prerequisites](prerequisites.md) and verify that your subscription, your Azure account, and resources meet the requirements.

+Azure Arc-enabled servers support the management of physical servers and virtual machines hosted *outside* of Azure. For specific details of which hybrid cloud environments hosting VMs are supported, see [Connected Machine agent prerequisites](prerequisites.md#supported-environments).

+ Title: Plan and deploy Azure Arc-enabled servers

+Consider the following basic requirements when planning your deployment:

+* Your machines must run a [supported operating system](prerequisites.md#supported-operating-systems) for the Connected Machine agent.

+* Your machines must have connectivity from your on-premises network or other cloud environment to resources in Azure, either directly or through a proxy server.

+* To install and configure the Azure Connected Machine agent, you must have an account with elevated privileges (that is, an administrator or as root)on the machines.

+* To onboard machines, you must have the **Azure Connected Machine Onboarding** Azure built-in role.

+* To read, modify, and delete a machine, you must have the **Azure Connected Machine Resource Administrator** Azure built-in role.

+For more details, see the [prerequisites](prerequisites.md) and [network requirements](network-requirements.md) for installing the Connected Machine agent.

+Before deploying to all production machines, start by evaluating the deployment process before adopting it broadly in your environment. For a pilot, identify a representative sampling of machines that aren't critical to your companies ability to conduct business. You'll want to be sure to allow enough time to run the pilot and assess its impact: we recommend a minimum of 30 days.

+In this phase, system engineers or administrators enable the core features in their organization's Azure subscription to start the foundation before enabling machines for management by Azure Arc-enabled servers and other Azure services.

+|Task |Detail |Estimated duration |

+¹ When evaluating your Log Analytics workspace design, consider integration with Azure Automation in support of its Update Management and Change Tracking and Inventory feature, as well as Microsoft Defender for Cloud and Microsoft Sentinel. If your organization already has an Automation account and enabled its management features linked with a Log Analytics workspace, evaluate whether you can centralize and streamline management operations, as well as minimize cost, by using those existing resources versus creating a duplicate account, workspace, etc.

+Next, we add to the foundation laid in Phase 1 by preparing for and [deploying the Azure Connected Machine agent](deployment-options.md).

+|Task |Detail |Estimated duration |

+Phase 3 is when administrators or system engineers can enable automation of manual tasks to manage and operate the Connected Machine agent and the machines during their lifecycle.

+|Task |Detail |Estimated duration |

+* Learn about [reconfiguring, upgrading, and removing the Connected Machine agent](manage-agent.md).

+* Review troubleshooting information in the [agent connection issues troubleshooting guide](troubleshoot-agent-onboard.md).

+* The Azure virtual machine is running an [operating system supported by Azure Arc-enabled servers](prerequisites.md#supported-operating-systems). If you don't have an Azure VM, you can deploy a [simple Windows VM](https://portal.azure.com/#create/Microsoft.Template/uri/https%3a%2f%2fraw.githubusercontent.com%2fAzure%2fazure-quickstart-templates%2fmaster%2fquickstarts%2fmicrosoft.compute%2fvm-simple-windows%2fazuredeploy.json) or a [simple Ubuntu Linux 18.04 LTS VM](https://portal.azure.com/#create/Microsoft.Template/uri/https%3a%2f%2fraw.githubusercontent.com%2fAzure%2fazure-quickstart-templates%2fmaster%2fquickstarts%2fmicrosoft.compute%2fvm-simple-windows%2fazuredeploy.json).

+ Title: Connected Machine agent prerequisites

+description: Learn about the prerequisites for installing the Connected Machine agent for Azure Arc-enabled servers.

+# Connected Machine agent prerequisites

+This topic describes the basic requirements for installing the Connected Machine agent to onboard a physical server or virtual machine to Azure Arc-enabled servers. Some [onboarding methods](deployment-options.md) may have additional requirements.

+## Supported environments

+Azure Arc-enabled servers supports the installation of the Connected Machine agent on physical servers and virtual machines hosted outside of Azure. This includes support for virtual machines running on platforms like:

+* VMware

+* Azure Stack HCI

+* Other cloud environments

+Azure Arc-enabled servers does not support installing the agent on virtual machines running in Azure, or on virtual machines running on Azure Stack Hub or Azure Stack Edge, as they are already modeled as Azure VMs and able to be managed directly in Azure.

+## Supported operating systems

+The following versions of the Windows and Linux operating system are officially supported for the Azure Connected Machine agent:

+* Windows Server 2008 R2 SP1, 2012 R2, 2016, 2019, and 2022

+ * Both Desktop and Server Core experiences are supported

+ * Azure Editions are supported when running as a virtual machine on Azure Stack HCI

+* Azure Stack HCI

+* Ubuntu 16.04, 18.04, and 20.04 LTS (x64)

+* CentOS Linux 7 and 8 (x64)

+* SUSE Linux Enterprise Server (SLES) 12 and 15 (x64)

+* Red Hat Enterprise Linux (RHEL) 7 and 8 (x64)

+* Amazon Linux 2 (x64)

+* Oracle Linux 7 and 8 (x64)

+> [!WARNING]

+> If the Linux hostname or Windows computer name uses a reserved word or trademark, attempting to register the connected machine with Azure will fail. For a list of reserved words, see [Resolve reserved resource name errors](../../azure-resource-manager/templates/error-reserved-resource-name.md).

+> [!NOTE]

+> While Azure Arc-enabled servers supports Amazon Linux, the following features are not supported by this distribution:

+>

+> * The Dependency agent used by Azure Monitor VM insights

+> * Azure Automation Update Management

+## Software requirements

+* NET Framework 4.6 or later is required. [Download the .NET Framework](/dotnet/framework/install/guide-for-developers).

+* Windows PowerShell 5.1 is required. [Download Windows Management Framework 5.1.](https://www.microsoft.com/download/details.aspx?id=54616).

+## Required permissions

+The following Azure built-in roles are required for different aspects of managing connected machines:

+* To onboard machines, you must have the [Azure Connected Machine Onboarding](../../role-based-access-control/built-in-roles.md#azure-connected-machine-onboarding) or [Contributor](../../role-based-access-control/built-in-roles.md#contributor) role for the resource group in which the machines will be managed.

+* To read, modify, and delete a machine, you must have the [Azure Connected Machine Resource Administrator](../../role-based-access-control/built-in-roles.md#azure-connected-machine-resource-administrator) role for the resource group.

+* To select a resource group from the drop-down list when using the **Generate script** method, you must have the [Reader](../../role-based-access-control/built-in-roles.md#reader) role for that resource group (or another role which includes **Reader** access).

+## Azure subscription and service limits

+Azure Arc-enabled servers supports up to 5,000 machine instances in a resource group.

+Before configuring your machines with Azure Arc-enabled servers, review the Azure Resource Manager [subscription limits](../../azure-resource-manager/management/azure-subscription-service-limits.md#subscription-limits) and [resource group limits](../../azure-resource-manager/management/azure-subscription-service-limits.md#resource-group-limits) to plan for the number of machines to be connected.

+## Azure resource providers

+To use Azure Arc-enabled servers, the following [Azure resource providers](../../azure-resource-manager/management/resource-providers-and-types.md) must be registered in your subscription:

+* **Microsoft.HybridCompute**

+* **Microsoft.GuestConfiguration**

+* **Microsoft.HybridConnectivity**

+If these resource providers are not already registered, you can register them using the following commands:

+Azure PowerShell:

+```azurepowershell-interactive

+Login-AzAccount

+Set-AzContext -SubscriptionId [subscription you want to onboard]

+Register-AzResourceProvider -ProviderNamespace Microsoft.HybridCompute

+Register-AzResourceProvider -ProviderNamespace Microsoft.GuestConfiguration

+Register-AzResourceProvider -ProviderNamespace Microsoft.HybridConnectivity

+```

+Azure CLI:

+```azurecli-interactive

+az account set --subscription "{Your Subscription Name}"

+az provider register --namespace 'Microsoft.HybridCompute'

+az provider register --namespace 'Microsoft.GuestConfiguration'

+az provider register --namespace 'Microsoft.HybridConnectivity'

+```

+You can also register the resource providers in the [Azure portal](../../azure-resource-manager/management/resource-providers-and-types.md#azure-portal).

+## Next steps

+* Review the [networking requirements for deploying Azure Arc-enabled servers](network-requirements.md).

+* Before you deploy the Azure Arc-enabled servers agent and integrate with other Azure management and monitoring services, review the [Planning and deployment guide](plan-at-scale-deployment.md).* To resolve problems, review the [agent connection issues troubleshooting guide](troubleshoot-agent-onboard.md).

+|Failed to AzcmagentConnect ARM resource |`The subscription is not registered to use namespace 'Microsoft.HybridCompute'` |Azure resource providers are not registered. |Register the [resource providers](prerequisites.md#azure-resource-providers). |

+ - is running a [supported operating system](../servers/prerequisites.md#supported-operating-systems).

+ - is able to connect through the firewall to communicate over the internet and these [URLs](../servers/network-requirements.md#urls) are not blocked.

+For Java specifically, you need to specifically include the artifacts into the build/target folder when copying resources. Here's an example on how to do it in Maven:

+If some of the properties in your JSON payload are objects with properties, you can refer to those directly by using dot (`.`) notation. This notation doesn't work for [Cosmos DB](./functions-bindings-cosmosdb-v2.md) or [Table storage](./functions-bindings-storage-table-output.md) bindings.

+|**maxMessageBatchSize**|`1000`|The maximum number of messages that will be passed to each function call. This setting only applies for functions that receive a batch of messages.|

+|**`AzureWebJobsStorage`**| Storage account connection string, or<br/>`UseDevelopmentStorage=true`| Contains the connection string for an Azure storage account. Required when using triggers other than HTTP. For more information, see the [`AzureWebJobsStorage`] reference.<br/>When you have the [Azurite Emulator](../storage/common/storage-use-azurite.md) installed locally and you set [`AzureWebJobsStorage`] to `UseDevelopmentStorage=true`, Core Tools uses the emulator. The emulator is useful during development, but you should test with an actual storage connection before deployment.|

+ JAVA_VERSION: '1.8.x' # set this to the Java version to use

+- Azure Functions 4.x uses Azure.Identity and Azure.Security.KeyVault.Secrets for the Key Vault provider and has deprecated the use of Microsoft.Azure.KeyVault. See the Key Vault option in [Secret Repositories](security-concepts.md#secret-repositories) for more information on how to configure function app settings. ([#2048](https://github.com/Azure/Azure-Functions/issues/2048))

+ Title: Add a pie chart layer to an Azure Maps Power BI visual

+description: In this article, you will learn how to use the pie chart layer in an Azure Maps Power BI visual.

+# Add a pie chart layer

+In this article, you will learn how to add a pie chart layer to an Azure Maps Power BI visual.

+A pie chart is a visual representation of data in the form of a circular chart or *pie* where each slice represents an element of the dataset that is shown as a percentage of the whole. A list of numerical variables along with categorical (location) variables are required to represent data in the form of a pie chart.

+> [!NOTE]

+> The data used in this article comes from the [Power BI Sales and Marketing Sample](/power-bi/create-reports/sample-datasets#download-original-sample-power-bi-files).

+## Prerequisites

+- [Get started with Azure Maps Power BI visual](./power-bi-visual-get-started.md).

+- Understand [layers in the Azure Maps Power BI visual](./power-bi-visual-understanding-layers.md).

+## Add the pie chart layer

+The pie chart layer is added automatically based on what fields in the **Visualizations** pane have values, these fields include location, size and legend.

+The following steps will walk you through creating a pie chart layer.

+1. Select two location sources from the **Fields** pane, such as city/state, to add to the **Location** field.

+1. Select a numerical field from your table, such as sales, and add it to the **Size** field in the **Visualizations** pane. This field must contain the numerical values used in the pie chart.

+1. Select a data field from your table that can be used as the category that the numerical field applies to, such as *manufacturer*, and add it to the **Legend** field in the **Visualizations** pane. This will appear as the slices of the pie, the size of each slice is a percentage of the whole based on the value in the size field, such as the number of sales broken out by manufacturer.

+1. Next, in the **Format** tab of the **Visualizations** pane, switch the **Bubbles** toggle to **On**.

+The pie chart layer should now appear. Next you can adjust the Pie chart settings such as size and transparency.

+## Pie chart layer settings

+Pie Chart layer is an extension of the bubbles layer, so all settings are made in the **Bubbles** section. If a field is passed into the **Legend** bucket of the **Fields** pane, the pie charts will be populated and will be colored based on their categorization. The outline of the pie chart is white by default but can be changed to a new color. The following are the settings in the **Format** tab of the **Visualizations** pane that are available to a **Pie Chart layer**.

+| Setting | Description |

+|--|-|

+| Size | The size of each bubble. |

+| Fill transparency | Transparency of each pie chart. |

+| Outline color | Color that outlines the pie chart. |

+| Outline transparency | Transparency of the outline. |

+| Outline width | Width of the outline in pixels. |

+| Min zoom | Minimum zoom level tiles are available. |

+| Max zoom | Maximum zoom level tiles are available. |

+| Layer position | Specifies the position of the layer relative to other map layers. |

+## Next steps

+Change how your data is displayed on the map:

+> [!div class="nextstepaction"]

+> [Add a bar chart layer](power-bi-visual-add-bar-chart-layer.md)

+> [!div class="nextstepaction"]

+> [Add a heat map layer](power-bi-visual-add-heat-map-layer.md)

+- For installing the agent on physical servers and virtual machines hosted *outside* of Azure (i.e. on-premises), you must [install the Azure Arc Connected Machine agent](../../azure-arc/servers/agent-overview.md) first (at no added cost)

+### Delayed telemetry, overloading network, or inefficient transmission

+System.Diagnostics.Tracing has an [Autoflush feature](https://docs.microsoft.com/dotnet/api/system.diagnostics.trace.autoflush). This causes SDK to flush with every telemetry item, which is undesirable, and can cause logging adapter issues like delayed telemetry, overloading network, inefficient transmission, etc.

+If you're using the Java SDK, use the [Java log adapters](java-2x-trace-logs.md).

+* If you're using System.Diagnostics.Trace, make sure that you've it [configured in *web.config*](/dotnet/api/system.diagnostics.eventlogtracelistener).

+### 2.8.44

+- Updated ApplicationInsights .NET/.NET Core SDK to 2.20.1-redfield.

+- Enabled SQL query collection.

+- Enabled support for Azure Active Directory (AAD) authentication.

+## Enable auto-instrumentation monitoring

+* [Upgrade by enabling via the portal](#enable-auto-instrumentation-monitoring). (Even if you have the Application Insights extension for Azure App Service installed, the UI shows only **Enable** button. Behind the scenes, the old private site extension will be removed.)

+ If it isn't running, follow the [enable Application Insights monitoring instructions](#enable-auto-instrumentation-monitoring).

+> Manually adding an Application Insights site extension via **Development Tools** > **Extensions** is deprecated. This method of extension installation was dependent on manual updates for each new version. The latest stable release of the extension is now [preinstalled](https://github.com/projectkudu/kudu/wiki/Azure-Site-Extensions) as part of the App Service image. The files are located in `d:\Program Files (x86)\SiteExtensions\ApplicationInsightsAgent` and are automatically updated with each stable release. If you follow the auto-instrumentation instructions to enable monitoring below, it will automatically remove the deprecated extension for you.

+> If both auto-instrumentation monitoring and manual SDK-based instrumentation are detected, only the manual instrumentation settings will be honored. This is to prevent duplicate data from being sent. To learn more about this, check out the [troubleshooting section](#troubleshooting) below.

+## Enable auto-instrumentation monitoring

+* [Upgrade by enabling via the portal](#enable-auto-instrumentation-monitoring). (Even if you have the Application Insights extension for Azure App Service installed, the UI shows only **Enable** button. Behind the scenes, the old private site extension will be removed.)

+ If it is not running, follow the [enable Application Insights monitoring instructions](#enable-auto-instrumentation-monitoring).

+> If both auto-instrumentation monitoring and manual SDK-based instrumentation are detected, only the manual instrumentation settings will be honored. This is to prevent duplicate data from being sent. To learn more about this, check out the [troubleshooting section](#troubleshooting) below.

+* [Set up Availability web tests](monitor-web-app-availability.md) to be alerted if your site is down.

+- **Auto-instrumentation application monitoring** (ApplicationInsightsAgent).

+ - The following are support for auto-instrumentation monitoring:

+ * If you need to make custom API calls to track events/dependencies not captured by default with auto-instrumentation monitoring, you would need to use this method. Check out the [API for custom events and metrics article](./api-custom-events-metrics.md) to learn more.

+> If both auto-instrumentation monitoring and manual SDK-based instrumentation are detected, in .NET only the manual instrumentation settings will be honored, while in Java only the auto-instrumentation will be emitting the telemetry. This is to prevent duplicate data from being sent.

+- Learn how to enable auto-instrumentation application monitoring for your [.NET Core](./azure-web-apps-net-core.md), [.NET](./azure-web-apps-net.md), [Java](./azure-web-apps-java.md) or [Nodejs](./azure-web-apps-nodejs.md) application running on App Service.

+A request telemetry item (in [Application Insights](./app-insights-overview.md)) represents the logical sequence of execution triggered by an external request to your application. Every request execution is identified by unique `ID` and `url` containing all the execution parameters. You can group requests by logical `name` and define the `source` of this request. Code execution can result in `success` or `fail` and has a certain `duration`. Both success and failure executions may be grouped further by `resultCode`. Start time for the request telemetry defined on the envelope level.

+By default, ASP.NET Core applications have an Application Insights logging provider registered when they're configured through the [code](./asp-net-core.md) or [codeless](./azure-web-apps-net-core.md#enable-auto-instrumentation-monitoring) approach. The registered provider is configured to automatically capture log events with a severity of <xref:Microsoft.Extensions.Logging.LogLevel.Warning?displayProperty=nameWithType> or greater. You can customize severity and categories. For more information, see [Logging level](#logging-level).

+ [!INCLUDE [azure-monitor-log-analytics-rebrand](../../../includes/azure-monitor-instrumentation-key-deprecation.md)]

+Matches can be either `strict` or `regexp`. Regular expression matches are performed against the entire attribute value,

+so if you want to match a value that contains `abc` anywhere in it, then you need to use `.*abc.*`.

+* **Required field**: `matchType` controls how items in `spanNames` arrays and `attributes` arrays are interpreted.

+ Possible values are `regexp` and `strict`. Regular expression matches are performed against the entire attribute value,

+ so if you want to match a value that contains `abc` anywhere in it, then you need to use `.*abc.*`.

+* **Required field**: `matchType` controls how items in `spanNames` arrays and `attributes` arrays are interpreted.

+ Possible values are `regexp` and `strict`. Regular expression matches are performed against the entire attribute value,

+ so if you want to match a value that contains `abc` anywhere in it, then you need to use `.*abc.*`.

+ * `matchType` controls how items in `attributes` arrays are interpreted. Possible values are `regexp` and `strict`.

+ Regular expression matches are performed against the entire attribute value,

+ so if you want to match a value that contains `abc` anywhere in it, then you need to use `.*abc.*`.

+ Regular expression matches are performed against the entire attribute value,

+ so if you want to match a value that contains `abc` anywhere in it, then you need to use `.*abc.*`.

+ * `metricNames` must match at least one of the items.

+If using Java 9 or later, please check if the JVM has `jdk.crypto.cryptoki` module included in the jmods folder. Also if you are building a custom Java runtime using `jlink` please make sure to include the same module.

+Application Insights can be used with any web pages - you just add a short piece of JavaScript. If your web service is [Java](java-in-process-agent.md) or [ASP.NET](asp-net.md), you can use the server-side SDKs with the client-side JavaScript SDK to get an end-to-end understanding of your app's performance.

+2. Copy the _instrumentation key_ (also known as "iKey") or [connection string](#connection-string-setup) for the resource where you want your JavaScript telemetry to be sent (from step 1.) You'll add it to the `instrumentationKey` or `connectionString` setting of the Application Insights JavaScript SDK.

+If your app doesn't use npm, you can directly instrument your webpages with Application Insights by pasting this snippet at the top of each your pages. Preferably, it should be the first script in your `<head>` section so that it can monitor any potential issues with all of your dependencies and optionally any JavaScript errors. If you're using Blazor Server App, add the snippet at the top of the file `_Host.cshtml` in the `<head>` section.

+This version of the snippet detects and reports failures when loading the SDK from the CDN as an exception to the Azure Monitor portal (under the failures &gt; exceptions &gt; browser), this exception provides visibility into failures of this type so that you're aware that your application isn't reporting telemetry (or other exceptions) as expected. This signal is an important measurement in understanding that you have lost telemetry because the SDK didn't load or initialize which can lead to:

+Reporting of this failure as an exception to the portal doesn't use the configuration option ```disableExceptionTracking``` from the application insights configuration and therefore if this failure occurs it will always be reported by the snippet, even when the window.onerror support is disabled.

+Reporting of SDK load failures is not supported on Internet Explorer 8 or earlier. This reduces the minified size of the snippet by assuming that most environments aren't exclusively IE 8 or less. If you have this requirement and you wish to receive these exceptions, you'll need to either include a fetch poly fill or create your own snippet version that uses ```XDomainRequest``` instead of ```XMLHttpRequest```, it's recommended that you use the [provided snippet source code](https://github.com/microsoft/ApplicationInsights-JS/blob/master/AISKU/snippet/snippet.js) as a starting point.

+All configuration options have now been move towards the end of the script to help avoid accidentally introducing JavaScript errors that wouldn't just cause the SDK to fail to load, but also it would disable the reporting of the failure.

+| name | string *[optional]* | The global name for the initialized SDK, defaults to `appInsights`. So ```window.appInsights``` will be a reference to the initialized instance. Note: if you provide a name value or a previous instance appears to be assigned (via the global name appInsightsSDK) then this name value will also be defined in the global namespace as ```window.appInsightsSDK=<name value>```. The SDK initialization code uses this reference to ensure it's initializing and updating the correct snippet skeleton and proxy methods.

+| crossOrigin | string *[optional]* | By including this setting, the script tag added to download the SDK will include the crossOrigin attribute with this string value. When not defined (the default) no crossOrigin attribute is added. Recommended values aren't defined (the default); ""; or "anonymous" (For all valid values see [HTML attribute: `crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) documentation)

+For either the NPM or Snippet setup, you can also configure your instance of Application Insights using a Connection String. Replace the `instrumentationKey` field with the `connectionString` field.

+By default the Application Insights JavaScript SDK autocollects many telemetry items that are helpful in determining the health of your application and the underlying user experience. These include:

+Telemetry initializers are used to modify the contents of collected telemetry before being sent from the user's browser. They can also be used to prevent certain telemetry from being sent, by returning `false`. Multiple telemetry initializers can be added to your Application Insights instance, and they're executed in order of adding them.

+The input argument to `addTelemetryInitializer` is a callback that takes a [`ITelemetryItem`](https://github.com/microsoft/ApplicationInsights-JS/blob/master/API-reference.md#addTelemetryInitializer) as an argument and returns a `boolean` or `void`. If returning `false`, the telemetry item isn't sent, else it proceeds to the next telemetry initializer, if any, or is sent to the telemetry collection endpoint.

+| maxBatchSizeInBytes | Max size of telemetry batch. If a batch exceeds this limit, it's immediately sent and a new batch is started | numeric<br/>10000 |

+| disable&#8203;ExceptionTracking | If true, exceptions aren't autocollected. | boolean<br/> false |

+| disableTelemetry | If true, telemetry isn't collected or sent. | boolean<br/>false |

+| enableDebug | If true, **internal** debugging data is thrown as an exception **instead** of being logged, regardless of SDK logging settings. Default is false. <br>***Note:*** Enabling this setting will result in dropped telemetry whenever an internal error occurs. This can be useful for quickly identifying issues with your configuration or usage of the SDK. If you don't want to lose telemetry while debugging, consider using `consoleLoggingLevel` or `telemetryLoggingLevel` instead of `enableDebug`. | boolean<br/>false |

+| autoTrackPageVisitTime | If true, on a pageview, the _previous_ instrumented page's view time is tracked and sent as telemetry and a new timer is started for the current pageview. It's sent as a custom metric named `PageVisitTime` in `milliseconds` and is calculated via the Date [now()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) function (if available) and falls back to (new Date()).[getTime()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime) if now() is unavailable (IE8 or less). Default is false. | boolean<br/>false |

+| disableAjaxTracking | If true, Ajax calls aren't autocollected. | boolean<br/> false |

+| disableFetchTracking | If true, Fetch requests aren't autocollected.|boolean<br/>true |

+| disableFlush&#8203;OnBeforeUnload | If true, flush method won't be called when onBeforeUnload event triggers | boolean<br/> false |

+| ~~isCookieUseDisabled~~<br>disableCookiesUsage | If true, the SDK won't store or read any data from cookies. Disables the User and Session cookies and renders the usage blades and experiences useless. isCookieUseDisable is deprecated in favor of disableCookiesUsage, when both are provided disableCookiesUsage takes precedence.<br>(Since v2.6.0) And if `cookieCfg.enabled` is also defined it will take precedence over these values, Cookie usage can be re-enabled after initialization via the core.getCookieMgr().setEnabled(true). | alias for [`cookieCfg.enabled`](#icookiemgrconfig)<br>false |

+| isStorageUseDisabled | If true, the SDK won't store or read any data from local and session storage. | boolean<br/> false |

+| appId | AppId is used for the correlation between AJAX dependencies happening on the client-side with the server-side requests. When Beacon API is enabled, it canΓÇÖt be used automatically, but can be set manually in the configuration. |string<br/> null |

+| enableUnhandled&#8203;PromiseRejection&#8203;Tracking | If true, unhandled promise rejections will be autocollected and reported as a JavaScript error. When disableExceptionTracking is true (don't track exceptions), the config value will be ignored and unhandled promise rejections won't be reported. | boolean<br/> false |

+| perfEvtsSendAll | When _enablePerfMgr_ is enabled and the [IPerfManager](https://github.com/microsoft/ApplicationInsights-JS/blob/master/shared/AppInsightsCore/src/JavaScriptSDK.Interfaces/IPerfManager.ts) fires a [INotificationManager](https://github.com/microsoft/ApplicationInsights-JS/blob/master/shared/AppInsightsCore/src/JavaScriptSDK.Interfaces/INotificationManager.ts).perfEvent() this flag determines whether an event is fired (and sent to all listeners) for all events (true) or only for 'parent' events (false &lt;default&gt;).<br />A parent [IPerfEvent](https://github.com/microsoft/ApplicationInsights-JS/blob/master/shared/AppInsightsCore/src/JavaScriptSDK.Interfaces/IPerfEvent.ts) is an event where no other IPerfEvent is still running at the point of this event being created and its _parent_ property isn't null or undefined. Since v2.5.7 | boolean<br />false |

+| idLength | The default length used to generate new random session and user id values. Defaults to 22, previous default value was 5 (v2.5.8 or less), if you need to keep the previous maximum length you should set this value to 5. | numeric<br />22 |

+Cookie Configuration for instance-based cookie management added in version 2.6.0.

+| enabled | A boolean that indicates whether the use of cookies by the SDK is enabled by the current instance. If false, the instance of the SDK initialized by this configuration won't store or read any data from cookies | boolean<br/> true |

+By setting `autoTrackPageVisitTime: true`, the time in milliseconds a user spends on each page is tracked. On each new PageView, the duration the user spent on the *previous* page is sent as a [custom metric](../essentials/metrics-custom-overview.md) named `PageVisitTime`. This custom metric is viewable in the [Metrics Explorer](../essentials/metrics-getting-started.md) as a "log-based metric".

+If any of your third-party servers that the client communicates with canΓÇÖt accept the `Request-Id` and `Request-Context` headers, and you canΓÇÖt update their configuration, then you'll need to put them into an exclude list via the `correlationHeaderExcludedDomains` configuration property. This property supports wildcards.

+The server-side needs to be able to accept connections with those headers present. Depending on the `Access-Control-Allow-Headers` configuration on the server-side it's often necessary to extend the server-side list by manually adding `Request-Id` and `Request-Context`.

+Currently, we offer a separate [React plugin](javascript-react-plugin.md), which you can initialize with this SDK. It will also accomplish route change tracking for you, and collect other React specific telemetry.

+Browser/client-side data can be viewed by going to **Metrics** and adding individual metrics you're interested in:

+To query your telemetry collected by the JavaScript SDK, select the **View in Logs (Analytics)** button. By adding a `where` statement of `client_Type == "Browser"`, you'll only see data from the JavaScript SDK and any server-side telemetry collected by other SDKs will be excluded.

+This version comes with the bare minimum number of features and functionalities and relies on you to build it up as you see fit. For example, it performs no autocollection (uncaught exceptions, AJAX, etc.). The APIs to send certain telemetry types, like `trackTrace`, `trackException`, etc., aren't included in this version, so you'll need to provide your own wrapper. The only API that is available is `track`. A [sample](https://github.com/Azure-Samples/applicationinsights-web-sample1/blob/master/testlightsku.html) is located here.

+- To allow for better API signatures, some of the API calls, such as trackPageView and trackException, have been updated. Running in Internet Explorer 8 and earlier versions of the browser isn't supported.

+While the script is downloading from the CDN, all tracking of your page is queued. Once the downloaded script finishes asynchronously initializing, all events that were queued are tracked. As a result, you won't lose any telemetry during the entire life cycle of your page. This setup process provides your page with a seamless analytics system, invisible to your users.

+As an SDK there are numerous users that canΓÇÖt control the browsers that their customers use. As such we need to ensure that this SDK continues to "work" and doesn't break the JS execution when loaded by an older browser. While it would be ideal to not support IE8 and older generation (ES3) browsers, there are numerous large customers/users that continue to require pages to "work" and as noted they may or canΓÇÖt control which browser that their end users choose to use.

+This does NOT mean that we'll only support the lowest common set of features, just that we need to maintain ES3 code compatibility and when adding new features they'll need to be added in a manner that wouldn't break ES3 JavaScript parsing and added as an optional feature.

+To learn more advanced configurations for monitoring websites, check out the [JavaScript SDK reference article](./javascript.md).

+| [OfficeActivity](/azure/azure-monitor/reference/tables/officeactivity) | |

+| [Perf](/azure/azure-monitor/reference/tables/perf) | Partial support ΓÇô only windows perf data is currently supported. |

+- [Permissions to create Data Collection Rule objects](https://docs.microsoft.com/azure/azure-monitor/essentials/data-collection-rule-overview#permissions) in the workspace.

+- [Learn more about writing transformation queries](../essentials/data-collection-rule-transformations.md)

+- The operating system of the machine isn't supported by the server agents enabled by Azure Arc. For more information, see [Supported operating systems](../../azure-arc/servers/prerequisites.md#supported-operating-systems).

+* [Modify Active Directory connections for Azure NetApp Files](modify-active-directory-connections.md)

+* [Modify Active Directory connections for Azure NetApp Files](modify-active-directory-connections.md)

+Several features of Azure NetApp Files require that you have an Active Directory connection. For example, you need to have an Active Directory connection before you can create an [SMB volume](azure-netapp-files-create-volumes-smb.md), a [NFSv4.1 Kerberos volume](configure-kerberos-encryption.md), or a [dual-protocol volume](create-volumes-dual-protocol.md). This article shows you how to create and manage Active Directory connections for Azure NetApp Files.

+* [Modify Active Directory connections](modify-active-directory-connections.md)

+ Title: Modify an Active Directory Connection for Azure NetApp Files | Microsoft Docs

+description: This article shows you how to modify Active Directory connections for Azure NetApp Files.

+documentationcenter: ''

+editor: ''

+ms.assetid:

+ na

+# Modify Active Directory connections for Azure NetApp Files

+Once you have [created an Active Directory connection](create-active-directory-connections.md) in Azure NetApp Files, you can modify it. When modifying an Active Directory, not all configurations can be modified.

+## Modify Active Directory connections

+1. Select **Active Directory connections**. Then, select **Edit** to edit an existing AD connection.

+1. In the **Edit Active Directory** window that appears, modify Active Directory connection configurations as needed. See [Options for Active Directory connections](#options-for-active-directory-connections) for an explanation of what fields can be modified.

+## Options for Active Directory connections

+|Field Name |What it is |Can it be modified? |Considerations & Impacts |Effect |

+|:-:|:--|:-:|:--|:--|

+| Primary DNS | Primary DNS server IP addresses for the Active Directory domain. | Yes | None* | New DNS IP will be used for DNS resolution. |

+| Secondary DNS | Secondary DNS server IP addresses for the Active Directory domain. | Yes | None* | New DNS IP will be used for DNS resolution in case primary DNS fails. |

+| AD DNS Domain Name | The domain name of your Active Directory Domain Services that you want to join.ΓÇ»| No | None | N/A |

+| AD Site Name | The site to which the domain controller discovery is limited. | Yes | This should match the site name in Active Directory Sites and Services. See footnote.* | Domain discovery will be limited to the new site name. If not specified, "Default-First-Site-Name" will be used. |

+| SMB Server (Computer Account) Prefix | Naming prefix for the machine account in Active Directory that Azure NetApp Files will use for the creation of new accounts. See footnote.* | Yes | Existing volumes need to be mounted again as the mount is changed for SMB shares and NFS Kerberos volumes.* | Renaming the SMB server prefix after you create the Active Directory connection is disruptive. You'll need to remount existing SMB shares and NFS Kerberos volumes after renaming the SMB server prefix as the mount path will change. |

+| Organizational Unit Path | The LDAP path for the organizational unit (OU) where SMB server machine accounts will be created. `OU=second level`, `OU=first level`| No | If you are using Azure NetApp Files with Azure Active Directory Domain Services (AADDS), the organizational path is `OU=AADDC Computers` when you configure Active Directory for your NetApp Account. | Machine accounts will be placed under the OU specified. If not specified, the default of `OU=Computers` is used by default. |

+| AES Encryption | To take advantage of the strongest security with Kerberos-based communication, you can enable AES-256 and AES-128 encryption on the SMB server. | Yes | If you enable AES encryption, the user credentials used to join Active Directory must have the highest corresponding account option enabled, matching the capabilities enabled for your Active Directory. For example, if your Active Directory has only AES-128 enabled, you must enable the AES-128 account option for the user credentials. If your Active Directory has the AES-256 capability, you must enable the AES-256 account option (which also supports AES-128). If your Active Directory does not have any Kerberos encryption capability, Azure NetApp Files uses DES by default.* | Enable AES encryption for Active Directory Authentication |

+| LDAP Signing | This functionality enables secure LDAP lookups between the Azure NetApp Files service and the user-specified Active Directory Domain Services domain controller. | Yes | LDAP signing to Require Signing in group policy* | This provides ways to increase the security for communication between LDAP clients and Active Directory domain controllers. |

+| Allow local NFS users with LDAP | If enabled, this option will manage access for local users and LDAP users. | Yes | This option will allow access to local users. It is not recommended and, if enabled, should only be used for a limited time and later disabled. | If enabled, this option will allow access to local users and LDAP users. If access is needed for only LDAP users, this option must be disabled. |

+| LDAP over TLS | If enabled, LDAP over TLS will be configured to support secure LDAP communication to active directory. | Yes | None | If LDAP over TLS is enabled and if the server root CA certificate is already present in the database, then LDAP traffic is secured using the CA certificate. If a new certificate is passed in, that certificate will be installed. |

+| Server root CA Certificate | When LDAP over SSL/TLS is enabled, the LDAP client is required to have base64-encoded Active Directory Certificate Service's self-signed root CA certificate. | Yes | None* | LDAP traffic secured with new certificate only if LDAP over TLS is enabled |

+| Backup policy users | You can include additional accounts that require elevated privileges to the computer account created for use with Azure NetApp Files. See [Create and manage Active Directory connections](create-active-directory-connections.md#create-an-active-directory-connection) for more information. | Yes | None* | The specified accounts will be allowed to change the NTFS permissions at the file or folder level. |

+| Administrators | Specify users or groups that will be given administrator privileges on the volume | Yes | None | User account will receive administrator privileges |

+| Username | Username of the Active Directory domain administrator | Yes | None* | Credential change to contact DC |

+| Password | Password of the Active Directory domain administrator | Yes | None* | Credential change to contact DC |

+| Kerberos Realm: AD Server Name | The name of the Active Directory machine. This option is only used when creating a Kerberos volume. | Yes | None* | |

+| Kerberos Realm: KDC IP | Specifies the IP address of the Kerberos Distribution Center (KDC) server. KDC in Azure NetApp Files is an Active Directory server | Yes | None | A new KDC IP address will be used | None* |

+| Region | The region where the Active Directory credentials are associated | No | None | N/A |

+| User DN | User domain name, which overrides the base DN for user lookups Nested userDN can be specified in `OU=subdirectory, OU=directory, DC=domain, DC=com` format.​ | Yes | None* | User search scope gets limited to User DN instead of base DN. |

+| Group DN | Group domain name. groupDN overrides the base DN for group lookups. Nested groupDN can be specified in `OU=subdirectory, OU=directory, DC=domain, DC=com` format.​ | Yes | None* | Group search scope gets limited to Group DN instead of base DN. |

+| Group Membership Filter | The custom LDAP search filter to be used when looking up group membership from LDAP server.​ `groupMembershipFilter` can be specified with the `(gidNumber=*)` format. | Yes | None* | Group membership filter will be used while querying group membership of a user from LDAP server. |

+| Security Privilege Users | You can grant security privilege (`SeSecurityPrivilege`) to users that require elevated privilege to access the Azure NetApp Files volumes. The specified user accounts will be allowed to perform certain actions on Azure NetApp Files SMB shares that require security privilege not assigned by default to domain users. See [Create and manage Active Directory connections](create-active-directory-connections.md#create-an-active-directory-connection) for more information. | Yes | Using this feature is optional and supported only for SQL Server. The domain account used for installing SQL Server must already exist before you add it to the Security privilege users field. When you add the SQL Server installer's account to Security privilege users, the Azure NetApp Files service might validate the account by contacting the domain controller. The command might fail if it cannot contact the domain controller. For more information about `SeSecurityPrivilege` and SQL Server, see [SQL Server installation fails if the Setup account doesn't have certain user rights](/troubleshoot/sql/install/installation-fails-if-remove-user-right.md).* | Allows non-administrator accounts to use SQL severs on top of ANF volumes. |

+**\*There is no impact on a modified entry only if the modifications are entered correctly. If you enter data incorrectly, users and applications will lose access.**

+## Next Steps

+* [Configure ADDS LDAP with extended groups for NFS](configure-ldap-extended-groups.md)

+* [Configure ADDS LDAP over TLS](configure-ldap-over-tls.md)

+* [Create and manage Active Directory connections](create-active-directory-connections.md)

+In NFSv4.1, sessions define the relationship between the client and the server. Whether the mounted NFS file systems sit atop one connection or many (as is the case with `nconnect`), the rules for the session apply. At session setup, the client and server negotiate the maximum requests for the session, settling on the lower of the two supported values. Azure NetApp Files supports 180 outstanding requests, and Linux clients default to 64. The following table shows the session limits:

+The local cache is found in:

+- On Windows

+ ```path

+ %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

+ ```

+- On Linux

+ ```path

+ /home/<username>/.bicep

+ ```

+- [Azure CLI](deploy-cli.md)

+- [Cloud Shell](deploy-cloud-shell.md)

+- [PowerShell](deploy-powershell.md)

+Bicep provides concise syntax, reliable type safety, and support for code reuse. Bicep offers a first-class authoring experience for your [infrastructure-as-code](/devops/deliver/what-is-infrastructure-as-code) solutions in Azure.

+## Azure Health Data Services

+### Azure Health Data Services limits

+> | workspaces / sqlPools | workspace | 1-15 | Can contain only letters, numbers, or underscore.<br><br>Can't contain [reserved word](../troubleshooting/error-reserved-resource-name.md). |

+> [!WARNING]

+> Tags are stored as plain text. Never add sensitive values to tags. Sensitive values could be exposed through many methods, including cost reports, tag taxonomies, deployment histories, exported templates, and monitoring logs.

+1. Make sure you have Azure Function Core Tools, Java (version 11 in the sample) and maven installed.

+ Title: Create and utilize Azure Active Directory server logins

+description: This article guides you through creating and utilizing Azure Active Directory logins in the virtual master database of Azure SQL

+# Tutorial: Create and utilize Azure Active Directory server logins

+> [!NOTE]

+> Azure Active Directory (Azure AD) server principals (logins) are currently in public preview for Azure SQL Database. Azure SQL Managed Instance can already utilize Azure AD logins.

+This article guides you through creating and utilizing [Azure Active Directory (Azure AD) principals (logins)](authentication-azure-ad-logins.md) in the virtual master database of Azure SQL.

+In this tutorial, you learn how to:

+> [!div class="checklist"]

+> - Create an Azure AD login in the virtual master database with the new syntax extension for Azure SQL Database

+> - Create a user mapped to an Azure AD login in the virtual master database

+> - Grant server roles to an Azure AD user

+> - Disable an Azure AD login

+## Prerequisites

+- A SQL Database or SQL Managed Instance with a database. See [Quickstart: Create an Azure SQL Database single database](single-database-create-quickstart.md) if you haven't already created an Azure SQL Database, or [Quickstart: Create an Azure SQL Managed Instance](../managed-instance/instance-create-quickstart.md).

+- Azure AD authentication set up for SQL Database or Managed Instance. For more information, see [Configure and manage Azure AD authentication with Azure SQL](authentication-aad-configure.md).

+- This article instructs you on creating an Azure AD login and user within the virtual master database. Only an Azure AD admin can create a user within the virtual master database, so we recommend you use the Azure AD admin account when going through this tutorial. An Azure AD principal with the `loginmanager` role can create a login, but not a user within the virtual master database.

+## Create Azure AD login

+1. Create an Azure SQL Database login for an Azure AD account. In our example, we'll use `bob@contoso.com` that exists in our Azure AD domain called `contoso`. A login can also be created from an Azure AD group or [service principal (applications)](authentication-aad-service-principal.md). For example, `mygroup` that is an Azure AD group consisting of Azure AD accounts that are a member of that group. For more information, see [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true).

+ > [!NOTE]

+ > The first Azure AD login must be created by the Azure Active Directory admin. A SQL login cannot create Azure AD logins.

+1. Using [SQL Server Management Studio (SSMS)](/sql/ssms/download-sql-server-management-studio-ssms), log into your SQL Database with the Azure AD admin account set up for the server.

+1. Run the following query:

+ ```sql

+ Use master

+ CREATE LOGIN [bob@contoso.com] FROM EXTERNAL PROVIDER

+ GO

+ ```

+1. Check the created login in `sys.server_principals`. Execute the following query:

+ ```sql

+ SELECT name, type_desc, type, is_disabled

+ FROM sys.server_principals

+ WHERE type_desc like 'external%'

+ ```

+ You would see a similar output to the following:

+ ```output

+ Name type_desc type is_disabled

+ bob@contoso.com EXTERNAL_LOGIN E 0

+ ```

+1. The login `bob@contoso.com` has been created in the virtual master database.

+## Create user from an Azure AD login

+1. Now that we've created an Azure AD login, we can create a database-level Azure AD user that is mapped to the Azure AD login in the virtual master database. We'll continue to use our example, `bob@contoso.com` to create a user in the virtual master database, as we want to demonstrate adding the user to special roles. Only an Azure AD admin or SQL server admin can create users in the virtual master database.

+1. We're using the virtual master database, but you can switch to a database of your choice if you want to create users in other databases. Run the following query.

+ ```sql

+ Use master

+ CREATE USER [bob@contoso.com] FROM LOGIN [bob@contoso.com]

+ ```

+ > [!TIP]

+ > Although it is not required to use Azure AD user aliases (for example, `bob@contoso.com`), it is a recommended best practice to use the same alias for Azure AD users and Azure AD logins.

+1. Check the created user in `sys.database_principals`. Execute the following query:

+ ```sql

+ SELECT name, type_desc, type

+ FROM sys.database_principals

+ WHERE type_desc like 'external%'

+ ```

+ You would see a similar output to the following:

+ ```output

+ Name type_desc type

+ bob@contoso.com EXTERNAL_USER E

+ ```

+> [!NOTE]

+> The existing syntax to create an Azure AD user without an Azure AD login is still supported, and requires the creation of a contained user inside SQL Database (without login).

+>

+> For example, `CREATE USER [bob@contoso.com] FROM EXTERNAL PROVIDER`.

+## Grant server-level roles to Azure AD logins

+You can add logins to the [built-in server-level roles](security-server-roles.md#built-in-server-level-roles), such as the **##MS_DefinitionReader##**, **##MS_ServerStateReader##**, or **##MS_ServerStateManager##** role.

+> [!NOTE]

+> The server-level roles mentioned here are not supported for Azure AD groups.

+```sql

+ALTER SERVER ROLE ##MS_DefinitionReader## ADD MEMBER [AzureAD_object];

+```

+```sql

+ALTER SERVER ROLE ##MS_ServerStateReader## ADD MEMBER [AzureAD_object];

+```

+```sql

+ALTER SERVER ROLE ##MS_ServerStateManager## ADD MEMBER [AzureAD_object];

+```

+Permissions aren't effective until the user reconnects. Flush the DBCC cache as well:

+```sql

+DBCC FLUSHAUTHCACHE

+DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS

+```

+To check which Azure AD logins are part of server-level roles, run the following query:

+```sql

+SELECT roles.principal_id AS RolePID,roles.name AS RolePName,

+ server_role_members.member_principal_id AS MemberPID, members.name AS MemberPName

+ FROM sys.server_role_members AS server_role_members

+ INNER JOIN sys.server_principals AS roles

+ ON server_role_members.role_principal_id = roles.principal_id

+ INNER JOIN sys.server_principals AS members

+ ON server_role_members.member_principal_id = members.principal_id;

+```

+## Grant special roles for Azure AD users

+[Special roles for SQL Database](/sql/relational-databases/security/authentication-access/database-level-roles#special-roles-for--and-azure-synapse) can be assigned to users in the virtual master database.

+In order to grant one of the special database roles to a user, the user must exist in the virtual master database.

+To add a user to a role, you can run the following query:

+```sql

+ALTER ROLE [dbamanger] ADD MEMBER [AzureAD_object]

+```

+To remove a user from a role, run the following query:

+```sql

+ALTER ROLE [dbamanger] DROP MEMBER [AzureAD_object]

+```

+`AzureAD_object` can be an Azure AD user, group, or service principal in Azure AD.

+In our example, we created the user `bob@contoso.com`. Let's give the user the **dbmanager** and **loginmanager** roles.

+1. Run the following query:

+ ```sql

+ ALTER ROLE [dbamanger] ADD MEMBER [bob@contoso.com]

+ ALTER ROLE [loginmanager] ADD MEMBER [bob@contoso.com]

+ ```

+1. Check the database role assignment by running the following query:

+ ```sql

+ SELECT DP1.name AS DatabaseRoleName,

+ isnull (DP2.name, 'No members') AS DatabaseUserName

+ FROM sys.database_role_members AS DRM

+ RIGHT OUTER JOIN sys.database_principals AS DP1

+ ON DRM.role_principal_id = DP1.principal_id

+ LEFT OUTER JOIN sys.database_principals AS DP2

+ ON DRM.member_principal_id = DP2.principal_id

+ WHERE DP1.type = 'R'and DP2.name like 'bob%'

+ ```

+ You would see a similar output to the following:

+ ```output

+ DatabaseRoleName DatabaseUserName

+ dbmanager bob@contoso.com

+ loginmanager bob@contoso.com

+ ```

+## Optional - Disable a login

+The [ALTER LOGIN (Transact-SQL)](/sql/t-sql/statements/alter-login-transact-sql?view=azuresqldb-current&preserve-view=true) DDL syntax can be used to enable or disable an Azure AD login in Azure SQL Database.

+```sql

+ALTER LOGIN [bob@contoso.com] DISABLE

+```

+For the `DISABLE` or `ENABLE` changes to take immediate effect, the authentication cache and the **TokenAndPermUserStore** cache must be cleared using the following T-SQL commands:

+```sql

+DBCC FLUSHAUTHCACHE

+DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS

+```

+Check that the login has been disabled by executing the following query:

+```sql

+SELECT name, type_desc, type

+FROM sys.server_principals

+WHERE is_disabled = 1

+```

+A use case for this would be to allow read-only on [geo-replicas](active-geo-replication-overview.md), but deny connection on a primary server.

+## See also

+For more information and examples, see:

+- [Azure Active Directory server principals](authentication-azure-ad-logins.md)

+- [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true)

+- [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sql)

+ Title: Azure Active Directory server principals

+description: Using Azure Active Directory server principals (logins) in Azure SQL

+# Azure Active Directory server principals

+> [!NOTE]

+> Azure Active Directory (Azure AD) server principals (logins) are currently in public preview for Azure SQL Database. Azure SQL Managed Instance can already utilize Azure AD logins.

+You can now create and utilize Azure AD server principals, which are logins in the virtual master database of a SQL Database. There are several benefits of using Azure AD server principals for SQL Database:

+- Support [Azure SQL Database server roles for permission management](security-server-roles.md).

+- Support multiple Azure AD users with [special roles for SQL Database](/sql/relational-databases/security/authentication-access/database-level-roles#special-roles-for--and-azure-synapse), such as the `loginmanager` and `dbmanager` roles.

+- Functional parity between SQL logins and Azure AD logins.

+- Increase functional improvement support, such as utilizing [Azure AD-only authentication](authentication-azure-ad-only-authentication.md). Azure AD-only authentication allows SQL authentication to be disabled, which includes the SQL server admin, SQL logins and users.

+- Allows Azure AD principals to support geo-replicas. Azure AD principals will be able to connect to the geo-replica of a user database, with a *read-only* permission and *deny* permission to the primary server.

+- Ability to use Azure AD service principal logins with special roles to execute a full automation of user and database creation, as well as maintenance provided by Azure AD applications.

+- Closer functionality between Managed Instance and SQL Database, as Managed Instance already supports Azure AD logins in the master database.

+For more information on Azure AD authentication in Azure SQL, see [Use Azure Active Directory authentication](authentication-aad-overview.md)

+## Permissions

+The following permissions are required to utilize or create Azure AD logins in the virtual master database.

+- Azure AD admin permission or membership in the `loginmanager` server role. The first Azure AD login can only be created by the Azure AD admin.

+- Must be a member of Azure AD within the same directory used for Azure SQL Database

+By default, the standard permission granted to newly created Azure AD login in the `master` database is **VIEW ANY DATABASE**.

+## Azure AD logins syntax

+New syntax for Azure SQL Database to use Azure AD server principals has been introduced with this feature release.

+### Create login syntax

+```syntaxsql

+CREATE LOGIN login_name { FROM EXTERNAL PROVIDER | WITH <option_list> [,..] }  

+<option_list> ::=     

+    PASSWORD = {'password'}  

+    | , SID = sid, ]

+```

+The *login_name* specifies the Azure AD principal, which is an Azure AD user, group, or application.

+For more information, see [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true).

+### Create user syntax

+The below T-SQL syntax is already available in SQL Database, and can be used for creating database-level Azure AD principals mapped to Azure AD logins in the virtual master database.

+To create an Azure AD user from an Azure AD login, use the following syntax. Only the Azure AD admin can execute this command in the virtual master database.

+```syntaxsql

+CREATE USER user_name FROM LOGIN login_name

+```

+For more information, see [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sql).

+### Disable or enable a login using ALTER LOGIN syntax

+The [ALTER LOGIN (Transact-SQL)](/sql/t-sql/statements/alter-login-transact-sql?view=azuresqldb-current&preserve-view=true) DDL syntax can be used to enable or disable an Azure AD login in Azure SQL Database.

+```syntaxsql

+ALTER LOGIN login_name DISABLE

+```

+The Azure AD principal `login_name` won't be able to log into any user database in the SQL Database logical server where an Azure AD user principal, `user_name` mapped to login `login_name` was created.

+> [!NOTE]

+> - `ALTER LOGIN login_name DISABLE` is not supported for contained users.

+> - `ALTER LOGIN login_name DISABLE` is not supported for Azure AD groups.

+> - An individual disabled login cannot belong to a user who is part of a login group created in the master database (for example, an Azure AD admin group).

+> - For the `DISABLE` or `ENABLE` changes to take immediate effect, the authentication cache and the **TokenAndPermUserStore** cache must be cleared using the T-SQL commands.

+>

+> ```sql

+> DBCC FLUSHAUTHCACHE

+> DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS

+> ```

+## Roles for Azure AD principals

+[Special roles for SQL Database](/sql/relational-databases/security/authentication-access/database-level-roles#special-roles-for--and-azure-synapse) can be assigned to *users* in the virtual master database for Azure AD principals, including **dbmanager** and **loginmanager**.

+[Azure SQL Database server roles](security-server-roles.md) can be assigned to *logins* in the virtual master database.

+For a tutorial on how to grant these roles, see [Tutorial: Create and utilize Azure Active Directory server logins](authentication-azure-ad-logins-tutorial.md).

+## Limitations and remarks

+- The SQL server admin canΓÇÖt create Azure AD logins or users in any databases.

+- Changing a database ownership to an Azure AD group as database owner isn't supported.

+ - `ALTER AUTHORIZATION ON database::<mydb> TO [my_aad_group]` fails with an error message:

+ ```output

+ Msg 33181, Level 16, State 1, Line 4

+ The new owner cannot be Azure Active Directory group.

+ ```

+ - Changing a database ownership to an individual user is supported.

+- A SQL admin or SQL user canΓÇÖt execute the following Azure AD operations:

+ - `CREATE LOGIN [bob@contoso.com] FROM EXTERNAL PROVIDER`

+ - `CREATE USER [bob@contoso.com] FROM EXTERNAL PROVIDER`

+ - `EXECUTE AS USER [bob@contoso.com]`

+ - `ALTER AUTHORIZATION ON securable::name TO [bob@contoso.com]`

+- Impersonation of Azure AD server-level principals (logins) isn't supported:

+ - [EXECUTE AS Clause (Transact-SQL)](/sql/t-sql/statements/execute-as-clause-transact-sql)

+ - [EXECUTE AS (Transact-SQL)](/sql/t-sql/statements/execute-as-transact-sql)

+ - Impersonation of Azure AD database-level principals (users) at a user database-level is still supported.

+- Azure AD logins overlapping with Azure AD administrator aren't supported. Azure AD admin takes precedence over any login. If an Azure AD account already has access to the server as an Azure AD admin, either directly or as a member of the admin group, the login created for this user won't have any effect. The login creation isn't blocked through T-SQL. After the account authenticates to the server, the login will have the effective permissions of an Azure AD admin, and not of a newly created login.

+- Changing permissions on specific Azure AD login object isn't supported:

+ - `GRANT <PERMISSION> ON LOGIN :: <Azure AD account> TO <Any other login> `

+- When permissions are altered for an Azure AD login with existing open connections to an Azure SQL Database, permissions aren't effective until the user reconnects. Also [flush the authentication cache and the TokenAndPermUserStore cache](#disable-or-enable-a-login-using-alter-login-syntax). This applies to server role membership change using the [ALTER SERVER ROLE](/sql/t-sql/statements/alter-server-role-transact-sql) statement.

+- Setting an Azure AD login mapped to an Azure AD group as the database owner isn't supported.

+- [Azure SQL Database server roles](security-server-roles.md) aren't supported for Azure AD groups.

+## Next steps

+> [!div class="nextstepaction"]

+> [Tutorial: Create and utilize Azure Active Directory server logins](authentication-azure-ad-logins-tutorial.md)

+In our examples, we're enabling Azure AD-only authentication during server or managed instance creation, with a system assigned server admin and password. This will prevent server admin access when Azure AD-only authentication is enabled, and only allows the Azure AD admin to access the resource. It's optional to add parameters to the APIs to include your own server admin and password during server creation. However, the password canΓÇÖt be reset until you disable Azure AD-only authentication. An example of how to use these optional parameters to specify the server admin login name is presented in the [PowerShell](?tabs=azure-powershell#azure-sql-database) tab on this page.

+Here's an example of specifying the server admin name (instead of letting the server admin name being automatically created) at the time of logical server creation. As mentioned earlier, this login isn't usable when Azure AD-only authentication is enabled.

+1. Once you're done with configuring your settings, select **Review + create** to proceed. Select **Create** to start provisioning the managed instance.

+| Method | Instructions |

+|--|-|

+| REST API | [Pricings API](/rest/api/securitycenter/pricings) |

+| Azure CLI | [az security pricing](/cli/azure/security/pricing) |

+| PowerShell | [Set-AzSecurityPricing](/powershell/module/az.security/set-azsecuritypricing) |

+Azure SQL Database currently provides three fixed server roles. The permissions that are granted to the fixed server roles cannot be changed and these roles can't have other fixed roles as members. You can add server-level logins as members to server-level roles.

+```

+### D. Check server-level roles for Azure AD logins

+Run this command in the virtual master database to see all Azure AD logins that are part of server-level roles in SQL Database. For more information on Azure AD server logins, see [Azure Active Directory server principals](authentication-azure-ad-logins.md).

+```sql

+SELECT roles.principal_id AS RolePID,roles.name AS RolePName,

+ server_role_members.member_principal_id AS MemberPID, members.name AS MemberPName

+ FROM sys.server_role_members AS server_role_members

+ INNER JOIN sys.server_principals AS roles

+ ON server_role_members.role_principal_id = roles.principal_id

+ INNER JOIN sys.server_principals AS members

+ ON server_role_members.member_principal_id = members.principal_id;

+```

+### E. Check the virtual master database roles for specific logins

+Run this command in the virtual master database to check with roles `bob` has, or change the value to match your principal.

+```sql

+SELECT DR1.name AS DbRoleName, isnull (DR2.name, 'No members') AS DbUserName

+ FROM sys.database_role_members AS DbRMem RIGHT OUTER JOIN sys.database_principals AS DR1

+ ON DbRMem.role_principal_id = DR1.principal_id LEFT OUTER JOIN sys.database_principals AS DR2

+ ON DbRMem.member_principal_id = DR2.principal_id

+ WHERE DR1.type = 'R' and DR2.name like 'bob%'

+```

+## Failover group status

+Auto-failover group reports its status describing the current state of the data replication:

+- Seeding - [Initial seeding](auto-failover-group-sql-mi.md#initial-seeding) is taking place after creation of the failover group, until all user databases are initialized on the secondary instance. Failover process cannot be initiated while auto-failover group is in the Seeding status, since user databases are not copied to secondary instance yet.

+- Synchronizing - the usual status of auto-failover group. It means that data changes on the primary instance are being replicated asynchronously to the secondary instance. This status doesn't guarantee that the data is fully synchronized at every moment. There may be data changes from primary still to be replicated to the secondary due to asynchronous nature of the replication process between instances in the auto-failover group. Both automatic and manual failovers can be initiated while the auto-failover group is in the Seeding status.

+- Failover in progress - this status indicates that either automatically or manually initiated failover process is in progress. No changes to the failover group or additional failovers can be initiated while the auto-failover group is in this status.

+For troubleshooting Azure App Service access via virtual network, see [Troubleshooting virtual networks and applications](../../app-service/overview-vnet-integration.md#troubleshooting).

+ Title: Fail over database with link feature with T-SQL and PowerShell scripts

+description: This guide teaches you how to use the SQL Managed Instance link with scripts to fail over database from SQL Server to Azure SQL Managed Instance.

+ms.devlang:

+# Failover (migrate) database with Azure SQL Managed Instance link feature with T-SQL and PowerShell scripts

+This article teaches you to use T-SQL and PowerShell scripts for [Managed Instance link feature](link-feature.md) to fail over (migrate) your database from SQL Server to Azure SQL Managed Instance.

+> [!NOTE]

+> The link feature for Azure SQL Managed Instance is currently in preview.

+> [!NOTE]

+> Configuration on Azure side is done with PowerShell that calls SQL Managed Instance REST API. Support for Azure PowerShell and CLI will be released in the upcomming weeks. At that point this article will be updated with the simplified PowerShell scripts.

+> [!TIP]

+> SQL Managed Instance link database failover can be set up with [SSMS wizard](managed-instance-link-use-ssms-to-failover-database.md).

+Database failover from SQL Server instance to SQL Managed Instance breaks the link between the two databases. Failover stops replication and leaves both databases in an independent state, ready for individual read-write workloads.

+To start migrating database to the SQL Managed Instance, first stop the application workload to the SQL Server during your maintenance hours. This is required to enable SQL Managed Instance to catchup with the database replication and make migration to Azure without any data loss.

+While database is a part of Always On Availability Group, it isn't possible to set it to read-only mode. You'll need to ensure that your application(s) aren't committing transactions to SQL Server.

+## Switch the replication mode from asynchronous to synchronous

+The replication between SQL Server and SQL Managed Instance is asynchronous by default. Before you perform database migration to Azure, the link needs to be switched to synchronous mode. Synchronous replication across distances might slow down transactions on the primary SQL Server.

+Switching from async to sync mode requires replication mode change on SQL Managed Instance and SQL Server.

+## Switch replication mode on Managed Instance

+Use the following PowerShell script to call REST API that changes the replication mode from asynchronous to synchronous on SQL Managed Instance. We suggest you execute the REST API call using Azure Cloud Shell in Azure portal.

+Replace `<YourSubscriptionID>` with your subscription ID and replace `<ManagedInstanceName>` with the name of your managed instance. Replace `<DAGName>` with the name of Distributed Availability Group link for which youΓÇÖd like to get the status.

+```powershell

+# ====================================================================================

+# POWERSHELL SCRIPT TO SWITCH REPLICATION MODE SYNC-ASYNC ON MANAGED INSTANCE

+# USER CONFIGURABLE VALUES

+# (C) 2021-2022 SQL Managed Instance product group

+# ====================================================================================

+# Enter your Azure Subscription ID

+$SubscriptionID = "<SubscriptionID>"

+# Enter your Managed Instance name ΓÇô example "sqlmi1"

+$ManagedInstanceName = "<ManagedInstanceName>"

+# Enter the Distributed Availability Group name

+$DAGName = "<DAGName>"

+# ====================================================================================

+# INVOKING THE API CALL -- THIS PART IS NOT USER CONFIGURABLE

+# ====================================================================================

+# Log in and select subscription if needed

+if ((Get-AzContext ) -eq $null)

+{

+ echo "Logging to Azure subscription"

+ Login-AzAccount

+}

+Select-AzSubscription -SubscriptionName $SubscriptionID

+# Build URI for the API call

+#

+$miRG = (Get-AzSqlInstance -InstanceName $ManagedInstanceName).ResourceGroupName

+$uriFull = "https://management.azure.com/subscriptions/" + $SubscriptionID + "/resourceGroups/" + $miRG+ "/providers/Microsoft.Sql/managedInstances/" + $ManagedInstanceName + "/distributedAvailabilityGroups/" + $DAGName + "?api-version=2021-05-01-preview"

+echo $uriFull

+# Build API request body

+#

+$bodyFull = @"

+{

+ "properties":{

+ "ReplicationMode":"sync"

+ }

+}"@

+echo $bodyFull

+# Get auth token and build the header

+#

+$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile

+$currentAzureContext = Get-AzContext

+$profileClient = New-Object Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient($azProfile)

+$token = $profileClient.AcquireAccessToken($currentAzureContext.Tenant.TenantId)

+$authToken = $token.AccessToken

+$headers = @{}

+$headers.Add("Authorization", "Bearer "+"$authToken")

+# Invoke API call

+#

+echo "Invoking API call switch Async-Sync replication mode on Managed Instance"

+Invoke-WebRequest -Method PATCH -Headers $headers -Uri $uriFull -ContentType "application/json" -Body $bodyFull

+```

+## Switch replication mode on SQL Server

+Use the following T-SQL script to change the replication mode of Distributed Availability Group on SQL Server from async to sync. Replace `<DAGName>` with the name of Distributed Availability Group, and replace `<AGName>` with the name of Availability Group created on SQL Server. In addition, replace `<ManagedInstanceName>` with the name of your SQL Managed Instance.

+With this step, the migration of the database from SQL Server to SQL Managed Instance is completed.

+```sql

+-- Sets the Distributed Availability Group to synchronous commit.

+-- ManagedInstanceName example 'sqlmi1'

+USE master

+GO

+ALTER AVAILABILITY GROUP [<DAGName>]

+MODIFY

+AVAILABILITY GROUP ON

+ '<AGName>' WITH

+ (AVAILABILITY_MODE = SYNCHRONOUS_COMMIT),

+ '<ManagedInstanceName>' WITH

+ (AVAILABILITY_MODE = SYNCHRONOUS_COMMIT);

+```

+To validate change of the link replication, execute the following DMV, and expected results are shown below. They're indicating SYNCHRONOUS_COMIT state.

+```sql

+-- Verifies the state of the distributed availability group

+SELECT

+ ag.name, ag.is_distributed, ar.replica_server_name,

+ ar.availability_mode_desc, ars.connected_state_desc, ars.role_desc,

+ ars.operational_state_desc, ars.synchronization_health_desc

+FROM

+ sys.availability_groups ag

+ join sys.availability_replicas ar

+ on ag.group_id=ar.group_id

+ left join sys.dm_hadr_availability_replica_states ars

+ on ars.replica_id=ar.replica_id

+WHERE

+ ag.is_distributed=1

+```

+With both SQL Managed Instance, and SQL Server being switched to Sync mode, the replication between the two entities is now synchronous. If you require to reverse this state, follow the same steps and set async state for both SQL Server and SQL Managed Instance.

+## Check LSN values on both SQL Server and Managed Instance

+To complete the migration, we need to ensure that the replication has completed. For this, you need to ensure that LSNs (Log Sequence Numbers) indicating the log records written for both SQL Server and SQL Managed Instance are the same. Initially, it's expected that SQL Server LSN will be higher than LSN number on SQL Managed Instance. The difference is caused by the fact that SQL Managed Instance might be lagging somewhat behind the primary SQL Server due to network latency. After some time, LSNs on SQL Managed Instance and SQL Server should match and stop changing, as the workload on SQL Server should be stopped.

+Use the following T-SQL query on SQL Server to read the LSN number of the last recorded transaction log. Replace `<DatabaseName>` with your database name and look for the last hardened LSN number, as shown below.

+```sql

+-- Obtain last hardened LSN for a database on SQL Server.

+SELECT

+ ag.name AS [Replication group],

+ db.name AS [Database name],

+ drs.database_id AS [Database ID],

+ drs.group_id,

+ drs.replica_id,

+ drs.synchronization_state_desc AS [Sync state],

+ drs.end_of_log_lsn AS [End of log LSN],

+ drs.last_hardened_lsn AS [Last hardened LSN]

+FROM

+ sys.dm_hadr_database_replica_states drs

+ inner join sys.databases db on db.database_id = drs.database_id

+ inner join sys.availability_groups ag on drs.group_id = ag.group_id

+WHERE

+ ag.is_distributed = 1 and db.name = '<DatabaseName>'

+```

+Use the following T-SQL query on SQL Managed Instance to read the LSN number of the last hardened LSN number for your database. Replace `<DatabaseName>` with your database name.

+Query shown below will work on General Purpose SQL Managed Instance. For Business Critical Managed Instance, you will need to uncomment `and drs.is_primary_replica = 1` at the end of the script. On Business Critical, this filter will make sure that only primary replica details are read.

+```sql

+-- Obtain LSN for a database on SQL Managed Instance.

+SELECT

+ db.name AS [Database name],

+ drs.database_id AS [Database ID],

+ drs.group_id,

+ drs.replica_id,

+ drs.synchronization_state_desc AS [Sync state],

+ drs.end_of_log_lsn AS [End of log LSN],

+ drs.last_hardened_lsn AS [Last hardened LSN]

+FROM

+ sys.dm_hadr_database_replica_states drs

+ inner join sys.databases db on db.database_id = drs.database_id

+WHERE

+ db.name = '<DatabaseName>'

+ -- for BC add the following as well

+ -- AND drs.is_primary_replica = 1

+```

+Verify once again that your workload is stopped on SQL Server. Check that LSNs on both SQL Server and SQL Managed Instance match, and that they remain matched and unchanged for some time. Stable LSN numbers on both ends indicate that tail log has been replicated to SQL Managed Instance and workload is effectively stopped. Proceed to the next step to initiate database failover and migration to Azure.

+## Initiate database failover and migration to Azure

+SQL Managed Instance link database failover and migration to Azure is accomplished by invoking REST API call. This will close the link and complete the replication on SQL Managed Instance. Replicated database will become read-write on SQL Managed Instance.

+Use the following API to initiate database failover to Azure. Replace `<YourSubscriptionID>` with your actual Azure subscription ID. Replace `<RG>` with the resource group where your SQL Managed Instance is deployed and replace `<ManagedInstanceName>` with the name of our SQL Managed Instance. In addition, replace `<DAGName>` with the name of Distributed Availability Group made on SQL Server.

+```PowerShell

+# ====================================================================================

+# POWERSHELL SCRIPT TO FAILOVER AND MIGRATE DATABASE WITH SQL MANAGED INSTANCE LINK

+# USER CONFIGURABLE VALUES

+# (C) 2021-2022 SQL Managed Instance product group

+# ====================================================================================

+# Enter your Azure Subscription ID

+$SubscriptionID = "<SubscriptionID>"

+# Enter your Managed Instance name ΓÇô example "sqlmi1"

+$ManagedInstanceName = "<ManagedInstanceName>"

+# Enter the Distributed Availability Group link name

+$DAGName = "<DAGName>"

+# ====================================================================================

+# INVOKING THE API CALL -- THIS PART IS NOT USER CONFIGURABLE.

+# ====================================================================================

+# Log in and select subscription if needed

+if ((Get-AzContext ) -eq $null)

+{

+ echo "Logging to Azure subscription"

+ Login-AzAccount

+}

+Select-AzSubscription -SubscriptionName $SubscriptionID

+# Build URI for the API call

+#

+$miRG = (Get-AzSqlInstance -InstanceName $ManagedInstanceName).ResourceGroupName

+$uriFull = "https://management.azure.com/subscriptions/" + $SubscriptionID + "/resourceGroups/" + $miRG+ "/providers/Microsoft.Sql/managedInstances/" + $ManagedInstanceName + "/distributedAvailabilityGroups/" + $DAGName + "?api-version=2021-05-01-preview"

+echo $uriFull

+# Get auth token and build the header

+#

+$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile

+$currentAzureContext = Get-AzContext

+$profileClient = New-Object Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient($azProfile)

+$token = $profileClient.AcquireAccessToken($currentAzureContext.Tenant.TenantId)

+$authToken = $token.AccessToken

+$headers = @{}

+$headers.Add("Authorization", "Bearer "+"$authToken")

+# Invoke API call

+#

+Invoke-WebRequest -Method DELETE -Headers $headers -Uri $uriFull -ContentType "application/json"

+```

+## Cleanup Availability Group and Distributed Availability Group on SQL Server

+After breaking the link and migrating database to Azure SQL Managed Instance, consider cleaning up Availability Group and Distributed Availability Group on SQL Server if they aren't used otherwise.

+Replace `<DAGName>` with the name of the Distributed Availability Group on SQL Server and replace `<AGName>` with Availability Group name on the SQL Server.

+``` sql

+DROP AVAILABILITY GROUP <DAGName>

+GO

+DROP AVAILABILITY GROUP <AGName>

+GO

+```

+With this step, the migration of the database from SQL Server to Managed Instance has been completed.

+## Next steps

+For more information on the link feature, see the following resources:

+- [Managed Instance link ΓÇô connecting SQL Server to Azure reimagined](https://aka.ms/mi-link-techblog).

+- [Prepare for SQL Managed Instance link](./managed-instance-link-preparation.md).

+- [Use SQL Managed Instance link with scripts to replicate database](./managed-instance-link-use-scripts-to-replicate-database.md).

+- [Use SQL Managed Instance link via SSMS to replicate database](./managed-instance-link-use-ssms-to-replicate-database.md).

+- [Use SQL Managed Instance link via SSMS to migrate database](./managed-instance-link-use-ssms-to-failover-database.md).

+ Title: Replicate database with link feature with T-SQL and PowerShell scripts

+description: This guide teaches you how to use the SQL Managed Instance link with scripts to replicate database from SQL Server to Azure SQL Managed Instance.

+ms.devlang:

+# Replicate database with Azure SQL Managed Instance link feature with T-SQL and PowerShell scripts

+This article teaches you to use scripts, T-SQL and PowerShell, to set up [Managed Instance link feature](link-feature.md) to replicate your database from SQL Server to Azure SQL Managed Instance.

+Before configuring replication for your database through the link feature, make sure you've [prepared your environment](managed-instance-link-preparation.md).

+> [!NOTE]

+> The link feature for Azure SQL Managed Instance is currently in preview.

+> [!NOTE]

+> Configuration on Azure side is done with PowerShell that calls SQL Managed Instance REST API. Support for Azure PowerShell and CLI will be released in the upcomming weeks. At that point this article will be updated with the simplified PowerShell scripts.

+> [!TIP]

+> SQL Managed Instance link database replication can be set up with [SSMS wizard](managed-instance-link-use-ssms-to-replicate-database.md).

+## Prerequisites

+To replicate your databases to Azure SQL Managed Instance, you need the following prerequisites:

+- An active Azure subscription. If you don't have one, [create a free account](https://azure.microsoft.com/free/).

+- [SQL Server 2019 Enterprise or Developer edition](https://www.microsoft.com/en-us/evalcenter/evaluate-sql-server-2019), starting with [CU15 (15.0.4198.2)](https://support.microsoft.com/topic/kb5008996-cumulative-update-15-for-sql-server-2019-4b6a8ee9-1c61-482d-914f-36e429901fb6).

+- An instance of Azure SQL Managed Instance. [Get started](instance-create-quickstart.md) if you don't have one.

+- [SQL Server Management Studio (SSMS) v18.11.1 or later](/sql/ssms/download-sql-server-management-studio-ssms).

+- A properly [prepared environment](managed-instance-link-preparation.md).

+## Terminology and naming conventions

+In executing scripts from this user guide, it's important not to mistaken, for example, SQL Server, or Managed Instance name, with their fully qualified domain names.

+The following table is explaining what different names exactly represent, and how to obtain their values.

+| Terminology | Description | How to find out |

+| :-| :- | :- |

+| SQL Server name | Also referred to as a short SQL Server name. For example: **"sqlserver1"**. This isn't a fully qualified domain name. | Execute **ΓÇ£SELECT @@SERVERNAMEΓÇ¥** from T-SQL |

+| SQL Server FQDN | Fully qualified domain name of your SQL Server. For example: **"sqlserver1.domain.com"**. | From your network (DNS) configuration on-prem, or Server name if using Azure VM. |

+| Managed Instance name | Also referred to as a short Managed Instance name. For example: **"managedinstance1"**. | See the name of your Managed Instance in Azure portal. |

+| SQL Managed Instance FQDN | Fully qualified domain name of your SQL Managed Instance name. For example: **"managedinstance1.6d710bcf372b.database.windows.net"**. | See the Host name at SQL Managed Instance overview page in Azure portal. |

+| Resolvable domain name | DNS name that could be resolved to an IP address. For example, executing **"nslookup sqlserver1.domain.com"** should return an IP address, for example 10.0.1.100. | Use nslookup from the command prompt. |

+## Trust between SQL Server and SQL Managed Instance

+This first step in creating SQL Managed Instance link is establishing the trust between the two entities and secure the endpoints used for communication and encryption of data across the network. Distributed Availability Groups technology in SQL Server doesn't have its own database mirroring endpoint, but it rather uses the existing Availability Group database mirroring endpoint. This is why the security and trust between the two entities needs to be configured for the Availability Group database mirroring endpoint.

+Certificates-based trust is the only supported way to secure database mirroring endpoints on SQL Server and SQL Managed Instance. In case you've existing Availability Groups that are using Windows Authentication, certificate based trust needs to be added to the existing mirroring endpoint as a secondary authentication option. This can be done by using ALTER ENDPOINT statement.

+> [!IMPORTANT]

+> Certificates are generated with an expiry date and time, and they need to be rotated before they expire.

+Here's the overview of the process to secure database mirroring endpoints for both SQL Server and SQL Managed Instance:

+- Generate certificate on SQL Server and obtain its public key.

+- Obtain public key of SQL Managed Instance certificate.

+- Exchange the public keys between the SQL Server and SQL Managed Instance.

+The following section discloses steps to complete these actions.

+## Create certificate on SQL Server and import its public key to Managed Instance

+First, create master key on SQL Server and generate authentication certificate.

+

+```sql

+-- Create MASTER KEY encryption password

+-- Keep the password confidential and in a secure place.

+USE MASTER

+CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<strong_password>'

+GO

+-- Create the SQL Server certificate for SQL Managed Instance link

+USE MASTER

+GO

+DECLARE @sqlserver_certificate_name NVARCHAR(MAX) = N'Cert_' + @@servername + N'_endpoint'

+DECLARE @sqlserver_certificate_subject NVARCHAR(MAX) = N'Certificate for ' + @sqlserver_certificate_name

+DECLARE @create_sqlserver_certificate_command NVARCHAR(MAX) = N'CREATE CERTIFICATE [' + @sqlserver_certificate_name + '] WITH SUBJECT = ''' + @sqlserver_certificate_subject + ''', EXPIRY_DATE = ''03/30/2025'''

+EXEC sp_executesql @stmt = @create_sqlserver_certificate_command

+GO

+```

+Then, use the following T-SQL query to verify the certificate has been created.

+

+```sql

+USE MASTER

+GO

+SELECT * FROM sys.certificates

+```

+In the query results you'll find the certificate and will see that it has been encrypted with the master key.

+Now you can get the public key of the generated certificate.

+```sql

+-- Show the public key of the generated SQL Server certificate

+USE MASTER

+GO

+DECLARE @sqlserver_certificate_name NVARCHAR(MAX) = N'Cert_' + @@servername + N'_endpoint'

+DECLARE @PUBLICKEYENC VARBINARY(MAX) = CERTENCODED(CERT_ID(@sqlserver_certificate_name));

+SELECT @PUBLICKEYENC AS PublicKeyEncoded;

+```

+Save the value of PublicKeyEncoded from the output, as it will be needed for the next step.

+Next step should be executed in PowerShell, with installed Az.Sql module, version 3.5.1 or higher, or use Azure Cloud Shell online to run the commands as it's always updated wit the latest module versions.

+

+Execute the following PowerShell script in Azure Cloud Shell (fill out necessary user information, copy, paste into Azure Cloud Shell and execute).

+Replace `<SubscriptionID>` with your Azure Subscription ID. Replace `<ManagedInstanceName>` with the short name of your managed instance. Replace `<PublicKeyEncoded>` below with the public portion of the SQL Server certificate in binary format generated in the previous step. That will be a long string value starting with 0x, that you've obtained from SQL Server.

+

+```powershell

+# ===============================================================================

+# POWERSHELL SCRIPT TO IMPORT SQL SERVER CERTIFICATE TO MANAGED INSTANCE

+# USER CONFIGURABLE VALUES

+# (C) 2021-2022 SQL Managed Instance product group

+# ===============================================================================

+# Enter your Azure Subscription ID

+$SubscriptionID = "<YourSubscriptionID>"

+# Enter your Managed Instance name ΓÇô example "sqlmi1"

+$ManagedInstanceName = "<YourManagedInstanceName>"

+# Insert the cert public key blob you got from the SQL Server

+$PublicKeyEncoded = "<PublicKeyEncoded>"

+# ===============================================================================

+# INVOKING THE API CALL -- REST OF THE SCRIPT IS NOT USER CONFIGURABLE

+# ===============================================================================

+# Log in and select Subscription if needed.

+#

+if ((Get-AzContext ) -eq $null)

+{

+ echo "Logging to Azure subscription"

+ Login-AzAccount

+}

+Select-AzSubscription -SubscriptionName $SubscriptionID

+# Build URI for the API call.

+#

+$miRG = (Get-AzSqlInstance -InstanceName $ManagedInstanceName).ResourceGroupName

+$uriFull = "https://management.azure.com/subscriptions/" + $SubscriptionID + "/resourceGroups/" + $miRG+ "/providers/Microsoft.Sql/managedInstances/" + $ManagedInstanceName + "/hybridCertificate?api-version=2020-11-01-preview"

+echo $uriFull

+# Build API request body.

+#

+$bodyFull = @"

+{

+ "properties":{ "PublicBlob":"$PublicKeyEncoded" }

+}"@

+echo $bodyFull

+# Get auth token and build the HTTP request header.

+#

+$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile

+$currentAzureContext = Get-AzContext

+$profileClient = New-Object Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient($azProfile)

+$token = $profileClient.AcquireAccessToken($currentAzureContext.Tenant.TenantId)

+$authToken = $token.AccessToken

+$headers = @{}

+$headers.Add("Authorization", "Bearer "+"$authToken")

+# Invoke API call

+#

+Invoke-WebRequest -Method POST -Headers $headers -Uri $uriFull -ContentType "application/json" -Body $bodyFull

+```

+The result of this operation will be time stamp of the successful upload of the SQL Server certificate private key to Managed Instance.

+## Get the Managed Instance public certificate public key and import it to SQL Server

+Certificate for securing the endpoint for SQL Managed Instance link is automatically generated. This section describes how to get the SQL Managed Instance certificate public key, and how import is to SQL Server.

+Use SSMS to connect to the SQL Managed Instance and execute stored procedure [sp_get_endpoint_certificate](/sql/relational-databases/system-stored-procedures/sp-get-endpoint-certificate-transact-sql) to get the certificate public key.

+```sql

+-- Execute stored procedure on SQL Managed Instance to get public key of the instance certificate.

+EXEC sp_get_endpoint_certificate @endpoint_type = 4

+```

+Copy the entire public key from Managed Instance starting with ΓÇ£0xΓÇ¥ shown in the previous step and use it in the below query by replacing `<InstanceCertificate>` with the key value. No quotations need to be used.

+> [!IMPORTANT]

+> Name of the certificate must be SQL Managed Instance FQDN.

+```sql

+USE MASTER

+CREATE CERTIFICATE [<SQLManagedInstanceFQDN>]

+FROM BINARY = <InstanceCertificate>

+```

+Finally, verify all created certificates by viewing the following DMV.

+```sql

+SELECT * FROM sys.certificates

+```

+## Mirroring endpoint on SQL Server

+If you donΓÇÖt have existing Availability Group nor mirroring endpoint, the next step is to create a mirroring endpoint on SQL Server and secure it with the certificate. If you do have existing Availability Group or mirroring endpoint, go straight to the next section ΓÇ£Altering existing database mirroring endpointΓÇ¥

+To verify that you don't have an existing database mirroring endpoint created, use the following script.

+```sql

+-- View database mirroring endpoints on SQL Server

+SELECT * FROM sys.database_mirroring_endpoints WHERE type_desc = 'DATABASE_MIRRORING'

+```

+In case that the above query doesn't show there exists a previous database mirroring endpoint, execute the following script to create a new database mirroring endpoint on the port 5022 and secure it with a certificate.

+```sql

+-- Create connection endpoint listener on SQL Server

+USE MASTER

+CREATE ENDPOINT database_mirroring_endpoint

+ STATE=STARTED

+ AS TCP (LISTENER_PORT=5022, LISTENER_IP = ALL)

+ FOR DATABASE_MIRRORING (

+ ROLE=ALL,

+ AUTHENTICATION = CERTIFICATE <SQL_SERVER_CERTIFICATE>,

+ ENCRYPTION = REQUIRED ALGORITHM AES

+ )

+GO

+```

+Validate that the mirroring endpoint was created by executing the following on SQL Server.

+```sql

+-- View database mirroring endpoints on SQL Server

+SELECT

+ name, type_desc, state_desc, role_desc,

+ connection_auth_desc, is_encryption_enabled, encryption_algorithm_desc

+FROM

+ sys.database_mirroring_endpoints

+```

+New mirroring endpoint was created with CERTIFICATE authentication, and AES encryption enabled.

+### Altering existing database mirroring endpoint

+> [!NOTE]

+> Skip this step if you've just created a new mirroring endpoint. Use this step only if using existing Availability Groups with existing database mirroring endpoint.

+In case existing Availability Groups are used for SQL Managed Instance link, or in case there's an existing database mirroring endpoint, first validate it satisfies the following mandatory conditions for SQL Managed Instance Link:

+- Type must be ΓÇ£DATABASE_MIRRORINGΓÇ¥.

+- Connection authentication must be ΓÇ£CERTIFICATEΓÇ¥.

+- Encryption must be enabled.

+- Encryption algorithm must be ΓÇ£AESΓÇ¥.

+Execute the following query to view details for an existing database mirroring endpoint.

+```sql

+-- View database mirroring endpoints on SQL Server

+SELECT

+ name, type_desc, state_desc, role_desc, connection_auth_desc,

+ is_encryption_enabled, encryption_algorithm_desc

+FROM

+ sys.database_mirroring_endpoints

+```

+In case that the output shows that the existing DATABASE_MIRRORING endpoint connection_auth_desc isn't ΓÇ£CERTIFICATEΓÇ¥, or encryption_algorthm_desc isn't ΓÇ£AESΓÇ¥, the **endpoint needs to be altered to meet the requirements**.

+On SQL Server, one database mirroring endpoint is used for both Availability Groups and Distributed Availability Groups. In case your connection_auth_desc is NTLM (Windows authentication) or KERBEROS, and you need Windows authentication for an existing Availability Groups, it's possible to alter the endpoint to use multiple authentication methods by switching the auth option to NEGOTIATE CERTIFICATE. This will allow the existing AG to use Windows authentication, while using certificate authentication for SQL Managed Instance. See details of possible options at documentation page for [sys.database_mirroring_endpoints](/sql/relational-databases/system-catalog-views/sys-database-mirroring-endpoints-transact-sql).

+Similarly, if encryption doesn't include AES and you need RC4 encryption, it's possible to alter the endpoint to use both algorithms. See details of possible options at documentation page for [sys.database_mirroring_endpoints](/sql/relational-databases/system-catalog-views/sys-database-mirroring-endpoints-transact-sql).

+The script below is provided as an example of how to alter your existing database mirroring endpoint. Depending on your existing specific configuration, you perhaps might need to customize it further for your scenario. Replace `<YourExistingEndpointName>` with your existing endpoint name. Replace `<CERTIFICATE-NAME>` with the name of the generated SQL Server certificate. You can also use `SELECT * FROM sys.certificates` to get the name of the created certificate on the SQL Server.

+```sql

+-- Alter the existing database mirroring endpoint to use CERTIFICATE for authentication and AES for encryption

+USE MASTER

+ALTER ENDPOINT <YourExistingEndpointName>

+ STATE=STARTED

+ AS TCP (LISTENER_PORT=5022, LISTENER_IP = ALL)

+ FOR DATABASE_MIRRORING (

+ ROLE=ALL,

+ AUTHENTICATION = WINDOWS NEGOTIATE CERTIFICATE <CERTIFICATE-NAME>,

+ ENCRYPTION = REQUIRED ALGORITHM AES

+ )

+GO

+```

+After running the ALTER endpoint query and setting the dual authentication mode to Windows and Certificate, use again this query to show the database mirroring endpoint details.

+```sql

+-- View database mirroring endpoints on SQL Server

+SELECT

+ name, type_desc, state_desc, role_desc, connection_auth_desc,

+ is_encryption_enabled, encryption_algorithm_desc

+FROM

+ sys.database_mirroring_endpoints

+```

+With this you've successfully modified your database mirroring endpoint for SQL Managed Instance link.

+## Availability Group on SQL Server

+If you don't have existing AG the next step is to create an AG on SQL Server. If you do have existing AG go straight to the next section ΓÇ£Use existing Availability Group (AG) on SQL ServerΓÇ¥. A new AG needs to be created with the following parameters for Managed Instance link:

+- Specify SQL Server name

+- Specify database name

+- Failover mode MANUAL

+- Seeding mode AUTOMATIC

+Use the following script to create a new AG on SQL Server. Replace `<SQLServerName>` with the name of your SQL Server. Find out your SQL Server name with executing the following T-SQL:

+```sql

+SELECT @@SERVERNAME AS SQLServerName

+```

+Replace `<AGName>` with the name of your availability group. For multiple databases you'll need to create multiple Availability Groups. Managed Instance link requires one database per AG. In this respect, consider naming each AG so that its name reflects the corresponding database - for example `AG_<db_name>`. Replace `<DatabaseName>` with the name of database you wish to replicate. Replace `<SQLServerIP>` with SQL ServerΓÇÖs IP address. Alternatively, resolvable SQL Server host machine name can be used, but you need to make sure that the name is resolvable from SQL Managed Instance virtual network.

+```sql

+-- Create primary AG on SQL Server

+USE MASTER

+CREATE AVAILABILITY GROUP [<AGName>]

+WITH (CLUSTER_TYPE = NONE)

+ FOR database [<DatabaseName>]

+ REPLICA ON

+ '<SQLServerName>' WITH

+ (

+ ENDPOINT_URL = 'TCP://<SQLServerIP>:5022',

+ AVAILABILITY_MODE = SYNCHRONOUS_COMMIT,

+ FAILOVER_MODE = MANUAL,

+ SEEDING_MODE = AUTOMATIC

+ );

+GO

+```

+> [!NOTE]

+> One database per single Availability Group is the current product limitation for replication to SQL Managed Instance using the link feature.

+> If you get the Error 1475 you'll have to create a full backup without COPY ONLY option, that will start new backup chain.

+> As the best practice it's highly recommended that collation on SQL Server and SQL Managed Instance is the same. This is because depending on collation settings, AG and DAG names could, or could not be case sensitive. If there's a mismatch with this, there could be issues in ability to successfully connect SQL Server to Managed Instance.

+### Verify AG and distributed AG

+Use the following script to list all available Availability Groups and Distributed Availability Groups on the SQL Server. Availability Group state needs to be connected, and Distributed Availability Group state disconnected at this point. Distributed Availability Group state will move to `connected` only when it has been joined with SQL Managed Instance. This will be explained in one of the next steps.

+```sql

+-- This will show that Availability Group and Distributed Availability Group have been created on SQL Server.

+SELECT

+ name, is_distributed, cluster_type_desc,

+ sequence_number, is_contained

+FROM

+ sys.availability_groups

+```

+Alternatively, in SSMS object explorer, expand the ΓÇ£Always On High AvailabilityΓÇ¥, then ΓÇ£Availability GroupsΓÇ¥ folder to show available Availability Groups and Distributed Availability Groups.

+## Creating SQL Managed Instance link

+The final step of the setup process is to create the SQL Managed Instance link. To accomplish this, a REST API call will be made. Invoking direct API calls will be replaced with PowerShell and CLI clients, which will be delivered in one of our next releases.

+Invoking direct API call to Azure can be accomplished with various API clients. However, for simplicity of the process, execute the below PowerShell script from Azure Cloud Shell.

+Log in to Azure portal and execute the below PowerShell scripts in Azure Cloud Shell. Make the following replacements with the actual values in the script: Replace `<SubscriptionID>` with your Azure Subscription ID. Replace `<ManagedInstanceName>` with the short name of your managed instance. Replace `<AGName>` with the name of Availability Group created on SQL Server. Replace `<DAGName>` with the name of Distributed Availability Group create on SQL Server. Replace `<DatabaseName>` with the database replicated in Availability Group on SQL Server. Replace `<SQLServerAddress>` with the address of the SQL Server. This can be a DNS name, or public IP or even private IP address, as long as the address provided can be resolved from the backend node hosting the SQL Managed Instance.

+

+```powershell

+# =============================================================================

+# POWERSHELL SCRIPT FOR CREATING MANAGED INSTANCE LINK

+# USER CONFIGURABLE VALUES

+# (C) 2021-2022 SQL Managed Instance product group

+# =============================================================================

+# Enter your Azure Subscription ID

+$SubscriptionID = "<SubscriptionID>"

+# Enter your Managed Instance name ΓÇô example "sqlmi1"

+$ManagedInstanceName = "<ManagedInstanceName>"

+# Enter Availability Group name that was created on the SQL Server

+$AGName = "<AGName>"

+# Enter Distributed Availability Group name that was created on SQL Server

+$DAGName = "<DAGName>"

+# Enter database name that was placed in Availability Group for replciation

+$DatabaseName = "<DatabaseName>"

+# Enter SQL Server address

+$ SQLServerAddress = "<SQLServerAddress>"

+# =============================================================================

+# INVOKING THE API CALL -- THIS PART IS NOT USER CONFIGURABLE

+# =============================================================================

+# Log in to subscription if needed

+if ((Get-AzContext ) -eq $null)

+{

+ echo "Logging to Azure subscription"

+ Login-AzAccount

+}

+Select-AzSubscription -SubscriptionName $SubscriptionID

+# --

+# Build URI for the API call

+# --

+echo "Building API URI"

+$miRG = (Get-AzSqlInstance -InstanceName $ManagedInstanceName).ResourceGroupName

+$uriFull = "https://management.azure.com/subscriptions/" + $SubscriptionID + "/resourceGroups/" + $miRG+ "/providers/Microsoft.Sql/managedInstances/" + $ManagedInstanceName + "/distributedAvailabilityGroups/" + $DAGName + "?api-version=2021-05-01-preview"

+echo $uriFull

+# --

+# Build API request body

+# --

+echo "Buildign API request body"

+$bodyFull = @"

+{

+ "properties":{

+ "TargetDatabase":"$DatabaseName",

+ "SourceEndpoint":"TCP://$SQLServerAddress`:5022",

+ "PrimaryAvailabilityGroupName":"$AGName",

+ "SecondaryAvailabilityGroupName":"$ManagedInstanceName",

+ }

+}

+"@

+echo $bodyFull

+# --

+# Get auth token and build the header

+# --

+$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile

+$currentAzureContext = Get-AzContext

+$profileClient = New-Object Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient($azProfile)

+$token = $profileClient.AcquireAccessToken($currentAzureContext.Tenant.TenantId)

+$authToken = $token.AccessToken

+$headers = @{}

+$headers.Add("Authorization", "Bearer "+"$authToken")

+# --

+# Invoke API call

+# --

+echo "Invoking API call to have Managed Instance join DAG on SQL Server"

+$response = Invoke-WebRequest -Method PUT -Headers $headers -Uri $uriFull -ContentType "application/json" -Body $bodyFull

+echo $response

+```

+The result of this operation will be the time stamp of the successful execution of request for Managed Instance link creation.

+## Verifying created SQL Managed Instance link

+To verify that connection has been made between SQL Managed Instance and SQL Server, execute the following query on SQL Server. Have in mind that connection will not be instantaneous upon executing the API call. It can take up to a minute for the DMV to start showing a successful connection. Keep refreshing the DMV until connection is shown as CONNECTED for SQL Managed Instance replica.

+```sql

+SELECT

+ r.replica_server_name AS [Replica],

+ r.endpoint_url AS [Endpoint],

+ rs.connected_state_desc AS [Connected state],

+ rs.last_connect_error_description AS [Last connection error],

+ rs.last_connect_error_number AS [Last connection error No],

+ rs.last_connect_error_timestamp AS [Last error timestamp]

+FROM

+ sys.dm_hadr_availability_replica_states rs

+ JOIN sys.availability_replicas r

+ ON rs.replica_id = r.replica_id

+```

+In addition, once the connection is established, Managed Instance Databases view in SSMS will initially show replicated database as “Restoring…”. This is because the initial seeding is in progress moving the full backup of the database, which is followed by the catchup replication. Once the seeding process is done, the database will no longer be in “Restoring…” state. For small databases, seeding might finish quickly so you might not see the initial “Restoring…” state in SSMS.

+> [!IMPORTANT]

+> The link will not work unless network connectivity exists between SQL Server and Managed Instance. To troubleshoot the network connectivity following steps described in [test bidirectional network connectivity](managed-instance-link-preparation.md#test-bidirectional-network-connectivity).

+> [!IMPORTANT]

+> Make regular backups of the log file on SQL Server. If the log space used reaches 100%, the replication to SQL Managed Instance will stop until this space use is reduced. It is highly recommended that you automate log backups through setting up a daily job. For more details on how to do this see [Backup log files on SQL Server](link-feature-best-practices.md#take-log-backups-regularly).

+## Next steps

+For more information on the link feature, see the following:

+- [Managed Instance link ΓÇô connecting SQL Server to Azure reimagined](https://aka.ms/mi-link-techblog).

+- [Prepare for SQL Managed Instance link](./managed-instance-link-preparation.md).

+- [Use SQL Managed Instance link with scripts to migrate database](./managed-instance-link-use-scripts-to-failover-database.md).

+- [Use SQL Managed Instance link via SSMS to replicate database](./managed-instance-link-use-ssms-to-replicate-database.md).

+- [Use SQL Managed Instance link via SSMS to migrate database](./managed-instance-link-use-ssms-to-failover-database.md).

+| **Simplification of availability group deployment to a SQL Server VM through the Azure CLI** | It's now easier than ever to deploy an availability group to a SQL Server VM in Azure. You can use the [Azure CLI](/cli/azure/sql/vm?view=azure-cli-2018-03-01-hybrid&preserve-view=true) to create the Windows failover cluster, internal load balancer, and availability group listeners, all from the command line. For more information, see [Use the Azure CLI to configure an Always On availability group for SQL Server on an Azure VM](./

+MicrosoftWindowsServer | WindowsServer | Windows Server 2019 Datacenter gen2(2019-Datacenter- gensecond)

+MicrosoftWindowsServer | WindowsServer | Windows Server 2022 Datacenter - Gen 2(2022-datacenter-g2)

+MicrosoftWindowsServer | WindowsServer | Windows Server 2022 Datacenter(2022-datacenter)

+MicrosoftWindowsServer | WindowsServer | Windows Server 2022 Datacenter: Azure Edition - Gen 2 (2022-datacenter-azure-edition)

+MicrosoftWindowsServer | WindowsServer | [smalldisk] Windows Server 2022 Datacenter: Azure Edition - Gen 2(2022-datacenter-azure-edition-smalldisk)

+MicrosoftWindowsServer | WindowsServer | Windows Server 2022 Datacenter: Azure Edition Core- Gen 2 (2022-datacenter-azure-edition-core)

+MicrosoftWindowsServer | WindowsServer | [smalldisk] Windows Server 2022 Datacenter: Azure Edition Core-Gen 2 (2022-datacenter-azure-edition-core-smalldisk)

+MicrosoftWindowsServer | WindowsServer | [smalldisk] Windows Server 2022 Datacenter-Gen 2 (2022-datacenter-smalldisk-g2)

+MicrosoftWindowsServer | WindowsServer | [smalldisk] Windows Server 2022 Datacenter-Gen 1 (2022-datacenter-smalldisk)

+MicrosoftWindowsServer | WindowsServer | Windows Server 2022 Datacenter Server Core -Gen 2 (2022-datacenter-core-g2)

+MicrosoftWindowsServer | WindowsServer | Windows Server 2022 Datacenter Server Core -Gen 1 (2022-datacenter-core)

+MicrosoftWindowsServer | WindowsServer | [smalldisk]Windows Server 2022 Datacenter Server Core -Gen 2 (2022-datacenter-core-smalldisk-g2)

+MicrosoftWindowsServer | WindowsServer | [smalldisk]Windows Server 2022 Datacenter Server Core -Gen 1(2022-datacenter-core-smalldisk)

+Canonical | UbuntuServer | 20.04-LTS

+ - **TDE - enabled database backup is supported**. To restore a TDE-encrypted database to another SQL Server, you need to first [restore the certificate to the destination server](/sql/relational-databases/security/encryption/move-a-tde-protected-database-to-another-sql-server). The backup compression for TDE-enabled databases for SQL Server 2016 and newer versions is available, but at lower transfer size as explained [here](https://techcommunity.microsoft.com/t5/sql-server/backup-compression-for-tde-enabled-databases-important-fixes-in/ba-p/385593).

+You can use the [Connection steps](#steps) in the section below to connect to your VM. You can also use any of the following articles to connect to a VM. Some connection types require the Bastion [Standard SKU](configuration-settings.md#skus).

+### <a name="audio"></a>To enable audio output

+You can use the [Connection steps](#steps) in the section below to connect to your VM. You can also use any of the following articles to connect to a VM. Some connection types require the Bastion [Standard SKU](configuration-settings.md#skus).

+### <a name="audio"></a>To enable audio output

+> [!NOTE]

+> The use of Azure Bastion with Azure Private DNS Zones is not supported at this time. Before you begin, please make sure that the virtual network where you plan to deploy your Bastion resource is not linked to a private DNS zone.

+>

+### <a name="audio"></a>To enable audio output

+In this quickstart, you deployed Bastion to your virtual network, and then connected to a virtual machine securely via Bastion. Next, you can continue with the following steps if you want to copy and paste to your VM.

+> [Copy and paste to a Windows VM](bastion-vm-copy-paste.md)

+## <a name="connect"></a>Connect to a VM

+You can use the [Connection steps](#steps) in the section below to connect to your VM. You can also use any of the following articles to connect to a VM. Some connection types require the Bastion [Standard SKU](configuration-settings.md#skus).

+### <a name="steps"></a>Connection steps

+### <a name="audio"></a>To enable audio output

+## <a name="ip"></a>Remove VM public IP address

+ Title: Troubleshoot the Anomaly Detector multivariate API

+description: Learn how to remediate common error codes when you use the Azure Anomaly Detector multivariate API.

+# Troubleshoot the multivariate API

+This article provides guidance on how to troubleshoot and remediate common error messages when you use the Azure Cognitive Services Anomaly Detector multivariate API.

+The following tables list multivariate error codes.

+### Common errors

+| Error code | HTTP error code | Error message | Comment |

+| `SubscriptionNotInHeaders` | 400 | apim-subscription-id is not found in headers. | Add your APIM subscription ID in the header. An example header is `{"apim-subscription-id": <Your Subscription ID>}`. |

+| `FileNotExist` | 400 | File \<source> does not exist. | Check the validity of your blob shared access signature. Make sure that it hasn't expired. |

+| `InvalidBlobURL` | 400 | | Your blob shared access signature isn't a valid shared access signature. |

+| `StorageWriteError` | 403 | | This error is possibly caused by permission issues. Our service isn't allowed to write the data to the blob encrypted by a customer-managed key. Either remove the customer-managed key or grant access to our service again. For more information, see [Configure customer-managed keys with Azure Key Vault for Cognitive Services](../../encryption/cognitive-services-encryption-keys-portal.md). |

+| `UnexpectedError` | 500 | | Contact us with detailed error information. You could take the support options from [Azure Cognitive Services support and help options](../../cognitive-services-support-options.md?context=%2fazure%2fcognitive-services%2fanomaly-detector%2fcontext%2fcontext) or email us at [AnomalyDetector@microsoft.com](mailto:AnomalyDetector@microsoft.com). |

+### Train a multivariate anomaly detection model

+| Error code | HTTP error code | Error message | Comment |

+| `TooManyModels` | 400 | This subscription has reached the maximum number of models. | Each APIM subscription ID is allowed to have 300 active models. Delete unused models before you train a new model. |

+| `TooManyRunningModels` | 400 | This subscription has reached the maximum number of running models. | Each APIM subscription ID is allowed to train five models concurrently. Train a new model after previous models have completed their training process. |

+| `InvalidJsonFormat` | 400 | Invalid JSON format. | Training request isn't a valid JSON. |

+| `InvalidAlignMode` | 400 | The `'alignMode'` field must be one of the following: `'Inner'` or `'Outer'` . | Check the value of `'alignMode'`, which should be either `'Inner'` or `'Outer'` (case sensitive). |

+| `InvalidFillNAMethod` | 400 | The `'fillNAMethod'` field must be one of the following: `'Previous'`, `'Subsequent'`, `'Linear'`, `'Zero'`, `'Fixed'`, `'NotFill'`. It cannot be `'NotFill'` when `'alignMode'` is `'Outer'`. | Check the value of `'fillNAMethod'`. For more information, see [Best practices for using the Anomaly Detector multivariate API](./best-practices-multivariate.md#optional-parameters-for-training-api). |

+| `RequiredPaddingValue` | 400 | The `'paddingValue'` field is required in the request when `'fillNAMethod'` is `'Fixed'`. | You need to provide a valid padding value when `'fillNAMethod'` is `'Fixed'`. For more information, see [Best practices for using the Anomaly Detector multivariate API](./best-practices-multivariate.md#optional-parameters-for-training-api). |

+| `RequiredSource` | 400 | The `'source'` field is required in the request. | Your training request hasn't specified a value for the `'source'` field. An example is `{"source": <Your Blob SAS>}`. |

+| `RequiredStartTime` | 400 | The `'startTime'` field is required in the request. | Your training request hasn't specified a value for the `'startTime'` field. An example is `{"startTime": "2021-01-01T00:00:00Z"}`. |

+| `InvalidTimestampFormat` | 400 | Invalid timestamp format. The `<timestamp>` format is not a valid format. | The format of timestamp in the request body isn't correct. Try `import pandas as pd; pd.to_datetime(timestamp)` to verify. |

+| `RequiredEndTime` | 400 | The `'endTime'` field is required in the request. | Your training request hasn't specified a value for the `'startTime'` field. An example is `{"endTime": "2021-01-01T00:00:00Z"}`. |

+| `InvalidSlidingWindow` | 400 | The `'slidingWindow'` field must be an integer between 28 and 2880. | The `'slidingWindow'` field must be an integer between 28 and 2880 (inclusive). |

+### Get a multivariate model with a model ID

+| Error code | HTTP error code | Error message | Comment |

+| `ModelNotExist` | 404 | The model does not exist. | The model with corresponding model ID doesn't exist. Check the model ID in the request URL. |

+### List multivariate models

+| Error code | HTTP error code | Error message | Comment |

+|`InvalidRequestParameterError`| 400 | Invalid values for $skip or $top. | Check whether the values for the two parameters are numerical. The values $skip and $top are used to list the models with pagination. Because the API only returns the 10 most recently updated models, you could use $skip and $top to get models updated earlier. |

+### Anomaly detection with a trained model

+| Error code | HTTP error code | Error message | Comment |

+| `ModelNotExist` | 404 | The model does not exist. | The model used for inference doesn't exist. Check the model ID in the request URL. |

+| `ModelFailed` | 400 | Model failed to be trained. | The model isn't successfully trained. Get detailed information by getting the model with model ID. |

+| `ModelNotReady` | 400 | The model is not ready yet. | The model isn't ready yet. Wait for a while until the training process completes. |

+| `InvalidFileSize` | 413 | File \<file> exceeds the file size limit (\<size limit> bytes). | The size of inference data exceeds the upper limit, which is currently 2 GB. Use less data for inference. |

+### Get detection results

+| Error code | HTTP error code | Error message | Comment |

+| `ResultNotExist` | 404 | The result does not exist. | The result per request doesn't exist. Either inference hasn't completed or the result has expired. The expiration time is seven days. |

+### Data processing errors

+The following error codes don't have associated HTTP error codes.

+| Error code | Error message | Comment |

+| `NoVariablesFound` | No variables found. Check that your files are organized as per instruction. | No CSV files could be found from the data source. This error is typically caused by incorrect organization of files. See the sample data for the desired structure. |

+| `RedundantFile` | File \<filename> is redundant. | This error usually happens during inference. The variable wasn't in the training data but appeared in the inference data. |

+| `FileSizeTooLarge` | The size of file \<filename> is too large. | The size of the single CSV file \<filename> exceeds the limit. Train with less data. |

+| `ReadingFileError` | Errors occurred when reading \<filename>. \<error messages> | Failed to read the file \<filename>. For more information, see the \<error messages> or verify with `pd.read_csv(filename)` in a local environment. |

+| `FileColumnsNotExist` | Columns timestamp or value in file \<filename> do not exist. | Each CSV file must have two columns with the names **timestamp** and **value** (case sensitive). |

+| `VariableParseError` | Variable \<variable> parse \<error message> error. | Can't process the \<variable> because of runtime errors. For more information, see the \<error message> or contact us with the \<error message>. |

+| `MergeDataFailed` | Failed to merge data. Check data format. | Data merge failed. This error is possibly because of the wrong data format or the incorrect organization of files. See the sample data for the current file structure. |

+| `ColumnNotFound` | Column \<column> cannot be found in the merged data. | A column is missing after merge. Verify the data. |

+| `NumColumnsMismatch` | Number of columns of merged data does not match the number of variables. | Verify the data. |

+| `TooManyData` | Too many data points. Maximum number is 1000000 per variable. | Reduce the size of input data. |

+| `NoData` | There is no effective data. | There's no data to train/inference after processing. Check the start time and end time. |

+| `DataExceedsLimit`. | The length of data whose timestamp is between `startTime` and `endTime` exceeds limit(\<limit>). | The size of data after processing exceeds the limit. Currently, there's no limit on processed data. |

+| `NotEnoughInput` | Not enough data. The length of data is \<data length>, but the minimum length should be larger than sliding window, which is \<sliding window size>. | The minimum number of data points for inference is the size of the sliding window. Try to provide more data for inference. |

+ Title: Create phonetic pronunciation data

+# Create phonetic pronunciation data

+- [Train your model](how-to-custom-speech-train-model.md)

+| Neural text-to-speech | Converts text to natural-sounding speech by using deep neural network technology, which allows for more natural synthesized speech. | 2.0.0 | Generally available |

+Starting in container version 2.0.0, select customers can run neural-text-to-speech containers in an environment without internet accessibility. For more information, see [Run Cognitive Services containers in disconnected environments](../containers/disconnected-containers.md).

+| [Speech Service API][sp-containers-ntts] | **Neural Text-to-speech** ([image](https://hub.docker.com/_/microsoft-azure-cognitive-services-speechservices-neural-text-to-speech)) | Converts text to natural-sounding speech using deep neural network technology, allowing for more natural synthesized speech. | Generally available. <br> container can also [run in disconnected environments](containers/disconnected-containers.md). |

+Release notes for `v2.0.0`:

+* Support for using containers in [disconnected environments](disconnected-containers.md).

+* Support `ar-bh-lailaneural` and `ar-eg-salmaneural` and `ar-eg-shakirneural` and `ar-sa-hamedneural` and `ar-sa-zariyahneural`.

+* `es-MX-Dalia` model upgrade.

+| `2.0.0-amd64-<locale-and-voice>` | Replace `<locale>` with one of the available locales, listed below. For example `2.0.0-amd64-en-us-arianeural`. |

+| v2.0.0 Locales and voices | Notes |

+| `ar-bh-lailaneural` | Container image with the `ar-BH` locale and `ar-BH-Lailaneural` voice. |

+| `ar-eg-salmaneura` | Container image with the `ar-EG` locale and `ar-eg-Salmaneura` voice. |

+| `ar-eg-shakirneural` | Container image with the `ar-EG` locale and `ar-eg-shakirneural` voice. |

+| `ar-sa-hamedneural` | Container image with the `ar-SA` locale and `ar-sa-Hamedneural` voice. |

+| `ar-sa-zariyahneural` | Container image with the `ar-SA` locale and `ar-sa-Zariyahneural` voice. |

+Release notes for `v1.12.0`:

+**Features**

+* Support `am-et-amehaneural` and `am-et-mekdesneural` and `so-so-muuseneural` and `so-so-ubaxneural`.

+| v1.12.0 Locales and voices | Notes |

+|-|:|

+| `am-et-amehaneural` | Container image with the `am-ET` locale and `am-ET-Amehaneural` voice. |

+| `am-et-mekdesneural` | Container image with the `am-ET` locale and `am-ET-Mekdesneural` voice. |

+| `cs-cz-antoninneural` | Container image with the `cs-CZ` locale and `cs-CZ-Antoninneural` voice. |

+| `cs-cz-vlastaneural` | Container image with the `cs-CZ` locale and `cs-CZ-Vlastaneural` voice. |

+| `de-ch-janneural` | Container image with the `de-CH` locale and `de-CH-Janneural` voice. |

+| `de-ch-lenineural` | Container image with the `de-CH` locale and `de-CH-Lenineural` voice. |

+| `de-de-conradneural` | Container image with the `de-DE` locale and `de-DE-ConradNeural` voice. |

+| `de-de-katjaneural` | Container image with the `de-DE` locale and `de-DE-KatjaNeural` voice. |

+| `en-au-natashaneural` | Container image with the `en-AU` locale and `en-AU-NatashaNeural` voice. |

+| `en-au-williamneural` | Container image with the `en-AU` locale and `en-AU-WilliamNeural` voice. |

+| `en-ca-claraneural` | Container image with the `en-CA` locale and `en-CA-ClaraNeural` voice. |

+| `en-ca-liamneural` | Container image with the `en-CA` locale and `en-CA-LiamNeural` voice. |

+| `en-gb-libbyneural` | Container image with the `en-GB` locale and `en-GB-LibbyNeural` voice. |

+| `en-gb-ryanneural` | Container image with the `en-GB` locale and `en-GB-RyanNeural` voice. |

+| `en-gb-sonianeural` | Container image with the `en-GB` locale and `en-GB-SoniaNeural` voice. |

+| `en-us-arianeural` | Container image with the `en-US` locale and `en-US-AriaNeural` voice. |

+| `en-us-guyneural` | Container image with the `en-US` locale and `en-US-GuyNeural` voice. |

+| `en-us-jennyneural` | Container image with the `en-US` locale and `en-US-JennyNeural` voice. |

+| `es-es-alvaroneural` | Container image with the `es-ES` locale and `es-ES-AlvaroNeural` voice. |

+| `es-es-elviraneural` | Container image with the `es-ES` locale and `es-ES-ElviraNeural` voice. |

+| `es-mx-dalianeural` | Container image with the `es-MX` locale and `es-MX-DaliaNeural` voice. |

+| `es-mx-jorgeneural` | Container image with the `es-MX` locale and `es-MX-JorgeNeural` voice. |

+| `fr-ca-antoineneural` | Container image with the `fr-CA` locale and `fr-CA-AntoineNeural` voice. |

+| `fr-ca-jeanneural` | Container image with the `fr-CA` locale and `fr-CA-JeanNeural` voice. |

+| `fr-ca-sylvieneural` | Container image with the `fr-CA` locale and `fr-CA-SylvieNeural` voice. |

+| `fr-fr-deniseneural` | Container image with the `fr-FR` locale and `fr-FR-DeniseNeural` voice. |

+| `fr-fr-henrineural` | Container image with the `fr-FR` locale and `fr-FR-HenriNeural` voice. |

+| `hi-in-madhurneural` | Container image with the `hi-IN` locale and `hi-IN-MadhurNeural` voice. |

+| `hi-in-swaraneural` | Container image with the `hi-IN` locale and `hi-IN-Swaraneural` voice. |

+| `it-it-diegoneural` | Container image with the `it-IT` locale and `it-IT-DiegoNeural` voice. |

+| `it-it-elsaneural` | Container image with the `it-IT` locale and `it-IT-ElsaNeural` voice. |

+| `it-it-isabellaneural` | Container image with the `it-IT` locale and `it-IT-IsabellaNeural` voice. |

+| `ja-jp-keitaneural` | Container image with the `ja-JP` locale and `ja-JP-KeitaNeural` voice. |

+| `ja-jp-nanamineural` | Container image with the `ja-JP` locale and `ja-JP-NanamiNeural` voice. |

+| `ko-kr-injoonneural` | Container image with the `ko-KR` locale and `ko-KR-InJoonNeural` voice. |

+| `ko-kr-sunhineural` | Container image with the `ko-KR` locale and `ko-KR-SunHiNeural` voice. |

+| `pt-br-antonioneural` | Container image with the `pt-BR` locale and `pt-BR-AntonioNeural` voice. |

+| `pt-br-franciscaneural` | Container image with the `pt-BR` locale and `pt-BR-FranciscaNeural` voice. |

+| `so-so-muuseneural` | Container image with the `so-SO` locale and `so-SO-Muuseneural` voice. |

+| `so-so-ubaxneural` | Container image with the `so-SO` locale and `so-SO-Ubaxneural` voice. |

+| `tr-tr-ahmetneural` | Container image with the `tr-TR` locale and `tr-TR-AhmetNeural` voice. |

+| `tr-tr-emelneural` | Container image with the `tr-TR` locale and `tr-TR-EmelNeural` voice. |

+| `zh-cn-xiaoxiaoneural` | Container image with the `zh-CN` locale and `zh-CN-XiaoxiaoNeural` voice. |

+| `zh-cn-xiaoyouneural` | Container image with the `zh-CN` locale and `zh-CN-XiaoYouNeural` voice. |

+| `zh-cn-yunyangneural` | Container image with the `zh-CN` locale and `zh-CN-YunYangNeural` voice. |

+| `zh-cn-yunyeneural` | Container image with the `zh-CN` locale and `zh-CN-YunYeNeural` voice. |

+| `zh-cn-xiaochenneural-preview` | Container image with the `zh-CN` locale and `zh-CN-XiaoChenNeural` voice. |

+| `zh-cn-xiaohanneural` | Container image with the `zh-CN` locale and `zh-CN-XiaoHanNeural` voice. |

+| `zh-cn-xiaomoneural` | Container image with the `zh-CN` locale and `zh-CN-XiaoMoNeural` voice. |

+| `zh-cn-xiaoqiuneural-preview` | Container image with the `zh-CN` locale and `zh-CN-XiaoQiuNeural` voice. |

+| `zh-cn-xiaoruineural` | Container image with the `zh-CN` locale and `zh-CN-XiaoRuiNeural` voice. |

+| `zh-cn-xiaoshuangneural-preview` | Container image with the `zh-CN` locale and `zh-CN-XiaoShuangNeural` voice.|

+| `zh-cn-xiaoxuanneural` | Container image with the `zh-CN` locale and `zh-CN-XiaoXuanNeural` voice. |

+| `zh-cn-xiaoyanneural-preview` | Container image with the `zh-CN` locale and `zh-CN-XiaoYanNeural` voice. |

+| `zh-cn-yunxineural` | Container image with the `zh-CN` locale and `zh-CN-YunXiNeural` voice. |

+* [Neural Text to Speech](../speech-service/speech-container-howto.md?tabs=ntts)

+> If you're using the Translator, Neural text-to-speech, or Speech-to-text containers, read the **Additional parameters** section below for information on commands or additional parameters you will need to use.

+#### Speech-to-text and Neural text-to-speech containers

+The [speech-to-text](../speech-service/speech-container-howto.md?tabs=stt) and [neural text-to-speech](../speech-service/speech-container-howto.md?tabs=ntts) containers provide a default directory for writing the license file and billing log at runtime. When you're mounting these directories to the container with the `docker run -v` command, make sure the local machine directory is set ownership to `user:group nonroot:nonroot` before running the container.

+| Feature | Supported versions | Latest Generally Available version | Latest preview version |

+| Sentiment Analysis and opinion mining | `2019-10-01`, `2020-04-01`, `2021-10-01` | `2021-10-01` | |

+<!--### Using a preview model version

+-->

+* Model 2021-10-01 is Generally Available (GA) for [Sentiment Analysis and Opinion Mining](sentiment-opinion-mining/overview.md), featuring enhanced modeling for emojis and better accuracy across all supported languages.

+* [Question Answering](question-answering/overview.md): Active learning v2 incorporates a better clustering logic providing improved accuracy of suggestions. It considers user actions when suggestions are accepted or rejected to avoid duplicate suggestions, and improve query suggestions.

+## Chat storage

+During a Teams meeting, all chat messages sent by Teams users or Communication Services users are stored in the geographic region associated with the Microsoft 365 organization hosting the meeting. For more information, review the article [Location of data in Microsoft Teams](/microsoftteams/location-of-data-in-teams). For each Communication Services user in the meetings, there is also a copy of the most recently sent message that is stored in the geographic region associated with the Communication Services resource used to develop the Communication Services application. For more information, review the article [Region availability and data residency](/azure/communication-services/concepts/privacy).

+If the hosting Microsoft 365 organization has defined a retention policy that deletes chat messages for any of the Teams users in the meeting, then all copies of the most recently sent message that have been stored for Communication Services users will also be deleted in accordance with the policy. If there is not a retention policy defined, then the copies of the most recently sent message for all Communication Services users will be deleted after 30 days. For more information about Teams retention policies, review the article [Learn about retention for Microsoft Teams](/microsoft-365/compliance/retention-policies-teams).

+> If you have newer JAVA installed in addition to JDK8: Set the %JAVA_HOME% variable in the local command prompt to target JDK8. This will only change Java version for the current session and leave global machine settings intact.

+description: This tutorial shows how to load sample user data to a Cassandra API table in Azure Cosmos DB by using a Java application.

+Azure Cosmos DB automatically takes a full backup of your data for every 4 hours and at any point of time, the latest two backups are stored. This configuration is the default option and itΓÇÖs offered without any extra cost. You can change the default backup interval and retention period during the Azure Cosmos account creation or after the account is created. The backup configuration is set at the Azure Cosmos account level and you need to configure it on each account. After you configure the backup options for an account, itΓÇÖs applied to all the containers within that account. You can modify these settings using the Azure portal as described below, or via [PowerShell](configure-periodic-backup-restore.md#modify-backup-options-using-azure-powershell) or the [Azure CLI](configure-periodic-backup-restore.md#modify-backup-options-using-azure-cli).

+Azure Cosmos DB does not natively support migrating account metadata from one region to another. To migrate both the account metadata and customer data from one region to another, you must create a new account in the desired region and then copy the data manually.

+> [!IMPORTANT]

+> It is not necessary to migrate the account metadata if the data is stored or moved to a different region. The region in which the account metadata resides has no impact on the performance, security or any other operational aspects of your Azure Cosmos DB account.

+`FeedOptions.PopulateQueryMetrics` is enabled by default with the results being present in the `FeedResponse.Diagnostics` property of the response.

+Where the v2 SDK used `DocumentClientException` to signal errors during operations, the v3 SDK uses `CosmosException`, which exposes the `StatusCode`, `Diagnostics`, and other response-related information. All the complete information is serialized when `ToString()` is used:

+catch (CosmosException ex)

+Open the Windows command prompt or a Terminal window from your local computer. You will run all the commands in the next sections from the command prompt or terminal. Run the following dotnet new command to create a new app with the name *bulk-import-demo*.

+ dotnet new console -n bulk-import-demo

+* If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

+> [!NOTE]

+> To perform a transfer, the destination account must be a paid account with a valid form of payment. For example, if the destination is an Azure free account, you can upgrade it to a pay-as-you-go Azure plan under a Microsoft Customer Agreement. Then you can make the transfer.

+> For data types that map to the Decimal interim type, currently Copy activity supports precision up to 28. If you have data that requires precision larger than 28, consider converting to a string in a SQL query.

+>

+> When copying data from SQL Server using Azure Data Factory, the bit data type is mapped to the Boolean interim data type. If you have data that need to be kept as the bit data type, use queries with [T-SQL CAST or CONVERT](/sql/t-sql/functions/cast-and-convert-transact-sql?view=sql-server-ver15&preserve-view=true).

+### Unable to connect to SFTP due to key exchange algorithms provided by SFTP are not supported in ADF

+- **Symptoms**: You are unable to connect to SFTP via ADF and meet the following error message: `Failed to negotiate key exchange algorithm.`

+- **Cause**: The key exchange algorithms provided by the SFTP server are not supported in ADF. The key exchange algorithms supported by ADF are:

+ - diffie-hellman-group-exchange-sha256

+ - diffie-hellman-group-exchange-sha1

+ - diffie-hellman-group14-sha1

+ - diffie-hellman-group1-sha1

+1. In the local web UI of your device, go to the **Get started** page. On the **Set up a single node device** tile, select **Start**.

+ 

+2. On the **Network** tile, select **Needs setup**.

+|Scale out file server|The device is available as a single node or a two-node cluster. For more information, see [What is clustering on Azure Stack Edge devices? (Preview)](azure-stack-edge-gpu-clustering-overview.md).|

+|Disconnected mode| Deploy, run, manage applications in offline mode. <br> Disconnected mode supports offline upload scenarios. For more information, see Use [Azure Stack Edge in disconnected mode](azure-stack-edge-gpu-disconnected-scenario.md)|

+- **Environment hardening** - Defender for Containers protects your Kubernetes clusters whether they're running on Azure Kubernetes Service, Kubernetes on-prem / IaaS, or Amazon EKS. By continuously assessing clusters, Defender for Containers provides visibility into misconfigurations and guidelines to help mitigate identified threats. Learn more in [Hardening](#hardening).

+## Hardening

+### Continuous monitoring of your Kubernetes clusters - wherever they're hosted

+Defender for Cloud continuously assesses the configurations of your clusters and compares them with the initiatives applied to your subscriptions. When it finds misconfigurations, Defender for Cloud generates security recommendations. Use Defender for Cloud's **recommendations page** to view recommendations and remediate issues. For details of the relevant Defender for Cloud recommendations that might appear for this feature, see the [compute section](recommendations-reference.md#recs-container) of the recommendations reference table.

+For Kubernetes clusters on EKS, you'll need to connect your AWS account to Microsoft Defender for Cloud via the environment settings page as described in [Connect your AWS accounts to Microsoft Defender for Cloud](quickstart-onboard-aws.md). Then ensure you've enabled the CSPM plan.

+When reviewing the outstanding recommendations for your container-related resources, whether in asset inventory or the recommendations page, you can use the resource filter:

+### Kubernetes data plane hardening

+For a bundle of recommendations to protect the workloads of your Kubernetes containers, install the **Azure Policy for Kubernetes**. You can also auto deploy this component as explained in [enable auto provisioning of agents and extensions](enable-data-collection.md#auto-provision-mma). By default, auto provisioning is enabled when you enable Defender for Containers.

+With the add-on on your AKS cluster, every request to the Kubernetes API server will be monitored against the predefined set of best practices before being persisted to the cluster. You can then configure to **enforce** the best practices and mandate them for future workloads.

+For example, you can mandate that privileged containers shouldn't be created, and any future requests to do so will be blocked.

+Learn more in [Kubernetes data plane hardening](kubernetes-workload-protections.md).

+## Vulnerability assessment

+### Scanning images in ACR registries

+Defender for Containers includes an integrated vulnerability scanner for scanning images in Azure Container Registry registries.

+There are four triggers for an image scan:

+- **On push** - Whenever an image is pushed to your registry, Defender for Containers automatically scans that image. To trigger the scan of an image, push it to your repository.

+- **Recently pulled** - Since new vulnerabilities are discovered every day, **Microsoft Defender for Containers** also scans, on a weekly basis, any image that has been pulled within the last 30 days. There's no extra charge for these rescans; as mentioned above, you're billed once per image.

+- **On import** - Azure Container Registry has import tools to bring images to your registry from Docker Hub, Microsoft Container Registry, or another Azure container registry. **Microsoft Defender for container Containers** scans any supported images you import. Learn more in [Import container images to a container registry](../container-registry/container-registry-import-images.md).

+- **Continuous scan**- This trigger has two modes:

+ - A Continuous scan based on an image pull. This scan is performed every seven days after an image was pulled, and only for 30 days after the image was pulled. This mode doesn't require the security profile, or extension.

+ - (Preview) Continuous scan for running images. This scan is performed every seven days for as long as the image runs. This mode runs instead of the above mode when the Defender profile, or extension is running on the cluster.

+This scan typically completes within 2 minutes, but it might take up to 40 minutes. For every vulnerability identified, Defender for Cloud provides actionable recommendations, along with a severity classification, and guidance for how to remediate the issue.

+Defender for Cloud filters, and classifies findings from the scanner. When an image is healthy, Defender for Cloud marks it as such. Defender for Cloud generates security recommendations only for images that have issues to be resolved. By only notifying when there are problems, Defender for Cloud reduces the potential for unwanted informational alerts.

+### View vulnerabilities for running images

+Defender for Containers expands on the registry scanning features by introducing the **preview feature** of run-time visibility of vulnerabilities powered by the Defender profile, or extension.

+> [!NOTE]

+> There's no Defender profile for Windows, it's only available on Linux OS.

+The new recommendation, **Running container images should have vulnerability findings resolved**, only shows vulnerabilities for running images, and relies on the Defender security profile, or extension to discover which images are currently running. This recommendation groups running images that have vulnerabilities, and provides details about the issues discovered, and how to remediate them. The Defender profile, or extension is used to gain visibility into vulnerable containers that are active.

+This recommendation shows running images, and their vulnerabilities based on ACR image. Images that are deployed from a non ACR registry, won't be scanned, and will appear under the Not applicable tab.

+## Run-time protection for Kubernetes nodes and clusters

+Defender for Cloud provides real-time threat protection for your containerized environments and generates alerts for suspicious activities. You can use this information to quickly remediate security issues and improve the security of your containers.

+Threat protection at the cluster level is provided by the Defender profile and analysis of the Kubernetes audit logs. Examples of events at this level include exposed Kubernetes dashboards, creation of high-privileged roles, and the creation of sensitive mounts.

+In addition, our threat detection goes beyond the Kubernetes management layer. Defender for Containers includes **host-level threat detection** with over 60 Kubernetes-aware analytics, AI, and anomaly detections based on your runtime workload. Our global team of security researchers constantly monitor the threat landscape. They add container-specific alerts and vulnerabilities as they're discovered. Together, this solution monitors the growing attack surface of multi-cloud Kubernetes deployments and tracks the [MITRE ATT&CK® matrix for Containers](https://www.microsoft.com/security/blog/2021/04/29/center-for-threat-informed-defense-teams-up-with-microsoft-partners-to-build-the-attck-for-containers-matrix/), a framework that was developed by the [Center for Threat-Informed Defense](https://mitre-engenuity.org/ctid/) in close partnership with Microsoft and others.

+The full list of available alerts can be found in the [Reference table of alerts](alerts-reference.md#alerts-k8scluster).

+> Defender for Containers' support for Arc-enabled Kubernetes clusters (AWS EKS, and GCP GKE) is a preview feature.

+### Does Microsoft Defender for Containers support AKS with virtual machines?

+No. If your cluster is deployed on an Azure Kubernetes Service (AKS) virtual machines, it's not recommended to enable the Microsoft Defender for Containers plan.

+### Do I need to install the Log Analytics VM extension on my AKS nodes for security protection?

+No, AKS is a managed service, and manipulation of the IaaS resources isn't supported. The Log Analytics VM extension is not needed and may result in additional charges.

+ Title: Kubernetes data plane hardening

+description: Learn how to use Microsoft Defender for Cloud's set of Kubernetes data plane hardening security recommendations

+# Protect your Kubernetes data plane hardening

+This page describes how to use Microsoft Defender for Cloud's set of security recommendations dedicated to Kubernetes data plane hardening.

+## Enable Kubernetes data plane hardening

+When you enable Microsoft Defender for Containers, Azure Kubernetes Service clusters, and Azure Arc enabled Kubernetes clusters (Preview) protection are both enabled by default. You can configure your Kubernetes data plane hardening, when you enable Microsoft Defender for Containers.

+You can manually configure the Kubernetes data plane hardening add-on, or extension protection through the Recommendations page. This can be accomplished by remediating the `Azure Policy add-on for Kubernetes should be installed and enabled on your clusters` recommendation, or `Azure policy extension for Kubernetes should be installed and enabled on your clusters`.

+ :::image type="content" source="media/kubernetes-workload-protections/containers-parameter-requires-configuration.png" alt-text="Modifying the parameters for one of the recommendations in the Kubernetes data plane hardening protection bundle.":::

+In this article, you learned how to configure Kubernetes data plane hardening.

+ - **Microsoft Defender for Containers** brings threat detection and advanced defenses to your Amazon EKS clusters. This plan includes Kubernetes threat protection, behavioral analytics, Kubernetes best practices, admission control recommendations and more. You can view the full list of available features in [Defender for Containers feature availability](supported-machines-endpoint-solutions-clouds-containers.md).

+ - **Microsoft Defender for servers** brings threat detection and advanced defenses to your Windows and Linux EC2 instances. This plan includes the integrated license for Microsoft Defender for Endpoint, security baselines and OS level assessments, vulnerability assessment scanning, adaptive application controls (AAC), file integrity monitoring (FIM), and more. You can view the full list of available features in the [feature availability table](supported-machines-endpoint-solutions-clouds-servers.md?tabs=tab/features-multi-cloud).

+1. By default the **Containers** plan is set to **On**. This is necessary to have Defender for Containers protect your AWS EKS clusters. Ensure you have fulfilled the [network requirements](defender-for-containers-enable.md?tabs=defender-for-container-eks#network-requirements) for the Defender for Containers plan.

+ - (Optional) Select **Configure**, to edit the configuration as required. If you choose to disable this configuration, the `Threat detection (control plane)` feature will be disabled. Learn more about the [feature availability](supported-machines-endpoint-solutions-clouds-containers.md).

+1. Make sure the appropriate [Azure resources providers](../azure-arc/servers/prerequisites.md#azure-resource-providers) are registered:

+ - **Microsoft Defender for Containers** - Microsoft Defender for Containers brings threat detection and advanced defenses to your Google's Kubernetes Engine (GKE) Standard clusters. This plan includes Kubernetes threat protection, behavioral analytics, Kubernetes best practices, admission control recommendations and more. You can view the full list of available features in [Defender for Containers feature availability](supported-machines-endpoint-solutions-clouds-containers.md).

+1. (**Containers only**) Ensure you have fulfilled the [network requirements](defender-for-containers-enable.md?tabs=defender-for-container-gcp#network-requirements) for the Defender for Containers plan.

+If you choose to disable all of available configuration options, no agents, or components will be deployed to your clusters. Learn more about the [features availability](supported-machines-endpoint-solutions-clouds-containers.md).

+> Defender for Cloud's auto-deploy tools for deploying the Log Analytics agent works with machines running Azure Arc however this capability is currently in preview . When you've connected your machines using Azure Arc, use the relevant Defender for Cloud recommendation to deploy the agent and benefit from the full range of protections offered by Defender for Cloud:

+Learn more in [Workload protection best-practices using Kubernetes admission control](defender-for-containers-introduction.md#hardening).

+Learn more in [Workload protection best-practices using Kubernetes admission control](defender-for-containers-introduction.md#hardening).

+| Vulnerability Assessment | Registry scan | ACR, Private ACR | GA | Γ£ô (Preview) | Agentless | Defender for Containers | Commercial clouds<br><br> National clouds: Azure Government, Azure China 21Vianet |

+| Vulnerability Assessment | View vulnerabilities for running images | AKS | Preview | X | Defender profile | Defender for Containers | Commercial clouds |

+| Runtime protection| Threat detection (control plane)| AKS | GA | Γ£ô | Agentless | Defender for Containers | Commercial clouds<br><br> National clouds: Azure Government, Azure China 21Vianet |

+| Runtime protection| Threat detection (workload) | AKS | Preview | X | Defender profile | Defender for Containers | Commercial clouds |

+| Discovery and provisioning | Discovery of unprotected clusters | AKS | GA | Γ£ô | Agentless | Free | Commercial clouds<br><br> National clouds: Azure Government, Azure China 21Vianet |

+| Discovery and provisioning | Collection of control plane threat data | AKS | GA | Γ£ô | Agentless | Defender for Containers | Commercial clouds<br><br> National clouds: Azure Government, Azure China 21Vianet |

+| Discovery and provisioning | Auto provisioning of Defender profile | AKS | Preview | X | Agentless | Defender for Containers | Commercial clouds<br><br> National clouds: Azure Government, Azure China 21Vianet |

+| Discovery and provisioning | Auto provisioning of Azure policy add-on | AKS | GA | X | Agentless | Free | Commercial clouds<br><br> National clouds: Azure Government, Azure China 21Vianet |

+| Vulnerability Assessment | Registry scan | - | - | - | - | - |

+| Vulnerability Assessment | View vulnerabilities for running images | - | - | - | - | - |

+| Runtime protection| Threat detection (control plane)| EKS | Preview | Γ£ô | Agentless | Defender for Containers |

+| Runtime protection| Threat detection (workload) | EKS | Preview | X | Defender extension | Defender for Containers |

+| Discovery and provisioning | Discovery of unprotected clusters | EKS | Preview | X | Agentless | Free |

+| Discovery and provisioning | Collection of control plane threat data | EKS | Preview | Γ£ô | Agentless | Defender for Containers |

+| Discovery and provisioning | Auto provisioning of Defender extension | - | - | - | - | - |

+| Discovery and provisioning | Auto provisioning of Azure policy extension | - | - | - | - | - |

+| Vulnerability Assessment | Registry scan | - | - | - | - | - |

+| Vulnerability Assessment | View vulnerabilities for running images | - | - | - | - | - |

+| Runtime protection| Threat detection (control plane)| GKE | Preview | Γ£ô | Agentless | Defender for Containers |

+| Runtime protection| Threat detection (workload) | GKE | Preview | X | Defender extension | Defender for Containers |

+| Discovery and provisioning | Discovery of unprotected clusters | GKE | Preview | X | Agentless | Free |

+| Discovery and provisioning | Collection of control plane threat data | GKE | Preview | Γ£ô | Agentless | Defender for Containers |

+| Discovery and provisioning | Auto provisioning of Defender extension | GKE | Preview | X | Agentless | Defender for Containers |

+| Discovery and provisioning | Auto provisioning of Azure policy extension | GKE | Preview | X | Agentless | Defender for Containers |

+| Vulnerability Assessment | Registry scan | ACR, Private ACR | Preview | Γ£ô (Preview) | Agentless | Defender for Containers |

+| Vulnerability Assessment | View vulnerabilities for running images | Arc enabled K8s clusters | Preview | X | Defender extension | Defender for Containers |

+| Runtime protection| Threat detection (control plane)| Arc enabled K8s clusters | Preview | Γ£ô | Defender extension | Defender for Containers |

+| Runtime protection| Threat detection (workload) | Arc enabled K8s clusters | Preview | X | Defender extension | Defender for Containers |

+| Discovery and provisioning | Discovery of unprotected clusters | Arc enabled K8s clusters | Preview | X | Agentless | Free |

+| Discovery and provisioning | Collection of control plane threat data | Arc enabled K8s clusters | Preview | Γ£ô | Defender extension | Defender for Containers |

+| Discovery and provisioning | Auto provisioning of Defender extension | Arc enabled K8s clusters | Preview | Γ£ô | Agentless | Defender for Containers |

+| Discovery and provisioning | Auto provisioning of Azure policy extension | Arc enabled K8s clusters | Preview | X | Agentless | Defender for Containers |

+| Kubernetes distributions and configurations | **Supported**<br> ΓÇó Any Cloud Native Computing Foundation (CNCF) certified Kubernetes clusters<br>ΓÇó [Azure Kubernetes Service (AKS)](../aks/intro-kubernetes.md)^{[1](#footnote1)}<br> ΓÇó [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/)<br> ΓÇó [Google Kubernetes Engine (GKE) Standard](https://cloud.google.com/kubernetes-engine/) <br><br> **Supported via Arc enabled Kubernetes** ^{[2](#footnote2)} ^{[3](#footnote3)}<br>ΓÇó [Azure Kubernetes Service on Azure Stack HCI](/azure-stack/aks-hci/overview)<br> ΓÇó [Kubernetes](https://kubernetes.io/docs/home/)<br> ΓÇó [AKS Engine](https://github.com/Azure/aks-engine)<br> ΓÇó [Azure Red Hat OpenShift](https://azure.microsoft.com/services/openshift/)<br> ΓÇó [Red Hat OpenShift](https://www.openshift.com/learn/topics/kubernetes/) (version 4.6 or newer)<br> ΓÇó [VMware Tanzu Kubernetes Grid](https://tanzu.vmware.com/kubernetes-grid)<br> ΓÇó [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/)<br><br>**Unsupported**<br> ΓÇó Azure Kubernetes Service (AKS) Clusters without [Kubernetes RBAC](../aks/concepts-identity.md#kubernetes-rbac) <br> |

+Add custom alert rule to pinpoint specific activity as needed for your organization such as for specific protocols, source or destination addresses, or a combination of parameters.

+For example, you might want to define an alert for an environment running MODBUS to detect any write commands to a memory register, on a specific IP address and ethernet destination. Another example would be an alert for any access to a specific IP address.

+Use custom alert rule actions to instruct Defender for IT to take specific action when the alert is triggered, such as allowing users to access PCAP files from the alert, assigning alert severity, or generating an event that shows in the event timeline. Alert messages indicate that the alert was generated from a custom alert rule.

+**To create a custom alert rule**:

+1. On the sensor console, select **Custom alert rules** > **+ Create rule**.

+1. In the **Create custom alert rule** pane that shows on the right, define the following fields:

+ - **Alert name**. Enter a meaningful name for the alert.

+ - **Alert protocol**. Select the protocol you want to detect. In specific cases, select one of the following protocols:

+ - For a database data or structure manipulation event, select **TNS** or **TDS**

+ - For a file event, select **HTTP**, **DELTAV**, **SMB**, or **FTP**, depending on the file type

+ - For a package download event, select **HTTP**

+ - For an open ports (dropped) event, select **TCP** or **UDP**, depending on the port type.

+ To create rules that monitor for specific changes in one of your OT protocols, such as S7 or CIP, use any parameters found on that protocol, such as `tag` or `sub-function`.

+

+ - **Message**. Define a message to display when the alert is triggered. Alert messages support alphanumeric characters and any traffic variables detected. For example, you might want to include the detected source and destination addresses. Use curly brackets (**{}**) to add variables to the alert message.

+ - **Direction**. Enter a source and/or destination IP address where you want to detect traffic.

+ - **Conditions**. Define one or more conditions that must be met to trigger the alert. Select the **+** sign to create a condition set with multiple conditions that use the **AND** operator. If you select a MAC address or IP address as a variable, you must convert the value from a dotted-decimal address to decimal format.

+ - **Detected**. Define a date and/or time range for the traffic you want to detect.

+ - **Action**. Define an action you want Defender for IoT to take automatically when the alert is triggered.

+To edit a custom alert rule, select the rule and then select the options (**...**) menu > **Edit**. Modify the alert rule as needed and save your changes.

+Edits made to custom alert rules, such as changing a severity level or protocol, are tracked in the **Event timeline** page on the sensor console. For more information, see [Track sensor activity](how-to-track-sensor-activity.md).

+**To enable or disable custom alert rules**

+You can disable custom alert rules to prevent them from running without deleting them altogether.

+In the **Custom alert rules** page, select one or more rules, and then select **Enable**, **Disable**, or **Delete** in the toolbar as needed.

+- [Custom alert updates](#custom-alert-updates)

+For more information and the updated custom alert procedure, see [Customize alert rules](how-to-accelerate-alert-incident-response.md#customize-alert-rules).

+ Title: Connect to lab virtual machines through Browser connect

+description: Learn how to connect to lab virtual machines (VMs) through a browser if Browser connect is enabled for the lab.

+# Connect to DevTest Labs VMs through a browser with Azure Bastion

+This article describes how to connect to DevTest Labs virtual machines (VMs) through a browser by using [Azure Bastion](../bastion/index.yml). Azure Bastion provides secure remote desktop protocol (RDP) or secure shell (SSH) access without using public IP addresses or exposing RDP or SSH ports to the internet.

+> [!IMPORTANT]

+> The VM's lab must be in a [Bastion-configured virtual network](enable-browser-connection-lab-virtual-machines.md#option-1-connect-a-lab-to-an-azure-bastion-enabled-virtual-network) and have [Browser connect enabled](enable-browser-connection-lab-virtual-machines.md#connect-to-lab-vms-through-azure-bastion). For more information, see [Enable browser connection to DevTest Labs VMs with Azure Bastion](enable-browser-connection-lab-virtual-machines.md).

+To connect to a lab VM through a browser:

+1. In the [Azure portal](https://portal.azure.com), search for and select **DevTest Labs**.

+1. On the **DevTest Labs** page, select your lab.

+1. On the lab's **Overview** page, select the VM you want to connect to from the list under **My virtual machines**.

+1. On the VM's **Overview** page, from the top menu, select **Browser connect**.

+1. In the **Browser connect** pane, enter the username and password for the VM, and select whether you want the VM to open in a new browser window.

+1. Select **Connect**.

+ :::image type="content" source="./media/connect-virtual-machine-through-browser/lab-vm-browser-connect.png" alt-text="Screenshot of the V M Overview screen with the Browser connect button highlighted.":::

+> [!NOTE]

+> If you don't see **Browser connect** on the VM's top menu, the lab isn't set up for Browser connect. You can select **Connect** to connect via [RDP](connect-windows-virtual-machine.md) or [SSH](connect-linux-virtual-machine.md).

+ Title: Delete a lab virtual machine or a lab

+description: Learn how to delete a virtual machine from a lab or delete a lab in Azure DevTest Labs.

+# Delete labs or lab VMs in Azure DevTest Labs

+This article shows you how to delete a virtual machine (VM) from a lab or delete a lab in Azure DevTest Labs.

+## Delete a VM from a lab

+When you create a VM in a lab, DevTest Labs automatically creates resources for the VM, like a disk, network interface, and public IP address, in a separate resource group. Deleting the VM deletes most of the resources created at VM creation, including the VM, network interface, and disk. However, deleting the VM doesn't delete:

+- Any resources you manually created in the VM's resource group.

+- The VM's key vault in the lab's resource group.

+- Any availability set, load balancer, or public IP address in the VM's resource group. These resources are shared by multiple VMs in a resource group.

+To delete a VM from a lab:

+1. On the lab's **Overview** page in the Azure portal, find the VM you want to delete in the list under **My virtual machines**.

+1. Either:

+ - Select **More options** (**...**) next to the VM listing, and select **Delete** from the context menu.

+ 

+ or

+ - Select the VM name in the list, and then on the VM's **Overview** page, select **Delete** from the top menu.

+ 

+1. On the **Are you sure you want to delete it?** page, select **Delete**.

+ 

+1. To check deletion status, select the **Notifications** icon on the Azure menu bar.

+## Delete a lab

+When you delete a lab from a resource group, DevTest Labs automatically deletes:

+- All VMs in the lab.

+- All resource groups associated with those VMs.

+- All resources that DevTest Labs automatically created during lab creation.

+DevTest Labs doesn't delete the lab's resource group itself, and doesn't delete any resources you manually created in the lab's resource group.

+> [!NOTE]

+> If you want to manually delete the lab's resource group, you must delete the lab first. You can't delete a resource group that has a lab in it.

+To delete a lab:

+1. On the lab's **Overview** page in the Azure portal, select **Delete** from the top toolbar.

+ 

+1. On the **Are you sure you want to delete it?** page, under **Type the lab name**, type the lab name, and then select **Delete**.

+ 

+1. To check deletion status, select the **Notifications** icon on the Azure menu bar.

+ 

+- [Attach and detach data disks for lab VMs](devtest-lab-attach-detach-data-disk.md)

+- [Export or delete personal data](personal-data-delete-export.md)

+- [Move a lab to another region](how-to-move-labs.md)

+This section describes additional considerations and recommendations for modeling.

+### Use DTDL industry-standard ontologies

+If your solution is for a certain established industry (like smart buildings, smart cities, or energy grids), consider starting with a pre-existing set of models for you industry instead of designing your models from scratch. Microsoft has partnered with domain experts to create DTDL model sets based on industry standards, to help minimize reinvention and encourage consistency and simplicity across industry solutions. You can read more about these ontologies, including how to use them and what ontologies are available now, in [What is an ontology?](concepts-ontologies.md).

+### Consider query implications

+### Validate models

+ Title: Adopting DTDL-based industry ontologies

+# Adopting a DTDL industry ontology

+Microsoft has partnered with domain experts to create DTDL model sets based on industry standards, to help minimize reinvention and simplify solutions. This article presents the industry ontologies that are currently available.

+## List of ontologies

+| Industry | Ontology repository | Description | Learn more |

+| | | | |

+| Smart buildings | [Digital Twins Definition Language-based RealEstateCore ontology for smart buildings](https://github.com/Azure/opendigitaltwins-building) | Microsoft has partnered with [RealEstateCore](https://www.realestatecore.io/) to deliver this open-source DTDL ontology for the real estate industry. [RealEstateCore](https://www.realestatecore.io/) is a Swedish consortium of real estate owners, software vendors, and research institutions.<br><br>This smart buildings ontology provides common ground for modeling smart buildings, using industry standards (like [BRICK Schema](https://brickschema.org/ontology/) or [W3C Building Topology Ontology](https://w3c-lbd-cg.github.io/bot/https://docsupdatetracker.net/index.html)) to avoid reinvention. The ontology also comes with best practices for how to consume and properly extend it. | You can read more about the partnership with RealEstateCore and goals for this initiative in the following blog post and embedded video: [RealEstateCore, a smart building ontology for digital twins, is now available](https://techcommunity.microsoft.com/t5/internet-of-things/realestatecore-a-smart-building-ontology-for-digital-twins-is/ba-p/1914794). |

+| Smart cities | [Digital Twins Definition Language (DTDL) ontology for Smart Cities](https://github.com/Azure/opendigitaltwins-smartcities) | Microsoft has collaborated with [Open Agile Smart Cities (OASC)](https://oascities.org/) and [Sirus](https://sirus.be/) to provide a DTDL-based ontology for smart cities, starting with [ETSI CIM NGSI-LD](https://www.etsi.org/committee/cim). | You can also read more about the partnerships and approach for smart cities in the following blog post and embedded video: [Smart Cities Ontology for Digital Twins](https://techcommunity.microsoft.com/t5/internet-of-things/smart-cities-ontology-for-digital-twins/ba-p/2166585). |

+| Energy grids | [Digital Twins Definition Language (DTDL) ontology for Energy Grid](https://github.com/Azure/opendigitaltwins-energygrid/) | This ontology was created to help solution providers accelerate development of digital twin solutions for energy use cases like monitoring grid assets, outage and impact analysis, simulation, and predictive maintenance. Additionally, the ontology can be used to enable the digital transformation and modernization of the energy grid. It's adapted from the [Common Information Model (CIM)](https://cimug.ucaiug.org/), a global standard for energy grid assets management, power system operations modeling, and physical energy commodity market. | You can also read more about the partnerships and approach for energy grids in the following blog post: [Energy Grid Ontology for Digital Twins](https://techcommunity.microsoft.com/t5/internet-of-things/energy-grid-ontology-for-digital-twins-is-now-available/ba-p/2325134). |

+Each ontology is focused on an initial set of models. You can contribute to the ontologies by suggesting extensions or other improvements through the GitHub contribution process in each ontology repository.

+For more information about the RealEstateCore ontology, see [Digital Twins Definition Language-based RealEstateCore ontology for smart buildings](https://github.com/Azure/opendigitaltwins-building) on GitHub.

+* [Adopting DTDL-based industry ontologies](concepts-ontologies-adopt.md)

+*Models* are defined in a JSON-like language called [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/dtdlv2.md), and they describe twins by their state properties, telemetry events, commands, components, and relationships. Here are some other capabilities of models:

+* You can specialize twins using model *inheritance*. One model can inherit from another.

+* You can design your own model sets from scratch, or get started with a pre-existing set of [DTDL industry ontologies](concepts-ontologies.md) based on common vocabulary for your industry.

+DTDL is also used for data models throughout other Azure IoT services, including [IoT Plug and Play](../iot-develop/overview-iot-plug-and-play.md) and [Time Series Insights](../time-series-insights/overview-what-is-tsi.md). This type of commonality helps you keep your Azure Digital Twins solution connected and compatible with other parts of the Azure ecosystem.

+ > In the offline migration mode, the source SQL Server database should not be used for write activity while database backups are restored on target Azure SQL Managed Instance. Application downtime needs to be considered till the migration completes.

+ > In the online migration mode, the source SQL Server database can be used for read and write activity while database backups are continuously restored on target Azure SQL Managed Instance. Application downtime is limited to duration for the cutover at the end of migration.

+ > In the offline migration mode, the source SQL Server database should not be used for write activity while database backup files are restored on the target Azure SQL database. Application downtime persists through the start until the completion of the migration process.

+ > In the online migration mode, the source SQL Server database can be used for read and write activity while database backups are continuously restored on the target SQL Server on Azure Virtual Machine. Application downtime is limited to duration for the cutover at the end of migration.

+ Title: Azure Health Data Services as Event Grid source

+description: Describes the properties that are provided for Azure Health Data Services events with Azure Event Grid

+# Azure Health Data Services as an Event Grid source

+This article provides the properties and schema for Azure Health Data Services events. For an introduction to event schemas, see [Azure Event Grid event schema](event-schema.md).

+## Available event types

+### List of events for Azure Health Data Services REST APIs

+The following Fast Healthcare Interoperability Resources (FHIR&#174;) resource events are triggered when calling the REST APIs.

+ |Event name|Description|

+ |-|--|

+ |**FhirResourceCreated** |The event emitted after a FHIR resource gets created successfully.|

+ |**FhirResourceUpdated** |The event emitted after a FHIR resource gets updated successfully.|

+ |**FhirResourceDeleted** |The event emitted after a FHIR resource gets soft deleted successfully.|

+## Example event

+This section contains examples of what events message data would look like for each FHIR resource event.

+> [!Note]

+> Events data looks similar to these examples with the `metadataVersion` property set to a value of `1`.

+>

+> For more information, see [Azure Event Grid event schema properties](/azure/event-grid/event-schema#event-properties).

+### FhirResourceCreated event

+# [Event Grid event schema](#tab/event-grid-event-schema)

+```json

+{

+ "id": "e4c7f556-d72c-e7f7-1069-1e82ac76ab41",

+ "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e0a1f743-1a70-451f-830e-e96477163902",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e0a1f743-1a70-451f-830e-e96477163902",

+ "resourceVersionId": 1

+ },

+ "eventType": "Microsoft.HealthcareApis.FhirResourceCreated",

+ "dataVersion": "1",

+ "metadataVersion": "1",

+ "eventTime": "2021-09-08T01:14:04.5613214Z"

+}

+```

+# [CloudEvent schema](#tab/cloud-event-schema)

+```json

+{

+ "id": "d674b9b7-7d1c-9b0a-8c48-139f3eb86c48",

+ "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "specversion": "1.0",

+ "type": "Microsoft.HealthcareApis.FhirResourceCreated",

+ "dataschema": "#1",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "time": "2022-02-03T16:48:09.6223354Z",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "resourceVersionId": 1

+ }

+}

+```

+### FhirResourceUpdated event

+# [Event Grid event schema](#tab/event-grid-event-schema)

+```json

+{

+ "id": "634bd421-8467-f23c-b8cb-f6a31e41c32a",

+ "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e0a1f743-1a70-451f-830e-e96477163902",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e0a1f743-1a70-451f-830e-e96477163902",

+ "resourceVersionId": 2

+ },

+ "eventType": "Microsoft.HealthcareApis.FhirResourceUpdated",

+ "dataVersion": "2",

+ "metadataVersion": "1",

+ "eventTime": "2021-09-08T01:29:12.0618739Z"

+}

+```

+# [CloudEvent schema](#tab/cloud-event-schema)

+```json

+{

+ "id": "5e45229e-c663-ea98-72d2-833428f48ad0",

+ "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "specversion": "1.0",

+ "type": "Microsoft.HealthcareApis.FhirResourceUpdated",

+ "dataschema": "#2",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "time": "2022-02-03T16:48:33.5147352Z",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "resourceVersionId": 2

+ }

+}

+```

+### FhirResourceDeleted event

+# [Event Grid event schema](#tab/event-grid-event-schema)

+```json

+{

+ "id": "ef289b93-3159-b833-3a44-dc6b86ed1a8a",

+ "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e0a1f743-1a70-451f-830e-e96477163902",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e0a1f743-1a70-451f-830e-e96477163902",

+ "resourceVersionId": 3

+ },

+ "eventType": "Microsoft.HealthcareApis.FhirResourceDeleted",

+ "dataVersion": "3",

+ "metadataVersion": "1",

+ "eventTime": "2021-09-08T01:31:58.5175837Z"

+}

+```

+# [CloudEvent schema](#tab/cloud-event-schema)

+```json

+{

+ "id": "14648a6e-d978-950e-ee9c-f84c70dba8d3",

+ "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "specversion": "1.0",

+ "type": "Microsoft.HealthcareApis.FhirResourceDeleted",

+ "dataschema": "#3",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "time": "2022-02-03T16:48:38.7338799Z",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "resourceVersionId": 3

+ }

+}

+```

+## Next steps

+* For an introduction to Azure Event Grid, see [What is Event Grid?](overview.md)

+* For more information about creating an Azure Event Grid subscription, see [Event Grid subscription schema](subscription-creation-schema.md).

+(FHIR&#174;) is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

+- [Azure Health Data Services](event-schema-azure-health-data-services.md)

+> [!NOTE]

+> BFD provides faster failover time when a link failure is detected, but the overall connection convergence will take up to a minute for failover between ExpressRoute virtual network gateways and MSEEs.

+>

+[ResetPeering]: ./expressroute-howto-reset-peering.md

+The backends that support direct private end point connectivity are now limited to Storage (Azure Blobs) and App Services. All other backends will have to be put behind an Internal Load Balancer as explained in the Next Steps below.

+The Azure Policy exemptions feature is used to _exempt_ a resource hierarchy or an

+You use JavaScript Object Notation (JSON) to create a policy exemption. The policy exemption contains elements for:

+(reference `requiredTags`) and the **Allowed locations** built-in policy definition (ID:

+If the `policyAssignmentId` is for an initiative assignment, the **policyDefinitionReferenceIds** property may be used to specify which policy definition(s) in the initiative the subject resource

+set the **expiresOn** property. This optional property must be in the Universal ISO 8601 DateTime

+ [Organize your resources with Azure management groups](../../management-groups/overview.md).

+create an initiative titled **Enable Monitoring in Microsoft Defender for Cloud**, with a goal to monitor

+all the available security recommendations in your Microsoft Defender for Cloud instance.

+- **Monitor unencrypted SQL Database in Microsoft Defender for Cloud** - For monitoring unencrypted SQL databases

+- **Monitor OS vulnerabilities in Microsoft Defender for Cloud** - For monitoring servers that don't satisfy the

+- **Monitor missing Endpoint Protection in Microsoft Defender for Cloud** - For monitoring servers without an

+side of the page. Otherwise, use <kbd>Ctrl</kbd>-<kbd>F</kbd> (Windows) or <kbd>Cmd</kbd>-<kbd>F</kbd> (macOS) to use your browser's search feature.

+ Title: Access Azure Health Data Services

+description: This article describes the different ways to access Azure Health Data Services in your applications using tools and programming languages.

+# Access Azure Health Data Services

+In this article, you'll learn about the different ways to access Azure Health Data Services in your applications. After you've provisioned a FHIR service, DICOM service, or IoT connector, you can then access them in your applications using tools like Postman, cURL, REST Client in Visual Studio Code, and with programming languages such as Python and C#.

+In this document, you learned about the tools and programming languages that you can use to access Azure Health Data Services in your applications. To learn how to deploy an instance of Azure Health Data Services using the Azure portal, see

+>[Deploy Azure Health Data Services workspace using the Azure portal](healthcare-apis-quickstart.md)

+ Title: Azure Health Data Services Authentication and Authorization

+description: This article provides an overview of the authentication and authorization of the Azure Health Data Services.

+# Authentication and Authorization for Azure Health Data Services

+ Azure Health Data Services is a collection of secured managed services using [Azure Active Directory (Azure AD)](../active-directory/index.yml), a global identity provider that supports [OAuth 2.0](https://oauth.net/2/).

+For the Azure Health Data Services to access Azure resources, such as storage accounts and event hubs, you must **enable the system managed identity**, and **grant proper permissions** to the managed identity. For more information, see [Azure managed identities](../active-directory/managed-identities-azure-resources/overview.md).

+Azure Health Data Services doesn't support other identity providers. However, customers can use their own identity provider to secure applications, and enable them to interact with the Healthcare APIs by managing client applications and user data access controls.

+FHIR service of Azure Health Data Services provides the following roles:

+DICOM service of Azure Health Data Services provides the following roles:

+The MedTech service doesn't require application roles, but it does rely on the "Azure Event Hubs Data Receiver" to retrieve data stored in the event hub of the customer's subscription.

+After being granted with proper application roles, the authenticated users and client applications can access Azure Health Data Services by obtaining a **valid access token** issued by Azure AD, and perform specific operations defined by the application roles.

+* For FHIR service, the access token is specific to the service or resource.

+* For DICOM service, the access token is granted to the `dicom.healthcareapis.azure.com` resource, not a specific service.

+* For MedTech service, the access token isnΓÇÖt required because it isnΓÇÖt exposed to the users or client applications.

+For obtaining an access token for the Azure Health Data Services, these are the steps using **authorization code flow**:

+4. **The Healthcare APIs service validates that the token contains appropriate claims (properties in the token).** If itΓÇÖs valid, it completes the request and returns data to the client.

+In the **client credentials flow**, permissions are granted directly to the application itself. When the application presents a token to a resource, the resource enforces that the application itself has authorization to perform an action since thereΓÇÖs no user involved in the authentication. Therefore, itΓÇÖs different from the **authorization code flow** in the following ways:

+- The user or the client doesnΓÇÖt need to log in interactively

+- The authorization code isnΓÇÖt required.

+|aud |https://xxx.fhir.azurehealthcareapis.com|Identifies the intended recipient of the token. In `id_tokens`, the audience is your app's Application ID, assigned to your app in the Azure portal. Your app should validate this value and reject the token if the value doesnΓÇÖt match.|

+|idp |https://sts.windows.net/{tenantid}/|Records the identity provider that authenticated the subject of the token. This value is identical to the value of the Issuer claim unless the user account isnΓÇÖt in the same tenant as the issuer - guests, for instance. If the claim isnΓÇÖt present, it means that the value of iss can be used instead. For personal accounts being used in an organizational context (for instance, a personal account invited to an Azure AD tenant), the idp claim may be 'live.com' or an STS URI containing the Microsoft account tenant 9188040d-6c67-4c5b-b112-36a304b66dad.|

+|oid |For example, tenantid |This is the immutable identifier for an object in the Microsoft identity system, in this case, a user account. This ID uniquely identifies the user across applications - two different applications signing in the same user will receive the same value in the oid claim. The Microsoft Graph will return this ID as the ID property for a given user account. Because the oid allows multiple apps to correlate users, the profile scope is required to receive this claim. Note: If a single user exists in multiple tenants, the user will contain a different object ID in each tenant - theyΓÇÖre considered different accounts, even though the user logs into each account with the same credentials.|

+|sub |For example, tenantid |The principal about which the token asserts information, such as the user of an app. This value is immutable and canΓÇÖt be reassigned or reused. The subject is a pairwise identifier - itΓÇÖs unique to a particular application ID. Therefore, if a single user signs into two different apps using two different client IDs, those apps will receive two different values for the subject claim. This may or may not be desired depending on your architecture and privacy requirements.|

+When you create a new service of Azure Health Data Services, your data is encrypted using **Microsoft-managed keys** by default.

+* DICOM service provides encryption of data at rest when imaging data including embedded metadata is persisted in the data store. When metadata is extracted and persisted in the FHIR service, itΓÇÖs encrypted automatically.

+* IoT Connector, after data mapping and normalization, persists device messages to the FHIR service, which is encrypted automatically. In cases where device messages are sent to Azure Event Hubs, which use Azure Storage to store the data, data is automatically encrypted with Azure Storage Service Encryption (Azure SSE).

+In this document, you learned the authentication and authorization of Azure Health Data Services. To learn how to deploy an instance of Azure Health Data Services, see

+>[Deploy Azure Health Data Services workspace using the Azure portal](healthcare-apis-quickstart.md)

+In general, customers should consider autoscale when their workloads vary significantly and are unpredictable.

+When autoscale is enabled, the system calculates and sets the initial `Tmax` value. The scalability is governed by the maximum throughput `RU/s` value, or `Tmax`, and scales between `0.1 *Tmax` (or 10% `Tmax`) and `Tmax RU/s`. The `Tmax` increases automatically as the total data size grows. To ensure maximum scalability, the `Tmax` value should be kept as-is. However, customers can request that the value be changed to something between 10% and 100% of the `Tmax` value.

+Use the formula to calculate required RU/s.

+1. The client sends a request to the `/authorize` endpoint of Azure AD. Azure AD will redirect the client to a sign-in page where the user will authenticate using appropriate credentials (for example username and password or two-factor authentication). See details on [obtaining an authorization code](../../active-directory/azuread-dev/v1-protocols-oauth-code.md#request-an-authorization-code). Upon successful authentication, an *authorization code* is returned to the client. Azure AD will only allow this authorization code to be returned to a registered reply URL configured in the client application registration.

+1. The client application exchanges the authorization code for an *access token* at the `/token` endpoint of Azure AD. When you request a token, the client application may have to provide a client secret (the applications password). See details on [obtaining an access token](../../active-directory/azuread-dev/v1-protocols-oauth-code.md#use-the-authorization-code-to-request-an-access-token).

+There are other variations (for example on behalf of flow) for obtaining a token. Check the Azure AD documentation for details. When you use Azure API for FHIR, there are some shortcuts for obtaining an access token (for debugging purposes) [using the Azure CLI](get-healthcare-apis-access-token-cli.md).

+The first step in the token validation is to verify that the token was issued by the correct identity provider and that it hasn't been modified. The FHIR server will be configured to use a specific identity provider known as the authority `Authority`. The FHIR server will retrieve information about the identity provider from the `/.well-known/openid-configuration` endpoint. When you use Azure AD, the full URL is:

+When you use the OSS Microsoft FHIR server for Azure, the server will validate:

+In this how-to guide, we'll review the additional settings you may want to set in your Azure API for FHIR. There are additional pages that drill into even more details.

+The Azure API for FHIR will only allow authorized users to access the FHIR API. You can configure authorized users through two different mechanisms. The primary and recommended way to configure access control is using [Azure role-based access control (Azure RBAC)](../../role-based-access-control/index.yml), which is accessible through the **Access control (IAM)** blade. Azure RBAC only works if you want to secure data plane access using the Azure Active Directory tenant associated with your subscription. If you wish to use a different tenant, the Azure API for FHIR offers a local FHIR data plane access control mechanism. The configuration options aren't as rich when using the local RBAC mechanism. For details, choose one of the following options:

+* [Azure RBAC for FHIR data plane](configure-azure-rbac.md). This is the preferred option when you're using the Azure Active Directory tenant associated with your subscription.

+* [CARIN IG for Blue Button®](http://hl7.org/fhir/us/carin-bb/STU1/https://docsupdatetracker.net/index.html): Payers are required to make patients' claims and encounters data available according to the CARIN IG for Blue Button Implementation Guide (C4BB IG). The C4BB IG provides a set of resources that payers can display to consumers via a FHIR API and includes the details required for claims data in the Interoperability and Patient Access API. This implementation guide uses the ExplanationOfBenefit (EOB) Resource as the main resource, pulling in other resources as they're referenced.

+To test adherence to the various implementation guides, [Touchstone](https://touchstone.aegis.net/touchstone/) is a great resource. Throughout the upcoming tutorials, we'll focus on ensuring that the Azure API for FHIR is configured to successfully pass various Touchstone tests. The Touchstone site has a great amount of documentation to help you get up and running.

+In this article, you'll learn how to use [Azure role-based access control (Azure RBAC)](../../role-based-access-control/index.yml) to assign access to the Azure API for FHIR data plane. Azure RBAC is the preferred methods for assigning data plane access when data plane users are managed in the Azure Active Directory tenant associated with your Azure subscription. If you're using an external Azure Active Directory tenant, refer to the [local RBAC assignment reference](configure-local-rbac.md).

+The **Authority** should be set to the Azure Active directory tenant associated with your subscription and there should be no GUIDs in the box labeled **Allowed object IDs**. You'll also notice that the box is disabled and a label indicates that Azure RBAC should be used to assign data plane roles.

+To grant users, service principals or groups access to the FHIR data plane, select **Access control (IAM)**, then select **Role assignments** and select **+ Add**:

+If the database throughput is greater than 10,000 RU/s or if the data stored in the database is more than 50 GB, your client application must be capable of handling continuation tokens. A new partition is created in the database for every throughput increase of 10,000 RU/s or if the amount of data stored is more than 50 GB. Multiple partitions create a multi-page response in which pagination is implemented by using continuation tokens.

+This article explains how to configure the Azure API for FHIR to use a secondary Azure Active Directory (Azure AD) tenant for data access. Use this mode only if it isn't possible for you to use the Azure AD tenant associated with your subscription.

+After entering the required Azure AD object IDs, select **Save** and wait for changes to be saved before trying to access the data plane using the assigned users, service principals, or groups. The object IDs are granted with all permissions, an equivalent of the "FHIR Data Contributor" role.

+The local RBAC setting is only visible from the authentication blade; it isn't visible from the Access Control (IAM) blade.

+For the resource type, search and select **Microsoft.HealthcareApis/services**. For the resource, select the FHIR resource. For target subresource, select **FHIR**.

+If you don't have an existing Private DNS Zone set up, select **(New)privatelink.azurehealthcareapis.com**. If you already have your Private DNS Zone configured, you can select it from the list. It must be in the format of **privatelink.azurehealthcareapis.com**.

+For manual approval, select the second option under Resource, "Connect to an Azure resource by resource ID or alias". For Target subresource, enter "fhir" as in Auto Approval.

+In the Azure portal, select the resource group of the FHIR server. Select and open the Private DNS zone, **privatelink.azurehealthcareapis.com**. Select **Virtual network links** under the *settings* section. Select the **Add** button to add your second VNet to the private DNS zone. Enter the link name of your choice, select the subscription and the VNet you created. Optionally, you can enter the resource ID for the second VNet. Select **Enable auto registration**, which automatically adds a DNS record for your VM connected to the second VNet. When you delete a VNet link, the DNS record for the VM is also deleted.

+To ensure that your FHIR server isn't receiving public traffic after disabling public network access, select the /metadata endpoint for your server from your computer. You should receive a 403 Forbidden.

+You can use the **nslookup** tool to verify connectivity. If the private link is configured properly, you should see the FHIR server URL resolves to the valid private IP address, as shown below. Note that the IP address **168.63.129.16** is a virtual public IP address used in Azure. For more information, see [What is IP address 168.63.129.16](../../virtual-network/what-is-ip-address-168-63-129-16.md)

+If the private link isn't configured properly, you may see the public IP address instead and a few aliases including the Traffic Manager endpoint. This indicates that the private link DNS zone canΓÇÖt resolve to the valid private IP address of the FHIR server. When VNet peering is configured, one possible reason is that the second peered VNet hasn't been added to the private link DNS zone. As a result, you'll see the HTTP error 403, "Access to xxx was denied", when trying to access the /metadata endpoint of the FHIR server.

+# Converting your data to FHIR for Azure API for FHIR

+The `$convert-data` custom endpoint in the FHIR service is meant for data conversion from different data types to FHIR. It uses the Liquid template engine and the templates from the [FHIR Converter](https://github.com/microsoft/FHIR-Converter) project as the default templates. You can customize these conversion templates as needed. Currently it supports three types of data conversion: **C-CDA to FHIR**, **HL7v2 to FHIR**, **JSON to FHIR**.

+> [!NOTE]

+> `$convert-data` endpoint can be used as a component within an ETL pipeline for the conversion of raw healthcare data from legacy formats into FHIR format. However, it is not an ETL pipeline in itself. We recommend you to use an ETL engine such as Logic Apps or Azure Data Factory for a complete workflow in preparing your FHIR data to be persisted into the FHIR server. The workflow might include: data reading and ingestion, data validation, making $convert-data API calls, data pre/post-processing, data enrichment, and data de-duplication.

+The `$convert-data` operation is integrated into the FHIR service to run as part of the service. After enabling `$convert-data` in your server, you can make API calls to the server to convert your data into FHIR:

+| inputData | Data to be converted. | For `Hl7v2`: string <br> For `Ccda`: XML <br> For `Json`: JSON |

+| inputDataType | Data type of input. | ```HL7v2```, ``Ccda``, ``Json`` |

+| templateCollectionReference | Reference to an [OCI image ](https://github.com/opencontainers/image-spec) template collection on [Azure Container Registry (ACR)](https://azure.microsoft.com/services/container-registry/). It's the image containing Liquid templates to use for conversion. It can be a reference either to the default templates or a custom template image that is registered within the FHIR service. See below to learn about customizing the templates, hosting those on ACR, and registering to the FHIR service. | For ***default/sample*** templates: <br> **HL7v2** templates: <br>```microsofthealth/fhirconverter:default``` <br>``microsofthealth/hl7v2templates:default``<br> **C-CDA** templates: <br> ``microsofthealth/ccdatemplates:default`` <br> **JSON** templates: <br> ``microsofthealth/jsontemplates:default`` <br><br> For ***custom*** templates: <br> \<RegistryServer\>/\<imageName\>@\<imageDigest\>, \<RegistryServer\>/\<imageName\>:\<imageTag\> |

+| rootTemplate | The root template to use while transforming the data. | For **HL7v2**:<br> "ADT_A01", "ADT_A02", "ADT_A03", "ADT_A04", "ADT_A05", "ADT_A08", "ADT_A11", "ADT_A13", "ADT_A14", "ADT_A15", "ADT_A16", "ADT_A25", "ADT_A26", "ADT_A27", "ADT_A28", "ADT_A29", "ADT_A31", "ADT_A47", "ADT_A60", "OML_O21", "ORU_R01", "ORM_O01", "VXU_V04", "SIU_S12", "SIU_S13", "SIU_S14", "SIU_S15", "SIU_S16", "SIU_S17", "SIU_S26", "MDM_T01", "MDM_T02"<br><br> For **C-CDA**:<br> "CCD", "ConsultationNote", "DischargeSummary", "HistoryandPhysical", "OperativeNote", "ProcedureNote", "ProgressNote", "ReferralNote", "TransferSummary" <br><br> For **JSON**: <br> "ExamplePatient", "Stu3ChargeItem" <br> |

+> [!NOTE]

+> JSON templates are sample templates for use, not "default" templates that adhere to any pre-defined JSON message types. JSON doesn't have any standardized message types, unlike HL7v2 messages or C-CDA documents. Therefore, instead of default templates we provide you with some sample templates that you can use as a starting guide for your own customized templates.

+#### Sample Request

+#### Sample Response

+It's recommended that you host your own copy of templates on ACR. There are four steps involved in hosting your own copy of templates and using those in the $convert-data operation:

+[  ](media/convert-data/fhir-mi-enabled.png#lightbox)

+ [  ](../../../includes/role-based-access-control/media/add-role-assignment-page.png#lightbox)

+Browse to the **Artifacts** blade under **Data transformation** in your Azure API for FHIR instance. You'll see the list of currently registered ACR servers. Select **Add**, and then select your registry server from the drop-down menu. You'll need to select **Save** for the registration to take effect. It may take a few minutes to apply the change and restart your instance.

+ :::image type="content" source="media/convert-data/networking-container-registry.png" alt-text=" Screen image of the container registry.":::

+> The above steps are similar to the configuration steps described in the document How to export FHIR data. For more information, see [Secure Export to Azure Storage](export-data.md#secure-export-to-azure-storage)

+## Next steps

+In this article, you learned about data conversion for Azure API for FHIR. For more information about related GitHub Projects for Azure API for FHIR, see

+>[!div class="nextstepaction"]

+>[Related GitHub Projects for Azure API for FHIR](fhir-github-projects.md)

+In this article, you'll learn three ways to copy data from Azure API for FHIR to [Azure Synapse Analytics](https://azure.microsoft.com/services/synapse-analytics/), which is a limitless analytics service that brings together data integration, enterprise data warehousing, and big data analytics.

+* Use the [FHIR to Synapse Sync Agent](https://github.com/microsoft/FHIR-Analytics-Pipelines/blob/main/FhirToDataLake/docs/Deployment.md) OSS tool

+* Use the [FHIR to CDM pipeline generator](https://github.com/microsoft/FHIR-Analytics-Pipelines/blob/main/FhirToCdm/docs/fhir-to-cdm.md) OSS tool

+* Use $export and load data to Synapse using T-SQL

+## Using the FHIR to Synapse Sync Agent OSS tool

+> [!Note]

+> [FHIR to Synapse Sync Agent](https://github.com/microsoft/FHIR-Analytics-Pipelines/blob/main/FhirToDataLake/docs/Deployment.md) is an open source tool released under MIT license, and is not covered by the Microsoft SLA for Azure services.

+The **FHIR to Synapse Sync Agent** is a Microsoft OSS project released under MIT License. It's an Azure function that extracts data from a FHIR server using FHIR Resource APIs, converts it to hierarchical Parquet files, and writes it to Azure Data Lake in near real time. This also contains a script to create external tables and views in [Synapse Serverless SQL pool](../../synapse-analytics/sql/on-demand-workspace-overview.md) pointing to the Parquet files.

+This solution enables you to query against the entire FHIR data with tools such as Synapse Studio, SSMS, and Power BI. You can also access the Parquet files directly from a Synapse Spark pool. You should consider this solution if you want to access all of your FHIR data in near real time, and want to defer custom transformation to downstream systems.

+Follow the OSS [documentation](https://github.com/microsoft/FHIR-Analytics-Pipelines/blob/main/FhirToDataLake/docs/Deployment.md) for installation and usage instructions.

+## Using the FHIR to CDM pipeline generator OSS tool

+> [!Note]

+> [FHIR to CDM pipeline generator](https://github.com/microsoft/FHIR-Analytics-Pipelines/blob/main/FhirToCdm/docs/fhir-to-cdm.md) is an open source tool released under MIT license, and is not covered by the Microsoft SLA for Azure services.

+The **FHIR to CDM pipeline generator** is a Microsoft OSS project released under MIT License. It's a tool to generate an ADF pipeline for copying a snapshot of data from a FHIR server using $export API, transforming it to csv format, and writing to a [CDM folder](https://docs.microsoft.com/common-data-model/data-lake) in Azure Data Lake Storage Gen 2. The tool requires a user-created configuration file containing instructions to project and flatten FHIR Resources and fields into tables. You can also follow the instructions for creating a downstream pipeline in Synapse workspace to move data from CDM folder to Synapse dedicated SQL pool.

+This solution enables you to transform the data into tabular format as it gets written to CDM folder. You should consider this solution if you want to transform FHIR data into a custom schema after it's extracted from the FHIR server.

+Follow the OSS [documentation](https://github.com/microsoft/FHIR-Analytics-Pipelines/blob/main/FhirToCdm/docs/fhir-to-cdm.md) for installation and usage instructions.

+## Loading exported data to Synapse using T-SQL

+In this approach, you use the FHIR `$export` operation to copy FHIR resources into a **Azure Data Lake Gen 2 (ADL Gen 2) blob storage** in `NDJSON` format. Subsequently, you load the data from the storage into **serverless or dedicated SQL pools** in Synapse using T-SQL. You can convert these steps into a robust data movement pipeline using [Synapse pipelines](../../synapse-analytics/get-started-pipelines.md).

+### Using `$export` to copy data

+#### Configuring `$export` in the FHIR server

+Azure API for FHIR implements the `$export` operation defined by the FHIR specification to export all or a filtered subset of FHIR data in `NDJSON` format. In addition, it supports [de-identified export](./de-identified-export.md) to anonymize FHIR data during the export.

+To export FHIR data to Azure blob storage, you first need to configure your FHIR server to export data to the storage account. You'll need to (1) enable Managed Identity, (2) go to Access Control in the storage account and add role assignment, (3) select your storage account for `$export`. More step by step can be found [here](./configure-export-data.md).

+You can also use `_type` parameter in the `$export` call above to restrict the resources that you want to export. For example, the following call will export only `Patient`, `MedicationRequest`, and `Observation` resources:

+### Using Synapse for Analytics

+#### Creating a Synapse workspace

+Before using Synapse, you'll need a Synapse workspace. You'll create an Azure Synapse Analytics service on Azure portal. More step-by-step guide can be found [here](../../synapse-analytics/get-started-create-workspace.md). You need an `ADLSGEN2` account to create a workspace. Your Azure Synapse workspace will use this storage account to store your Synapse workspace data.

+After creating a workspace, you can view your workspace in Synapse Studio by signing into your workspace on [https://web.azuresynapse.net](https://web.azuresynapse.net), or launching Synapse Studio in the Azure portal.

+To copy your data to Synapse, you need to create a linked service that connects your Azure Storage account, where you've exported your data, with Synapse. More step-by-step instructions can be found [here](../../synapse-analytics/data-integration/data-integration-sql-pool.md#create-linked-services).

+Now that you have a linked service between your ADL Gen 2 storage and Synapse, you're ready to use Synapse SQL pools to load and analyze your FHIR data.

+#### Decide between serverless and dedicated SQL pool

+Since it's serverless, there's no infrastructure to setup or clusters to maintain. You can start querying data from Synapse Studio as soon as the workspace is created.

+The simplest and fastest way to load data from your storage to a dedicated SQL pool is to use the **`COPY`** command in T-SQL, which can read CSV, Parquet, and ORC files. As in the example query below, use the `COPY` command to load the `NDJSON` rows into a tabular structure.

+Once you have the JSON rows in the `StagingPatient` table above, you can create different tabular formats of the data using the `OPENJSON` function and storing the results into tables. Here's a sample SQL query to create a `Patient` table by extracting a few fields from the `Patient` resource:

+ ResourceId VARCHAR(64) '$.id',

+ FullName VARCHAR(100) '$.name[0].text',

+ FamilyName VARCHAR(50) '$.name[0].family',

+ GivenName VARCHAR(50) '$.name[0].given[0]',

+ Gender VARCHAR(20) '$.gender',

+ DOB DATETIME2 '$.birthDate',

+ MaritalStatus VARCHAR(20) '$.maritalStatus.coding[0].display',

+ LanguageOfCommunication VARCHAR(20) '$.communication[0].language.text'

+In this article, you learned three different ways to copy your FHIR data into Synapse.

+Next, you can learn about how you can de-identify your FHIR data while exporting it to Synapse in order to protect PHI.

+In Azure, this is typically accomplished using an encryption key in the customer's Azure Key Vault. Azure SQL, Azure Storage, and Cosmos DB are some examples that provide this capability today. Azure API for FHIR leverages this support from Cosmos DB. When you create an account, you'll have the option to specify an Azure Key Vault key URI. This key will be passed on to Cosmos DB when the DB account is provisioned. When a FHIR request is made, Cosmos DB fetches your key and uses it to encrypt/decrypt the data.

+In this test, youΓÇÖll need to load some sample data for the test to pass. We have a rest file [here](https://github.com/microsoft/fhir-server/blob/main/docs/rest/PayerDataExchange/membermatch.http) with the patient and coverage linked that you'll need for the test. Once this data is loaded, you'll be able to successfully pass this test. If the data isn't loaded, you'll receive a 422 response due to not finding an exact match.

+The next tests we'll review is the [patient by reference](https://touchstone.aegis.net/touchstone/testdefinitions?selectedTestGrp=/FHIRSandbox/DaVinci/FHIR4-0-1-Test/PDEX/PayerExchange/02-PatientByReference&activeOnly=false&contentEntry=TEST_SCRIPTS) tests. This set of tests validates that you can find a patient based on various search criteria. The best way to test the patient by reference will be to test against your own data, but we've uploaded a [sample resource file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/PayerDataExchange/PDex_Sample_Data.http) that you can load to use as well.

+ Title: Exporting de-identified data for Azure API for FHIR

+# Exporting de-identified data for Azure API for FHIR

+Here's the list of parameters to use with the command to create an endpoint:

+Here's the list of parameters to use with the command to add a message route:

+|EndpointName|endpoint-name|Name of the endpoint you've created above.|

+In this article, you'll learn how to enable diagnostic logging in Azure API for FHIR and be able to review some sample queries for these logs. Access to diagnostic logs is essential for any healthcare service where compliance with regulatory requirements (such as HIPAA) is a must. The feature in Azure API for FHIR that enables diagnostic logs is the [**Diagnostic settings**](../../azure-monitor/essentials/diagnostic-settings.md) in the Azure portal.

+You can view the metrics under Monitoring | Metrics from the portal. The metrics include Number of Requests, Average Latency, Number of Errors, Data Size, RUs Used, Number of requests that exceeded capacity, and Availability (in %). The screenshot below shows RUs used for a sample environment with few activities in the last seven days. You can download the data in Json format.

+ 2. **Stream to event hub** for ingestion by a third-party service or custom analytic solution. You'll need to create an event hub namespace and event hub policy before you can configure this step.

+ 3. **Stream to the Log Analytics** workspace in Azure Monitor. You'll need to create your Logs Analytics Workspace before you can select this option.

+|LogCategory|String|The log category (we're currently returning ΓÇÿAuditLogsΓÇÖ LogCategory)

+|Location|String|The location of the server that processed the request (for example, South Central US)

+|OperationName|String| Describes the type of operation (for example, update, search-type)

+|StatusCode|Int|The HTTP status code. (for example, 200)

+In some situations, thereΓÇÖs a potential for a job to be stuck in a bad state. This can occur especially if the storage account permissions havenΓÇÖt been set up properly. One way to validate if your export is successful is to check your storage account to see if the corresponding container (that is, `ndjson`) files are present. If they arenΓÇÖt present, and there are no other export jobs running, then thereΓÇÖs a possibility the current job is stuck in a bad state. You should cancel the export job by sending a cancellation request and try requeuing the job again. Our default run time for an export in bad state is 10 minutes before it will stop and move to a new job or retry the export.

+1. **Confidential clients**, also known as web apps in Azure AD. Confidential clients are applications that use [authorization code flow](../../active-directory/azuread-dev/v1-protocols-oauth-code.md) to obtain a token on behalf of a signed in user presenting valid credentials. They're called confidential clients because they're able to hold a secret and will present this secret to Azure AD when exchanging the authentication code for a token. Since confidential clients are able to authenticate themselves using the client secret, they're trusted more than public clients and can have longer lived tokens and be granted a refresh token. Read the details on how to [register a confidential client](register-confidential-azure-ad-client-app.md). Note it's important to register the reply URL at which the client will be receiving the authorization code.

+1. **Public clients**. These are clients that canΓÇÖt keep a secret. Typically this would be a mobile device application or a single page JavaScript application, where a secret in the client could be discovered by a user. Public clients also use authorization code flow, but they aren't allowed to present a secret when obtaining a token and they may have shorter lived tokens and no refresh token. Read the details on how to [register a public client](register-public-azure-ad-client-app.md).

+1. Service clients. These clients obtain tokens on behalf of themselves (not on behalf of a user) using the [client credentials flow](../../active-directory/azuread-dev/v1-oauth2-client-creds-grant-flow.md). They typically represent applications that access the FHIR server in a non-interactive way. An example would be an ingestion process. When using a service client, it isn't necessary to start the process of getting a token with a call to the `/authorize` endpoint. A service client can go straight to the `/token` endpoint and present client ID and client secret to obtain a token. Read the details on how to [register a service client](register-service-azure-ad-client-app.md)

+Once you've registered your applications, you can deploy the Azure API for FHIR.

+| patch | Yes | Yes | Support for [JSON Patch](https://www.hl7.org/fhir/http.html#patch) only. We've included a workaround to use JSON Patch in a bundle in [this PR](https://github.com/microsoft/fhir-server/pull/2143).|

+| patch (conditional) | Yes | Yes | Support for [JSON Patch](https://www.hl7.org/fhir/http.html#patch) only. We've included a workaround to use JSON Patch in a bundle in [this PR](https://github.com/microsoft/fhir-server/pull/2143).

+* [**Request Units (RUs)**](../../cosmos-db/concepts-limits.md) - You can configure up to 10,000 RUs in the portal for Azure API for FHIR. You'll need a minimum of 400 RUs or 40 RUs/GB, whichever is larger. If you need more than 10,000 RUs, you can put in a support ticket to have the RUs increased. The maximum available is 1,000,000. In addition, we support [autoscaling of RUs](autoscale-azure-api-fhir.md).

+We have many open-source projects on GitHub that provide you the source code and instructions to deploy services for various uses. You're always welcome to visit our GitHub repositories to learn and experiment with our features and products.

+* To see the latest releases, refer to the [Release Notes](https://github.com/microsoft/fhir-server/releases)

+* [microsoft/FHIR-Converter](https://github.com/microsoft/FHIR-Converter): a data conversion project that uses CLI tool and $convert-data FHIR endpoint to translate healthcare legacy data formats into FHIR

+* Integrated with the FHIR service and FHIR server for Azure in the form of $convert-data operation

+* [microsoft/vscode-azurehealthcareapis-tools](https://github.com/microsoft/vscode-azurehealthcareapis-tools): a VS Code extension that contains a collection of tools to work with FHIR Converter

+* Released to Visual Studio Marketplace, you can install it here: [FHIR Converter VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-health-fhir-converter)

+* Used for authoring Liquid conversion templates and managing templates on Azure Container Registry

+* [microsoft/Tools-for-Health-Data-Anonymization](https://github.com/microsoft/Tools-for-Health-Data-Anonymization): a data anonymization project that provides tools for de-identifying FHIR data and DICOM data

+* Integrated with the FHIR service and FHIR server for Azure in the form of `de-identified $export` operation

+* For FHIR data, it can also be used with Azure Data Factory (ADF) pipeline by reading FHIR data from Azure blob storage and writing back the anonymized data

+## MedTech service

+* [Tools to help build the conversation map](https://github.com/microsoft/iomt-fhir/tree/master/tools/data-mapper): visualize the mapping configuration for normalizing the device input data and transform it to the FHIR resources. Developers can use this tool to edit and test the mappings, device mapping and FHIR mapping, and export them for uploading to the MedTech service in the Azure portal.

+ ## Next steps

+In this article, you've learned about the related GitHub Projects for Azure API for FHIR that provide source code and instructions to let you experiment and deploy services for various uses. For more information about Azure API for FHIR, see

+

+>[!div class="nextstepaction"]

+>[What is Azure API for FHIR?](overview.md)

+Open the [Azure portal](https://portal.azure.com) and select **Create a resource**

+Select an existing resource group or create a new one, choose a name for the account, and finally select **Review + create**:

+You can also select **Next: Additional settings** to view the authentication settings. The default configuration for the Azure API for FHIR is to [use Azure RBAC for assigning data plane roles](configure-azure-rbac.md). When configured in this mode, the "Authority" for the FHIR service will be set to the Azure Active Directory tenant of the subscription:

+If the `Microsoft.HealthcareApis` resource provider isn't already registered for your subscription, you can register it with:

+Azure API for FHIR offers two delete types. There's [Delete](https://www.hl7.org/fhir/http.html#delete), which is also know as Hard + Soft Delete, and [Conditional Delete](https://www.hl7.org/fhir/http.html#3.1.0.7.1).

+If the ID of the resource isn't known, do a history search on the entire resource type:

+Within Patch, there's a test operation that allows you to validate that a condition is true before doing the patch. For example, if you wanted to set a patient deceased, only if they weren't already marked as deceased, you could use the example below:

+By default, JSON Patch isn't supported in Bundle resources. This is because a Bundle only supports with FHIR resources and JSON Patch isn't a FHIR resource. To work around this, we'll treat Binary resources with a content-type of `"application/json-patch+json"`as base64 encoding of JSON string when a Bundle is executed. For information about this workaround, log in to [Zulip](https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Transaction.20with.20PATCH.20request).

+In the example below, we want to change the gender on the patient to female. We've taken the JSON patch `[{"op":"replace","path":"/gender","value":"female"}]` and encoded it to base64.

+Suppose you've registered a [service client app](register-service-azure-ad-client-app.md) and you would like to allow this service client to access the Azure API for FHIR, you can find the object ID for the client service principal with the following PowerShell command:

+If you're using the Azure CLI, you can use:

+Where `mygroup` is the name of the group you're interested in.

+If you're using the Azure CLI, you can use:

+* **type**: Describes the data type for the search parameter. Type is limited by the support for the Azure API for FHIR. This means that you canΓÇÖt define a search parameter of type Special or define a [composite search parameter](overview-of-search.md) unless it's a supported combination.

+* **expression**: Describes how to calculate the value for the search. When describing a search parameter, you must include the expression, even though it isn't required by the specification. This is because you need either the expression or the xpath syntax and the Azure API for FHIR ignores the xpath syntax.

+While you canΓÇÖt use the search parameters in production until you run a reindex job, there are a few ways to test your search parameters before reindexing the entire database.

+First, you can test your new search parameter to see what values will be returned. By running the command below against a specific resource instance (by inputting their ID), you'll get back a list of value pairs with the search parameter name and the value stored for the specific patient. This will include all of the search parameters for the resource and you can scroll through to find the search parameter you created. Running this command won't change any behavior in your FHIR server.

+Once you see that your search parameter is displaying as expected, you can reindex a single resource to test searching with the element. First you'll reindex a single resource:

+description: This article describes how to run a reindex job to index any search or sort parameters that haven't yet been indexed in your database.

+There are scenarios where you may have search or sort parameters in the Azure API for FHIR that haven't yet been indexed. This scenario is relevant when you define your own search parameters. Until the search parameter is indexed, it can't be used in search. This article covers an overview of how to run a reindex job to index any search or sort parameters that haven't yet been indexed in your database.

+For more information about how to create device and FHIR mapping templates, see

+On the left-hand navigation menu, select **IoT Connector (preview)** under the **Add-ins** section to open the **IoT Connectors** page.

+Select the **Add** button to open the **Create IoT Connector** page.

+Enter settings for the new Azure IoT Connector for FHIR. Select the **Create** button and await Azure IoT Connector for FHIR deployment.

+|Resolution type|Look up or Create|Select **Lookup** if you have an out-of-band process to create [Device](https://www.hl7.org/fhir/device.html) and [Patient](https://www.hl7.org/fhir/patient.html) FHIR resources in your Azure API for FHIR. Azure IoT Connector for FHIR will use reference to these resources when creating an [Observation](https://www.hl7.org/fhir/observation.html) FHIR resource to represent the device data. Select **Create** when you want Azure IoT Connector for FHIR to create bare-bones Device and Patient resources in your Azure API for FHIR using respective identifier values present in the device data.|

+To upload mapping templates, select the newly deployed Azure IoT Connector for FHIR to go to the **IoT Connector** page.

+On the **Device mapping** page, add the following script to the JSON editor and select **Save**.

+FHIR mapping template transforms a normalized message to a FHIR-based Observation resource. On the **IoT Connector** page, select the **Configure FHIR mapping** button to browse to the **FHIR mapping** page.

+[](media/quickstart-iot-fhir-portal/portal-iot-connector-click-fhir-mapping.jpg#lightbox)

+On the **FHIR mapping** page, add the following script to the JSON editor and select **Save**.

+On the **Connections** page, select the **Add** button to create a new connection.

+To directly remove an Azure IoT Connector for FHIR instance, select the instance from **IoT Connectors** page to browse to the **IoT Connector** page and select the **Delete** button. Select **Yes** when asked for confirmation.

+|**Values[].Required**|Will require the value to be present in the payload. If not found, a measurement won't be generated and an InvalidOperationException will be thrown.|`true`

+|Move resource isn't supported for IoT Connector enabled Azure API for FHIR resource.|API and Azure portal|Attempting to do a move operation on an Azure API for FHIR resource that has one or more instances of the Azure IoT Connector for FHIR.|Delete existing instance(s) of Azure IoT Connector for FHIR to do the move operation.|

+|The request isn't supported.|API|Specific API request isn't supported.|Use the correct API request.|

+|Account doesn't exist.|API|Attempting to add an Azure IoT Connector for FHIR and the Azure API for FHIR resource doesn't exist.|Create the Azure API for FHIR resource and then reattempt the operation.|

+|Azure API for FHIR resource FHIR version isn't supported for IoT Connector.|API|Attempting to use an Azure IoT Connector for FHIR with an incompatible version of the Azure API for FHIR resource.|Create a new Azure API for FHIR resource (version R4) or use an existing Azure API for FHIR resource (version R4).

+|FHIR conversion mapping JSON hasn't been configured.|Configure and save conforming FHIR conversion mapping JSON.|

+|A Patient Resource hasn't been created in the Azure API for FHIR (Resolution Type: Lookup only)*.|Create a valid Patient Resource in the Azure API for FHIR.|

+Azure IoT Connector for FHIR generates multiple metrics to provide insights into the data flow process. One of the supported metrics is called *Total Errors, which provide the count for all errors that occur within an instance of Azure IoT Connector for FHIR.

+Select on the *Total Errors* graph and then select the **Add filter** button to slice and dice the error metric using any of the properties mentioned below.

+This property represents the operation being performed by IoT Connector when the error has occurred. An operation generally represents the data flow stage while processing a device message. Here's the list of possible values for this property.

+This property represents the severity of the occurred error. Here's the list of possible values for this property.

+This property signifies a category for a given error, which basically represents a logical grouping for similar type of errors. Here's the list of possible value for this property.

+This property provides the name for a specific error. Here's the list of all error names with their description and associated error type(s), severity, and data flow stage(s).

+The FHIR specification defines the fundamentals of search for FHIR resources. This article will guide you through some key aspects to searching resources in FHIR. For complete details about searching FHIR resources, refer to [Search](https://www.hl7.org/fhir/search.html) in the HL7 FHIR Specification. Throughout this article, we'll give examples of search syntax. Each search will be against your FHIR server, which typically has a URL of `https://<FHIRSERVERNAME>.azurewebsites.net`. In the examples, we'll use the placeholder {{FHIR_URL}} for this URL.

+| **Search parameter type** | **Azure API for FHIR** | **FHIR service in Azure Health Data Services** | **Comment**|

+| **Common search parameter** | **Azure API for FHIR** | **FHIR service in Azure Health Data Services** | **Comment**|

+| **Modifiers** | **Azure API for FHIR** | **FHIR service in Azure Health Data Services** | **Comment**|

+| **Search result parameters** | **Azure API for FHIR** | **FHIR service in Azure Health Data Services** | **Comment**|

+| _include | Yes | Yes | Included items are limited to 100. _include on PaaS and OSS on Cosmos DB don't include :iterate support [(#2137)](https://github.com/microsoft/fhir-server/issues/2137). |

+| _revinclude | Yes | Yes |Included items are limited to 100. _revinclude on PaaS and OSS on Cosmos DB don't include :iterate support [(#2137)](https://github.com/microsoft/fhir-server/issues/2137). There's also an incorrect status code for a bad request [#1319](https://github.com/microsoft/fhir-server/issues/1319) |

+| _sort | Partial | Partial | sort=_lastUpdated is supported on Azure API for FHIR and the FHIR service. For Azure API for FHIR and OSS Cosmos DB databases created after April 20, 2021, sort is supported on first name, last name, birthdate, and clinical date. Note there's an open issue using _sort with chained search, which is documented in open-source issue [#2344](https://github.com/microsoft/fhir-server/issues/2344). |

+You control your data. Role-based access control (RBAC) enables you to manage how your data is stored and accessed. Providing increased security and reducing administrative workload, you determine who has access to the datasets you create, based on role definitions you create for your environment.

+Protect your PHI with unparalleled security intelligence. Your data is isolated to a unique database per API instance and protected with multi-region failover. The Azure API for FHIR implements a layered, in-depth defense and advanced threat protection for your data.

+FHIR servers are key tools for interoperability of health data. The Azure API for FHIR is designed as an API and service that you can create, deploy, and begin using quickly. As the FHIR standard expands in healthcare, use cases will continue to grow, but some initial customer applications where Azure API for FHIR is useful are below:

+- **Startup/IoT and App Development:** Customers developing a patient or provider centric app (mobile or web) can leverage Azure API for FHIR as a fully managed backend service. The Azure API for FHIR provides a valuable resource in that customers can manage data and exchange data in a secure cloud environment designed for health data, leverage SMART on FHIR implementation guidelines, and enable their technology to be utilized by all provider systems (for example, most EHRs have enabled FHIR read APIs).

+- **Healthcare Ecosystems:** While EHRs exist as the primary ΓÇÿsource of truthΓÇÖ in many clinical settings, it isn't uncommon for providers to have multiple databases that arenΓÇÖt connected to one another or store data in different formats. Utilizing the Azure API for FHIR as a service that sits on top of those systems allows you to standardize data in the FHIR format. This helps to enable data exchange across multiple systems with a consistent data format.

+For use cases that require extending or customizing the FHIR server, or requires access to the underlying servicesΓÇösuch as the databaseΓÇöwithout going through the FHIR APIs, developers should choose the open-source FHIR Server for Azure. For implementation of a turn-key, production-ready FHIR API and backend service where persisted data should only be accessed through the FHIR API, developers should choose the Azure API for FHIR.

+To try out the Azure IoT Connector for FHIR feature, check out the quickstart to deploy Azure IoT Connector for FHIR using the Azure portal.

+1. In the [Azure portal](https://portal.azure.com), on the left navigation panel, select **Azure Active Directory**.

+2. In the **Azure Active Directory** blade, select **App registrations**:

+3. Select **New registration**.

+If the application you registered in this article and your FHIR server are in the same Azure AD tenant, you're good to proceed to the next steps.

+If you configure your client application in a different Azure AD tenant from your FHIR server, you'll need to update the **Authority**. In Azure API for FHIR, you do set the Authority under Settings --> Authentication. Set your Authority to ``https://login.microsoftonline.com/\<TENANT-ID>`.

+If you're using the Azure API for FHIR, a resource application is automatically created when you deploy the service. As long as you're using the Azure API for FHIR in the same Azure Active Directory tenant as you're deploying your application, you can skip this how-to-guide and instead deploy your Azure API for FHIR to get started.

+If you're using a different Azure Active Directory tenant (not associated with your subscription), you can import the Azure API for FHIR resource application into your tenant with

+If you're using the open source FHIR Server for Azure, follow the steps on the [GitHub repo](https://github.com/microsoft/fhir-server/blob/master/docs/Register-Resource-Application.md) to register a resource application.

+4. Give the service client a display name. Service client applications typically don't use a reply URL.

+3. Provide a description and duration of the secret (either one year, two years or never).

+4. Once the secret has been generated, it will only be displayed once in the portal. Make a note of it and store in a secure location.

+`:not` allows you to find resources where an attribute isn't true. For example, you could search for patients where the gender isn't female:

+As a return value, you would get all patient entries where the gender isn't female, including empty values (entries specified without gender). This is different than searching for Patients where gender is male, since that wouldn't include the entries without a specific gender.

+This request returns `Patient` resources that have the name exactly the same as `Jon`. If the resource had Patients with names such as `Jonathan` or `joN`, the search would ignore and skip the resource as it doesn't exactly match the specified value.

+Using chained search, you can find all the `Encounter` resources that match a particular piece of `Patient` information, such as the `birthdate`:

+When a resource conforms to a profile, the profile is specified inside the `profile` element of the resource. Below you can see an example of the beginning of a 'Patient' resource, which has http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient profile.

+For example, if you'd like to store the `us-core-allergyintolerance` profile, you'd use the following rest command with the US Core allergy intolerance profile in the body. We've included a snippet of this profile for the example.

+For more examples, see the [US Core sample REST file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/PayerDataExchange/USCore.http) on the open-source site that walks through storing US Core profiles. To get the most up to date profiles, you should get the profiles directly from HL7 and the implementation guide that defines them.

+Azure API for FHIR doesn't return `StructureDefinition` instances for the base profiles, but they can be found in the HL7 website, such as:

+In this tutorial, you'll deploy a small JavaScript app, which reads data from a FHIR service. The steps in this tutorial are:

+Before starting this set of tutorials, you'll need the following items:

+Now that you have your Azure API for FHIR deployed, you're ready to register a public client application.

+ Title: Grant permissions to users and client applications using CLI and REST API - Azure Health Data Services

+# Configure Azure RBAC role Using Azure CLI and REST API

+In this article, you'll learn how to grant permissions to client applications (and users) to access Azure Health Data Services using Azure Command-Line Interface (CLI) and REST API. This step is referred to as "role assignment" or Azure

+[role-based access control (Azure RBAC role)](./../role-based-access-control/role-assignments-cli.md). To further your understanding about the application roles defined for Azure Health Data Services, see [Configure Azure RBAC role](configure-azure-rbac.md).

+### Azure Health Data Services role assignment

+The role assignments for Azure Health Data Services require the following values.

+- Scope for the role assignment, that is, the Azure Health Data Services service instance. It includes subscription, resource group, workspace name, and FHIR or DICOM service name. You can use the absolute or relative URL for the scope. Note that "/" isnΓÇÖt added at the beginning of the relative URL.

+You can verify the role assignment status from the command-line response or in the Azure portal.

+Role assignments for Azure API for FHIR work similarly. The difference is that the scope contains the FHIR service only and the workspace name isnΓÇÖt required.

+- Scope for Azure Health Data Services to which you grant access permissions. It includes subscription ID, resource group name, and the FHIR or DICOM service instance name.

+@roleapiversion=2021-04-01

+@roleapiversion=2021-04-01

+## List service instances of Azure Health Data Services

+Optionally, you can get a list of Azure Health Data Services services, or Azure API for FHIR. Note that the API version is based on Azure Health Data Services, not the version for the role assignment REST API.

+For Azure Health Data Services, specify the subscription ID, resource group name, workspace name, FHIR or DICOM services, and the API version.

+@apiversion=2021-06-01

+@apiversion=2021-06-01

+Now that you've granted proper permissions to the client application, you can access Azure Health Data Services in your applications.

+In this article, you learned how to grant permissions to client applications using Azure CLI and REST API. For information on how to access Azure Health Data Services using the REST Client Extension in Visual Studio Code, see

+>[Access using REST Client](./fhir/using-rest-client.md)

+ Title: Configure Azure RBAC role for FHIR service - Azure Health Data Services

+description: This article describes how to configure Azure RBAC role for FHIR.

+# Configure Azure RBAC role for Azure Health Data Services

+In this article, you'll learn how to use [Azure role-based access control (Azure RBAC role)](../role-based-access-control/index.yml) to assign access to the Azure Health Data Services data plane. Azure RBAC role is the preferred methods for assigning data plane access when data plane users are managed in the Azure Active Directory tenant associated with your Azure subscription.

+* **FHIR Data Converter**: Can use the converter to perform data conversion.

+If the client application isnΓÇÖt found, check your application registration. This is to ensure that the name is correct. Ensure that the client application is created in the same tenant where the FHIR service in Azure Health Data Services (hereby called the FHIR service) is deployed in.

+If these roles arenΓÇÖt sufficient for your need, you can use PowerShell to create custom roles. For information about creating custom roles, see [Create a custom role using Azure PowerShell](../role-based-access-control/custom-roles-powershell.md).

+In this article, you've learned how to assign Azure roles for the FHIR service and DICOM service. To learn how to access the Azure Health Data Services using Postman, see

+ Title: How to create Azure Health Data Services, workspaces, FHIR and DICOM service, and IoT connectors using Azure Bicep

+description: This document describes how to deploy Azure Health Data Services using Azure Bicep.

+# Deploy Azure Health Data Services Using Azure Bicep

+In this article, you'll learn how to create Azure Health Data Services, including workspaces, FHIR services, DICOM services, and IoT connectors using Azure Bicep. You can view and download the Bicep scripts used in this article in [HealthcareAPIs samples](https://github.com/microsoft/healthcare-apis-samples/blob/main/src/templates/healthcareapis.bicep).

+To use or reference an existing workspace without creating one, use the keyword *existing*. Specify the workspace resource name, and the existing workspace instance name for the name property. Note that a different name for the existing workspace resource is used in the template, but that isn't a requirement.

+Note that the child resource name such as the FHIR service includes the parent resource name, and the "dependsOn" property is required. However, when the child resource is created within the parent resource, its name doesn't need to include the parent resource name, and the "dependsOn" property isn't required. For more info on nested resources, see [Set name and type for child resources in Bicep](../azure-resource-manager/bicep/child-resource-name-type.md).

+In this article, you learned how to create Azure Health Data Services, including workspaces, FHIR services, DICOM services, and IoT connectors using Bicep. You also learned how to create and debug Bicep templates. For more information about Azure Health Data Services, see

+>[What is Azure Health Data Services](healthcare-apis-overview.md)

+ Title: API Versioning for DICOM service - Azure Health Data Services

+Currently routes without a version are still supported. For example, `<service_url>/studies` has the same behavior as specifying the version as v1.0-prerelease. However, we strongly recommend that you specify the version in all requests via the URL as routes without a version won't be supported after the General Availability release of the DICOM service.

+* v1

+An API version with the label "prerelease" indicates that the version isn't ready for production, and it should only be used in testing environments. These endpoints may experience breaking changes without notice.

+We currently only increment the major version whenever there's a breaking change, which is considered to be not backwards compatible.

+Non-breaking changes (Version isn't incremented):

+ReportApiVersions is turned on, which means we'll return the headers api-supported-versions and api-deprecated-versions when appropriate.

+```

+[ApiVersion("1")]

+[ApiVersion("1.0-prerelease", Deprecated = true)]

+```

+[  ](media/api-supported-deprecated-versions.png#lightbox)

+## Next steps

+In this article, you learned about the API version policies for the DICOM service. For more information about the DICOM service, see

+>[!div class="nextstepaction"]

+>[Overview of the DICOM service](dicom-services-overview.md)

+ Title: Deploy DICOM service using the Azure portal - Azure Health Data Services

+description: This article describes how to deploy DICOM service in the Azure portal.

+In this quickstart, you'll learn how to deploy DICOM Service using the Azure portal.

+To deploy DICOM service, you must have a workspace created in the Azure portal. For more information about creating a workspace, see **Deploy Workspace in the Azure portal**.

+1. On the **Resource group** page of the Azure portal, select the name of your **Azure Health Data Services Workspace**.

+ [  ](media/select-workspace-resource-group.png#lightbox)

+ [  ](media/workspace-deploy-dicom-services.png#lightbox)

+ [  ](media/add-dicom-service.png#lightbox)

+4. Enter a name for DICOM service, and then select **Review + create**.

+ [  ](media/enter-dicom-service-name.png#lightbox)

+5. When you notice the green validation check mark, select **Create** to deploy DICOM service.

+ [  ](media/go-to-resource.png#lightbox)

+ The result of the newly deployed DICOM service is shown below.

+ [  ](media/results-deployed-dicom-service.png#lightbox)

+## Next steps

+In this quickstart, you learned how to deploy DICOM service using the Azure portal. For information about assigning roles for the DICOM service, see

+>[!div class="nextstepaction"]

+>[Assign roles for the DICOM service](https://docs.microsoft.com/azure/healthcare-apis/configure-azure-rbac#assign-roles-for-the-dicom-service)

+For more information about how to use the DICOMweb&trade; Standard APIs with the DICOM service, see

+>[Using DICOMweb&trade;Standard APIs with DICOM services](dicomweb-standard-apis-with-dicom-services.md)

+ Title: DICOM access request reference guide - Azure Health Data Services

+description: This reference guide provides information about to create an Azure support ticket to request DICOM cast access.

+# DICOM cast access request

+This article describes how to request DICOM cast access.

+## Create Azure support ticket

+To enable DICOM cast for your Azure subscription, please request access for DICOM cast by opening an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/).

+> [!IMPORTANT]

+> Ensure that you include the **resource IDs** of your DICOM service and FHIR service when you submit a support ticket.

+### Basics tab

+1. In the **Summary** field, enter "Access request for DICOM cast".

+

+ [  ](media/new-support-request-basic-tab.png#lightbox)

+1. Select the **Issue type** drop-down list, and then select **Technical**.

+1. Select the **Subscription** drop-down list, and then select your Azure subscription.

+1. Select the **Service type** drop-down list, and then select **Azure Health Data Services**.

+1. Select the **Resource** drop-down list, and then select your resource.

+1. Select the **Problem** drop-down list, and then select **DICOM service**.

+1. Select the **Problem subtype** drop-down list, and then select **About the DICOM service**.

+1. Select **Next Solutions**.

+1. From the **Solutions** tab, select **Next Details**.

+### Details tab

+1. Under the **Problem details** section, select today's date to submit your support request. You may keep the default time as 12:00AM.

+ [  ](media/new-support-request-details-tab.png#lightbox)

+1. In the **Description** box, ensure to include the Resource IDs of your FHIR service and DICOM service.

+ > [!NOTE]

+ > To obtain your DICOM service and FHIR service resource IDs, select your DICOM service instance in the Azure portal, and select the **Properties** blade that's listed under **Settings**.

+1. File upload isn't required, so you may omit this option.

+1. Under the **Support method** section, select the **Severity** and the **Preferred contact method** options.

+1. Select **Next: Review + Create >>**.

+1. In the **Review + create** tab, select **Create** to submit your Azure support ticket.

+## Next steps

+This article described the steps for creating an Azure support ticket to request DICOM cast access. For more information about using the DICOM service, see

+>[!div class="nextstepaction"]

+>[Deploy DICOM service to Azure](deploy-dicom-services-in-azure.md)

+For more information about DICOM cast, see

+>[!div class="nextstepaction"]

+>[DICOM cast overview](dicom-cast-overview.md)

+ Title: DICOM cast overview - Azure Health Data Services

+description: In this article, you'll learn the concepts of DICOM cast.

+# DICOM cast overview

+DICOM cast offers customers the ability to synchronize the data from a DICOM service to a [FHIR service](../../healthcare-apis/fhir/overview.md), which allows healthcare organizations to integrate clinical and imaging data. DICOM cast expands the use cases for health data by supporting both a streamlined view of longitudinal patient data and the ability to effectively create cohorts for medical studies, analytics, and machine learning.

+## Architecture

+[  ](media/dicom-cast-architecture.png#lightbox)

+1. **Poll for batch of changes**: DICOM cast polls for any changes via the [Change Feed](dicom-change-feed-overview.md), which captures any changes that occur in your Medical Imaging Server for DICOM.

+1. **Fetch corresponding FHIR resources, if any**: If any DICOM service changes and correspond to FHIR resources, DICOM cast will fetch the related FHIR resources. DICOM cast synchronizes DICOM tags to the FHIR resource types *Patient* and *ImagingStudy*.

+1. **Merge FHIR resources and 'PUT' as a bundle in a transaction**: The FHIR resources corresponding to the DICOM cast captured changes will be merged. The FHIR resources will be 'PUT' as a bundle in a transaction into your FHIR service.

+1. **Persist state and process next batch**: DICOM cast will then persist the current state to prepare for next batch of changes.

+The current implementation of DICOM cast:

+- Supports a single-threaded process that reads from the DICOM change feed and writes to a FHIR service.

+- Is hosted by Azure Container Instance in our sample template, but can be run elsewhere.

+- Synchronizes DICOM tags to *Patient* and *ImagingStudy* FHIR resource types*.

+- Is configurated to ignore invalid tags when syncing data from the change feed to FHIR resource types.

+ - If `EnforceValidationOfTagValues` is enabled, then the change feed entry won't be written to the FHIR service unless every tag that's mapped is valid. For more information, see the [Mappings](#mappings) section below.

+ - If `EnforceValidationOfTagValues` is disabled (default), and if a value is invalid, but it's not required to be mapped, then that particular tag won't be mapped. The rest of the change feed entry will be mapped to FHIR resources. If a required tag is invalid, then the change feed entry won't be written to the FHIR service. For more information about the required tags, see [Patient](#patient) and [Imaging Study](#imagingstudy)

+- Logs errors to Azure Table Storage.

+ - Errors occur when processing change feed entries that are persisted in Azure Table storage that are in different tables.

+ - `InvalidDicomTagExceptionTable`: Stores information about tags with invalid values. Entries here don't necessarily mean that the entire change feed entry wasn't stored in FHIR service, but that the particular value had a validation issue.

+ - `DicomFailToStoreExceptionTable`: Stores information about change feed entries that weren't stored to FHIR service due to an issue with the change feed entry (such as invalid required tag). All entries in this table weren't stored to FHIR service.

+ - `FhirFailToStoreExceptionTable`: Stores information about change feed entries that weren't stored to FHIR service due to an issue with the FHIR service (such as conflicting resource already exists). All entries in this table weren't stored to FHIR service.

+ - `TransientRetryExceptionTable`: Stores information about change feed entries that faced a transient error (such as FHIR service too busy) and are being retried. Entries in this table note how many times they've been retried, but it doesn't necessarily mean that they eventually failed or succeeded to store to FHIR service.

+ - `TransientFailureExceptionTable`: Stores information about change feed entries that had a transient error, and went through the retry policy and still failed to store to FHIR service. All entries in this table failed to store to FHIR service.

+## Mappings

+The current implementation of DICOM cast has the following mappings:

+### Patient

+| Property | Tag ID | Tag Name | Required Tag?| Note |

+| :- | :-- | :- | :-- | :-- |

+| Patient.identifier.where(system = '') | (0010,0020) | PatientID | Yes | For now, the system will be empty string. We'll add support later for allowing the system to be specified. |

+| Patient.name.where(use = 'usual') | (0010,0010) | PatientName | No | PatientName will be split into components and added as HumanName to the Patient resource. |

+| Patient.gender | (0010,0040) | PatientSex | No | |

+| Patient.birthDate | (0010,0030) | PatientBirthDate | No | PatientBirthDate only contains the date. This implementation assumes that the FHIR and DICOM services have data from the same time zone. |

+### Endpoint

+| Property | Tag ID | Tag Name | Note |

+| :- | :-- | :- | : |

+| Endpoint.status ||| The value 'active' will be used when creating the endpoint. |

+| Endpoint.connectionType ||| The system 'http://terminology.hl7.org/CodeSystem/endpoint-connection-type' and value 'dicom-wado-rs' will be used when creating the endpoint. |

+| Endpoint.address ||| The root URL to the DICOMWeb service will be used when creating the endpoint. The rule is described in 'http://hl7.org/fhir/imagingstudy.html#endpoint'. |

+### ImagingStudy

+| Property | Tag ID | Tag Name | Required | Note |

+| :- | :-- | :- | : | : |

+| ImagingStudy.identifier.where(system = 'urn:dicom:uid') | (0020,000D) | StudyInstanceUID | Yes | The value will have prefix of `urn:oid:`. |

+| ImagingStudy.status | | | No | The value 'available' will be used when creating ImagingStudy. |

+| ImagingStudy.modality | (0008,0060) | Modality | No | |

+| ImagingStudy.subject | | | No | It will be linked to the [Patient](#mappings). |

+| ImagingStudy.started | (0008,0020), (0008,0030), (0008,0201) | StudyDate, StudyTime, TimezoneOffsetFromUTC | No | Refer to the section for details about how the [timestamp](#timestamp) is constructed. |

+| ImagingStudy.endpoint | | | | It will be linked to the [Endpoint](#endpoint). |

+| ImagingStudy.note | (0008,1030) | StudyDescription | No | |

+| ImagingStudy.series.uid | (0020,000E) | SeriesInstanceUID | Yes | |

+| ImagingStudy.series.number | (0020,0011) | SeriesNumber | No | |

+| ImagingStudy.series.modality | (0008,0060) | Modality | Yes | |

+| ImagingStudy.series.description | (0008,103E) | SeriesDescription | No | |

+| ImagingStudy.series.started | (0008,0021), (0008,0031), (0008,0201) | SeriesDate, SeriesTime, TimezoneOffsetFromUTC | No | Refer to the section for details about how the [timestamp](#timestamp) is constructed. |

+| ImagingStudy.series.instance.uid | (0008,0018) | SOPInstanceUID | Yes | |

+| ImagingStudy.series.instance.sopClass | (0008,0016) | SOPClassUID | Yes | |

+| ImagingStudy.series.instance.number | (0020,0013) | InstanceNumber | No| |

+| ImagingStudy.identifier.where(type.coding.system='http://terminology.hl7.org/CodeSystem/v2-0203' and type.coding.code='ACSN')) | (0008,0050) | Accession Number | No | Refer to http://hl7.org/fhir/imagingstudy.html#notes. |

+### Timestamp

+DICOM has different date time VR types. Some tags (like Study and Series) have the date, time, and UTC offset stored separately. This means that the date might be partial. This code attempts to translate this into a partial date syntax allowed by the FHIR service.

+## Summary

+In this concept, we reviewed the architecture and mappings of DICOM cast. This feature is available on demand. To enable DICOM cast for your Azure subscription, please request access for DICOM cast by opening an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/). For more information about requesting access to DICOM cast, see [DICOM cast request access](dicom-cast-access-request.md).

+> [!IMPORTANT]

+> Ensure that you include the **resource IDs** of your DICOM service and FHIR service when you submit a support ticket.

+

+## Next steps

+To get started using the DICOM service, see

+>[!div class="nextstepaction"]

+>[Deploy DICOM service to Azure](deploy-dicom-services-in-azure.md)

+>[!div class="nextstepaction"]

+>[Using DICOMweb&trade;Standard APIs with DICOM service](dicomweb-standard-apis-with-dicom-services.md)

+ Title: Overview of DICOM Change Feed - Azure Health Data Services

+The Change Feed provides logs of all the changes that occur in DICOM service. The Change Feed provides ordered, guaranteed, immutable, and read-only logs of these changes. The Change Feed offers the ability to go through the history of DICOM service and acts upon the creates and deletes in the service.

+Below is the usage flow for an example application that does other processing on the instances within DICOM service.

+ Title: Configure Azure RBAC for the DICOM service - Azure Health Data Services

+In this article, you'll learn how to use [Azure role-based access control (Azure RBAC)](../../role-based-access-control/index.yml) to assign access to the DICOM service.

+[  ](media/dicom-access-control.png#lightbox)

+[  ](media/rbac-add-role-assignment.png#lightbox)

+If these roles aren't sufficient for your need, you can use PowerShell to create custom roles. For information about creating custom roles, see [Create a custom role using Azure PowerShell](../../role-based-access-control/tutorial-custom-role-powershell.md).

+ Title: DICOM extended query tags overview - Azure Healthcare APIs

+description: In this article, you'll learn the concepts of Extended Query Tags.

+# Extended query tags

+## Overview

+By default, the DICOM service supports querying on the DICOM tags specified in the [conformance statement](dicom-services-conformance-statement.md#searchable-attributes). By enabling extended query tags, the list of tags can easily be expanded based on the application's needs.

+Using the APIs listed below, users can index their DICOM studies, series, and instances on both standard and private DICOM tags such that they can be specified in QIDO-RS queries.

+## APIs

+### Version: v1

+To help manage the supported tags in a given DICOM service instance, the following API endpoints have been added.

+| API | Description |

+| - | |

+| POST .../extendedquerytags | [Add Extended Query Tags](#add-extended-query-tags) |

+| GET .../extendedquerytags | [List Extended Query Tags](#list-extended-query-tags) |

+| GET .../extendedquerytags/{tagPath} | [Get Extended Query Tag](#get-extended-query-tag) |

+| DELETE .../extendedquerytags/{tagPath} | [Delete Extended Query Tag](#delete-extended-query-tag) |

+| PATCH .../extendedquerytags/{tagPath} | [Update Extended Query Tag](#update-extended-query-tag) |

+| GET .../extendedquerytags/{tagPath}/errors | [List Extended Query Tag Errors](#list-extended-query-tag-errors) |

+| GET .../operations/{operationId} | [Get Operation](#get-operation) |

+### Add extended query tags

+Adds one or more extended query tags and starts a long-running operation that reindexes current DICOM instances with the specified tag(s).

+```http

+POST .../extendedquerytags

+```

+#### Request header

+| Name | Required | Type | Description |

+| | -- | | - |

+| Content-Type | True | string | `application/json` is supported |

+#### Request body

+| Name | Required | Type | Description |

+| - | -- | | -- |

+| body | | [Extended Query Tag for Adding](#extended-query-tag-for-adding)`[]` | |

+#### Limitations

+The following VR types are supported:

+| VR | Description | Single Value Matching | Range Matching | Fuzzy Matching |

+| - | | | -- | -- |

+| AE | Application Entity | X | | |

+| AS | Age String | X | | |

+| CS | Code String | X | | |

+| DA | Date | X | X | |

+| DS | Decimal String | X | | |

+| DT | Date Time | X | X | |

+| FD | Floating Point Double | X | | |

+| FL | Floating Point Single | X | | |

+| IS | Integer String | X | | |

+| LO | Long String | X | | |

+| PN | Person Name | X | | X |

+| SH | Short String | X | | |

+| SL | Signed Long | X | | |

+| SS | Signed Short | X | | |

+| TM | Time | X | X | |

+| UI | Unique Identifier | X | | |

+| UL | Unsigned Long | X | | |

+| US | Unsigned Short | X | | |

+> [!NOTE]

+> Sequential tags, which are tags under a tag of type Sequence of Items (SQ), are currently not supported.

+> You can add up to 128 extended query tags.

+#### Responses

+| Name | Type | Description |

+| -- | - | |

+| 202 (Accepted) | [Operation Reference](#operation-reference) | Extended query tag(s) have been added, and a long-running operation has been started to reindex existing DICOM instances |

+| 400 (Bad Request) | | Request body has invalid data |

+| 409 (Conflict) | | One or more requested query tags already are supported |

+### List extended query tags

+Lists of all extended query tag(s).

+```http

+GET .../extendedquerytags

+```

+#### Responses

+| Name | Type | Description |

+| -- | | |

+| 200 (OK) | [Extended Query Tag](#extended-query-tag)`[]` | Returns extended query tags |

+### Get extended query tag

+Get an extended query tag.

+```http

+GET .../extendedquerytags/{tagPath}

+```

+#### URI parameters

+| Name | In | Required | Type | Description |

+| - | - | -- | | |

+| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by `00100020` or `PatientId` |

+#### Responses

+| Name | Type | Description |

+| -- | -- | |

+| 200 (OK) | [Extended Query Tag](#extended-query-tag) | The extended query tag with the specified `tagPath` |

+| 400 (Bad Request) | | Requested tag path is invalid |

+| 404 (Not Found) | | Extended query tag with requested tagPath isn't found |

+### Delete extended query tag

+Delete an extended query tag.

+```http

+DELETE .../extendedquerytags/{tagPath}

+```

+#### URI parameters

+| Name | In | Required | Type | Description |

+| - | - | -- | | |

+| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by `00100020` or `PatientId` |

+#### Responses

+| Name | Type | Description |

+| -- | - | |

+| 204 (No Content) | | Extended query tag with requested tagPath has been successfully deleted. |

+| 400 (Bad Request) | | Requested tag path is invalid. |

+| 404 (Not Found) | | Extended query tag with requested tagPath isn't found |

+### Update extended query tag

+Update an extended query tag.

+```http

+PATCH .../extendedquerytags/{tagPath}

+```

+#### URI parameters

+| Name | In | Required | Type | Description |

+| - | - | -- | | |

+| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by `00100020` or `PatientId` |

+#### Request header

+| Name | Required | Type | Description |

+| | -- | | -- |

+| Content-Type | True | string | `application/json` is supported. |

+#### Request body

+| Name | Required | Type | Description |

+| - | -- | | -- |

+| body | | [Extended Query Tag for Updating](#extended-query-tag-for-updating) | |

+#### Responses

+| Name | Type | Description |

+| -- | -- | |

+| 20 (OK) | [Extended Query Tag](#extended-query-tag) | The updated extended query tag |

+| 400 (Bad Request) | | Requested tag path or body is invalid |

+| 404 (Not Found) | | Extended query tag with requested tagPath isn't found |

+### List extended query tag errors

+Lists errors on an extended query tag.

+```http

+GET .../extendedquerytags/{tagPath}/errors

+```

+#### URI parameters

+| Name | In | Required | Type | Description |

+| - | - | -- | | |

+| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by `00100020` or `PatientId` |

+#### Responses

+| Name | Type | Description |

+| -- | - | |

+| 200 (OK) | [Extended Query Tag Error](#extended-query-tag-error) `[]` | List of extended query tag errors associated with the tag |

+| 400 (Bad Request) | | Requested tag path is invalid |

+| 404 (Not Found) | | Extended query tag with requested tagPath isn't found |

+### Get operation

+Get a long-running operation.

+```http

+GET .../operations/{operationId}

+```

+#### URI parameters

+| Name | In | Required | Type | Description |

+| -- | - | -- | | - |

+| operationId | path | True | string | The operation ID |

+#### Responses

+| Name | Type | Description |

+| | -- | -- |

+| 200 (OK) | [Operation](#operation) | The completed operation for the specified ID |

+| 202 (Accepted) | [Operation](#operation) | The running operation for the specified ID |

+| 404 (Not Found) | | The operation isn't found |

+## QIDO with extended query tags

+### Tag status

+The [Status](#extended-query-tag-status) of extended query tag indicates current status. When an extended query tag is first added, its status is set to `Adding`, and a long-running operation is kicked off to reindex existing DICOM instances. After the operation is completed, the tag status is updated to `Ready`. The extended query tag can now be used in [QIDO](dicom-services-conformance-statement.md#search-qido-rs).

+For example, if the tag Manufacturer Model Name (0008,1090) is added, and in `Ready` status, hereafter the following queries can be used to filter stored instances by the Manufacturer Model Name.

+```http

+../instances?ManufacturerModelName=Microsoft

+```

+They can also be used with existing tags. For example:

+```http

+../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true

+```

+### Tag query status

+[QueryStatus](#extended-query-tag-status) indicates whether QIDO is allowed for the tag. When a reindex operation fails to process one or more DICOM instances for a tag, that tag's QueryStatus is set to `Disabled` automatically. You can choose to ignore indexing errors and allow queries to use this tag by setting the `QueryStatus` to `Enabled` via [Update Extended Query Tag](#update-extended-query-tag) API. Any QIDO requests that reference at least one manually enabled tag will include the set of tags with indexing errors in the response header `erroneous-dicom-attributes`.

+For example, suppose the extended query tag `PatientAge` had errors during reindexing, but it was enabled manually. For the following query, you would be able to see `PatientAge` in the `erroneous-dicom-attributes` header.

+```http

+../instances?PatientAge=035Y

+```

+## Definitions

+### Extended query tag

+A DICOM tag that will be supported for QIDO-RS.

+| Name | Type | Description |

+| -- | | |

+| Path | string | Path of tag, normally composed of group ID and element ID. for example, `PatientId` (0010,0020) has path 00100020 |

+| VR | string | Value representation of this tag |

+| PrivateCreator | string | Identification code of the implementer of this private tag |

+| Level | [Extended Query Tag Level](#extended-query-tag-level) | Level of extended query tag |

+| Status | [Extended Query Tag Status](#extended-query-tag-status) | Status of the extended query tag |

+| QueryStatus | [Extended Query Tag Query Status](#extended-query-tag-query-status) | Query status of extended query tag |

+| Errors | [Extended Query Tag Errors Reference](#extended-query-tag-errors-reference) | Reference to extended query tag errors |

+| Operation | [Operation Reference](#operation-reference) | Reference to a long-running operation |

+Code **example 1** is a standard tag (0008,0070) in `Ready` status.

+```json

+{

+ "status": "Ready",

+ "level": "Instance",

+ "queryStatus": "Enabled",

+ "path": "00080070",

+ "vr": "LO"

+}

+```

+Code **example 2** is a standard tag (0010,1010) in `Adding` status. An operation with ID `1a5d0306d9624f699929ee1a59ed57a0` is running on it, and 21 errors has occurred so far.

+```json

+{

+ "status": "Adding",

+ "level": "Study",

+ "errors": {

+ "count": 21,

+ "href": "https://localhost:63838/extendedquerytags/00101010/errors"

+ },

+ "operation": {

+ "id": "1a5d0306d9624f699929ee1a59ed57a0",

+ "href": "https://localhost:63838/operations/1a5d0306d9624f699929ee1a59ed57a0"

+ },

+ "queryStatus": "Disabled",

+ "path": "00101010",

+ "vr": "AS"

+}

+```

+### Operation reference

+Reference to a long-running operation.

+| Name | Type | Description |

+| - | | -- |

+| ID | string | operation ID |

+| Href | string | Uri to the operation |

+### Operation

+Represents a long-running operation.

+| Name | Type | Description |

+| | - | |

+| OperationId | string | The operation ID |

+| OperationType | [Operation Type](#operation-type) | Type of the long running operation |

+| CreatedTime | string | Time when the operation was created |

+| LastUpdatedTime | string | Time when the operation was updated last time |

+| Status | [Operation Status](#operation-status) | Represents run time status of operation |

+| PercentComplete | Integer | Percentage of work that has been completed by the operation |

+| Resources | string`[]` | Collection of resources locations that the operation is creating or manipulating |

+The following code **example** is a running reindex operation.

+```json

+{

+ "resources": [

+ "https://localhost:63838/extendedquerytags/00101010"

+ ],

+ "operationId": "a99a8b51-78d4-4fd9-b004-b6c0bcaccf1d",

+ "type": "Reindex",

+ "createdTime": "2021-10-06T16:40:02.5247083Z",

+ "lastUpdatedTime": "2021-10-06T16:40:04.5152934Z",

+ "status": "Running",

+ "percentComplete": 10

+}

+```

+### Operation status

+Represents a run time status of long running operation.

+| Name | Type | Description |

+| - | | |

+| NotStarted | string | The operation isn't started |

+| Running | string | The operation is executing and hasn't yet finished |

+| Completed | string | The operation has finished successfully |

+| Failed | string | The operation has stopped prematurely after encountering one or more errors |

+### Extended query tag error

+An error that occurred during an extended query tag indexing operation.

+| Name | Type | Description |

+| -- | | - |

+| StudyInstanceUid | string | Study instance UID where indexing errors occurred |

+| SeriesInstanceUid | string | Series instance UID where indexing errors occurred |

+| SopInstanceUid | string | Sop instance UID where indexing errors occurred |

+| CreatedTime | string | Time when error occurred(UTC) |

+| ErrorMessage | string | Error message |

+The following code **example** contains an unexpected value length error on a DICOM instance. It occurred at 2021-10-06T16:41:44.4783136.

+```json

+{

+ "studyInstanceUid": "2.25.253658084841524753870559471415339023884",

+ "seriesInstanceUid": "2.25.309809095970466602239093351963447277833",

+ "sopInstanceUid": "2.25.225286918605419873651833906117051809629",

+ "createdTime": "2021-10-06T16:41:44.4783136",

+ "errorMessage": "Value length is not expected."

+}

+```

+### Extended query tag errors reference

+Reference to extended query tag errors.

+| Name | Type | Description |

+| -- | - | |

+| Count | Integer | Total number of errors on the extended query tag |

+| Href | string | URI to extended query tag errors |

+### Operation type

+The type of a long-running operation.

+| Name | Type | Description |

+| - | | |

+| Reindex | string | A reindex operation that updates the indices for previously added data based on new tags |

+### Extended query tag status

+The status of extended query tag.

+| Name | Type | Description |

+| -- | | |

+| Adding | string | The extended query tag has been added, and a long-running operation is reindexing existing DICOM instances |

+| Ready | string | The extended query tag is ready for QIDO-RS |

+| Deleting | string | The extended query tag is being deleted |

+### Extended query tag level

+The level of the DICOM information hierarchy where this tag applies.

+| Name | Type | Description |

+| -- | | -- |

+| Instance | string | The extended query tag is relevant at the instance level |

+| Series | string | The extended query tag is relevant at the series level |

+| Study | string | The extended query tag is relevant at the study level |

+### Extended query tag query status

+The query status of extended query tag.

+| Name | Type | Description |

+| -- | | |

+| Disabled | string | The extended query tag isn't allowed to be queried |

+| Enabled | string | The extended query tag is allowed to be queried |

+> [!NOTE]

+> Errors during the reindex operation disables QIDO on the extended query tag. You can call the [Update Extended Query Tag](#update-extended-query-tag) API to enable it.

+### Extended query tag for updating

+Represents extended query tag for updating.

+| Name | Type | Description |

+| -- | | -- |

+| QueryStatus | [Extended Query Tag Query Status](#extended-query-tag-query-status) | The query status of extended query tag |

+### Extended query tag for adding

+Represents extended query tag for adding.

+| Name | Required | Type | Description |

+| -- | -- | -- | |

+| Path | True | string | Path of tag, normally composed of the group ID and element ID that's the `PatientId` (0010,0020) has path 00100020 |

+| VR | | string | Value representation of this tag. It's optional for standard tag, and required for private tag |

+| PrivateCreator | | string | Identification code of the implementer of this private tag. Only set when the tag is a private tag |

+| Level | True | [Extended Query Tag Level](#extended-query-tag-level) | Represents the hierarchy at which this tag is relevant. Should be one of Study, Series or Instance |

+Code **example 1** `MicrosoftPC` is defining the private tag (0401,1001) with the `SS` value representation on the instance level.

+```json

+{

+ "Path": "04011001",

+ "VR": "SS",

+ "PrivateCreator": "MicrosoftPC",

+ "Level": "Instance"

+}

+```

+Code **example 2** uses the standard tag with keyword `ManufacturerModelName` with the `LO` value representation that's defined on the series level.

+```json

+{

+ "Path": "ManufacturerModelName",

+ "VR": "LO",

+ "Level": "Series"

+}

+```

+ Code **example 3** uses the standard tag (0010,0040) and is defined on studies. The value representation is already defined by the DICOM standard.

+```json

+{

+ "Path": "00100040",

+ "Level": "Study"

+}

+```

+## Summary

+This conceptual article provided you with an overview of the Extended Query Tag feature within the DICOM service.

+

+## Next steps

+For more information about deploying the DICOM service, see

+>[!div class="nextstepaction"]

+>[Deploy DICOM service to Azure](deploy-dicom-services-in-azure.md)

+>[!div class="nextstepaction"]

+>[Using DICOMweb&trade;Standard APIs with DICOM service](dicomweb-standard-apis-with-dicom-services.md)

+ Title: Get access token using Azure CLI - Azure Health Data Services for DICOM service

+[  ](media/launch-cloud-shell.png#lightbox)

+ Title: DICOM Conformance Statement for Azure Health Data Services

+description: This document provides details about the DICOM Conformance Statement for Azure Health Data Services.

+The **DICOM service within Azure Health Data Services** supports a subset of the DICOMweb&trade; Standard. This support includes:

+Parameter `study` corresponds to the DICOM attribute StudyInstanceUID. If it's specified, any instance that doesn't belong to the provided study will be rejected with a `43265` warning code.

+DICOM File Size Limit: there's a size limit of 2 GB for a DICOM file by default.

+| 400 (Bad Request) | The request was badly formatted. For example, the provided study instance identifier didn't conform to the expected UID format. |

+| 401 (Unauthorized) | The client isn't authenticated. |

+| 403 (Forbidden) | The user isn't authorized. |

+| 406 (Not Acceptable) | The specified `Accept` header isn't supported. |

+| 415 (Unsupported Media Type) | The provided `Content-Type` isn't supported. |

+| 272 | The store transaction didn't store the instance because of a general failure in processing the operation. |

+| 43265 | The provided instance StudyInstanceUID didn't match the specified StudyInstanceUID in the store request. |

+| 45071 | A DICOM instance is being created by another process, or the previous attempt to create has failed and the cleanup process hasn't had chance to clean up yet. Delete the instance first before attempting to create again. |

+* `multipart/related; type="application/dicom";` (when transfer-syntax isn't specified, 1.2.840.10008.1.2.1 is used as default)

+* `application/dicom;` (when transfer-syntax isn't specified, 1.2.840.10008.1.2.1 is used as default)

+* `multipart/related; type="application/dicom"` (when transfer-syntax isn't specified, 1.2.840.10008.1.2.1 is used as default)

+* `multipart/related; type="application/octet-stream";` (when transfer-syntax isn't specified, 1.2.840.10008.1.2.1 is used as default)

+* `multipart/related; type="image/jp2";` (when transfer-syntax isn't specified, 1.2.840.10008.1.2.4.90 is used as default)

+Retrieving metadata won't return attributes with the following value representations:

+* Data hasn't changed since the last request: HTTP 304 (Not Modified) response will be sent with no response body.

+| 304 (Not Modified) | The requested data hasn't been modified since the last request. Content isn't added to the response body in such case. For more information, see the above section **Retrieve Metadata Cache Validation (for Study, Series, or Instance)**. |

+| 400 (Bad Request) | The request was badly formatted. For example, the provided study instance identifier didn't conform to the expected UID format, or the requested transfer-syntax encoding isn't supported. |

+| 401 (Unauthorized) | The client isn't authenticated. |

+| 403 (Forbidden) | The user isn't authorized. |

+| 404 (Not Found) | The specified DICOM resource couldn't be found. |

+| 406 (Not Acceptable) | The specified `Accept` header isn't supported. |

+| `fuzzymatching=` | `true` \| `false` | 0..1 | If true fuzzy matching is applied to PatientName attribute. It will do a prefix word match of any name part inside PatientName value. For example, if PatientName is "John^Doe", then "joh", "do", "jo do", "Doe" and "John Doe" will all match. However, "ohn" won't match. |

+Tags can be encoded in many ways for the query parameter. We've partially implemented the standard as defined in [PS3.18 6.7.1.1.1](http://dicom.nema.org/medical/dicom/2019a/output/chtml/part18/sect_6.7.html#sect_6.7.1.1.1). The following encodings for a tag are supported:

+| 401 (Unauthorized) | The client isn't authenticated. |

+| 403 (Forbidden) | The user isn't authorized. |

+* Querying using the `TimezoneOffsetFromUTC` (`00080201`) isn't supported.

+* The query API won't return 413 (request entity too large). If the requested query response limit is outside of the acceptable range, a bad request will be returned. Anything requested within the acceptable range will be resolved.

+* When target resource is study/series, there's a potential for inconsistent study/series level metadata across multiple instances. For example, two instances could have different patientName. In this case, the latest will win, and you can search only on the latest data.

+This transaction isn't part of the official DICOMweb&trade; Standard. It uses the DELETE method to remove representations of studies, series, and instances from the store.

+| 401 (Unauthorized) | The client isn't authenticated. |

+| 403 (Forbidden) | The user isn't authorized. |

+| 404 (Not Found) | When the specified series wasn't found within a study, or the specified instance wasn't found within the series. |

+ Title: Overview of the DICOM service - Azure Health Data Services

+description: In this article, you'll learn concepts of DICOM and the DICOM service.

+This article describes the concepts of DICOM and the DICOM service.

+## DICOM

+DICOM (Digital Imaging and Communications in Medicine) is the international standard to transmit, store, retrieve, print, process, and display medical imaging information, and is the primary medical imaging standard accepted across healthcare.

+## DICOM service

+The DICOM service is a managed service within [Azure Health Data Services](../healthcare-apis-overview.md) that ingests and persists DICOM objects at multiple thousands of images per second. It facilitates communication and transmission of imaging data with any DICOMweb&trade; enabled systems or applications via DICOMweb Standard APIs like [Store (STOW-RS)](dicom-services-conformance-statement.md#store-stow-rs), [Search (QIDO-RS)](dicom-services-conformance-statement.md#search-qido-rs), [Retrieve (WADO-RS)](dicom-services-conformance-statement.md#retrieve-wado-rs). It's backed by a managed Platform-as-a Service (PaaS) offering in the cloud with complete [PHI](https://www.hhs.gov/answers/hipaa/what-is-phi/https://docsupdatetracker.net/index.html) compliance that you can upload PHI data to the DICOM service and exchange it through secure networks.

+- **PHI Compliant**: Protect your PHI with unparalleled security intelligence. Your data is isolated to a unique database per API instance and protected with multi-region failover. The DICOM service implements a layered, in-depth defense and advanced threat protection for your data.

+- **Extended Query Tags**: Additionally index DICOM studies, series, and instances on both standard and private DICOM tags by expanding list of tags that are already specified within [DICOM Conformance Statement](dicom-services-conformance-statement.md).

+- **Change Feed**: Access ordered, guaranteed, immutable, read-only logs of all the changes that occur in DICOM service. Client applications can read these logs at any time independently, in parallel and at their own pace.

+- **DICOM cast**: Via DICOM cast, DICOM service can inject DICOM metadata into a FHIR service, or FHIR server, as an imaging study resource allowing a single source of truth for both clinical data and imaging metadata. This feature is available on demand. To enable DICOM cast for your Azure subscription, please request access for DICOM cast via opening an [Azure Technical Support](https://azure.microsoft.com/support/create-ticket/) ticket.

+- **Region availability**: DICOM service has wide-range of [availability across many regions](https://azure.microsoft.com/global-infrastructure/services/?products=azure-api-for-fhir&regions=all) with multi-region failover protection and continuously expanding.

+- **Scalability**: DICOM service is designed out-of-the-box to support different workload levels at a hospital, region, country and global scale without sacrificing any performance spec by using autoscaling features.

+- **Role-based access**: You control your data. Role-based access control (RBAC) enables you to manage how your data is stored and accessed. Providing increased security and reducing administrative workload, you determine who has access to the datasets you create, based on role definitions you create for your environment.

+[Open-source DICOM-server project](https://github.com/microsoft/dicom-server) is also constantly monitored for feature parity with managed service so that developers can deploy open source version as a set of Docker containers to speed up development and test in their environments, and contribute to potential future managed service features.

+## Applications for the DICOM service

+In order to effectively treat patients, research new treatments, diagnose solutions, or provide an effective overview of the health history of a single patient, organizations must integrate data across several sources. One of the most pressing integrations is between clinical and imaging data. DICOM service enables imaging data to securely persist in the Microsoft cloud and allows it to reside with EHR and IoT data in the same Azure subscription.

+FHIR&trade; is becoming an important standard for clinical data and provides extensibility to support integration of other types of data directly, or through references. By using DICOM service, organizations can store references to imaging data in FHIR&trade; and enable queries that cross clinical and imaging datasets. This can enable many different scenarios, for example:

+- **Image back-up**: Research institutions, clinics, imaging centers, veterinary clinics, pathology institutions, retailers, any team or organization can use the DICOM service to back up their images with unlimited storage and access. And there's no need to de-identify PHI data as our service is validated for PHI compliance.

+- **Image exchange and collaboration**: Share an image, a sub set of images in your storage, or entire image library instantly with or without related EHR data.

+- **Disaster recovery**: High availability is a resiliency characteristic of DICOM service. High availability is implemented in place (in the same region as your primary service) by designing it as a feature of the primary system.

+- **Creating cohorts for research**: Often through queries for patients that match data in both clinical and imaging systems, such as this one (which triggered the effort to integrate FHIR&trade; and DICOM data): ΓÇ£Give me all the medications prescribed with all the CT scan documents and their associated radiology reports for any patient older than 45 that has had a diagnosis of osteosarcoma over the last two years.ΓÇ¥

+- **Finding outcomes for similar patients to understand options and plan treatments**: When presented with a patient diagnosis, a physician can identify patient outcomes and treatment plans for past patients with a similar diagnosis, even when these include imaging data.

+- **Providing a longitudinal view of a patient during diagnosis**: Radiologists, especially teleradiologists, often don't have complete access to a patientΓÇÖs medical history and related imaging studies. Through FHIR&trade; integration, this data can be easily provided, even to radiologists outside of the organizationΓÇÖs local network.

+- **Closing the feedback loop with teleradiologists**: Ideally a radiologist has access to a hospitalΓÇÖs clinical data to close the feedback loop after making a recommendation. However for teleradiologists, this is often not the case. Instead, they're often unable to close the feedback loop after performing a diagnosis, since they don't have access to patient data after the initial read. With no (or limited) access to clinical results or outcomes, they canΓÇÖt get the feedback necessary to improve their skills. As one teleradiologist put it: ΓÇ£Take parathyroid for example. We do more than any other clinic in the country, and yet I have to beg and plead for surgeons to tell me what they actually found. Out of the more than 500 studies I do each month, I get direct feedback on only three or four.ΓÇ¥ Through integration with FHIR&trade;, an organization can easily create a tool that will provide direct feedback to teleradiologists, helping them to hone their skills and make better recommendations in the future.

+- **Closing the feedback loop for AI/ML models**: Machine learning models do best when real-world feedback can be used to improve their models. However, third-party ML model providers rarely get the feedback they need to improve their models over time. For instance, one ISV put it this way: ΓÇ£We use a combination of machine models and human experts to recommend a treatment plan for heart surgery. However, we only rarely get feedback from physicians on how accurate our plan was. For instance, we often recommend a stent size. WeΓÇÖd love to get feedback on if our prediction was correct, but the only time we hear from customers is when thereΓÇÖs a major issue with our recommendations.ΓÇ¥ As with feedback for teleradiologists, integration with FHIR&trade; allows organizations to create a mechanism to provide feedback to the model retraining pipeline.

+This conceptual article provided you with an overview of DICOM and the DICOM service.

+For more information about how to use the DICOMweb&trade; Standard APIs with the DICOM service, see

+ Title: Using DICOMweb&trade;Standard APIs with C# - Azure Health Data Services

+This response deletes the green-square instance (it's the only element left in the series) from the server. If it's successful, the response status code will contain no content.

+This response deletes the blue-circle instance (it's the only element left in the series) from the server. If it's successful, the response status code contains no content.

+ Title: Using DICOMweb&trade;Standard APIs with cURL - Azure Health Data Services

+This tutorial uses cURL to demonstrate working with the DICOM service.

+For this code, we'll be accessing an Public Preview Azure service. It's important that you don't upload any private health information (PHI).

+The DICOMweb&trade; Standard makes heavy use of `multipart/related` HTTP requests combined with DICOM specific accept headers. Developers familiar with other REST-based APIs often find working with the DICOMweb&trade; Standard awkward. However, once you've it up and running, it's easy to use. It just takes a little familiarity to get started.

+This cURL command will show the downloaded bytes in the output file (suppressWarnings.txt), but these aren't direct DICOM files, only a text representation of the multipart/related download.

+This cURL command will show the downloaded bytes in the output file (suppressWarnings.txt), but these aren't direct DICOM files, only a text representation of the multipart/related download.

+Delete isn't part of the DICOM standard, but it's been added for convenience.

+Delete isn't part of the DICOM standard, but it's been added for convenience.

+Delete isn't part of the DICOM standard, but it has been added for convenience.

+ Title: Using DICOMweb Standard APIs with Python - Azure Health Data Services

+For this code, we'll be accessing a Public Preview Azure service. It's important that you don't upload any private health information (PHI).

+The DICOMweb&trade; Standard makes heavy use of `multipart/related` HTTP requests combined with DICOM specific accept headers. Developers familiar with other REST-based APIs often find working with the DICOMweb&trade; standard awkward. However, once you've it up and running, it's easy to use. It just takes a little familiarity to get started.

+Replace all variable values wrapped in { } with your own values. Additionally, validate that any constructed variables are correct. For instance, `base_url` is constructed using the Service URL and then appended with the version of the REST API being used. The Service URL of your DICOM service will be: ```https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com```. You can use the Azure portal to navigate to the DICOM service and obtain your Service URL. You can also visit the [API Versioning for DICOM service Documentation](api-versioning-dicom-service.md) for more information on versioning. If you're using a custom URL, you'll need to override that value with your own.

+`DefaultAzureCredential` allows us to get a variety of ways to get tokens to log into the service. We'll use the `AzureCliCredential` to get a token to log into the service. There are other credential providers such as `ManagedIdentityCredential` and `EnvironmentCredential` that are also possible to use. In order to use the AzureCliCredential, you must have logged into Azure from the CLI prior to running this code. (For more information, see [Get access token for the DICOM service using Azure CLI](dicom-get-access-token-azure-cli.md).) Alternatively, you can simply copy and paste the token retrieved while logging in from the CLI.

+The `Requests` libraries (and most Python libraries) don't work with `multipart\related` in a way that supports DICOMweb&trade;. Because of these libraries, we must add a few methods to support working with DICOM files.

+By passing an array of files to the fields parameter of `encode_multipart_related`, multiple files can be uploaded in a single POST. It's sometimes used to upload a complete series or study.

+The following code example demonstrates how to upload a single DICOM file. It's a non-standard API endpoint that simplifies uploading a single file as binary bytes sent in the body of a request

+This code example deletes the green-square instance (it's the only element left in the series) from the server. If it's successful, the response status code won't delete content.

+ Title: Using DICOMweb - Standard APIs with Azure Health Data Services DICOM service

+This tutorial provides an overview of how to use DICOMweb&trade; Standard APIs with the DICOM service.

+The DICOM service supports a subset of DICOMweb&trade; Standard that includes:

+To learn more about our support of DICOM Web Standard APIs, see the [DICOM Conformance Statement](dicom-services-conformance-statement.md) reference document.

+To use DICOMweb&trade; Standard APIs, you must have an instance of DICOM service deployed. If you haven't already deployed an instance of DICOM service, see [Deploy DICOM service using the Azure portal](deploy-dicom-services-in-azure.md).

+Because DICOM service is exposed as a REST API, you can access it using any modern development language. For language-agnostic information on working with the service, see [DICOM Conformance Statement](dicom-services-conformance-statement.md).

+Refer to the [Using DICOMwebΓäó Standard APIs with C#](dicomweb-standard-apis-c-sharp.md) tutorial to learn how to use C# with DICOM service.

+To learn how to use cURL with DICOM service, see [Using DICOMWebΓäó Standard APIs with cURL](dicomweb-standard-apis-curl.md) tutorial.

+One important caveat with Postman and DICOMweb&trade; Standard is that Postman can only support uploading DICOM files using the single part payload defined in the DICOM standard. This reason is because Postman can't support custom separators in a multipart/related POST request. For more information, see [Multipart POST not working for me # 576](https://github.com/postmanlabs/postman-app-support/issues/576). Thus, all examples in the Postman collection for uploading DICOM documents using a multipart request are prefixed with [won't work - see description]. The examples for uploading using a single part request are included in the collection and are prefixed with "Store-Single-Instance".

+This tutorial provided an overview of the APIs supported by DICOM service. Get started using these APIs with the following tools:

+ Title: Enable diagnostic logging in the DICOM service - Azure Health Data Services

+In this article, you'll learn how to enable diagnostic logging in DICOM service and be able to review some sample queries for these logs. Access to diagnostic logs is essential for any healthcare service where compliance with regulatory requirements is a must. The feature in DICOM service enables diagnostic logs is the [Diagnostic settings](../../azure-monitor/essentials/diagnostic-settings.md) in the Azure portal.

+ [  ](media/dicom-activity-log.png#lightbox)

+ [  ](media/add-diagnostic-settings.png#lightbox)

+ [  ](media/configure-diagnostic-settings.png#lightbox)

+ * **Send to partner solution** that you're working with as partner organization in Azure. For information about potential partner integrations, see [Azure partner solutions documentation](../../partner-solutions/overview.md)

+|operationName|String|Describes the type of operation (for example, Retrieve, Store, Query, etc.)

+|identity|Dynamic|A generic property bag containing identity information (currently doesn't apply to DICOM).

+|resultSignature|Int|The HTTP Status Code (for example, 200)

+ Title: Get started with the DICOM service - Azure Health Data Services

+description: This document describes how to get started with the DICOM service in Azure Health Data Services.

+This article outlines the basic steps to get started with the DICOM service in [Azure Health Data Services](../healthcare-apis-overview.md).

+As a prerequisite, you'll need an Azure subscription and have been granted proper permissions to create Azure resource groups and to deploy Azure resources. You can follow all the steps, or skip some if you have an existing environment. Also, you can combine all the steps and complete them in PowerShell, Azure CLI, and REST API scripts. You'll need a workspace to provision a DICOM service. A FHIR service is optional and is needed only if you connect imaging data with electronic health records of the patient via DICOM cast.

+[](media/get-started-with-dicom.png#lightbox)

+You can create a workspace from the [Azure portal](../healthcare-apis-quickstart.md) or using PowerShell, Azure CLI, and REST API. You can find scripts from the [Azure Health Data Services samples](https://github.com/microsoft/healthcare-apis-samples/tree/main/src/scripts).

+You can create a DICOM service instance from the [Azure portal](deploy-dicom-services-in-azure.md) or using PowerShell, Azure CLI, and REST API. You can find scripts from the [Azure Health Data Services samples](https://github.com/microsoft/healthcare-apis-samples/tree/main/src/scripts).

+Optionally, you can create a [FHIR service](../fhir/fhir-portal-quickstart.md) and [MedTech service](../iot/deploy-iot-connector-in-azure.md) in the workspace.

+You can create or register a client application from the [Azure portal](../register-application.md), or using PowerShell and Azure CLI scripts. This client application can be used for one or more DICOM service instances. It can also be used for other services in Azure Health Data Services.

+You can obtain an Azure AD access token using PowerShell, Azure CLI, REST CLI, or .NET SDK. For more information, see [Get access token](../get-access-token.md).

+- Postman

+- REST Client

+#### DICOM cast

+DICOM cast is currently available as an [open source](https://github.com/microsoft/dicom-server/blob/main/docs/concepts/dicom-cast.md) project, and it's under private preview as a managed service. To enable DICOM cast as a managed service for your Azure subscription, request access by creating an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/following) by following the guidance in the article [DICOM cast access request](dicom-cast-access-request.md).

+description: This how-to guide explains how to pull DICOM changes using DICOM Change Feed for Azure Health Data Services.

+DICOM Change Feed offers customers the ability to go through the history of the DICOM service and act on the create and delete events in the service. This how-to guide describes how to consume Change Feed.

+ Title: References for DICOM service - Azure Health Data Services

+description: This reference provides related resources for the DICOM service.

+# DICOM service open-source projects

+This article describes our open-source projects on GitHub that provide source code and instructions to connect DICOM service with other tools, services, and products.

+## DICOM service GitHub projects

+### DICOM server

+* [Medical imaging server for DICOM](https://github.com/microsoft/dicom-server): Open-source version of the Azure Healthcare APIs DICOM service managed service.

+### DICOM cast

+* [Integrate clinical and imaging data](https://github.com/microsoft/dicom-server/blob/main/docs/concepts/dicom-cast.md): DICOM cast allows synchronizing the data from the DICOM service to the FHIR service, which allows healthcare organization to integrate clinical and imaging data. DICOM cast expands the use cases for health data by supporting both a streamlined view of longitudinal patient data and the ability to effectively create cohorts for medical studies, analytics, and machine learning.

+### DICOM data anonymization

+* [Anonymize DICOM metadata](https://github.com/microsoft/Tools-for-Health-Data-Anonymization/blob/master/docs/DICOM-anonymization.md): A DICOM file not only contains a viewable image but also a header with a large variety of data elements. These meta-data elements include identifiable information about the patient, the study, and the institution. Sharing such sensitive data demands proper protection to ensure data safety and maintain patient privacy. DICOM Anonymization Tool helps anonymize metadata in DICOM files for this purpose.

+### Access imaging study resources on Power BI, Power Apps, and Dynamics 365 Customer Insights

+* [Connect to a FHIR service from Power Query Desktop](https://docs.microsoft.com/power-query/connectors/fhir/fhir): After provisioning DICOM service, FHIR service and synchronizing imaging study for a given patient via DICOM cast, you can use the POWER Query connector for FHIR to import and shape data from the FHIR server including imaging study resource.

+### Convert imaging study data to hierarchical parquet files

+* [FHIR to Synapse Sync Agent](https://github.com/microsoft/FHIR-Analytics-Pipelines/blob/main/FhirToDataLake/docs/Deployment.md): After you provision a DICOM service, FHIR service and synchronizing imaging study for a given patient via DICOM cast, you can use FHIR to Synapse Sync Agent to perform Analytics and Machine Learning on imaging study data by moving FHIR data to Azure Data Lake in near real time and making it available to a Synapse workspace.

+## Next steps

+For more information about using the DICOM service, see

+>[!div class="nextstepaction"]

+>[Deploy DICOM service to Azure](deploy-dicom-services-in-azure.md)

+For more information about DICOM cast, see

+>[!div class="nextstepaction"]

+>[DICOM cast overview](dicom-cast-overview.md)

+ Title: Deploy Events in the Azure portal - Azure Health Data Services

+description: This article describes how to deploy the Events feature in the Azure portal.

+# Deploy Events in the Azure portal

+In this quickstart, you’ll learn how to deploy the Azure Health Data Services Events feature in the Azure portal to send Fast Healthcare Interoperability Resources (FHIR®) event messages.

+## Prerequisites

+It's important that you have the following prerequisites completed before you begin the steps of deploying the Events feature in Azure Health Data Services.

+* [An active Azure account](https://azure.microsoft.com/free/search/?OCID=AID2100131_SEM_c4b0772dc7df1f075552174a854fd4bc:G:s&ef_id=c4b0772dc7df1f075552174a854fd4bc:G:s&msclkid=c4b0772dc7df1f075552174a854fd4bc)

+* [Event Hubs namespace and an event hub deployed in the Azure portal](../../event-hubs/event-hubs-create.md)

+* [Workspace deployed in Azure Health Data Services](../healthcare-apis-quickstart.md)

+* [FHIR service deployed in Azure Health Data Services](../fhir/fhir-portal-quickstart.md)

+> [!NOTE]

+> For the purposes of this quickstart, we'll be using a basic set up and an event hub as the endpoint for Events messages.

+## Deploy Events

+1. Browse to the Workspace that contains the FHIR service you want to send event messages from and select the **Events** blade.

+

+ :::image type="content" source="media/events-deploy-in-portal/events-workspace-select.png" alt-text="Screenshot of Workspace and select Events button." lightbox="media/events-deploy-in-portal/events-workspace-select.png":::

+2. Select **+ Event Subscription** to begin the creation of an event subscription.

+ :::image type="content" source="media/events-deploy-in-portal/events-new-subscription-select.png" alt-text="Screenshot of Workspace and select events subscription button." lightbox="media/events-deploy-in-portal/events-new-subscription-select.png":::

+3. In the **Create Event Subscription** box, enter the following subscription information.

+ * **Name**: Provide a name for your Events subscription.

+ * **Event types**: Type of FHIR events to send messages for (for example: create, updated, and deleted).

+ * **Endpoint Details**: Endpoint to send Events messages to (for example: an Event Hubs).

+ >[!NOTE]

+ > For the purposes of this quickstart, we'll use the **Event Schema** and the **Managed Identity Type** settings as their defaults.

+ :::image type="content" source="media/events-deploy-in-portal/events-create-new-subscription.png" alt-text="Screenshot of the create event subscription box." lightbox="media/events-deploy-in-portal/events-create-new-subscription.png":::

+4. After the form is completed, select **Create** to begin the subscription creation.

+5. After provisioning a new Events subscription, event messages won't be sent until the System Topic deployment has successfully completed and the status of the Workspace has changed from "Updating" to "Succeeded".

+ :::image type="content" source="media/events-deploy-in-portal/events-new-subscription-create.png" alt-text="Screenshot of an events subscription being deployed" lightbox="media/events-deploy-in-portal/events-new-subscription-create.png":::

+ :::image type="content" source="media/events-deploy-in-portal/events-workspace-update.png" alt-text="Screenshot of an events subscription successfully deployed." lightbox="media/events-deploy-in-portal/events-workspace-update.png":::

+6. After the subscription is deployed, it will require access to your message delivery endpoint.

+ :::image type="content" source="media/events-deploy-in-portal/events-new-subscription-created.png" alt-text="Screenshot of a successfully deployed events subscription." lightbox="media/events-deploy-in-portal/events-new-subscription-created.png":::

+ >[!TIP]

+ >For more information about providing access using an Azure Managed identity, see

+ > - [Assign a system-managed identity to an Event Grid system topic](../../event-grid/enable-identity-system-topics.md)

+ > - [Event delivery with a managed identity](../../event-grid/managed-service-identity.md)

+ >

+ >For more information about managed identities, see

+ > - [What are managed identities for Azure resources](/azure/active-directory/managed-identities-azure-resources/overview)

+ >

+ >For more information about Azure role-based access control (Azure RBAC), see

+ > - [What is Azure role-based access control (Azure RBAC)](/azure/role-based-access-control/overview)

+## Next steps

+In this article, you've learned how to deploy Events in the Azure portal.

+To learn how to display the Events metrics, see

+>[!div class="nextstepaction"]

+>[How to display Events metrics](./events-display-metrics.md)

+To learn how to export Event Grid system diagnostic logs and metrics, see

+>[!div class="nextstepaction"]

+>[How to export Events diagnostic logs and metrics](./events-display-metrics.md)

+(FHIR&#174;) is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

+ Title: Disable Events and delete Workspaces - Azure Health Data Services

+description: This article provides resources on how to disable Events and delete Workspaces.

+# Disable Events and delete Workspaces

+In this article, you'll learn how to disable Events and delete Workspaces in Azure Health Data Services.

+## Disable Events

+To disable Events from sending event messages for a single Event Subscription, the Event Subscription must be deleted.

+1. Select the Event Subscription to be deleted. In this example, we'll be selecting an Event Subscription named **fhir-events**.

+ :::image type="content" source="media/disable-delete-workspaces/events-select-subscription.png" alt-text="Screenshot of Events subscriptions and select event subscription to be deleted." lightbox="media/disable-delete-workspaces/events-select-subscription.png":::

+2. Select **Delete** and confirm the Event Subscription deletion.

+ :::image type="content" source="media/disable-delete-workspaces/events-select-subscription-delete.png" alt-text="Screenshot of events subscriptions and select delete and confirm the event subscription to be deleted." lightbox="media/disable-delete-workspaces/events-select-subscription-delete.png":::

+3. To completely disable Events, delete all Event Subscriptions so that no Event Subscriptions remain.

+ :::image type="content" source="media/disable-delete-workspaces/events-disable-no-subscriptions.png" alt-text="Screenshot of Events subscriptions and delete all event subscriptions to disable events." lightbox="media/disable-delete-workspaces/events-disable-no-subscriptions.png":::

+> [!NOTE]

+>

+> The Fast Healthcare Interoperability Resources (FHIR&#174;) service will automatically go into an **Updating** status to disable the Events extension when a full delete of Event Subscriptions is executed. The FHIR service will remain online while the operation is completing.

+## Delete Workspaces

+To successfully delete a Workspace, delete all associated child resources first (for example: DICOM services, FHIR services and MedTech services), delete all Event Subscriptions, and then delete the Workspace. Not deleting the child resources and Event Subscriptions first will cause an error when attempting to delete a Workspace with child resources.

+As an example:

+ 1. Delete all Workspace associated child resources - for example: DICOM service(s), FHIR service(s), and MedTech service(s).

+ 2. Delete all Workspace associated Event Subscriptions.

+ 3. Delete Workspace.

+## Next steps

+For more information about how to troubleshoot Events, see

+>[!div class="nextstepaction"]

+>[Troubleshoot Events](./events-troubleshooting-guide.md)

+(FHIR&#174;) is a registered trademark of HL7 and is used with the permission of HL7.

+ Title: Display Events metrics in Azure Health Data Services

+description: This article explains how to display Events metrics

+# How to display Events metrics

+In this article, you'll learn how to display Events metrics in the Azure portal.

+> [!NOTE]

+> For the purposes of this article, an Azure Event Hubs event hub was used as the Events message endpoint.

+## Display metrics

+1. Within your Azure Health Data Services Workspace, select the **Events** button.

+ :::image type="content" source="media\events-display-metrics\events-metrics-workspace-select.png" alt-text="Screenshot of select the events button from the Workspace." lightbox="media\events-display-metrics\events-metrics-workspace-select.png":::

+2. The Events page displays the combined metrics for all Events Subscriptions. For example, we have one subscription named **fhir-events** and one processed message. Select the subscription in the lower left-hand corner to view the metrics for that subscription.

+ :::image type="content" source="media\events-display-metrics\events-metrics-main.png" alt-text="Screenshot of events you would like to display metrics for." lightbox="media\events-display-metrics\events-metrics-main.png":::

+

+3. From this page, you'll notice that the subscription named **fhir-events** has one processed message. To view the Event Hubs metrics, select the name of the Event Hubs (for this example, **azuredocsfhirservice**) from the lower right-hand corner of the page.

+ :::image type="content" source="media\events-display-metrics\events-metrics-subscription.png" alt-text="Screenshot of select the metrics button." lightbox="media\events-display-metrics\events-metrics-subscription.png":::

+4. From this page, you'll notice that the Event Hubs received the incoming message presented in the previous Events subscription metrics pages.

+ :::image type="content" source="media\events-display-metrics\events-metrics-event-hub.png" alt-text="Screenshot of displaying event hubs metrics." lightbox="media\events-display-metrics\events-metrics-event-hub.png":::

+## Next steps

+To learn how to export Events Azure Event Grid system diagnostic logs and metrics, see

+>[!div class="nextstepaction"]

+>[Configure Events diagnostic logs and metrics exporting](./events-export-logs-metrics.md)

+(FHIR&#174;) is a registered trademark of HL7 and is used with the permission of HL7.

+ Title: Configure Events Diagnostic settings for diagnostic logs and metrics export - Azure Health Data Services

+description: This article provides resources on how to configure Events Diagnostic settings for diagnostic logs and metrics exporting.

+# Configure Diagnostic settings for Events diagnostics logs and metrics exporting

+In this article, you'll be provided resources to configure the Events Diagnostic settings for Azure Event Grid system topics.

+After they're configured, Event Grid system topics diagnostic logs and metrics will be exported for audit, analysis, troubleshooting, or backup.

+## Resources

+|Description|Resource|

+|-|--|

+|Learn how to enable the Event Grid system topics diagnostic logging and metrics export feature.|[Enable diagnostic logs for Event Grid system topics](../../event-grid/enable-diagnostic-logs-topic.md#enable-diagnostic-logs-for-event-grid-system-topics)|

+|View a list of currently captured Event Grid system topics diagnostic logs.|[Event Grid system topic diagnostic logs](../../azure-monitor/essentials/resource-logs-categories.md#microsofteventgridsystemtopics)|

+|View a list of currently captured Event Grid system topics metrics.|[Event Grid system topic metrics](../../azure-monitor/essentials/metrics-supported.md#microsofteventgridsystemtopics)|

+|More information about how to work with diagnostics logs.|[Azure Resource Log documentation](../../azure-monitor/essentials/platform-logs-overview.md)|

+> [!Note]

+> It might take up to 15 minutes for the first Events diagnostic logs and metrics to display in the destination of your choice.

+## Next steps

+To learn how to display Events metrics in the Azure portal, see

+>[!div class="nextstepaction"]

+>[How to display Events metrics](./events-display-metrics.md)

+(FHIR&#174;) is a registered trademark of HL7 and is used with the permission of HL7.

+ Title: FAQs about Events in Azure Health Data Services

+description: This document provides answers to the frequently asked questions about Events.

+# Frequently asked questions (FAQs) about Events

+The following are some of the frequently asked questions about Events.

+## Events: The basics

+### Can I use Events with a different FHIR service other than the Azure Health Data Services FHIR service?

+No. The Azure Health Data Services Events feature only currently supports the Azure Health Data Services FHIR service.

+### What FHIR resource events does Events support?

+Events are generated from the following FHIR service types:

+- **FhirResourceCreated** - The event emitted after a FHIR resource gets created successfully.

+- **FhirResourceUpdated** - The event emitted after a FHIR resource gets updated successfully.

+- **FhirResourceDeleted** - The event emitted after a FHIR resource gets soft deleted successfully.

+For more information about the FHIR service delete types, see [FHIR Rest API capabilities for Azure Health Data Services FHIR service](../../healthcare-apis/fhir/fhir-rest-api-capabilities.md)

+### What is the payload of an Events message?

+For a detailed description of the Events message structure and both required and non-required elements, see [Events troubleshooting guide](events-troubleshooting-guide.md).

+### What is the throughput for the Events messages?

+The throughput of FHIR events is governed by the throughput of the FHIR service and the Event Grid. When a request made to the FHIR service is successful, it will return a 2xx HTTP status code. It will also generate a FHIR resource changing event. The current limitation is 5,000 events/second per a workspace for all FHIR service instances in it.

+### How am I charged for using Events?

+There are no extra charges for using Azure Health Data Services Events. However, applicable charges for the [Event Grid](https://azure.microsoft.com/pricing/details/event-grid/) might be assessed against your Azure subscription.

+### How do I subscribe to multiple FHIR services in the same workspace separately?

+You can use the Event Grid filtering feature. There are unique identifiers in the event message payload to differentiate different accounts and workspaces. You can find a global unique identifier for workspace in the `source` field, which is the Azure Resource ID. You can locate the unique FHIR account name in that workspace in the `data.resourceFhirAccount` field. When you create a subscription, you can use the filtering operators to select the events you want to get in that subscription.

+ :::image type="content" source="media\event-grid\event-grid-filters.png" alt-text="Screenshot of the Event Grid filters tab." lightbox="media\event-grid\event-grid-filters.png":::

+### Can I use the same subscriber for multiple workspaces or multiple FHIR accounts?

+Yes. We recommend that you use different subscribers for each individual FHIR accounts to process in isolated scopes.

+### Is Event Grid compatible with HIPAA and HITRUST compliance obligations?

+Yes. Event Grid supports customer's Health Insurance Portability and Accountability Act (HIPAA) and Health Information Trust Alliance (HITRUST) obligations. For more information, see [Microsoft Azure Compliance Offerings](https://azure.microsoft.com/resources/microsoft-azure-compliance-offerings/).

+ ### What is the expected time to receive an Events message?

+On average, you should receive your event message within one second after a successful HTTP request. 99.99% of the event messages should be delivered within five seconds unless the limitation of either the FHIR service or [Event Grid](../../event-grid/quotas-limits.md) has been met.

+### Is it possible to receive duplicate Events message?

+Yes. The Event Grid guarantees at least one Events message delivery with its push mode. There may be chances that the event delivery request returns with a transient failure status code for random reasons. In this situation, the Event Grid will consider that as a delivery failure and will resend the Events message. For more information, see [Azure Event Grid delivery and retry](../../event-grid/delivery-and-retry.md).

+Generally, we recommend that developers ensure idempotency for the event subscriber. The event ID or the combination of all fields in the ```data``` property of the message content are unique per each event. The developer can rely on them to de-duplicate.

+

+## More frequently asked questions

+[FAQs about the Azure Health Data Services](../healthcare-apis-faqs.md)

+[FAQs about Azure Health Data Services FHIR service](../fhir/fhir-faq.md)

+[FAQs about Azure Health Data Services DICOM service](../dicom/dicom-services-faqs.yml)

+[FAQs about Azure Health Data Services MedTech service](../iot/iot-connector-faqs.md)

+(FHIR&#174;) is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

+ Title: Events message structure - Azure Health Data Services

+description: In this article, you'll learn about Events message structure and required values.

+# Events message structure

+In this article, you'll learn about the Events message structure, required and non-required elements, and you'll be provided with samples of Events message payloads.

+> [!IMPORTANT]

+> Events currently supports only the following FHIR resource operations:

+>

+> - **FhirResourceCreated** - The event emitted after a FHIR resource gets created successfully.

+>

+> - **FhirResourceUpdated** - The event emitted after a FHIR resource gets updated successfully.

+>

+> - **FhirResourceDeleted** - The event emitted after a FHIR resource gets soft deleted successfully.

+>

+> For more information about the FHIR service delete types, see [FHIR Rest API capabilities for Azure Health Data Services FHIR service](../../healthcare-apis/fhir/fhir-rest-api-capabilities.md)

+## Events message structure

+|Name|Type|Required|Description|

+|-|-|--|--|

+|topic|string|Yes|The topic is the Azure Resource ID of your Healthcare APIs Workspace.|

+|subject|string|Yes|The Uniform Resource Identifier (URI) of the FHIR resource that was changed. Customer can access the resource with the subject with https:// scheme. Customer should use the dataVersion or data.resourceVersionId to visit specific data version regarding this event.|

+|eventType|string(enum)|Yes|The type of change on the FHIR resource.|

+|eventTime|string(datetime)|Yes|The UTC time when the FHIR resource change committed.|

+|id|string|Yes|Unique identifier for the event.|

+|data|object|Yes|FHIR resource change event details.|

+|data.resourceType|string(enum)|Yes|The FHIR Resource Type.|

+|data.resourceFhirAccount|string|Yes|The service name of FHIR account in the Healthcare APIs Workspace.|

+|data.resourceFhirId|string|Yes|The resource ID of the FHIR account. Note that this ID is randomly generated by the FHIR service of the Healthcare APIs when a customer creates the Resource. Customer can also use customized ID in FHIR resource creation; however the ID should **not** include or infer any PHI/PII information. It should be a system metadata, not specific to any personal data content.|

+|data.resourceVersionId|string(number)|Yes|The data version of the FHIR resource.|

+|dataVersion|string|No|Same as ΓÇ£data.resourceVersionIdΓÇ¥.|

+|metadataVersion|string|No|The schema version of the event metadata. This is defined by Azure Event Grid and should be constant most of the time.|

+## Events message samples

+### FhirResourceCreated event

+

+# [Event Grid event schema](#tab/event-grid-event-schema)

+

+```json

+{

+ "id": "e4c7f556-d72c-e7f7-1069-1e82ac76ab41",

+ "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e0a1f743-1a70-451f-830e-e96477163902",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e0a1f743-1a70-451f-830e-e96477163902",

+ "resourceVersionId": 1

+ },

+ "eventType": "Microsoft.HealthcareApis.FhirResourceCreated",

+ "dataVersion": "1",

+ "metadataVersion": "1",

+ "eventTime": "2021-09-08T01:14:04.5613214Z"

+}

+```

+# [CloudEvent schema](#tab/cloud-event-schema)

+

+```json

+{

+ "id": "d674b9b7-7d1c-9b0a-8c48-139f3eb86c48",

+ "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "specversion": "1.0",

+ "type": "Microsoft.HealthcareApis.FhirResourceCreated",

+ "dataschema": "#1",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "time": "2022-02-03T16:48:09.6223354Z",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "resourceVersionId": 1

+ }

+}

+```

+### FhirResourceUpdated event

+

+# [Event Grid event schema](#tab/event-grid-event-schema)

+

+```json

+{

+ "id": "634bd421-8467-f23c-b8cb-f6a31e41c32a",

+ "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e0a1f743-1a70-451f-830e-e96477163902",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e0a1f743-1a70-451f-830e-e96477163902",

+ "resourceVersionId": 2

+ },

+ "eventType": "Microsoft.HealthcareApis.FhirResourceUpdated",

+ "dataVersion": "2",

+ "metadataVersion": "1",

+ "eventTime": "2021-09-08T01:29:12.0618739Z"

+}

+```

+# [CloudEvent schema](#tab/cloud-event-schema)

+

+```json

+{

+ "id": "5e45229e-c663-ea98-72d2-833428f48ad0",

+ "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "specversion": "1.0",

+ "type": "Microsoft.HealthcareApis.FhirResourceUpdated",

+ "dataschema": "#2",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "time": "2022-02-03T16:48:33.5147352Z",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "resourceVersionId": 2

+ }

+}

+```

+### FhirResourceDeleted event

+

+# [Event Grid event schema](#tab/event-grid-event-schema)

+

+```json

+{

+ "id": "ef289b93-3159-b833-3a44-dc6b86ed1a8a",

+ "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e0a1f743-1a70-451f-830e-e96477163902",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e0a1f743-1a70-451f-830e-e96477163902",

+ "resourceVersionId": 3

+ },

+ "eventType": "Microsoft.HealthcareApis.FhirResourceDeleted",

+ "dataVersion": "3",

+ "metadataVersion": "1",

+ "eventTime": "2021-09-08T01:31:58.5175837Z"

+}

+```

+# [CloudEvent schema](#tab/cloud-event-schema)

+

+```json

+{

+ "id": "14648a6e-d978-950e-ee9c-f84c70dba8d3",

+ "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.HealthcareApis/workspaces/{workspace-name}",

+ "specversion": "1.0",

+ "type": "Microsoft.HealthcareApis.FhirResourceDeleted",

+ "dataschema": "#3",

+ "subject": "{fhir-account}.fhir.azurehealthcareapis.com/Patient/e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "time": "2022-02-03T16:48:38.7338799Z",

+ "data": {

+ "resourceType": "Patient",

+ "resourceFhirAccount": "{fhir-account}.fhir.azurehealthcareapis.com",

+ "resourceFhirId": "e87ef649-abe1-485c-8c09-549d85dfe30b",

+ "resourceVersionId": 3

+ }

+}

+```

+## Next steps

+For more information about deploying Events, see:

+>[!div class="nextstepaction"]

+>[Deploying Events in the Azure portal](./events-deploy-portal.md)

+(FHIR&#174;) is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

+ Title: What are Events? - Azure Health Data Services

+description: In this article, you'll learn about Events, its features, integrations, and next steps.

+# What are Events?

+Events are a notification and subscription feature in the Azure Health Data Services. Events enable customers to utilize and enhance the analysis and workflows of structured and unstructured data like vitals and clinical or progress notes, operations data, and Internet of Medical Things (IoMT) health data. When Fast Healthcare Interoperability Resources (FHIR&#174;) resource changes are successfully written to the Azure Health Data Services FHIR service, the Events feature sends notification messages to Events subscribers. These event notification occurrences can be sent to multiple endpoints to trigger automation ranging from starting workflows to sending email and text messages to support the changes occurring from the health data it originated from. The Events feature integrates with the [Azure Event Grid service](../../event-grid/overview.md) and creates a system topic for the Azure Health Data Services Workspace.

+> [!IMPORTANT]

+>

+> FHIR resource change data is only written and event messages are sent when the Events feature is turned on. The Event feature doesn't send messages on past FHIR resource changes or when the feature is turned off.

+> [!TIP]

+>

+> For more information about the features, configurations, and to learn about the use cases of the Azure Event Grid service, see [Azure Event Grid](../../event-grid/overview.md)

+> [!IMPORTANT]

+>

+> Events currently supports only the following FHIR resource operations:

+>

+> - **FhirResourceCreated** - The event emitted after a FHIR resource gets created successfully.

+>

+> - **FhirResourceUpdated** - The event emitted after a FHIR resource gets updated successfully.

+>

+> - **FhirResourceDeleted** - The event emitted after a FHIR resource gets soft deleted successfully.

+>

+> For more information about the FHIR service delete types, see [FHIR Rest API capabilities for Azure Health Data Services FHIR service](../../healthcare-apis/fhir/fhir-rest-api-capabilities.md)

+## Scalable

+Events are designed to support growth and changes in healthcare technology needs by using the [Azure Event Grid service](../../event-grid/overview.md) and creating a system topic for the Azure Health Data Services Workspace.

+## Configurable

+Choose the FHIR resources that you want to receive messages about. Use the advanced features like filters, dead-lettering, and retry policies to tune Events message delivery options.

+> [!NOTE]

+> The advanced features come as part of the Event Grid service.

+## Extensible

+Use Events to send FHIR resource change messages to services like [Azure Event Hubs](../../event-hubs/event-hubs-about.md) or [Azure Functions](../../azure-functions/functions-overview.md) to trigger downstream automated workflows to enhance items such as operational data, data analysis, and visibility to the incoming data capturing near real time.

+

+## Secure

+Built on a platform that supports protected health information (PHI) and personal identifiable information (PII) data compliance with privacy, safety, and security in mind, the Events messages do not transmit sensitive data as part of the message payload.

+Use [Azure Managed identities](../../active-directory/managed-identities-azure-resources/overview.md) to provide secure access from your Event Grid system topic to the Events message receiving endpoints of your choice.

+## Next steps

+For more information about deploying Events, see

+>[!div class="nextstepaction"]

+>[Deploying Events in the Azure portal](./events-deploy-portal.md)

+For frequently asks questions (FAQs) about Events, see

+>[!div class="nextstepaction"]

+>[Frequently asked questions about Events](./events-faqs.md)

+For Events troubleshooting resources, see

+>[!div class="nextstepaction"]

+>[Events troubleshooting guide](./events-troubleshooting-guide.md)

+(FHIR&#174;) is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.