+## Pass the IDP refresh token (optional)

+The access token the identity provider returns is valid for a short period of time. Some identity providers also issue a refresh token along with the access token. Your client application can then exchange the identity provider's refresh token for a new access token when needed.

+Azure AD B2C custom policy supports passing the refresh token of OAuth 2.0 identity providers, which includes [Facebook](https://github.com/azure-ad-b2c/unit-tests/tree/main/Identity-providers#facebook-with-access-token), [Google](https://github.com/azure-ad-b2c/unit-tests/tree/main/Identity-providers#facebook-with-access-token) and [GitHub](https://github.com/azure-ad-b2c/unit-tests/tree/main/Identity-providers#github-with-access-token).

+To pass the identity provider's refresh token, follow these steps:

+1. Open your *TrustframeworkExtensions.xml* file and add the following **ClaimType** element with an identifier of `identityProviderRefreshToken` to the **ClaimsSchema** element.

+

+ ```xml

+ <ClaimType Id="identityProviderRefreshToken">

+ <DisplayName>Identity provider refresh token</DisplayName>

+ <DataType>string</DataType>

+ </ClaimType>

+ ```

+

+1. Add the **OutputClaim** element to the **TechnicalProfile** element for each OAuth 2.0 identity provider that you would like the refresh token for. The following example shows the element added to the Facebook technical profile:

+

+ ```xml

+ <ClaimsProvider>

+ <DisplayName>Facebook</DisplayName>

+ <TechnicalProfiles>

+ <TechnicalProfile Id="Facebook-OAUTH">

+ <OutputClaims>

+ <OutputClaim ClaimTypeReferenceId="identityProviderRefreshToken" PartnerClaimType="{oauth2:refresh_token}" />

+ </OutputClaims>

+ ...

+ </TechnicalProfile>

+ </TechnicalProfiles>

+ </ClaimsProvider>

+ ```

+1. Some identity providers require you to include metadata or scopes to the identity provider's technical profile.

+ - For Google identity provider, add two claim types `access_type` and `prompt`. Then add the following input claims to the identity provider's technical profile:

+ ```xml

+ <InputClaims>

+ <InputClaim ClaimTypeReferenceId="access_type" PartnerClaimType="access_type" DefaultValue="offline" AlwaysUseDefaultValue="true" />

+

+ <!-- The refresh_token is return only on the first authorization for a given user. Subsequent authorization request doesn't return the refresh_token.

+ To fix this issue we add the prompt=consent query string parameter to the authorization request-->

+ <InputClaim ClaimTypeReferenceId="prompt" PartnerClaimType="prompt" DefaultValue="consent" AlwaysUseDefaultValue="true" />

+ </InputClaims>

+ ```

+

+ - Other identity providers may have different methods to issue a refresh token. Follow the identity provider's audience and add the necessary elements to your identity provider's technical profile.

+1. Save the changes you made in your *TrustframeworkExtensions.xml* file.

+1. Open your relying party policy file, such as *SignUpOrSignIn.xml*, and add the **OutputClaim** element to the **TechnicalProfile**:

+ ```xml

+ <RelyingParty>

+ <DefaultUserJourney ReferenceId="SignUpOrSignIn" />

+ <TechnicalProfile Id="PolicyProfile">

+ <OutputClaims>

+ <OutputClaim ClaimTypeReferenceId="identityProviderRefreshToken" PartnerClaimType="idp_refresh_token"/>

+ </OutputClaims>

+ ...

+ </TechnicalProfile>

+ </RelyingParty>

+ ```

+1. Save the changes you made in your policy's relying party policy file.

+1. Upload the *TrustframeworkExtensions.xml* file, and then the relying party policy file.

+1. [Test your policy](#test-your-policy)

+

+

+ Title: Configure Haventec Authenticate with Azure Active Directory B2C for single-step, multi-factor passwordless authentication

+description: Learn to integrate Azure AD B2C with Haventec Authenticate for multi-factor passwordless authentication

+# Tutorial: Configure Haventec Authenticate with Azure Active Directory B2C for single-step, multi-factor passwordless authentication

+Learn to integrate Azure Active Directory B2C (Azure AD B2C) with Haventec Authenticate, a passwordless technology that eliminates passwords, shared secrets, and friction.

+To learn more, go to haventec.com: [Haventec](https://www.haventec.com/)

+## Scenario description

+The Authenticate integration includes the following components:

+* **Azure AD B2C** - authorization server that verifies user credentials

+ * Also known as the identity provider (IdP)

+* **Web and mobile applications** - Open ID Connect (OIDC) mobile or web applications protected by Authenticate and Azure AD B2C

+* **Haventec Authenticate service** - external IdP for the Azure AD B2C tenant

+The following diagram illustrates sign-up and sign-in user flows in the Haventec Authenticate integration.

+ 

+1. User selects sign-in or sign-up and enters a username.

+2. The application sends user attributes to Azure AD B2C for identity verification.

+3. Azure AD B2C collects user attributes and sends them to Haventec Authenticate.

+4. For new users, Authenticate sends push notification to the user mobile device. It can send email with a one-time password (OTP) for device registration.

+5. User responds and is granted or denied access. New cryptographic keys are pushed to the user device for a future session.

+## Get started with Authenticate

+Go to the haventec.com [Get a demo of Haventec Authenticate](https://www.haventec.com/products/get-started) page. In the personalized demo request form, indicate your interest in Azure AD B2C integration. An email arrives when the demo environment is ready.

+## Integrate Authenticate with Azure AD B2C

+Use the following instructions to prepare for and integrate Azure AD B2C with Authenticate.

+To get started, you need:

+* An Azure AD subscription

+ * If you don't have one, get an [Azure free account](https://azure.microsoft.com/free/)

+* An Azure AD B2C tenant linked to the Azure subscription

+ * see, [Tutorial: Create an Azure Active Directory B2C tenant](tutorial-create-tenant.md)

+* A Haventec Authenticate demo environment

+ * See, [Get a demo of Haventec Authenticate](https://www.haventec.com/products/get-started)

+### Create a web application registration

+Before applications can interact with Azure AD B2C, register them in a tenant you manage.

+See, [Tutorial: Register a web application in Azure Active Directory B2C](tutorial-register-applications.md)

+### Add a new identity provider in Azure AD B2C

+For the following instructions, use the directory with the Azure AD B2C tenant.

+1. Sign in to the [Azure portal](https://portal.azure.com/#home) as the Global Administrator of your Azure AD B2C tenant.

+2. In the top menu, select **Directory + subscription**.

+3. Select the directory with the tenant.

+4. In the top-left corner of the Azure portal, select **All services**.

+5. Search for and select **Azure AD B2C**.

+6. Navigate to **Dashboard** > **Azure Active Directory B2C** > **Identity providers**.

+7. Select **New OpenID Connect Provider**.

+8. Select **Add**.

+### Configure an identity provider

+To configure an identity provider:

+1. Select **Identity provider type** > **OpenID Connect**.

+2. For **Name**, enter **Haventec**, or another name.

+3. For **Metadata URL**, use `https://iam.demo.haventec.com/auth/realms/*your\_realm\_name*/.well-known/openid-configuration`.

+4. For **Client ID**, enter the application ID recorded from the Haventec admin UI.

+5. For **Client Secret**, enter the application Secret recorded from the Haventec admin UI.

+6. For **Scope**, select **OpenID email profile**.

+7. For **Response type**, select **Code**.

+8. For **Response mode**, select **forms_post**.

+9. For **Domain hint**, leave blank.

+10. Select **OK**.

+11. Select **Map this identity provider's claims**.

+12. For **User ID**, select **From subscription**.

+13. For **Display** name, select **From subscription**.

+14. For **Given name**, use **given_name**.

+15. For **Surname**, use **family_name**.

+16. For **Email**, use **Email**.

+17. Select **Save**.

+For the following instructions, Haventec is a new OIDC identity provider in the B2C identity providers list.

+1. In the Azure AD B2C tenant, under **Policies**, select **User flows**.

+4. Enter a **Name** for the policy.

+5. In **Identity providers**, select the created Haventec identity provider.

+6. For **Local Accounts**, select **None**. This selection disables email and password authentication.

+7. Select **Run user flow**.

+8. In the form, enter the replying URL, for example, `https://jwt.ms`.

+9. The browser redirects to the Haventec sign-in page.

+10. User is prompted to register, or enter a PIN.

+11. The authentication challenge is performed.

+12. The browser redirects to the replying URL.

+1. In the Azure AD B2C tenant, under **Policies**, select **User flows**.

+2. Select the created **User Flow**.

+3. Select **Run user flow**.

+4. For **Application**, select the registered app. The example is JWT.

+5. For **Reply URL**, select the redirect URL.

+6. Select **Run user flow**.

+7. Perform a sign-up flow and create an account.

+8. Haventec Authenticate is called.

+## Next steps

+* Go to docs.haventec.com for [Haventec Documentation](https://docs.haventec.com/)

+* [Azure AD B2C custom policy overview](custom-policy-overview.md)

+ Title: Tutorial to configure Nok Nok Passport with Azure Active Directory B2C for passwordless FIDO2 authentication

+description: Configure Nok Nok Passport with Azure AD B2C to enable passwordless FIDO2 authentication

+# Tutorial: Configure Nok Nok Passport with Azure Active Directory B2C for passwordless FIDO2 authentication

+Learn to integrate the Nok Nok S3 Authentication Suite into your Azure Active Directory B2C (Azure AD B2C) tenant. Nok Nok solutions enable FIDO certified multi-factor authentication such as FIDO UAF, FIDO U2F, WebAuthn, and FIDO2 for mobile and web applications. Nok Nok solutions improve security posture while balancing user experience.

+To to noknok.com to learn more: [Nok Nok Labs, Inc.](https://noknok.com/)

+## Prerequisites

+To get started, you need:

+* An Azure subscription

+ * If you don't have one, get a [Azure free account](https://azure.microsoft.com/free/)

+* An Azure AD B2C tenant linked to the Azure subscription

+ * [Tutorial: Create an Azure Active Directory B2C tenant](tutorial-create-tenant.md)

+* Go to [noknok.com](https://noknok.com/products/strong-authentication-service/). On the top menu, select **Demo**.

+To enable passwordless FIDO authentication for your users, enable Nok Nok as an identity provider (IdP) in your Azure AD B2C tenant. Nok Nok solution integration includes the following components:

+* **Azure AD B2C** ΓÇô authorization server that verifies user credentials

+* **Web and mobile applications** ΓÇô mobile or web apps to protect with Nok Nok solutions and Azure AD B2C

+* **Nok Nok app SDK or Passport app** ΓÇô authenticate Azure AD B2C enabled applications.

+ * Go to the Apple App Store for [Nok Nok Passport](https://apps.apple.com/us/app/nok-nok-passport/id1050437340)

+ * Or, Google Play [Nok Nok Passport](https://play.google.com/store/apps/details?id=com.noknok.android.passport2&hl=en&gl=US)

+The following diagram illustrates the Nok Nok solution as IdP for Azure AD B2C using Open ID Connect (OIDC) for passwordless authentication.

+ 

+1. At the sign-in page, user selects sign-in or sign-up and enters the username.

+2. Azure AD B2C redirects user to the Nok Nok OIDC authentication provider.

+3. For mobile authentications, a QR code appears or push notification goes to the user device. For desktop sign-in, the user is redirected to the web app sign-in page for passwordless authentication.

+4. User scans the QR code with Nok Nok app SDK or Passport app. Or, username is sign-in page input.

+5. User is prompted for authentication. User does passwordless authentication: biometrics, device PIN, or any roaming authenticator. Authentication prompt appears on web application. User does passwordless authentication: biometrics, device PIN, or any roaming authenticator.

+6. Nok Nok server validates FIDO assertion and sends OIDC authentication response to Azure AD B2C.

+7. User is granted or denied access.

+## Get started with Nok Nok

+1. Go to the noknok.com [Contact](https://noknok.com/contact/) page.

+2. Fill out the form for a Nok Nok tenant.

+3. An email arrives with tenant access information and links to documentation.

+4. Use the Nok Nok integration documentation to complete the tenant OIDC configuration.

+Use the following instructions to add and configure an IdP then configure a user flow.

+For the following instructions, use the directory with the Azure AD B2C tenant. To add a new IdP:

+1. Sign in to the **[Azure portal](https://portal.azure.com/#home)** as Global Administrator of the Azure AD B2C tenant.

+2. In the portal toolbar, select the **Directories + subscriptions**.

+3. On **Portal settings, Directories + subscriptions**, in the **Directory name** list, locate the Azure AD B2C directory.

+4. Select **Switch**.

+5. In the top-left corner of the Azure portal, select **All services**.

+6. Search for and select **Azure AD B2C**.

+7. Navigate to **Dashboard** > **Azure Active Directory B2C** > **Identity providers**.

+8. Select **Identity providers**.

+9. Select **Add**.

+To configure an IdP:

+1. Select **Identity provider type** > **OpenID Connect (Preview)**.

+2. For **Name**, enter Nok Nok Authentication Provider, or another name.

+3. For **Metadata URL**, enter hosted Nok Nok Authentication app URI, followed by the path such as `https://demo.noknok.com/mytenant/oidc/.well-known/openid-configuration`

+4. For **Client Secret**, use the Client Secret from Nok Nok.

+5. For **Client ID**, use the client ID provided by Nok Nok.

+6. For **Scope**, use **OpenID profile email**.

+7. For **Response type**, use **code**.

+8. For **Response mode**, use **form_post**.

+9. Select **OK**.

+10. Select **Map this identity providerΓÇÖs claims**.

+11. For **UserID**, select **From subscription**.

+12. For **Display name**, select **From subscription**.

+13. For **Response mode**, select **From subscription**.

+14. Select **Save**.

+For the following instructions, Nok Nok is a new OIDC IdP in the B2C identity providers list.

+2. Select **New**.

+3. Select **Sign up and sign in**.

+4. Select a **version**.

+5. Select **Create**.

+6. Enter a policy **Name**.

+7. In **Identity providers**, select the created Nok Nok IdP.

+8. You can add an email address. Azure won't redirect sign-in to Nok Nok; a screen appears with user options.

+9. Leave the **Multi-factor Authentication** field.

+10. Select **Enforce conditional access policies**.

+11. Under **User attributes and token claims**, in the Collect attribute option, select **Email Address**.

+12. Add user attributes for Azure AD to collect, with claims that Azure AD B2C returns to the client application.

+13. Select **Create**.

+14. Select the new **User flow**.

+15. On the left panel, select **Application Claims**.

+16. Under options, select the **email** checkbox

+17. Select **Save**.

+1. Open the Azure AD B2C tenant and under **Policies** select **Identity Experience Framework**.

+2. Select the created **SignUpSignIn**.

+3. Select **Run user flow**.

+4. For **Application**, select the registered app. The example is JWT.

+5. For **Reply URL**, select the redirect URL.

+6. Select **Run user flow**.

+7. Perform a sign-up flow and create an account.

+8. After the user attribute is created, Nok Nok is called.

+If the flow is incomplete, confirm the user is or isn't saved in the directory.

+* [Azure AD B2C custom policy overview](./custom-policy-overview.md)

+* [Tutorial: Create user flows and custom policies in Azure Active Directory B2C](tutorial-create-user-flows.md?pivots=b2c-custom-policy)

+You need to create the **RelyingParty** child elements in the order presented in the preceding table.

+A "web application" refers to a traditional web application that performs most of the application logic on the server. They may be built using frameworks like ASP.NET Core, Spring (Java), Flask (Python), and Express (Node.js).

+description: An introduction to how you can use Azure Active Directory to automatically provision, deprovision, and continuously update user accounts across multiple third-party applications.

+Azure AD features preintegrated support for many popular SaaS apps and human resources systems, and generic support for apps that implement specific parts of the [SCIM 2.0 standard](https://techcommunity.microsoft.com/t5/Identity-Standards-Blog/Provisioning-with-SCIM-getting-started/ba-p/880010).

+* **Preintegrated applications (gallery SaaS apps)**: You can find all applications for which Azure AD supports a preintegrated provisioning connector in [Tutorials for integrating SaaS applications with Azure Active Directory](../saas-apps/tutorial-list.md). The preintegrated applications listed in the gallery generally use SCIM 2.0-based user management APIs for provisioning.

+For preintegrated applications listed in the gallery, use existing step-by-step guidance to set up automatic provisioning, see [Tutorials for integrating SaaS applications with Azure Active Directory](../saas-apps/tutorial-list.md). The following video shows you how to set up automatic user provisioning for SalesForce.

+ :::image type="content" source="./media/application-proxy-configure-complex-application/add-application-segment-1.png" alt-text="Screenshot of Manage and configure application segment blade.":::

+6. Add CORS Rules (optional). For more information see [Configuring CORS Rule](/graph/api/resources/corsconfiguration_v2?view=graph-rest-beta).

+Azure AD CBA can be used as a second factor to meet MFA requirements with single-factor certificates.

+Some of the supported combintaions are

+1. CBA (first factor) + passwordless phone sign-in (PSI as second factor)

+1. CBA (first factor) + FIDO2 security keys (second factor)

+1. Password (first factor) + CBA (second factor)

+>A user will be considered MFA capable when a user is in scope for Certificate-based authentication auth method. This means user will not be able to use proof up as part of their authentication to registerd other available methods. Make sure users who do not have a valid certificate are not part of CBA auth method scope. More info on [Azure AD MFA](../authentication/concept-mfa-howitworks.md)

+> [!NOTE]

+> Currently, Microsoft Azure and Google Cloud Platform (GCP) do not provide significant information about access keys to return access keys data. Access Keys analytics are currently only available for Amazon Web Services (AWS) accounts.

+ - **Authorization System Type**: Select **AWS**.

+ - **Authorization System**: Select from a **List** of accounts and **Folders**.

+1. From the **Authorization System Type** dropdown, select **AWS**.

+1. From the **Authorization System Type** dropdown, select **AWS**.

+1. From the **Authorization System Type** dropdown, select **AWS**.

+1. From the **Authorization System Type** dropdown, select **AWS**.

+1. From the **Authorization System Type** dropdown, select **AWS**.

+1. From the **Authorization System Type** dropdown, select **AWS**.

+The following short video provides an excellent overview of the Azure AD custom extensions and custom claims providers:

+> [!VIDEO https://www.youtube.com/embed/BYOMshjlwbc]

+This how-to guide demonstrates the token issuance start event with a REST API running in Azure Functions and a sample OpenID Connect application. Before you start, take a look at following video, which demonstrates how to configure Azure AD custom claims provider with Function App:

+> [!VIDEO https://www.youtube.com/embed/r-JEsMBJ7GE]

+1. In the [Azure portal](https://portal.azure.com), navigate and select the function app you previously published.

+1. In the [Azure portal](https://portal.azure.com), navigate and select the function app you previously published.

+ Follow the [remediation guidance](#mpnaccountnotfoundornoaccess).

+**Remediation Steps**

+1. Go to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile) and verify that:

+ - The MPN ID is correct.

+ - There are no errors or ΓÇ£pending actionsΓÇ¥ shown, and the verification status under Legal business profile and Partner info both say ΓÇ£authorizedΓÇ¥ or ΓÇ£successΓÇ¥.

+2. Go to the [MPN tenant management page](https://partner.microsoft.com/dashboard/account/v3/tenantmanagement) and confirm that the tenant the app is registered in and that you're signing with a user account from is on the list of associated tenants. To add another tenant, follow the [multi-tenant-account instructions](/partner-center/multi-tenant-account). Be aware that all Global Admins of any tenant you add will be granted Global Administrator privileges on your Partner Center account.

+3. Go to the [MPN User Management page](https://partner.microsoft.com/pcv/users) and confirm the user you're signing in as is either a Global Administrator, MPN Admin, or Accounts Admin. To add a user to a role in Partner Center, follow the instructions for [creating user accounts and setting permissions](/partner-center/create-user-accounts-and-set-permissions).

+**Remediation Steps**

+1. Navigate to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile) > Identifiers blade > Microsoft Cloud Partners Program Tab

+2. Use the Partner ID with type PartnerGlobal

+**Remediation Steps**

+1. Navigate to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile) > Identifiers blade > Microsoft Cloud Partners Program Tab

+2. Use the Partner ID with type PartnerGlobal

+**Remediation Steps**

+1. Navigate to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile) and verify that there are no errors or **pending actions** shown, and that the verification status under Legal business profile and Partner info both say **authorized** or **success**.

+2. If not, view pending action items in Partner Center and troubleshoot with [here](/partner-center/verification-responses)

+**Remediation Steps**

+1. Navigate to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile) > Identifiers blade > Microsoft Cloud Partners Program Tab

+2. Use the Partner ID with type PartnerGlobal

+**Remediation Steps**

+1. Navigate to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile) > Identifiers blade > Microsoft Cloud Partners Program Tab

+2. Use the Partner ID with type PartnerGlobal

+Most commonly caused when verification is being performed via Graph API, and the ID of the application provided is incorrect.

+**Remediation Steps**

+1. The Object ID of the application must be provided, not the AppId/ClientId. See **id** on the list of application properties [here](/graph/api/resources/application)

+2. Log in to [Azure Active Directory](https://aad.portal.azure.com/) with a user account in your organization's primary tenant > Azure Active Directory > App Registrations blade

+3. Find your app's registration to view the Object ID

+**Remediation Steps**

+1. The Object ID of the application must be provided, not the AppId/ClientId. See **id** on the list of application properties [here](/graph/api/resources/application)

+2. Log in to [Azure Active Directory](https://aad.portal.azure.com/) with a user account in your organization's primary tenant > Azure Active Directory > App Registrations blade

+3. Find your app's registration to view the Object ID

+**Remediation Steps**

+1. Follow the directions [here](/azure/active-directory/develop/howto-configure-publisher-domain#set-a-publisher-domain-in-the-azure-portal) to set a Publisher Domain

+**Remediation Steps**

+1. Navigate to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile), and view the email listed as Primary Contact

+2. The domain used to perform email verification in Partner Center is the portion after the ΓÇ£@ΓÇ¥ in the Primary ContactΓÇÖs email

+3. Log in to [Azure Active Directory](https://aad.portal.azure.com/) > Azure Active Directory > App Registrations blade > (`Your App`) > Branding and Properties

+4. Select **Update Publisher Domain** and follow the instructions to **Verify a New Domain**.

+5. Add the domain used to perform email verification in Partner Center as a New Domain

+**Remediation Steps**

+1. Sign in to the [Azure AD Portal](https://aad.portal.azure.com) using a user account in your organization's primary tenant.

+2. Navigate to [Role Management](https://aad.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RolesAndAdministrators).

+3. Select the desired admin role and click ΓÇ£Add AssignmentΓÇ¥ if you have sufficient permissions.

+4. If you do not have sufficient permissions, contact an admin role for assistance

+**Remediation Steps**

+1. Navigate to your [partner profile](https://partner.microsoft.com/pcv/accountsettings/connectedpartnerprofile) > Identifiers blade > Microsoft Cloud Partners Program Tab

+2. Use the Partner ID with type PartnerGlobal in the request

+**Remediation Steps**

+1. Ensure [multi-factor authentication](../fundamentals/concept-fundamentals-mfa-get-started.md) is enabled and **required** for the user you're signing in with and for this scenario

+2. Retry Publisher Verification

+**Remediation Steps**

+>

+>

+>

+>

+- Error code and message being returned

+GET /v1.0/users

+curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...." 'https://graph.microsoft.com/v1.0/users'

+- Autopilot

+- **Additional local administrators on Azure AD joined devices**: This setting allows you to select the users who are granted local administrator rights on a device. These users are added to the Device Administrators role in Azure AD. Global Administrators in Azure AD and device owners are granted local administrator rights by default.

+This option is a premium edition capability available through products like Azure AD Premium and Enterprise Mobility + Security.

+- **Restrict non-admin users from recovering the BitLocker key(s) for their owned devices (preview)**: In this preview, admins can block self-service BitLocker key access to the registered owner of the device. Default users without the BitLocker read permission will be unable to view or copy their BitLocker key(s) for their owned devices.

+When a Microsoft CSP creates a GDAP relationship request for your tenant a global administrator needs to approve the request. The GDAP relationship request specifies:

+If you have GDAP relationships in your tenant, you will see a notification banner on the **Delegated Administration** page in the Azure AD admin portal. Select the notification banner to see and manage GDAP relationships in the **Partners** page in Microsoft Admin Center.

+All DAP relationships enable the CSP to delegate Global administrator and Helpdesk administrator roles to their technicians. Unlike a GDAP relationship, a DAP relationship persists until they are revoked either by you or by your CSP.

+If you're a beginning Azure AD administrator, get the basics down in [Azure Active Directory Fundamentals](../fundamentals/index.yml).

+- [Delegated administration privileges (DAP) FAQ](/partner-center/dap-faq)

+- [Granular delegated admin privileges (GDAP) introduction](/partner-center/gdap-introduction)

+Secure Shell (SSH) is a network protocol that provides encryption for operating network services securely over an unsecured network. It's commonly used in systems like Unix and Linux. SSH replaces the Telnet protocol, which doesn't provide encryption in an unsecured network.

+| Unit testing | Unit test and generate tokens. </br>See, [Microsoft identity platform and OAuth 2.0 Resource Owner Password Credentials](../develop/v2-oauth-ropc.md). </br>If you reach the Azure AD B2C token limit, see [Azure AD B2C: File Support Requests](../../active-directory-b2c/find-help-open-support-ticket.md). </br>Reuse tokens to reduce investigation on your infrastructure. </br>[Set up a resource owner password credentials flow in Azure Active Directory B2C](../../active-directory-b2c/add-ropc-policy.md?pivots=b2c-user-flow&tabs=app-reg-ga).|

+| **Restrict non-admin users from reading BitLocker key(s) for their owned devices** | Setting this option to **Yes** restricts users from being able to self-service recover BitLocker key(s) for their owned devices. Setting this option to **No** allows users to recover their BitLocker key(s). |

+For more information, see: [Block users from viewing their BitLocker keys (preview)](../devices/device-management-azure-portal.md#configure-device-settings)

+2. The authentication method is a critical component of an organization's presence in the cloud. It controls access to all cloud data and resources.

+Identity is the new control plane of IT security, so authentication is an organization's access guard to the new cloud world. Organizations need an identity control plane that strengthens their security and keeps their cloud apps safe from intruders.

+> Changing your authentication method requires planning, testing, and potentially downtime. [Staged rollout](./how-to-connect-staged-rollout.md) is a great way to test users' migration from federation to cloud authentication.

+Organizations that don't have an existing on-premises directory footprint aren't the focus of this article. Typically, those businesses create identities only in the cloud, which doesn't require a hybrid identity solution. Cloud-only identities exist solely in the cloud and aren't associated with corresponding on-premises identities.

+When the Azure AD hybrid identity solution is your new control plane, authentication is the foundation of cloud access. Choosing the correct authentication method is a crucial first decision in setting up an Azure AD hybrid identity solution. The authentication method you choose, is configured by using Azure AD Connect, which also provisions users in the cloud.

+When you choose this authentication method, Azure AD handles users' sign-in process. Coupled with single sign-on (SSO), users can sign in to cloud apps without having to reenter their credentials. With cloud authentication, you can choose from two options:

+**Azure AD password hash synchronization**. The simplest way to enable authentication for on-premises directory objects in Azure AD. Users can use the same username and password that they use on-premises without having to deploy any other infrastructure. Some premium features of Azure AD, like Identity Protection and [Azure AD Domain Services](../../active-directory-domain-services/tutorial-create-instance.md), require password hash synchronization, no matter which authentication method you choose.

+When you choose this authentication method, Azure AD hands off the authentication process to a separate trusted authentication system, such as on-premises Active Directory Federation Services (AD FS), to validate the user's password.

+The authentication system can provide other advanced authentication requirements, for example, third-party multifactor authentication.

+2. Azure AD can hand off user sign-in to a trusted authentication provider such as Microsoft's AD FS.

+* **User experience**. To improve users' sign-in experience, use [Azure AD joined devices (AADJ)](../../active-directory/devices/concept-azure-ad-join.md) or [Hybrid Azure AD joined devices (HAADJ)](../../active-directory/devices/howto-hybrid-azure-ad-join.md). If you can't join your Windows devices to Azure AD, we recommend deploying seamless SSO with password hash synchronization. Seamless SSO eliminates unnecessary prompts when users are signed in.

+* **Business continuity**. Using password hash synchronization with cloud authentication is highly available as a cloud service that scales to all Microsoft datacenters. To make sure password hash synchronization doesn't go down for extended periods, deploy a second Azure AD Connect server in staging mode in a standby configuration.

+* **User experience**. To improve users' sign-in experience, use [Azure AD joined devices (AADJ)](../../active-directory/devices/concept-azure-ad-join.md) or [Hybrid Azure AD joined devices (HAADJ)](../../active-directory/devices/howto-hybrid-azure-ad-join.md). If you can't join your Windows devices to Azure AD, we recommend deploying seamless SSO with password hash synchronization. Seamless SSO eliminates unnecessary prompts when users are signed in.

+* **Advanced scenarios**. Pass-through Authentication enforces the on-premises account policy at the time of sign-in. For example, access is denied when an on-premises user's account state is disabled, locked out, or their [password expires](../../active-directory/hybrid/how-to-connect-pta-faq.yml#what-happens-if-my-user-s-password-has-expired-and-they-try-to-sign-in-by-using-pass-through-authentication-) or the logon attempt falls outside the hours when the user is allowed to sign in.

+* **Business continuity**. We recommend that you deploy two extra pass-through authentication agents. These extras are in addition to the first agent on the Azure AD Connect server. This other deployment ensures high availability of authentication requests. When you have three agents deployed, one agent can still fail when another agent is down for maintenance.

+ * Third-party multifactor providers requiring a federated identity provider.

+For a nonroutable domain that can't be verified in Azure AD, you need extra configuration to implement user ID sign in. This requirement is known as Alternate login ID support. See [Configuring Alternate Login ID](/windows-server/identity/ad-fs/operations/configuring-alternate-login-id) for limitations and requirements. If you choose to use a third-party multi-factor authentication provider with federation, ensure the provider supports WS-Trust to allow devices to join Azure AD.

+|Consideration|Password hash synchronization|Pass-through Authentication|Federation with AD FS|

+|Where does authentication happen?|In the cloud|In the cloud, after a secure password verification exchange with the on-premises authentication agent|On-premises|

+|Do users get single sign-on to cloud resources from domain-joined devices within the company network?|Yes with [Azure AD joined devices (AADJ)](../../active-directory/devices/concept-azure-ad-join.md), [Hybrid Azure AD joined devices (HAADJ)](../../active-directory/devices/howto-hybrid-azure-ad-join.md), the [Microsoft Enterprise SSO plug-in for Apple devices](../../active-directory/develop/apple-sso-plugin.md), or [Seamless SSO](../../active-directory/hybrid/how-to-connect-sso.md)|Yes with [Azure AD joined devices (AADJ)](../../active-directory/devices/concept-azure-ad-join.md), [Hybrid Azure AD joined devices (HAADJ)](../../active-directory/devices/howto-hybrid-azure-ad-join.md), the [Microsoft Enterprise SSO plug-in for Apple devices](../../active-directory/develop/apple-sso-plugin.md), or [Seamless SSO](../../active-directory/hybrid/how-to-connect-sso.md)|Yes|

+|What sign-in types are supported?|UserPrincipalName + password<br><br>Windows-Integrated Authentication by using [Seamless SSO](../../active-directory/hybrid/how-to-connect-sso.md)<br><br>[Alternate login ID](../../active-directory/hybrid/how-to-connect-install-custom.md)<br><br>[Azure AD Joined Devices](../../active-directory/devices/concept-azure-ad-join.md)<br><br>[Hybrid Azure AD joined devices (HAADJ)](../../active-directory/devices/howto-hybrid-azure-ad-join.md)<br><br>[Certificate and smart card authentication](../../active-directory/authentication/concept-certificate-based-authentication-smartcard.md)|UserPrincipalName + password<br><br>Windows-Integrated Authentication by using [Seamless SSO](../../active-directory/hybrid/how-to-connect-sso.md)<br><br>[Alternate login ID](../../active-directory/hybrid/how-to-connect-pta-faq.yml)<br><br>[Azure AD Joined Devices](../../active-directory/devices/concept-azure-ad-join.md)<br><br>[Hybrid Azure AD joined devices (HAADJ)](../../active-directory/devices/howto-hybrid-azure-ad-join.md)<br><br>[Certificate and smart card authentication](../../active-directory/authentication/concept-certificate-based-authentication-smartcard.md)|UserPrincipalName + password<br><br>sAMAccountName + password<br><br>Windows-Integrated Authentication<br><br>[Certificate and smart card authentication](/windows-server/identity/ad-fs/operations/configure-user-certificate-authentication)<br><br>[Alternate login ID](/windows-server/identity/ad-fs/operations/configuring-alternate-login-id)|

+|What are the multifactor authentication options?|[Azure AD MFA](/azure/multi-factor-authentication/)<br><br>[Custom Controls with Conditional Access*](../../active-directory/conditional-access/controls.md)|[Azure AD MFA](/azure/multi-factor-authentication/)<br><br>[Custom Controls with Conditional Access*](../../active-directory/conditional-access/controls.md)|[Azure AD MFA](/azure/multi-factor-authentication/)<br><br>[Third-party MFA](/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs)<br><br>[Custom Controls with Conditional Access*](../../active-directory/conditional-access/controls.md)|

+Your identity system ensures your users' access to apps that you migrate and make available in the cloud. Use or enable password hash synchronization with whichever authentication method you choose, for the following reasons:

+ To avoid single points of failure, deploy redundant servers. Then authentication requests will always be serviced if any component fails. Both pass-through authentication and federation also rely on domain controllers to respond to authentication requests, which can also fail. Many of these components need maintenance to stay healthy. Outages are more likely when maintenance isn't planned and implemented correctly.

+ * Organizations that didn't previously enable password hash synchronization had to resort to untrusted external consumer email systems for communications to resolve issues. In those cases, it took them weeks to restore their on-premises identity infrastructure, before users were able to sign in to cloud-based apps again.

+In today's world, threats are present 24 hours a day and come from everywhere. Implement the correct authentication method, and it will mitigate your security risks and protect your identities.

+If you're thinking about migrating from federated to cloud authentication, learn more about [changing the sign-in method](../../active-directory/hybrid/plan-connect-user-signin.md). To help you plan and implement the migration, use [these project deployment plans](../fundamentals/active-directory-deployment-plans.md), or consider using the new [Staged Rollout](../../active-directory/hybrid/how-to-connect-staged-rollout.md) feature to migrate federated users to using cloud authentication in a staged approach.

+| Malicious application | Offline | This detection indicates that Microsoft has disabled an application for violating our terms of service. We recommend [conducting an investigation](https://go.microsoft.com/fwlink/?linkid=2208429) of the application. Note: These applications will show `DisabledDueToViolationOfServicesAgreement` on the `disabledByMicrosoftStatus` property on the related [application](/graph/api/resources/application) and [service principal](/graph/api/resources/serviceprincipal) resource types in Microsoft Graph. To prevent them from being instantiated in your organization again in the future, you cannot delete these objects. |

+| Suspicious application | Offline | This detection indicates that Microsoft has identified an application that may be violating our terms of service, but hasn't disabled it. We recommend [conducting an investigation](https://go.microsoft.com/fwlink/?linkid=2208429) of the application.|

+

+1. Enable the SCIM v2 Plugin using the steps outlined by this [ServiceNow doc](https://docs.servicenow.com/en-US/bundle/utah-platform-security/page/integrate/authentication/task/activate-scim-plugin.html)

+- Tenant URL: https://**InsertInstanceName**.service-now.com/api/now/scim

+- Authorization Endpoint: https://**InsertInstanceName**.service-now.com/oauth_auth.do?response_type=code&client_id=**InsertClientID**&state=1&scope=useraccount&redirect_uri=https%3A%2F%2Fportal.azure.com%2FTokenAuthorize

+- Token Endoint: https://**InsertInstanceName**.service-now.com/api/now/scim

+

+> Failure to restore the previous settings may results in attributes (name.formatted for example) updating in ServiceNow unexpectedly. Be sure to check the configuration before enabling provisioning

+ Title: Azure Active Directory SSO integration with Signiant Media Shuttle

+description: Learn how to configure single sign-on between Azure Active Directory and Signiant Media Shuttle.

+# Azure Active Directory SSO integration with Signiant Media Shuttle

+In this article, you learn how to integrate Signiant Media Shuttle with Azure Active Directory (Azure AD). Media Shuttle is a solution for securely moving large files and data sets to, and from, cloud-based or on-premises storage. Transfers are accelerated and can be up to 100 s of times faster than FTP. When you integrate Signiant Media Shuttle with Azure AD, you can:

+* Control in Azure AD who has access to Signiant Media Shuttle.

+* Enable your users to be automatically signed-in to Signiant Media Shuttle with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+You need to configure and test Azure AD single sign-on for Signiant Media Shuttle in a test environment. Signiant Media Shuttle supports only **SP** initiated single sign-on and **Just In Time** user provisioning.

+## Prerequisites

+To integrate Azure Active Directory with Signiant Media Shuttle, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

+* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).

+* Signiant Media Shuttle single sign-on (SSO) enabled subscription.

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the Signiant Media Shuttle application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add Signiant Media Shuttle from the Azure AD gallery

+Add Signiant Media Shuttle from the Azure AD application gallery to configure single sign-on with Signiant Media Shuttle. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **Signiant Media Shuttle** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier** textbox, type a value or URL using one of the following patterns:

+ | **Identifier** |

+ ||

+ | `https://<PORTALNAME>.mediashuttle.com` |

+ | `mediashuttle` |

+ b. In the **Reply URL** textbox, type a URL using one of the following patterns:

+ | **Reply URL**|

+ ||

+ | `https://portals.mediashuttle.com/auth` |

+ | `https://<PORTALNAME>.mediashuttle.com/auth` |

+ c. In the **Sign on URL** textbox, type a URL using one of the following patterns:

+ | **Sign on URL**|

+ ||

+ | `https://portals.mediashuttle.com/auth` |

+ | `https://<PORTALNAME>.mediashuttle.com/auth` |

+ > [!Note]

+ > These values are not real. Update these values with the actual Identifier, Reply URL and Sign on URL. Contact [Signiant Media Shuttle support team](mailto:support@signiant.com) to get these values. You can also refer to the patterns shown in the Basic SAML Configuration section in the Azure portal.

+1. Your Signiant Media Shuttle application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows an example. The default value of **Unique User Identifier** is **user.userprincipalname** but Signiant Media Shuttle expects to be mapped with the user's email address. For that you can use **user.mail** attribute from the list or use the appropriate attribute value based on your organization configuration.

+ 

+1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, click copy button to copy **App Federation Metadata Url** and save it on your computer.

+ 

+## Configure Signiant Media Shuttle SSO

+To configure single sign-on on **Signiant Media Shuttle** side, you need to send the **App Federation Metadata Url** to [Signiant Media Shuttle support team](mailto:support@signiant.com). They set this setting to have the SAML SSO connection set properly on both sides.

+### Create Signiant Media Shuttle test user

+In this section, a user called Britta Simon is created in Signiant Media Shuttle. Signiant Media Shuttle supports just-in-time user provisioning, which is enabled by default. There's no action item for you in this section. If a user doesn't already exist in Signiant Media Shuttle, a new one is created after authentication.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on **Test this application** in Azure portal. This will redirect to Signiant Media Shuttle Sign-on URL where you can initiate the login flow.

+* Go to Signiant Media Shuttle Sign-on URL directly and initiate the login flow from there.

+* You can use Microsoft My Apps. When you click the Signiant Media Shuttle tile in the My Apps, this will redirect to Signiant Media Shuttle Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Additional resources

+* [What is single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure Signiant Media Shuttle you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+ Title: Azure Active Directory SSO integration with SuperAnnotate

+description: Learn how to configure single sign-on between Azure Active Directory and SuperAnnotate.

+# Azure Active Directory SSO integration with SuperAnnotate

+In this article, you learn how to integrate SuperAnnotate with Azure Active Directory (Azure AD). SuperAnnotate is the all-in-one AI data infrastructure platform that helps ML and data teams save time on building accurate AI models with the highest quality training data - SuperData. When you integrate SuperAnnotate with Azure AD, you can:

+* Control in Azure AD who has access to SuperAnnotate.

+* Enable your users to be automatically signed-in to SuperAnnotate with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+You'll configure and test Azure AD single sign-on for SuperAnnotate in a test environment. SuperAnnotate supports only **SP** initiated single sign-on.

+## Prerequisites

+To integrate Azure Active Directory with SuperAnnotate, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

+* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).

+* SuperAnnotate single sign-on (SSO) enabled subscription.

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the SuperAnnotate application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add SuperAnnotate from the Azure AD gallery

+Add SuperAnnotate from the Azure AD application gallery to configure single sign-on with SuperAnnotate. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **SuperAnnotate** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier** textbox, type a value using the following pattern:

+ `urn:amazon:cognito:sp:<USER_POOL_ID>`

+ b. In the **Reply URL** textbox, type a URL using the following pattern:

+ `https://<DOMAIN PREFIX>.auth.<REGION>.amazoncognito.com/saml2/idpresponse`

+ c. In the **Sign on URL** textbox, type the URL:

+ `https://auth.superannotate.com/login`

+ > [!Note]

+ > These values are not real. Update these values with the actual Identifier and Reply URL. Contact [SuperAnnotate support team](mailto:support@superannotate.com) to get these values. You can also refer to the patterns shown in the Basic SAML Configuration section in the Azure portal.

+1. SuperAnnotate application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes.

+ 

+1. In addition to above, SuperAnnotate application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements.

+ | Name | Source Attribute|

+ | | |

+ | groups | user.groups [ApplicationGroup] |

+1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, click copy button to copy **App Federation Metadata Url** and save it on your computer.

+ 

+## Configure SuperAnnotate SSO

+To configure single sign-on on **SuperAnnotate** side, you need to send the **App Federation Metadata Url** to [SuperAnnotate support team](mailto:support@superannotate.com). They set this setting to have the SAML SSO connection set properly on both sides

+### Create SuperAnnotate test user

+In this section, you create a user called Britta Simon in SuperAnnotate. Work with [SuperAnnotate support team](mailto:support@superannotate.com) to add the users in the SuperAnnotate platform. Users must be created and activated before you use single sign-on.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on **Test this application** in Azure portal. This will redirect to SuperAnnotate Sign-on URL where you can initiate the login flow.

+* Go to SuperAnnotate Sign-on URL directly and initiate the login flow from there.

+* You can use Microsoft My Apps. When you click the SuperAnnotate tile in the My Apps, this will redirect to SuperAnnotate Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Additional resources

+* [What is single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure SuperAnnotate you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+| Revocation |[Verifiable Credential Status List 2021](https://w3c.github.io/vc-status-list-2021/)| W3C CCG |

+An Azure Kubernetes Service (AKS) cluster configured with API Server VNet Integration (Preview) projects the API server endpoint directly into a delegated subnet in the VNet where AKS is deployed. API Server VNet Integration enables network communication between the API server and the cluster nodes without requiring a private link or tunnel. The API server is available behind an Internal Load Balancer VIP in the delegated subnet, which the nodes are configured to utilize. By using API Server VNet Integration, you can ensure network traffic between your API server and your node pools remains on the private network only.

+1. You need the Azure CLI version 2.44.1 or later installed and configured. Run `az --version` to find the version currently installed. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install].

+1. If you don't already have kubectl installed, install it through Azure CLI using `az aks install-cli` or follow the [upstream instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/).

+az aks create --name testMarinerCluster --resource-group MarinerTest --os-sku mariner --generate-ssh-keys

+To add Mariner to an existing ARM template, you need to do the following:

+- Add `"osSKU": "mariner"` and `"mode": "System"` to agentPoolProfiles property.

+- Set the apiVersion to 2021-03-01 or newer: `"apiVersion": "2021-03-01"`

+The following deployment uses the ARM template `marineraksarm.json`.

+```json

+ "defaultValue": "mariner",

+Create this file on your system and include the settings defined in the `marineraksarm.json` file.

+az deployment group create --resource-group MarinerTest --template-file marineraksarm.json --parameters linuxAdminUsername=azureuser sshRSAPublicKey=`<contents of your id_rsa.pub>`

+ os_sku = "mariner"

+When using [Azure Container Registry (ACR)][acr-intro] with Azure Kubernetes Service (AKS), you need to establish an authentication mechanism. Configuring the required permissions between ACR and AKS can be accomplished using the Azure CLI, Azure PowerShell, and Azure portal. This article provides examples to configure authentication between these Azure services using the Azure CLI or Azure PowerShell.

+The AKS to ACR integration assigns the [**AcrPull** role][acr-pull] to the [Azure Active Directory (Azure AD) **managed identity**][aad-identity] associated with the agent pool in your AKS cluster. For more information on AKS managed identities, see [Summary of managed identities][summary-msi].

+> There is a latency issue with Azure Active Directory groups when attaching ACR. If the **AcrPull** role is granted to an Azure AD group and the kubelet identity is added to the group to complete the RBAC configuration, there may be a delay before the RBAC group takes effect. If you are running automation that requires the RBAC configuration to be complete, we recommended you use the [Bring your own kubelet identity][byo-kubelet-identity] as a workaround. You can pre-create a user-assigned identity, add it to the Azure AD group, then use the identity as the kubelet identity to create an AKS cluster. This ensures the identity is added to the Azure AD group before a token is generated by kubelet, which avoids the latency issue.

+* Examples and syntax to use Terraform for configuring ACR can be found in the [Terraform reference][terraform-reference].

+This command may take several minutes to complete.

+This command may take several minutes to complete.

+[terraform-reference]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/container_registry

+ - port: 80

+ - port: 80

+ - http:

+ - http:

+ az deployment group create --resource-group myResourceGroup --template-file main.bicep --parameters clusterName=<cluster-name> dnsPrefix=<dns-prefix> linuxAdminUsername=<linux-admin-username> sshRSAPublicKey='<ssh-key>'

+- Snapshots must be created same region as the source node pool, those snapshots can be used to create or update clusters and node pools in other regions.

+helm install my-release kubereboot/kured --namespace kured --set controller.nodeSelector."kubernetes\.io/os"=linux

+ * `containerd`

+For VNet, attached Azure disk, static IP address, route table which are outside the default worker node resource group, you need to assign the `Contributor` role on custom resource group.

+You can add a Mariner node pool into your existing cluster using the `az aks nodepool add` command and specifying `--os-sku mariner`.

+ --os-sku mariner

+1. Add a Mariner node pool into your existing cluster using the `az aks nodepool add` command and specifying `--os-sku mariner`.

+az identity federated-credential create --name myfederatedIdentity --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RG_NAME}" --issuer "${AKS_OIDC_ISSUER}" --subject system:serviceaccount:"${SERVICE_ACCOUNT_NAMESPACE}":"${SERVICE_ACCOUNT_NAME}" --audience api://AzureADTokenExchange

+ Title: Disaster recovery guide

+description: Learn three common disaster recovery patterns for Azure App Service.

+keywords: app service, azure app service, hadr, disaster recovery, business continuity, high availability, bcdr

+# Strategies for business continuity and disaster recovery in Azure App Service

+Most organizations have a business continuity plan to maintain availability of their applications during downtime and the preservation of their data in a regional disaster. This article covers some common strategies for web apps deployed to App Service.

+For example, when you create a web app in App Service and choose an Azure region during resource creation, it's a single-region app. When the region becomes unavailable during a disaster, your application also becomes unavailable. If you create an identical deployment in a secondary Azure region, your application becomes less susceptible to a single-region outage, which guarantees business continuity, and any data replication across the regions lets you recover your last application state.

+For IT, business continuity plans are largely driven by two metrics:

+

+- Recovery Time Objective (RTO) ΓÇô the time duration in which your application must come back online after an outage.

+- Recovery Point Objective (RPO) ΓÇô the acceptable amount of data loss in a disaster, expressed as a unit of time (for example, 1 minute of transactional database records).

+Normally, maintaining an SLA around RTO is impractical for regional disasters, and you would typically design your disaster recovery strategy around RPO alone (i.e. focus on recovering data and not on minimizing interruption). With Azure, however, it's not only practical but could even be straightforward to deploy App Service for automatic geo-failovers. This lets you disaster-proof your applications further by take care of both RTO and RPO.

+Depending on your desired RTO and RPO metrics, three disaster recovery architectures are commonly used, as shown in the following table:

+

+|.| Active-Active regions | Active-Passive regions | Passive/Cold region|

+|-|-|-|-|

+|RTO| Real-time or seconds| Minutes| Hours |

+|RPO| Real-time or seconds| Minutes| Hours |

+|Cost | $$$| $$| $|

+|Scenarios| Mission-critical apps| High-priority apps| Low-priority apps|

+|Ability to serve multi-region user traffic| Yes| Yes/maybe| No|

+|Code deployment | CI/CD pipelines preferred| CI/CD pipelines preferred| Backup and restore |

+|Creation of new App Service resources during downtime | Not required | Not required| Required |

+## Active-Active architecture

+In this disaster recovery approach, identical web apps are deployed in two separate regions and Azure Front door is used to route traffic to both the active regions.

+With this example architecture:

+- Identical App Service apps are deployed in two separate regions, including pricing tier and instance count.

+- Public traffic directly to the App Service apps is blocked.

+- Azure Front Door is used to route traffic to both the active regions.

+- During a disaster, one of the regions becomes offline, and Azure Front Door routes traffic exclusively to the region that remains online. The RTO during such a geo-failover is near-zero.

+- Application files should be deployed to both web apps with a CI/CD solution. This ensures that the RPO is practically zero.

+- If your application actively modifies the file system, the best way to minimize RPO is to only write to a [mounted Azure Storage share](configure-connect-to-azure-storage.md) instead of writing directly to the web app's */home* content share. Then, use the Azure Storage redundancy features ([GZRS](../storage/common/storage-redundancy.md#geo-zone-redundant-storage) or [GRS](../storage/common/storage-redundancy.md#geo-redundant-storage)) for your mounted share, which has an [RPO of about 15 minutes](../storage/common/storage-redundancy.md#redundancy-in-a-secondary-region).

+- Review [important considerations](#important-considerations) for disaster recovery guidance on the rest of your architecture, such as Azure SQL Database and Azure Storage.

+Steps to create an active-active architecture for your web app in App Service are summarized as follows:

+1. Create two App Service plans in two different Azure regions. Configure the two App Service plans identically.

+1. Create two instances of your web app, with one in each App Service plan.

+1. Create an Azure Front Door profile with:

+ - An endpoint.

+ - Two origin groups, each with a priority of 1. The equal priority tells Azure Front Door to route traffic to both regions equally (thus active-active).

+ - A route.

+1. [Limit network traffic to the web apps only from the Azure Front Door instance](app-service-ip-restrictions.md#restrict-access-to-a-specific-azure-front-door-instance).

+1. Setup and configure all other back-end Azure service, such as databases, storage accounts, and authentication providers.

+1. Deploy code to both the web apps with [continuous deployment](deploy-continuous-deployment.md).

+[Tutorial: Create a highly available multi-region app in Azure App Service](tutorial-multi-region-app.md) shows you how to set up an *active-passive* architecture. The same steps with minimal changes (setting priority to ΓÇ£1ΓÇ¥ for both origin groups in Azure Front Door) give you an *active-active* architecture.

+## Active-passive architecture

+In this disaster recovery approach, identical web apps are deployed in two separate regions and Azure Front door is used to route traffic to one region only (the *active* region).

+With this example architecture:

+- Identical App Service apps are deployed in two separate regions.

+- Public traffic directly to the App Service apps is blocked.

+- Azure Front Door is used to route traffic to the primary region.

+- To save cost, the secondary App Service plan is configured to have fewer instances and/or be in a lower pricing tier. There are three possible approaches:

+ - **Preferred** The secondary App Service plan has the same pricing tier as the primary, with the same number of instances or fewer. This approach ensures parity in both feature and VM sizing for the two App Service plans. The RTO during a geo-failover only depends on the time to scale out the instances.

+ - **Less preferred** The secondary App Service plan has the same pricing tier type (such as PremiumV3) but smaller VM sizing, with lesser instances. For example, the primary region may be in P3V3 tier while the secondary region is in P1V3 tier. This approach still ensures feature parity for the two App Service plans, but the lack of size parity may require a manual scale-up when the secondary region becomes the active region. The RTO during a geo-failover depends on the time to both scale up and scale out the instances.

+ - **Least-preferred** The secondary App Service plan has a different pricing tier than the primary and lesser instances. For example, the primary region may be in P3V3 tier while the secondary region is in S1 tier. Make sure that the secondary App Service plan has all the features your application needs in order to run. Differences in features availability between the two may cause delays to your web app recovery. The RTO during a geo-failover depends on the time to both scale up and scale out the instances.

+- Autoscale is configured on the secondary region in the event the active region becomes inactive. ItΓÇÖs advisable to have similar autoscale rules in both active and passive regions.

+- During a disaster, the primary region becomes inactive, and the secondary region starts receiving traffic and becomes the active region.

+- Once the secondary region becomes active, the network load triggers preconfigured autoscale rules to scale out the secondary web app.

+- You may need to scale up the pricing tier for the secondary region manually, if it doesn't already have the needed features to run as the active region. For example, [autoscaling requires Standard tier or higher](https://azure.microsoft.com/pricing/details/app-service/windows/).

+- When the primary region is active again, Azure Front Door automatically directs traffic back to it, and the architecture is back to active-passive as before.

+- Application files should be deployed to both web apps with a CI/CD solution. This ensures that the RPO is practically zero.

+- If your application actively modifies the file system, the best way to minimize RPO is to only write to a [mounted Azure Storage share](configure-connect-to-azure-storage.md) instead of writing directly to the web app's */home* content share. Then, use the Azure Storage redundancy features ([GZRS](../storage/common/storage-redundancy.md#geo-zone-redundant-storage) or [GRS](../storage/common/storage-redundancy.md#geo-redundant-storage)) for your mounted share, which has an [RPO of about 15 minutes](../storage/common/storage-redundancy.md#redundancy-in-a-secondary-region).

+- Review [important considerations](#important-considerations) for disaster recovery guidance on the rest of your architecture, such as Azure SQL Database and Azure Storage.

+Steps to create an active-passive architecture for your web app in App Service are summarized as follows:

+1. Create two App Service plans in two different Azure regions. The secondary App Service plan may be provisioned using one of the approaches mentioned previously.

+1. Configure autoscaling rules for the secondary App Service plan so that it scales to the same instance count as the primary when the primary region becomes inactive.

+1. Create two instances of your web app, with one in each App Service plan.

+1. Create an Azure Front Door profile with:

+ - An endpoint.

+ - An origin group with a priority of 1 for the primary region.

+ - A second origin group with a priority of 2 for the secondary region. The difference in priority tells Azure Front Door to prefer the primary region when it's online (thus active-passive).

+ - A route.

+1. [Limit network traffic to the web apps only from the Azure Front Door instance](app-service-ip-restrictions.md#restrict-access-to-a-specific-azure-front-door-instance).

+1. Setup and configure all other back-end Azure service, such as databases, storage accounts, and authentication providers.

+1. Deploy code to both the web apps with [continuous deployment](deploy-continuous-deployment.md).

+[Tutorial: Create a highly available multi-region app in Azure App Service](tutorial-multi-region-app.md) shows you how to set up an *active-passive* architecture.

+## Passive/cold region

+In this disaster recovery approach, you create regular backups of your web app to an Azure Storage account.

+With this example architecture:

+- A single web app is deployed to a singled region.

+- The web app is regularly backed up to an Azure Storage account in the same region.

+- The cross-region replication of your backups depends on the data redundancy configuration in the Azure storage account. You should set your Azure Storage account as [GZRS](../storage/common/storage-redundancy.md#geo-zone-redundant-storage) if possible. GZRS offers both synchronous zone redundancy within a region and asynchronous in a secondary region. If GZRS isn't available, configure the account as [GRS](../storage/common/storage-redundancy.md#geo-redundant-storage). Both GZRS and GRS have an [RPO of about 15 minutes](../storage/common/storage-redundancy.md#redundancy-in-a-secondary-region).

+- To ensure that you can retrieve backups when the storage account's primary region becomes unavailable, [**enable read only access to secondary region**](../storage/common/storage-redundancy.md#read-access-to-data-in-the-secondary-region) (making the storage account **RA-GZRS** or **RA-GRS**, respectively). For more information on designing your applications to take advantage of geo-redundancy, see [Use geo-redundancy to design highly available applications](../storage/common/geo-redundant-design.md).

+- During a disaster in the web app's region, you must manually deploy all required App Service dependent resources by using the backups from the Azure Storage account, most likely from the secondary region with read access. The RTO may be hours or days.

+- To minimize RTO, it's highly recommended that you have a comprehensive playbook outlining all the steps required to restore your web app backup to another Azure Region. For more information, see [Important considerations](#important-considerations).

+- Review [important considerations](#important-considerations) for disaster recovery guidance on the rest of your architecture, such as Azure SQL Database and Azure Storage.

+Steps to create a passive-cold region for your web app in App Service are summarized as follows:

+1. Create an Azure storage account in the same region as your web app. Choose Standard performance tier and select redundancy as Geo-redundant storage (GRS) or Geo-Zone-redundant storage (GZRS).

+1. Enable RA-GRS or RA-GZRS (read access for the secondary region).

+1. [Configure custom backup](manage-backup.md) for your web app. You may decide to set a schedule for your web app backups, such as hourly.

+1. Verify that the web app backup files can be retrieved the secondary region of your storage account.

+#### What if my web app's region doesn't have GZRS or GRS storage?

+[Azure regions that don't have a regional pair](../reliability/cross-region-replication-azure.md#regions-with-availability-zones-and-no-region-pair) don't have GRS nor GZRS. In this scenario, utilize zone-redundant storage (ZRS) or locally redundant storage (LRS) to create a similar architecture. For example, you can manually create a secondary region for the storage account as follows:

+Steps to create a passive-cold region without GRS and GZRS are summarized as follows:

+1. Create an Azure storage account in the same region of your web app. Choose Standard performance tier and select redundancy as zone-redundant storage (ZRS).

+1. [Configure custom backup](manage-backup.md) for your web app. You may decide to set a schedule for your web app backups, such as hourly.

+1. Verify that the web app backup files can be retrieved the secondary region of your storage account.

+1. Create a second Azure storage account in a different region. Choose Standard performance tier and select redundancy as locally redundant storage (LRS).

+1. By using a tool like [AzCopy](../storage/common/storage-use-azcopy-v10.md#use-in-a-script), replicate your custom backup (Zip, XML and log files) from primary region to the secondary storage. For example:

+ ```

+ azcopy copy 'https://<source-storage-account-name>.blob.core.windows.net/<container-name>/<blob-path>' 'https://<destination-storage-account-name>.blob.core.windows.net/<container-name>/<blob-path>'

+ ```

+ You can use [Azure Automation with a PowerShell Workflow runbook](../automation/learn/automation-tutorial-runbook-textual.md) to run your replication script [on a schedule](../automation/shared-resources/schedules.md). Make sure that the replication schedule follows a similar schedule to the web app backups.

+## Important considerations

+- These disaster recovery strategies are applicable to both App Service multitenant and App Service Environments.

+- Within the same region, an App Service app can be deployed into [availability zones (AZ)](../reliability/availability-zones-overview.md) to help you achieve high availability for your mission-critical workloads. For more information, see [Migrate App Service to availability zone support](../reliability/migrate-app-service.md).

+- There are multiple ways to replicate your web apps content and configurations across Azure regions in an active-active or active-passive architecture, such as using [App service backup and restore](manage-backup.md). However, these options are point-in-time snapshots and eventually lead to web app versioning challenges across regions. To avoid these limitations, configure your CI/CD pipelines to deploy code to both the Azure regions. Consider using [Azure Pipelines](/azure/devops/pipelines/get-started/what-is-azure-pipelines) or [GitHub Actions](https://docs.github.com/actions). For more information, see [Continuous deployment to Azure App Service](deploy-continuous-deployment.md).

+- Use an infrastructure-as-code (IoC) mechanism to manage your application resources in Azure. In a complex deployment across multiple regions, to manage the regions independently and to keep the configuration synchronized across regions in a reliable manner requires a predictable, testable, and repeatable process. Consider an IoC tool such as [Azure Resource Manager templates](../azure-resource-manager/management/overview.md) or [Terraform](/azure/developer/terraform/overview).

+- Your application most likely depends on other data services in Azure, such as Azure SQL Database and Azure Storage accounts. You should develop disaster recovery strategies for each of these dependent Azure Services as well. For SQL Database, see [Active geo-replication for Azure SQL Database](/azure/azure-sql/database/active-geo-replication-overview). For Azure Storage, see [Azure Storage redundancy](../storage/common/storage-redundancy.md).

+- Aside from Azure Front Door, which is proposed in this article, Azure provides other load balancing options, such as Azure Traffic Manager. For a comparison of the various options, see [Load-balancing options - Azure Architecture Center](/azure/architecture/guide/technology-choices/load-balancing-overview).

+- It's also recommended to set up monitoring and alerts for your web apps to for timely notifications during a disaster. For more information, see [Application Insights availability tests](../azure-monitor/app/availability-overview.md).

+## Next steps

+[Tutorial: Create a highly available multi-region app in Azure App Service](tutorial-multi-region-app.md)

+ Title: Add-on capabilities - Form Recognizer

+description: How to increase service limit capacity with add-on capabilities.

+monikerRange: 'form-recog-3.0.0'

+recommendations: false

+<!-- markdownlint-disable MD033 -->

+# Azure Form Recognizer add-on capabilities

+**This article applies to:**  **Form Recognizer v3.0**.

+> [!NOTE]

+>

+> Add-on capabilities for Form Recognizer Studio are only available within the Read and Layout models for the `2023-02-28-preview` release.

+Form Recognizer now supports more sophisticated analysis capabilities. These optional capabilities can be enabled and disabled depending on the scenario of the document extraction. There are three add-on capabilities available for the `2023-02-28-preview`:

+* [`ocr.highResolution`](#high-resolution-extraction)

+* [`ocr.formula`](#formula-extraction)

+* [`ocr.font`](#font-property-extraction)

+## High resolution extraction

+The task of recognizing small text from large-size documents, like engineering drawings, is a challenge. Often the text is mixed with other graphical elements and has varying fonts, sizes and orientations. Moreover, the text may be broken into separate parts or connected with other symbols. Form Recognizer now supports extracting content from these types of documents with the `ocr.highResolution` capability. You get improved quality of content extraction from A1/A2/A3 documents by enabling this add-on capability.

+## Formula extraction

+The `ocr.formula` capability extracts all identified formulas, such as mathematical equations, in the `formulas` collection as a top level object under `content`. Inside `content`, detected formulas are represented as `:formula:`. Each entry in this collection represents a formula that includes the formula type as `inline` or `display`, and its LaTeX representation as `value` along with its `polygon` coordinates. Initially, formulas appear at the end of each page.

+ > [!NOTE]

+ > The `confidence` score is hard-coded for the `2023-02-28` public preview release.

+ ```json

+ "content": ":formula:",

+ "pages": [

+ {

+ "pageNumber": 1,

+ "formulas": [

+ {

+ "kind": "inline",

+ "value": "\\frac { \\partial a } { \\partial b }",

+ "polygon": [...],

+ "span": {...},

+ "confidence": 0.99

+ },

+ {

+ "kind": "display",

+ "value": "y = a \\times b + a \\times c",

+ "polygon": [...],

+ "span": {...},

+ "confidence": 0.99

+ }

+ ]

+ }

+ ]

+ ```

+## Font property extraction

+The `ocr.font` capability extracts all font properties of text extracted in the `styles` collection as a top-level object under `content`. Each style object specifies a single font property, the text span it applies to, and its corresponding confidence score. The existing style property is extended with more font properties such as `similarFontFamily` for the font of the text, `fontStyle` for styles such as italic and normal, `fontWeight` for bold or normal, `color` for color of the text, and `backgroundColor` for color of the text bounding box.

+ ```json

+ "content": "Foo bar",

+ "styles": [

+ {

+ "similarFontFamily": "Arial, sans-serif",

+ "spans": [ { "offset": 0, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "similarFontFamily": "Times New Roman, serif",

+ "spans": [ { "offset": 4, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "fontStyle": "italic",

+ "spans": [ { "offset": 1, "length": 2 } ],

+ "confidence": 0.98

+ },

+ {

+ "fontWeight": "bold",

+ "spans": [ { "offset": 2, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "color": "#FF0000",

+ "spans": [ { "offset": 4, "length": 2 } ],

+ "confidence": 0.98

+ },

+ {

+ "backgroundColor": "#00FF00",

+ "spans": [ { "offset": 5, "length": 2 } ],

+ "confidence": 0.98

+ }

+ ]

+ ```

+## Next steps

+> [!div class="nextstepaction"]

+> Learn more:

+> [**Read model**](concept-read.md) [**Layout model**](concept-layout.md).

+The Form Recognizer business card model combines powerful Optical Character Recognition (OCR) capabilities with deep learning models to analyze and extract data from business card images. The API analyzes printed business cards; extracts key information such as first name, last name, company name, email address, and phone number; and returns a structured JSON data representation.

+Form Recognizer v3.0 supports the following tools:

+Form Recognizer v2.1 supports the following tools:

+See how data, including name, job title, address, email, and company name, is extracted from business cards. You need the following resources:

+1. Select **Run analysis**. The Form Recognizer Sample Labeling tool calls the Analyze Prebuilt API and analyze the document.

+With the introduction of [****custom classifier models****](./concept-custom-classifier.md), you can choose to use [**composed models**](./concept-composed-models.md) or the classifier model as an explicit step before analysis. For a deeper understanding of when to use a classifier or composed model, _see_ [**Custom classifier models**](concept-custom-classifier.md).

+* Models composed with v2.1 of the API continues to be supported, requiring no updates.

+> [**Compose custom models**](how-to-guides/compose-custom-models.md)

+ Title: Custom classifier model - Form Recognizer

+description: Use the custom classifier model to train a model to identify and split the documents you process within your application.

+monikerRange: 'form-recog-3.0.0'

+recommendations: false

+# Custom classifier model

+**This article applies to:**  **Form Recognizer v3.0**.

+Custom classifier models are deep-learning-model types that combine layout and language features to accurately detect and identify documents you process within your application. Custom classifier models can classify each page in an input file to identify the document(s) within and can also identify multiple documents or multiple instances of a single document within an input file.

+## Model capabilities

+Custom classifier models can analyze a single- or multi-file documents to identify if any of the trained document types are contained within an input file. Here are the currently supported scenarios:

+* A single file containing one document. For instance, a loan application form.

+* A single file containing multiple documents. For instance, a loan application package containing a loan application form, payslip, and bank statement.

+* A single file containing multiple instances of the same document. For instance, a collection of scanned invoices.

+Training a custom classifier model requires at least two distinct classes and a minimum of five samples per class.

+### Compare custom classifier and composed models

+A custom classifier model can replace [a composed model](concept-composed-models.md) in some scenarios but there are a few differences to be aware of:

+| Capability | Custom classifier process | Composed model process |

+|--|--|--|

+|Analyze a single document of unknown type belonging to one of the types trained for extraction model processing.| &#9679; Requires multiple calls. </br> &#9679; Call the classifier models based on the document class. This step allows for a confidence-based check before invoking the extraction model analysis.</br> &#9679; Invoke the extraction model. | &#9679; Requires a single call to a composed model containing the model corresponding to the input document type. |

+ |Analyze a single document of unknown type belonging to several types trained for extraction model processing.| &#9679;Requires multiple calls.</br> &#9679; Make a call to the classifier that ignores documents not matching a designated type for extraction.</br> &#9679; Invoke the extraction model. | &#9679; Requires a single call to a composed model. The service selects a custom model within the composed model with the highest match.</br> &#9679; A composed model can't ignore documents.|

+|Analyze a file containing multiple documents of known or unknown type belonging to one of the types trained for extraction model processing.| &#9679; Requires multiple calls. </br> &#9679; Call the extraction model for each identified document in the input file.</br> &#9679; Invoke the extraction model. | &#9679; Requires a single call to a composed model.</br> &#9679; The composed model invokes the component model once on the first instance of the document. </br> &#9679;The remaining documents are ignored. |

+## Language support

+Classifier models currently only support English language documents.

+## Best practices

+Custom classifier models require a minimum of five samples per class to train. If the classes are similar, adding extra training samples improves model accuracy.

+## Training a model

+Custom classifier models are only available in the [v3.0 API](v3-migration-guide.md) starting with API version ```2023-02-28-preview```. [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio) provides a no-code user interface to interactively train a custom classifier.

+When using the REST API, if you've organized your documents by folders, you can use the ```azureBlobSource``` property of the request to train a classifier model.

+```rest

+https://{endpoint}/formrecognizer/documentClassifiers:build?api-version=2023-02-28-preview

+{

+ "classifierId": "demo2.1",

+ "description": "",

+ "docTypes": {

+ "car-maint": {

+ "azureBlobSource": {

+ "containerUrl": "SAS URL to container",

+ "prefix": "sample1/car-maint/"

+ }

+ },

+ "cc-auth": {

+ "azureBlobSource": {

+ "containerUrl": "SAS URL to container",

+ "prefix": "sample1/cc-auth/"

+ }

+ },

+ "deed-of-trust": {

+ "azureBlobSource": {

+ "containerUrl": "SAS URL to container",

+ "prefix": "sample1/deed-of-trust/"

+ }

+ }

+ }

+}

+```

+Alternatively, if you have a flat list of files or only plan to use a few select files within each folder to train the model, you can use the ```azureBlobFileListSource``` property to train the model. This step requires a ```file list``` in [JSON Lines](https://jsonlines.org/) format. For each class, add a new file with a list of files to be submitted for training.

+```rest

+{

+ "classifierId": "demo2",

+ "description": "",

+ "docTypes": {

+ "car-maint": {

+ "azureBlobFileListSource": {

+ "containerUrl": "SAS URL to container",

+ "fileList": "sample1/car-maint.jsonl"

+ }

+ },

+ "cc-auth": {

+ "azureBlobFileListSource": {

+ "containerUrl": "SAS URL to container",

+ "fileList": "sample1/cc-auth.jsonl"

+ }

+ },

+ "deed-of-trust": {

+ "azureBlobFileListSource": {

+ "containerUrl": "SAS URL to container",

+ "fileList": "sample1/deed-of-trust.jsonl"

+ }

+ }

+ }

+}

+```

+File list `car-maint.jsonl` contains the following files.

+```json

+{"file":"sample1/car-maint/Commercial Motor Vehicle - Adatum.pdf"}

+{"file":"sample1/car-maint/Commercial Motor Vehicle - Fincher.pdf"}

+{"file":"sample1/car-maint/Commercial Motor Vehicle - Lamna.pdf"}

+{"file":"sample1/car-maint/Commercial Motor Vehicle - Liberty.pdf"}

+{"file":"sample1/car-maint/Commercial Motor Vehicle - Trey.pdf"}

+```

+## Next steps

+Learn to create custom classifier models:

+> [!div class="nextstepaction"]

+> [**Build a custom classifier model**](how-to-guides/build-a-custom-classifier.md)

+> [**Custom models overview**](concept-custom.md)

+* Here, we examine best practices for labeling your selected documents. With semantically relevant and consistent labeling, you should see an improvement in model performance.</br></br>

+* You provide a set of sample documents (typically PDFs or images). A minimum of five documents is needed to train a model.

+* Additionally, the labeling process generates the following files:

+* Here, we explore how to create a balanced data set and select the right documents to label. This process sets you on the path to higher quality models.</br></br>

+Before you start labeling, it's a good idea to look at a few different samples of the document to identify which samples you want to use in your labeled dataset. A balanced dataset represents all the typical variations you would expect to see for the document. Creating a balanced dataset results in a model with the highest possible accuracy. A few examples to consider are:

+* **Variations (Neural models)**: When your dataset has a manageable set of variations, about 15 or fewer, create a single dataset with a few samples of each of the different variations to train a single model. If the number of template variations is larger than 15, you train multiple models and [compose](concept-composed-models.md) them together.

+> [!NOTE]

+Custom neural models currently only support key-value pairs, structured fields (tables), and selection marks.

+* **Visually repeating data**. Tables support visually repeating groups of information not just explicit tables. Explicit tables are identified in tables section of the analyzed documents as part of the layout output and don't need to be labeled as tables. Only label a table field if the information is visually repeating and not identified as a table as part of the layout response. An example would be the repeating work experience section of a resume.

+Custom neural models currently only support key-value pairs and selection marks and structured fields (tables), future releases include support for signatures.

+¹ Region labels in custom neural models use the results from the Layout API for specified region. This feature is different from template models where, if no value is present, text is generated at training time.

+Neural models support documents that have the same information, but different page structures. Examples of these documents include United States W2 forms, which share the same information, but may vary in appearance across companies. For more information, *see* [Custom model build mode](concept-custom.md#build-mode).

+## Language support

+1. Neural models now support added languages in the ```2023-02-28-preview``` API.

+| Languages | API version |

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

+| English | `2022-08-31` (GA), `2023-02-28-preview`|

+| German | `2023-02-28-preview`|

+| Italian | `2023-02-28-preview`|

+| French | `2023-02-28-preview`|

+| Spanish | `2023-02-28-preview`|

+| Dutch | `2023-02-28-preview`|

+When you label the data, labeling the field relevant to the value improves the accuracy of the key-value pairs extracted. For example, for a field value containing the supplier ID, consider naming the field "supplier_id". Field names should be in the language of the document.

+* Custom neural models are only trained in English. Model performance is lower for documents in other languages.

+# Azure Form Recognizer Custom document models

+Form Recognizer uses advanced machine learning technology to identify documents, detect and extract information from forms and documents, and return the extracted data in a structured JSON output. With Form Recognizer, you can use document analysis models, pre-built/pre-trained, or your trained standalone custom models.

+Custom models now include [custom classifier models](./concept-custom-classifier.md) for scenarios where you need to identify the document type prior to invoking the extraction model. Classifier models are available starting with the ```2023-02-28-preview``` API. A classifier model can be paired with a custom extraction model to analyze and extract fields from forms and documents specific to your business to create a document processing solution. Standalone custom extraction models can be combined to create [composed models](concept-composed-models.md).

+### Custom extraction models

+To create a custom extraction model, label a dataset of documents with the values you want extracted and train the model on the labeled dataset. You only need five examples of the same form or document type to get started.

+The custom template or custom form model relies on a consistent visual template to extract the labeled data. Variances in the visual structure of your documents affect the accuracy of your model. Structured forms such as questionnaires or applications are examples of consistent visual templates.

+Your training set consists of structured documents where the formatting and layout are static and constant from one document instance to the next. Custom template models support key-value pairs, selection marks, tables, signature fields, and regions. Template models and can be trained on documents in any of the [supported languages](language-support.md). For more information, *see* [custom template models](concept-custom-template.md ).

+The following table compares custom template and custom neural features:

+|Language support | Multiple [language support](language-support.md#read-layout-and-custom-form-template-model) | English, with preview support for Spanish, French, German, Italian and Dutch [language support](language-support.md#custom-neural-model) |

+### Custom classifier model

+ Document classification is a new scenario supported by Form Recognizer with the ```2023-02-28-preview``` API. Document classifier supports classification and splitting scenarios. Train a classifier model to identify the different types of documents your application supports. The input file for the classifier model can contain multiple documents and classifies each document within an associated page range. See [custom classification](concept-custom-classifier.md) models to learn more.

+Form Recognizer v3.0 supports the following tools:

+Form Recognizer v2.1 supports the following tools:

+### [Custom extraction](#tab/extraction)

+1. On the **Form Recognizer Studio** home page, select **Custom extraction models**.

+1. Add your sample documents to label, build and test your custom model.

+For a detailed walkthrough to create your first custom extraction model, see [how to create a custom extraction model](how-to-guides/build-a-custom-model.md)

+### [Custom classification](#tab/classification)

+Extract data from your specific or unique documents using custom models. You need the following resources:

+* An Azure subscription. You can [create one for free](https://azure.microsoft.com/free/cognitive-services/).

+* A [Form Recognizer instance](https://portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer) in the Azure portal. You can use the free pricing tier (`F0`) to try the service. After your resource deploys, select **Go to resource** to get your key and endpoint.

+ :::image type="content" source="media/containers/keys-and-endpoint.png" alt-text="Screenshot that shows the keys and endpoint location in the Azure portal.":::

+## Form Recognizer Studio

+> [!NOTE]

+> Form Recognizer Studio is available with the v3.0 API.

+1. On the **Form Recognizer Studio** home page, select **Custom classification models**.

+1. Under **My Projects**, select **Create a project**.

+1. Complete the project details fields.

+1. Configure the service resource by adding your **Storage account** and **Blob container** to **Connect your training data source**.

+1. Review and create your project.

+1. Label your documents to build and test your custom classifier model.

+ > [!div class="nextstepaction"]

+ > [Try Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/document-classifier/projects)

+For a detailed walkthrough to create your first custom extraction model, see [how to create a custom extraction model](how-to-guides/build-a-custom-classifier.md)

+|Custom neural| Γ£ö| Γ£ö | Γ£ö | **n/a** | * |

+**Table symbols**:

+Γ£öΓÇösupported;

+**n/aΓÇöcurrently unavailable;

+*-behaves differently. With template models, synthetic data is generated at training time. With neural models, exiting text recognized in the region is selected.

+[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/) is an online tool for visually exploring, understanding, and integrating features from the Form Recognizer service into your applications. Use the [Form Recognizer Studio quickstart](quickstarts/try-v3-form-recognizer-studio.md) to get started analyzing documents with pretrained models. Build custom template models and reference the models in your applications using the [Python SDK v3.0](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true) and other quickstarts.

+> The ```2023-02-28-preview``` version of the general document model adds support for **normalized keys**.

+* Key names are spans of text within the document that are associated with a value. With the ```2023-02-28-preview``` API version, key names are normalized where applicable.

+* Selection marks are identified as fields with a value of ```:selected:``` or ```:unselected:```

+## Key-value pair extraction

+The general document API supports most form types and analyzes your documents and extract keys and associated values. It's ideal for extracting common key-value pairs from documents. You can use the general document model as an alternative to training a custom model without labels.

+### Key normalization (common name)

+When the service analyzes documents with variations in key names like ```Social Security Number```, ```Social Security Nbr```, ```SSN```, the output normalizes the key variations to a single common name, ```SocialSecurityNumber```. This normalization simplifies downstream processing for documents where you no longer need to account for variations in the key name.

+Form Recognizer v3.0 supports the following tools:

+You need the following resources:

+Keys can also exist in isolation when the model detects that a key exists, with no associated value or when processing optional fields. For example, a middle name field may be left blank on a form in some instances. Key-value pairs are spans of text contained in the document. For documents where the same value is described in different ways, for example, customer/user, the associated key is either customer or user (based on context).

+| **Model** | **Text extraction** |**Key-Value pairs** |**Selection Marks** | **Tables** | **Common Names** |

+| | :: |::| :: | :: | :: |

+|General document | Γ£ô | Γ£ô | Γ£ô | Γ£ô | Γ£ô* |

+Γ£ô* - Only available in the 2023-02-28-preview API version.

+#### `idDocument` fields extracted

+ Title: Form Recognizer insurance card prebuilt model

+description: Data extraction and analysis extraction using the insurance card model

+monikerRange: 'form-recog-3.0.0'

+recommendations: false

+# Azure Form Recognizer health insurance card model

+**This article applies to:**  **Form Recognizer v3.0**.

+The Form Recognizer health insurance card model combines powerful Optical Character Recognition (OCR) capabilities with deep learning models to analyze and extract key information from US health insurance cards. A health insurance card is a key document for care processing and can be digitally analyzed for patient onboarding, financial coverage information, cashless payments, and insurance claim processing. The health insurance card model analyzes health card images; extracts key information such as insurer, member, prescription, and group number; and returns a structured JSON representation. Health insurance cards can be presented in various formats and quality including phone-captured images, scanned documents, and digital PDFs.

+***Sample health insurance card processed using Form Recognizer Studio***

+## Development options

+Form Recognizer v3.0 supports the prebuilt health insurance card model with the following tools:

+| Feature | Resources | Model ID |

+|-|-|--|

+|**health insurance card model**|<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|**prebuilt-healthInsuranceCard.us**|

+### Try Form Recognizer

+See how data is extracted from health insurance cards using the Form Recognizer Studio. You need the following resources:

+* An Azure subscriptionΓÇöyou can [create one for free](https://azure.microsoft.com/free/cognitive-services/)

+* A [Form Recognizer instance](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer) in the Azure portal. You can use the free pricing tier (`F0`) to try the service. After your resource deploys, select **Go to resource** to get your key and endpoint.

+ :::image type="content" source="media/containers/keys-and-endpoint.png" alt-text="Screenshot of keys and endpoint location in the Azure portal.":::

+#### Form Recognizer Studio

+> [!NOTE]

+> Form Recognizer studio is available with API version v3.0.

+1. On the [Form Recognizer Studio home page](https://formrecognizer.appliedai.azure.com/studio), select **Health insurance cards**.

+1. You can analyze the sample insurance card document or select the **Γ₧ò Add** button to upload your own sample.

+1. Select the **Analyze** button:

+ :::image type="content" source="media/studio/insurance-card-analyze.png" alt-text="Screenshot: analyze health insurance card window in the Form Recognizer Studio.":::

+ > [!div class="nextstepaction"]

+ > [Try Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=healthInsuranceCard.us)

+## Input requirements

+## Supported languages and locales

+| Model | LanguageΓÇöLocale code | Default |

+|--|:-|:|

+|prebuilt-healthInsuranceCard.us| <ul><li>English (United States)</li></ul>|English (United States)ΓÇöen-US|

+## Field extraction

+| Field | Type | Description | Example |

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

+|`Insurer`|`string`|Health insurance provider name|PREMERA<br>BLUE CROSS|

+|`Member`|`object`|||

+|`Member.Name`|`string`|Member name|ANGEL BROWN|

+|`Member.BirthDate`|`date`|Member date of birth|01/06/1958|

+|`Member.Employer`|`string`|Member name employer|Microsoft|

+|`Member.Gender`|`string`|Member gender|M|

+|`Member.IdNumberSuffix`|`string`|Identification Number Suffix as it appears on some health insurance cards|01|

+|`Dependents`|`array`|Array holding list of dependents, ordered where possible by membership suffix value||

+|`Dependents.*`|`object`|||

+|`Dependents.*.Name`|`string`|Dependent name|01|

+|`IdNumber`|`object`|||

+|`IdNumber.Prefix`|`string`|Identification Number Prefix as it appears on some health insurance cards|ABC|

+|`IdNumber.Number`|`string`|Identification Number|123456789|

+|`GroupNumber`|`string`|Insurance Group Number|1000000|

+|`PrescriptionInfo`|`object`|||

+|`PrescriptionInfo.Issuer`|`string`|ANSI issuer identification number (IIN)|(80840) 300-11908-77|

+|`PrescriptionInfo.RxBIN`|`string`|Prescription issued BIN number|987654|

+|`PrescriptionInfo.RxPCN`|`string`|Prescription processor control number|63200305|

+|`PrescriptionInfo.RxGrp`|`string`|Prescription group number|BCAAXYZ|

+|`PrescriptionInfo.RxId`|`string`|Prescription identification number. If not present, defaults to membership ID number|P97020065|

+|`PrescriptionInfo.RxPlan`|`string`|Prescription Plan number|A1|

+|`Pbm`|`string`|Pharmacy Benefit Manager for the plan|CVS CAREMARK|

+|`EffectiveDate`|`date`|Date from which the plan is effective|08/12/2012|

+|`Copays`|`array`|Array holding list of CoPay Benefits||

+|`Copays.*`|`object`|||

+|`Copays.*.Benefit`|`string`|Co-Pay Benefit name|Deductible|

+|`Copays.*.Amount`|`currency`|Co-Pay required amount|$1,500|

+|`Payer`|`object`|||

+|`Payer.Id`|`string`|Payer ID Number|89063|

+|`Payer.Address`|`address`|Payer address|123 Service St., Redmond WA, 98052|

+|`Payer.PhoneNumber`|`phoneNumber`|Payer phone number|+1 (987) 213-5674|

+|`Plan`|`object`|||

+|`Plan.Number`|`string`|Plan number|456|

+|`Plan.Name`|`string`|Plan name - If see Medicaid -> then Medicaid|HEALTH SAVINGS PLAN|

+|`Plan.Type`|`string`|Plan type|PPO|

+### Migration guide and REST API v3.0

+* Follow our [**Form Recognizer v3.0 migration guide**](v3-migration-guide.md) to learn how to use the v3.0 version in your applications and workflows.

+* Explore our [**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument) to learn more about the v3.0 version and new capabilities.

+## Next steps

+* Try processing your own forms and documents with the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)

+* Complete a [Form Recognizer quickstart](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true) and get started creating a document processing app in the development language of your choice.

+| CurrencyCode | String | The currency code associated with the extracted amount | |

+| PaymentDetails | Array | An array that holds Payment Option details such as `IBAN`and `SWIFT` | |

+Form Recognizer layout model is an advanced machine-learning based document analysis API available in the Form Recognizer cloud. It enables you to take documents in various formats and return structured data representations of the documents. It combines an enhanced version of our powerful [Optical Character Recognition (OCR)](../../cognitive-services/computer-vision/overview-ocr.md) capabilities with deep learning models to extract text, tables, selection marks, and document structure.

+Form Recognizer v3.0 supports the following tools:

+See how data, including text, tables, table headers, selection marks, and structure information is extracted from documents using Form Recognizer. You need the following resources:

+1. Select **Run Layout**. The Form Recognizer Sample Labeling tool calls the Analyze Layout API and analyze the document.

+Form Recognizer v2.1 supports the following tools:

+### Annotations extraction

+The Layout model extracts annotations in documents, such as checks and crosses. The response includes the kind of annotation, along with a confidence score and bounding polygon.

+```json

+ {

+ "pages": [

+ {

+ "annotations": [

+ {

+ "kind": "cross",

+ "polygon": [...],

+ "confidence": 1

+ }

+ ]

+ }

+ ]

+}

+```

+### Extracting barcodes from documents

+The Layout model extracts all identified barcodes in the `barcodes` collection as a top level object under `content`. Inside the `content`, detected barcodes are represented as `:barcode:`. Each entry in this collection represents a barcode and includes the barcode type as `kind` and the embedded barcode content as `value` along with its `polygon` coordinates. Initially, barcodes appear at the end of each page.

+#### Supported barcode types

+| **Barcode Type** | **Example** |

+| | |

+| QR Code |:::image type="content" source="media/barcodes/qr-code.png" alt-text="Screenshot of the QR Code.":::|

+| Code 39 |:::image type="content" source="media/barcodes/code-39.png" alt-text="Screenshot of the Code 39.":::|

+| Code 128 |:::image type="content" source="media/barcodes/code-128.png" alt-text="Screenshot of the Code 128.":::|

+| UPC (UPC-A & UPC-E) |:::image type="content" source="media/barcodes/upc.png" alt-text="Screenshot of the UPC.":::|

+| PDF417 |:::image type="content" source="media/barcodes/pdf-417.png" alt-text="Screenshot of the PDF417.":::|

+ > [!NOTE]

+ > The `confidence` score is hard-coded for the `2023-02-28` public preview.

+ ```json

+ "content": ":barcode:",

+ "pages": [

+ {

+ "pageNumber": 1,

+ "barcodes": [

+ {

+ "kind": "QRCode",

+ "value": "http://test.com/",

+ "span": { ... },

+ "polygon": [...],

+ "confidence": 1

+ }

+ ]

+ }

+ ]

+ ```

+### Extract selected pages from documents

+The second step is to call the [Get Analyze Layout Result](https://westcentralus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/GetAnalyzeLayoutResult) operation. This operation takes as input the Result ID the Analyze Layout operation created. It returns a JSON response that contains a **status** field with the following possible values.

+When the **status** field has the `succeeded` value, the JSON response includes the extracted layout, text, tables, and selection marks. The extracted data includes extracted text lines and words, bounding boxes, text appearance with handwritten indication, tables, and selection marks with selected/unselected indicated.

+* `readResults` node contains all of the recognized text and selection mark. The text presentation hierarchy is page, then line, then individual words.

+<!-- markdownlint-disable MD011 -->

+| [Health insurance card](#health-insurance-card) | Automate healthcare processes by extracting insurer, member, prescription, group number and other key information from US health insurance cards.|

+| [Invoice](#invoice) | Automate invoices. |

+| [Receipt](#receipt) | Extract receipt data from receipts.|

+| [Custom model (overview)](#custom-models) | Extract data from forms and documents specific to your business. Custom models are trained for your distinct data and use cases. |

+| [Custom extraction models](#custom-extraction)| &#9679; **Custom template models** use layout cues to extract values from documents and are suitable to extract fields from highly structured documents with defined visual templates.</br>&#9679; **Custom neural models** are trained on various document types to extract fields from structured, semi-structured and unstructured documents.|

+| [Custom classifier model](#custom-classifier)| The **Custom classifier model** can classify each page in an input file to identify the document(s) within and can also identify multiple documents or multiple instances of a single document within an input file.

+The general document model is ideal for extracting common key-value pairs from forms and documents. It's a pre-trained model and can be directly invoked via the REST API and the SDKs. You can use the general document model as an alternative to training a custom model.

+### Health insurance card

+The health insurance card model combines powerful Optical Character Recognition (OCR) capabilities with deep learning models to analyze and extract key information from US health insurance cards.

+***Sample US health insurance card processed using [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=healthInsuranceCard.us)***:

+> [!div class="nextstepaction"]

+> [Learn more: Health insurance card model](concept-insurance-card.md)

+### W-2

+Custom document models analyze and extract data from forms and documents specific to your business. They're trained to recognize form fields within your distinct content and extract key-value pairs and table data. You only need five examples of the same form type to get started.

+#### Custom extraction

+[:::image type="icon" source="media/studio/custom-extraction.png":::](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)

+Custom extraction model can be one of two types, **custom template** or **custom neural**. To create a custom extraction model, label a dataset of documents with the values you want extracted and train the model on the labeled dataset. You only need five examples of the same form or document type to get started.

+***Sample custom extraction processed using [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/customform/projects)***:

+> [!div class="nextstepaction"]

+> [Learn more: custom template model](concept-custom-template.md)

+> [!div class="nextstepaction"]

+> [Learn more: custom neural model](./concept-custom-neural.md)

+#### Custom classifier

+[:::image type="icon" source="media/studio/custom-classifier.png":::](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)

+The custom classifier model enables you to identify the document type prior to invoking the extraction model. The classifier model is available starting with the 2023-02-28-preview. Training a custom classifier model requires at least two distinct classes and a minimum of five samples per class.

+> [!div class="nextstepaction"]

+> [Learn more: custom classifier model](concept-custom-classifier.md)

+A composed model is created by taking a collection of custom models and assigning them to a single model built from your form types. You can assign multiple custom models to a composed model called with a single model ID. You can assign up to 200 trained custom models to a single composed model.

+| [prebuilt-healthInsuranceCard.us](concept-insurance-card.md#field-extraction) | Γ£ô | | Γ£ô | | Γ£ô | | | Γ£ô |

+ Title: Query field extraction - Form Recognizer

+description: Use Form Recognizer to extract query field data.

+monikerRange: 'form-recog-3.0.0'

+recommendations: false

+<!-- markdownlint-disable MD033 -->

+# Azure Form Recognizer query field extraction

+**This article applies to:**  **Form Recognizer v3.0**.

+> [!IMPORTANT]

+>

+> * The Form Recognizer Studio query fields extraction feature is currently in gated preview. Features, approaches and processes may change, prior to General Availability (GA), based on user feedback.

+> * Complete and submit the [**Form Recognizer private preview request form**](https://aka.ms/form-recognizer/preview/survey) to request access.

+Form Recognizer now supports query field extractions using Azure OpenAI capabilities. With query field extraction, you can add fields to the extraction process using a query request without the need for added training.

+> [!NOTE]

+>

+> Form Recognizer Studio query field extraction is currently available with the general document model for the `2023-02-28-preview` release.

+## Select query fields

+For query field extraction, specify the fields you want to extract and Form Recognizer analyzes the document accordingly. Here's an example:

+* If you're processing a contract in the Form Recognizer Studio, you can pass a list of field labels like `Party1`, `Party2`, `TermsOfUse`, `PaymentTerms`, `PaymentDate`, and `TermEndDate`" as part of the analyze document request.

+ :::image type="content" source="media/studio/query-field-select.png" alt-text="Screenshot of query fields selection window in Form Recognizer Studio.":::

+* Form Recognizer utilizes the capabilities of both [**Azure OpenAI Service**](../../cognitive-services/openai/overview.md) and extraction models to analyze and extract the field data and return the values in a structured JSON output.

+* In addition to the query fields, the response includes text, tables, selection marks, general document key-value pairs, and other relevant data.

+## Next steps

+> [!div class="nextstepaction"]

+> [Try the Form Recognizer Studio quickstart](./quickstarts/try-form-recognizer-studio.md)

+> For extracting text from external images like labels, street signs, and posters, use the [Computer Vision v4.0 preview Read](../../cognitive-services/Computer-vision/concept-ocr.md) feature optimized for general, non-document images with a performance-enhanced synchronous API that makes it easier to embed OCR in your user experience scenarios.

+Form Recognizer v3.0's Read Optical Character Recognition (OCR) model runs at a higher resolution than Computer Vision Read and extracts print and handwritten text from PDF documents and scanned images. It also includes preview support for extracting text from Microsoft Word, Excel, PowerPoint, and HTML documents. It detects paragraphs, text lines, words, locations, and languages. The Read model is the underlying OCR engine for other Form Recognizer prebuilt models like Layout, General Document, Invoice, Receipt, Identity (ID) document, in addition to custom models.

+## Read OCR supported document types

+Form Recognizer v3.0 supports the following resources:

+Try extracting text from forms and documents using the Form Recognizer Studio. You need the following assets:

+### Form Recognizer Studio

+### Extracting barcodes from documents

+The Read OCR model extracts all identified barcodes in the `barcodes` collection as a top level object under `content`. Inside the `content`, detected barcodes are represented as `:barcode:`. Each entry in this collection represents a barcode and includes the barcode type as `kind` and the embedded barcode content as `value` along with its `polygon` coordinates. Initially, barcodes appear at the end of each page. Here, the `confidence` is hard-coded for the public preview (`2023-02-28`) release.

+#### Supported barcode types

+| **Barcode Type** | **Example** |

+| | |

+| QR Code |:::image type="content" source="media/barcodes/qr-code.png" alt-text="Screenshot of the QR Code.":::|

+| Code 39 |:::image type="content" source="media/barcodes/code-39.png" alt-text="Screenshot of the Code 39.":::|

+| Code 128 |:::image type="content" source="media/barcodes/code-128.png" alt-text="Screenshot of the Code 128.":::|

+| UPC (UPC-A & UPC-E) |:::image type="content" source="media/barcodes/upc.png" alt-text="Screenshot of the UPC.":::|

+| PDF417 |:::image type="content" source="media/barcodes/pdf-417.png" alt-text="Screenshot of the PDF417.":::|

+```json

+"content": ":barcode:",

+ "pages": [

+ {

+ "pageNumber": 1,

+ "barcodes": [

+ {

+ "kind": "QRCode",

+ "value": "http://test.com/",

+ "span": { ... },

+ "polygon": [...],

+ "confidence": 1

+ }

+ ]

+ }

+ ]

+```

+### Language detection

+The Read OCR model in Form Recognizer adds [language detection](language-support.md#detected-languages-read-api) as a new feature for text lines. Read predicts the detected primary language for each text line along with the `confidence` in the `languages` collection under `analyzeResult`.

+For the preview of Microsoft Word, Excel, PowerPoint, and HTML file support, Read extracts all embedded text as is. For any embedded images, it runs OCR on the images to extract text and append the text from each image as an added entry to the `pages` collection. These added entries include the extracted text lines and words, their bounding polygons, confidences, and the spans pointing to the associated text.

+## Supported languages and locales

+### [**2022-08-31 (GA)**](#tab/2022-08-31)

+#### Thermal receipts (retail, meal, parking, etc.)

+| Supported Languages | Details |

+|:--|:-:|

+|English|United States (`en-US`), Australia (`en-AU`), Canada (`en-CA`), United Kingdom (`en-GB`), India (`en-IN`), United Arab Emirates (`en-AE`)|

+|Croatian|Croatia (`hr-HR`)|

+|Czech|Czechia (`cs-CZ`)|

+|Danish|Denmark (`da-DK`)|

+|Dutch|Netherlands (`nl-NL`)|

+|Finnish|Finland (`fi-FI`)|

+|French|Canada (`fr-CA`), France (`fr-FR`)|

+|German|Germany (`de-DE`)|

+|Hungarian|Hungary (`hu-HU`)|

+|Italian|Italy (`it-IT`)|

+|Japanese|Japan (`ja-JP`)|

+|Latvian|Latvia (`lv-LV`)|

+|Lithuanian|Lithuania (`lt-LT`)|

+|Norwegian|Norway (`no-NO`)|

+|Portuguese|Brazil (`pt-BR`), Portugal (`pt-PT`)|

+|Spanish|Spain (`es-ES`)|

+|Swedish|Sweden (`sv-SE`)|

+|Vietnamese|Vietnam (`vi-VN`)|

+#### Hotel receipts

+| Supported Languages | Details |

+|:--|:-:|

+|English|United States (`en-US`)|

+|French|France (`fr-FR`)|

+|German|Germany (`de-DE`)|

+|Italian|Italy (`it-IT`)|

+|Japanese|Japan (`ja-JP`)|

+|Portuguese|Portugal (`pt-PT`)|

+|Spanish|Spain (`es-ES`)|

+### [2023-02-28-preview](#tab/2023-02-28-preview)

+#### Thermal receipts (retail, meal, parking, etc.)

+| Supported Languages | Details |

+|:--|:-:|

+|English|United States (`en-US`), Australia (`en-AU`), Canada (`en-CA`), United Kingdom (`en-GB`), India (`en-IN`), United Arab Emirates (`en-AE`)|

+|Croatian|Croatia (`hr-HR`)|

+|Czech|Czechia (`cs-CZ`)|

+|Danish|Denmark (`da-DK`)|

+|Dutch|Netherlands (`nl-NL`)|

+|Finnish|Finland (`fi-FI`)|

+|French|Canada (`fr-CA`), France (`fr-FR`)|

+|German|Germany (`de-DE`)|

+|Hungarian|Hungary (`hu-HU`)|

+|Italian|Italy (`it-IT`)|

+|Japanese|Japan (`ja-JP`)|

+|Latvian|Latvia (`lv-LV`)|

+|Lithuanian|Lithuania (`lt-LT`)|

+|Norwegian|Norway (`no-NO`)|

+|Portuguese|Brazil (`pt-BR`), Portugal (`pt-PT`)|

+|Spanish|Spain (`es-ES`)|

+|Swedish|Sweden (`sv-SE`)|

+|Vietnamese|Vietnam (`vi-VN`)|

+#### Hotel receipts

+| Supported Languages | Details |

+|:--|:-:|

+|English|United States (`en-US`)|

+|French|France (`fr-FR`)|

+|German|Germany (`de-DE`)|

+|Italian|Italy (`it-IT`)|

+|Japanese|Japan (`ja-JP`)|

+|Portuguese|Portugal (`pt-PT`)|

+|Spanish|Spain (`es-ES`)|

+ Form Recognizer v3.0 introduces several new features and capabilities. In addition to thermal receipts, the **Receipt** model supports single-page hotel receipt processing and tax detail extraction for all receipt types.

+### [**2022-08-31 (GA)**](#tab/2022-08-31)

+#### Thermal receipts (receipt, receipt.retailMeal, receipt.creditCard, receipt.gas, receipt.parking)

+| Field | Type | Description | Example |

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

+|`MerchantName`|`string`|Name of the merchant issuing the receipt|Contoso|

+|`MerchantPhoneNumber`|`phoneNumber`|Listed phone number of merchant|987-654-3210|

+|`MerchantAddress`|`address`|Listed address of merchant|123 Main St. Redmond WA 98052|

+|`Total`|`number`|Full transaction total of receipt|$14.34|

+|`TransactionDate`|`date`|Date the receipt was issued|June 06, 2019|

+|`TransactionTime`|`time`|Time the receipt was issued|4:49 PM|

+|`Subtotal`|`number`|Subtotal of receipt, often before taxes are applied|$12.34|

+|`TotalTax`|`number`|Tax on receipt, often sales tax or equivalent|$2.00|

+|`Tip`|`number`|Tip included by buyer|$1.00|

+|`Items`|`array`|||

+|`Items.*`|`object`|Extracted line item|1<br>Surface Pro 6<br>$999.00<br>$999.00|

+|`Items.*.TotalPrice`|`number`|Total price of line item|$999.00|

+|`Items.*.Description`|`string`|Item description|Surface Pro 6|

+|`Items.*.Quantity`|`number`|Quantity of each item|1|

+|`Items.*.Price`|`number`|Individual price of each item unit|$999.00|

+|`Items.*.ProductCode`|`string`|Product code, product number, or SKU associated with the specific line item|A123|

+|`Items.*.QuantityUnit`|`string`|Quantity unit of each item||

+|`TaxDetails`|`array`|||

+|`TaxDetails.*`|`object`|Extracted line item|1<br>Surface Pro 6<br>$999.00<br>$999.00|

+|`TaxDetails.*.Amount`|`currency`|The amount of the tax detail|$999.00|

+#### Hotel receipts (receipt.hotel)

+| Field | Type | Description | Example |

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

+|`MerchantName`|`string`|Name of the merchant issuing the receipt|Contoso|

+|`MerchantPhoneNumber`|`phoneNumber`|Listed phone number of merchant|987-654-3210|

+|`MerchantAddress`|`address`|Listed address of merchant|123 Main St. Redmond WA 98052|

+|`Total`|`number`|Full transaction total of receipt|$14.34|

+|`ArrivalDate`|`date`|Date of arrival|27Mar21|

+|`DepartureDate`|`date`|Date of departure|28Mar21|

+|`Currency`|`string`|Currency unit of receipt amounts (ISO 4217), or 'MIXED' if multiple values are found|USD|

+|`MerchantAliases`|`array`|||

+|`MerchantAliases.*`|`string`|Alternative name of merchant|Contoso (R)|

+|`Items`|`array`|||

+|`Items.*`|`object`|Extracted line item|1<br>Surface Pro 6<br>$999.00<br>$999.00|

+|`Items.*.TotalPrice`|`number`|Total price of line item|$999.00|

+|`Items.*.Description`|`string`|Item description|Room Charge|

+|`Items.*.Date`|`date`|Item date|27Mar21|

+|`Items.*.Category`|`string`|Item category|Room|

+### [2023-02-28-preview](#tab/2023-02-28-preview)

+#### Thermal receipts (receipt, receipt.retailMeal, receipt.creditCard, receipt.gas, receipt.parking)

+| Field | Type | Description | Example |

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

+|`MerchantName`|`string`|Name of the merchant issuing the receipt|Contoso|

+|`MerchantPhoneNumber`|`phoneNumber`|Listed phone number of merchant|987-654-3210|

+|`MerchantAddress`|`address`|Listed address of merchant|123 Main St. Redmond WA 98052|

+|`Total`|`number`|Full transaction total of receipt|$14.34|

+|`TransactionDate`|`date`|Date the receipt was issued|June 06, 2019|

+|`TransactionTime`|`time`|Time the receipt was issued|4:49 PM|

+|`Subtotal`|`number`|Subtotal of receipt, often before taxes are applied|$12.34|

+|`TotalTax`|`number`|Tax on receipt, often sales tax or equivalent|$2.00|

+|`Tip`|`number`|Tip included by buyer|$1.00|

+|`Items`|`array`|||

+|`Items.*`|`object`|Extracted line item|1<br>Surface Pro 6<br>$999.00<br>$999.00|

+|`Items.*.TotalPrice`|`number`|Total price of line item|$999.00|

+|`Items.*.Description`|`string`|Item description|Surface Pro 6|

+|`Items.*.Quantity`|`number`|Quantity of each item|1|

+|`Items.*.Price`|`number`|Individual price of each item unit|$999.00|

+|`Items.*.ProductCode`|`string`|Product code, product number, or SKU associated with the specific line item|A123|

+|`Items.*.QuantityUnit`|`string`|Quantity unit of each item||

+|`TaxDetails`|`array`|||

+|`TaxDetails.*`|`object`|Extracted line item|1<br>Surface Pro 6<br>$999.00<br>$999.00|

+|`TaxDetails.*.Amount`|`currency`|The amount of the tax detail|$999.00|

+#### Hotel receipts (receipt.hotel)

+| Field | Type | Description | Example |

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

+|`MerchantName`|`string`|Name of the merchant issuing the receipt|Contoso|

+|`MerchantPhoneNumber`|`phoneNumber`|Listed phone number of merchant|987-654-3210|

+|`MerchantAddress`|`address`|Listed address of merchant|123 Main St. Redmond WA 98052|

+|`Total`|`number`|Full transaction total of receipt|$14.34|

+|`ArrivalDate`|`date`|Date of arrival|27Mar21|

+|`DepartureDate`|`date`|Date of departure|28Mar21|

+|`Currency`|`string`|Currency unit of receipt amounts (ISO 4217), or 'MIXED' if multiple values are found|USD|

+|`MerchantAliases`|`array`|||

+|`MerchantAliases.*`|`string`|Alternative name of merchant|Contoso (R)|

+|`Items`|`array`|||

+|`Items.*`|`object`|Extracted line item|1<br>Surface Pro 6<br>$999.00<br>$999.00|

+|`Items.*.TotalPrice`|`number`|Total price of line item|$999.00|

+|`Items.*.Description`|`string`|Item description|Room Charge|

+|`Items.*.Date`|`date`|Item date|27Mar21|

+|`Items.*.Category`|`string`|Item category|Room|

+An employer sends form W-2, also known as the Wage and Tax Statement, to each employee and the Internal Revenue Service (IRS) at the end of the year. A W-2 form reports employees' annual wages and the amount of taxes withheld from their paychecks. The IRS also uses W-2 forms to track individuals' tax obligations. The Social Security Administration (SSA) uses the information on this and other forms to compute the Social Security benefits for all workers.

+Form Recognizer v3.0 supports the following tools:

+Try extracting data from W-2 forms using the Form Recognizer Studio. You need the following resources:

+| Verification&#8203;Code | 9 | String | Verification Code on Form W-2 | A123-B456-C789-DXYZ |

+* Try processing your own forms and documents with the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)

+* Complete a [Form Recognizer quickstart](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true) and get started creating a document processing app in the development language of your choice.

+ Title: "Build and train a custom classifier"

+description: Learn how to label, and build a custom document classifier model.

+monikerRange: 'form-recog-3.0.0'

+recommendations: false

+# Build and train a custom classifier model

+Custom classifier models can classify each page in an input file to identify the document(s) within. Classifier models can also identify multiple documents or multiple instances of a single document in the input file. Form Recognizer custom models require as few as five training documents per document class to get started. To get started training a custom classifier model, you need at least **five documents** for each class and **two classes** of documents.

+## Custom classifier model input requirements

+Make sure your training data set follows the input requirements for Form Recognizer.

+## Training data tips

+Follow these tips to further optimize your data set for training:

+* If possible, use text-based PDF documents instead of image-based documents. Scanned PDFs are handled as images.

+* If your form images are of lower quality, use a larger data set (10-15 images, for example).

+## Upload your training data

+Once you've put together the set of forms or documents for training, you need to upload it to an Azure blob storage container. If you don't know how to create an Azure storage account with a container, follow the [Azure Storage quickstart for Azure portal](../../../storage/blobs/storage-quickstart-blobs-portal.md). You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production. If your dataset is organized as folders, preserve that structure as the Studio can use your folder names for labels to simplify the labeling process.

+## Create a classification project in the Form Recognizer Studio

+The Form Recognizer Studio provides and orchestrates all the API calls required to complete your dataset and train your model.

+1. Start by navigating to the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio). The first time you use the Studio, you need to [initialize your subscription, resource group, and resource](../quickstarts/try-v3-form-recognizer-studio.md). Then, follow the [prerequisites for custom projects](../quickstarts/try-v3-form-recognizer-studio.md#additional-prerequisites-for-custom-projects) to configure the Studio to access your training dataset.

+1. In the Studio, select the **Custom classifier models** tile, on the custom models section of the page and select the **Create a project** button.

+ :::image type="content" source="../media/how-to/studio-create-classifier-project.png" alt-text="Screenshot of how to create a classifier project in the Form Recognizer Studio.":::

+ 1. On the create project dialog, provide a name for your project, optionally a description, and select continue.

+ 1. Next, choose or create a Form Recognizer resource before you select continue.

+ :::image type="content" source="../media/how-to/studio-select-resource.png" alt-text="Screenshot showing the project setup dialog window.":::

+1. Next select the storage account you used to upload your custom model training dataset. The **Folder path** should be empty if your training documents are in the root of the container. If your documents are in a subfolder, enter the relative path from the container root in the **Folder path** field. Once your storage account is configured, select continue.

+ > [!IMPORTANT]

+ > You can either organize the training dataset by folders where the folder name is the label or class for documents or create a flat list of documents that you can assign a label to in the Studio.

+ :::image type="content" source="../media/how-to/studio-select-storage.png" alt-text="Screenshot showing how to select the Form Recognizer resource.":::

+1. Training a custom classifier requires the output from the Layout model for each document in your dataset. Run layout on all documents as an optional step to speed up the model training process.

+1. Finally, review your project settings and select **Create Project** to create a new project. You should now be in the labeling window and see the files in your dataset listed.

+## Label your data

+In your project, you only need to label each document with the appropriate class label.

+You see the files you uploaded to storage in the file list, ready to be labeled. You have a few options to label your dataset.

+1. If the documents are organized in folders, the Studio prompts you to use the folder names as labels. This step simplifies your labeling down to a single select.

+1. To assign a label to a document, select on the add label selection mark to assign a label.

+1. Control select to multi-select documents to assign a label

+You should now have all the documents in your dataset labeled. If you look at the storage account, you find *.ocr.json* files that correspond to each document in your training dataset and a new **class-name.jsonl** file for each class labeled. This training dataset is submitted to train the model.

+## Train your model

+With your dataset labeled, you're now ready to train your model. Select the train button in the upper-right corner.

+1. On the train model dialog, provide a unique classifier ID and, optionally, a description. The classifier ID accepts a string data type.

+1. Select **Train** to initiate the training process.

+1. Classifier models train in a few minutes.

+1. Navigate to the *Models* menu to view the status of the train operation.

+## Test the model

+Once the model training is complete, you can test your model by selecting the model on the models list page.

+1. Select the model and select on the **Test** button.

+1. Add a new file by browsing for a file or dropping a file into the document selector.

+1. With a file selected, choose the **Analyze** button to test the model.

+1. The model results are displayed with the list of identified documents, a confidence score for each document identified and the page range for each of the documents identified.

+1. Validate your model by evaluating the results for each document identified.

+Congratulations you've trained a custom classifier model in the Form Recognizer Studio! Your model is ready for use with the REST API or the SDK to analyze documents.

+## Next steps

+> [!div class="nextstepaction"]

+> [Learn about custom model types](../concept-custom.md)

+> [!div class="nextstepaction"]

+> [Learn about accuracy and confidence with custom models](../concept-accuracy-confidence.md)

+A composed model is created by taking a collection of custom models and assigning them to a single model ID. You can assign up to 200 trained custom models to a single composed model ID. When a document is submitted to a composed model, the service performs a classification step to decide which custom model accurately represents the form presented for analysis. Composed models are useful when you've trained several models and want to group them to analyze similar form types. For example, your composed model might include custom models trained to analyze your supply, equipment, and furniture purchase orders. Instead of manually trying to select the appropriate model, you can use a composed model to determine the appropriate custom model for each analysis and extraction.

+In this article, you learn how to create and use composed custom models to analyze your forms and documents.

+To get started, you need the following resources:

+ 1. Copy the **Keys and Endpoint** values from the Azure portal and paste them in a convenient location, such as *Microsoft Notepad*. You need the key and endpoint values to connect your application to the Form Recognizer API.

+First, you need a set of custom models to compose. You can use the Form Recognizer Studio, REST API, or client-library SDKs. The steps are as follows:

+Building a custom model begins with establishing your training dataset. You need a minimum of five completed forms of the same type for your sample dataset. They can be of different file types (jpg, png, pdf, tiff) and contain both text and handwriting. Your forms must follow the [input requirements](../how-to-guides/build-a-custom-model.md?view=form-recog-2.1.0&preserve-view=true#custom-model-input-requirements) for Form Recognizer.

+When you've gathered a set of training documents, you need to [upload your training data](../how-to-guides/build-a-custom-model.md?view=form-recog-2.1.0&preserve-view=true#upload-your-training-data) to an Azure blob storage container.

+If you want to use manually labeled data, you have to upload the *.labels.json* and *.ocr.json* files that correspond to your training documents.

+Label files contain key-value associations that a user has entered manually. They're needed for labeled data training, but not every source file needs to have a corresponding label file. Source files without labels are treated as ordinary training documents. We recommend five or more labeled files for reliable training. You can use a UI tool like [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/customform/projects) to generate these files.

+1. When the operation completes, your newly composed model appears in the list.

+In this article, you learn how to create Form Recognizer custom and composed models using our [Form Recognizer Sample Labeling tool](../label-tool.md), [REST APIs](../how-to-guides/use-sdk-rest-api.md?view=form-recog-2.1.0&preserve-view=true#train-a-custom-model), or [client-library SDKs](../how-to-guides/use-sdk-rest-api.md?view=form-recog-2.1.0&preserve-view=true#train-a-custom-model).

+Try extracting data from custom forms using our Sample Labeling tool. You need the following resources:

+Building a custom model begins with establishing your training dataset. You need a minimum of five completed forms of the same type for your sample dataset. They can be of different file types (jpg, png, pdf, tiff) and contain both text and handwriting. Your forms must follow the [input requirements](build-a-custom-model.md?view=form-recog-2.1.0&preserve-view=true#custom-model-input-requirements) for Form Recognizer.

+You need to [upload your training data](build-a-custom-model.md?view=form-recog-2.1.0&preserve-view=true#upload-your-training-data)

+With the Model Compose operation, you can assign up to 200 trained custom models to a single model ID. When you call Analyze with the composed model ID, Form Recognizer classifies the form you submitted first, chooses the best matching assigned model, and then returns results for that model. This operation is useful when incoming forms may belong to one of several templates.

+Using the Form Recognizer Sample Labeling tool, the REST API, or the Client-library SDKs, follow the steps to set up a composed model:

+Once the training process has successfully completed, your custom model is assigned a model ID. You can retrieve a model ID as follows:

+The [**REST API**](build-a-custom-model.md?view=form-recog-2.1.0&preserve-view=true#train-your-model) returns a `201 (Success)` response with a **Location** header. The value of the last parameter in this header is the model ID for the newly trained model:

+When the operation completes, your newly composed model appears in the list.

+Use the programming language code of your choice to create a composed model that is called with a single model ID. The following links are code samples that demonstrate how to create a composed model from existing custom models:

+1. The tool applies tags in bounding boxes and reports the confidence percentage for each tag.

+Using the programming language of your choice to analyze a form or document with a custom or composed model. You need your Form Recognizer endpoint, key, and model ID.

+ In this guide, you learn how to add Form Recognizer models to your applications and workflows using a programming language SDK of your choice or the REST API. Azure Form Recognizer is a cloud-based Azure Applied AI Service that uses machine learning to extract key text and structure elements from documents. We recommend that you use the free service as you're learning the technology. Remember that the number of free pages is limited to 500 per month.

+> * The [prebuilt-healthInsuranceCard.us](../concept-insurance-card.md) model extracts key information from US health insurance cards.

+>

+In this how-to guide, you learn how to add Form Recognizer to your applications and workflows using an SDK, in a programming language of your choice, or the REST API. Azure Form Recognizer is a cloud-based Azure Applied AI Service that uses machine learning to extract key-value pairs, text, and tables from your documents. We recommend that you use the free service when you're learning the technology. Remember that the number of free pages is limited to 500 per month.

+You use the following APIs to extract structured data from forms and documents:

+In this article, you use the Form Recognizer REST API with the Sample Labeling tool to train a custom model with manually labeled data.

+ You need the following resources to complete this project:

+ * You need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. You paste your key and endpoint into the code later in the quickstart.

+* A set of at least six forms of the same type. You use this data to train the model and test a form. You can use a [sample data set](https://go.microsoft.com/fwlink/?linkid=2090451) (download and extract *sample_data.zip*) for this quickstart. Upload the training files to the root of a blob storage container in a standard-performance-tier Azure Storage account.

+You need an Azure subscription ([create one for free](https://azure.microsoft.com/free/cognitive-services)) and a [Form Recognizer resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer) endpoint and key to try out the Form Recognizer service.

+You use the Docker engine to run the Sample Labeling tool. Follow these steps to set up the Docker container. For a primer on Docker and container basics, see the [Docker overview](https://docs.docker.com/engine/docker-overview/).

+1. First, install Docker on a host computer. This guide shows you how to use local computer as a host. If you want to use a Docker hosting service in Azure, see the [Deploy the Sample Labeling tool](deploy-label-tool.md) how-to guide.

+ This command makes the sample-labeling tool available through a web browser. Go to `http://localhost:3000`.

+First, make sure all the training documents are of the same format. If you have forms in multiple formats, organize them into subfolders based on common format. When you train, you need to direct the API to a subfolder.

+* **Security Token** - Some project settings can include sensitive values, such as keys or other shared secrets. Each project generates a security token that can be used to encrypt/decrypt sensitive project settings. You can find security tokens in the Application Settings by selecting the gear icon at the bottom of the left navigation bar.

+Select **Run Layout on unvisited documents** on the left pane to get the text and table layout information for each document. The labeling tool draws bounding boxes around each text element.

+The labeling tool also shows which tables have been automatically extracted. Select the table/grid icon on the left hand of the document to see the extracted table. In this quickstart, because the table content is automatically extracted, we don't label the table content, but rather rely on the automated extraction.

+Next, you create tags (labels) and apply them to the text elements that you want the model to analyze.

+You can set the expected data type for each tag. Open the context menu to the right of a tag and select a type from the menu. This feature allows the detection algorithm to make assumptions that improve the text-detection accuracy. It also ensures that the detected values are returned in a standardized format in the final JSON output. Value type information is saved in the **fields.json** file in the same path as your label files.

+ * Example: 1234.98 on the document is formatted into 1234.98 on the output

+ * Example: 1234.98 on the document is formatted into 123498 on the output.

+At times, your data might lend itself better to being labeled as a table rather than key-value pairs. In this case, you can create a table tag by selecting **Add a new table tag**. Specify whether the table has a fixed number of rows or variable number of rows depending on the document and define the schema.

+Choose the Train icon on the left pane to open the Training page. Then select the **Train** button to begin training the model. Once the training process completes, you see the following information:

+* **Model ID** - The ID of the model that was created and trained. Each training call creates a new model with its own ID. Copy this string to a secure location; you need it if you want to do prediction calls through the [REST API](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api?pivots=programming-language-rest-api&tabs=preview%2cv2-1) or [client library guide](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api).

+After training finishes, examine the **Average Accuracy** value. If it's low, you should add more input documents and repeat the labeling steps. The documents you've already labeled remain in the project index.

+With Model Compose, you can compose up to 200 models to a single model ID. When you call Analyze with the composed `modelID`, Form Recognizer classifies the form you submitted, choose the best matching model, and then return results for that model. This operation is useful when incoming forms may belong to one of several templates.

+Select the Analyze icon from the navigation bar to test your model. Select source 'Local file'. Browse for a file and select a file from the sample dataset that you unzipped in the test folder. Then choose the **Run analysis** button to get key/value pairs, text and tables predictions for the form. The tool applies tags in bounding boxes and reports the confidence of each tag.

+Finally, go to the main page (house icon) and select **Open Cloud Project**. Then select the blob storage connection, and select your project's `.fott` file. The application loads all of the project's settings because it has the security token.

+The following lists include the currently GA languages in the most recent v3.0 version for Read, Layout, and Custom template (form) models.

+Language| API Version |

+|English | `2022-08-31` (GA), `2023-02-28-preview`|

+|Spanish | `2023-02-28-preview`|

+|German | `2023-02-28-preview`|

+|French | `2023-02-28-preview`|

+|Italian | `2023-02-28-preview`|

+|Dutch | `2023-02-28-preview`|

+Receipt supports all English receipts and the following locales:

+|English |`en-au`|

+|French | `fr` |

+| Spanish | `es` |

+|English |`en-US`, `en-CA`, `en-GB`, `en-IN`|

+|German | de|

+|French | fr|

+|Italian |it|

+|Portuguese |pt|

+|Dutch | nl|

+|English |`en-US`, `en-CA`, `en-GB`, `en-IN`|

+|German | de|

+|French | fr|

+|Italian |it|

+|Portuguese |pt|

+|Dutch | nl|

+ > It's not necessary to specify a locale. This is an optional parameter. The Form Recognizer deep-learning technology will auto-detect the language of the text in your image.

+|Language| Locale code |

+|English (Australia)|`en-au`|

+|English (Canada)|`en-ca`|

+|English (United Kingdom)|`en-gb`|

+|English (India|`en-in`|

+|English (United States)| `en-us`|

+Language| Locale code |

+|:--|:-:|

+|English (United States)|en-us|

+Azure Form Recognizer is a cloud-based [Azure Applied AI Service](../../applied-ai-services/index.yml) for developers to build intelligent document processing solutions. Form Recognizer applies machine-learning-based optical character recognition (OCR) and document understanding technologies to classify documents, extract text, tables, structure, and key-value pairs from documents. You can also label and train custom models to automate data extraction from structured, semi-structured, and unstructured documents. To learn more about each model, *see* the Concepts articles:

+This section helps you decide which **Form Recognizer v3.0** supported model you should use for your application:

+|**A generic document** like a contract or letter.|You want to extract primarily text lines, words, locations, and detected languages.|The document is written or printed in a [supported language](language-support.md#read-layout-and-custom-form-template-model).| [**Read OCR model**](concept-read.md)|

+|**U.S. W-2 form**|You want to extract key information such as salary, wages, and taxes withheld from US W2 tax forms. |The W-2 document is in United States English (en-US) text.|[**W-2 model**](concept-w2.md)

+|**Invoice**|You want to extract key information such as customer name, billing address, and amount due from invoices. |The invoice document is written or printed in a [supported language](language-support.md#invoice-model).|[**Invoice model**](concept-invoice.md)

+ |**Receipt**|You want to extract key information such as merchant name, transaction date, and transaction total from a sales or single-page hotel receipt. |The receipt is written or printed in a [supported language](language-support.md#receipt-model). |[**Receipt model**](concept-receipt.md)|

+|**Business card**|You want to extract key information such as first name, last name, company name, email address, and phone number from business cards.|The business card document is in English or Japanese text. | [**Business card model**](concept-business-card.md)|

+|**Application specific documents**| You want to extract key-value pairs, selection marks, tables, signature fields, and selected regions not extracted by prebuilt or general document models.| You have various documents with structured, semi-structured, and/or unstructured elements.| [**Custom extraction model**](concept-custom.md)|

+|**Mixed-type document(s)**| You want to classify documents or split a file into individual documents.| You have various documents with structured, semi-structured, and/or unstructured elements.| [**Custom classification model**](concept-custom.md)|

+|[**Read OCR model**](concept-read.md)|Extract text lines, words, detected languages, and handwritten style if detected.| &#9679; Contract processing. </br>&#9679; Financial or medical report processing.|&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/read)</br>&#9679; [**REST API**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-rest-api)</br>&#9679; [**C# SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-csharp)</br>&#9679; [**Python SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-python)</br>&#9679; [**Java SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-java)</br>&#9679; [**JavaScript**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-javascript) |

+|[**General document model**](concept-general-document.md)|Extract text, tables, structure, and key-value pairs.|&#9679; Key-value pair extraction.</br>&#9679; Form processing.</br>&#9679; Survey data collection and analysis.|&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/document)</br>&#9679; [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model) |

+|[**Layout analysis model**](concept-layout.md) | Extract text, selection marks, and tables structures, along with their bounding box coordinates, from forms and documents.</br></br> Layout API has been updated to a prebuilt model. |&#9679; Document indexing and retrieval by structure.</br>&#9679; Preprocessing prior to OCR analysis. |&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/layout)</br>&#9679; [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)|

+|[**Custom model (updated)**](concept-custom.md) | Classification, extraction and analysis of data from forms and documents specific to distinct business data and use cases. Custom model API v3.0 supports two model types:&#9679; [**Custom Classifier model**](concept-custom-classifier.md) is used to identify and split document types.</br>&#9679; [**Custom Extraction model**](concept-custom.md) is used to analyze forms or documents and extract specific fields and tables. [Custom template](concept-custom-template.md) and [custom neural](concept-custom-neural.md) are the two types of custom extraction models.|&#9679; Identification and extraction of data from documents unique to your business, impacted by a regulatory change or market event.</br>&#9679; Identification and analysis of previously overlooked unique data. |&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&#9679; [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md)|

+|[**W-2 Form**](concept-w2.md) | Extract information reported in each box on a W-2 form.|&#9679; Automated tax document management.</br>&#9679; Mortgage loan application processing. |&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2)&#9679; [**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/AnalyzeDocument)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model) |

+|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. |&#9679; Accounts payable processing.</br>&#9679; Automated tax recording and reporting. |&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice)</br>&#9679; [**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)|

+|[**Receipt model (updated)**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.</br></br>Receipt model v3.0 supports processing of **single-page hotel receipts**.|&#9679; Expense management.</br>&#9679; Consumer behavior data analysis.</br>&#9679; Customer loyalty program.</br>&#9679; Merchandise return processing.</br>&#9679; Automated tax recording and reporting. |&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=receipt)</br>&#9679; [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)|

+|[**Identity document (ID) model (updated)**](concept-id-document.md) |Automated data processing and extraction of key information from US driver's licenses and international passports.</br></br>Prebuilt ID document API supports the **extraction of endorsements, restrictions, and vehicle classifications from US driver's licenses**. |&#9679; Know your customer (KYC) financial services guidelines compliance.</br>&#9679; Medical account management.</br>&#9679; Identity checkpoints and gateways.</br>&#9679; Hotel registration. |&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=idDocument)</br>&#9679; [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)|

+|[**Business card model**](concept-business-card.md) |Automated data processing and extraction of key information from business cards.|&#9679; Sales lead and marketing management. |&#9679; [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard)</br>&#9679; [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</br>&#9679; [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)|

+This section helps you decide which Form Recognizer v2.1 supported model you should use for your application:

+|**Invoice**|You want to extract key information such as customer name, billing address, and amount due from invoices. |The invoice document is written or printed in a [supported language](language-support.md#invoice-model).|[**Invoice model**](concept-invoice.md?view=form-recog-2.1.0&preserve-view=true)

+ |**Receipt**|You want to extract key information such as merchant name, transaction date, and transaction total from a sales or single-page hotel receipt. |The receipt is written or printed in a [supported language](language-support.md#receipt-model). |[**Receipt model**](concept-receipt.md?view=form-recog-2.1.0&preserve-view=true)|

+|**Business card**|You want to extract key information such as first name, last name, company name, email address, and phone number from business cards.|The business card document is in English or Japanese text. | [**Business card model**](concept-business-card.md?view=form-recog-2.1.0&preserve-view=true)|

+|[**Layout analysis**](concept-layout.md?view=form-recog-2.1.0&preserve-view=true) | Extraction and analysis of text, selection marks, tables, and bounding box coordinates, from forms and documents. | &#9679; [**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-layout)</br>&#9679; [**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-layout-model)</br>&#9679; [**Client-library SDK**](quickstarts/get-started-sdks-rest-api.md)</br>&#9679; [**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?branch=main&tabs=layout#run-the-container-with-the-docker-compose-up-command)|

+|[**Custom model**](concept-custom.md?view=form-recog-2.1.0&preserve-view=true) | Extraction and analysis of data from forms and documents specific to distinct business data and use cases.| &#9679; [**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#train-a-custom-form-model)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md)</br>&#9679; [**Sample Labeling Tool**](concept-custom.md?view=form-recog-2.1.0&preserve-view=true#build-a-custom-model)</br>&#9679; [**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=custom#run-the-container-with-the-docker-compose-up-command)|

+|[**Invoice model**](concept-invoice.md?view=form-recog-2.1.0&preserve-view=true) | Automated data processing and extraction of key information from sales invoices. | &#9679; [**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</br>&#9679; [**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</br>&#9679; [**Client-library SDK**](quickstarts/get-started-sdks-rest-api.md#try-it-prebuilt-model)</br>&#9679; [**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=invoice#run-the-container-with-the-docker-compose-up-command)|

+|[**Receipt model**](concept-receipt.md?view=form-recog-2.1.0&preserve-view=true) | Automated data processing and extraction of key information from sales receipts.| &#9679; [**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</br>&#9679; [**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</br>&#9679; [**Client-library SDK**](quickstarts/get-started-sdks-rest-api.md)</br>&#9679; [**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=receipt#run-the-container-with-the-docker-compose-up-command)|

+|[**Identity document (ID) model**](concept-id-document.md?view=form-recog-2.1.0&preserve-view=true) | Automated data processing and extraction of key information from US driver's licenses and international passports.| &#9679; [**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</br>&#9679; [**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</br>&#9679; [**Client-library SDK**](quickstarts/get-started-sdks-rest-api.md)</br>&#9679; [**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=id-document#run-the-container-with-the-docker-compose-up-command)|

+|[**Business card model**](concept-business-card.md?view=form-recog-2.1.0&preserve-view=true) | Automated data processing and extraction of key information from business cards.| &#9679; [**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</br>&#9679; [**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</br>&#9679; [**Client-library SDK**](quickstarts/get-started-sdks-rest-api.md)</br>&#9679; [**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=business-card#run-the-container-with-the-docker-compose-up-command)|

+description: Form and document processing, data extraction, and analysis using Form Recognizer Studio

+<!-- markdownlint-disable MD001 -->

+# Get started: Form Recognizer Studio

+[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/) is an online tool for visually exploring, understanding, and integrating features from the Form Recognizer service in your applications. You can get started by exploring the pretrained models with sample or your own documents. You can also create projects to build custom template models and reference the models in your applications using the [Python SDK](get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true) and other quickstarts.

+## Models

+Prebuilt models help you add Form Recognizer features to your apps without having to build, train, and publish your own models. You can choose from several prebuilt models, each of which has its own set of supported data fields. The choice of model to use for the analyze operation depends on the type of document to be analyzed. Form Recognizer currently supports the following prebuilt models:

+#### Document analysis

+* [**Read**](https://formrecognizer.appliedai.azure.com/studio/read): extract text lines, words, their locations, detected languages, and handwritten style if detected from documents (PDF, TIFF) and images (JPG, PNG, BMP).

+#### Prebuilt

+* [**Health insurance card**](https://formrecognizer-dogfood.appliedai.azure.com/studio/prebuilt?formType=healthInsuranceCard.us): extract insurer, member, prescription, group number and other key information from US health insurance cards.

+* [**W-2**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2): extract text and key information from W-2 tax forms.

+#### Custom

+* [**Custom extraction models**](https://formrecognizer-dogfood.appliedai.azure.com/studio/custommodel/projects): extract information from forms and documents with custom extraction models. Quickly train a model by labeling as few as five sample documents.

+* [**Custom classifier model**](https://formrecognizer-dogfood.appliedai.azure.com/studio/document-classifier/projects): train a custom classifier to distinguish between the different document types within your applications. Quickly train a model with as few as two classes and five samples per class.

+#### Gated preview models

+> [!NOTE]

+> To request access for gated preview models in Form Recognizer Studio, complete and submit the [**Form Recognizer private preview request form**](https://aka.ms/form-recognizer/preview/survey).

+* [**General document with query fields**](https://formrecognizer.appliedai.azure.com/studio): extract labels, values such as names, dates, and amounts from documents.

+* [**Contract**](https://formrecognizer.appliedai.azure.com/studio): extract the title and signatory party information (including names, references, and addresses) from contracts.

+* [**Vaccination card**](https://formrecognizer.appliedai.azure.com/studio): extract card holder name, health provider, and vaccination records from US COVID-19 vaccination cards.

+* [**US 1098 tax form**](https://formrecognizer.appliedai.azure.com/studio): extract mortgage interest information from US 1098 tax forms.

+* [**US 1098-E tax form**](https://formrecognizer.appliedai.azure.com/studio): extract student loan information from US 1098-E tax forms.

+* [**US 1098-T tax form**](https://formrecognizer.appliedai.azure.com/studio): extract tuition information from US 1098-T forms.

+> [!NOTE]

+> To request access for gated preview models in Form Recognizer Studio, complete and submit the [**Form Recognizer private preview request form**](https://aka.ms/form-recognizer/preview/survey).

+After you've completed the prerequisites, navigate to [Form Recognizer Studio General Documents](https://formrecognizer.appliedai.azure.com/studio/document).

+In the following example, we use the General Documents feature. The steps to use other pretrained features like [W2 tax form](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2), [Read](https://formrecognizer.appliedai.azure.com/studio/read), [Layout](https://formrecognizer.appliedai.azure.com/studio/layout), [Invoice](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice), [Receipt](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=receipt), [Business card](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard), and [ID documents](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=idDocument) models are similar.

+In addition to the Azure account and a Form Recognizer or Cognitive Services resource, you need:

+A **standard performance** [**Azure Blob Storage account**](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM). You create containers to store and organize your training documents within your storage account. If you don't know how to create an Azure storage account with a container, following these quickstarts:

+[CORS (Cross Origin Resource Sharing)](/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services) needs to be configured on your Azure storage account for it to be accessible from the Form Recognizer Studio. To configure CORS in the Azure portal, you need access to the CORS tab of your storage account.

+1. The **Upload blob** window appears.

+> [!IMPORTANT]

+> The **2023-02-28-preview** version is currently only available through the [**Form Recognizer 2023-02-28-preview REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2023-02-28-preview/operations/AnalyzeDocument).

+> * [**Composed classification models**](concept-custom-classifier.md)

+| **Training dataset size * Template** | 50 MB ⁴ | 50 MB (default value) |

+| **Max number of pages (Training) * Classifier** | 10,000 | 10,000 (default value) |

+| Adjustable | No | No |

+| **Training dataset size * Classifier** | 1GB | 1GB (default value) |

+| Adjustable | No | No |

+| **Compose Model limit** | 5 | 200 (default value) |

+*Example.* Your application is using Form Recognizer and your current workload is 10 TPS (transactions per second). The next second you increase the load to 40 TPS (that is four times more). The Service immediately starts scaling up to fulfill the new load, but likely it can't do it within a second, so some of the requests get Response Code 429.

+* A new window appears with auto-populated information about your Azure Subscription and Azure Resource

+* Under the *Details* tab, enter the following information in the *Description* field:

+ * Note the support request number in Azure portal notifications. You're contacted shortly for further processing

+If you find that you're being throttled on the number of POST requests for documents being submitted, consider adding a delay between the requests. If your workload requires a higher degree of concurrent processing, you then need to create a support request to increase your service limits on transactions per second.

+To learn more about each model, *see* concept pages.

+Form Recognizer service is updated on an ongoing basis. Bookmark this page to stay up to date with release notes, feature enhancements, and our newest documentation.

+## March 2023

+> [!IMPORTANT]

+> Document classification, Query fields, and Add-on capabilities are currently only available in the following regions:

+>

+> * West Europe

+> * West US2

+> * East US

+* **Document classification** is now a new capability within Form Recognizer starting with the ```2023-02-28-preview``` API. Try out the document classification capability in the [Studio](https://formrecognizer-dogfood.appliedai.azure.com/studio/) or the REST API.

+* **Query fields** added to the General Document model uses Open AI model to extract specific fields from documents. See the [general document](concept-general-document.md) model to learn more or try the feature in the [Studio](https://formrecognizer-dogfood.appliedai.azure.com/studio/). Query fields are currently only active for resources in the East US region.

+* **Additions to the Read and Layout APIs**

+ * **Barcodes** are now supported with the ```2023-02-28-preview``` API.

+ * **Fonts** are now recognized with the ```2023-02-28-preview``` API.

+ * **Formulas** are now recognized with the ```2023-02-28-preview``` API.

+* **Common name** normalizing key variation to a common name makes the General Document model more useful in processing forms with variations in key names. Learn more about the common name feature in the [General Document model](concept-general-document.md).

+* **Custom extraction model updates**

+ * Custom neural models now support added languages for training and analysis. Train neural models for Dutch, French, German, Italian and Spanish.

+ * Custom template models now have an improved signature detection capability.

+* **Service Updates**

+ * Support for high resolution documents

+* **Studio updates**

+ * In addition to support for all the new features like classification and query fields, the Studio now enables project sharing for custom model projects.

+* **Receipt model updates**

+ * Receipt model has added support for thermal receipts.

+ * Receipt model now has added language support for 18 languages and three language dialects (English, French, Portuguese).

+ * Receipt model now supports `TaxDetails` extraction.

+* **Layout model** now has improved table recognition.

+* **Read model** now has added improvement for single-digit character recognition.

+## February 2023

+* Select Form Recognizer containers for v3.0 are now available for use!

+* Currently **Read v3.0** and **Layout v3.0** containers are available.

+ For more information, _see_ [Install and run Form Recognizer containers](containers/form-recognizer-container-install-run.md?view=form-recog-3.0.0&preserve-view=true)

+* Prebuilt receipt model - added languages supported. The receipt model now supports these added languages and locales

+ * Japanese - Japan (ja-JP)

+ * French - Canada (fr-CA)

+ * Dutch - Netherlands (nl-NL)

+ * English - United Arab Emirates (en-AE)

+ * Portuguese - Brazil (pt-BR)

+* Prebuilt invoice model - added languages supported. The invoice model now supports these added languages and locales

+ * English - United States (en-US), Australia (en-AU), Canada (en-CA), Great Britain (en-GB), India (en-IN)

+ * Spanish - Spain (es-ES)

+ * French - France (fr-FR)

+ * Italian - Italy (it-IT)

+ * Portuguese - Portugal (pt-PT)

+ * Dutch - Netherlands (nl-NL)

+* Prebuilt invoice model - added fields recognized. The invoice model now recognizes these added fields

+ * Currency code

+ * Payment options

+ * Total discount

+ * Tax items (en-IN only)

+* Prebuilt ID model - added document types supported. The ID model now supports these added document types

+ * US Military ID

+* **[Prebuilt receipt model](concept-receipt.md#supported-languages-and-locales)ΓÇöadditional language support**:

+* Building custom neural models is now supported in the US Gov Virginia region.

+* Preview API versions ```2022-01-30-preview``` and ```2021-09-30-preview``` will be retired January 31 2023. Update to the ```2022-08-31``` API version to avoid any service disruptions.

+ * Form Recognizer documentation has been updated to present a versioned experience. Now, you can choose to view content targeting the v3.0 GA experience or the v2.1 GA experience. The v3.0 experience is the default.

+ * For a complete list of regions where training is supported see [custom neural models](concept-custom-neural.md).

+ * [**prebuilt-invoice**](concept-invoice.md). The TotalVAT and Line/VAT fields now resolves to the existing fields TotalTax and Line/Tax respectively.

+ * [**prebuilt-idDocument**](concept-id-document.md). Data extraction support for US state ID, social security, and green cards. Support for passport visa information.

+ * [**Read model now supports common Microsoft Office document types**](concept-read.md). Document types like Word (docx) and PowerPoint (ppt) are now supported with the Read API. See [Microsoft Office and HTML text extraction](concept-read.md#microsoft-office-and-html-text-extraction).

+ * [**General document**](concept-general-document.md) pre-trained model is now updated to support selection marks in addition to API text, tables, structure, key-value pairs, and named entities from forms and documents.

+* Form Recognizer containers v2.1 released in gated preview and are now supported by six feature containersΓÇö**Layout**, **Business Card**,**ID Document**, **Receipt**, **Invoice**, and **Custom**. To use them, you must submit an [online request](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xUNlpBU1lFSjJUMFhKNzVHUUVLN1NIOEZETiQlQCN0PWcu), and receive approval.

+* The updated Layout API table feature adds header recognition with column headers that can span multiple rows. Each table cell has an attribute that indicates whether it's part of a header or not. This update can be used to identify which rows make up the table header.

+* Expanded the set of document languages that can be provided to the **[StartRecognizeContent](/dotnet/api/azure.ai.formrecognizer.formrecognizerclient.startrecognizecontent?view=azure-dotnet-preview&preserve-view=true)** method.

+ The `ReadingOrder` property is an optional parameter that allows you to specify which reading order algorithmΓÇö`basic` or `natural`ΓÇöshould be applied to order the extraction of text elements. If not specified, the default value is `basic`.

+ * The `ReadingOrder` keyword argument is an optional parameter that allows you to specify which reading order algorithmΓÇö`basic` or `natural`ΓÇöshould be applied to order the extraction of text elements. If not specified, the default value is `basic`.

+* Added support for a **[ReadingOrder](/javascript/api/@azure/ai-form-recognizer/formreadingorder?view=azure-node-latest&preserve-view=true to the URL)** type to the content recognition methods. This option enables you to control the algorithm that the service uses to determine how recognized lines of text should be ordered. You can specify which reading order algorithmΓÇö`basic` or `natural`ΓÇöshould be applied to order the extraction of text elements. If not specified, the default value is `basic`.

+ The `readingOrder` keyword argument is an optional parameter that allows you to specify which reading order algorithmΓÇö`basic` or `natural`ΓÇöshould be applied to order the extraction of text elements. If not specified, the default value is `basic`.

+* **Supervised table labeling and training, empty-value labeling** - In addition to Form Recognizer's [state-of-the-art deep learning automatic table extraction capabilities](https://techcommunity.microsoft.com/t5/azure-ai/enhanced-table-extraction-from-documents-with-form-recognizer/ba-p/2058011), it now enables customers to label and train on tables. This new release includes the ability to label and train on line items/tables (dynamic and fixed) and train a custom model to extract key-value pairs and line items. Once a model is trained, the model extracts line items as part of the JSON output in the documentResults section.

+ * **New language supported: Japanese** - The following new languages are now supported: for `AnalyzeLayout` and `AnalyzeCustomForm`: Japanese (`ja`). [Language support](language-support.md)

+ * **Text line style indication (handwritten/other) (Latin languages only)** - Form Recognizer now outputs an `appearance` object classifying whether each text line is handwritten style or not, along with a confidence score. This feature is supported only for Latin languages.

+ * **New try-it-out feature in the Form Recognizer Sample and Labeling Tool** - Ability to try out prebuilt Invoice, Receipt, and Business Card models and the Layout API using the Form Recognizer Sample Labeling tool. See how your data is extracted without writing any code.

+* **Form Recognizer v2.1-preview.1 has been released and includes the following features:

+ * **New languages supported In addition to English**, the following [languages](language-support.md) are now supported: for `Layout` and `Train Custom Model`: English (`en`), Chinese (Simplified) (`zh-Hans`), Dutch (`nl`), French (`fr`), German (`de`), Italian (`it`), Portuguese (`pt`) and Spanish (`es`).

+ * **Checkbox / Selection Mark detection** ΓÇô Form Recognizer supports detection and extraction of selection marks such as check boxes and radio buttons. Selection Marks are extracted in `Layout` and you can now also label and train in `Train Custom Model` - _Train with Labels_ to extract key-value pairs for selection marks.

+ * **Model Compose** - allows multiple models to be composed and called with a single model ID. When you submit a document to be analyzed with a composed model ID, a classification step is first performed to route it to the correct custom model. Model Compose is available for `Train Custom Model` - _Train with labels_.

+ * The [Sample Labeling tool](https://github.com/microsoft/OCR-Form-Tools) has been updated to support the new v2.1 functionality. See this [quickstart](label-tool.md) for getting started with the tool.

+* **Value types for labeling** You can now specify the types of values you're labeling with the Form Recognizer Sample Labeling tool. The following value types and variations are currently supported:

+* **Table visualization** The Sample Labeling tool now displays tables that were recognized in the document. This feature lets you view recognized and extracted tables from the document prior to labeling and analyzing. This feature can be toggled on/off using the layers option.

+* The following image is an example of how tables are recognized and extracted:

+* TLS 1.2 is now enforced for all HTTP requests to this service. For more information, see [Azure Cognitive Services security](../../cognitive-services/security-features.md).

+ All of the APIs for training and using custom models have been renamed, and some synchronous methods are now asynchronous. The following are major changes:

+ * Key/value extraction is now initiated by the **/custom/models/{modelID}/analyze** API call. This call returns an operation ID, which you can pass into **custom/models/{modelID}/analyzeResults/{resultID}** to return the extraction results.

+ * Operation IDs for the Train operation are now found in the **Location** header of HTTP responses, not the **Operation-Location** header.

+ * The APIs for reading sales receipts have been renamed.

+ * Receipt data extraction is now initiated by the **/prebuilt/receipt/analyze** API call. This call returns an operation ID, which you can pass into **/prebuilt/receipt/analyzeResults/{resultID}** to return the extraction results.

+ * The JSON responses for all API calls have new formats. Some keys and values have been added, removed, or renamed. See the quickstarts for examples of the current JSON formats.

+The naming convention is not being followed. Ensure that your runbook name starts with a letter and can contain letters, numbers, underscores, and dashes. The naming convention requirements are now being enforced starting with the Az module version 1.9 through the portal and cmdlets.

+We recommend that you follow the runbook naming convention or revert to [1.8.0 version](https://www.powershellgallery.com/packages/Az.Automation/1.8.0) of the module where the naming convention isn't enforced.

+When deploying Arc resource bridge with AKS on Azure Stack HCI (AKS Hybrid), the resource bridge should share the same 'vswitchname' and `ipaddressprefix`, but require different IP addresses for `vippoolstart/end` and `k8snodeippoolstart/end`. Arc resource bridge should be given a unique 'vnetname' that is different from the one used for AKS Hybrid. For full instructions to deploy Arc resource bridge on AKS Hybrid, see [How to install Azure Arc Resource Bridge on Windows Server - AKS hybrid](/azure/aks/hybrid/deploy-arc-resource-bridge-windows-server).

+We strongly recommend that you deploy new caches in a [zone redundant](cache-high-availability.md) configuration. Zone redundancy ensures that Redis Enterprise nodes are spread among three availability zones, boosting redundancy from data center-level outages. Using zone redundancy increases availability. For more information, see [Service Level Agreements (SLA) for Online Services](https://azure.microsoft.com/support/legal/sla/cache/v1_1/).

+In the Enterprise and Enterprise Flash tiers of Azure Cache for Redis, we recommend prioritizing scaling up over scaling out. Prioritize scaling up because the Enterprise tiers are built on Redis Enterprise, which is able to utilize more CPU cores in larger VMs.

+- When using a VNet injected cache, you must change your VNet to cache dependencies such as CRLs/PKI, AKV, Azure Storage, Azure Monitor, and more.

+- You can't inject an Azure Cache for Redis instance into a Virtual Network. You can only select this option when you _create_ the cache.

+The example implementation below handles making these requests to your Azure Function. It uses the [axios](https://www.npmjs.com/package/axios) library to make HTTP requests. You can use other libraries or approaches to making an HTTP request from server code. This specific implementation is also provided for you as an export from the `@fluidframework/azure-client` package.

+> During development, you can use `InsecureTokenProvider` to generate and sign authentication tokens that the Azure Fluid Relay service will accept. However, as the name implies, this is insecure and should not be used in production environments. The Azure Fluid Relay resource creation process provides you with a secret key which can be used to sign secure requests. **To ensure that this secret doesn't get exposed, this should be replaced with another implementation of ITokenProvider that fetches the token from a secure, developer-provided backend service prior to releasing to production.**

+>

+> One secure approach is outlined in ["How to: Write a TokenProvider with an Azure Function"](../how-tos/azure-function-token-provider.md).

+For more information on snapshots, see [Debug snapshots on exceptions in .NET apps](../azure-monitor/app/snapshot-debugger.md) and [Troubleshoot problems enabling Application Insights Snapshot Debugger or viewing snapshots](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md).

+ - `<virtual-machine-region-name>`.handler.control.monitor.azure.com (example: westus.handler.control.monitor.azure.com)

+ :::image type="content" source="./media/action-groups/test-action-group.png" alt-text="Screenshot that shows the test action group page with the Test option.":::

+> - To find common schema samples for all sample types, see [Alert payload samples](./alerts-payload-samples.md).

+ :::image type="content" source="./media/action-groups/action-groups-secure-webhook.png" alt-text="Screenshot that shows the Secured Webhook dialog in the Azure portal with the Object ID box." border="true":::

+> You can also use the [common alert schema](./alerts-common-schema.md) for your webhook integrations. It provides the advantage of having a single extensible and unified alert payload across all the alert services in Azure Monitor. [Learn about the common alert schema](./alerts-common-schema.md)ΓÇï.

+| ID |Resource ID of the alert. |

+The common alert schema standardizes the consumption of Azure Monitor alert notifications. Historically, activity log, metric, and log alerts each had their own email templates and webhook schemas. The common alert schema provides one standardized schema for all alert notifications.

+The new schema enables a richer alert consumption experience in both the Azure portal and the Azure mobile app.

+For sample alerts that use the common schema, see [Sample alert payloads](alerts-payload-samples.md).

+| monitoringService | The monitoring service or solution that generated the alert. The monitoring service determines which fields are in the alert context. |

+## Alert context fields for metric alerts

+|Field |Description |

+|||

+|properties |(Optional.) A collection of customer-defined properties. |

+|conditionType |The type of condition selected for the alert rule:<br> - static threshold<br> - dynamic threshold<br> - webtest |

+|condition | |

+|windowSize |The time period analyzed by the alert rule.|

+|allOf |Indicates that all conditions defined in the alert rule must be met to trigger an alert.|

+|alertSensitivity |In an alert rule with a dynamic threshold, indicates how sensitive the rule is, or how much the value can deviate from the upper or lower threshold.|

+|failingPeriods |In an alert rule with a dynamic threshold, the number of evaluation periods that don't meet the alert threshold that will trigger an alert. For example, you can indicate that an alert is triggered when 3 out of the last five evaluation periods aren't within the alert thresholds. |

+|numberOfEvaluationPeriods|The total number of evaluations. |

+|minFailingPeriodsToAlert|The minimum number of evaluations that do no meet the alert rule conditions.|

+|ignoreDataBefore |(Optional.) In an alert rule with a dynamic threshold, the date from which the threshold is calculated. Use this value to indicate that the rule shouldn't calculate the dynamic threshold using data from before the specified date. |

+|metricName |The name of the metric monitored by the alert rule. |

+|metricNamespace |The namespace of the metric monitored by the alert rule. |

+|operator |The logical operator of the alert rule. |

+|threshold |The threshold defined in the alert rule. For an alert rule with a dynamic threshold, this value is the calculated threshold. |

+|timeAggregation |The aggregation type of the alert rule. |

+|dimensions |The metric dimension that triggered the alert. |

+|name |The dimension name. |

+|value |The dimension value. |

+|metricValue |The metric value at the time that it violated the threshold. |

+|webTestName |If the condition type is `webtest`, the name of the webtest. |

+|windowStartTime |The start time of the evaluation window in which the alert fired. |

+|windowEndTime |The end time of the evaluation window in which the alert fired. |

+### Sample metric alert with a static threshold when the monitoringService = `Platform`

+### Sample metric alert with a dynamic threshold when the monitoringService = `Platform`

+### Sample metric alert for availability tests when the monitoringService = `Platform`

+|Field |Description |

+|||

+|SearchQuery |The query defined in the alert rule. |

+|SearchIntervalStartTimeUtc |The start time of the evaluation window in which the alert fired in UTC. |

+|SearchIntervalEndTimeUtc |The end time of the evaluation window in which the alert fired in UTC. |

+|ResultCount |The number of records returned by the query. For metric measurement rules, the number or records that match the specific dimension combination. |

+|LinkToSearchResults |A link to the search results. |

+|LinkToFilteredSearchResultsUI |For metric measurement rules, the link to the search results after they've been filtered by the dimension combinations. |

+|LinkToSearchResultsAPI |A link to the query results using the Log Analytics API. |

+|LinkToFilteredSearchResultsAPI |For metric measurement rules, the link to the search results using the Log Analytics API after they've been filtered by the dimension combinations. |

+|SearchIntervalDurationMin |The total number of minutes in the search interval. |

+|SearchIntervalInMin |The total number of minutes in the search interval. |

+|Threshold |The threshold defined in the alert rule. |

+|Operator |The operator defined in the alert rule. |

+|ApplicationID |The Application Insights ID on which the alert was triggered. |

+|Dimensions |For metric measurement rules, the metric dimensions on which the alert was triggered. |

+|name |The dimension name. |

+|value |The dimension value. |

+|SearchResults |The complete search results. |

+|table |The table of results in the search results. |

+|name |The name of the table in the search results. |

+|columns |The columns in the table. |

+|name |The name of the column. |

+|type |The type of the column. |

+|rows |The rows in the table. |

+|DataSources |The data sources on which the alert was triggered. |

+|resourceID |The resource ID affected by the alert. |

+|tables |The draft response tables included in the query. |

+|IncludedSearchResults | Flag that indicates if the payload should contain the results. |

+|AlertType |The alert type:<br> - Metric Measurement<br> - Number Of Results |

+See [Azure activity log event schema](../essentials/activity-log-schema.md) for detailed information about the fields in activity log alerts.

+See [Azure Monitor managed service for Prometheus rule groups (preview)](../essentials/prometheus-rule-groups.md) for detailed information about the fields in Prometheus alerts.

+> It is recommended you use [common alert schema](../alerts/alerts-common-schema.md) for your webhook integrations. The common alert schema provides the advantage of having a single extensible and unified alert payload across all the alert services in Azure Monitor. For log alerts rules that have a custom JSON payload defined, enabling the common alert schema reverts the payload schema to the one described [here](../alerts/alerts-common-schema.md#alert-context-fields-for-log-alerts). This means that if you want to have a custom JSON payload defined, the webhook can't use the common alert schema. Alerts with the common schema enabled have an upper size limit of 256 KB per alert, bigger alert will not include search results. When the search results aren't included, you should use the `LinkToFilteredSearchResultsAPI` or `LinkToSearchResultsAPI` to access query results via the Log Analytics API.

+> You can also use the [common alert schema](./alerts-common-schema.md), which provides the advantage of having a single extensible and unified alert payload across all the alert services in Azure Monitor, for your webhook integrations.ΓÇï

+ Title: Samples of Azure Monitor alert payloads

+description: See examples of payloads for Azure monitor alerts.

+# Sample alert payloads

+The common alert schema standardizes the consumption experience for alert notifications in Azure. Historically, activity log, metric, and log alerts each had their own email templates and webhook schemas. The common alert schema provides one standardized schema for all alert notifications.

+A standardized schema can help you minimize the number of integrations, which simplifies the process of managing and maintaining your integrations.

+The common schema includes information about the affected resource and the cause of the alert in these sections:

+- **Essentials**: Standardized fields, used by all alert types that describe the resource affected by the alert and common alert metadata, such as severity or description.

+ If you want to route alert instances to specific teams based on criteria such as a resource group, you can use the fields in the **Essentials** section to provide routing logic for all alert types. The teams that receive the alert notification can then use the context fields for their investigation.

+- **Alert context**: Fields that vary depending on the type of the alert. The alert context fields describe the cause of the alert. For example, a metric alert would have fields like the metric name and metric value in the alert context. An activity log alert would have information about the event that generated the alert.

+## Sample alert payload

+```json

+{

+ "schemaId": "azureMonitorCommonAlertSchema",

+ "data": {

+ "essentials": {

+ "alertId": "/subscriptions/<subscription ID>/providers/Microsoft.AlertsManagement/alerts/b9569717-bc32-442f-add5-83a997729330",

+ "alertRule": "WCUS-R2-Gen2",

+ "severity": "Sev3",

+ "signalType": "Metric",

+ "monitorCondition": "Resolved",

+ "monitoringService": "Platform",

+ "alertTargetIDs": [

+ "/subscriptions/<subscription ID>/resourcegroups/pipelinealertrg/providers/microsoft.compute/virtualmachines/wcus-r2-gen2"

+ ],

+ "configurationItems": [

+ "wcus-r2-gen2"

+ ],

+ "originAlertId": "3f2d4487-b0fc-4125-8bd5-7ad17384221e_PipeLineAlertRG_microsoft.insights_metricAlerts_WCUS-R2-Gen2_-117781227",

+ "firedDateTime": "2019-03-22T13:58:24.3713213Z",

+ "resolvedDateTime": "2019-03-22T14:03:16.2246313Z",

+ "description": "",

+ "essentialsVersion": "1.0",

+ "alertContextVersion": "1.0"

+ },

+ "alertContext": {

+ "properties": null,

+ "conditionType": "SingleResourceMultipleMetricCriteria",

+ "condition": {

+ "windowSize": "PT5M",

+ "allOf": [

+ {

+ "metricName": "Percentage CPU",

+ "metricNamespace": "Microsoft.Compute/virtualMachines",

+ "operator": "GreaterThan",

+ "threshold": "25",

+ "timeAggregation": "Average",

+ "dimensions": [

+ {

+ "name": "ResourceId",

+ "value": "3efad9dc-3d50-4eac-9c87-8b3fd6f97e4e"

+ }

+ ],

+ "metricValue": 7.727

+ }

+ ]

+ }

+ }

+ }

+}

+```

+## Sample metric alerts

+The following are sample metric alert payloads.

+### Metric alert with a static threshold and the monitoringService = `Platform`

+```json

+{

+ "alertContext": {

+ "properties": null,

+ "conditionType": "SingleResourceMultipleMetricCriteria",

+ "condition": {

+ "windowSize": "PT5M",

+ "allOf": [

+ {

+ "metricName": "Percentage CPU",

+ "metricNamespace": "Microsoft.Compute/virtualMachines",

+ "operator": "GreaterThan",

+ "threshold": "25",

+ "timeAggregation": "Average",

+ "dimensions": [

+ {

+ "name": "ResourceId",

+ "value": "3efad9dc-3d50-4eac-9c87-8b3fd6f97e4e"

+ }

+ ],

+ "metricValue": 31.1105

+ }

+ ],

+ "windowStartTime": "2019-03-22T13:40:03.064Z",

+ "windowEndTime": "2019-03-22T13:45:03.064Z"

+ }

+ }

+}

+```

+### Metric alert with a dynamic threshold and the monitoringService = Platform

+```json

+{

+ "alertContext": {

+ "properties": null,

+ "conditionType": "DynamicThresholdCriteria",

+ "condition": {

+ "windowSize": "PT5M",

+ "allOf": [

+ {

+ "alertSensitivity": "High",

+ "failingPeriods": {

+ "numberOfEvaluationPeriods": 1,

+ "minFailingPeriodsToAlert": 1

+ },

+ "ignoreDataBefore": null,

+ "metricName": "Egress",

+ "metricNamespace": "microsoft.storage/storageaccounts",

+ "operator": "GreaterThan",

+ "threshold": "47658",

+ "timeAggregation": "Total",

+ "dimensions": [],

+ "metricValue": 50101

+ }

+ ],

+ "windowStartTime": "2021-07-20T05:07:26.363Z",

+ "windowEndTime": "2021-07-20T05:12:26.363Z"

+ }

+ }

+}

+```

+### Metric alert for availability tests and the monitoringService = Platform

+```json

+{

+ "alertContext": {

+ "properties": null,

+ "conditionType": "WebtestLocationAvailabilityCriteria",

+ "condition": {

+ "windowSize": "PT5M",

+ "allOf": [

+ {

+ "metricName": "Failed Location",

+ "metricNamespace": null,

+ "operator": "GreaterThan",

+ "threshold": "2",

+ "timeAggregation": "Sum",

+ "dimensions": [],

+ "metricValue": 5,

+ "webTestName": "myAvailabilityTest-myApplication"

+ }

+ ],

+ "windowStartTime": "2019-03-22T13:40:03.064Z",

+ "windowEndTime": "2019-03-22T13:45:03.064Z"

+ }

+ }

+}

+```

+## Sample log alerts

+> [!NOTE]

+> When you enable the common schema, the fields in the payload are reset to the common schema fields. Therefore, log alerts have these limitations regarding the common schema:

+> - The common schema is not supported for log alerts using webhooks with a custom email subject and/or JSON payload, since the common schema overwrites the custom configurations.

+> - Alerts using the common schema have an upper size limit of 256 KB per alert. If the log alerts payload includes search results that cause the alert to exceed the maximum size, the search results aren't embedded in the log alerts payload. You can check if the payload includes the search results with the `IncludedSearchResults` flag. Use `LinkToFilteredSearchResultsAPI` or `LinkToSearchResultsAPI` to access query results with the [Log Analytics API](/rest/api/loganalytics/dataaccess/query/get) if the search results are not included.

+### Log alert with monitoringService = Platform

+```json

+{

+ "alertContext": {

+ "SearchQuery": "Perf | where ObjectName == \"Processor\" and CounterName == \"% Processor Time\" | summarize AggregatedValue = avg(CounterValue) by bin(TimeGenerated, 5m), Computer",

+ "SearchIntervalStartTimeUtc": "3/22/2019 1:36:31 PM",

+ "SearchIntervalEndtimeUtc": "3/22/2019 1:51:31 PM",

+ "ResultCount": 2,

+ "LinkToSearchResults": "https://portal.azure.com/#Analyticsblade/search/index?_timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",

+ "LinkToFilteredSearchResultsUI": "https://portal.azure.com/#Analyticsblade/search/index?_timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",

+ "LinkToSearchResultsAPI": "https://api.loganalytics.io/v1/workspaces/workspaceID/query?query=Heartbeat&timespan=2020-05-07T18%3a11%3a51.0000000Z%2f2020-05-07T18%3a16%3a51.0000000Z",

+ "LinkToFilteredSearchResultsAPI": "https://api.loganalytics.io/v1/workspaces/workspaceID/query?query=Heartbeat&timespan=2020-05-07T18%3a11%3a51.0000000Z%2f2020-05-07T18%3a16%3a51.0000000Z",

+ "SeverityDescription": "Warning",

+ "WorkspaceId": "12345a-1234b-123c-123d-12345678e",

+ "SearchIntervalDurationMin": "15",

+ "AffectedConfigurationItems": [

+ "INC-Gen2Alert"

+ ],

+ "SearchIntervalInMinutes": "15",

+ "Threshold": 10000,

+ "Operator": "Less Than",

+ "Dimensions": [

+ {

+ "name": "Computer",

+ "value": "INC-Gen2Alert"

+ }

+ ],

+ "SearchResults": {

+ "tables": [

+ {

+ "name": "PrimaryResult",

+ "columns": [

+ {

+ "name": "$table",

+ "type": "string"

+ },

+ {

+ "name": "Computer",

+ "type": "string"

+ },

+ {

+ "name": "TimeGenerated",

+ "type": "datetime"

+ }

+ ],

+ "rows": [

+ [

+ "Fabrikam",

+ "33446677a",

+ "2018-02-02T15:03:12.18Z"

+ ],

+ [

+ "Contoso",

+ "33445566b",

+ "2018-02-02T15:16:53.932Z"

+ ]

+ ]

+ }

+ ],

+ "dataSources": [

+ {

+ "resourceId": "/subscriptions/a5ea55e2-7482-49ba-90b3-60e7496dd873/resourcegroups/test/providers/microsoft.operationalinsights/workspaces/test",

+ "tables": [

+ "Heartbeat"

+ ]

+ }

+ ]

+ },

+ "IncludedSearchResults": "True",

+ "AlertType": "Metric measurement"

+ }

+}

+```

+### Log alert with monitoringService = Application Insights

+```json

+{

+ "alertContext": {

+ "SearchQuery": "requests | where resultCode == \"500\" | summarize AggregatedValue = Count by bin(Timestamp, 5m), IP",

+ "SearchIntervalStartTimeUtc": "3/22/2019 1:36:33 PM",

+ "SearchIntervalEndtimeUtc": "3/22/2019 1:51:33 PM",

+ "ResultCount": 2,

+ "LinkToSearchResults": "https://portal.azure.com/AnalyticsBlade/subscriptions/12345a-1234b-123c-123d-12345678e/?query=search+*+&timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",

+ "LinkToFilteredSearchResultsUI": "https://portal.azure.com/AnalyticsBlade/subscriptions/12345a-1234b-123c-123d-12345678e/?query=search+*+&timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",

+ "LinkToSearchResultsAPI": "https://api.applicationinsights.io/v1/apps/0MyAppId0/metrics/requests/count",

+ "LinkToFilteredSearchResultsAPI": "https://api.applicationinsights.io/v1/apps/0MyAppId0/metrics/requests/count",

+ "SearchIntervalDurationMin": "15",

+ "SearchIntervalInMinutes": "15",

+ "Threshold": 10000.0,

+ "Operator": "Less Than",

+ "ApplicationId": "8e20151d-75b2-4d66-b965-153fb69d65a6",

+ "Dimensions": [

+ {

+ "name": "IP",

+ "value": "1.1.1.1"

+ }

+ ],

+ "SearchResults": {

+ "tables": [

+ {

+ "name": "PrimaryResult",

+ "columns": [

+ {

+ "name": "$table",

+ "type": "string"

+ },

+ {

+ "name": "Id",

+ "type": "string"

+ },

+ {

+ "name": "Timestamp",

+ "type": "datetime"

+ }

+ ],

+ "rows": [

+ [

+ "Fabrikam",

+ "33446677a",

+ "2018-02-02T15:03:12.18Z"

+ ],

+ [

+ "Contoso",

+ "33445566b",

+ "2018-02-02T15:16:53.932Z"

+ ]

+ ]

+ }

+ ],

+ "dataSources": [

+ {

+ "resourceId": "/subscriptions/a5ea27e2-7482-49ba-90b3-52e7496dd873/resourcegroups/test/providers/microsoft.operationalinsights/workspaces/test",

+ "tables": [

+ "Heartbeat"

+ ]

+ }

+ ]

+ },

+ "IncludedSearchResults": "True",

+ "AlertType": "Metric measurement"

+ }

+}

+```

+### Log alert with monitoringService = Log Alerts V2

+> [!NOTE]

+> Log alert rules from API version 2020-05-01 use this payload type, which only supports common schema. Search results aren't embedded in the log alerts payload when you use this version. Use [dimensions](./alerts-unified-log.md#split-by-alert-dimensions) to provide context to fired alerts. You can also use `LinkToFilteredSearchResultsAPI` or `LinkToSearchResultsAPI` to access query results with the [Log Analytics API](/rest/api/loganalytics/dataaccess/query/get). If you must embed the results, use a logic app with the provided links to generate a custom payload.

+```json

+{

+ "alertContext": {

+ "properties": {

+ "name1": "value1",

+ "name2": "value2"

+ },

+ "conditionType": "LogQueryCriteria",

+ "condition": {

+ "windowSize": "PT10M",

+ "allOf": [

+ {

+ "searchQuery": "Heartbeat",

+ "metricMeasureColumn": "CounterValue",

+ "targetResourceTypes": "['Microsoft.Compute/virtualMachines']",

+ "operator": "LowerThan",

+ "threshold": "1",

+ "timeAggregation": "Count",

+ "dimensions": [

+ {

+ "name": "Computer",

+ "value": "TestComputer"

+ }

+ ],

+ "metricValue": 0.0,

+ "failingPeriods": {

+ "numberOfEvaluationPeriods": 1,

+ "minFailingPeriodsToAlert": 1

+ },

+ "linkToSearchResultsUI": "https://portal.azure.com#@12345a-1234b-123c-123d-12345678e/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%212345a-1234b-123c-123d-12345678e%2FresourceGroups%2FContoso%2Fproviders%2FMicrosoft.Compute%2FvirtualMachines%2FContoso%22%7D%5D%7D/q/eJzzSE0sKklKTSypUSjPSC1KVQjJzE11T81LLUosSU1RSEotKU9NzdNIAfJKgDIaRgZGBroG5roGliGGxlYmJlbGJnoGEKCpp4dDmSmKMk0A/prettify/1/timespan/2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z",

+ "linkToFilteredSearchResultsUI": "https://portal.azure.com#@12345a-1234b-123c-123d-12345678e/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%212345a-1234b-123c-123d-12345678e%2FresourceGroups%2FContoso%2Fproviders%2FMicrosoft.Compute%2FvirtualMachines%2FContoso%22%7D%5D%7D/q/eJzzSE0sKklKTSypUSjPSC1KVQjJzE11T81LLUosSU1RSEotKU9NzdNIAfJKgDIaRgZGBroG5roGliGGxlYmJlbGJnoGEKCpp4dDmSmKMk0A/prettify/1/timespan/2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z",

+ "linkToSearchResultsAPI": "https://api.loganalytics.io/v1/subscriptions/12345a-1234b-123c-123d-12345678e/resourceGroups/Contoso/providers/Microsoft.Compute/virtualMachines/Contoso/query?query=Heartbeat%7C%20where%20TimeGenerated%20between%28datetime%282020-07-09T13%3A44%3A34.0000000%29..datetime%282020-07-09T13%3A54%3A34.0000000%29%29&timespan=2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z",

+ "linkToFilteredSearchResultsAPI": "https://api.loganalytics.io/v1/subscriptions/12345a-1234b-123c-123d-12345678e/resourceGroups/Contoso/providers/Microsoft.Compute/virtualMachines/Contoso/query?query=Heartbeat%7C%20where%20TimeGenerated%20between%28datetime%282020-07-09T13%3A44%3A34.0000000%29..datetime%282020-07-09T13%3A54%3A34.0000000%29%29&timespan=2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z"

+ }

+ ],

+ "windowStartTime": "2020-07-07T13:54:34Z",

+ "windowEndTime": "2020-07-09T13:54:34Z"

+ }

+ }

+}

+```

+## Sample activity log alerts

+### Activity log alert with monitoringService = `Activity Log - Administrative`

+```json

+{

+ "alertContext": {

+ "authorization": {

+ "action": "Microsoft.Compute/virtualMachines/restart/action",

+ "scope": "/subscriptions/<subscription ID>/resourceGroups/PipeLineAlertRG/providers/Microsoft.Compute/virtualMachines/WCUS-R2-ActLog"

+ },

+ "channels": "Operation",

+ "claims": "{\"aud\":\"https://management.core.windows.net/\",\"iss\":\"https://sts.windows.net/12345a-1234b-123c-123d-12345678e/\",\"iat\":\"1553260826\",\"nbf\":\"1553260826\",\"exp\":\"1553264726\",\"aio\":\"42JgYNjdt+rr+3j/dx68v018XhuFAwA=\",\"appid\":\"e9a02282-074f-45cf-93b0-50568e0e7e50\",\"appidacr\":\"2\",\"http://schemas.microsoft.com/identity/claims/identityprovider\":\"https://sts.windows.net/12345a-1234b-123c-123d-12345678e/\",\"http://schemas.microsoft.com/identity/claims/objectidentifier\":\"9778283b-b94c-4ac6-8a41-d5b493d03aa3\",\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier\":\"9778283b-b94c-4ac6-8a41-d5b493d03aa3\",\"http://schemas.microsoft.com/identity/claims/tenantid\":\"12345a-1234b-123c-123d-12345678e\",\"uti\":\"v5wYC9t9ekuA2rkZSVZbAA\",\"ver\":\"1.0\"}",

+ "caller": "9778283b-b94c-4ac6-8a41-d5b493d03aa3",

+ "correlationId": "8ee9c32a-92a1-4a8f-989c-b0ba09292a91",

+ "eventSource": "Administrative",

+ "eventTimestamp": "2019-03-22T13:56:31.2917159+00:00",

+ "eventDataId": "161fda7e-1cb4-4bc5-9c90-857c55a8f57b",

+ "level": "Informational",

+ "operationName": "Microsoft.Compute/virtualMachines/restart/action",

+ "operationId": "310db69b-690f-436b-b740-6103ab6b0cba",

+ "status": "Succeeded",

+ "subStatus": "",

+ "submissionTimestamp": "2019-03-22T13:56:54.067593+00:00"

+ }

+}

+```

+### Activity log alert with monitoringService = `Activity Log - Policy`

+```json

+{

+ "alertContext": {

+ "authorization": {

+ "action": "Microsoft.Resources/checkPolicyCompliance/read",

+ "scope": "/subscriptions/<GUID>"

+ },

+ "channels": "Operation",

+ "claims": "{\"aud\":\"https://management.azure.com/\",\"iss\":\"https://sts.windows.net/<GUID>/\",\"iat\":\"1566711059\",\"nbf\":\"1566711059\",\"exp\":\"1566740159\",\"aio\":\"42FgYOhynHNw0scy3T/bL71+xLyqEwA=\",\"appid\":\"<GUID>\",\"appidacr\":\"2\",\"http://schemas.microsoft.com/identity/claims/identityprovider\":\"https://sts.windows.net/<GUID>/\",\"http://schemas.microsoft.com/identity/claims/objectidentifier\":\"<GUID>\",\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier\":\"<GUID>\",\"http://schemas.microsoft.com/identity/claims/tenantid\":\"<GUID>\",\"uti\":\"Miy1GzoAG0Scu_l3m1aIAA\",\"ver\":\"1.0\"}",

+ "caller": "<GUID>",

+ "correlationId": "<GUID>",

+ "eventSource": "Policy",

+ "eventTimestamp": "2019-08-25T11:11:34.2269098+00:00",

+ "eventDataId": "<GUID>",

+ "level": "Warning",

+ "operationName": "Microsoft.Authorization/policies/audit/action",

+ "operationId": "<GUID>",

+ "properties": {

+ "isComplianceCheck": "True",

+ "resourceLocation": "eastus2",

+ "ancestors": "<GUID>",

+ "policies": "[{\"policyDefinitionId\":\"/providers/Microsoft.Authorization/policyDefinitions/<GUID>/\",\"policySetDefinitionId\":\"/providers/Microsoft.Authorization/policySetDefinitions/<GUID>/\",\"policyDefinitionReferenceId\":\"vulnerabilityAssessmentMonitoring\",\"policySetDefinitionName\":\"<GUID>\",\"policyDefinitionName\":\"<GUID>\",\"policyDefinitionEffect\":\"AuditIfNotExists\",\"policyAssignmentId\":\"/subscriptions/<GUID>/providers/Microsoft.Authorization/policyAssignments/SecurityCenterBuiltIn/\",\"policyAssignmentName\":\"SecurityCenterBuiltIn\",\"policyAssignmentScope\":\"/subscriptions/<GUID>\",\"policyAssignmentSku\":{\"name\":\"A1\",\"tier\":\"Standard\"},\"policyAssignmentParameters\":{}}]"

+ },

+ "status": "Succeeded",

+ "subStatus": "",

+ "submissionTimestamp": "2019-08-25T11:12:46.1557298+00:00"

+ }

+}

+```

+### Activity log alert with monitoringService = `Activity Log - Autoscale`

+```json

+{

+ "alertContext": {

+ "channels": "Admin, Operation",

+ "claims": "{\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/spn\":\"Microsoft.Insights/autoscaleSettings\"}",

+ "caller": "Microsoft.Insights/autoscaleSettings",

+ "correlationId": "<GUID>",

+ "eventSource": "Autoscale",

+ "eventTimestamp": "2019-08-21T16:17:47.1551167+00:00",

+ "eventDataId": "<GUID>",

+ "level": "Informational",

+ "operationName": "Microsoft.Insights/AutoscaleSettings/Scaleup/Action",

+ "operationId": "<GUID>",

+ "properties": {

+ "description": "The autoscale engine attempting to scale resource '/subscriptions/d<GUID>/resourceGroups/testRG/providers/Microsoft.Compute/virtualMachineScaleSets/testVMSS' from 9 instances count to 10 instances count.",

+ "resourceName": "/subscriptions/<GUID>/resourceGroups/voiceassistancedemo/providers/Microsoft.Compute/virtualMachineScaleSets/alexademo",

+ "oldInstancesCount": "9",

+ "newInstancesCount": "10",

+ "activeAutoscaleProfile": "{\r\n \"Name\": \"Auto created scale condition\",\r\n \"Capacity\": {\r\n \"Minimum\": \"1\",\r\n \"Maximum\": \"10\",\r\n \"Default\": \"1\"\r\n },\r\n \"Rules\": [\r\n {\r\n \"MetricTrigger\": {\r\n \"Name\": \"Percentage CPU\",\r\n \"Namespace\": \"microsoft.compute/virtualmachinescalesets\",\r\n \"Resource\": \"/subscriptions/<GUID>/resourceGroups/testRG/providers/Microsoft.Compute/virtualMachineScaleSets/testVMSS\",\r\n \"ResourceLocation\": \"eastus\",\r\n \"TimeGrain\": \"PT1M\",\r\n \"Statistic\": \"Average\",\r\n \"TimeWindow\": \"PT5M\",\r\n \"TimeAggregation\": \"Average\",\r\n \"Operator\": \"GreaterThan\",\r\n \"Threshold\": 0.0,\r\n \"Source\": \"/subscriptions/<GUID>/resourceGroups/testRG/providers/Microsoft.Compute/virtualMachineScaleSets/testVMSS\",\r\n \"MetricType\": \"MDM\",\r\n \"Dimensions\": [],\r\n \"DividePerInstance\": false\r\n },\r\n \"ScaleAction\": {\r\n \"Direction\": \"Increase\",\r\n \"Type\": \"ChangeCount\",\r\n \"Value\": \"1\",\r\n \"Cooldown\": \"PT1M\"\r\n }\r\n }\r\n ]\r\n}",

+ "lastScaleActionTime": "Wed, 21 Aug 2019 16:17:47 GMT"

+ },

+ "status": "Succeeded",

+ "submissionTimestamp": "2019-08-21T16:17:47.2410185+00:00"

+ }

+}

+```

+### Activity log alert with monitoringService = `Activity Log - Security`

+```json

+{

+ "alertContext": {

+ "channels": "Operation",

+ "correlationId": "<GUID>",

+ "eventSource": "Security",

+ "eventTimestamp": "2019-08-26T08:34:14+00:00",

+ "eventDataId": "<GUID>",

+ "level": "Informational",

+ "operationName": "Microsoft.Security/locations/alerts/activate/action",

+ "operationId": "<GUID>",

+ "properties": {

+ "threatStatus": "Quarantined",

+ "category": "Virus",

+ "threatID": "2147519003",

+ "filePath": "C:\\AlertGeneration\\test.eicar",

+ "protectionType": "Windows Defender",

+ "actionTaken": "Blocked",

+ "resourceType": "Virtual Machine",

+ "severity": "Low",

+ "compromisedEntity": "testVM",

+ "remediationSteps": "[\"No user action is necessary\"]",

+ "attackedResourceType": "Virtual Machine"

+ },

+ "status": "Active",

+ "submissionTimestamp": "2019-08-26T09:28:58.3019107+00:00"

+ }

+}

+```

+### Activity log alert with `monitoringService = ServiceHealth`

+```json

+{

+ "alertContext": {

+ "authorization": null,

+ "channels": 1,

+ "claims": null,

+ "caller": null,

+ "correlationId": "f3cf2430-1ee3-4158-8e35-7a1d615acfc7",

+ "eventSource": 2,

+ "eventTimestamp": "2019-06-24T11:31:19.0312699+00:00",

+ "httpRequest": null,

+ "eventDataId": "<GUID>",

+ "level": 3,

+ "operationName": "Microsoft.ServiceHealth/maintenance/action",

+ "operationId": "<GUID>",

+ "properties": {

+ "title": "Azure Synapse Analytics Scheduled Maintenance Pending",

+ "service": "Azure Synapse Analytics",

+ "region": "East US",

+ "communication": "<MESSAGE>",

+ "incidentType": "Maintenance",

+ "trackingId": "<GUID>",

+ "impactStartTime": "2019-06-26T04:00:00Z",

+ "impactMitigationTime": "2019-06-26T12:00:00Z",

+ "impactedServices": "[{\"ImpactedRegions\":[{\"RegionName\":\"East US\"}],\"ServiceName\":\"Azure Synapse Analytics\"}]",

+ "impactedServicesTableRows": "<tr>\r\n<td align='center' style='padding: 5px 10px; border-right:1px solid black; border-bottom:1px solid black'>Azure Synapse Analytics</td>\r\n<td align='center' style='padding: 5px 10px; border-bottom:1px solid black'>East US<br></td>\r\n</tr>\r\n",

+ "defaultLanguageTitle": "Azure Synapse Analytics Scheduled Maintenance Pending",

+ "defaultLanguageContent": "<MESSAGE>",

+ "stage": "Planned",

+ "communicationId": "<GUID>",

+ "maintenanceId": "<GUID>",

+ "isHIR": "false",

+ "version": "0.1.1"

+ },

+ "status": "Active",

+ "subStatus": null,

+ "submissionTimestamp": "2019-06-24T11:31:31.7147357+00:00",

+ "ResourceType": null

+ }

+}

+```

+### Activity log alert with monitoringService = `ResourceHealth`

+```json

+{

+ "alertContext": {

+ "channels": "Admin, Operation",

+ "correlationId": "<GUID>",

+ "eventSource": "ResourceHealth",

+ "eventTimestamp": "2019-06-24T15:42:54.074+00:00",

+ "eventDataId": "<GUID>",

+ "level": "Informational",

+ "operationName": "Microsoft.Resourcehealth/healthevent/Activated/action",

+ "operationId": "<GUID>",

+ "properties": {

+ "title": "This virtual machine is stopping and deallocating as requested by an authorized user or process",

+ "details": null,

+ "currentHealthStatus": "Unavailable",

+ "previousHealthStatus": "Available",

+ "type": "Downtime",

+ "cause": "UserInitiated"

+ },

+ "status": "Active",

+ "submissionTimestamp": "2019-06-24T15:45:20.4488186+00:00"

+ }

+}

+```

+## Sample Prometheus alert

+```json

+{

+ "alertContext": {

+ "interval": "PT1M",

+ "expression": "sql_up > 0",

+ "expressionValue": "0",

+ "for": "PT2M",

+ "labels": {

+ "Environment": "Prod",

+ "cluster": "myCluster1"

+ },

+ "annotations": {

+ "summary": "alert on SQL availability"

+ },

+ "ruleGroup": "/subscriptions/<subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.AlertsManagement/prometheusRuleGroups/myRuleGroup"

+ }

+}

+```

+## Sample payloads for test actions

+### Sample test action alert

+```json

+{

+ "schemaId": "azureMonitorCommonAlertSchema",

+ "data": {

+ "essentials": {

+ "alertId": "/subscriptions/<subscription ID>/providers/Microsoft.AlertsManagement/alerts/b9569717-bc32-442f-add5-83a997729330",

+ "alertRule": "WCUS-R2-Gen2",

+ "severity": "Sev3",

+ "signalType": "Metric",

+ "monitorCondition": "Resolved",

+ "monitoringService": "Platform",

+ "alertTargetIDs": [

+ "/subscriptions/<subscription ID>/resourcegroups/pipelinealertrg/providers/microsoft.compute/virtualmachines/wcus-r2-gen2"

+ ],

+ "configurationItems": [

+ "wcus-r2-gen2"

+ ],

+ "originAlertId": "3f2d4487-b0fc-4125-8bd5-7ad17384221e_PipeLineAlertRG_microsoft.insights_metricAlerts_WCUS-R2-Gen2_-117781227",

+ "firedDateTime": "2019-03-22T13:58:24.3713213Z",

+ "resolvedDateTime": "2019-03-22T14:03:16.2246313Z",

+ "description": "",

+ "essentialsVersion": "1.0",

+ "alertContextVersion": "1.0"

+ },

+ "alertContext": {

+ "properties": null,

+ "conditionType": "SingleResourceMultipleMetricCriteria",

+ "condition": {

+ "windowSize": "PT5M",

+ "allOf": [

+ {

+ "metricName": "Percentage CPU",

+ "metricNamespace": "Microsoft.Compute/virtualMachines",

+ "operator": "GreaterThan",

+ "threshold": "25",

+ "timeAggregation": "Average",

+ "dimensions": [

+ {

+ "name": "ResourceId",

+ "value": "3efad9dc-3d50-4eac-9c87-8b3fd6f97e4e"

+ }

+ ],

+ "metricValue": 7.727

+ }

+ ]

+ }

+ }

+ }

+}

+```

+### Sample test action metric alerts

+#### Test action metric alert with a static threshold and the monitoringService = `Platform`

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"test-metricAlertRule",

+ "severity":"Sev3",

+ "signalType":"Metric",

+ "monitorCondition":"Fired",

+ "monitoringService":"Platform",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/Microsoft.Storage/storageAccounts/test-storageAccount"

+ ],

+ "configurationItems":[

+ "test-storageAccount"

+ ],

+ "originAlertId":"11111111-1111-1111-1111-111111111111_test-RG_microsoft.insights_metricAlerts_test-metricAlertRule_1234567890",

+ "firedDateTime":"2021-11-15T09:35:24.3468506Z",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.0"

+ },

+ "alertContext":{

+ "properties":{

+ "customKey1":"value1",

+ "customKey2":"value2"

+ },

+ "conditionType":"DynamicThresholdCriteria",

+ "condition":{

+ "windowSize":"PT15M",

+ "allOf":[

+ {

+ "alertSensitivity":"Low",

+ "failingPeriods":{

+ "numberOfEvaluationPeriods":3,

+ "minFailingPeriodsToAlert":3

+ },

+ "ignoreDataBefore":null,

+ "metricName":"Transactions",

+ "metricNamespace":"Microsoft.Storage/storageAccounts",

+ "operator":"GreaterThan",

+ "threshold":"0.3",

+ "timeAggregation":"Average",

+ "dimensions":[

+

+ ],

+ "metricValue":78.09,

+ "webTestName":null

+ }

+ ],

+ "windowStartTime":"2021-12-15T01:04:11.719Z",

+ "windowEndTime":"2021-12-15T01:19:11.719Z"

+ }

+ },

+ "customProperties":{

+ "customKey1":"value1",

+ "customKey2":"value2"

+ }

+ }

+}

+```

+#### Test action metric alert with dynamic threshold and monitoringService = `Platform`

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"test-metricAlertRule",

+ "severity":"Sev3",

+ "signalType":"Metric",

+ "monitorCondition":"Fired",

+ "monitoringService":"Platform",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/Microsoft.Storage/storageAccounts/test-storageAccount"

+ ],

+ "configurationItems":[

+ "test-storageAccount"

+ ],

+ "originAlertId":"11111111-1111-1111-1111-111111111111_test-RG_microsoft.insights_metricAlerts_test-metricAlertRule_1234567890",

+ "firedDateTime":"2021-11-15T09:35:24.3468506Z",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.0"

+ },

+ "alertContext":{

+ "properties":{

+ "customKey1":"value1",

+ "customKey2":"value2"

+ },

+ "conditionType":"DynamicThresholdCriteria",

+ "condition":{

+ "windowSize":"PT15M",

+ "allOf":[

+ {

+ "alertSensitivity":"Low",

+ "failingPeriods":{

+ "numberOfEvaluationPeriods":3,

+ "minFailingPeriodsToAlert":3

+ },

+ "ignoreDataBefore":null,

+ "metricName":"Transactions",

+ "metricNamespace":"Microsoft.Storage/storageAccounts",

+ "operator":"GreaterThan",

+ "threshold":"0.3",

+ "timeAggregation":"Average",

+ "dimensions":[

+

+ ],

+ "metricValue":78.09,

+ "webTestName":null

+ }

+ ],

+ "windowStartTime":"2021-12-15T01:04:11.719Z",

+ "windowEndTime":"2021-12-15T01:19:11.719Z"

+ }

+ },

+ "customProperties":{

+ "customKey1":"value1",

+ "customKey2":"value2"

+ }

+ }

+}

+```

+### Sample test action log alerts

+#### Test action log alert V1 ΓÇô Metric

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"test-logAlertRule-v1-metricMeasurement",

+ "severity":"Sev3",

+ "signalType":"Log",

+ "monitorCondition":"Fired",

+ "monitoringService":"Log Analytics",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.operationalinsights/workspaces/test-logAnalyticsWorkspace"

+ ],

+ "configurationItems":[

+

+ ],

+ "originAlertId":"12345678-4444-4444-4444-1234567890ab",

+ "firedDateTime":"2021-11-16T15:17:21.9232467Z",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.1"

+ },

+ "alertContext":{

+ "SearchQuery":"Heartbeat | summarize AggregatedValue=count() by bin(TimeGenerated, 5m)",

+ "SearchIntervalStartTimeUtc":"2021-11-15T15:16:49Z",

+ "SearchIntervalEndtimeUtc":"2021-11-16T15:16:49Z",

+ "ResultCount":2,

+ "LinkToSearchResults":"https://portal.azure.com#@aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F11111111-1111-1111-1111-111111111111%2FresourceGroups%2Ftest-RG%2Fproviders%2FMicrosoft.OperationalInsights%2Fworkspaces%2Ftest-logAnalyticsWorkspace%22%7D%5D%7D/q/aBcDeFgHi%2BWqUSguzc1NLMqsSlVwTE8vSk1PLElNCUvMKU21Tc4vzSvRaBcDeFgHiaBcDeFgHiaBcDeFgHiaBcDeFgHi/prettify/1/timespan/2021-11-15T15%3a16%3a49.0000000Z%2f2021-11-16T15%3a16%3a49.0000000Z",

+ "LinkToFilteredSearchResultsUI":"https://portal.azure.com#@aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F11111111-1111-1111-1111-111111111111%2FresourceGroups%2Ftest-RG%2Fproviders%2FMicrosoft.OperationalInsights%2Fworkspaces%2Ftest-logAnalyticsWorkspace%22%7D%5D%7D/q/aBcDeFgHiaBcDeFgHiaBcDeFgHiaBcDeFgHiaBcDeFgHidp%2BOPOhDKsHR%2FFeJXsTgzGJRmVui3KF3RpLyEJCX9A2iMl6jgxMn6jRevng3JmIHLdYtKP4DRI9mhc%3D/prettify/1/timespan/2021-11-15T15%3a16%3a49.0000000Z%2f2021-11-16T15%3a16%3a49.0000000Z",

+ "LinkToSearchResultsAPI":"https://api.loganalytics.io/v1/workspaces/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb/query?query=Heartbeat%20%0A%7C%20summarize%20AggregatedValue%3Dcount%28%29%20by%20bin%28TimeGenerated%2C%205m%29&timespan=2021-11-15T15%3a16%3a49.0000000Z%2f2021-11-16T15%3a16%3a49.0000000Z",

+ "LinkToFilteredSearchResultsAPI":"https://api.loganalytics.io/v1/workspaces/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb/query?query=Heartbeat%20%0A%7C%20summarize%20AggregatedValue%3Dcount%28%29%20by%20bin%28TimeGenerated%2C%205m%29%7C%20where%20todouble%28AggregatedValue%29%20%3E%200&timespan=2021-11-15T15%3a16%3a49.0000000Z%2f2021-11-16T15%3a16%3a49.0000000Z",

+ "SeverityDescription":"Informational",

+ "WorkspaceId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",

+ "SearchIntervalDurationMin":"1440",

+ "AffectedConfigurationItems":[

+

+ ],

+ "AlertType":"Metric measurement",

+ "IncludeSearchResults":true,

+ "Dimensions":[

+

+ ],

+ "SearchIntervalInMinutes":"1440",

+ "SearchResults":{

+ "tables":[

+ {

+ "name":"PrimaryResult",

+ "columns":[

+ {

+ "name":"TimeGenerated",

+ "type":"datetime"

+ },

+ {

+ "name":"AggregatedValue",

+ "type":"long"

+ }

+ ],

+ "rows":[

+ [

+ "2021-11-16T10:56:49Z",

+ 11

+ ],

+ [

+ "2021-11-16T11:56:49Z",

+ 11

+ ]

+ ]

+ }

+ ],

+ "dataSources":[

+ {

+ "resourceId":"/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.operationalinsights/workspaces/test-logAnalyticsWorkspace",

+ "region":"eastus",

+ "tables":[

+ "Heartbeat"

+ ]

+ }

+ ]

+ },

+ "Threshold":0,

+ "Operator":"Greater Than",

+ "IncludedSearchResults":"True"

+ }

+ }

+}

+```

+#### Test action log alert V1 - Numresults

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"test-logAlertRule-v1-numResults",

+ "severity":"Sev3",

+ "signalType":"Log",

+ "monitorCondition":"Fired",

+ "monitoringService":"Log Analytics",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.operationalinsights/workspaces/test-logAnalyticsWorkspace"

+ ],

+ "configurationItems":[

+ "test-computer"

+ ],

+ "originAlertId":"22222222-2222-2222-2222-222222222222",

+ "firedDateTime":"2021-11-16T15:15:58.3302205Z",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.1"

+ },

+ "alertContext":{

+ "SearchQuery":"Heartbeat",

+ "SearchIntervalStartTimeUtc":"2021-11-15T15:15:24Z",

+ "SearchIntervalEndtimeUtc":"2021-11-16T15:15:24Z",

+ "ResultCount":1,

+ "LinkToSearchResults":"https://portal.azure.com#@aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F11111111-1111-1111-1111-111111111111%2FresourceGroups%2Ftest-RG%2Fproviders%2FMicrosoft.OperationalInsights%2Fworkspaces%2Ftest-logAnalyticsWorkspace%22%7D%5D%7D/q/aBcDeFgHi%2ABCDE%3D%3D/prettify/1/timespan/2021-11-15T15%3a15%3a24.0000000Z%2f2021-11-16T15%3a15%3a24.0000000Z",

+ "LinkToFilteredSearchResultsUI":"https://portal.azure.com#@aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F11111111-1111-1111-1111-111111111111%2FresourceGroups%2Ftest-RG%2Fproviders%2FMicrosoft.OperationalInsights%2Fworkspaces%2Ftest-logAnalyticsWorkspace%22%7D%5D%7D/q/aBcDeFgHi%2ABCDE%3D%3D/prettify/1/timespan/2021-11-15T15%3a15%3a24.0000000Z%2f2021-11-16T15%3a15%3a24.0000000Z",

+ "LinkToSearchResultsAPI":"https://api.loganalytics.io/v1/workspaces/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb/query?query=Heartbeat%0A&timespan=2021-11-15T15%3a15%3a24.0000000Z%2f2021-11-16T15%3a15%3a24.0000000Z",

+ "LinkToFilteredSearchResultsAPI":"https://api.loganalytics.io/v1/workspaces/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb/query?query=Heartbeat%0A&timespan=2021-11-15T15%3a15%3a24.0000000Z%2f2021-11-16T15%3a15%3a24.0000000Z",

+ "SeverityDescription":"Informational",

+ "WorkspaceId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",

+ "SearchIntervalDurationMin":"1440",

+ "AffectedConfigurationItems":[

+ "test-computer"

+ ],

+ "AlertType":"Number of results",

+ "IncludeSearchResults":true,

+ "SearchIntervalInMinutes":"1440",

+ "SearchResults":{

+ "tables":[

+ {

+ "name":"PrimaryResult",

+ "columns":[

+ {

+ "name":"TenantId",

+ "type":"string"

+ },

+ {

+ "name":"Computer",

+ "type":"string"

+ },

+ {

+ "name":"TimeGenerated",

+ "type":"datetime"

+ }

+ ],

+ "rows":[

+ [

+ "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",

+ "test-computer",

+ "2021-11-16T12:00:00Z"

+ ]

+ ]

+ }

+ ],

+ "dataSources":[

+ {

+ "resourceId":"/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.operationalinsights/workspaces/test-logAnalyticsWorkspace",

+ "region":"eastus",

+ "tables":[

+ "Heartbeat"

+ ]

+ }

+ ]

+ },

+ "Threshold":0,

+ "Operator":"Greater Than",

+ "IncludedSearchResults":"True"

+ }

+ }

+}

+```

+#### Test action log alert V2

+> [!NOTE]

+> Log alerts rules from API version 2020-05-01 use this payload type, which only supports common schema. Search results aren't embedded in the log alerts payload when you use this version. Use [dimensions](./alerts-unified-log.md#split-by-alert-dimensions) to provide context to fired alerts.

+You can also use `LinkToFilteredSearchResultsAPI` or `LinkToSearchResultsAPI` to access query results with the [Log Analytics API](/rest/api/loganalytics/dataaccess/query/get). If you must embed the results, use a logic app with the provided links to generate a custom payload.

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"test-logAlertRule-v2",

+ "severity":"Sev3",

+ "signalType":"Log",

+ "monitorCondition":"Fired",

+ "monitoringService":"Log Alerts V2",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.operationalinsights/workspaces/test-logAnalyticsWorkspace"

+ ],

+ "configurationItems":[

+ "test-computer"

+ ],

+ "originAlertId":"22222222-2222-2222-2222-222222222222",

+ "firedDateTime":"2021-11-16T11:47:41.4728231Z",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.0"

+ },

+ "alertContext":{

+ "properties":{

+ "customKey1":"value1",

+ "customKey2":"value2"

+ },

+ "conditionType":"LogQueryCriteria",

+ "condition":{

+ "windowSize":"PT1H",

+ "allOf":[

+ {

+ "searchQuery":"Heartbeat",

+ "metricMeasureColumn":null,

+ "targetResourceTypes":"['Microsoft.OperationalInsights/workspaces']",

+ "operator":"GreaterThan",

+ "threshold":"0",

+ "timeAggregation":"Count",

+ "dimensions":[

+ {

+ "name":"Computer",

+ "value":"test-computer"

+ }

+ ],

+ "metricValue":3.0,

+ "failingPeriods":{

+ "numberOfEvaluationPeriods":1,

+ "minFailingPeriodsToAlert":1

+ },

+ "linkToSearchResultsUI":"https://portal.azure.com#@aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F11111111-1111-1111-1111-111111111111%2FresourceGroups%2Ftest-RG%2Fproviders%2FMicrosoft.OperationalInsights%2Fworkspaces%2Ftest-logAnalyticsWorkspace%22%7D%5D%7D/q/aBcDeFgHiJkLmNaBcDeFgHiJkLmNaBcDeFgHiJkLmNaBcDeFgHiJkLmN1234567890ZAZBZiaGBlaG5lbKlnAAFRmnp6WNUZoqvTBAA%3D/prettify/1/timespan/2021-11-16T10%3a17%3a39.0000000Z%2f2021-11-16T11%3a17%3a39.0000000Z",

+ "linkToFilteredSearchResultsUI":"https://portal.azure.com#@aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F11111111-1111-1111-1111-111111111111%2FresourceGroups%2Ftest-RG%2Fproviders%2FMicrosoft.OperationalInsights%2Fworkspaces%2Ftest-logAnalyticsWorkspace%22%7D%5D%7D/q/aBcDeFgHiJkLmN%2Fl35oOTZoKioEOouaBcDeFgHiJkLmN%2BaBcDeFgHiJkLmN%2BaBcDeFgHiJkLmN7HHgOCZTR0Ak%2FaBcDeFgHiJkLmN1234567890Ltcw%2FOqZS%2FuX0L5d%2Bx3iMHNzQiu3Y%2BzsjpFSWlOzgA87vAxeHW2MoAtQxe6OUvVrZR3XYZPXrd%2FIE/prettify/1/timespan/2021-11-16T10%3a17%3a39.0000000Z%2f2021-11-16T11%3a17%3a39.0000000Z",

+ "linkToSearchResultsAPI":"https://api.loganalytics.io/v1/workspaces/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb/query?query=Heartbeat%7C%20where%20TimeGenerated%20between%28datetime%282021-11-16T10%3A17%3A39.0000000Z%29..datetime%282021-11-16T11%3A17%3A39.0000000Z%29%29&timespan=2021-11-16T10%3a17%3a39.0000000Z%2f2021-11-16T11%3a17%3a39.0000000Z",

+ "linkToFilteredSearchResultsAPI":"https://api.loganalytics.io/v1/workspaces/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb/query?query=Heartbeat%7C%20where%20TimeGenerated%20between%28datetime%282021-11-16T10%3A17%3A39.0000000Z%29..datetime%282021-11-16T11%3A17%3A39.0000000Z%29%29%7C%20where%20tostring%28Computer%29%20%3D%3D%20%27test-computer%27&timespan=2021-11-16T10%3a17%3a39.0000000Z%2f2021-11-16T11%3a17%3a39.0000000Z"

+ }

+ ],

+ "windowStartTime":"2021-11-16T10:17:39Z",

+ "windowEndTime":"2021-11-16T11:17:39Z"

+ }

+ }

+ }

+}

+```

+### Sample test action activity log alerts

+#### Test action activity log alert with MonitoringService = `Administrative`

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"test-activityLogAlertRule",

+ "severity":"Sev4",

+ "signalType":"Activity Log",

+ "monitorCondition":"Fired",

+ "monitoringService":"Activity Log - Administrative",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.compute/virtualmachines/test-VM"

+ ],

+ "configurationItems":[

+ "test-VM"

+ ],

+ "originAlertId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb_123456789012345678901234567890ab",

+ "firedDateTime":"2021-11-16T08:29:01.2932462Z",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.0"

+ },

+ "alertContext":{

+ "authorization":{

+ "action":"Microsoft.Compute/virtualMachines/restart/action",

+ "scope":"/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/test-RG/providers/Microsoft.Compute/virtualMachines/test-VM"

+ },

+ "channels":"Operation",

+ "claims":"{}",

+ "caller":"user-email@domain.com",

+ "correlationId":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",

+ "eventSource":"Administrative",

+ "eventTimestamp":"2021-11-16T08:27:36.1836909+00:00",

+ "eventDataId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",

+ "level":"Informational",

+ "operationName":"Microsoft.Compute/virtualMachines/restart/action",

+ "operationId":"cccccccc-cccc-cccc-cccc-cccccccccccc",

+ "properties":{

+ "eventCategory":"Administrative",

+ "entity":"/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/test-RG/providers/Microsoft.Compute/virtualMachines/test-VM",

+ "message":"Microsoft.Compute/virtualMachines/restart/action",

+ "hierarchy":"22222222-2222-2222-2222-222222222222/CnAIOrchestrationServicePublicCorpprod/33333333-3333-3333-3333-3333333333333/44444444-4444-4444-4444-444444444444/55555555-5555-5555-5555-555555555555/11111111-1111-1111-1111-111111111111"

+ },

+ "status":"Succeeded",

+ "subStatus":"",

+ "submissionTimestamp":"2021-11-16T08:29:00.141807+00:00",

+ "Activity Log Event Description":""

+ }

+ }

+}

+```

+#### Test action activity log alert with MonitoringService = `ServiceHealth`

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/1234abcd5678efgh1234abcd5678efgh1234abcd5678efgh1234abcd5678efgh",

+ "alertRule":"test-ServiceHealthAlertRule",

+ "severity":"Sev4",

+ "signalType":"Activity Log",

+ "monitorCondition":"Fired",

+ "monitoringService":"ServiceHealth",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111"

+ ],

+ "originAlertId":"12345678-1234-1234-1234-1234567890ab",

+ "firedDateTime":"2021-11-17T05:34:48.0623172",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.0"

+ },

+ "alertContext":{

+ "authorization":null,

+ "channels":1,

+ "claims":null,

+ "caller":null,

+ "correlationId":"12345678-abcd-efgh-ijkl-abcd12345678",

+ "eventSource":2,

+ "eventTimestamp":"2021-11-17T05:34:44.5778226+00:00",

+ "httpRequest":null,

+ "eventDataId":"12345678-1234-1234-1234-1234567890ab",

+ "level":3,

+ "operationName":"Microsoft.ServiceHealth/incident/action",

+ "operationId":"12345678-abcd-efgh-ijkl-abcd12345678",

+ "properties":{

+ "title":"Test Action Group - Test Service Health Alert",

+ "service":"Azure Service Name",

+ "region":"Global",

+ "communication":"<p><strong>Summary of impact</strong>:&nbsp;This is the impact summary.</p>\n<p><br></p>\n<p><strong>Preliminary Root Cause</strong>: This is the preliminary root cause.</p>\n<p><br></p>\n<p><strong>Mitigation</strong>:&nbsp;Mitigation description.</p>\n<p><br></p>\n<p><strong>Next steps</strong>: These are the next steps.&nbsp;</p>\n<p><br></p>\n<p>Stay informed about Azure service issues by creating custom service health alerts: <a href=\"https://aka.ms/ash-videos\" rel=\"noopener noreferrer\" target=\"_blank\">https://aka.ms/ash-videos</a> for video tutorials and <a href=\"https://aka.ms/ash-alerts%20for%20how-to%20documentation\" rel=\"noopener noreferrer\" target=\"_blank\">https://aka.ms/ash-alerts for how-to documentation</a>.</p>\n<p><br></p>",

+ "incidentType":"Incident",

+ "trackingId":"ABC1-DEF",

+ "impactStartTime":"2021-11-16T20:00:00Z",

+ "impactMitigationTime":"2021-11-17T01:00:00Z",

+ "impactedServices":"[{\"ImpactedRegions\":[{\"RegionName\":\"Global\"}],\"ServiceName\":\"Azure Service Name\"}]",

+ "impactedServicesTableRows":"<tr>\r\n<td align='center' style='padding: 5px 10px; border-right:1px solid black; border-bottom:1px solid black'>Azure Service Name</td>\r\n<td align='center' style='padding: 5px 10px; border-bottom:1px solid black'>Global<br></td>\r\n</tr>\r\n",

+ "defaultLanguageTitle":"Test Action Group - Test Service Health Alert",

+ "defaultLanguageContent":"<p><strong>Summary of impact</strong>:&nbsp;This is the impact summary.</p>\n<p><br></p>\n<p><strong>Preliminary Root Cause</strong>: This is the preliminary root cause.</p>\n<p><br></p>\n<p><strong>Mitigation</strong>:&nbsp;Mitigation description.</p>\n<p><br></p>\n<p><strong>Next steps</strong>: These are the next steps.&nbsp;</p>\n<p><br></p>\n<p>Stay informed about Azure service issues by creating custom service health alerts: <a href=\"https://aka.ms/ash-videos\" rel=\"noopener noreferrer\" target=\"_blank\">https://aka.ms/ash-videos</a> for video tutorials and <a href=\"https://aka.ms/ash-alerts%20for%20how-to%20documentation\" rel=\"noopener noreferrer\" target=\"_blank\">https://aka.ms/ash-alerts for how-to documentation</a>.</p>\n<p><br></p>",

+ "stage":"Resolved",

+ "communicationId":"11223344556677",

+ "isHIR":"false",

+ "IsSynthetic":"True",

+ "impactType":"SubscriptionList",

+ "version":"0.1.1"

+ },

+ "status":"Resolved",

+ "subStatus":null,

+ "submissionTimestamp":"2021-11-17T01:23:45.0623172+00:00",

+ "ResourceType":null

+ }

+ }

+}

+```

+#### Test action activity log alert with MonitoringService = `Resource Health`

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"test-ResourceHealthAlertRule",

+ "severity":"Sev4",

+ "signalType":"Activity Log",

+ "monitorCondition":"Fired",

+ "monitoringService":"Resource Health",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.compute/virtualmachines/test-VM"

+ ],

+ "configurationItems":[

+ "test-VM"

+ ],

+ "originAlertId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb_123456789012345678901234567890ab",

+ "firedDateTime":"2021-11-16T09:54:08.9938123Z",

+ "description":"Alert rule description",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.0"

+ },

+ "alertContext":{

+ "channels":"Admin, Operation",

+ "correlationId":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",

+ "eventSource":"ResourceHealth",

+ "eventTimestamp":"2021-11-16T09:50:20.406+00:00",

+ "eventDataId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",

+ "level":"Informational",

+ "operationName":"Microsoft.Resourcehealth/healthevent/Activated/action",

+ "operationId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",

+ "properties":{

+ "title":"Rebooted by user",

+ "details":null,

+ "currentHealthStatus":"Unavailable",

+ "previousHealthStatus":"Available",

+ "type":"Downtime",

+ "cause":"UserInitiated"

+ },

+ "status":"Active",

+ "submissionTimestamp":"2021-11-16T09:54:08.5303319+00:00",

+ "Activity Log Event Description":null

+ }

+ }

+}

+```

+#### Test action activity log alert with MonitoringService = `Budget`

+```json

+{

+ "schemaId":"AIP Budget Notification",

+ "data":{

+ "SubscriptionName":"test-subscription",

+ "SubscriptionId":"11111111-1111-1111-1111-111111111111",

+ "EnrollmentNumber":"",

+ "DepartmentName":"test-budgetDepartmentName",

+ "AccountName":"test-budgetAccountName",

+ "BillingAccountId":"",

+ "BillingProfileId":"",

+ "InvoiceSectionId":"",

+ "ResourceGroup":"test-RG",

+ "SpendingAmount":"1111.32",

+ "BudgetStartDate":"11/17/2021 5:40:29 PM -08:00",

+ "Budget":"10000",

+ "Unit":"USD",

+ "BudgetCreator":"email@domain.com",

+ "BudgetName":"test-budgetName",

+ "BudgetType":"Cost",

+ "NotificationThresholdAmount":"8000.0"

+ }

+}

+```

+#### Test action activity log alert with MonitoringService = `Actual Cost Budget`

+```json

+{

+ "schemaId": "azureMonitorCommonAlertSchema",

+ "data": {

+ "essentials": {

+ "monitoringService": "CostAlerts",

+ "firedDateTime": "2022-12-07T21:13:20.645Z",

+ "description": "Your spend for budget Test_actual_cost_budget is now $11,111.00 exceeding your specified threshold $25.00.",

+ "essentialsVersion": "1.0",

+ "alertContextVersion": "1.0",

+ "alertId": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.CostManagement/alerts/Test_Alert",

+ "alertRule": null,

+ "severity": null,

+ "signalType": null,

+ "monitorCondition": null,

+ "alertTargetIDs": null,

+ "configurationItems": [

+ "budgets"

+ ],

+ "originAlertId": null

+ },

+ "alertContext": {

+ "AlertCategory": "budgets",

+ "AlertData": {

+ "Scope": "/subscriptions/11111111-1111-1111-1111-111111111111/",

+ "ThresholdType": "Actual",

+ "BudgetType": "Cost",

+ "BudgetThreshold": "$50.00",

+ "NotificationThresholdAmount": "$25.00",

+ "BudgetName": "Test_actual_cost_budget",

+ "BudgetId": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.Consumption/budgets/Test_actual_cost_budget",

+ "BudgetStartDate": "2022-11-01",

+ "BudgetCreator": "test@sample.test",

+ "Unit": "USD",

+ "SpentAmount": "$11,111.00"

+ }

+ }

+ }

+}

+```

+#### Test action activity log alerts with MonitoringService = `Forecasted Budget`

+```json

+{

+ "schemaId": "azureMonitorCommonAlertSchema",

+ "data": {

+ "essentials": {

+ "monitoringService": "CostAlerts",

+ "firedDateTime": "2022-12-07T21:13:29.576Z",

+ "description": "The total spend for your budget, Test_forcasted_budget, is forecasted to reach $1111.11 before the end of the period. This amount exceeds your specified budget threshold of $50.00.",

+ "essentialsVersion": "1.0",

+ "alertContextVersion": "1.0",

+ "alertId": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.CostManagement/alerts/Test_Alert",

+ "alertRule": null,

+ "severity": null,

+ "signalType": null,

+ "monitorCondition": null,

+ "alertTargetIDs": null,

+ "configurationItems": [

+ "budgets"

+ ],

+ "originAlertId": null

+ },

+ "alertContext": {

+ "AlertCategory": "budgets",

+ "AlertData": {

+ "Scope": "/subscriptions/11111111-1111-1111-1111-111111111111/",

+ "ThresholdType": "Forecasted",

+ "BudgetType": "Cost",

+ "BudgetThreshold": "$50.00",

+ "NotificationThresholdAmount": "$50.00",

+ "BudgetName": "Test_forcasted_budget",

+ "BudgetId": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.Consumption/budgets/Test_forcasted_budget",

+ "BudgetStartDate": "2022-11-01",

+ "BudgetCreator": "test@sample.test",

+ "Unit": "USD",

+ "SpentAmount": "$999.99",

+ "ForecastedTotalForPeriod": "$1111.11"

+ }

+ }

+ }

+}

+```

+#### Test action activity log alerts with MonitoringService = `Smart Alert`

+```json

+{

+ "schemaId":"azureMonitorCommonAlertSchema",

+ "data":{

+ "essentials":{

+ "alertId":"/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.AlertsManagement/alerts/12345678-1234-1234-1234-1234567890ab",

+ "alertRule":"Dependency Latency Degradation - test-applicationInsights",

+ "severity":"Sev3",

+ "signalType":"Log",

+ "monitorCondition":"Fired",

+ "monitoringService":"SmartDetector",

+ "alertTargetIDs":[

+ "/subscriptions/11111111-1111-1111-1111-111111111111/resourcegroups/test-RG/providers/microsoft.insights/components/test-applicationInsights"

+ ],

+ "configurationItems":[

+ "test-applicationInsights"

+ ],

+ "originAlertId":"1234abcd5678efgh1234abcd5678efgh1234abcd5678efgh1234abcd5678efgh",

+ "firedDateTime":"2021-10-28T19:09:09.1115084Z",

+ "description":"Dependency Latency Degradation notifies you of an unusual increase in response by a dependency your app is calling (e.g. REST API or database)",

+ "essentialsVersion":"1.0",

+ "alertContextVersion":"1.0"

+ },

+ "alertContext":{

+ "DetectionSummary":"A degradation in the dependency duration over the last 24 hours",

+ "FormattedOccurrenceTime":"2021-10-27T23:59:59Z",

+ "DetectedValue":"0.45 sec",

+ "NormalValue":"0.27 sec (over the last 7 days)",

+ "PresentationInsightEventRequest":"/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/test-RG/providers/microsoft.insights/components/test-applicationInsights/query?query=systemEvents%0d%0a++++++++++++++++%7c+where+timestamp+%3e%3d+datetime(%272021-10-27T23%3a29%3a59.0000000Z%27)+%0d%0a++++++++++++++++%7c+where+itemType+%3d%3d+%27systemEvent%27+and+name+%3d%3d+%27ProactiveDetectionInsight%27+%0d%0a++++++++++++++++%7c+where+dimensions.InsightType+%3d%3d+3+%0d%0a++++++++++++++++%7c+where+dimensions.InsightVersion+%3d%3d+%27SmartAlert%27%0d%0a++++++++++++++++%7c+where+dimensions.InsightDocumentId+%3d%3d+%2712345678-abcd-1234-5678-abcd12345678%27+%0d%0a++++++++++++++++%7c+project+dimensions.InsightPropertiesTable%2cdimensions.InsightDegradationChart%2cdimensions.InsightCountChart%2cdimensions.InsightLinksTable%0d%0a++++++++++++++++&api-version=2018-04-20",

+ "SmartDetectorId":"DependencyPerformanceDegradationDetector",

+ "SmartDetectorName":"Dependency Performance Degradation Detector",

+ "AnalysisTimestamp":"2021-10-28T19:09:09.1115084Z"

+ }

+ }

+}

+```

+## Next steps

+- [Learn how to create a logic app that uses the common alert schema to handle all your alerts](./alerts-common-schema-integrations.md)

+Alert context (payload) | The rule applies only to alerts that contain any of the filter's strings within the [alert context](./alerts-common-schema.md) section of the alert. This section includes fields specific to each alert type. This filter does not apply to log alert search results. |

+This article discusses common problems in Azure Monitor alerting and notifications. Azure Monitor alerts proactively notify you when important conditions are found in your monitoring data. They allow you to identify and address issues before the users of your system notice them. For more information on alerting, see [Overview of alerts in Microsoft Azure](./alerts-overview.md).

+You can see fired alerts in the Azure portal.

+Refer to these articles for troubleshooting information about metric or log alerts that are not behaving as expected:

+- [Troubleshoot Azure Monitor metric alerts](alerts-troubleshoot-metric.md)

+- [Troubleshoot Azure Monitor log alerts](alerts-troubleshoot-log.md)

+ Also, check the payload format (JSON) for [activity log alerts](../alerts/activity-log-alerts-webhook.md), for [log search alerts](../alerts/alerts-log-webhook.md) (both Application Insights and log analytics), for [metric alerts](alerts-metric-near-real-time.md#payload-schema), for the [common alert schema](../alerts/alerts-common-schema.md), and for the deprecated [classic metric alerts](./alerts-webhooks.md).

+- You need to have managed identity authentication enabled on your cluster. To enable, see [migrate your AKS cluster to managed identity authentication](container-insights-enable-existing-clusters.md?tabs=azure-cli#migrate-to-managed-identity-authentication). Note: Enabling Managed Identity will create a new Data Collection Rule (DCR) named `MSCI-<WorkspaceRegion>-<ClusterName>`

+### From the Azure portal

+Navigate to your cluster. Open the _Insights_ tab for your cluster. Open the _Monitor Settings_ panel. Click on Edit collection settings, then check the box for _Enable Syslog collection_

+Use the following command in Azure CLI to enable syslog collection when you create a new AKS cluster.

+### Access using built-in workbooks

+To get a quick snapshot of your syslog data, customers can use our built-in Syslog workbook. There are two ways to access the built-in workbook.

+Option 1 - The Reports tab in Container Insights.

+Navigate to your cluster. Open the _Insights_ tab for your cluster. Open the _Reports_ tab and look for the _Syslog_ workbook.

+Option 2 - The Workbooks tab in AKS

+Navigate to your cluster. Open the _Workbooks_ tab for your cluster and look for the _Syslog_ workbook.

+### Access using log queries

+#### Sample queries

+Once setup customers can start sending Syslog data to the tools of their choice

+- Send Syslog to Microsoft Sentinel: https://learn.microsoft.com/azure/sentinel/connect-syslog

+- Export data from Log Analytics: https://learn.microsoft.com/azure/azure-monitor/logs/logs-data-export?tabs=portal

+Read more

+- [Syslog record properties](/azure/azure-monitor/reference/tables/syslog)

+Share your feedback for the preview here: https://forms.office.com/r/BBvCjjDLTS

+> InfluxData Telegraf is an open source agent and not officially supported by Azure Monitor. For issues wuth the Telegraf connector, please refer to the Telegraf GitHub page here: [InfluxData](https://github.com/influxdata/telegraf)

+For general Snapshot Debugger troubleshooting, refer to the [Snapshot Debugger Troubleshoot documentation](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md).

+<br>Snapshot Collector used via SDK is not supported when Interop feature is enabled. [See more not supported scenarios.](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md#not-supported-scenarios)

+* For help with troubleshooting Snapshot Debugger issues, see [Snapshot Debugger troubleshooting](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md).

+* For help with troubleshooting Snapshot Debugger issues, see [Snapshot Debugger troubleshooting](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md).

+- For help with troubleshooting Snapshot Debugger issues, see [Snapshot Debugger troubleshooting](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md).

+If you've enabled Snapshot Debugger but aren't seeing snapshots, check our [Troubleshooting guide](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md).

+Snapshot-Debugger|[ Troubleshoot problems enabling Application Insights Snapshot Debugger or viewing snapshots](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot.md)|Removing the TSG from the AzMon TOC and adding to the support TOC|

+ The VNet you specify must have a subnet delegated to Azure NetApp Files. The Azure NetApp Files service can be accessed only from the same Vnet or from a Vnet that is in the same region as the volume through VNet peering. You can also access the volume from your on-premises network through Express Route.

+ If you have not delegated a subnet, you can click **Create new** on the Create a Volume page. Then in the Create Subnet page, specify the subnet information, and select **Microsoft.NetApp/volumes** to delegate the subnet for Azure NetApp Files. In each VNet, only one subnet can be delegated to Azure NetApp Files.

+* Qatar Central

+* Qatar Central

+* Qatar Central

+>

+> Visual Studio Code enables you to paste JSON as Bicep. It automatically runs the decompile command. For more information, see [Paste JSON as Bicep](./visual-studio-code.md#paste-as-bicep-preview).

+>

+> Visual Studio Code enables you to paste JSON as Bicep. For more information, see [Paste JSON as Bicep](./visual-studio-code.md#paste-as-bicep-preview).

+1. **Identify and recreate any missing resources.** Not all Azure resource types can be exported through the Azure portal, Azure CLI, or Azure PowerShell. For example, virtual machine extensions such as the DependencyAgentWindows and MMAExtension (Microsoft Monitoring Agent) aren't supported resource types for export. For any resource that wasn't exported, such as virtual machine extensions, you need to recreate those resources in your new Bicep file. You can recreate resources using various tools and approaches, including [Azure Resource Explorer](../templates/export-template-portal.md?azure-portal=true), the [Bicep and ARM template reference documentation](/azure/templates/?azure-portal=true), and the [Azure Quickstart Templates](https://azure.microsoft.com/resources/templates?azure-portal=true) site.

+1. **Revise parameters, variables, and symbolic names.** It's possible the names of parameters, variables, and symbolic names generated by the decompiler don't match your standard naming convention. Review the generated names and make adjustments as necessary.

+1. **Prepare a rollback plan.** The ability to recover from a failed deployment is crucial. Create a rollback strategy if any breaking changes are introduced into your environments. Take inventory of the types of resources that are deployed, such as virtual machines, web apps, and databases. Each resource's data plane should be considered as well. Do you have a way to recover a virtual machine and its data? Do you have a way to recover a database after deletion? A well-developed rollback plan helps to keep your downtime to a minimum if any issues arise from a deployment.

+1. **Run smoke tests.** After your deployment is complete, you should run a series of *smoke tests* to ensure that your application or workload is working properly. For example, test to see if your web app is accessible through normal access channels, such as the public Internet or across a corporate VPN. For databases, attempt to make a database connection and execute a series of queries. With virtual machines, sign in to the virtual machine and make sure that all services are up and running.

+Open or create a Bicep file in VS Code, select the **View** menu and then select **Command Palette**. You can also use **F1** or the key combination <kbd>Ctrl+Shift+P</kbd> to bring up the command palette. Type **Bicep** to list the Bicep commands.

+1. From the **View** menu, select **Command Palette** (or press <kbd>Ctrl/Cmd+Shift+P</kbd>), and then select **Bicep: Create Bicep Configuration File**.

+## Paste as Bicep (Preview)

+You can paste a JSON snippet from an ARM template to Bicep file. Visual Studio Code automatically decompiles the JSON to Bicep. This feature is only available with the Bicep extension version 0.14.0 or newer.

+To enable the feature:

+1. In Visual Studio Code, select **Manage** (gear icon) in the side menu. Select **Settings**. You can also use <kbd>Ctrl+,</kbd> to open settings.

+1. Expand **Extensions** and then select **Bicep**.

+1. Select **Decompile on Paste**.

+ :::image type="content" source="./media/visual-studio-code/enable-paste-json.png" alt-text="Screenshot of Visual Studio Code Paste as Bicep.":::

+By using this feature, you can paste:

+- Full ARM JSON templates.

+- Single resource or multiple resources.

+- JSON values, such as objects, arrays, and strings. A string with double-quotes is converted to single-quotes.

+For example, you can start with the following Bicep file:

+```bicep

+@description('Storage Account type')

+@allowed([

+ 'Standard_LRS'

+ 'Standard_GRS'

+ 'Standard_ZRS'

+ 'Premium_LRS'

+])

+param storageAccountsku string = 'Standard_LRS'

+@description('Location for all resources.')

+param location string = resourceGroup().location

+var storageAccountName = '${uniqueString(resourceGroup().id)}storage'

+resource storageAccount 'Microsoft.Storage/storageAccounts@2021-08-01' = {

+ name: storageAccountName

+ location: location

+ sku: {

+ name: storageAccountsku

+ }

+ kind: 'StorageV2'

+ tags: {

+ ObjectName: storageAccountName

+ }

+ properties: {}

+}

+output storageAccountName string = storageAccountName

+```

+And, paste the following JSON:

+```json

+{

+ "type": "Microsoft.Batch/batchAccounts",

+ "apiVersion": "2021-06-01",

+ "name": "[parameters('batchAccountName')]",

+ "location": "[parameters('location')]",

+ "tags": {

+ "ObjectName": "[parameters('batchAccountName')]"

+ },

+ "properties": {

+ "autoStorage": {

+ "storageAccountId": "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"

+ }

+ }

+}

+```

+Visual Studio Code automatically converts the JSON to Bicep. Notice that you also need to add the parameter named `batchAccountName`.

+You can undo the decompilation by using <kbd>Ctrl+Z</kbd>. The original JSON appears in the file.

+You cannot move VPN Gateways across resource groups or subscriptions if they are of Basic SKU. Basic SKU is only meant for test environment usage and doesn't support resource move operation.

+> | virtualnetworkgateways | **Yes** except Basic SKU - see [Networking move guidance](./move-limitations/networking-move-limitations.md)| **Yes** except Basic SKU - see [Networking move guidance](./move-limitations/networking-move-limitations.md) | No |

+ "name": "$return"

+You can use the Windows cmd.exe command shell instead of a Bash shell to run the commands in this tutorial.

+## Prepare your environment

+## Create a resource group

+Use the Azure CLI [az webpubsub create](/cli/azure/webpubsub#az-webpubsub-create) command to create a Web PubSub in the resource group you've created. The following command creates a _Free_ Web PubSub resource under resource group `myResourceGroup` in `EastUS`:

+Each Web PubSub resource must have a unique name. Replace &lt;your-unique-resource-name&gt; with the name of your Web PubSub instance in the following command.

+```azurecli

+az webpubsub create --resource-group myResourceGroup --name <your-unique-resource-name> --location EastUS --sku Free_F1

+```

+The output of this command shows properties of the newly created resource. Take note of the two properties listed below:

+* **name**: The Web PubSub name you provided in the `--name` parameter above.

+* **hostName**: In the example, the host name is `<your-unique-resource-name>.webpubsub.azure.com/`.

+At this point, your Azure account is the only one authorized to perform any operations on this new resource.

+ * The package [Websocket.Client](https://github.com/Marfusios/websocket-client) is a third-party package supporting WebSocket connections. You can use any API/library that supports WebSocket.

+1. To start the subscriber, run the following command replacing `<Web-PubSub-connection-string>` with the connection string you copied earlier:

+ dotnet run <Web-PubSub-connection-string> "myHub1"

+1. Run the following command replacing `<Web-PubSub-connection-string>` with the connection string you copied earlier. If you are using Windows command shell, you can use `set` instead of `export`.

+ export WebPubSubConnectionString=<Web-PubSub-connection-string>

+ node subscribe.js

+1. Run the following command replacing `<Web-PubSub-connection-string>` with the connection string you copied earlier:

+ python subscribe.py <Web-PubSub-connection-string> "myHub1"

+ ```bash

+1. To start the subscriber app, go to the *webpubsub-quickstart-subscriber* directory and run the following command. Replace `<Web-PubSub-connection-string>` with the connection string you copied earlier.

+ ```bash

+ mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"

+1. Send a message by running the following command. Replace `<Web-PubSub-connection-string>` with the connection string you copied earlier.

+ dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"

+1. Check the command shell of the subscriber to see that it received the message:

+ ```console

+1. To send a message, run the following command replacing `<Web-PubSub-connection-string>` with the connection string you copied earlier. If you are using Windows command shell, you can use `set` instead of `export`.

+ export WebPubSubConnectionString=<Web-PubSub-connection-string>

+1. You can see that the subscriber received the message:

+ ```console

+1. To send a message, run the following command replacing `<Web-PubSub-connection-string>` with the connection string you copied earlier.

+ python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"

+ ```console

+ ```bash

+1. To send a message, go to the *webpubsub-quickstart-publisher* directory and run the project using the following command. Replace the `<Web-PubSub-connection-string>` with the connection string you copied earlier.

+ ```bash

+ mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1' 'Hello World'"

+1. You can see that the subscriber received the message:

+ ```console

+This tutorial provides you with a basic idea of how to connect to the Web PubSub service and publish messages to the connected clients.

+ >To further tighten the security, we recommend you create a custom role and assign that to the Managed Identity instead of the above built-in roles. This ensures that all the calls run with least privileges. For more information on custom role, see the [GitHub article](https://github.com/Azure/Microsoft-Defender-for-Cloud/tree/main/Workflow%20automation/Protect%20Azure%20VM%20Backup%20from%20Ransomware).

+> Users should note the performance limitations of this feature. As pointed out in the footnote section of the above blade, this feature should be used when the total size of recovery is 10 GB or less. The expected data transfer speeds are around 1 GB per hour.

+zone_pivot_groups: app-service-platform-windows-linux-sphere-rtos

+Edge Secured-core is an incremental certification in the Azure Certified Device program for IoT devices running a full operating system, such as Linux, Windows 10 IoT or Azure Sphere OS. This program enables device partners to differentiate their devices by meeting an additional set of security criteria. Devices meeting this criteria enable these promises:

+|Name|SecuredCore.Hardware.Identity|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement is to validate the device identity is rooted in hardware and can be the primary authentication method with Azure IoT Hub Device Provisioning Service (DPS).|

+|Validation|Devices are enrolled to DPS using the TPM authentication mechanism during testing.|

+|Name|SecuredCore.Hardware.MemoryProtection|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement is to validate that DMA isn't enabled on externally accessible ports.|

+|Validation|If DMA capable external ports exist on the device, toolset to validate that the IOMMU, or SMMU is enabled and configured for those ports.|

+|Name|SecuredCore.Firmware.Protection|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement is to ensure that device has adequate mitigations from Firmware security threats.|

+|Validation|Device to be validated through [Edge Secured-core Agent](https://aka.ms/Scforwiniot) toolset to confirm it's protected from firmware security threats through one of the following approaches: <ul><li>DRTM + UEFI Management Mode mitigations</li><li>DRTM + UEFI Management Mode hardening</li></ul> |

+|Name|SecuredCore.Firmware.SecureBoot|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement is to validate the boot integrity of the device.|

+|Name|SecuredCore.Firmware.Attestation|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement is to ensure the device can remotely attest to the Microsoft Azure Attestation service.|

+|Name|SecuredCore.Encryption.Storage|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement to validate that sensitive data can be encrypted on nonvolatile storage.|

+|Name|SecuredCore.Encryption.TLS|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement is to validate support for required TLS versions and cipher suites.|

+|Name|SecuredCore.Protection.CodeIntegrity|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of this requirement is to validate that code integrity is available on this device.|

+|Name|SecuredCore.Protection.NetworkServices|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2024|

+|Description|The purpose of the requirement is to validate that services listening for input from the network aren't running with elevated privileges.|

+|Validation|Device to be validated through [Edge Secured-core Agent](https://aka.ms/Scforwiniot) toolset to ensure that third party services accepting network connections aren't running with elevated LocalSystem and LocalService privileges. <ol><li>Exceptions may apply</li></ol>|

+|Name|SecuredCore.Built-in.Security|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|Future|Future|

+|Description|The purpose of the requirement is to make sure devices can report security information and events by sending data to Azure Defender for IoT. <br>Note: Download and deploy security agent from GitHub|

+|Name|SecuredCore.Protection.Baselines|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|Future|Future|

+|Description|The purpose of the requirement is to validate that the system conforms to a baseline security configuration.|

+Some requirements of this program are based on a business agreement between your company and Microsoft. The following requirements aren't validated through our test harness, but are required by your company in certifying the device.

+|Description|The purpose of the requirement is to validate that debug functionality on the device is disabled.|

+|Description|The purpose of this requirement is to validate the device against two use cases: a) Ability to perform a reset (remove user data, remove user configs), b) Restore device to last known good in the case of an update causing issues.|

+|Validation|Commitment from submission that devices certified can be kept up to date for 60 months from date of submission. Specifications available to the purchaser and devices itself in some manner should indicate the duration for which their software will be updated.|

+|Description|The purpose of this policy is to ensure that there's a mechanism for collecting and distributing reports of vulnerabilities in the product.|

+The Edge Secured-core program for Linux is enabled through the IoT Edge runtime, which is supported based on [Tier 1 and Tier 2 operating systems](../iot-edge/support.md).

+|Name|SecuredCore.Hardware.Identity|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to validate the device identify is rooted in hardware.|||

+|Requirements dependency||TPM v2.0 device|TPM v2.0 </br><sup>or *other supported method</sup>|

+|Validation Type|Manual/Tools|||

+|Validation|Device to be validated through toolset to ensure that the device has a HWRoT present and that it can be provisioned through DPS using TPM or SE.|||

+|Resources|[Setup auto provisioning with DPS](../iot-dps/quick-setup-auto-provision.md)|||

+|Name|SecuredCore.Hardware.MemoryProtection|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to validate ensure that memory integrity helps protect the device from vulnerable peripherals.|

+|Validation|memory regions for peripherals must be gated with hardware/firmware such as memory region domain controllers or SMMU (System memory management Unit).|

+|Name|SecuredCore.Firmware.Protection|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to ensure that device has adequate mitigations from Firmware security threats.|

+|Validation|Device to be validated through toolset to confirm it's protected from firmware security threats through one of the following approaches: <ul><li>Approved FW that does SRTM + runtime firmware hardening</li><li>Firmware scanning and evaluation by approved Microsoft third party</li></ul> |

+|Name|SecuredCore.Firmware.SecureBoot|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to validate the boot integrity of the device.|

+|Name|SecuredCore.Firmware.Attestation|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to ensure the device can remotely attest to the Microsoft Azure Attestation service.|

+|Dependency||TPM 2.0|TPM 2.0 </br><sup>or *supported OP-TEE based application chained to a HWRoT (Secure Element or Secure Enclave)</sup>|

+|Validation|Device to be validated through toolset to ensure that platform boot logs and applicable runtime measurements can be collected and remotely attested to the Microsoft Azure Attestation service.|

+|Resources| [Microsoft Azure Attestation](../attestation/index.yml) </br> Certification portal test includes an attestation client that when combined with the TPM 2.0 can validate the Microsoft Azure Attestation service.|

+|Name|SecuredCore.Hardware.SecureEnclave|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|Future|Future|

+|Description|The purpose of the requirement to validate the existence of a secure enclave and that the enclave can be used for security functions.|

+|Validation||

+|Name|SecuredCore.Encryption.Storage|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement to validate that sensitive data can be encrypted on nonvolatile storage.|

+|Name|SecuredCore.Encryption.TLS|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to validate support for required TLS versions and cipher suites.|

+|Name|SecuredCore.Protection.CodeIntegrity|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of this requirement is to validate that authorized code runs with least privilege.|

+|Name|SecuredCore.Protection.NetworkServices|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|<sup>*</sup>Required|2023|2023|

+|Description|The purpose of the requirement is to validate that applications accepting input from the network aren't running with elevated privileges.|

+|Validation|Device to be validated through toolset to ensure that services accepting network connections aren't running with SYSTEM or root privileges.|

+|Name|SecuredCore.Built-in.Security|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to make sure devices can report security information and events by sending data to Microsoft Defender for IoT.|

+|Validation |<ol><li>Device must generate security logs and alerts.</li><li>Device logs and alerts messages to Azure Security Center.</li><li>Device must have the Azure Defender for IoT microagent running</li><li>Configuration_Certification_Check must report TRUE in the module twin</li><li>Validate alert messages from Azure Defender for IoT.</li></ol>|

+|Name|SecuredCore.Manageability.Configuration|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to validate that device supports auditing and setting of system configuration (and certain management actions such as reboot) through Azure.|

+|Dependency|azure-osconfig|

+|Validation|<ol><li>Device must report, via IoT Hub, its firewall state, firewall fingerprint, ip addresses, network adapter state, host name, hosts file, TPM (absence, or presence with version) and package manager sources (see What can I manage) </li><li>Device must accept the creation, via IoT Hub, of a default firewall policy (accept vs drop), and at least one firewall rule, with positive remote acknowledgment (see configurationStatus)</li><li>Device must accept the replacement of /etc/hosts file contents via IoT Hub, with positive remote acknowledgment (see https://learn.microsoft.com/en-us/azure/osconfig/howto-hosts?tabs=portal#the-object-model )</li><li>Device must accept and implement, via IoT Hub, remote reboot</li></ol> Note: Use of other system management toolchains (for example, Ansible, etc.) by operators are not prohibited, but the device must include the azure-osconfig agent such that it's ready to be managed from Azure.|

+|Name|SecuredCore.Update|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Audit|2023|2023|

+|Description|The purpose of the requirement is to validate the device can receive and update its firmware and software.|

+|Name|SecuredCore.Protection.Baselines|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to validate the extent to which the device implements the Azure Security Baseline|

+|Dependency|azure-osconfig|

+|Validation|OSConfig is present on the device and reporting to what extent it implements the Azure Security Baseline.|

+|Resources| <ul><li>https://techcommunity.microsoft.com/t5/microsoft-security-baselines/bg-p/Microsoft-Security-Baselines </li><li> https://www.cisecurity.org/cis-benchmarks/ </li><li>https://learn.microsoft.com/en-us/azure/governance/policy/samples/guest-configuration-baseline-linux|</li></ul>

+|Name|SecuredCore.Protection.SignedUpdates|x86/AMD64|Arm64|

+|:|:|:|:|

+|Status|Required|2023|2023|

+|Description|The purpose of the requirement is to validate that updates must be signed.|

+|Validation|Device to be validated through toolset to ensure that updates to the operating system, drivers, application software, libraries, packages and firmware won't be applied unless properly signed and validated.

+|Description|The purpose of the requirement is to validate that debug functionality on the device is disabled.|

+|Description|The purpose of this requirement is to validate the device against two use cases: a) Ability to perform a reset (remove user data, remove user configs), b) Restore device to last known good if an update causing issues.|

+|Description|The purpose of this policy is to ensure that there's a mechanism for collecting and distributing reports of vulnerabilities in the product.|

+</br>

+<!->

+<!->

+<!->

+## Azure Sphere platform Support

+The Mediatek MT3620AN must be included in your design. Additional guidance for building secured Azure Sphere applications can be within the [Azure Sphere application notes](https://learn.microsoft.com/azure-sphere/app-notes/app-notes-overview).

+## Azure Sphere Hardware/Firmware Requirements

+|Name|SecuredCore.Hardware.Identity|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to validate the device identity is rooted in hardware.||

+|Validation Type|Prevalidated, no additional validation is required||

+|Validation|Provided by Microsoft||

+</br>

+|Name|SecuredCore.Hardware.MemoryProtection|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to ensure that memory integrity helps protect the device from vulnerable peripherals.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Firmware.Protection|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to ensure that device has adequate mitigations from Firmware security threats.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Firmware.SecureBoot|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to validate the boot integrity of the device.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Firmware.Attestation|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to ensure the device can remotely attest to a Microsoft Azure Attestation service.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Hardware.SecureEnclave|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of this requirement is to validate hardware security that is accessible from a secure operating system.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+## Azure Sphere OS Configuration Requirements

+|Name|SecuredCore.Encryption.Storage|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of this requirement is to validate that sensitive data can be encrypted on nonvolatile storage.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+|Resources|[Data at rest protection on Azure Sphere](https://learn.microsoft.com/azure-sphere/app-notes/app-notes-overview)|

+</br>

+|Name|SecuredCore.Encryption.TLS|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to validate support for required TLS versions and cipher suites.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+|Resources| [TLS support in IoT Hub](../iot-hub/iot-hub-tls-support.md) <br /> |

+</br>

+|Name|SecuredCore.Protection.CodeIntegrity|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of this requirement is to validate that authorized code runs with least privilege.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Protection.NetworkServices|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to validate that applications accepting input from the network aren't running with elevated privileges.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Protection.NetworkFirewall|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of this requirement is to validate that applications can't connect to endpoints that haven't been authorized.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+## Azure Sphere Software/Service Requirements

+|Name|SecuredCore.Built-in.Security|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of this requirement is to make sure devices can report security information and events by sending data to a Microsoft telemetry service.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+|Resources|[Collect and interpret error data - Azure Sphere](https://learn.microsoft.com/azure-sphere/deployment/interpret-error-data?tabs=cliv2beta)</br>[Configure crash dumps - Azure Sphere](https://learn.microsoft.com/azure-sphere/deployment/configure-crash-dumps)|

+</br>

+|Name|SecuredCore.Manageability.Configuration|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of this requirement is to validate the device supports remote administration via service-based configuration control.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Update|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to validate the device can receive and update its firmware and software.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Protection.Baselines|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to validate that the system conforms to a baseline security configuration|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Protection.SignedUpdates|Azure Sphere|

+|:|:|:|

+|Status|Required|2023|

+|Description|The purpose of the requirement is to validate that updates must be signed.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+## Azure Sphere Policy Requirements

+|Name|SecuredCore.Policy.Protection.Debug|

+|:|:|

+|Status|Required|

+|Description|The purpose of the policy requires that debug functionality on the device is disabled.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Policy.Manageability.Reset|

+|:|:|

+|Status|Required|

+|Description|The policy requires that the device can execute two use cases: a) Ability to perform a reset (remove user data, remove user configurations), b) Restore device to last known good in the case of an update causing issues.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Policy.Updates.Duration|

+|:|:|

+|Status|Required|

+|Description|The purpose of this policy is to ensure that the device remains secure.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+</br>

+|Name|SecuredCore.Policy.Vuln.Disclosure|

+|:|:|

+|Status|Required|

+|Description|The purpose of this policy is to ensure that there's a mechanism for collecting and distributing reports of vulnerabilities in the product.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Azure Sphere vulnerabilities are collected by Microsoft through MSRC and are published to customers through the Tech Community Blog, Azure Sphere ΓÇ£WhatΓÇÖs NewΓÇ¥ page, and through MitreΓÇÖs CVE database.|

+|Resources|<ul><li>[Report an issue and submission guidelines](https://www.microsoft.com/msrc/faqs-report-an-issue)</li><li>[What's new - Azure Sphere](https://learn.microsoft.com/azure-sphere/product-overview/whats-new)</li><li>

+[Azure Sphere CVEs](https://learn.microsoft.com/azure-sphere/deployment/azure-sphere-cves)|</li></ul>

+</br>

+|Name|SecuredCore.Policy.Vuln.Fixes|

+|:|:|

+|Status|Required|

+|Description|The purpose of this policy is to ensure that vulnerabilities that are high/critical (using CVSS 3.0) are addressed within 180 days of the fix being available.|

+|Validation Type|Prevalidated, no additional validation is required|

+|Validation|Provided by Microsoft|

+[Intent recognition](./intent-recognition.md): Use speech-to-text with conversational language understanding to derive user intents from transcribed speech and act on voice commands.

+| Speech-to-text | Analyzes sentiment and transcribes continuous real-time speech or batch audio recordings with intermediate results. | Latest: 3.12.0<br/><br/>For all supported versions and locales, see the [Microsoft Container Registry (MCR)](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/speech-to-text/tags) and [JSON tags](https://mcr.microsoft.com/v2/azure-cognitive-services/speechservices/speech-to-text/tags/list).|

+| Custom speech-to-text | Using a custom model from the [Custom Speech portal](https://speech.microsoft.com/customspeech), transcribes continuous real-time speech or batch audio recordings into text with intermediate results. | Latest: 3.12.0<br/><br/>For all supported versions and locales, see the [Microsoft Container Registry (MCR)](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/custom-speech-to-text/tags) and [JSON tags](https://mcr.microsoft.com/v2/azure-cognitive-services/speechservices/speech-to-text/tags/list). |

+| Neural text-to-speech | Converts text to natural-sounding speech by using deep neural network technology, which allows for more natural synthesized speech. | Latest: 2.11.0<br/><br/>For all supported versions and locales, see the [Microsoft Container Registry (MCR)](https://mcr.microsoft.com/product/azure-cognitive-services/speechservices/neural-text-to-speech/tags) and [JSON tags](https://mcr.microsoft.com/v2/azure-cognitive-services/speechservices/neural-text-to-speech/tags/list). |

+## Add a break

+Use the `break` element to override the default behavior of breaks or pauses between words. You can use it to add pauses that are otherwise automatically inserted by the Speech service.

+| `strength` | The relative duration of a pause by using one of the following values:<br/><ul><li>x-weak</li><li>weak</li><li>medium (default)</li><li>strong</li><li>x-strong</li></ul>| Optional |

+The supported values for attributes of the `break` element were [described previously](#add-a-break). The following three ways all add 750 ms breaks.

+ Welcome <break time="750ms" /> to text-to-speech.

+ curl ${endpoint%/}/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2022-12-01 \

+For more information about managed identities, see [Managed identities for Azure resources](../../../active-directory/managed-identities-azure-resources/overview.md).

+- The dataset cannot exceed 100 Mb in total file size.

+### MacOS Ventura Safari(v16.3 and below) screen sharing.

+Screen sharing does not work in MacOS Ventura Safari(v16.3 and below). Known issue from Safari and will be fixed in v16.4+

+ --priority 100

+ USER_NAME=$(az identity show -n $SERVICE_PRINCIPAL_NAME -g $RESOURCE_GROUP_NAME --subscription $SUBSCRIPTION_ID --query "clientId" -o tsv)

+- Reading or updating throughput on database or container level resources.

+ConsumedService | EA, PAYG | Name of the service the charge is associated with. For more information about choosing a method to get cost details, see [Choose a cost details solution](../automate/usage-details-best-practices.md).

+1. From ADF portal under **Manage**, select a custom integration run time and you go to edit mode.

+ Title: Use alert processing rules to manage alert notifications on Azure Stack Edge devices | Microsoft Docs

+description: Describes how to define alert processing rules to manage alert notifications for Azure Stack Edge devices in the Azure portal.

+# Use alert processing rules to manage alert notifications on Azure Stack Edge devices

+This article describes how to create alert processing rules in the Azure portal. Alert processing rules trigger or suppress notifications for device events that occur within a resource group, an Azure subscription, or an individual Azure Stack Edge resource.

+## About alert processing rules

+An alert processing rule can add action groups to alert notifications. Use alert notification preferences, like email or SMS messages, to notify users when alerts are triggered.

+For more information about alert processing rules, see [Alert processing rules](../azure-monitor/alerts/alerts-processing-rules.md?tabs=portal). For more information about action groups, see [Create and manage action groups in the Azure portal](../azure-monitor/alerts/action-groups.md).

+## Create an alert processing rule

+Use the following steps in the Azure portal to create an alert processing rule for your Azure Stack Edge device.

+> These steps create an alert processing rule. The alert processing rule adds action groups to alert notifications. For details about creating an alert processing rule to suppress notifications, see [Alert processing rules](../azure-monitor/alerts/alerts-action-rules.md?tabs=portal).

+1. Go to the Azure Stack Edge device in the [Azure portal](https://portal.azure.com), and select the **Alerts** menu item (under **Monitoring**). Then select **Alert processing rules**.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-alert-processing-rules-01.png#lightbox)

+2. On the **Alert processing rules** page, select **+ Create** to launch the **Create an alert processing rule** wizard.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-alert-processing-rules-create-rule-02.png#lightbox)

+3. On the **Scope** page, select **+ Select scope**.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-alert-processing-rules-select-scope-03.png#lightbox)

+1. Select a **Subscription** and optionally filter by **Resource types**. To filter by Azure Stack Edge resources, select **Resource types** for **Azure Stack Edge / Data Box Gateway** as shown in the following example.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-alert-processing-rules-select-subscription-04.png#lightbox)

+1. The **Resource type** option lists the available resources based on your selection. Use the filter option to reduce the list of options. Select the **Checkbox** for the scope option you want to work with and then select **Apply**.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-new-action-rule-scope-selection-05a.png#lightbox)

+1. You can also use the **Filter** control in the following example to reduce the list of options to a subset of alerts within the selected scope.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-filter-scope-results-06a.png#lightbox)

+

+1. On the **Add filters** pane, under **Filters**, add each filter you want to apply. For each filter, select the **Filter** type, **Operator**, and **Value**.

+ For a list of filter options, see [Filter criteria](../azure-monitor/alerts/alerts-processing-rules.md?tabs=portal#scope-and-filters-for-alert-processing-rules).

+ The filters in the following example apply to all alerts at Severity levels 2, 3, and 4 that the Monitor service raises for Azure Stack Edge resources.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-action-rule-filter-criteria-builder-07.png#lightbox)

+1. On the **Rule Settings** page, select **Apply action group** to create a rule that sends notifications.

+ Select an option to **+ Select action group** for an existing group or **+ Create action group** to create a new one.

+ To create a new action group, select **+ Create action group** and follow the steps in [Alert processing rules](../azure-monitor/alerts/alerts-processing-rules.md#add-action-groups-to-all-alert-types).

+ >[!NOTE]

+ >Select the **Suppress notifications** option if you don't want to invoke notifications for alerts. For more information, see [Alert processing rules](../azure-monitor/alerts/alerts-processing-rules.md?tabs=portal#suppress-notifications-during-planned-maintenance).

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-action-rule-setting-options-08.png#lightbox)

+1. On the **Select action groups** page, select up to five action groups to attach to the alert processing rule, and then choose **Select**.

+ The new alert processing rule is added to the notification preferences of the action group.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-select-action-group-09a.png#lightbox)

+1. On the **Details** tab, assign the alert processing rule to a **Resource group** and then specify a **Name** and a **Description** (optional) for the new rule.

+ The new rule is enabled by default. If you don't want to start using the rule immediately, leave the **Enable rule upon creation** option unchecked.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-create-processing-rule-10.png#lightbox)

+1. To continue, select **Review+Create**.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-processing-rule-details-11a.png#lightbox)

+1. Review your selections and then select **Create**.

+ The **Alert processing rules** page launches, but you may not see the new rule immediately. The default view is **All** resource groups.

+1. To view your new alert processing rule, select the resource group that contains the rule.

+ [](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-processing-rules-12.png#lightbox)

+Notifications go out when an event triggers an alert for a resource within the scope of an alert processing rule.

+The action group for an alert processing rule determines who receives a notification and the type of notification to send. Notifications can be sent via email, SMS message, or both.

+It may take a few minutes to receive notifications after an alert is triggered.

+The email notification looks similar to the following example.

+[](media/azure-stack-edge-gpu-manage-device-event-alert-notifications/azure-stack-edge-sample-action-rule-email-notification-13.png#lightbox)

+| **MicroBurst exploitation toolkit used to enumerate resources in your subscriptions**<br>(ARM_MicroBurst.AzDomainInfo) | MicroBurst's Information Gathering module was run on your subscription. This tool can be used to discover resources, permissions and network structures. This was detected by analyzing the Azure Activity logs and resource management operations in your subscription | - | Low |

+| **MicroBurst exploitation toolkit used to enumerate resources in your subscriptions**<br>(ARM_MicroBurst.AzureDomainInfo) | MicroBurst's Information Gathering module was run on your subscription. This tool can be used to discover resources, permissions and network structures. This was detected by analyzing the Azure Activity logs and resource management operations in your subscription | - | Low |

+| Alert (alert type) | Description | MITRE tactics<br>([Learn more](#intentions)) | Severity |

+|||:-:||

+| **Access from a suspicious IP address to a key vault**<br>(KV_SuspiciousIPAccess) | A key vault has been successfully accessed by an IP that has been identified by Microsoft Threat Intelligence as a suspicious IP address. This may indicate that your infrastructure has been compromised. We recommend further investigation. Learn more about [Microsoft's threat intelligence capabilities](https://go.microsoft.com/fwlink/?linkid=2128684). | Credential Access | Medium |

+| **Access from a TOR exit node to a key vault**<br>(KV_TORAccess) | A key vault has been accessed from a known TOR exit node. This could be an indication that a threat actor has accessed the key vault and is using the TOR network to hide their source location. We recommend further investigations. | Credential Access | Medium |

+| **High volume of operations in a key vault**<br>(KV_OperationVolumeAnomaly) | An anomalous number of key vault operations were performed by a user, service principal, and/or a specific key vault. This anomalous activity pattern may be legitimate, but it could be an indication that a threat actor has gained access to the key vault and the secrets contained within it. We recommend further investigations. | Credential Access | Medium |

+| **Suspicious policy change and secret query in a key vault**<br>(KV_PutGetAnomaly) | A user or service principal has performed an anomalous Vault Put policy change operation followed by one or more Secret Get operations. This pattern is not normally performed by the specified user or service principal. This may be legitimate activity, but it could be an indication that a threat actor has updated the key vault policy to access previously inaccessible secrets. We recommend further investigations. | Credential Access | Medium |

+| **Suspicious secret listing and query in a key vault**<br>(KV_ListGetAnomaly) | A user or service principal has performed an anomalous Secret List operation followed by one or more Secret Get operations. This pattern is not normally performed by the specified user or service principal and is typically associated with secret dumping. This may be legitimate activity, but it could be an indication that a threat actor has gained access to the key vault and is trying to discover secrets that can be used to move laterally through your network and/or gain access to sensitive resources. We recommend further investigations. | Credential Access | Medium |

+| **Unusual access denied - Unusual user accessing key vault denied**<br>(KV_UserAccessDeniedAnomaly) | A key vault access was attempted by a user that does not normally access it, this anomalous access pattern may be legitimate activity. Though this attempt was unsuccessful, it could be an indication of a possible attempt to gain access of key vault and the secrets contained within it. | Initial Access, Discovery | Low |

+| **Unusual application accessed a key vault**<br>(KV_AppAnomaly) | A key vault has been accessed by a service principal that does not normally access it. This anomalous access pattern may be legitimate activity, but it could be an indication that a threat actor has gained access to the key vault in an attempt to access the secrets contained within it. We recommend further investigations. | Credential Access | Medium |

+| **Unusual operation pattern in a key vault**<br>(KV_OperationPatternAnomaly) | An anomalous pattern of key vault operations was performed by a user, service principal, and/or a specific key vault. This anomalous activity pattern may be legitimate, but it could be an indication that a threat actor has gained access to the key vault and the secrets contained within it. We recommend further investigations. | Credential Access | Medium |

+| **Unusual user accessed a key vault**<br>(KV_UserAnomaly) | A key vault has been accessed by a user that does not normally access it. This anomalous access pattern may be legitimate activity, but it could be an indication that a threat actor has gained access to the key vault in an attempt to access the secrets contained within it. We recommend further investigations. | Credential Access | Medium |

+| **Unusual user-application pair accessed a key vault**<br>(KV_UserAppAnomaly) | A key vault has been accessed by a user-service principal pair that does not normally access it. This anomalous access pattern may be legitimate activity, but it could be an indication that a threat actor has gained access to the key vault in an attempt to access the secrets contained within it. We recommend further investigations. | Credential Access | Medium |

+| **User accessed high volume of key vaults**<br>(KV_AccountVolumeAnomaly) | A user or service principal has accessed an anomalously high volume of key vaults. This anomalous access pattern may be legitimate activity, but it could be an indication that a threat actor has gained access to multiple key vaults in an attempt to access the secrets contained within them. We recommend further investigations. | Credential Access | Medium |

+| **Denied access from a suspicious IP to a key vault**<br>(KV_SuspiciousIPAccessDenied) | An unsuccessful key vault access has been attempted by an IP that has been identified by Microsoft Threat Intelligence as a suspicious IP address. Though this attempt was unsuccessful, it indicates that your infrastructure might have been compromised. We recommend further investigations. | Credential Access | Low |

+> You must have a [GitHub connector](quickstart-onboard-github.md) or a [DevOps connector](quickstart-onboard-devops.md), connected to your environment in order to utilize this workbook

+## March 2023

+Updates in March include:

+- [New alert in Azure Defender for Key Vault](#new-alert-in-azure-defender-for-key-vault)

+### New alert in Azure Defender for Key Vault

+Azure Defender for Key Vault has the following new alert:

+| Alert (alert type) | Description | MITRE tactics | Severity |

+|||:-:||

+| **Denied access from a suspicious IP to a key vault**<br>(KV_SuspiciousIPAccessDenied) | An unsuccessful key vault access has been attempted by an IP that has been identified by Microsoft Threat Intelligence as a suspicious IP address. Though this attempt was unsuccessful, it indicates that your infrastructure might have been compromised. We recommend further investigations. | Credential Access | Low |

+You can see a list of all of the [alerts available for Key Vault](alerts-reference.md).

+> Neousys Nuvo-5006LP is a legacy appliance, and is supported for Defender for IoT software up to the latest patch for versions [22.2.x](../release-notes.md#versions-222x). We recommend that you replace these appliances with newer certified models, such as the [YS-FIT2](ys-techsystems-ys-fit2.md) or [HPE DL20 (NHP 2LFF)](hpe-proliant-dl20-plus-smb.md).

+|**Status** | Supported up to the latest Defender for IoT software patch for versions [22.2.x](../release-notes.md#versions-222x)|

+# Get Azure recommendations to migrate your SQL Server database

+The Azure SQL Migration extension for Azure Data Studio provides both the assessment and SKU recommendations when you're trying to choose the best option to migrate your SQL Server databases to Azure SQL Managed Instance, SQL Server on Azure Virtual Machines, or Azure SQL Database. The extension has an intuitive interface to help you efficiently run the assessment and generate recommendations.

+SQL Server to Azure SQL Database |[PowerShell](https://github.com/Azure-Samples/data-migration-sql/blob/main//PowerShell/sql-server-to-sql-db.md) / [Azure CLI](https://github.com/Azure-Samples/data-migration-sql/blob/main/CLI/sql-server-to-sql-db.md)

+ - Contributor for the target Azure SQL Managed Instance, SQL Server on Azure Virtual Machines or Azure SQL Database and, Storage Account to upload your database backup files from SMB network share (*Not applicable for Azure SQL Database*).

+ - Reader role for the Azure Resource Groups containing the target Azure SQL Managed Instance, SQL Server on Azure Virtual Machines or Azure SQL Database.

+* Create a target [Azure SQL Managed Instance](/azure/azure-sql/managed-instance/create-configure-managed-instance-powershell-quickstart), [SQL Server on Azure Virtual Machine](/azure/azure-sql/virtual-machines/windows/sql-vm-create-powershell-quickstart), or [Azure SQL Database](/azure/azure-sql/database/single-database-create-quickstart)

+ > If your target is Azure SQL Database you have to migrate database schema from source to target using [SQL Server dacpac extension](/sql/azure-data-studio/extensions/sql-server-dacpac-extension) or, [SQL Database Projects extension](/sql/azure-data-studio/extensions/sql-database-project-extension) for Azure Data Studio.

+* If your target is **Azure SQL Database**, ensure that the login used to connect the source SQL Server is a member, and the `db_datareader` and login for the target SQL server is `db_owner`.

+ > If your migration target is Azure SQL Database, you don't need backups to perform this migration. The migration to Azure SQL Database is considered a logical migration involving the database's pre-creation and data movement (performed by DMS).

+SQL Server to Azure SQL Database | [Offline](./tutorial-sql-server-azure-sql-database-offline-ads.md)

+### [Azure SQL Database](#tab/azure-sql-db)

+ Title: "Custom roles for SQL Server to Azure SQL Database migrations in Azure Data Studio"

+description: Learn how to use custom roles for SQL Server to Azure SQL Database migrations in Azure Data Studio.

+# Custom roles for SQL Server to Azure SQL Database migrations in Azure Data Studio

+This article explains how to set up a custom role in Azure for SQL Server database migrations. A custom role will have only the permissions that are required to create and run an instance of Azure Database Migration Service with Azure SQL Database as a target.

+## Permissions required to migrate to Azure SQL Database

+ Title: "Tutorial: Migrate SQL Server to Azure SQL Database offline in Azure Data Studio"

+description: Learn how to migrate on-premises SQL Server to Azure SQL Database offline by using Azure Data Studio and Azure Database Migration Service.

+# Tutorial: Migrate SQL Server to Azure SQL Database offline in Azure Data Studio

+You can use Azure Database Migration Service and the Azure SQL Migration extension for Azure Data Studio to migrate databases from an on-premises instance of SQL Server to Azure SQL Database offline and with minimal downtime.

+Shared access signature (SAS) gives you granular control over the type of access you grant to the clients. Here are some of the controls you can set in a SAS:

+You can configure a SAS rule on an Event Hubs namespace, or an entity (event hub instance or Kafka Topic in an event hub). Configuring a SAS rule on a consumer group is currently not supported, but you can use rules configured on a namespace or entity to secure access to consumer group.

+In this example, the sample Event Hubs namespace (ExampleNamespace) has two entities: eh1 and Kafka topic1. The authorization rules are defined both at the entity level and also at the namespace level.

+The manageRuleNS, sendRuleNS, and listenRuleNS authorization rules apply to both eh1 and t1. The listenRule-eh and sendRule-eh authorization rules apply only to eh1 and sendRuleT authorization rule applies only to topic1.

+The signature-string is the SHA-256 hash computed over the resource URI (scope as described in the previous section) and the string representation of the token expiry instant, separated by CRLF. The hash computation looks similar to the following pseudo code and returns a 256-bit/32-byte hash value.

+The SAS rule used for signing must be configured on the entity specified by this URI, or by one of its hierarchical parents. For example, `http://contoso.servicebus.windows.net/eh1` or `http://contoso.servicebus.windows.net` in the previous example.

+As shown in the following image, in the namespace overview section, select **Local Authentication**.

+And then select **Disabled** option and select **Ok** as shown below.

+Every time you publish or consume events from an event hub, your client is trying to access Event Hubs resources. Every request to a secure resource must be authorized so that the service can ensure that the client has the required permissions to publish or consume the data.

+Azure Active Directory (Azure AD) integration with Event Hubs resources provides Azure role-based access control (Azure RBAC) for fine-grained control over a client's access to resources. You can use Azure RBAC to grant permissions to security principal, which may be a user, a group, or an application service principal. Azure AD authenticates the security principal and returns an OAuth 2.0 token. The token can be used to authorize a request to access an Event Hubs resource.

+- [Authenticate requests to Azure Event Hubs using Azure AD](authenticate-application.md)

+- [Authorize access to Event Hubs resources using Azure AD](authorize-access-azure-active-directory.md).

+By default, all Event Hubs resources are secured, and are available only to the account owner. Although you can use any of the authorization strategies outlined above to grant clients access to Event Hubs resources. Microsoft recommends using Azure AD when possible for maximum security and ease of use.

+A shared access signature (SAS) provides you with a way to grant limited access to resources in your Event Hubs namespace. SAS guards access to Event Hubs resources based on authorization rules. These rules are configured either on a namespace, or an event hub. This article provides an overview of the SAS model, and reviews SAS best practices.

+> [!NOTE]

+> This article covers authorizing access to Event Hubs resources using SAS. To learn about **authenticating** access to Event Hubs resources using SAS, see [Authenticate with SAS](authorize-access-shared-access-signature.md).

+SAS is a claim-based authorization mechanism using simple tokens. When you use SAS, keys are never passed on the wire. Keys are used to cryptographically sign information that can later be verified by the service. SAS can be used similar to a username and password scheme where the client is in immediate possession of an authorization rule name and a matching key. SAS can be used similar to a federated security model, where the client receives a time-limited and signed access token from a security token service without ever coming into possession of the signing key.

+> Azure Event Hubs also supports authorizing to Event Hubs resources using Azure Active Directory (Azure AD). Authorizing users or applications using OAuth 2.0 token returned by Azure AD provides superior security and ease of use over shared access signatures (SAS). With Azure AD, there is no need to store the tokens in your code and risk potential security vulnerabilities.

+Each Event Hubs namespace and each Event Hubs entity (an event hub or a Kafka topic) has a shared access authorization policy made up of rules. The policy at the namespace level applies to all entities inside the namespace, irrespective of their individual policy configuration.

+- **Listen** ΓÇô Gives the right to listen or receive messages from the entity

+- **Manage** ΓÇô Gives the right to manage the topology of the namespace, including creation and deletion of entities. The **Manage** right includes the **Send** and **Listen** rights.

+- **Have clients automatically renew the SAS if necessary**: Clients should renew the SAS well before expiration, to allow time for retries if the service providing the SAS is unavailable. If your SAS is meant to be used for a small number of immediate, short-lived operations that are expected to be completed within the expiration period, then it may be unnecessary as the SAS isn't expected to be renewed. However, if you have client that is routinely making requests via SAS, then the possibility of expiration comes into play. The key consideration is to balance the need for the SAS to be short-lived (as previously stated) with the need to ensure that client is requesting renewal early enough (to avoid disruption due to the SAS expiring prior to a successful renewal).

+- **Be careful with the SAS start time**: If you set the start time for SAS to **now**, then due to clock skew (differences in current time according to different machines), failures may be observed intermittently for the first few minutes. In general, set the start time to be at least 15 minutes in the past. Or, donΓÇÖt set it at all, which will make it valid immediately in all cases. The same generally applies to the expiry time as well. Remember that you may observe up to 15 minutes of clock skew in either direction on any request.

+- **Always use HTTPs**: Always use Https to create or distribute a SAS. If a SAS is passed over HTTP and intercepted, an attacker performing a man-in-the-middle attack is able to read the SAS and then use it just as the intended user could have, potentially compromising sensitive data or allowing for data corruption by the malicious user.

+Share access signatures are useful for providing limited permissions to Event Hubs resources to your clients. They're vital part of the security model for any application using Azure Event Hubs. If you follow the best practices listed in this article, you can use SAS to provide greater flexibility of access to your resources, without compromising the security of your application.

+ Title: Introduction to Apache Kafka in Event Hubs on Azure Cloud

+description: Learn what Apache Kafka in the Event Hubs service on Azure Cloud is and how to use it to stream data from Apache Kafka applications without setting up a Kafka cluster on your own.

+If an Event Hubs namespace is created in a region with [availability zones](../availability-zones/az-overview.md), the outage risk is further spread across three physically separated facilities, and the service has enough capacity reserves to instantly cope up with the complete, catastrophic loss of the entire facility. For more information, see [Azure Event Hubs - Geo-disaster recovery](event-hubs-geo-dr.md).

+### If I have multiple Virtual Networks (VNets) connected to the same ExpressRoute circuit, can I use ExpressRoute for VNet-to-VNet connectivity?

+VNet-to-VNet connectivity over ExpressRoute isn't recommended. To achieve this, configure [Virtual Network Peering](../virtual-network/virtual-network-peering-overview.md?msclkid=b64a7b6ac19e11eca60d5e3e5d0764f5).

+No.

+ExpressRoute supports the connection of multiple VNets to a single ExpressRoute circuit for better utilization of the higher-speed connections. A single ExpressRoute circuit can be shared among multiple Azure subscriptions owned by the same customer.

+In a connect-through configuration, you will be responsible for all of the networking underpinnings to connect your customer's datacenter resources to the subscriptions hosted in Azure. Each of your customers that want to use Azure capabilities will need their own ExpressRoute connection, which will be managed by you. You will use the same methods the customer would use to procure the ExpressRoute circuit. You will follow the same steps outlined in the article [ExpressRoute workflows](expressroute-workflows.md) for circuit provisioning and circuit states. You will then configure the Border Gateway Protocol (BGP) routes to control the traffic flowing between the on-premises network and Azure VNet.

+In a connect-to configuration, your customer already has an existing connection to Azure or will initiate a connection to the internet service provider linking ExpressRoute from their own datacenter directly to Azure, instead of your datacenter. To begin the provisioning process, your customer will follow the steps as described in the Connect-Through model, above. Once the circuit has been established, your customer will need to configure the on-premises routers to be able to access both your network and Azure VNets.

+Creating Azure Virtual Networks also creates a default routing table for the VNet to direct traffic to/from the subnets of the VNet. If the default route table is insufficient for the solution, custom routes can be created to route outgoing traffic to custom appliances or to block routes to specific subnets or external networks.

+Depending on which model is in use, Connect-To or Connect-Through, your customer defines the security policies in their VNet or provides the security policy requirements to the CSP to define to their VNets. The following security criteria can be defined:

+1. **Customer Isolation** ΓÇö The Azure platform provides customer isolation by storing Customer ID and VNet info in a secure database, which is used to encapsulate each customerΓÇÖs traffic in a GRE tunnel.

+2. **Network Security Group (NSG)** rules are for defining allowed traffic into and out of the subnets within VNets in Azure. By default, the NSG contains Block rules to block traffic from the Internet to the VNet and Allow rules for traffic within a VNet. For more information about Network Security Groups, look [here](https://azure.microsoft.com/blog/network-security-groups/).

+[Microsoft Cloud Solution Provider resources](https://partner.microsoft.com/solutions/cloud-reseller-resources).

+|TLSi intermediate CA certification expiration|In some unique cases, your intermediate CA certificate can be expired two months ahead of its original expiration date.|Renew your intermediate CA certification two months ahead of time. <br>A fix is being investigated.|

+> [!Note]

+> Azure Health Data services is the evolved version of Azure API for FHIR enabling customers to manage FHIR, DICOM, and MedTech services with integrations into other Azure Services. To learn about Azure Health Data Services [click here](https://azure.microsoft.com/products/health-data-services/).

+FHIR&#174; is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

+> [!Note]

+> Azure Health Data services is the evolved version of Azure API for FHIR enabling customers to manage FHIR, DICOM, and MedTech services with integrations into other Azure Services. To learn about Azure Health Data Services [click here](https://azure.microsoft.com/products/health-data-services/).

+| Java | [SetRetryPolicy](/jav) |

+| Java|[Maven](https://mvnrepository.com/artifact/com.microsoft.azure.sdk.iot.provisioning/provisioning-device-client)|[GitHub](https://github.com/Azure/azure-iot-sdk-jav?pivots=programming-language-java&tabs=windows)|[Reference](/java/api/com.microsoft.azure.sdk.iot.provisioning.device) |

+| Java|[Maven](https://mvnrepository.com/artifact/com.microsoft.azure.sdk.iot.provisioning/provisioning-service-client)|[GitHub](https://github.com/Azure/azure-iot-sdk-jav?pivots=programming-language-java&tabs=symmetrickey)|[Reference](/java/api/com.microsoft.azure.sdk.iot.provisioning.service) |

+- [Java SDK sample](https://github.com/Azure/azure-iot-service-sdk-java/tree/main/service/iot-service-samples/role-based-authorization-sample)

+4. Add the following dependency to the **dependencies** node. This dependency configures a NOP for the Apache [SLF4J](https://www.slf4j.org/) logging facade, which is used by the device client SDK to implement logging. This configuration is optional, but, if you omit it, you may see a warning in the console when you run the app. For more information about logging in the device client SDK, see [Logging](https://github.com/Azure/azure-iot-sdk-java/tree/main/iothub/device/iot-device-samples#logging) in the *Samples for the Azure IoT device SDK for Java* readme file.

+](https://github.com/Azure/azure-iot-sdk-java/tree/main/iothub/device/iot-device-samples/file-upload-sample/src/main/java/samples/com/microsoft/azure/sdk/iot) in GitHub.

+* [Simulating a device with IoT Edge](../iot-edge/quickstart-linux.md)

+4. Add the following dependency to the **dependencies** node. This dependency configures a NOP for the Apache [SLF4J](https://www.slf4j.org/) logging facade, which is used by the device client SDK to implement logging. This configuration is optional, but if you omit it, you may see a warning in the console when you run the app. For more information about logging in the device client SDK, see [Logging](https://github.com/Azure/azure-iot-sdk-jav#logging)in the *Samples for the Azure IoT device SDK for Java* readme file.

+To continue exploring IoT Hub and device management patterns, update an image in [Device Update for Azure IoT Hub tutorial using the Raspberry Pi 3 B+ Reference Image](../iot-hub-device-update/device-update-raspberry-pi.md).

+1. Add the following dependency to the **dependencies** node. This dependency configures a NOP for the Apache [SLF4J](https://www.slf4j.org/) logging facade, which is used by the device client SDK to implement logging. This configuration is optional, but, if you omit it, you may see a warning in the console when you run the app. For more information about logging in the device client SDK, see [Logging](https://github.com/Azure/azure-iot-sdk-jav#logging) in the *Samples for the Azure IoT device SDK for Java* readme file.

+* Control devices interactively, such as turning on a fan from a user-controlled app, see [Quickstart: Control a device connected to an IoT hub](./quickstart-control-device.md?pivots=programming-language-java)

+| [Java](https://github.com/Azure/azure-iot-sdk-java/blob/main/iothub/device/iot-device-samples/send-receive-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/SendReceive.java) |[IotHubClientProtocol](/java/api/com.microsoft.azure.sdk.iot.device.iothubclientprotocol).MQTT | IotHubClientProtocol.MQTT_WS |

+|Java | 230 seconds | [Yes](https://github.com/Azure/azure-iot-sdk-java/blob/main/iothub/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/ClientOptions.java#L64) |

+* [Quickstart: Deploy your first IoT Edge module to a virtual Linux device](../iot-edge/quickstart-linux.md)

+- In production, we recommend you get your X.509 CA certificates from a public root certificate authority. Purchasing a CA certificate has the benefit of the root CA acting as a trusted third party to vouch for the legitimacy of your devices. If you already have an X.509 CA certificate, and you know how to create and sign device certificates into a certificate chain, follow the instructions in [Tutorial: Upload and verify a CA certificate to IoT Hub](tutorial-x509-prove-possession.md) to upload your CA certificate to your IoT hub. Then, follow the instructions in [Tutorial: Test certificate authentication](tutorial-x509-test-certificate.md) to authenticate a device with your IoT hub.

+If you have a root CA certificate or subordinate CA certificate and you want to upload it to your IoT hub, you must verify that you own that certificate. For more information, see [Tutorial: Upload and verify a CA certificate to IoT Hub](tutorial-x509-prove-possession.md).

+ Title: Migrating from physical labs to the cloud

+description: Learn about the benefits and considerations for migrating from physical labs to Azure Lab Services. Understand how to configure your labs to optimize costs.

+# Considerations for migrating from physical labs to Azure Lab Services

+Azure Lab Services enables you to provide lab environments that users can access from anywhere, any time of the day. When you migrate from physical labs to Azure Lab Services, you should reassess your lab structure to minimize costs and optimize the experience for lab creators and users. In this article, you learn about the considerations and benefits of migrating from physical labs to Azure Lab Services.

+## Considerations for moving to Azure Lab Services

+When you migrate physical labs to Azure Lab Services, you should consider the following aspects:

+- What is the lab structure? Are labs used for different purposes (shared lab), such as multiple classes, or are they dedicated (single-purpose lab)?

+- What are the software requirements for the lab?

+- What are the lab hardware requirements? A shared lab has to accommodate the needs for all usage scenarios and therefore has higher requirements.

+To optimally benefit, you need to reassess the lab and image contents as a whole. It's not recommended to reuse the same lab image from your physical lab as-is.

+## Lab structure

+Usually a physical lab is shared by students from multiple classes. As a result, all of the classesΓÇÖ software applications are installed together at once on each lab computer. When a class uses the lab, students only run a subset of the applications that are relevant to their class.

+This type of physical computer lab often leads to increased hardware requirements:

+- A large disk size may be required to install the combined set of applications that are needed by the classes that are sharing the lab.

+- Some applications require more processing power compared to others, or require specialized processors, such as a GPU. By installing multiple applications on the same lab computer, each computer must have sufficient hardware to run the most compute-intensive applications.

+This level of hardware is wasted for classes that only use the lab to run applications that require less memory, compute power, or disk space.

+Azure Lab Services is designed to use hardware more efficiently, so that you only pay for what your users actually need and use. With Azure Lab Services, labs are structured to be more granular:

+- One lab is created for each class (or session of a class).

+- On the labΓÇÖs image, only the software applications that are needed by that specific class are installed.

+This structure helps to identify the optimal VM size for each class based on the specific workload, and helps to reduce the disk size requirements (Azure Lab ServicesΓÇÖ currently supports a disk size of 127 GB).

+When you use Azure Lab Services, it's recommended that you use single-purpose labs.

+Learn more about [how to structure labs](./administrator-guide.md#lab) in the Azure Lab Services administrator guide.

+## Benefits

+There are multiple benefits of using single-purpose labs (for example, one class per lab):

+- Optimize costs by selecting the right VM size for each lab. See the below [example use case and cost analysis](#example-use-case).

+- Lab VMs only contain the software that is needed for their purpose. This simplifies the set-up and maintenance of labs by lab creators, and provides more clarity for lab users.

+- Access to each individual lab is controlled. Lab users are only granted access to labs and software they need. Learn how to [add and manage lab users](./how-to-configure-student-usage.md).

+- Further optimize costs by taking advantage of the following features:

+ - [Schedules](./how-to-create-schedules.md) are used to automatically start and stop all VMs within a lab according to each classΓÇÖs schedule.

+ - [Quotas](./how-to-configure-student-usage.md#set-quotas-for-users) allow you to control the amount of time that each classΓÇÖs students can access VMs outside of their scheduled hours.

+## Example use case

+Consider the following physical lab configuration, where the lab is shared by multiple classes:

+- An engineering class that uses [SolidWorks](./class-type-solidworks.md) with 100 students enrolled.

+- A math class that uses [MATLAB](./class-type-matlab.md) that also has 100 students enrolled.

+Since our physical lab is shared by these two classes, each lab computer has both SolidWorks and MATLAB installed, along with various other common applications, such as Word, or Excel. Also, itΓÇÖs important to note that SolidWorks is more compute-intensive since it typically requires a GPU.

+To move this physical lab to Azure Lab

+- Create two labs: one for the engineering class and another for the math class.

+- Create two VM images: one with SolidWorks installed and another with MATLAB.

+Because SolidWorks requires a GPU, the engineering lab uses the **Small GPU (Visualization)** VM size. The lab for math class only requires a **Medium** VM size.

+The following image shows how the lab structure changes when moving this physical lab to Azure Lab Services.

+### Cost analysis

+In this example, the cost per usage hour for the two VM sizes is substantially different:

+- Small GPU (Visualization): provides high compute-power and as a result, the cost is 160 lab units per hour.

+- Medium: provides less compute power but is suitable for many types of classes. The cost is only 55 lab units per hour.

+By using separate labs and assigning the smallest appropriate VM size for each lab, you can save on the total cost for running the labs.

+Consider a usage scenario where student uses their VM for a total of 10 hours:

+- A single lab using the Small GPU (Visualization) size that is shared by students from both the engineering and math classes is estimated to have the following usage:

+ 10 hours * 200 students * 160 lab units/hour = 320000 lab units

+- Separate labs that use the Small GPU (Visualization) size for engineering and Medium size for math are estimated to have the following usage:

+ - Engineering class lab: 10 hours * 100 students * 160 lab units/hour = 160000

+ - Math class lab: 10 hours * 100 students * 55 lab units/hour = 55000

+ The total of both the engineering and math labs is 215000.

+By using a more granular lab structure, the total savings for running the labs are 33%. Also, keep in mind that you only pay for the number of hours that your students actually use their VMs. If students use their VMs less, the actual costs are lower.

+>[!IMPORTANT]

+> The cost estimate is for example purposes only. For current details on pricing, see [Azure Lab Services Pricing](https://azure.microsoft.com/pricing/details/lab-services/).

+## Prepare for migrating to Azure Lab Services

+When you start using Azure Lab Services, IT and faculty should coordinate early in the planning process to:

+- Identify the specific software applications that each class requires. Learn more about [lab software requirements](./setup-guide.md#what-software-requirements-does-the-class-have).

+- Understand the workloads that students perform using the lab.

+This information is needed to choose the appropriate VM size when you create a lab and to set up the image on the template VM. Learn more about [VM sizing in Azure Lab Services](./administrator-guide.md#vm-sizing).

+To ensure that you choose the appropriate VM size, we recommend starting with the minimum VM size that meets the hardware requirements for your applications. Then, have faculty connect to a lab VM to validate common workloads that students perform to ensure the performance and experience is sufficient. ItΓÇÖs helpful to refer to the [Class Types](./class-types.md), which show real-world examples of how to set up applications for classes along with the recommended VM size.

+Also, [Azure Compute Gallery](./how-to-use-shared-image-gallery.md) is useful for creating and storing custom images. A compute gallery enables you to create an image once and reuse it to create multiple labs.

+## Conclusion

+Azure Lab Services provides many benefits for optimizing the cost of running your labs, simplifying set-up and maintenance, and having fine-grained access control. To optimally benefit, it's recommended to structure your labs in Azure Lab Services to have a single purpose. For example, create a separate lab for each classroom training.

+## Next steps

+- Get started by [creating a lab plan](./quick-create-lab-plan-portal.md).

+- Understand [cost estimation and analysis](./cost-management-guide.md).

+- Understand the [lab requirements for a lab](./setup-guide.md#understand-the-lab-requirements-of-your-class).

+- Learn more about [VM sizing in Azure Lab Services](./administrator-guide.md#vm-sizing).

+### Create the Azure load testing resource

+The Azure load testing resource is a top-level resource for your load-testing activities. This resource provides a centralized place to view and manage load tests, test results, and related artifacts.

+If you already have a load testing resource, skip this section and continue to [Create a load test](#create-a-load-test).

+If you don't yet have an Azure load testing resource, create one now:

+### Create a load test

+Next, you create a load test in your load testing resource for the sample app. You create the load test by using an existing JMeter script in the sample app repository.

+1. Go to your load testing resource, and select **Create** on the **Overview** page.

+* You can create a function directly from inside a Consumption logic app workflow, but not from a Standard logic app workflow. However, you can create functions in other ways. For more information, see [Create functions from inside logic app workflows](#create-function-designer).

+Workspaces are places to collaborate with colleagues and group related work. For example, experiments, jobs, datasets, components, and inference endpoints.

+We recommend creating a workspace _per project_. While a workspace can be used for multiple projects, limiting it to one project per workspace allows for cost reporting accrued to a project level. It also allows you to manage configurations like datastores in the scope of each project.

+## Working with a workspace

+Machine learning tasks read and/or write artifacts to your workspace.

+ To use an existing Azure Storage account, it can't be of type BlobStorage or a premium account (Premium_LRS and Premium_GRS). It also can't ha