+To improve your production environment performance and better user experience, it's important to configure your policy to ignore messages that are unimportant. Use the following configuration in production environments and no logs will be sent to your application insights.

+ Title: Use additional context in Microsoft Authenticator notifications (Preview) - Azure Active Directory

+# How to use additional context in Microsoft Authenticator notifications (Preview) - Authentication Methods Policy

+>[!NOTE]

+>In Graph Explorer, ensure you've consented to the **Policy.Read.All** and **Policy.ReadWrite.AuthenticationMethod** permissions.

+>For passwordless users, enabling or disabling number matching has no impact because it's already part of the passwordless experience.

+>For passwordless users, enabling or disabling number matching has no impact because it's already part of the passwordless experience.

+> [!NOTE]

+> If you've met the publisher verification requirements and are still having issues, try using an existing or newly created user with similar permissions.

+| Routable | Managed | From 1803 release | Generally available, Azure AD SSPR on Windows lock screen isn't supported in environments where the on-premises UPN is different from the Azure AD UPN. The on-premises UPN must be synced to the `onPremisesUserPrincipalName` attribute in Azure AD |

+When an external user accesses resources in your organization, the authentication flow is determined by the collaboration method (B2B collaboration or B2B direct connect), user's identity provider (an external Azure AD tenant, social identity provider, etc.), Conditional Access policies, and the [cross-tenant access settings](cross-tenant-access-overview.md) configured both in the user's home tenant and the tenant hosting resources.

+The following diagram illustrates the authentication flow when an Azure AD organization shares resources with users from other Azure AD organizations. This diagram shows how cross-tenant access settings work with Conditional Access policies, such as multi-factor authentication (MFA), to determine if the user can access resources. This flow applies to both B2B collaboration and B2B direct connect, except as noted in step 6.

+|**6** | When no trust settings are configured and MFA is required, B2B collaboration users are prompted for MFA, which they need to satisfy in the resource tenant. Access is blocked for B2B direct connect users. If device compliance is required but can't be evaluated, access is blocked for both B2B collaboration and B2B direct connect users. |

+Organizations can enforce Conditional Access policies for external B2B collaboration and B2B direct connect users in the same way that they're enabled for full-time employees and members of the organization. This section describes important considerations for applying Conditional Access to users outside of your organization.

+ Title: B2B direct connect overview - Azure AD

+description: Azure Active Directory B2B direct connect lets users from other Azure AD tenants seamlessly sign in to your shared resources via Teams shared channels. There's no need for a guest user object in your Azure AD directory.

+# B2B direct connect overview

+Azure Active Directory (Azure AD) B2B direct connect is a feature of External Identities that lets you set up a mutual trust relationship with another Azure AD organization for seamless collaboration. With B2B direct connect, users from both organizations can work together using their home credentials and B2B direct connect-enabled apps, without having to be added to each otherΓÇÖs organizations as guests. Use B2B direct connect to share resources with external Azure AD organizations. Or use it to share resources across multiple Azure AD tenants within your own organization.

+

+B2B direct connect requires a mutual trust relationship between two Azure AD organizations to allow access to each other's resources. Both the resource organization and the external organization need to mutually enable B2B direct connect in their cross-tenant access settings. When the trust is established, the B2B direct connect user has single sign-on access to resources outside their organization using credentials from their home Azure AD organization.

+Currently, B2B direct connect capabilities work with Teams Connect shared channels. This means that users in one organization can create a shared channel in Teams and invite an external B2B direct connect user to it. Then from within Teams, the B2B direct connect user can seamlessly access the shared channel in their home tenant Teams instance, without having to manually sign in to the organization hosting the shared channel.

+For licensing and pricing information related to B2B direct connect users, refer to [Azure Active Directory pricing](https://azure.microsoft.com/pricing/details/active-directory/).

+## Managing cross-tenant access for B2B direct connect

+Azure AD organizations can manage their trust relationships with other Azure AD organizations by defining inbound and outbound [cross-tenant access settings](cross-tenant-access-settings-b2b-collaboration.md). Cross-tenant access settings give you granular control over how other organizations collaborate with you (inbound access) and how your users collaborate with other organizations (outbound access).

+- **Inbound access settings** control whether users from external organizations can access resources in your organization. You can apply these settings to everyone, or you can specify individual users, groups, and applications.

+- **Outbound access settings** control whether your users can access resources in an external organization. You can apply these settings to everyone, or you can specify individual users, groups, and applications.

+- **Tenant restrictions** determine how your users can access an external organization when theyΓÇÖre using your devices and network, but theyΓÇÖre signed in using an account that was issued to them by the external organization.

+- **Trust settings** determine whether your Conditional Access policies will trust the multi-factor authentication (MFA), compliant device, and hybrid Azure AD joined device claims from an external organization when their users access your resources.

+> [!IMPORTANT]

+> B2B direct connect is possible only when both organizations allow access to and from the other organization. For example, Contoso can allow inbound B2B direct connect from Fabrikam, but sharing isn't possible until Fabrikam also enables outbound B2B direct connect with Contoso. Therefore, youΓÇÖll need to coordinate with the external organizationΓÇÖs admin to make sure their cross-tenant access settings allow sharing with you. This mutual agreement is important because B2B direct connect enables limited sharing of data for the users you enable for B2B direct connect.

+### Default settings

+The default cross-tenant access settings apply to all external Azure AD organizations, except organizations for which you've configured individual settings. Initially, Azure AD blocks all inbound and outbound B2B direct connect capabilities by default for all external Azure AD tenants. You can change these default settings, but typically you'll leave them as-is and enable B2B direct connect access with individual organizations.

+### Organization-specific settings

+You can configure organization-specific settings by adding the organization and modifying the cross-tenant access settings. These settings will then take precedence over the default settings for this organization.

+### Example 1: Allow B2B direct connect with Fabrikam and block all others

+In this example, Contoso wants to block B2B direct connect with all external organizations by default, but allow B2B direct connect for all users, groups, and apps in Fabrikam.

+

+Contoso sets the following **Default settings** for cross-tenant access:

+- Block inbound access to B2B direct connect for all external users and groups.

+- Block outbound access to B2B direct connect for all Contoso users and groups.

+Then Contoso adds the Fabrikam organization and configures the following **Organizational settings** for Fabrikam:

+- Allow inbound access to B2B direct connect for all Fabrikam users and groups.

+- Allow inbound access to all internal Contoso applications by Fabrikam B2B direct connect users.

+- Allow all Contoso users and groups to have outbound access to Fabrikam using B2B direct connect.

+- Allow Contoso B2B direct connect users to have outbound access to all Fabrikam applications.

+For this scenario to work, Fabrikam also needs to allow B2B direct connect with Contoso by configuring these same cross-tenant access settings for Contoso and for their own users and applications. Contoso users who manage Teams shared channels in your organizations will be able to add Fabrikam users by searching for their full Fabrikam email addresses.

+### Example 2: Enable B2B direct connect with Fabrikam's Marketing group only

+Starting from the example above, Contoso could also choose to allow only the Fabrikam Marketing group to collaborate with Contoso's users through B2B direct connect. In this case, Contoso will need to obtain the Marketing group's object ID from Fabrikam. Then, instead of allowing inbound access to all Fabrikam's users, they'll configure their Fabrikam-specific access settings as follows:

+- Allow inbound access to B2B direct connect for Fabrikam's Marketing group only. Contoso specifies Fabrikam's Marketing group object ID in the allowed users and groups list.

+- Allow inbound access to all internal Contoso applications by Fabrikam B2B direct connect users.

+- Allow all Contoso users and groups to have outbound access to Fabrikam using B2B direct connect.

+- Allow Contoso B2B direct connect users to have outbound access to all Fabrikam applications.

+Fabrikam will also need to configure their outbound cross-tenant access settings so that their Marketing group is allowed to collaborate with Contoso through B2B direct connect. Contoso users who manage Teams shared channels in your organizations will be able to add only Fabrikam Marketing group users by searching for their full Fabrikam email addresses.

+## Authentication

+In a B2B direct connect scenario, authentication involves a user from an Azure AD organization (the user's home tenant) attempting to sign in to a file or app in another Azure AD organization (the resource tenant). The user signs in with Azure AD credentials from their home tenant. The sign-in attempt is evaluated against cross-tenant access settings in both the user's home tenant and the resource tenant. If all access requirements are met, a token is issued to the user that allows the user to access the resource. This token is valid for 1 hour.

+For details about how authentication works in a cross-tenant scenario with Conditional Access policies, see [Authentication and Conditional Access in cross-tenant scenarios](authentication-conditional-access.md).

+## Multi-factor authentication (MFA)

+If you want to allow B2B direct connect with an external organization and your Conditional Access policies require MFA, you ***must*** configure your inbound [trust settings](cross-tenant-access-settings-b2b-direct-connect.md#to-change-inbound-trust-settings-for-mfa-and-device-state) so that your Conditional Access policies will accept MFA claims from the external organization. This configuration ensures that B2B direct connect users from the external organization are compliant with your Conditional Access policies, and it provides a more seamless user experience.

+For example, say Contoso (the resource tenant) trusts MFA claims from Fabrikam. Contoso has a Conditional Access policy requiring MFA. This policy is scoped to all guests, external users, and SharePoint Online. As a prerequisite for B2B direct connect, Contoso must configure trust settings in their cross-tenant access settings to accept MFA claims from Fabrikam. When a Fabrikam user accesses a B2B direct connect-enabled app (for example, a Teams Connect shared channel), the user is subject to the MFA requirement enforced by Contoso:

+- If the Fabrikam user has already performed MFA in their home tenant, theyΓÇÖll be able to access the resource within the shared channel.

+- If the Fabrikam user hasnΓÇÖt completed MFA, theyΓÇÖll be blocked from accessing the resource.

+For information about Conditional Access and Teams, see [Overview of security and compliance](/microsoftteams/security-compliance-overview) in the Microsoft Teams documentation.

+## B2B direct connect user experience

+Currently, B2B direct connect enables the Teams Connect shared channels feature. B2B direct connect users can access an external organization's Teams shared channel without having to switch tenants or sign in with a different account. The B2B direct connect userΓÇÖs access is determined by the shared channelΓÇÖs policies.

+In the resource organization, the Teams shared channel owner can search within Teams for users from an external organization and add them to the shared channel. After they're added, the B2B direct connect users can access the shared channel from within their home instance of Teams, where they collaborate using features such as chat, calls, file-sharing, and app-sharing. For details, see [Overview of teams and channels in Microsoft Teams](/microsoftteams/teams-channels-overview).For details about the resources, files, and applications, that are available to the B2B direct connect user via the Teams shared channel, refer to [Chat, teams, channels, & apps in Microsoft Teams](/microsoftteams/deploy-chat-teams-channels-microsoft-teams-landing-page).

+## B2B direct connect vs. B2B collaboration

+B2B collaboration and B2B direct connect are two different approaches to sharing with users outside of your organization. You'll find a [feature-to-feature comparison](external-identities-overview.md#comparing-external-identities-feature-sets) in the External Identities overview. Here, we'll discuss some key differences in how users are managed and how they access resources.

+### User access and management

+B2B direct connect users collaborate via a mutual connection between two organizations, whereas B2B collaboration users are invited to an organization and managed via a user object.

+- B2B direct connect offers way to collaborate with users from another Azure AD organization through a mutual, two-way connection configured by admins from both organizations. Users have single sign-on access to B2B direct connect-enabled Microsoft applications. Currently, B2B direct connect support Teams Connect shared channels.

+- B2B collaboration lets you invite external partners to access your Microsoft, SaaS, or custom-developed apps. B2B collaboration is especially useful when the external partner doesn't use Azure AD or it's not practical or possible to set up B2B direct connect. B2B collaboration allows external users to sign in using their preferred identity, including their Azure AD account, consumer Microsoft account, or a social identity you enable such as Google. With B2B collaboration, you can let external users sign in to your Microsoft applications, SaaS apps, custom-developed apps, and so on.

+### Using Teams with B2B direct connect vs. B2B collaboration

+Within the context of Teams, there are differences in how resources can be shared depending on whether youΓÇÖre collaborating with someone using B2B direct connect or B2B collaboration.

+- With B2B direct connect, you add the external user to a shared channel within a team. This user can access the resources within the shared channel, but they donΓÇÖt have access to the entire team or any other resources outside the shared channel. For example, they donΓÇÖt have access to the Azure AD admin portal. They do, however, have access to My apps portal. B2B direct connect users donΓÇÖt have a presence in your Azure AD organization, so these users are managed in the Teams client by the shared channel owner. For details, see the [Assign team owners and members in Microsoft Teams](/microsoftteams/assign-roles-permissions).

+- With B2B collaboration, you can invite the guest user to a team. The B2B collaboration guest user signs into the resource tenant using the email address that was used to invite them. Their access is determined by the permissions assigned to guest users in the resource tenant. Guest users canΓÇÖt see or participate in any shared channels in the team.

+For more information about differences between B2B collaboration and B2B direct connect in Teams, see [Guest access in Microsoft Teams](/microsoftteams/guest-access).

+## Monitoring and auditing

+Reporting for monitoring and auditing B2B direct connect activity is available in both the Azure portal and the Microsoft Teams admin center.

+### Azure AD monitoring and audit logs

+Azure AD includes information about cross-tenant access and B2B direct connect in the organization's Audit logs and Sign-in logs. These logs can be viewed in the Azure portal under **Monitoring**.

+- **Azure AD audit logs**: Azure AD Audit logs show when inbound and outbound policies are created, updated, or deleted.

+ 

+- **Azure AD sign-in logs** Azure AD sign-in logs are available in both the home organization and the resource organization. Once B2B direct connect is enabled, sign-in logs will begin including user object IDs for B2B direct connect users from other tenants. The information reported in each organization varies, for example:

+ - In both organizations, B2B direct connect sign-ins are labeled with a cross-tenant access type of B2B direct connect. A sign-in event is recorded when a B2B direct connect user first accesses a resource organization, and again when a refresh token is issued for the user. Users can access their own sign-in logs. Admins can view sign-ins for their entire organization to see how B2B direct connect users are accessing resources in their tenant.

+ - In the home organization, the logs include client application information.

+ - In the resource organization, the logs include conditionalAccessPolicies in the Conditional Access tab.

+ [  ](media/b2b-direct-connect-overview/sign-in-logs.png#lightbox)

+- **Azure AD access reviews**: With Azure Active Directory (Azure AD) access reviews, a tenant admin can ensure that external guest users donΓÇÖt have access to your apps and resources longer than is necessary by configuring a one-time or recurring access review of the external users. [Learn more about access reviews](../governance/access-reviews-overview.md).

+### Microsoft Teams monitoring and audit logs

+The Microsoft Teams admin center displays reporting for shared channels, including external B2B direct connect members for each team.

+- **Teams audit logs**: Teams supports the following auditing events in the tenant that hosts the shared channel: Shared channel lifecycle (Create/Delete channel), In-tenant/Cross-tenant Member lifecycle (Add/remove/Promote/Demote member). These audit logs are available in the resource tenant so that admins can determine who has access to the Teams shared channel. There are no audit logs in the external userΓÇÖs home tenant related to their activity in an external shared channel.

+- **Teams access reviews**: Access reviews of Groups that are Teams can now detect B2B direct connect users who are using Teams shared channels. When creating an access review, you can scope the review to all internal users, guest users, and external B2B direct connect users who have been added directly to a shared channel. The reviewer is then presented with users who have direct access to the shared channel.

+- **Current limitations**: An access review can detect internal users and external B2B direct connect users, but not other teams, that have been added to a shared channel. To view and remove teams that have been added to a shared channel, the shared channel owner can manage membership from within Teams.

+For more information about Microsoft Teams audit logs, see the [Microsoft Teams auditing documentation](/microsoftteams/audit-log-events).

+## Privacy and data handling

+B2B direct connect lets your users and groups access apps and resources that are hosted by an external organization. To establish a connection, an admin from the external organization must also enable B2B direct connect.

+By enabling B2B connect with an external organization, you're allowing the external organizations that you have enabled outbound settings with to access limited contact data about your users. Microsoft shares this data with those organizations to help them send a request to connect with your users. Data collected by external organizations, including limited contact data, is subject to the privacy policies and practices of those organizations.

+### Outbound access

+When B2B direct connect is enabled with an external organization, users in the external organization will be able to search for your users by full email address. Matching search results will return limited data about your users, including first name and last name. Your users will need to consent to the external organizationΓÇÖs privacy policies before more of their data is shared. We recommend you review the privacy information that will be provided by the organization and presented to your users.

+### Inbound access

+We strongly recommend you add both your global privacy contact and your organization's privacy statement so your internal employees and external guests can review your policies. Follow the steps to [add your organization's privacy info](../fundamentals/active-directory-properties-area.md).

+### Restricting access to users and groups

+You might want to consider using cross-tenant access settings to restrict B2B direct connect to specific users and groups within your organization and the external organization.

+## Next steps

+- [Configure cross-tenant access settings](cross-tenant-access-settings-b2b-collaboration.md)

+- See the Microsoft Teams documentation for details about [data loss prevention](/microsoft-365/compliance), [retention policies](/microsoftteams/retention-policies), and [eDiscovery](/microsoftteams/ediscovery-investigation).

+| Carefully plan your cross-tenant access and external collaboration settings | Azure AD gives you a flexible set of controls for managing collaboration with external users and organizations. You can allow or block all collaboration, or configure collaboration only for specific organizations, users, and apps. Before configuring settings for cross-tenant access and external collaboration, take a careful inventory of the organizations you work and partner with. Then determine if you want to enable [B2B direct connect](b2b-direct-connect-overview.md) or [B2B collaboration](what-is-b2b.md) with other Azure AD tenants, and how you want to manage [B2B collaboration invitations](external-collaboration-settings-configure.md). |

+Azure AD organizations can use External Identities cross-tenant access settings to manage how they collaborate with other Azure AD organizations through [B2B collaboration](cross-tenant-access-settings-b2b-collaboration.md) and [B2B direct connect](cross-tenant-access-settings-b2b-direct-connect.md). Cross-tenant access settings give you granular control over how external Azure AD organizations collaborate with you (inbound access) and how your users collaborate with external Azure AD organizations (outbound access). These settings also let you trust multi-factor authentication (MFA) and device claims ([compliant claims and hybrid Azure AD joined claims](../conditional-access/howto-conditional-access-policy-compliant-device.md)) from other Azure AD organizations.

+This article describes cross-tenant access settings, which are used to manage B2B collaboration and B2B direct connect with external Azure AD organizations. Additional settings are available for B2B collaboration with non-Azure AD identities (for example, social identities or non-IT managed external accounts). These [external collaboration settings](external-collaboration-settings-configure.md) include options for restricting guest user access, specifying who can invite guests, and allowing or blocking domains.

+By default, B2B collaboration with other Azure AD organizations is enabled, and B2B direct connect is blocked. But the following comprehensive admin settings let you manage both of these features.

+- **Outbound access settings** control whether your users can access resources in an external organization. You can apply these settings to everyone, or specify individual users, groups, and applications.

+- **Inbound access settings** control whether users from external Azure AD organizations can access resources in your organization. You can apply these settings to everyone, or specify individual users, groups, and applications.

+The default cross-tenant access settings apply to all Azure AD organizations external to your tenant, except those for which you've configured organizational settings. You can change your default settings, but the initial default settings for B2B collaboration and B2B direct connect are as follows:

+- **B2B collaboration**: All your internal users are enabled for B2B collaboration by default. This means your users can invite external guests to access your resources and they can be invited to external organizations as guests. MFA and device claims from other Azure AD organizations aren't trusted.

+- **B2B direct connect**: No B2B direct connect trust relationships are established by default. Azure AD blocks all inbound and outbound B2B direct connect capabilities for all external Azure AD tenants.

+- **Organizational settings**: No organizations are added to your Organizational settings by default. This means all external Azure AD organizations are enabled for B2B collaboration with your organization.

+- For B2B collaboration with other Azure AD organizations, use cross-tenant access settings to manage inbound and outbound B2B collaboration and scope access to specific users, groups, and applications. You can set a default configuration that applies to all external organizations, and then create individual, organization-specific settings as needed. Using cross-tenant access settings, you can also trust multi-factor (MFA) and device claims (compliant claims and hybrid Azure AD joined claims) from other Azure AD organizations.

+- For B2B direct connect, use organizational settings to set up a mutual trust relationship with another Azure AD organization. Both your organization and the external organization need to mutually enable B2B direct connect by configuring inbound and outbound cross-tenant access settings.

+- To configure cross-tenant access settings in the Azure portal, you'll need an account with a Global administrator or Security administrator role.

+- To configure trust settings or apply access settings to specific users, groups, or applications, you'll need an Azure AD Premium P1 license.

+- Cross-tenant access settings are used to manage B2B collaboration and B2B direct connect with other Azure AD organizations. For B2B collaboration with non-Azure AD identities (for example, social identities or non-IT managed external accounts), use [external collaboration settings](external-collaboration-settings-configure.md). External collaboration settings include B2B collaboration options for restricting guest user access, specifying who can invite guests, and allowing or blocking domains.

+ - **Example 1**: If you block inbound access for all external users and groups, access to all your applications must also be blocked.

+ - **Example 2**: If you allow outbound access for all your users (or specific users or groups), youΓÇÖll be prevented from blocking all access to external applications; access to at least one application must be allowed.

+- If you want to allow B2B direct connect with an external organization and your Conditional Access policies require MFA, you must configure your trust settings so that your Conditional Access policies will accept MFA claims from the external organization.

+- If you block access to all apps by default, users will be unable to read emails encrypted with Microsoft Rights Management Service (also known as Office 365 Message Encryption or OME). To avoid this issue, we recommend configuring your outbound settings to allow your users to access this app ID: 00000012-0000-0000-c000-000000000000. If this is the only application you allow, access to all other apps will be blocked by default.

+Several tools are available to help you identify the access your users and partners need before you set inbound and outbound access settings. To ensure you donΓÇÖt remove access that your users and partners need, you should examine current sign-in behavior. Taking this preliminary step will help prevent loss of desired access for your end users and partner users. However, in some cases these logs are only retained for 30 days, so we strongly recommend you speak with your business stakeholders to ensure required access isn't lost.

+To review user sign-in activity associated with external tenants, use the [cross-tenant user sign-in activity](https://aka.ms/cross-tenant-signins-ps) PowerShell script. For example, to view all available sign-in events for inbound activity (external users accessing resources in the local tenant) and outbound activity (local users accessing resources in an external tenant), run the following command:

+To determine your users' access to external Azure AD organizations, use the [Get-MgAuditLogSignIn](/powershell/module/microsoft.graph.reports/get-mgauditlogsignin) cmdlet in the Microsoft Graph PowerShell SDK to view data from your sign-in logs for the last 30 days. For example, run the following command:

+If your organization subscribes to the Azure Monitor service, use the [Cross-tenant access activity workbook](../reports-monitoring/workbook-cross-tenant-access-activity.md) (available in the Monitoring workbooks gallery in the Azure portal) to visually explore inbound and outbound sign-ins for longer time periods.

+If your organization exports sign-in logs to a Security Information and Event Management (SIEM) system, you can retrieve the required information from your SIEM system.

+[Configure cross-tenant access settings for B2B direct connect](cross-tenant-access-settings-b2b-direct-connect.md)

+ - **Allow access**: Allows the users and groups specified under **Applies to** to be invited for B2B collaboration.

+ - **Block access**: Blocks the users and groups specified under **Applies to** from being invited to B2B collaboration.

+1. Under **Applies to**, select one of the following:

+ - **Allow access**: Allows the applications specified under **Applies to** to be accessed by B2B collaboration users.

+ - **Block access**: Blocks the applications specified under **Applies to** from being accessed by B2B collaboration users.

+1. Under **Applies to**, select one of the following:

+ - **Allow access**: Allows your users and groups specified under **Applies to** to be invited to external organizations for B2B collaboration.

+ - **Block access**: Blocks your users and groups specified under **Applies to** from being invited to B2B collaboration. If you block access for all users and groups, this will also block all external applications from being accessed via B2B collaboration.

+1. Under **Applies to**, select one of the following:

+ - **Allow access**: Allows the external applications specified under **Applies to** to be accessed by your users via B2B collaboration.

+ - **Block access**: Blocks the external applications specified under **Applies to** from being accessed by your users via B2B collaboration.

+1. Under **Applies to**, select one of the following:

+- See [Configure external collaboration settings](external-collaboration-settings-configure.md) for B2B collaboration with non-Azure AD identities, social identities, and non-IT managed external accounts.

+- [Configure cross-tenant access settings for B2B direct connect](cross-tenant-access-settings-b2b-direct-connect.md)

+ Title: Configure B2B direct connect cross-tenant access - Azure AD

+description: Use cross-tenant access settings to manage how you collaborate with other Azure AD organizations. Learn how to configure outbound access to external organizations and inbound access from external Azure AD for B2B direct connect.

+# Configure cross-tenant access settings for B2B direct connect

+> [!NOTE]

+> Cross-tenant access settings are preview features of Azure Active Directory. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

+Use cross-tenant access settings to manage how you collaborate with other Azure AD organizations through [B2B direct connect](b2b-direct-connect-overview.md). These settings let you determine the level of outbound access your users have to external organizations. They also let you control the level of inbound access that users in external Azure AD organizations will have to your internal resources.

+- **Default settings**: The default cross-tenant access settings apply to all external Azure AD organizations, except organizations for which you've configured individual settings. You can change these default settings. For B2B direct connect, you'll typically leave the default settings as-is and enable B2B direct connect access with organization-specific settings. Initially, your default values are as follows:

+ - **B2B direct connect initial default settings** - By default, outbound B2B direct connect is blocked for your entire tenant, and inbound B2B direct connect is blocked for all external Azure AD organizations.

+ - **Organizational settings** - No organizations are added by default.

+- **Organization-specific settings**: You can configure organization-specific settings by adding an organization and modifying the inbound and outbound settings for that organization. Organizational settings take precedence over default settings.

+Learn more about using cross-tenant access settings to [manage B2B direct connect](b2b-direct-connect-overview.md#managing-cross-tenant-access-for-b2b-direct-connect).

+## Before you begin

+- Review the [Important considerations](cross-tenant-access-overview.md#important-considerations) section in the [cross-tenant access overview](cross-tenant-access-overview.md) before configuring your cross-tenant access settings.

+- Decide on the default level of access you want to apply to all external Azure AD organizations.

+- Identify any Azure AD organizations that will need customized settings.

+- Contact organizations with which you want to set up B2B direct connect. Because B2B direct connect is established through mutual trust, both you and the other organization need to enable B2B direct connect with each other in your cross-tenant access settings.

+- Obtain any required information from external organizations. If you want to apply access settings to specific users, groups, or applications within an external organization, you'll need to obtain these IDs from the organization before you can configure access settings.

+- To configure cross-tenant access settings in the Azure portal, you'll need an account with a Global administrator or Security administrator role. Teams administrators can read cross-tenant access settings, but they can't update these settings.

+## Configure default settings

+ Default cross-tenant access settings apply to all external tenants for which you haven't created organization-specific customized settings. If you want to modify the Azure AD-provided default settings, follow these steps.

+1. Sign in to the [Azure portal](https://portal.azure.com) using a Global administrator or Security administrator account. Then open the **Azure Active Directory** service.

+1. Select **External Identities**, and then select **Cross-tenant access settings (Preview)**.

+1. Select the **Default settings** tab and review the summary page.

+ 

+1. To change the settings, select the **Edit inbound defaults** link or the **Edit outbound defaults** link.

+ 

+1. Modify the default settings by following the detailed steps in these sections:

+ - [Modify inbound access settings](#modify-inbound-access-settings)

+ - [Modify outbound access settings](#modify-outbound-access-settings)

+## Add an organization

+Follow these steps to configure customized settings for specific organizations.

+1. Sign in to the [Azure portal](https://portal.azure.com) using a Global administrator or Security administrator account. Then open the **Azure Active Directory** service.

+2. Select **External Identities**, and then select **Cross-tenant access settings (preview)**.

+3. Select **Organizational settings**.

+4. Select **Add organization**.

+5. On the **Add organization** pane, type the full domain name (or tenant ID) for the organization.

+ 

+1. Select the organization in the search results, and then select **Add**.

+2. The organization appears in the **Organizational settings** list. At this point, all access settings for this organization are inherited from your default settings. To change the settings for this organization, select the **Inherited from default** link under the **Inbound access** or **Outbound access** column.

+ 

+1. Modify the organization's settings by following the detailed steps in these sections:

+ - [Modify inbound access settings](#modify-inbound-access-settings)

+ - [Modify outbound access settings](#modify-outbound-access-settings)

+## Modify inbound access settings

+With inbound settings, you select which external users and groups will be able to access the internal applications you choose. Whether you're configuring default settings or organization-specific settings, the steps for changing inbound cross-tenant access settings are the same. As described in this section, you'll navigate to either the **Default** tab or an organization on the **Organizational settings** tab, and then make your changes.

+1. Sign in to the [Azure portal](https://portal.azure.com) using a Global administrator or Security administrator account. Then open the **Azure Active Directory** service.

+1. Select **External Identities**, and then select **Cross-tenant access settings (Preview)**.

+1. Navigate to the settings you want to modify:

+ - To modify default inbound settings, select the **Default settings** tab, and then under **Inbound access settings**, select **Edit inbound defaults**.

+ - To modify settings for a specific organization, select the **Organizational settings** tab, find the organization in the list (or [add one](#add-an-organization)), and then select the link in the **Inbound access** column.

+1. Follow the detailed steps for the settings you want to change:

+ - [To change inbound B2B direct connect settings](#to-change-inbound-b2b-direct-connect-settings)

+ - [To change inbound trust settings for MFA and device state](#to-change-inbound-trust-settings-for-mfa-and-device-state)

+### To change inbound B2B direct connect settings

+1. Select the **B2B direct connect** tab

+1. *If you're configuring settings for an organization,* select one of these options:

+ - **Default settings**: The organization will use the settings configured on the **Default** settings tab. If customized settings were already configured for this organization, you'll need to select **Yes** to confirm that you want all settings to be replaced by the default settings. Then select **Save**, and skip the rest of the steps in this procedure.

+ - **Customize settings**: You can customize the settings for this organization, which will be enforced for this organization instead of the default settings. Continue with the rest of the steps in this procedure.

+1. Select **External users and groups**.

+1. Under **Access status**, select one of these options:

+ - **Allow access**: Allows the users and groups specified under **Applies to** to access B2B direct connect.

+ - **Block access**: Blocks the users and groups specified under **Applies to** from accessing B2B direct connect. Blocking access for all external users and groups also blocks all your internal applications from being shared via B2B direct connect.

+ 

+1. Under **Applies to**, select one of the following:

+ - **All external users and groups**: Applies the action you chose under **Access status** to all users and groups from external Azure AD organizations.

+ - **Select external users and groups** (requires an Azure AD premium subscription): Lets you apply the action you chose under **Access status** to specific users and groups within the external organization.

+ 

+1. If you chose **Select external users and groups**, do the following for each user or group you want to add:

+ - Select **Add external users and groups**.

+ - In the **Add other users and groups** pane, type the user object ID or the group object ID in the search box.

+ - In the menu next to the search box, choose either **user** or **group**.

+ - Select **Add**.

+ 

+1. When you're done adding users and groups, select **Submit**.

+1. Select the **Applications** tab.

+1. Under **Access status**, select one of the following:

+ - **Allow access**: Allows the applications specified under **Applies to** to be accessed by B2B direct connect users.

+ - **Block access**: Blocks the applications specified under **Applies to** from being accessed by B2B direct connect users.

+ 

+1. Under **Applies to**, select one of the following:

+ - **All applications**: Applies the action you chose under **Access status** to all of your applications.

+ - **Select applications** (requires an Azure AD premium subscription): Lets you apply the action you chose under **Access status** to specific applications in your organization.

+ 

+1. If you chose **Select applications**, do the following for each application you want to add:

+ - Select **Add Microsoft applications**.

+ - In the applications pane, type the application name in the search box and select the application in the search results.

+ - When you're done selecting applications, choose **Select**.

+ 

+1. Select **Save**.

+### To change inbound trust settings for MFA and device state

+1. Select the **Trust settings** tab.

+1. *If you're configuring settings for an organization*, select one of these options:

+ - **Default settings**: The organization will use the settings configured on the **Default** settings tab. If customized settings were already configured for this organization, you'll need to select **Yes** to confirm that you want all settings to be replaced by the default settings. Then select **Save**, and skip the rest of the steps in this procedure.

+ - **Customize settings**: You can customize the settings for this organization, which will be enforced for this organization instead of the default settings. Continue with the rest of the steps in this procedure.

+1. Select one or more of the following options:

+ - **Trust multi-factor authentication from Azure AD tenants**: Select this checkbox if your Conditional Access policies require multi-factor authentication (MFA). This setting allows your Conditional Access policies to trust MFA claims from external organizations. During authentication, Azure AD will check a user's credentials for a claim that the user has completed MFA. If not, an MFA challenge will be initiated in the user's home tenant.

+ - **Trust compliant devices**: Allows your Conditional Access policies to trust compliant device claims from an external organization when their users access your resources.

+ - **Trust hybrid Azure AD joined devices**: Allows your Conditional Access policies to trust hybrid Azure AD joined device claims from an external organization when their users access your resources.

+ 

+1. Select **Save**.

+## Modify outbound access settings

+With outbound settings, you select which of your users and groups will be able to access the external applications you choose. The detailed steps for modifying outbound cross-tenant access settings are the same whether you're configuring default or organization-specific settings. As described in this section, navigate to the **Default** tab or an organization on the **Organizational settings** tab, and then make your changes.

+1. Sign in to the [Azure portal](https://portal.azure.com) using a Global administrator or Security administrator account. Then open the **Azure Active Directory** service.

+1. Select **External Identities** > **Cross-tenant access settings (preview)**.

+1. Navigate to the settings you want to modify:

+ - To modify default outbound settings, select the **Default settings** tab, and then under **Outbound access settings**, select **Edit outbound defaults**.

+ - To modify settings for a specific organization, select the **Organizational settings** tab, find the organization in the list (or [add one](#add-an-organization)) and then select the link in the **Outbound access** column.

+### To change the outbound access settings

+1. Select the **B2B direct connect** tab.

+1. *If you're configuring settings for an organization,* select one of these options:

+ - **Default settings**: The organization will use the settings configured on the **Default** settings tab. If customized settings were already configured for this organization, you'll need to select **Yes** to confirm that you want all settings to be replaced by the default settings. Then select **Save**, and skip the rest of the steps in this procedure.

+ - **Customize settings**: You can customize the settings for this organization, which will be enforced for this organization instead of the default settings. Continue with the rest of the steps in this procedure.

+1. Select **Users and groups**.

+1. Under **Access status**, select one of the following:

+ - **Allow access**: Allows your users and groups specified under **Applies to** to access B2B direct connect.

+ - **Block access**: Blocks your users and groups specified under **Applies to** from accessing B2B direct connect. Blocking access for all your users and groups also blocks all external applications from being shared via B2B direct connect.

+ 

+1. Under **Applies to**, select one of the following:

+ - **All \<your organization\> users**: Applies the action you chose under **Access status** to all your users and groups.

+ - **Select \<your organization\> users and groups** (requires an Azure AD premium subscription): Lets you apply the action you chose under **Access status** to specific users and groups.

+ 

+1. If you chose **Select \<your organization\> users and groups**, do the following for each user or group you want to add:

+ - Select **Add \<your organization\> users and groups**.

+ - In the **Select** pane, type the user name or the group name in the search box.

+ - When you're done selecting users and groups, choose **Select**.

+1. Select **Save**.

+1. Select the **External applications** tab.

+1. Under **Access status**, select one of the following:

+ - **Allow access**: Allows the applications specified under **Applies to** to be accessed by B2B direct connect users.

+ - **Block access**: Blocks the applications specified under **Applies to** from being accessed by B2B direct connect users.

+ 

+1. Under **Applies to**, select one of the following:

+ - **All external applications**: Applies the action you chose under **Access status** to all external applications.

+ - **Select applications** (requires an Azure AD premium subscription): Lets you apply the action you chose under **Access status** to specific external applications.

+ 

+1. If you chose **Select external applications**, do the following for each application you want to add:

+ - Select **Add Microsoft applications** or **Add other applications**.

+ - In the applications pane, type the application name in the search box and select the application in the search results.

+ - When you're done selecting applications, choose **Select**.

+ 

+1. Select **Save**.

+## Remove an organization

+When you remove an organization from your Organizational settings, the default cross-tenant access settings will go into effect for all B2B collaboration with that organization.

+> [!NOTE]

+> If the organization is a cloud service provider for your organization (the isServiceProvider property in the Microsoft Graph [partner-specific configuration](/graph/api/resources/crosstenantaccesspolicyconfigurationpartner) is true), you won't be able to remove the organization.

+1. Sign in to the [Azure portal](https://portal.azure.com) using a Global administrator or Security administrator account. Then open the **Azure Active Directory** service.

+1. Select **External Identities**, and then select **Cross-tenant access settings (Preview)**.

+1. Select the **Organizational settings** tab.

+2. Find the organization in the list, and then select the trash can icon on that row.

+## Next steps

+[Configure cross-tenant access settings for B2B collaboration (Preview)](cross-tenant-access-settings-b2b-collaboration.md)

+- **B2B direct connect** - Establish a mutual, two-way trust with another Azure AD organization for seamless collaboration. B2B direct connect currently supports Teams shared channels, enabling external users to access your resources from within their home instances of Teams. B2B direct connect users aren't represented in your directory, but they're visible from within the Teams shared channel and can be monitored in Teams admin center reports.

+With [B2B collaboration](what-is-b2b.md), you can invite anyone to sign in to your Azure AD organization using their own credentials so they can access the apps and resources you want to share with them. Use B2B collaboration when you need to let external users access your Office 365 apps, software-as-a-service (SaaS) apps, and line-of-business applications, especially when the partner doesn't use Azure AD or it's impractical for administrators to set up a mutual connection through B2B direct connect. There are no credentials associated with B2B collaboration users. Instead, they authenticate with their home organization or identity provider, and then your organization checks the guest userΓÇÖs eligibility for B2B collaboration.

+## B2B direct connect

+B2B direct connect is a new way to collaborate with other Azure AD organizations. With B2B direct connect, you create two-way trust relationships with other Azure AD organizations to allow users to seamlessly sign in to your shared resources and vice versa. B2B direct connect users aren't added as guests to your Azure AD directory. When two organizations mutually enable B2B direct connect, users authenticate in their home organization and receive a token from the resource organization for access. Learn more about [B2B direct connect in Azure AD](b2b-direct-connect-overview.md).

+Currently, B2B direct connect enables the Teams Connect shared channels feature, which lets your users collaborate with external users from multiple organizations with a Teams shared channel for chat, calls, file-sharing, and app-sharing. Once youΓÇÖve set up B2B direct connect with an external organization, the following Teams shared channels capabilities become available:

+- Within Teams, a shared channel owner can search for allowed users from the external organization and add them to the shared channel.

+- External users can access the Teams shared channel without having to switch organizations or sign in with a different account. From within Teams, the external user can access files and apps through the Files tab. The userΓÇÖs access is determined by the shared channelΓÇÖs policies.

+You use [cross-tenant access settings](cross-tenant-access-settings-b2b-collaboration.md) to manage trust relationships with other Azure AD organizations and define inbound and outbound policies for B2B direct connect.

+For details about the resources, files, and applications, that are available to the B2B direct connect user via the Teams shared channel, refer to [Chat, teams, channels, & apps in Microsoft Teams](/microsoftteams/deploy-chat-teams-channels-microsoft-teams-landing-page).

+The following table gives a detailed comparison of the scenarios you can enable with Azure AD External Identities. In the B2B scenarios, an external user is anyone who isn't homed in your Azure AD organization.

+| | B2B collaboration | B2B direct connect | Azure AD B2C |

+| - | | | |

+| **Primary scenario** | Collaborate with external users by letting them use their preferred identity to sign in to resources in your Azure AD organization. Provides access to Microsoft applications or your own applications (SaaS apps, custom-developed apps, etc.). <br><br> *Example:* Invite an external user to sign in to your Microsoft apps or become a guest member in Teams. | Collaborate with users from other Azure AD organizations by establishing a mutual connection. Currently can be used with Teams shared channels, which external users can access from within their home instances of Teams. <br><br> *Example:* Add an external user to a Teams shared channel, which provides a space to chat, call, and share content. | Publish apps to consumers and customers using Azure AD B2C for identity experiences. Provides identity and access management for modern SaaS or custom-developed applications (not first-party Microsoft apps). |

+| **Intended for** | Collaborating with business partners from external organizations like suppliers, partners, vendors. These users may or may not have Azure AD or managed IT. | Collaborating with business partners from external organizations that use Azure AD, like suppliers, partners, vendors. | Customers of your product. These users are managed in a separate Azure AD directory. |

+| **User management** | B2B collaboration users are managed in the same directory as employees but are typically annotated as guest users. Guest users can be managed the same way as employees, added to the same groups, and so on. Cross-tenant access settings can be used to determine which users have access to B2B collaboration. | No user object is created in your Azure AD directory. Cross-tenant access settings determine which users have access to B2B collaboration. direct connect. Shared channel users can be managed in Teams, and usersΓÇÖ access is determined by the Teams shared channelΓÇÖs policies. | User objects are created for consumer users in your Azure AD B2C directory. They're managed separately from the organization's employee and partner directory (if any). |

+| **Identity providers supported** | External users can collaborate using work accounts, school accounts, any email address, SAML and WS-Fed based identity providers, and social identity providers like Gmail and Facebook. | External users collaborate using Azure AD work accounts or school accounts. | Consumer users with local application accounts (any email address, user name, or phone number), Azure AD, various supported social identities, and users with corporate and government-issued identities via SAML/WS-Fed-based identity provider federation. |

+| **Single sign-on (SSO)** | SSO to all Azure AD-connected apps is supported. For example, you can provide access to Microsoft 365 or on-premises apps, and to other SaaS apps such as Salesforce or Workday. | SSO to a Teams shared channel. | SSO to customer owned apps within the Azure AD B2C tenants is supported. SSO to Microsoft 365 or to other Microsoft SaaS apps isn't supported. |

+| **Licensing and billing** | Based on monthly active users (MAU), including B2B collaboration and Azure AD B2C users. Learn more about [External Identities pricing](https://azure.microsoft.com/pricing/details/active-directory/external-identities/) and [billing setup for B2B](external-identities-pricing.md). | Based on monthly active users (MAU), including B2B collaboration, B2B direct connect, and Azure AD B2C users. Learn more about [External Identities pricing](https://azure.microsoft.com/pricing/details/active-directory/external-identities/) and [billing setup for B2B](external-identities-pricing.md). | Based on monthly active users (MAU), including B2B collaboration and Azure AD B2C users. Learn more about [External Identities pricing](https://azure.microsoft.com/pricing/details/active-directory/external-identities/) and [billing setup for Azure AD B2C](../../active-directory-b2c/billing.md). |

+| **Security policy and compliance** | Managed by the host/inviting organization (for example, with [Conditional Access policies](authentication-conditional-access.md) and cross-tenant access settings). | Managed by the host/inviting organization (for example, with [Conditional Access policies](authentication-conditional-access.md) and cross-tenant access settings). See also the [Teams documentation](/microsoftteams/security-compliance-overview). | Managed by the organization via Conditional Access and Identity Protection. |

+| **Branding** | Host/inviting organization's brand is used. | For sign-in screens, the userΓÇÖs home organization brand is used. In the shared channel, the resource organization's brand is used. | Fully customizable branding per application or organization. |

+| **More information** | [Blog post](https://blogs.technet.microsoft.com/enterprisemobility/2017/02/01/azure-ad-b2b-new-updates-make-cross-business-collab-easy/), [Documentation](what-is-b2b.md) | [Documentation](b2b-direct-connect-overview.md) | [Product page](https://azure.microsoft.com/services/active-directory-b2c/), [Documentation](../../active-directory-b2c/index.yml) |

+Azure AD B2B collaboration and B2B direct connect are features Azure AD, and they're managed in the Azure portal through the Azure Active Directory service. To control inbound and outbound collaboration, you can use a combination of *cross-tenant access settings* and *external collaboration settings*.

+Cross-tenant access settings let you manage B2B collaboration and B2B direct connect with other Azure AD organizations. You can determine how other Azure AD organizations collaborate with you (inbound access), and how your users collaborate with other Azure AD organizations (outbound access). Granular controls let you determine the people, groups, and apps, both in your organization and in external Azure AD organizations, that can participate in B2B collaboration and B2B direct connect. You can also trust multi-factor authentication (MFA) and device claims (compliant claims and hybrid Azure AD joined claims) from other Azure AD organizations.

+- **Default cross-tenant access settings** determine your baseline inbound and outbound settings for both B2B collaboration and B2B direct connect. Initially, your default settings are configured to allow all inbound and outbound B2B collaboration with other Azure AD organizations and to block B2B direct connect with all Azure AD organizations. You can change these initial settings to create your own default configuration.

+- **Organization-specific access settings** let you configure customized settings for individual Azure AD organizations. Once you add an organization and customize your cross-tenant access settings with this organization, these settings will take precedence over your defaults. For example, you could disable B2B collaboration and B2B direct connect with all external organizations by default, but enable these features only for Fabrikam.

+There are several Azure AD technologies that are related to collaboration with external users and organizations. As you design your External Identities collaboration model, consider these other features.

+- **Cross-tenant access settings API**: The [Microsoft Graph cross-tenant access API](/graph/api/resources/crosstenantaccesspolicy-overview?view=graph-rest-beta) lets you programmatically create the same B2B collaboration and B2B direct connect policies that are configurable in the Azure portal. Using the API, you can set up policies for inbound and outbound collaboration to allow or block features for everyone by default and limit access to specific organizations, groups, users, and applications. The API also allows you to accept MFA and device claims (compliant claims and hybrid Azure AD joined claims) from other Azure AD organizations.

+Organizations can enforce Conditional Access policies for external B2B collaboration and B2B direct connect users in the same way that they're enabled for full-time employees and members of the organization. For Azure AD cross-tenant scenarios, if your Conditional Access policies require MFA or device compliance, you can now trust MFA and device compliance claims from an external user's home organization. When trust settings are enabled, during authentication, Azure AD will check a user's credentials for an MFA claim or a device ID to determine if the policies have already been met. If so, the external user will be granted seamless sign-on to your shared resource. Otherwise, an MFA or device challenge will be initiated in the user's home tenant. Learn more about the [authentication flow and Conditional Access for external users](authentication-conditional-access.md).

+- [What is Azure AD B2B direct connect?](b2b-direct-connect-overview.md)

+# Leave an organization as a B2B collaboration user

+An Azure Active Directory (Azure AD) B2B collaboration user can decide to leave an organization at any time if they no longer need to use apps from that organization or maintain any association.

+- **B2B collaboration users** can usually leave an organization on their own without having to contact an administrator. This option won't be available if it's not allowed by the organization, or if the B2B collaboration user's account has been disabled. The user will need to contact the tenant admin, who can delete the account.

+- **B2B direct connect users** don't currently have the option to leave the external organization. If you're a B2B direct connect user at an organization, you can contact your IT admin to submit a Data Subject Request, which is a request to remove the personal data associated with your B2B direct connect user account from the organization.

+

+- If you're using a personal account, go to https://myapps.microsoft.com and sign in, and then select your account icon in the upper right and select **View account**. Or, use a My Account URL that includes your tenant information to go directly to your My Account page (examples are shown in the following note).

+When a B2B collaboration user leaves an organization, the B2B collaboration user account is "soft deleted" in the directory. By default, the user object moves to the **Deleted users** area in Azure AD but isn't permanently deleted for 30 days. This soft deletion enables the administrator to restore the B2B collaboration user account, including groups and permissions, if the user makes a request to restore the account before it's permanently deleted.

+If desired, a tenant administrator can permanently delete the account at any time during the soft-delete period:

+If you permanently delete a B2B collaboration user account, this action is irrevocable.

+## B2B direct connect user is unable to access a shared channel (error AADSTS90071)

+When a B2B direct connect sees the following error message when trying to access another organization's Teams shared channel, multi-factor authentication trust settings haven't been configured by the external organization:

+> The organization you're trying to reach needs to update their settings to let you sign in.

+>

+> AADSTS90071: An admin from *&lt;organization&gt;* must update their access settings to accept inbound multifactor authentication.

+The organization hosting the Teams shared channel must enable the trust setting for multi-factor authentication to allow access to B2B direct connect users. Trust settings are configurable in an organization's [cross-tenant access settings](cross-tenant-access-settings-b2b-direct-connect.md).

+As you configure [cross-tenant access settings](cross-tenant-access-settings-b2b-collaboration.md), if you receive an error that says ΓÇ£Failure to update policy due to object limit,ΓÇ¥ you've reached the policy object limit of 25 KB. We're working toward increasing this limit. If you need to be able to calculate how close the current policy is to this limit, do the following:

+As you configure [cross-tenant access settings](cross-tenant-access-settings-b2b-collaboration.md), if you block access to all apps by default, users will be unable to read emails encrypted with Microsoft Rights Management Service (also known as OME). To avoid this issue, we recommend configuring your outbound settings to allow your users to access this app ID: 00000012-0000-0000-c000-000000000000. If this is the only application you allow, access to all other apps will be blocked by default.

+## IΓÇÖve added an external user but don't see them in my Global Address Book or in the people picker

+In cases where external users aren't populated in the list, the object might take a few minutes to replicate.

+## A B2B guest user isn't showing up in SharePoint Online/OneDrive people picker

+You can enable this feature by using the setting 'ShowPeoplePickerSuggestionsForGuestUsers' at the tenant and site collection level. You can set the feature using the Set-SPOTenant and Set-SPOSite cmdlets, which allow members to search all existing guest users in the directory. Changes in the tenant scope don't affect already provisioned SPO sites.

+By default, SharePoint Online and OneDrive have their own set of external user options and don't use the settings from Azure AD. You need to enable [SharePoint and OneDrive integration with Azure AD B2B](/sharepoint/sharepoint-azureb2b-integration-preview) to ensure the options are consistent among those applications.

+If you're notified that you don't have permissions to invite users, verify that your user account is authorized to invite external users under Azure Active Directory > User settings > External users > Manage external collaboration settings:

+If you've recently modified these settings or assigned the Guest Inviter role to a user, there might be a 15-60 minute delay before the changes take effect.

+When inviting users whose organization is using Azure Active Directory, but where the specific userΓÇÖs account doesn't exist (for example, the user doesn't exist in Azure AD contoso.com). The administrator of contoso.com may have a policy in place preventing users from being created. The user must check with their admin to determine if external users are allowed. The external userΓÇÖs admin may need to allow Email Verified users in their domain (see this [article](/powershell/module/msonline/set-msolcompanysettings) on allowing Email Verified Users).

+

+### External user doesn't exist already in a federated domain

+If you're using federation authentication and the user doesn't already exist in Azure Active Directory, the user can't be invited.

+When we check whether a user is able to be invited to your tenant, one of the things we check for is for a collision in the proxyAddress. This includes any proxyAddresses for the user in their home tenant and any proxyAddress for local users in your tenant. For external users, we'll add the email to the proxyAddress of the existing B2B user. For local users, you can ask them to sign in using the account they already have.

+Sometimes, the external guest user you're inviting conflicts with an existing [Contact object](/graph/api/resources/contact). When this occurs, the guest user is created without a proxyAddress. This means that the user won't be able to redeem this account using [just-in-time redemption](redemption-experience.md#redemption-through-a-direct-link) or [email one-time passcode authentication](one-time-passcode.md#user-experience-for-one-time-passcode-guest-users).

+## How does ΓÇÿ\#ΓÇÖ, which isn't normally a valid character, sync with Azure AD?

+## My external user didn't receive an email to redeem

+## I notice that the custom message doesn't get included with invitation messages at times

+To comply with privacy laws, our APIs don't include custom messages in the email invitation when:

+## You receive an ΓÇ£AADSTS65005ΓÇ¥ error when you try to sign in to an Azure resource

+A user who has a guest account can't sign in, and is receiving the following error message:

+## I receive the error that Azure AD can't find the aad-extensions-app in my tenant

+When you're using self-service sign-up features, like custom user attributes or user flows, an app called `aad-extensions-app. Do not modify. Used by AAD for storing user data.` is automatically created. It's used by Azure AD External Identities to store information about users who sign up and custom attributes collected.

+## A guest user was invited successfully but the email attribute isn't populating

+> | microsoft.insights/allEntities/allProperties/allTasks | Manage all aspects of Insights app |

+> | microsoft.virtualVisits/allEntities/allProperties/allTasks | Manage and share Virtual Visits information and metrics from admin centers or the Virtual Visits app |

+> | microsoft.insights/allEntities/allProperties/read | Read all aspects of Viva Insights |

+> | microsoft.virtualVisits/allEntities/allProperties/read | Read all aspects of Virtual Visits |

+> | microsoft.insights/allEntities/allProperties/allTasks | Manage all aspects of Insights app |

+> | microsoft.insights/reports/allProperties/read | View reports and dashboard in Insights app |

+> | microsoft.insights/programs/allProperties/update | Deploy and manage programs in Insights app |

+## Autoscaling

+While we provide [guidance on the minimum number of replicas](#number-of-replicas) for the self-hosted gateway, we recommend that you use autoscaling for the self-hosted gateway to meet the demand of your traffic more proactively.

+There are two ways to autoscale the self-hosted gateway horizontally:

+- Autoscale based on resource usage (CPU and memory)

+- Autoscale based on the number of requests per second

+This is possible through native Kubernetes functionality, or by using [Kubernetes Event-driven Autoscaling (KEDA)](https://keda.sh/). KEDA is a CNCF Incubation project that strives to make application autoscaling simple.

+> [!NOTE]

+> KEDA is an open-source technology that is not supported by Azure support and needs to be operated by customers.

+### Resource-based autoscaling

+Kubernetes allows you to autoscale the self-hosted gateway based on resource usage by using a [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). It allows you to [define CPU and memory thresholds](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#support-for-resource-metrics), and the number of replicas to scale out or in.

+An alternative is to use Kubernetes Event-driven Autoscaling (KEDA) allowing you to scale workloads based on a [variety of scalers](https://keda.sh/docs/latest/scalers/), including CPU and memory.

+> [!TIP]

+> If you are already using KEDA to scale other workloads, we recommend using KEDA as a unified app autoscaler. If that is not the case, then we strongly suggest to rely on the native Kubernetes functionality through Horizontal Pod Autoscaler.

+### Traffic-based autoscaling

+Kubernetes does not provide an out-of-the-box mechanism for traffic-based autoscaling.

+Kubernetes Event-driven Autoscaling (KEDA) provides a few ways that can help with traffic-based autoscaling:

+- You can scale based on metrics from a Kubernetes ingress if they are available in [Prometheus](https://keda.sh/docs/latest/scalers/prometheus/) or [Azure Monitor](https://keda.sh/docs/latest/scalers/azure-monitor/) by using an out-of-the-box scaler

+- You can install [HTTP add-on](https://github.com/kedacore/http-add-on), which is available in beta, and scales based on the number of requests per second.

+* Learn more about [configuring policies](/azure/api-management/api-management-howto-policies) in API Management.

+> * API Management support for private endpoints is currently in **preview**.

+* [Troubleshoot Azure private endpoint connectivity problems](../private-link/troubleshoot-private-endpoint-connectivity.md).

+### Web Application Firewall (WAF) metrics

+For information on WAF Monitoring, see [WAF v2 Metrics](../../articles/web-application-firewall/ag/application-gateway-waf-metrics.md#application-gateway-waf-v2-metrics)

+### Web Application Firewall (WAF) metrics

+For information on WAF Monitoring, see [WAF v1 Metrics](../../articles/web-application-firewall/ag/application-gateway-waf-metrics.md#application-gateway-waf-v1-metrics)

+| [appgw.ingress.kubernetes.io/rewrite-rule-set](#rewrite-rule-set) | `string` | `nil` | |

+```

+## Rewrite Rule Set

+This annotation allows you to assign an existing rewrite rule set to the corresponding request routing rule.

+### Usage

+```yaml

+appgw.ingress.kubernetes.io/rewrite-rule-set: <rewrite rule set name>

+```

+### Example

+```yaml

+apiVersion: networking.k8s.io/v1

+kind: Ingress

+metadata:

+ name: go-server-ingress-bkprefix

+ namespace: test-ag

+ annotations:

+ kubernetes.io/ingress.class: azure/application-gateway

+ appgw.ingress.kubernetes.io/rewrite-rule-set: add-custom-response-header

+spec:

+ rules:

+ - http:

+ paths:

+ - path: /

+ pathType: Exact

+ backend:

+ service:

+ name: go-server-service

+ port:

+ number: 8080

+```

+References to Key Vaults in other Azure subscriptions is supported, but must be configured via ARM Template, Azure PowerShell, CLI, Bicep, etc. Cross-subscription key vault configuration is not supported by Application Gateway via Azure Portal today.

+$secretId = $secret.Id.Replace($secret.Version, "") # Remove the secret version so AppGW will use the latest version in future syncs

+| 🆕[Read (preview)](#read-preview) | Extract printed and handwritten text lines, words, locations, and detected languages.|

+The W-2 model analyzes and extracts key information reported in each box on a W-2 form. The model supports standard and customized forms from 2018 to the present, including single and multiple forms on one page.

+***Sample document processed using the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/layout)***:

+The receipt model analyzes and extracts key information from printed and handwritten receipts.

+ The ID document model analyzes and extracts key information from the following documents:

+* U.S. Driver's Licenses (all 50 states and District of Columbia)

+* Biographical pages from international passports (excluding visa and other travel documents). The API analyzes identity documents and extracts

+The business card model analyzes and extracts key information from business card images.

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

+## Run your application

+Once you've added a code sample to your application, choose the green **Start** button next to formRecognizer_quickstart to build and run your program, or press **F5**.

+ :::image type="content" source="../media/quickstarts/run-visual-studio.png" alt-text="Screenshot: run your Visual Studio program.":::

+<!-- ### [.NET Command-line interface (CLI)](#tab/cli)

+Open your command prompt and go to the directory that contains your project and type the following:

+```console

+dotnet run formrecognizer-quickstart.dll

+```

+### [Visual Studio](#tab/vs) -->

+Here's a snippet of the expected output:

+```console

+ Detected key-value pairs:

+ Found key with no value: '?'

+ Found key-value pair: 'QUARTERLY REPORT PURSUANT TO SECTION 13 OR 15(d) OF THE SECURITIES EXCHANGE ACT OF 1934' and ':selected:'

+ Found key-value pair: 'For the Quarterly Period Ended March 31, 2020' and 'OR'

+ Found key with no value: '?'

+ Found key-value pair: 'TRANSITION REPORT PURSUANT TO SECTION 13 OR 15(d) OF THE SECURITIES EXCHANGE ACT OF 1934' and ':unselected:'

+ Found key with no value: 'For the Transition Period From'

+ Found key-value pair: 'to Commission File Number' and '001-37845'

+```

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

+Here's a snippet of the expected output:

+```console

+ Document Page 1 has 69 line(s), 425 word(s), and 15 selection mark(s).

+ Line 0 has content: 'UNITED STATES'.

+ Its bounding box is:

+ Upper left => X: 3.4915, Y= 0.6828

+ Upper right => X: 5.0116, Y= 0.6828

+ Lower right => X: 5.0116, Y= 0.8265

+ Lower left => X: 3.4915, Y= 0.8265

+ Line 1 has content: 'SECURITIES AND EXCHANGE COMMISSION'.

+ Its bounding box is:

+ Upper left => X: 2.1937, Y= 0.9061

+ Upper right => X: 6.297, Y= 0.9061

+ Lower right => X: 6.297, Y= 1.0498

+ Lower left => X: 2.1937, Y= 1.0498

+```

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

+Here's a snippet of the expected output:

+ Document 0:

+ Vendor Name: 'CONTOSO LTD.', with confidence 0.962

+ Customer Name: 'MICROSOFT CORPORATION', with confidence 0.951

+ Item:

+ Description: 'Test for 23 fields', with confidence 0.899

+ Amount: '100', with confidence 0.902

+ Sub Total: '100', with confidence 0.979

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

+<!-- markdownlint-disable MD025 -->

+## Create a Java application

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

+## Build and run your application

+Once you've added a code sample to your application, navigate back to your main project directoryΓÇö**form-recognizer-app**.

+1. Build your application with the `build` command:

+ ```console

+ gradle build

+ ```

+1. Run your application with the `run` command:

+

+ ```console

+ gradle run

+ ```

+Here's a snippet of the expected output:

+```console

+Key content: For the Transition Period From

+Key content bounding region: [com.azure.ai.formrecognizer.models.BoundingRegion@14c053c6]

+Key content: to Commission File Number

+Key content bounding region: [com.azure.ai.formrecognizer.models.BoundingRegion@6c2d4cc6]

+Value content: 001-37845

+Value content bounding region: [com.azure.ai.formrecognizer.models.BoundingRegion@30865a90]

+Key content: (I.R.S. ID)

+Key content bounding region: [com.azure.ai.formrecognizer.models.BoundingRegion@6134ac4a]

+Value content: 91-1144442

+Value content bounding region: [com.azure.ai.formrecognizer.models.BoundingRegion@777c9dc9]

+Key content: Securities registered pursuant to Section 12(g) of the Act:

+Key content bounding region: [com.azure.ai.formrecognizer.models.BoundingRegion@71b1a49c]

+Value content: NONE

+```

+To view the entire output, visit the Azure samples repository on GitHub to view the [general document model output](https://github.com/Azure-Samples/cognitive-services-quickstart-code/blob/master/jav).

+ // sample document

+

+Here's a snippet of the expected output:

+```console

+ Table 0 has 5 rows and 3 columns.

+ Cell 'Title of each class', has row index 0 and column index 0.

+ Cell 'Trading Symbol', has row index 0 and column index 1.

+ Cell 'Name of exchange on which registered', has row index 0 and column index 2.

+ Cell 'Common stock, $0.00000625 par value per share', has row index 1 and column index 0.

+ Cell 'MSFT', has row index 1 and column index 1.

+ Cell 'NASDAQ', has row index 1 and column index 2.

+ Cell '2.125% Notes due 2021', has row index 2 and column index 0.

+ Cell 'MSFT', has row index 2 and column index 1.

+ Cell 'NASDAQ', has row index 2 and column index 2.

+ Cell '3.125% Notes due 2028', has row index 3 and column index 0.

+ Cell 'MSFT', has row index 3 and column index 1.

+ Cell 'NASDAQ', has row index 3 and column index 2.

+ Cell '2.625% Notes due 2033', has row index 4 and column index 0.

+ Cell 'MSFT', has row index 4 and column index 1.

+ Cell 'NASDAQ', has row index 4 and column index 2.

+```

+To view the entire output,visit the Azure samples repository on GitHub to view the [layout model output](https://github.com/Azure-Samples/cognitive-services-quickstart-code/blob/master/jav).

+ System.out.printf("Analyzed document has doc type %s with confidence : %.2f%n",

+Here's a snippet of the expected output:

+ -- Analyzing invoice 0 --

+ Analyzed document has doc type invoice with confidence : 1.00

+ Vendor Name: CONTOSO LTD., confidence: 0.92

+ Vendor address: 123 456th St New York, NY, 10001, confidence: 0.91

+ Customer Name: MICROSOFT CORPORATION, confidence: 0.84

+ Customer Address Recipient: Microsoft Corp, confidence: 0.92

+ Invoice ID: INV-100, confidence: 0.97

+ Invoice Date: 2019-11-15, confidence: 0.97

+To view the entire output, visit the Azure samples repository on GitHub to view the [prebuilt invoice model output](https://github.com/Azure-Samples/cognitive-services-quickstart-code/blob/master/jav)

+[Reference documentation](/javascript/api/@azure/ai-form-recognizer/?view=azure-node-preview&preserve-view=true) | [Library source code](https://github.com/Azure/azure-sdk-for-js/tree/@azure/ai-form-recognizer_4.0.0-beta.3/sdk/formrecognizer/ai-form-recognizer/) | [Package (npm)](https://www.npmjs.com/package/@azure/ai-form-recognizer/v/4.0.0-beta.3) | [Samples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4-bet)

+ * We recommend keeping `index.js` for the entry point name. The description, test command, GitHub repository, keywords, author, and license information are optional attributesΓÇöthey can be skipped for this project.

+ * After you've completed the prompts, a `package.json` file will be created in your form-recognizer-app directory.

+ npm install @azure/ai-form-recognizer@4.0.0-beta.3 @azure/identity

+## Build your application

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

+1. Open the `index.js` file in Visual Studio Code or your favorite IDE and select one of the following code samples to copy and paste into your application:

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

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

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

+> [!IMPORTANT]

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

+## Run your application

+Once you've added a code sample to your application, build and run your application:

+1. Navigate to the folder where you have your form recognizer application (form-recognizer-app).

+1. Type the following command in your terminal:

+ ```console

+ node index.js

+ ```

+**Add the following code sample to the `index.js` file. Make sure you update the key and endpoint variables with values from your Form Recognizer instance in the Azure portal:**

+ const { AzureKeyCredential, DocumentAnalysisClient } = require("@azure/ai-form-recognizer");

+ // set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal

+ const key = "<your-endpoint>";

+ const endpoint = "<your-key>";

+ // sample document

+ const formUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-layout.pdf"

+ async function main() {

+ // create your `DocumentAnalysisClient` instance and `AzureKeyCredential` variable

+ const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));

+ const poller = await client.beginAnalyzeDocuments("prebuilt-document", formUrl);

+ const {

+ keyValuePairs,

+ entities

+ } = await poller.pollUntilDone();

+ if (keyValuePairs.length <= 0) {

+ console.log("No key-value pairs were extracted from the document.");

+ } else {

+ console.log("Key-Value Pairs:");

+ for (const {

+ key,

+ value,

+ confidence

+ } of keyValuePairs) {

+ console.log("- Key :", `"${key.content}"`);

+ console.log(" Value:", `"${value?.content ?? "<undefined>"}" (${confidence})`);

+ }

+ }

+ if (entities.length <= 0) {

+ console.log("No entities were extracted from the document.");

+ } else {

+ console.log("Entities:");

+ for (const entity of entities) {

+ console.log(

+ `- "${entity.content}" ${entity.category} - ${entity.subCategory ?? "<none>"} (${

+ entity.confidence

+ })`

+ );

+ }

+ }

+ }

+ main().catch((error) => {

+ console.error("An error occurred:", error);

+ process.exit(1);

+ });

+```

+### General document model output

+Here's a snippet of the expected output:

+```console

+Key-Value Pairs:

+- Key : "For the Quarterly Period Ended"

+ Value: "March 31, 2020" (0.35)

+- Key : "From"

+ Value: "1934" (0.119)

+- Key : "to"

+ Value: "<undefined>" (0.317)

+- Key : "Commission File Number"

+ Value: "001-37845" (0.87)

+- Key : "(I.R.S. ID)"

+ Value: "91-1144442" (0.87)

+- Key : "Class"

+ Value: "Common Stock, $0.00000625 par value per share" (0.748)

+- Key : "Outstanding as of April 24, 2020"

+ Value: "7,583,440,247 shares" (0.838)

+Entities:

+- "$0.00000625" Quantity - Currency (0.8)

+- "MSFT" Organization - <none> (0.99)

+- "NASDAQ" Organization - StockExchange (0.99)

+- "2.125%" Quantity - Percentage (0.8)

+- "2021" DateTime - DateRange (0.8)

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

+**Add the following code sample to the `index.js` file. Make sure you update the key and endpoint variables with values from your Form Recognizer instance in the Azure portal:**

+ const { AzureKeyCredential, DocumentAnalysisClient } = require("@azure/ai-form-recognizer");

+ // set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal

+ const key = "<your-endpoint>";

+ const endpoint = "<your-key>";

+ // sample document

+ const formUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-layout.pdf"

+ async function main() {

+ const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));

+ const poller = await client.beginAnalyzeDocuments("prebuilt-layout", formUrl);

+ const {

+ pages,

+ tables

+ } = await poller.pollUntilDone();

+ if (pages.length <= 0) {

+ console.log("No pages were extracted from the document.");

+ } else {

+ console.log("Pages:");

+ for (const page of pages) {

+ console.log("- Page", page.pageNumber, `(unit: ${page.unit})`);

+ console.log(` ${page.width}x${page.height}, angle: ${page.angle}`);

+ console.log(` ${page.lines.length} lines, ${page.words.length} words`);

+ }

+ }

+ if (tables.length <= 0) {

+ console.log("No tables were extracted from the document.");

+ } else {

+ console.log("Tables:");

+ for (const table of tables) {

+ console.log(

+ `- Extracted table: ${table.columnCount} columns, ${table.rowCount} rows (${table.cells.length} cells)`

+ );

+ }

+ }

+ }

+ main().catch((error) => {

+ console.error("An error occurred:", error);

+ process.exit(1);

+ });

+```

+### Layout model output

+Here's a snippet of the expected output:

+```console

+Pages:

+- Page 1 (unit: inch)

+ 8.5x11, angle: 0

+ 69 lines, 425 words

+Tables:

+- Extracted table: 3 columns, 5 rows (15 cells)

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

+ // Using the PrebuiltModels object, rather than the raw model ID, adds strong typing to the model's output.

+ const { PrebuiltModels } = require("@azure/ai-form-recognizer");

+ // set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal

+ const key = "<your-endpoint>";

+ const endpoint = "<your-key>";

+ // sample document

+ const invoiceUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-invoice.pdf";

+ async function main() {

+ const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));

+ const poller = await client.beginAnalyzeDocuments(PrebuiltModels.Invoice, invoiceUrl);

+ const {

+ documents: [result]

+ } = await poller.pollUntilDone();

+ if (result) {

+ const invoice = result.fields;

+ console.log("Vendor Name:", invoice.vendorName?.value);

+ console.log("Customer Name:", invoice.customerName?.value);

+ console.log("Invoice Date:", invoice.invoiceDate?.value);

+ console.log("Due Date:", invoice.dueDate?.value);

+ console.log("Items:");

+ for (const {

+ properties: item

+ } of invoice.items?.values ?? []) {

+ console.log("-", item.productCode?.value ?? "<no product code>");

+ console.log(" Description:", item.description?.value);

+ console.log(" Quantity:", item.quantity?.value);

+ console.log(" Date:", item.date?.value);

+ console.log(" Unit:", item.unit?.value);

+ console.log(" Unit Price:", item.unitPrice?.value);

+ console.log(" Tax:", item.tax?.value);

+ console.log(" Amount:", item.amount?.value);

+ }

+ console.log("Subtotal:", invoice.subTotal?.value);

+ console.log("Previous Unpaid Balance:", invoice.previousUnpaidBalance?.value);

+ console.log("Tax:", invoice.totalTax?.value);

+ console.log("Amount Due:", invoice.amountDue?.value);

+ } else {

+ throw new Error("Expected at least one receipt in the result.");

+ }

+ }

+ main().catch((error) => {

+ console.error("An error occurred:", error);

+ process.exit(1);

+ });

+### Prebuilt model output

+Here's a snippet of the expected output:

+ Vendor Name: CONTOSO LTD.

+ Customer Name: MICROSOFT CORPORATION

+ Invoice Date: 2019-11-15T00:00:00.000Z

+ Due Date: 2019-12-15T00:00:00.000Z

+ Items:

+ - <no product code>

+ Description: Test for 23 fields

+ Quantity: 1

+ Date: undefined

+ Unit: undefined

+ Unit Price: 1

+ Tax: undefined

+ Amount: 100

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

+## Create your Python application

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

+## Run your application

+Once you've added a code sample to your application, build and run your application:

+1. Navigate to the folder where you have your **form_recognizer_quickstart.py** file.

+1. Type the following command in your terminal:

+ ```console

+ python form_recognizer_quickstart.py

+ ```

+Here's a snippet of the expected output:

+```console

+ -Key-value pairs found in document-

+ Key 'ΓÿÆ' found within 'Page #1: [0.6694, 1.7746], [0.7764, 1.7746], [0.7764, 1.8833], [0.6694, 1.8833]' bounding regions

+ Key 'QUARTERLY REPORT PURSUANT TO SECTION 13 OR 15(d) OF THE SECURITIES EXCHANGE ACT OF 1934' found within 'Page #1: [0.996, 1.7804], [7.8449, 1.7804], [7.8449, 2.0559], [0.996, 2.0559]' bounding regions

+ Value ':selected:' found within 'Page #1: [0.6694, 1.7746], [0.7764, 1.7746], [0.7764, 1.8833], [0.6694, 1.8833]' bounding regions

+ Key 'For the Quarterly Period Ended March 31, 2020' found within 'Page #1: [0.9982, 2.1626], [3.4543, 2.1626], [3.4543, 2.2665], [0.9982, 2.2665]' bounding regions

+ Value 'OR' found within 'Page #1: [4.1471, 2.2972], [4.3587, 2.2972], [4.3587, 2.4049], [4.1471, 2.4049]' bounding regions

+```

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

+Here's a snippet of the expected output:

+```console

+ -Analyzing layout from page #1-

+ Page has width: 8.5 and height: 11.0, measured with unit: inch

+ ...Line # 0 has word count 2 and text 'UNITED STATES' within bounding box '[3.4915, 0.6828], [5.0116, 0.6828], [5.0116, 0.8265], [3.4915, 0.8265]'

+ ......Word 'UNITED' has a confidence of 1.0

+ ......Word 'STATES' has a confidence of 1.0

+ ...Line # 1 has word count 4 and text 'SECURITIES AND EXCHANGE COMMISSION' within bounding box '[2.1937, 0.9061], [6.297, 0.9061], [6.297, 1.0498], [2.1937, 1.0498]'

+ ......Word 'SECURITIES' has a confidence of 1.0

+ ......Word 'AND' has a confidence of 1.0

+ ......Word 'EXCHANGE' has a confidence of 1.0

+ ......Word 'COMMISSION' has a confidence of 1.0

+ ...Line # 2 has word count 3 and text 'Washington, D.C. 20549' within bounding box '[3.4629, 1.1179], [5.031, 1.1179], [5.031, 1.2483], [3.4629, 1.2483]'

+ ......Word 'Washington,' has a confidence of 1.0

+ ......Word 'D.C.' has a confidence of 1.0

+```

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

+Here's a snippet of the expected output:

+ --Recognizing invoice #1--

+ Vendor Name: CONTOSO LTD. has confidence: 0.919

+ Vendor Address: 123 456th St New York, NY, 10001 has confidence: 0.907

+ Vendor Address Recipient: Contoso Headquarters has confidence: 0.919

+ Customer Name: MICROSOFT CORPORATION has confidence: 0.84

+ Customer Id: CID-12345 has confidence: 0.956

+ Customer Address: 123 Other St, Redmond WA, 98052 has confidence: 0.909

+ Customer Address Recipient: Microsoft Corp has confidence: 0.917

+ Invoice Id: INV-100 has confidence: 0.972

+ Invoice Date: 2019-11-15 has confidence: 0.971

+ Invoice Total: CurrencyValue(amount=110.0, symbol=$) has confidence: 0.97

+ Due Date: 2019-12-15 has confidence: 0.973

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

+* 🆕 Read—Analyze and extract printed and handwritten text lines, words, locations, and detected languages.

+* LayoutΓÇöAnalyze and extract tables, lines, words, and selection marks from documents, without the need to train a model.

+Form Recognizer v3.0 consolidates the analyze document (POST) and get results (GET) operations for layout, prebuilt models, and custom models into a single pair of operations by assigningΓÇ»`modelIds` to the POST and GET operations:

+* [PowerShell version 7.*+](/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2&preserve-view=true), or a similar command-line application.

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

+curl -v -i POST "{endpoint}/formrecognizer/documentModels/prebuilt-document:analyze?api-version=2022-01-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

+You'll receive a `202 (Success)` response that includes an **Operation-Location** header. The value of this header contains a result ID that can be queried to get the status of the asynchronous operation:

+curl -v -X GET "{endpoint}/formrecognizer/documentModels/prebuilt-document/analyzeResults/{resultId}?api-version=2022-01-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

+curl -v -i POST "{endpoint}/formrecognizer/documentModels/prebuilt-layout:analyze?api-version=2022-01-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

+You'll receive a `202 (Success)` response that includes an **Operation-Location** header. The value of this header contains a result ID that can be queried to get the status of the asynchronous operation:

+curl -v -X GET "{endpoint}/formrecognizer/documentModels/prebuilt-layout/analyzeResults/{resultId}?api-version=2022-01-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

+curl -v -i POST "{endpoint}/formrecognizer/documentModels/prebuilt-invoice:analyze?api-version=2022-01-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

+You'll receive a `202 (Success)` response that includes an **Operation-Location** header. The value of this header contains a result ID that can be queried to get the status of the asynchronous operation:

+curl -v -X GET "{endpoint}/formrecognizer/documentModels/prebuilt-invoice/analyzeResults/{resultId}?api-version=2022-01-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

+curl -v -X GET "{endpoint}/formrecognizer/documentModels?api-version=2022-01-30-preview"

+curl -v -X GET "{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-01-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

+curl -v -X DELETE "{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-01-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

+## Version 1.11 - September 2021

+### Fixed

+- The agent can now be installed on Windows systems with the [System objects: Require case insensitivity for non-Windows subsystems](/windows/security/threat-protection/security-policy-settings/system-objects-require-case-insensitivity-for-non-windows-subsystems) policy set to Disabled.

+- The guest configuration policy agent will now automatically retry if an error is encountered during service start or restart events.

+- Fixed an issue that prevented guest configuration audit policies from successfully executing on Linux machines.

+## Version 1.16 - March 2022

+### New features

+- You can now granularly control which extensions are allowed to be deployed to your server and whether or not Guest Configuration should be enabled. See [local agent controls to enable or disable capabilities](security-overview.md#local-agent-security-controls) for more information.

+### Fixed

+- The "Arc" proxy bypass keyword no longer includes Azure Active Directory endpoints on Linux. Azure Storage endpoints for extension downloads are now included with the "Arc" keyword.

+ - On-demand network check now available using `azcmagent check`

+* **check** - To troubleshoot network connectivity issues

+### Check

+This parameter allows you to run the network connectivity tests to troubleshoot networking issues between the agent and Azure services. The network connectivity check includes all [required Azure Arc network endpoints](network-requirements.md#urls), but does not include endpoints accessed by extensions you install.

+When running a network connectivity check, you must provide the name of the Azure region (for example, eastus) that you want to test. It's also recommended to use the `--verbose` parameter to see the results of both successful and unsuccessful tests.

+`azcmagent check --location <regionName> --verbose`

+## Local agent security controls

+Starting with agent version 1.16, you can optionally limit the extensions that can be installed on your server and disable Guest Configuration. These controls can be useful when connecting servers to Azure that need to be monitored or secured by Azure, but should not allow arbitrary management capabilities like running scripts with Custom Script Extension or configuring settings on the server with Guest Configuration.

+These security controls can only be configured by running a command on the server itself and cannot be modified from Azure. This approach preserves the server admin's intent when enabling remote management scenarios with Azure Arc, but also means that changing the setting is more difficult if you later decide to change them. This feature is intended for particularly sensitive servers (for example, Active Directory Domain Controllers, servers that handle payment data, and servers subject to strict change control measures). In most other cases, it is not necessary to modify these settings.

+### Extension allowlists and blocklists

+To limit which [extensions](manage-vm-extensions.md) can be installed on your server, you can configure lists of the extensions you wish to allow and block on the server. The extension manager will evaluate all requests to install, update, or upgrade extensions against the allowlist and blocklist to determine if the extension can be installed on the server. Delete requests are always allowed.

+The most secure option is to explicitly allow the extensions you expect to be installed. Any extension not in the allowlist is automatically blocked. To configure the Azure Connected Machine agent to allow only the Log Analytics Agent for Linux and the Dependency Agent for Linux, run the following command on each server:

+```bash

+azcmagent config set extensions.allowlist "Microsoft.EnterpriseCloud.Monitoring/OMSAgentForLinux,Microsoft.Azure.Monitoring.DependencyAgent/DependencyAgentLinux"

+```

+You can block one or more extensions by adding them to the blocklist. If an extension is present in both the allowlist and blocklist, it will be blocked. To block the Custom Script extension for Linux, run the following command:

+```bash

+azcmagent config set extensions.blocklist "Microsoft.Azure.Extensions/CustomScript"

+```

+Extensions are specified by their publisher and type, separated by a forward slash. See the list of the [most common extensions](manage-vm-extensions.md) in the docs or list the VM extensions already installed on your server in the [portal](manage-vm-extensions-portal.md#list-extensions-installed), [Azure PowerShell](manage-vm-extensions-powershell.md#list-extensions-installed), or [Azure CLI](manage-vm-extensions-cli.md#list-extensions-installed).

+The table below describes the behavior when performing an extension operation against an agent that has the allowlist or blocklist configured.

+| Operation | In the allowlist | In the blocklist | In both the allowlist and blocklist | Not in any list, but an allowlist is configured |

+|--|--|--|--|

+| Install extension | Allowed | Blocked | Blocked | Blocked |

+| Update (reconfigure) extension | Allowed | Blocked | Blocked | Blocked |

+| Upgrade extension | Allowed | Blocked | Blocked | Blocked |

+| Delete extension | Allowed | Allowed | Allowed | Allowed |

+> [!IMPORTANT]

+> If an extension is already installed on your server before you configure an allowlist or blocklist, it will not automatically be removed. It is your responsibility to delete the extension from Azure to fully remove it from the machine. Delete requests are always accepted to accommodate this scenario. Once deleted, the allowlist and blocklist will determine whether or not to allow future install attempts.

+### Enable or disable Guest Configuration

+Azure Policy's Guest Configuration feature enables you to audit and configure settings on your server from Azure. You can disable Guest Configuration from running on your server if you don't want to allow this functionality by running the following command:

+```bash

+azcmagent config set guestconfiguration.enabled false

+```

+When Guest Configuration is disabled, any Guest Configuration policies assigned to the machine in Azure will report as non-compliant. Consider [creating an exemption](../../governance/policy/concepts/exemption-structure.md) for these machines or [changing the scope](../../governance/policy/concepts/assignment-structure.md#excluded-scopes) of your policy assignments if you don't want to see these machines reported as non-compliant.

+### Locked down machine best practices

+When configuring the Azure Connected Machine agent with a reduced set of capabilities, it is important to consider the mechanisms that someone could use to remove those restrictions and implement appropriate controls. Anybody capable of running commands as an administrator or root user on the server can change the Azure Connected Machine agent configuration. Extensions and guest configuration policies execute in privileged contexts on your server, and as such may be able to change the agent configuration. If you apply these security controls to lock down the agent, Microsoft recommends the following best practices to ensure only local server admins can update the agent configuration:

+* Use allowlists for extensions instead of blocklists whenever possible.

+* Don't include the Custom Script Extension in the extension allowlist to prevent execution of arbitrary scripts that could change the agent configuration.

+* Disable Guest Configuration to prevent the use of custom Guest Configuration policies that could change the agent configuration.

+### Example configuration for monitoring and security scenarios

+It's common to use Azure Arc to monitor your servers with Azure Monitor and Microsoft Sentinel and secure them with Microsoft Defender for Cloud. The following configuration samples can help you configure the Azure Arc agent to only allow these scenarios.

+#### Azure Monitor Agent only

+On your Windows servers, run the following commands in an elevated command console:

+```powershell

+azcmagent config set extensions.allowlist "Microsoft.Azure.Monitor/AzureMonitorWindowsAgent"

+azcmagent config set guestconfiguration.enabled false

+```

+On your Linux servers, run the following commands:

+```bash

+sudo azcmagent config set extensions.allowlist "Microsoft.Azure.Monitor/AzureMonitorLinuxAgent"

+sudo azcmagent config set guestconfiguration.enabled false

+```

+#### Log Analytics and dependency (Azure Monitor VM Insights) only

+This configuration is for the legacy Log Analytics agents and the dependency agent.

+On your Windows servers, run the following commands in an elevated console:

+```powershell

+azcmagent config set extensions.allowlist "Microsoft.EnterpriseCloud.Monitoring/MicrosoftMonitoringAgent,Microsoft.Azure.Monitoring.DependencyAgent/DependencyAgentWindows"

+azcmagent config set guestconfiguration.enabled false

+```

+On your Linux servers, run the following commands:

+```bash

+sudo azcmagent config set extensions.allowlist "Microsoft.EnterpriseCloud.Monitoring/OMSAgentForLinux,Microsoft.Azure.Monitoring.DependencyAgent/DependencyAgentLinux"

+sudo azcmagent config set guestconfiguration.enabled false

+```

+#### Monitoring and security

+Microsoft Defender for Cloud enables additional extensions on your server to identify vulnerable software on your server and enable Microsoft Defender for Endpoint (if configured). Microsoft Defender for Cloud also uses Guest Configuration for its regulatory compliance feature. Since a custom Guest Configuration assignment could be used to undo the agent limitations, you should carefully evaluate whether or not you need the regulatory compliance feature and, as a result, Guest Configuration to be enabled on the machine.

+On your Windows servers, run the following commands in an elevated command console:

+```powershell

+azcmagent config set extensions.allowlist "Microsoft.EnterpriseCloud.Monitoring/MicrosoftMonitoringAgent,Qualys/WindowsAgent.AzureSecurityCenter,Microsoft.Azure.AzureDefenderForServers/MDE.Windows,Microsoft.Azure.AzureDefenderForSQL/AdvancedThreatProtection.Windows"

+azcmagent config set guestconfiguration.enabled true

+```

+On your Linux servers, run the following commands:

+```bash

+sudo azcmagent config set extensions.allowlist "Microsoft.EnterpriseCloud.Monitoring/OMSAgentForLinux,Qualys/LinuxAgent.AzureSecurityCenter,Microsoft.Azure.AzureDefenderForServers/MDE.Linux"

+sudo azcmagent config set guestconfiguration.enabled true

+```

+ Title: Drawing package requirements in Microsoft Azure Maps Creator

+| Term | Definition |

+|:|:|

+| Layer | An AutoCAD DWG layer from the drawing file. |

+| Entity| An AutoCAD DWG entity from the drawing file. |

+|Feature| An instance of an object produced from the Conversion service that combines a geometry with metadata information. |

+|Feature classes| A common blueprint for features. For example, a *unit* is a feature class, and an *office* is a feature. |

+ - Levels

+ - Units

+ - Zones

+ - Openings

+ - Walls

+ - Vertical penetrations

+ - room

+ - structure

+ - wall

+ - opening.door

+ - zone

+ - facility

+| Object | Required | Description |

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

+| `name` |string| true | Name of building. |

+| `streetAddress`|string|false| Address of building. |

+|`unit` |string| false | Unit in building. |

+|`locality` |string | false | Name of a city, town, area, neighborhood, or region.|

+|`adminDivisions`|JSON array of strings | false| An array containing address designations. For example: (Country, State) Use ISO 3166 country codes and ISO 3166-2 state/territory codes. |

+|`postalCode`|string| false | The mail sorting code. |

+|`hoursOfOperation` |string|false| Adheres to the [OSM Opening Hours](https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification) format. |

+|`phone` |string| false | Phone number associated with the building. |

+|`website` |string| false | Website associated with the building. |

+|`nonPublic`|bool| false | Flag specifying if the building is open to the public. |

+|`anchorLatitude`|numeric|false | Latitude of a facility anchor (pushpin). |

+|`anchorLongitude`|numeric |false | Longitude of a facility anchor (pushpin). |

+|`anchorHeightAboveSeaLevel`| numeric | false | Height of the facility's ground floor above sea level, in meters. |

+|`defaultLevelVerticalExtent` numeric | false | Default height (thickness) of a level of this facility to use when a level's `verticalExtent` is undefined. |

+| Property | Type | Required | Description |

+|--|-|-|-|

+|`levelName`|string |true |Descriptive level name. For example: Floor 1, Lobby, Blue Parking, or Basement.|

+|`ordinal` |integer|true | Determines the vertical order of levels. Every facility must have a level with ordinal 0. |

+|`heightAboveFacilityAnchor`| numeric | false |Level height above the anchor in meters. |

+|`verticalExtent`|numeric|false| Floor-to-ceiling height (thickness) of the level in meters. |

+|`filename` |string |true |File system path of the CAD drawing for a building level. It must be relative to the root of the building's zip file. |

+|`lat`|numeric|true|Decimal representation of degrees latitude at the facility drawing's origin. The origin coordinates must be in WGS84 Web Mercator (`EPSG:3857`).|

+|`lon`|numeric|true|Decimal representation of degrees longitude at the facility drawing's origin. The origin coordinates must be in WGS84 Web Mercator (`EPSG:3857`).|

+|`angle`|numeric|true|The clockwise angle, in degrees, between true north and the drawing's vertical (Y) axis.|

+| Property | Type | Required | Description |

+|--||-||

+|`exterior` |array of strings|true |Names of layers that define the exterior building profile.|

+|`unit` |array of strings|false|Names of layers that define units. |

+|`wall` |array of strings|false|Names of layers that define walls. |

+|`door` |array of strings|false|Names of layers that define doors. |

+|`unitLabel`|array of strings|false|Names of layers that define names of units. |

+|`zone` |array of strings|false|Names of layers that define zones. |

+|`zoneLabel`|array of strings|false|Names of layers that define names of zones. |

+|`unitName`|string|true|Name of unit to associate with this `unitProperty` record. This record is only valid when a label matching `unitName` is found in the `unitLabel` layers. |

+|`categoryName`|string|false|Purpose of the unit. A list of values that the provided rendering styles can make use of is available [here](https://atlas.microsoft.com/sdk/javascript/indoor/0.1/categories.json).|

+|`occupants`|array of directoryInfo objects |false |List of occupants for the unit. |

+|`nameAlt`|string|false|Alternate name of the unit. |

+|`nameSubtitle`|string|false|Subtitle of the unit. |

+|`addressRoomNumber`|string|false|Room, unit, apartment, or suite number of the unit.|

+|`verticalPenetrationCategory`|string|false| When this property is defined, the resulting feature is a vertical penetration (VRT) rather than a unit. You can use vertical penetrations to go to other vertical penetration features in the levels above or below it. Vertical penetration is a [Category](https://aka.ms/pa-indoor-spacecategories) name. If this property is defined, the `categoryName` property is overridden with `verticalPenetrationCategory`. |

+|zoneName |string |true |Name of zone to associate with `zoneProperty` record. This record is only valid when a label matching `zoneName` is found in the `zoneLabel` layer of the zone. |

+|categoryName| string| false |Purpose of the zone. A list of values that the provided rendering styles can make use of is available [here](https://atlas.microsoft.com/sdk/javascript/indoor/0.1/categories.json).|

+|zoneNameAlt| string| false |Alternate name of the zone. |

+|zoneNameSubtitle| string | false |Subtitle of the zone. |

+|zoneSetId| string | false | Set ID to establish a relationship among multiple zones so that they can be queried or selected as a group. For example, zones that span multiple levels. |

+Below is the manifest file for the sample Drawing package. Go to the [Sample Drawing package for Azure Maps Creator](https://github.com/Azure-Samples/am-creator-indoor-data-examples) on GitHub to download the entire package.

+> [Creator for indoor maps](creator-indoor-maps.md)

+> [Indoor maps dynamic styling](indoor-map-dynamic-styling.md)

+> Azure Monitor recently launched a new agent, the [Azure Monitor agent](./azure-monitor-agent-overview.md), that provides all capabilities necessary to collect guest operating system monitoring data. **Use this new agent if you don't require [these current limitations](./azure-monitor-agent-overview.md#current-limitations)**, as it consolidates the features of all the legacy agents listed below and provides additional benefits. If you do require the limitations today, you may continue using the other legacy agents listed below until **August 2024**. [Learn more](./azure-monitor-agent-overview.md)

+The following tables provide a quick comparison of the telemetry agents for Windows and Linux. Further detail on each is provided in the section below.

+When compared with the legacy agents, the Azure Monitor Agent has [these limitations currently](./azure-monitor-agent-overview.md#current-limitations).

+The legacy [Log Analytics agent](./log-analytics-agent.md) collects monitoring data from the guest operating system and workloads of virtual machines in Azure, other cloud providers, and on-premises machines. It sends data to a Log Analytics workspace. The Log Analytics agent is the same agent used by System Center Operations Manager, and you can multihome agent computers to communicate with your management group and Azure Monitor simultaneously. This agent is also required by certain insights in Azure Monitor and other services in Azure.

+ Title: Using data collection endpoints with Azure Monitor agent

+# Using data collection endpoints with Azure Monitor agent

+See [Data collection endpoints in Azure Monitor](../essentials/data-collection-endpoint-overview.md) for details on data collection endpoints and how to create them.

+The Azure Monitor agent is meant to replace the following legacy monitoring agents that are currently used by Azure Monitor to collect guest data from virtual machines ([view known gaps](../faq.yml)):

+| [Microsoft Sentinel](../../sentinel/overview.md) | <ul><li>Linux Syslog CEF (Common Event Format): Private preview</li><li>Windows Forwarding Event (WEF): [Public preview](../../sentinel/data-connectors-reference.md#windows-forwarded-events-preview)</li><li>Windows Security Events: [Generally available](../../sentinel/connect-windows-security-events.md?tabs=AMA)</li></ul> | <ul><li>[Sign-up link](https://aka.ms/AMAgent)</li><li>No sign-up needed </li><li>No sign-up needed</li></ul> |

+2. After the values for the *settings* and *protectedSettings* parameters are determined, **provide these additional parameters** when you deploy the Azure Monitor agent by using PowerShell commands. Refer the following examples.

+$settingsString = '{"proxy":{"mode":"application","address":"http://[address]:[port]","auth": true}}';

+$protectedSettingsString = '{"proxy":{"username":"[username]","password": "[password]"}}';

+Set-AzVMExtension -ExtensionName AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion 1.0 -Settings $settingsString -ProtectedSettings $protectedSettingsString

+$settingsHashtable = @{"proxy":{"mode":"application","address":"http://[address]:[port]","auth": true}};

+Set-AzVMExtension -ExtensionName AzureMonitorLinuxAgent -ExtensionType AzureMonitorLinuxAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion 1.5 -Settings $settingsString -ProtectedSettings $protectedSettingsString

+$settingsString = '{"proxy":{"mode":"application","address":"http://[address]:[port]","auth": true}}';

+$protectedSettingsString = '{"proxy":{"username":"[username]","password": "[password]"}}';

+New-AzConnectedMachineExtension -Name AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -MachineName <arc-server-name> -Location <arc-server-location> -Settings $settingsString -ProtectedSettings $protectedSettingsString

+$settingsString = '{"proxy":{"mode":"application","address":"http://[address]:[port]","auth": true}}';

+$protectedSettingsString = '{"proxy":{"username":"[username]","password": "[password]"}}';

+New-AzConnectedMachineExtension -Name AzureMonitorLinuxAgent -ExtensionType AzureMonitorLinuxAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -MachineName <arc-server-name> -Location <arc-server-location> -Settings $settingsString -ProtectedSettings $protectedSettingsString

+### Private link configuration using data collection endpoints

+* [.NET reference](/dotnet/api/overview/azure/insights)

+* [.NET](https://github.com/Microsoft/ApplicationInsights-dotnet)

+### [.NET](#tab/net)

+Below is an example of configuring the `TelemetryConfiguration` using .NET Core:

+### [.NET](#tab/net)

+- .NET v2.12.0

+.NET Core Explicitly Set:

+.NET Core config.json:

+ Title: Data collection endpoints in Azure Monitor

+# Data collection endpoints in Azure Monitor

+- [Azure Monitor agent](../agents/data-collection-rule-azure-monitor-agent.md)

+* East US 2

+* [Manual Recovery Guide for SAP Oracle 19c on Azure VMs from Azure NetApp Files snapshot with AzAcSnap](https://techcommunity.microsoft.com/t5/running-sap-applications-on-the/manual-recovery-guide-for-sap-oracle-19c-on-azure-vms-from-azure/ba-p/3242408)

+* [Reverting a volume using snapshot revert](snapshots-revert-volume.md) is not supported on Azure NetApp Files volumes that have backups.

+## Considerations

+* Reverting a volume using snapshot revert is not supported on [Azure NetApp Files volumes that have backups](backup-requirements-considerations.md).

+* [Azure NetApp Files Snapshot Overview](https://anfcommunity.com/2021/01/31/azure-netapp-files-snapshot-overview/)

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [loops](../bicep/loops.md).

+- To learn how to deploy your template, see [Deploy resources with ARM templates and Azure PowerShell](deploy-powershell.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [loops](../bicep/loops.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [loops](../bicep/loops.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [loops](../bicep/loops.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [How to deploy resources with Bicep and Azure CLI](../bicep/deploy-cli.md).

+```

+* For tips on resolving common deployment errors, see [Troubleshoot common Azure deployment errors with Azure Resource Manager](common-deployment-errors.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [Deploy resources with Bicep and Azure PowerShell](../bicep/deploy-powershell.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [modules](../bicep/modules.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [parameter files](../bicep/parameter-files.md).

+- For more information about using values from a key vault, see [Use Azure Key Vault to pass secure parameter value during deployment](key-vault-parameter.md).

+> [!TIP]

+> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [resource dependencies](../bicep/resource-dependencies.md).

+* For a list of the available functions in a template, see [ARM template functions](template-functions.md).

+In Bicep, see [parameters](../bicep/file.md#parameters).

+In Bicep, see [variables](../bicep/file.md#variables).

+In Bicep, user-defined functions aren't supported. Bicep does support a variety of [functions](../bicep/bicep-functions.md) and [operators](../bicep/operators.md).

+In Bicep, see [resources](../bicep/file.md#resources).

+In Bicep, see [outputs](../bicep/file.md#outputs).

+In Bicep, see [comments](../bicep/file.md#comments).

+In Bicep, see [multi-line strings](../bicep/file.md#multi-line-strings).

+- **Applications that have suboptimal queries**

+- **Applications that have suboptimal data access design**

+The key insight is that the IO capacity of a shared, commodity system is more limited than that of a dedicated server machine. There's a premium on minimizing unnecessary IO to take maximum advantage of the system in the resources of each compute size of the service tiers. Appropriate physical database design choices can significantly improve the latency for individual queries, improve the throughput of concurrent requests handled per scale unit, and minimize the costs required to satisfy the query.

+For more information about tuning indexes using missing index requests, see [Tune nonclustered indexes with missing index suggestions](/sql/relational-databases/indexes/tune-nonclustered-missing-index-suggestions).

+An example that is common in SQL Server and which also applies to Azure SQL Database and Azure SQL Managed Instance is how the query optimizer "sniffs" parameters. During compilation, the query optimizer evaluates the current value of a parameter to determine whether it can generate a more optimal query plan. Although this strategy often can lead to a query plan that is significantly faster than a plan compiled without known parameter values, currently it works imperfectly both in SQL Server, in Azure SQL Database, and Azure SQL Managed Instance. Sometimes the parameter is not sniffed, and sometimes the parameter is sniffed but the generated plan is suboptimal for the full set of parameter values in a workload. Microsoft includes query hints (directives) so that you can specify intent more deliberately and override the default behavior of parameter sniffing. Often, if you use hints, you can fix cases in which the default SQL Server, Azure SQL Database, and Azure SQL Managed Instance behavior is imperfect for a specific customer workload.

+The next example demonstrates how the query processor can generate a plan that is suboptimal both for performance and resource requirements. This example also shows that if you use a query hint, you can reduce query run time and resource requirements for your database:

+The setup code creates a table that has skewed data distribution. The optimal query plan differs based on which parameter is selected. Unfortunately, the plan caching behavior doesn't always recompile the query based on the most common parameter value. So, it's possible for a suboptimal plan to be cached and used for many values, even when a different plan might be a better plan choice on average. Then the query plan creates two stored procedures that are identical, except that one has a special query hint.

+Because we executed the procedure by using the value 1, the resulting plan was optimal for the value 1 but was suboptimal for all other values in the table. The result likely isn't what you would want if you were to pick each plan randomly, because the plan performs more slowly and uses more resources.

+> Although the volume in this example is intentionally small, the effect of suboptimal parameters can be substantial, especially on larger databases. The difference, in extreme cases, can be between seconds for fast cases and hours for slow cases.

+- Learn to [Diagnose and troubleshoot high CPU on Azure SQL Database](high-cpu-diagnose-troubleshoot.md)

+- [Tune nonclustered indexes with missing index suggestions](/sql/relational-databases/indexes/tune-nonclustered-missing-index-suggestions)

+ Title: Types of query performance issues

+description: Learn about types of query performance issues in Azure SQL Database and Azure SQL Managed Instance, and how to identify and resolve queries with these issues.

+# Detectable types of query performance bottlenecks in Azure SQL Database and Azure SQL Managed Instance

+You can use [Intelligent Insights](database/intelligent-insights-troubleshoot-performance.md#detectable-database-performance-patterns) or SQL Server [DMVs](database/monitoring-with-dmvs.md) to detect these types of performance bottlenecks.

+- Contention related to tempdb usage

+ - Review recommendations in the [Database Advisor](database/database-advisor-implement-performance-recommendations.md) for single and pooled databases in Azure SQL Database. You may also choose to enable [automatic tuning options for tuning indexes](database/automatic-tuning-overview.md#automatic-tuning-options) for Azure SQL Database.

+ - Missing indexes in DMVs and query execution plans. This article shows you how to [detect and tune nonclustered indexes using missing index requests](/sql/relational-databases/indexes/tune-nonclustered-missing-index-suggestions).

+- Try to [update statistics](/sql/t-sql/statements/update-statistics-transact-sql) or [rebuild indexes](/sql/relational-databases/indexes/reorganize-and-rebuild-indexes) to get the better plan. Enable [automatic plan correction](../azure-sql/database/automatic-tuning-overview.md) in Azure SQL Database or Azure SQL Managed Instance to automatically mitigate these problems.

+- As an advanced troubleshooting step, use [Query Store hints](/sql/relational-databases/performance/query-store-hints) to apply [query hints](/sql/t-sql/queries/hints-transact-sql-query) using the Query Store, without making code changes.

+- **Tempdb problems**

+ If the workload uses temporary tables or there are `tempdb` spills in the plans, the queries might have a problem with `tempdb` throughput. To investigate further, review [identify tempdb issues](database/monitoring-with-dmvs.md#identify-tempdb-performance-issues).

+- [Tune nonclustered indexes with missing index suggestions](/sql/relational-databases/indexes/tune-nonclustered-missing-index-suggestions)

+# Connect to a VM using a native client

+

+ The extension can be installed by running, ```az extension add --name ssh```. To sign in using an SSH key pair, use the following example.

+ The extension can be installed by running, ```az extension add --name ssh```. To sign in using an SSH key pair, use the following example.

+# File upload and download to a VM using a native client

+Speech-to-text, also known as speech recognition, enables real-time transcription of audio streams into text. Your applications, tools, or devices can consume, display, and take action on this text as command input.

+This feature uses the same recognition technology that Microsoft uses for Cortana and Office products. It seamlessly works with the <a href="./speech-translation.md">translation </a> and <a href="./text-to-speech.md">text-to-speech </a> offerings of the Speech service. For a full list of available speech-to-text languages, see [Language and voice support for the Speech service](language-support.md#speech-to-text).

+The speech-to-text feature defaults to using the Universal Language Model. This model was trained through Microsoft-owned data and is deployed in the cloud. It's optimal for conversational and dictation scenarios.

+In addition to the standard Speech service model, you can create custom models. Customization helps to overcome speech recognition barriers such as speaking style, vocabulary, and background noise. For more information, see [Custom Speech](./custom-speech-overview.md).

+- <a href="https://aka.ms/csspeech/csharpref">C# SDK </a>

+- <a href="https://aka.ms/csspeech/cppref">C++ SDK </a>

+- <a href="https://aka.ms/csspeech/javaref">Java SDK </a>

+- <a href="https://aka.ms/csspeech/pythonref">Python SDK</a>

+- <a href="https://aka.ms/csspeech/javascriptref">JavaScript SDK</a>

+- <a href="https://aka.ms/csspeech/objectivecref">Objective-C SDK </a>

+- <a href="https://westus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0">REST API: Batch transcription and customization </a>

+In this overview, you learn about the benefits and capabilities of the text-to-speech feature of the Speech service, which is part of Azure Cognitive Services.

+Text-to-speech includes the following features:

+| Feature | Summary | Demo |

+| | | |

+The patterns of stress and intonation in spoken language are called _prosody_. Traditional text-to-speech systems break down prosody into separate linguistic analysis and acoustic prediction steps that are governed by independent models. That can result in muffled, buzzy voice synthesis.

+ - Enhance in-car navigation systems.

+* **Fine-tuning text-to-speech output with SSML**: Speech Synthesis Markup Language (SSML) is an XML-based markup language that's used to customize text-to-speech outputs. With SSML, you can adjust pitch, add pauses, improve pronunciation, change speaking rate, adjust volume, and attribute multiple voices to a single document.

+* **Visemes**: [Visemes](how-to-speech-synthesis-viseme.md) are the key poses in observed speech, including the position of the lips, jaw, and tongue in producing a particular phoneme. Visemes have a strong correlation with voices and phonemes.

+>

+> If your applications, tools, or products are using any of the standard voices and custom voices, you must migrate to the neural version. For more information, see [Migrate to neural voices](migration-overview-neural-voice.md).

+- Form Recognizer

+When multiple components are defined for an entity, their predictions may overlap. When an overlap occurs, each entity's final prediction is determined by one of the following options.

+As you use orchestration workflow in your applications, see the following reference documentation and samples for Azure Cognitive Services for Language:

+> | [Orchestration workflow](orchestration-workflow/overview.md) | Train language models to connect your applications to question answering, conversational language understanding, and LUIS | * [Language Studio](orchestration-workflow/quickstart.md?pivots=language-studio) <br> * [REST API](orchestration-workflow/quickstart.md?pivots=rest-api) |

+### Leg between SBC and Cloud Media Processor.

+A dedicated host for Azure Container Instances provides [double encryption at rest](../virtual-machines/windows/disk-encryption.md#double-encryption-at-rest) for your container data when it is persisted by the service to the cloud. This encryption protects your data to help meet your organization's security and compliance requirements. ACI also gives you the option to [encrypt this data with your own key](container-instances-encrypt-data.md), giving you greater control over the data related to your ACI deployments.

+> Using the dedicated sku is only available in **API version 2019-12-01 or later**. Specify this API version or a more recent one in your deployment template.

+ Title: Quickstart - create a container instance - Bicep

+description: In this quickstart, you use a Bicep file to quickly deploy a containerized web app that runs in an isolated Azure container instance.

+# Quickstart: Deploy a container instance in Azure using Bicep

+Use Azure Container Instances to run serverless Docker containers in Azure with simplicity and speed. Deploy an application to a container instance on-demand when you don't need a full container orchestration platform like Azure Kubernetes Service. In this quickstart, you use a Bicep file to deploy an isolated Docker container and make its web application available with a public IP address.

+## Prerequisites

+If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/free/) account before you begin.

+## Review the Bicep file

+The Bicep file used in this quickstart is from [Azure Quickstart Templates](https://azure.microsoft.com/resources/templates/aci-linuxcontainer-public-ip/).

+The following resource is defined in the Bicep file:

+* **[Microsoft.ContainerInstance/containerGroups](/azure/templates/microsoft.containerinstance/containergroups)**: create an Azure container group. This Bicep file defines a group consisting of a single container instance.

+More Azure Container Instances template samples can be found in the [quickstart template gallery](https://azure.microsoft.com/resources/templates/?resourceType=Microsoft.Containerinstance&pageNumber=1&sort=Popular).

+## Deploy the Bicep file

+1. Save the Bicep file as **main.bicep** to your local computer.

+1. Deploy the Bicep file using either Azure CLI or Azure PowerShell.

+ # [CLI](#tab/CLI)

+ ```azurecli

+ az group create --name exampleRG --location eastus

+ az deployment group create --resource-group exampleRG --template-file main.bicep

+ ```

+ # [PowerShell](#tab/PowerShell)

+ ```azurepowershell

+ New-AzResourceGroup -Name exampleRG -Location eastus

+ New-AzResourceGroupDeployment -ResourceGroupName exampleRG -TemplateFile ./main.bicep

+ ```

+

+ When the deployment finishes, you should see a message indicating the deployment succeeded.

+## Review deployed resources

+Use the Azure portal, Azure CLI, or Azure PowerShell to list the deployed resources in the resource group.

+# [CLI](#tab/CLI)

+```azurecli-interactive

+az resource list --resource-group exampleRG

+```

+# [PowerShell](#tab/PowerShell)

+```azurepowershell-interactive

+Get-AzResource -ResourceGroupName exampleRG

+```

+### View container logs

+Viewing the logs for a container instance is helpful when troubleshooting issues with your container or the application it runs. Use the Azure portal, Azure CLI, or Azure PowerShell to view the container's logs.

+# [CLI](#tab/CLI)

+```azurecli-interactive

+az container logs --resource-group exampleRG --name acilinuxpublicipcontainergroup

+```

+# [PowerShell](#tab/PowerShell)

+```azurepowershell-interactive

+Get-AzContainerInstanceLog -ResourceGroupName exampleRG -ContainerGroupName acilinuxpublicipcontainergroup -ContainerName acilinuxpublicipcontainergroup

+```

+> [!NOTE]

+> It may take a few minutes for the HTTP GET request to generate.

+## Clean up resources

+When no longer needed, use the Azure portal, Azure CLI, or Azure PowerShell to delete the container and all of the resources in the resource group.

+# [CLI](#tab/CLI)

+```azurecli-interactive

+az group delete --name exampleRG

+```

+# [PowerShell](#tab/PowerShell)

+```azurepowershell-interactive

+Remove-AzResourceGroup -Name exampleRG

+```

+## Next steps

+In this quickstart, you created an Azure container instance using Bicep. If you'd like to build a container image and deploy it from a private Azure container registry, continue to the Azure Container Instances tutorial.

+> [!div class="nextstepaction"]

+> [Tutorial: Create a container image for deployment to Azure Container Instances](./container-instances-tutorial-prepare-app.md)

+You can use your existing MongoDB apps with API for MongoDB by just changing the connection string. You can move any existing data using native MongoDB tools such as mongodump & mongorestore or using our Azure Database Migration tool. Tools, such as the MongoDB shell, [MongoDB Compass](mongodb/connect-using-compass.md), and [Robo3T](mongodb/connect-using-robomongo.md), can run queries and work with data as they do with native MongoDB. To learn more, see [API for MongoDB](mongodb/mongodb-introduction.md) article.

+Before you can send notifications to Teams from your pipelines, you must create an [Incoming Webhook](/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using) for your Teams channel. If you need to create a new Teams channel for this purpose, refer to the [Teams documentation](https://support.microsoft.com/office/create-a-channel-in-teams-fda0b75e-5b90-4fb8-8857-7e102b014525).  

+1. Select the "Add to a team" button to add the connector to the Team or Team channel name site where you want to send notifications.

+1. Type or select Team or Team channel name where you want to send the notifications.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/type-a-team-or-team-channel-name.png" alt-text="Shows the team selection prompt on the Incoming Webhook app configuration dialog in Teams. Type the &quot;Team or Team channel name&quot;":::

+1. Select the "Set up a connector" button to set up the Incoming Webhook for the Team or Team channel name you selected in the previous step.

+

+ :::image type="content" source="media/how-to-send-notifications-to-teams/teams-prod-notifications.png" alt-text="Shows the team selection prompt on the Incoming Webhook app configuration dialog in Teams. Highlights the Team and the &quot;Set up a connector&quot; button":::

+1. Copy the Webhook URL that is generated on creation and save it for later use in pipeline. After that, select the "Done" button to complete the setup.

+1. Select **Author** tab from the left pane.

+1. Select the + (plus) button, and then select **New pipeline**.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/new-pipeline.png" alt-text="Shows the &quot;New pipeline&quot; menu in the Azure Data Factory Studio.":::

+1. In the "Properties" pane under "General", specify **NotifiyTeamsChannelPipeline** for **Name**. Then collapse the panel by clicking the **Properties** icon in the top-right corner.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/name-pipeline.png" alt-text="Shows the &quot;Properties&quot; panel.":::

+ :::image type="content" source="media/how-to-send-notifications-to-teams/hide-properties-panel.png" alt-text="Shows the &quot;Properties&quot; panel hidden.":::

+1. In the "Configurations" pane, select **Parameters**, and then select the **+ New** button define following parameters for your pipeline.

+ | Name | Type | Default Value |

+ | :-- | : |: |

+ | subscription | ``String`` | ``Specify subscription id for the pipeline`` |

+ | resourceGroup | ``String`` | ``Specify resource group name for the pipeline`` |

+ | runId | ``String`` | ``@activity('Specify name of the calling pipeline').output['pipelineRunId']`` |

+ | name | ``String`` | ``@activity('Specify name of the calling pipeline').output['pipelineName']`` |

+ | triggerTime | ``String`` | ``@activity('Specify name of the calling pipeline').ExecutionStartTime`` |

+ | status | ``String`` | ``@activity('Specify name of the calling pipeline').Status`` |

+ | message | ``String`` | ``@activity('Specify name of the calling pipeline').Error['message']`` |

+ | executionEndTime | ``String`` | ``@activity('Specify name of the calling pipeline').ExecutionEndTime`` |

+ | runDuration | ``String`` | ``@activity('Specify name of the calling pipeline').Duration`` |

+ | teamWebhookUrl | ``String`` | ``Specify Team Webhook URL`` |

+ :::image type="content" source="media/how-to-send-notifications-to-teams/pipeline-parameters.png" alt-text="Shows the &quot;Pipeline parameters&quot;.":::

+ > [!NOTE]

+ > These parameters are used to construct the monitoring URL. Suppose you do not provide a valid subscription and resource group (of the same data factory where the pipelines belong). In that case, the notification will not contain a valid pipeline monitoring URL, but the messages will still work. Additionally, adding these parameters helps prevent the need to always pass those values from another pipeline. If you intend to control those values through a metadata-driven approach, then you should modify them accordingly.

+ > [!TIP]

+ > We recommend adding the current Data Factory **Subscription ID**, **Resource Group**, and the **Teams webhook URL** (refer to [prerequisites](#prerequisites)) for the default value of the relevant parameters.

+1. In the "Configurations" pane, select **Variables**, and then select the **+ New** button define following variables for your pipeline.

+ | Name | Type | Default Value |

+ | :-- | : |:- |

+ | messageCard | ``String`` | |

+ :::image type="content" source="media/how-to-send-notifications-to-teams/pipeline-variables.png" alt-text="Shows the &quot;Pipeline variables&quot;.":::

+1. Search for "Set variable" in the pipeline "Activities" pane, and drag a **Set Variable** activity to the pipeline canvas.

+1. Select the **Set Variable** activity on the canvas if it isn't already selected, and its "General" tab, to edit its details.

+1. In the "General" tab, specify **Set JSON schema** for **Name** of the **Set Variable** activity.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/set-variable-activity-name.png" alt-text="Shows the &quot;Set variable&quot; activity general tab.":::

+1. In the "Variables" tab, select **messageCard** variable for the **Name** property and enter the following **JSON** for its **Value** property:

+ ```json

+ {

+ "@type": "MessageCard",

+ "@context": "http://schema.org/extensions",

+ "themeColor": "0076D7",

+ "summary": "Pipeline status alert messageΓÇïΓÇïΓÇïΓÇï",

+ "sections": [

+ {

+ "activityTitle": "Pipeline execution alertΓÇïΓÇïΓÇïΓÇï",

+ "facts": [

+ {

+ "name": "Subscription Id:",

+ "value": "@{pipeline().parameters.subscription}"

+ },

+ {

+ "name": "Resource Group:",

+ "value": "@{pipeline().parameters.resourceGroup}"

+ },

+ {

+ "name": "Data Factory Name:",

+ "value": "@{pipeline().DataFactory}"

+ },

+ {

+ "name": "Pipeline RunId:",

+ "value": "@{pipeline().parameters.runId}"

+ },

+ {

+ "name": "Pipline Name:",

+ "value": "@{pipeline().parameters.name}"

+ },

+ {

+ "name": "Pipeline Status:",

+ "value": "@{pipeline().parameters.status}"

+ },

+ {

+ "name": "Execution Start Time (UTC):",

+ "value": "@{pipeline().parameters.triggerTime}"

+ },

+ {

+ "name": "Execution Finish Time (UTC):",

+ "value": "@{pipeline().parameters.executionEndTime}"

+ },

+ {

+ "name": "Execution Duration (s):",

+ "value": "@{pipeline().parameters.runDuration}"

+ },

+ {

+ "name": "Message:",

+ "value": "@{pipeline().parameters.message}"

+ },

+ {

+ "name": "Notification Time (UTC):",

+ "value": "@{utcnow()}"

+ }

+ ],

+ "markdown": true

+ }

+ ],

+ "potentialAction": [

+ {

+ "@type": "OpenUri",

+ "name": "View pipeline run",

+ "targets": [

+ {

+ "os": "default",

+ "uri": "@{concat('https://adf.azure.com/monitoring/pipelineruns/',pipeline().parameters.runId,'?factory=/subscriptions/',pipeline().parameters.subscription,'/resourceGroups/',pipeline().parameters.resourceGroup,'/providers/Microsoft.DataFactory/factories/',pipeline().DataFactory)}"

+ }

+ ]

+ }

+ ]

+ }

+ ```

+

+ :::image type="content" source="media/how-to-send-notifications-to-teams/set-variable-activity-variables-tab.png" alt-text="Shows the &quot;Set variable&quot; activity variables tab.":::

+1. Search for "Web" in the pipeline "Activities" pane, and drag a **Web** activity to the pipeline canvas.

+1. Create a dependency condition for the **Web** activity so that it only runs if the **Set Variable** activity succeeds. To create this dependency, select the green handle on the right side of the **Set Variable** activity, drag it, and connect it to the **Web** activity.

+1. Select the new **Web** activity on the canvas if it isn't already selected, and its "General" tab, to edit its details.

+1. In the "General" pane, specify **Invoke Teams Webhook Url** for **Name** of the **Web** activity.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/web-activity-name.png" alt-text="Shows the &quot;Web&quot; activity general pane.":::

+1. In the "Settings" pane, set following properties as follows:

+ | Property | value |

+ | :-- | : |

+ | URL | ``@pipeline().parameters.teamWebhookUrl`` |

+ | Method | ``POST`` |

+ | Body | ``@json(variables('messageCard'))`` |

+ :::image type="content" source="media/how-to-send-notifications-to-teams/web-activity-settings-pane.png" alt-text="Shows the &quot;Web&quot; activity settings pane.":::

+1. All set and now you're ready to validate, debug, and then publish your **NotifiyTeamsChannelPipeline** pipeline.

+ - To validate the pipeline, select **Validate** from the tool bar.

+ - To debug the pipeline, select **Debug** on the toolbar. You can see the status of the pipeline run in the "Output" tab at the bottom of the window.

+ - Once the pipeline can run successfully, in the top toolbar, select **Publish all**. This action publishes entities you created to Data Factory. Wait until you see the **Successfully** published message.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/validate-debug-publish.png" alt-text="Shows the &quot;Validate, Debug, Publish&quot; buttons to validate, debug, and then publish your pipeline.":::

+1. Select **Integrate** tab from the left pane.

+1. Select the + (plus) button, and then select **Pipeline**.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/new-pipeline-synapse.png" alt-text="Shows the &quot;New pipeline&quot; menu in the Synapse Studio.":::

+1. In the "Properties" panel under "General", specify **NotifiyTeamsChannelPipeline** for **Name**. Then collapse the panel by clicking the **Properties** icon in the top-right corner.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/name-pipeline-synapse.png" alt-text="Shows the &quot;Properties&quot; panel.":::

+ :::image type="content" source="media/how-to-send-notifications-to-teams/hide-properties-panel-synapse.png" alt-text="Shows the &quot;Properties&quot; panel hidden.":::

+1. In the "Configurations" pane, select **Parameters**, and then select the **+ New** button define following parameters for your pipeline.

+ | Name | Type | Default Value |

+ | :-- | : |:- |

+ | subscription | ``String`` | ``Specify subscription id for the pipeline`` |

+ | resourceGroup | ``String`` | ``Specify resource group name for the pipeline`` |

+ | runId | ``String`` | ``@activity('Specify name of the calling pipeline').output['pipelineRunId']`` |

+ | name | ``String`` | ``@activity('Specify name of the calling pipeline').output['pipelineName']`` |

+ | triggerTime | ``String`` | ``@activity('Specify name of the calling pipeline').ExecutionStartTime`` |

+ | status | ``String`` | ``@activity('Specify name of the calling pipeline').Status`` |

+ | message | ``String`` | ``@activity('Specify name of the calling pipeline').Error['message']`` |

+ | executionEndTime | ``String`` | ``@activity('Specify name of the calling pipeline').ExecutionEndTime`` |

+ | runDuration | ``String`` | ``@activity('Specify name of the calling pipeline').Duration`` |

+ | teamWebhookUrl | ``String`` | ``Specify Team Webhook URL`` |

+ :::image type="content" source="media/how-to-send-notifications-to-teams/pipeline-parameters-synapse.png" alt-text="Shows the &quot;Pipeline parameters&quot;.":::

+ > [!NOTE]

+ > These parameters are used to construct the monitoring URL. Suppose you do not provide a valid subscription and resource group (of the same data factory where the pipelines belong). In that case, the notification will not contain a valid pipeline monitoring URL, but the messages will still work. Additionally, adding these parameters helps prevent the need to always pass those values from another pipeline. If you intend to control those values through a metadata-driven approach, then you should modify them accordingly.

+ > [!TIP]

+ > We recommend adding the current Data Factory **Subscription ID**, **Resource Group**, and the **Teams webhook URL** (refer to [prerequisites](#prerequisites)) for the default value of the relevant parameters.

+1. In the "Configurations" pane, select **Variables**, and then select the **+ New** button define following variables for your pipeline.

+ | Name | Type | Default Value |

+ | :-- | : |:- |

+ | messageCard | ``String`` | |

+ :::image type="content" source="media/how-to-send-notifications-to-teams/pipeline-variables-synapse.png" alt-text="Shows the &quot;Pipeline variables&quot;.":::

+1. Search for "Set variable" in the pipeline "Activities" pane, and drag a **Set Variable** activity to the pipeline canvas.

+1. Select the "Set variable" activity on the canvas if it isn't already selected, and its **General** tab, to edit its details.

+1. In the "General" tab, specify **Set JSON schema** for **Name** of the "Set variable" activity.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/set-variable-activity-name-synapse.png" alt-text="Shows the &quot;Set variable&quot; activity general tab.":::

+1. In the "Variables" tab, select **messageCard** variable for the **Name** property and enter the following **JSON** for its **Value** property:

+ ```json

+ {

+ "@type": "MessageCard",

+ "@context": "http://schema.org/extensions",

+ "themeColor": "0076D7",

+ "summary": "Pipeline status alert messageΓÇïΓÇïΓÇïΓÇï",

+ "sections": [

+ {

+ "activityTitle": "Pipeline execution alertΓÇïΓÇïΓÇïΓÇï",

+ "facts": [

+ {

+ "name": "Subscription Id:",

+ "value": "@{pipeline().parameters.subscription}"

+ },

+ {

+ "name": "Resource Group:",

+ "value": "@{pipeline().parameters.resourceGroup}"

+ },

+ {

+ "name": "Data Factory Name:",

+ "value": "@{pipeline().DataFactory}"

+ },

+ {

+ "name": "Pipeline RunId:",

+ "value": "@{pipeline().parameters.runId}"

+ },

+ {

+ "name": "Pipline Name:",

+ "value": "@{pipeline().parameters.name}"

+ },

+ {

+ "name": "Pipeline Status:",

+ "value": "@{pipeline().parameters.status}"

+ },

+ {

+ "name": "Execution Start Time (UTC):",

+ "value": "@{pipeline().parameters.triggerTime}"

+ },

+ {

+ "name": "Execution Finish Time (UTC):",

+ "value": "@{pipeline().parameters.executionEndTime}"

+ },

+ {

+ "name": "Execution Duration (s):",

+ "value": "@{pipeline().parameters.runDuration}"

+ },

+ {

+ "name": "Message:",

+ "value": "@{pipeline().parameters.message}"

+ },

+ {

+ "name": "Notification Time (UTC):",

+ "value": "@{utcnow()}"

+ }

+ ],

+ "markdown": true

+ }

+ ],

+ "potentialAction": [

+ {

+ "@type": "OpenUri",

+ "name": "View pipeline run",

+ "targets": [

+ {

+ "os": "default",

+ "uri": "@{concat('https://adf.azure.com/monitoring/pipelineruns/',pipeline().parameters.runId,'?factory=/subscriptions/',pipeline().parameters.subscription,'/resourceGroups/',pipeline().parameters.resourceGroup,'/providers/Microsoft.DataFactory/factories/',pipeline().DataFactory)}"

+ }

+ ]

+ }

+ ]

+ }

+ ```

+

+ :::image type="content" source="media/how-to-send-notifications-to-teams/set-variable-activity-variables-tab-synapse.png" alt-text="Shows the &quot;Set variable&quot; activity variables tab.":::

+1. Search for "Web" in the pipeline "Activities" pane, and drag a **Web** activity to the pipeline canvas.

+1. Create a dependency condition for the **Web** activity so that it only runs if the **Set Variable** activity succeeds. To create this dependency, select the green handle on the right side of the **Set Variable** activity, drag it, and connect it to the **Web** activity.

+1. Select the new **Web** activity on the canvas if it isn't already selected, and its "General" tab, to edit its details.

+1. In the "General" pane, specify **Invoke Teams Webhook Url** for **Name** of the **Web** activity.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/web-activity-name-synapse.png" alt-text="Shows the &quot;Web&quot; activity general pane.":::

+1. In the "Settings" pane, set following properties as follows:

+ | Property | value |

+ | :-- | : |

+ | URL | ``@pipeline().parameters.teamWebhookUrl`` |

+ | Method | ``POST`` |

+ | Body | ``@json(variables('messageCard'))`` |

+ :::image type="content" source="media/how-to-send-notifications-to-teams/web-activity-settings-pane-synapse.png" alt-text="Shows the &quot;Web&quot; activity settings pane.":::

+1. All set and now you're ready to validate, debug, and then publish your **NotifiyTeamsChannelPipeline** pipeline.

+ - To validate the pipeline, select **Validate** from the tool bar.

+ - To debug the pipeline, select **Debug** on the toolbar. You can see the status of the pipeline run in the "Output" tab at the bottom of the window.

+ - Once the pipeline can run successfully, in the top toolbar, select **Publish all**. This action publishes entities you created to Data Factory. Wait until you see the **Successfully** published message.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/validate-debug-publish-synapse.png" alt-text="Shows the &quot;Validate, Debug, Publish&quot; buttons to validate, debug, and then publish your pipeline.":::

+## Sample usage

+In this sample usage scenario, we'll create a master pipeline with three **Execute Pipeline** activities. The first **Execute Pipeline** activity will invoke our ETL pipeline and the remaining two **Execute Pipeline** activities will invoke the "NotifiyTeamsChannelPipeline" pipeline to send relevant success or failure notifications to the Teams channel depending on the execution state of our ETL pipeline.

+1. Select **Author** tab from the left pane in **Data Factory** or **Integrate** tab from the left pane in **Synapse Studio**. Next, select the + (plus) button, and then select **Pipeline** to create a new pipeline.

+1. In the "General" panel under Properties, specify **MasterPipeline** for **Name**. Then collapse the panel by clicking the **Properties** icon in the top-right corner.

+1. Search for pipeline in the pipeline "Activities" pane, and drag three **Execute Pipeline** activities to the pipeline canvas.

+1. Select first **Execute Pipeline** activity on the canvas if it isn't already selected, and its "General" pane, to edit its details.

+ - For **Name** property of the **Execute Pipeline** activity, we recommend using the name of your invoked ETL pipeline for which you want to send notifications. For example, we used **LoadDataPipeline** for the **Name** of our **Execute Pipeline** activity because it's the name of our invoked pipeline.

+ - In the "Settings" pane, select an existing pipeline or create a new one using the **+ New** button for the **Invoked pipeline** property. For example, in our case, we selected **LoadDataPipeline** pipeline for the "Invoked pipeline" property. Select other options and configure any parameters for the pipeline as required to complete your configuration.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/execute-pipeline-activity-1-general.png" alt-text="Shows the &quot;Execute pipeline&quot; activity general pane for &quot;LoadDataPipeline&quot; pipeline.":::

+

+ :::image type="content" source="media/how-to-send-notifications-to-teams/execute-pipeline-activity-1-settings.png" alt-text="Shows the &quot;Execute pipeline&quot; activity setting pane for &quot;LoadDataPipeline&quot; pipeline.":::

+1. Select second **Execute Pipeline** activity on the canvas, and it's "General" pane, to edit its details.

+ - Specify **OnSuccess Notification** for **Name** of the **Execute Pipeline** activity.

+ - In the "Settings" pane, select **NotifiyTeamsChannelPipeline** pipeline, which we created earlier, for the **Invoked pipeline** property. Customize the parameters as required based on activity type. For example, I've customized the parameters as follows:

+ | Name | Value |

+ | :- | :- |

+ | subscription | ``11111111-0000-aaaa-bbbb-0000000000`` |

+ | resourceGroup | ``contosorg`` |

+ | runId | ``@activity('LoadDataPipeline').output['pipelineRunId']`` |

+ | name | ``@activity('LoadDataPipeline').output['pipelineName']`` |

+ | triggerTime | ``@activity('LoadDataPipeline').ExecutionStartTime`` |

+ | status | ``@activity('LoadDataPipeline').Status`` |

+ | message | ``Pipeline - LoadDataPipeline ran with success.`` |

+ | executionEndTime | ``@activity('LoadDataPipeline').ExecutionEndTime`` |

+ | runDuration | ``@activity('LoadDataPipeline').Duration`` |

+ | teamWebhookUrl | ``https://microsoft.webhook.office.com/webhookb2/1234abcd-1x11-2ff1-ab2c-1234d0699a9e@72f988bf-32b1-41af-91ab-2d7cd011db47/IncomingWebhook/8212f66ad80040ab83cf68b554d9232a/17d524d0-ed5c-44ed-98a0-35c12dd89a6d`` |

+ - Create a dependency condition for the second **Execute Pipeline** activity so that it only runs if the first **Execute Pipeline** activity succeeds. To create this dependency, select the green handle on the right side of the first **Execute Pipeline** activity, drag it, and connect it to the second **Execute Pipeline** activity.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/execute-pipeline-activity-2-general.png" alt-text="Shows the second &quot;Execute pipeline&quot; activity &quot;OnSuccess Notification&quot; general pane for &quot;NotifiyTeamsChannelPipeline&quot; pipeline.":::

+ :::image type="content" source="media/how-to-send-notifications-to-teams/execute-pipeline-activity-2-settings.png" alt-text="Shows the second &quot;Execute pipeline&quot; activity &quot;OnSuccess Notification&quot; setting pane for &quot;NotifiyTeamsChannelPipeline&quot; pipeline.":::

+1. Select third **Execute Pipeline** activity on the canvas, and it's "General" pane, to edit its details.

+ - Specify **OnFailure Notification** for **Name** of the **Execute Pipeline** activity.

+ - In the "Settings" pane, select **NotifiyTeamsChannelPipeline** pipeline for the **Invoked pipeline** property. Customize the parameters as required based on activity type. For example, I've customized the parameters this time as follows:

+ | Name | Value |

+ | :- | :- |

+ | subscription | ``11111111-0000-aaaa-bbbb-0000000000`` |

+ | resourceGroup | ``contosorg`` |

+ | runId | ``@activity('LoadDataPipeline').output['pipelineRunId']`` |

+ | name | ``@activity('LoadDataPipeline').output['pipelineName']`` |

+ | triggerTime | ``@activity('LoadDataPipeline').ExecutionStartTime`` |

+ | status | ``@activity('LoadDataPipeline').Status`` |

+ | message | ``@activity('LoadDataPipeline').Error['message']`` |

+ | executionEndTime | ``@activity('LoadDataPipeline').ExecutionEndTime`` |

+ | runDuration | ``@activity('LoadDataPipeline').Duration`` |

+ | teamWebhookUrl | ``https://microsoft.webhook.office.com/webhookb2/1234abcd-1x11-2ff1-ab2c-1234d0699a9e@72f988bf-32b1-41af-91ab-2d7cd011db47/IncomingWebhook/8212f66ad80040ab83cf68b554d9232a/17d524d0-ed5c-44ed-98a0-35c12dd89a6d`` |

+ - Create a dependency condition for the third **Execute Pipeline** activity so that it only runs if the first **Execute Pipeline** activity fails. To create this dependency, select the red handle on the right side of the first **Execute Pipeline** activity, drag it, and connect it to the third **Execute Pipeline** activity.

+ - Validate, debug, and then publish your **MasterPipeline** pipeline.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/execute-pipeline-activity-3-general.png" alt-text="Shows the third &quot;Execute pipeline&quot; activity &quot;OnFailure Notification&quot; general pane for &quot;NotifiyTeamsChannelPipeline&quot; pipeline.":::

+ :::image type="content" source="media/how-to-send-notifications-to-teams/execute-pipeline-activity-3-settings.png" alt-text="Shows the third &quot;Execute pipeline&quot; activity &quot;OnFailure Notification&quot; settings pane for &quot;NotifiyTeamsChannelPipeline&quot; pipeline.":::

+1. Run pipeline to receive notifications in Teams. For example, below are sample notifications, when my pipeline ran successfully and when it failed.

+ :::image type="content" source="media/how-to-send-notifications-to-teams/teams-notifications-view-pipeline-run-onsuccess.png" alt-text="Shows on success pipeline notifications in a Teams channel.":::

+ :::image type="content" source="media/how-to-send-notifications-to-teams/teams-notifications-view-pipeline-run-onfailure.png" alt-text="Shows on failure pipeline notifications in a Teams channel.":::

+1. Select the "View pipeline run" button to view pipeline run.

+The above expressions will return the relevant error messages from a failure, which can be sent out as notification on a Teams channel. For more information about this topic, see the

+[Copy activity output properties](copy-activity-monitoring.md) article.

+[How to send email from a pipeline](how-to-send-email.md)

+You can add a DevTest Labs User to a lab by using the following Azure PowerShell script. The script requires the user to be in the Azure Active Directory (Azure AD). For information about adding an external user to Azure AD as a guest, see [Add a new guest user](/azure/active-directory/fundamentals/add-users-azure-active-directory#add-a-new-guest-user). If the user isn't in Azure AD, use the portal procedure instead.

+- [Automate adding lab users](automate-add-lab-user.md)

+description: See a reference architecture and considerations for Azure DevTest Labs in an enterprise.

+# DevTest Labs enterprise reference architecture

+This article provides a reference architecture for deploying Azure DevTest Labs in an enterprise. The architecture includes the following key elements:

+- On-premises connectivity via Azure ExpressRoute

+- A remote desktop gateway to remotely sign in to virtual machines (VMs)

+- Connectivity to a private artifact repository

+- Other platform-as-a-service (PaaS) components that labs use

+The following diagram shows a typical DevTest Labs enterprise deployment. This architecture connects several labs in different Azure subscriptions to a company's on-premises network.

+

+### DevTest Labs components

+DevTest Labs makes it easy and fast for enterprises to provide access to Azure resources. Each lab contains software-as-a-service (SaaS), infrastructure-as-a-service (IaaS), and PaaS resources. Lab users can create and configure VMs, PaaS environments, and VM [artifacts]().

+In the preceding diagram, **Team Lab 1** in **Azure Subscription 1** shows an example of Azure components that labs can access and use. For more information, see [About DevTest Labs](devtest-lab-overview.md).

+### Connectivity components

+You need on-premises connectivity if your labs must access on-premises corporate resources. Common scenarios are:

+- Some on-premises data can't move to the cloud.

+- You want to join lab VMs to an on-premises domain.

+- You want to force all cloud network traffic through an on-premises firewall for security or compliance reasons.

+This architecture uses [ExpressRoute](../expressroute/expressroute-introduction.md) for connectivity to the on-premises network. You can also use a [site-to-site VPN](../vpn-gateway/vpn-gateway-about-vpn-gateway-settings.md).

+On-premises, a [remote desktop gateway](/windows-server/remote/remote-desktop-services/desktop-hosting-logical-architecture) enables outgoing remote desktop protocol (RDP) connections to DevTest Labs. Enterprise corporate firewalls usually block outgoing connections at the corporate firewall. To enable connectivity, you can:

+- Use a remote desktop gateway, and allow the static IP address of the gateway load balancer.

+- Use [forced tunneling](../vpn-gateway/vpn-gateway-forced-tunneling-rm.md) to redirect all RDP traffic back over the ExpressRoute or site-to-site VPN connection. Forced tunneling is common functionality for enterprise-scale DevTest Labs deployments.

+### Networking components

+In this architecture, [Azure Active Directory (Azure AD)](/azure/active-directory/fundamentals/active-directory-whatis) provides identity and access management across all networks. Lab VMs usually have a local administrative account for access. If there's an Azure AD, on-premises, or [Azure AD Domain Services](../active-directory-domain-services/overview.md) domain available, you can join lab VMs to the domain. Users can then use their domain-based identities to connect to the VMs.

+[Azure networking topology](../networking/fundamentals/networking-overview.md) controls how lab resources access and communicate with on-premises networks and the internet. This architecture shows a common way that enterprises network DevTest Labs. The labs connect with [peered virtual networks](../virtual-network/virtual-network-peering-overview.md) in a [hub-spoke configuration](/azure/architecture/reference-architectures/hybrid-networking/hub-spoke), through the ExpressRoute or site-to-site VPN connection, to the on-premises network.

+Because DevTest Labs uses Azure Virtual Network directly, there are no restrictions on how you set up the networking infrastructure. You can set up a [network security group](../virtual-network/network-security-groups-overview.md) to restrict cloud traffic based on source and destination IP addresses. For example, you can allow only traffic that originates from the corporate network into the lab's networks.

+DevTest Labs has no built-in quotas or limits, but other Azure resources that labs use have [subscription-level quotas](../azure-resource-manager/management/azure-subscription-service-limits.md). In a typical enterprise deployment, you need several Azure subscriptions to cover a large DevTest Labs deployment. Enterprises commonly reach the following quotas:

+- Resource groups. DevTest Labs creates a resource group for every new VM, and lab users create environments in resource groups. Subscriptions can contain [up to 980 resource groups](../azure-resource-manager/management/azure-subscription-service-limits.md#subscription-limits), so that's the limit of VMs and environments in a subscription.

+ Two strategies can help you stay under resource group limits:

+ - [All VMs go in the same resource group](resource-group-control.md). This strategy helps you meet the resource group limit, but it affects the resource-type-per-resource-group limit.

+ - [Use shared public IPs](devtest-lab-shared-ip.md). If VMs are allowed to have public IP addresses, put all VMs of the same size and region into the same resource group. This configuration helps meet both resource group quotas and resource-type-per-resource-group quotas.

+- Resources per resource group per resource type. The default limit for [resources per resource group per resource type is 800](../azure-resource-manager/management/azure-subscription-service-limits.md#resource-group-limits). Putting all VMs in the same resource group hits this limit much sooner, especially if the VMs have many extra disks.

+- Storage accounts. Every lab in DevTest Labs comes with a storage account. The Azure quota for [number of storage accounts per region per subscription is 250](../azure-resource-manager/management/azure-subscription-service-limits.md#storage-limits). So the maximum number of DevTest Labs in one region is also 250.

+- Role assignments. A role assignment gives a user or principal access to a resource. Azure has a limit of [2,000 role assignments per subscription](../azure-resource-manager/management/azure-subscription-service-limits.md#azure-rbac-limits).

+ By default, DevTest Labs creates a resource group for each lab VM. The VM creator gets *owner* permission for the VM and *reader* permission to the resource group. So each lab VM uses two role assignments. Granting user permissions to the lab also uses role assignments.

+

+- API reads/writes. You can automate Azure and DevTest Labs by using REST APIs, PowerShell, Azure CLI, and Azure SDK. Each Azure subscription allows up to [12,000 read requests and 1,200 write requests per hour](../azure-resource-manager/management/request-limits-and-throttling.md). By automating DevTest Labs, you might hit the limit on API requests.

+You can use the Azure portal to manage a single DevTest Labs instance at a time, but enterprises might have multiple Azure subscriptions and many labs to administer. Making changes consistently to all labs requires scripting automation.

+Here are some examples of using scripting in DevTest Labs deployments:

+- Changing lab settings. Update a specific lab setting across all labs by using PowerShell scripts, Azure CLI, or REST APIs. For example, update all labs to allow a new VM instance size.

+- Updating artifact repository personal access tokens (PATs). PATs for Git repositories typically expire in 90 days, one year, or two years. To ensure continuity, it's important to extend the PAT. Or, create a new PAT and use automation to apply it to all labs.

+- Restricting changes to lab settings. To restrict certain settings, such as allowing marketplace image use, you can use Azure Policy to prevent changes to a resource type. Or you can create a custom role, and grant users that role instead of a built-in lab role. You can restrict changes for most lab settings, such as internal support, lab announcements, and allowed VM sizes.

+- Applying a naming convention for VMs. You can use Azure Policy to [specify a naming pattern](https://github.com/Azure/azure-policy/tree/master/samples/TextPatterns/allow-multiple-name-patterns) that helps identify VMs in cloud-based environments.

+You manage Azure resources for DevTest Labs the same way as for other purposes. For example, Azure Policy applies to VMs you create in a lab. Microsoft Defender for Cloud can report on lab VM compliance. Azure Backup can provide regular backups for lab VMs.

+DevTest Labs automatically benefits from built-in Azure security features. To require incoming remote desktop connections to originate only from the corporate network, you can add a network security group to the virtual network on the remote desktop gateway.

+Another security consideration is the permission level you grant to lab users. Lab owners use Azure role-based access control (Azure RBAC) to assign roles to users and set resource and access-level permissions. The most common DevTest Labs permissions are Owner, Contributor, and User. You can also create and assign [custom roles](devtest-lab-grant-user-permissions-to-specific-lab-policies.md). For more information, see [Add owners and users in Azure DevTest Labs](devtest-lab-add-devtest-user.md).

+See the next article in this series: [Deliver a proof of concept](deliver-proof-concept.md).

+ Title: Create a lab virtual machine by using Azure PowerShell

+description: Learn how to use Azure PowerShell to create and manage virtual machines in Azure DevTest Labs.

+# Create DevTest Labs VMs by using Azure PowerShell

+This article shows you how to create an Azure DevTest Labs virtual machine (VM) in a lab by using Azure PowerShell. You can use PowerShell scripts to automate lab VM creation.

+You need the following prerequisites to work through this article:

+- Access to a lab in DevTest Labs. [Create a lab](devtest-lab-create-lab.md), or use an existing lab.

+- Azure PowerShell. [Install Azure PowerShell](/powershell/azure/install-az-ps), or [use Azure Cloud Shell](/azure/cloud-shell/quickstart-powershell) in the Azure portal.

+## PowerShell VM creation script

+The PowerShell [Invoke-AzResourceAction](/powershell/module/az.resources/invoke-azresourceaction) cmdlet invokes the `createEnvironment` action with the lab's resource ID and VM parameters. The parameters are in a hash table that contains all the VM properties. The properties are different for each type of VM. To get the properties for the VM type you want, see [Get VM properties](#get-vm-properties).

+This sample script creates a Windows Server 2019 Datacenter VM. The sample also includes properties to add a second data disk under `dataDiskParameters`.

+ ```powershell

+ #The preceding command puts the VM in the first allowed subnet in the first virtual network for the lab.

+ #If you need to use a specific virtual network, use | to find the network. For example:

+ #$virtualNetwork = @(Get-AzResource -ResourceType 'Microsoft.DevTestLab/labs/virtualnetworks' -ResourceName $LabName -ResourceGroupName $lab.ResourceGroupName -ApiVersion $API_VERSION) | Where-Object Name -EQ "SpecificVNetName"

+ #Prepare all the properties needed for the createEnvironment call.

+ # The properties are slightly different depending on the type of VM base.

+ # The virtual network setup might also affect the properties.

+ "notes" = "Windows Server 2019 Datacenter";

+ "expirationDate" = "2022-12-01"

+ "sku" = "2019-Datacenter";

+ #The following line has the same effect as invoking the

+ # https://azure.github.io/projects/apis/#!/Labs/Labs_CreateEnvironment REST API

+Save the preceding script in a file named *Create-LabVirtualMachine.ps1*. Run the script by using the following command. Enter your own values for the placeholders.

+.\Create-LabVirtualMachine.ps1 -ResourceGroupName '<lab resource group name>' -LabName '<lab name>' -userName '<VM administrative username>' -password '<VM admin password>' -VMName '<VM name to create>'

+## Get VM properties

+This section shows how to get the specific properties for the type of VM you want to create. You can get the properties from an Azure Resource Manager (ARM) template in the Azure portal, or by calling the DevTest Labs Azure REST API.

+### Use the Azure portal to get VM properties

+Creating a VM in the Azure portal generates an Azure Resource Manager (ARM) template that shows the VM's properties. Once you choose a VM base, you can see the ARM template and get the properties without actually creating the VM. This method is the easiest way to get the JSON VM description if you don't already have a lab VM of that type.

+1. In the [Azure portal](https://portal.azure.com), on the **Overview** page for your lab, select **Add** on the top toolbar.

+1. On the **Choose a base** page, select the VM type you want. Depending on lab settings, the VM base can be an Azure Marketplace image, a custom image, a formula, or an environment.

+1. On the **Create lab resource** page, optionally [add artifacts](add-artifact-vm.md) and configure any other settings you want on the **Basic settings** and **Advanced settings** tabs.

+1. On the **Advanced settings** tab, select **View ARM template** at the bottom of the page.

+1. On the **View Azure Resource Manager template** page, review the JSON template for creating the VM. The **resources** section has the VM properties.

+ For example, the following `resources` section has the properties for a Windows Server 2022 Datacenter VM:

+ ```json

+ "resources": [

+ {

+ "apiVersion": "2018-10-15-preview",

+ "type": "Microsoft.DevTestLab/labs/virtualmachines",

+ "name": "[variables('vmName')]",

+ "location": "[resourceGroup().location]",

+ "properties": {

+ "labVirtualNetworkId": "[variables('labVirtualNetworkId')]",

+ "notes": "Windows Server 2022 Datacenter: Azure Edition Core",

+ "galleryImageReference": {

+ "offer": "WindowsServer",

+ "publisher": "MicrosoftWindowsServer",

+ "sku": "2022-datacenter-azure-edition-core",

+ "osType": "Windows",

+ "version": "latest"

+ },

+ "size": "[parameters('size')]",

+ "userName": "[parameters('userName')]",

+ "password": "[parameters('password')]",

+ "isAuthenticationWithSshKey": false,

+ "labSubnetName": "[variables('labSubnetName')]",

+ "disallowPublicIpAddress": true,

+ "storageType": "Standard",

+ "allowClaim": false,

+ "networkInterface": {

+ "sharedPublicIpAddressConfiguration": {

+ "inboundNatRules": [

+ {

+ "transportProtocol": "tcp",

+ "backendPort": 3389

+ }

+ ]

+ }

+ }

+ }

+ ],

+ ```

+1. Copy and save the template to use in future PowerShell automation, and transfer the properties to the PowerShell VM creation script.

+

+### Use the DevTest Labs Azure REST API to get VM properties

+You can also call the DevTest Labs REST API to get the properties of existing lab VMs. You can use those properties to create more lab VMs of the same types.

+1. On the [Virtual Machines - list](/rest/api/dtl/virtualmachines/list) page, select **Try it** above the first code block.

+1. On the **REST API Try It** page:

+ - Under **labName**, enter your lab name.

+ - Under **labResourceGroup**, enter the lab resource group name.

+ - Under **subscriptionId**, select the lab's Azure subscription.

+1. Select **Run**.

+1. In the **Response** section under **Body**, view the properties for all the existing VMs in the lab.

+## Set VM expiration date

+In training, demo, and trial scenarios, you can avoid unnecessary costs by deleting VMs automatically on a certain date. You can set the VM `expirationDate` property when you create a VM. The PowerShell VM creation script earlier in this article sets an expiration date under `properties`:

+```json

+ "expirationDate" = "2022-12-01"

+```

+You can also set expiration dates on existing VMs by using PowerShell. The following PowerShell script sets an expiration date for an existing lab VM if it doesn't already have an expiration date:

+# Enter your own values:

+$subscriptionId = '<Lab subscription Id>'

+$labResourceGroup = '<Lab resource group>'

+$labName = '<Lab name>'

+$VmName = '<VM name>'

+$expirationDate = '<Expiration date, such as 2022-12-16>'

+# Sign in to your Azure account

+Select-AzSubscription -SubscriptionId $subscriptionId

+$vm = Get-AzResource -ResourceId $VmResourceId -ExpandProperties

+# Get the Vm properties

+ $VmProperties | Add-Member -MemberType NoteProperty -Name expirationDate -Value $expirationDate -Force

+Set-AzResource -ResourceId $VmResourceId -Properties $VmProperties -Force

+[Az.DevTestLabs PowerShell reference](/powershell/module/az.devtestlabs/)

+ Title: Manage storage accounts for labs

+description: Learn about DevTest Labs storage accounts, encryption, customer-managed keys, and setting expiration dates for artifact results storage.

+# Manage Azure DevTest Labs storage accounts

+This article explains how to view and manage the Azure Storage accounts associated with Azure DevTest Labs.

+## View storage account contents

+DevTest Labs automatically creates an Azure Storage account for every lab it creates. To see a lab's storage account and the information it holds:

+1. On the lab's **Overview** page, select the **Resource group**.

+ :::image type="content" source="./media/encrypt-storage/overview-resource-group-link.png" alt-text="Screenshot that shows selecting the resource group on the lab Overview page.":::

+1. On the resource group's **Overview** page, select the lab's storage account. The naming convention for the lab storage account is: `a<labName><4-digit number>`. For example, if the lab name is `contosolab`, the storage account name could be `acontosolab5237`.

+ :::image type="content" source="./media/encrypt-storage/select-storage-account.png" alt-text="Screenshot that shows selecting the storage account in the lab's resource group.":::

+3. On the **Storage account** page, select **Storage browser (preview)** on the left menu, and then select **Blob containers** to see relevant lab-related content.

+ :::image type="content" source="./media/encrypt-storage/storage-explorer.png" alt-text="Screenshot that shows the Storage browser (preview).":::

+## Manage Azure Storage lifecycle

+The lab storage account stores:

+- [Formula documents](devtest-lab-manage-formulas.md) to use for creating lab virtual machines (VMs).

+- [Uploaded virtual hard disks (VHDs)](devtest-lab-create-template.md) to use for creating custom VM images.

+- [Artifact](add-artifact-vm.md) and [Azure Resource Manager (ARM) template](devtest-lab-create-environment-from-arm.md) caches, for faster retrieval during VM and environment creation.

+- Artifact results, which are deployment and extension logs generated from applying artifacts.

+The information in the lab storage account persists for the life of the lab and its resources, unless explicitly deleted. Most of this information is critical for the lab to operate. Manually deleting storage account information can cause data corruption or VM creation errors.

+- Removing uploaded VHDs makes it no longer possible to create custom images from these VHDs.

+- Deleting formula documents can lead to errors when creating VMs from formulas, updating formulas, or creating new formulas.

+- DevTest Labs refreshes the artifact and ARM template caches whenever the lab connects to the artifact or template repositories. If you remove the caches manually, DevTest Labs recreates the caches the next time the lab connects to the repositories.

+### Set expiration for artifact results

+The artifact results size can increase over time as artifacts are applied. You can set an expiration rule for artifact results to regularly delete older results from the storage account. This practice reduces storage account size and helps control costs.

+The following rule sets a 90-day expiration specifically for artifact results:

+## Storage encryption and customer-managed keys

+Azure Storage automatically encrypts all data in the lab storage account. Azure Storage encryption protects your data and helps meet organizational security and compliance commitments. For more information, see [Azure Storage encryption for data at rest](../storage/common/storage-service-encryption.md).

+Azure Storage encrypts lab data with a Microsoft-managed key. Optionally, you can manage encryption with your own keys. If you choose to manage lab storage account encryption with your own key, you can use Azure Key Vault to specify a customer-managed key for encrypting and decrypting data.

+For more information and instructions on configuring customer-managed keys for Azure Storage encryption, see:

+- [Use customer-managed keys with Azure Key Vault to manage Azure Storage encryption](/azure/storage/common/customer-managed-keys-overview.md)

+- [Configure encryption with customer-managed keys stored in Azure Key Vault](/azure/storage/common/customer-managed-keys-configure-key-vault)

+For more information about managing Azure Storage, see [Optimize costs by automatically managing the data lifecycle](../storage/blobs/lifecycle-management-overview.md).

+ Title: Define VM start order with Azure Automation

+description: Learn how to start virtual machines in a specific order by using Azure Automation runbooks in Azure DevTest Labs.

+# Define the startup order for DevTest Lab VMs with Azure Automation

+This article explains how to start up DevTest Labs virtual machines (VMs) in a specific order by using a PowerShell runbook in Azure Automation. The PowerShell script uses tags on lab VMs, so you can change the startup order without having to change the script.

+The DevTest Labs [autostart](devtest-lab-set-lab-policy.md#set-autostart) feature can configure lab VMs to start automatically at a specified time. However, sometimes you might want lab VMs to start in a specific sequence. For example, if a jumpbox VM in a lab is the access point to the other VMs, the jumpbox VM must start before the other VMs.

+## Prerequisites

+- [Create and apply a tag](devtest-lab-add-tag.md) called **StartupOrder** to all lab VMs with an appropriate startup value, 0 through 10. Designate any machines that don't need starting as -1.

+- Create an Azure Automation account by following instructions in [Create a standalone Azure Automation account](/azure/automation/automation-create-standalone-account). Choose the **Run As Accounts** option when you create the account.

+## Create the PowerShell runbook

+1. On the **Overview** page for the Automation Account, select **Runbooks** from the left menu.

+1. On the **Runbooks** page, select **Create a runbook**.

+1. Follow the instructions in [Create an Automation PowerShell runbook using managed identity](../automation/learn/powershell-runbook-managed-identity.md) to create a PowerShell runbook. Populate the runbook with the following PowerShell script.

+## Prepare the PowerShell script

+The following script takes the subscription name and the lab name as parameters. The script gets all the VMs in the lab and parses their tag information to create a list of VM names and their startup order. The script walks through the list in order and starts the VMs.

+If there are multiple VMs in a specific order number, those VMs start asynchronously using PowerShell jobs. VMs that don't have a tag have their startup value set to 10 and start last by default. The script ignores any VMs that have tag values other than 0 through 10.

+# Get the StartupOrder tag. If missing, set to start up last (10).

+## Run the script

+- To run this script daily, [create a schedule](../automation/shared-resources/schedules.md#create-a-schedule) in the Automation Account, and [link the schedule to the runbook](../automation/shared-resources/schedules.md#link-a-schedule-to-a-runbook).

+- In an enterprise scenario that has several subscriptions with multiple labs, you can store the parameter information for different labs and subscriptions in a file. Pass the file to the script instead of passing the individual parameters.

+- This example uses Azure Automation to run the PowerShell script, but you can also use other options, like a [build/release pipeline](use-devtest-labs-build-release-pipelines.md).

+- [What is Azure Automation?](/azure/automation/automation-intro)

+- [Start up lab virtual machines automatically](devtest-lab-auto-startup-vm.md)

+- [Use command-line tools to start and stop Azure DevTest Labs virtual machines](use-command-line-start-stop-virtual-machines.md)

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+> On March 31, 2023, Event Grid on Azure IoT Edge support will be retired, so make sure to transition to IoT Edge native capabilities prior to that date. For more information, see [Transition from Event Grid on Azure IoT Edge to Azure IoT Edge](transition.md).

+ Title: 'Configure custom BGP communities for Azure ExpressRoute private peering using the Azure portal (Preview)'

+description: Learn how to apply or update BGP community value for a new or an existing virtual network using the Azure portal.

+# Configure custom BGP communities for Azure ExpressRoute private peering using the Azure portal (Preview)

+BGP communities are groupings of IP prefixes tagged with a community value. This value can be used to make routing decisions on the router's infrastructure. You can apply filters or specify routing preferences for traffic sent to your on-premises from Azure with BGP community tags. This article explains how to apply a custom BGP community value for your virtual networks using the Azure portal. Once configured, you can view the regional BGP community value and the custom community value of your virtual network. This value will be used for outbound traffic sent over ExpressRoute when originating from that virtual network.

+## Prerequisites

+* Review the [prerequisites](expressroute-prerequisites.md), [routing requirements](expressroute-routing.md), and [workflows](expressroute-workflows.md) before you begin configuration.

+* You must have an active ExpressRoute circuit.

+ * Follow the instructions to [create an ExpressRoute circuit](expressroute-howto-circuit-arm.md) and have the circuit enabled by your connectivity provider.

+ * Ensure that you have Azure private peering configured for your circuit. See the [configure routing](expressroute-howto-routing-arm.md) article for routing instructions.

+ * Ensure that Azure private peering gets configured and establishes BGP peering between your network and Microsoft for end-to-end connectivity.

+

+## Applying or updating the custom BGP value for an existing virtual network

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

+1. Select the virtual network that you want to update the BGP community value for.

+ :::image type="content" source="./media/how-to-configure-custom-bgp-communities-portal/virtual-network-list.png" alt-text="Screenshot of the list of virtual networks.":::

+1. Select the **configure** link below the *BGP community string*.

+ :::image type="content" source="./media/how-to-configure-custom-bgp-communities-portal/virtual-network-overview.png" alt-text="Screenshot of the overview page of a virtual network.":::

+1. On the *BGP community string* page, enter the BGP value you would like to configure this virtual network and then select **Save**.

+ :::image type="content" source="./media/how-to-configure-custom-bgp-communities-portal/bgp-community-value.png" alt-text="Screenshot of the BGP community string page.":::

+> [!IMPORTANT]

+> If your existing virtual network is already connected to an ExpressRoute circuit, you'll need to delete and recreate the ExpressRoute connection after applying the custom BGP community value. See [link a virtual network to an ExpressRoute circuit](expressroute-howto-linkvnet-arm.md), to learn how.

+>

+## Next steps

+- [Verify ExpressRoute connectivity](expressroute-troubleshooting-expressroute-overview.md).

+- [Troubleshoot your network performance](expressroute-troubleshooting-network-performance.md)

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+**resultTruncated** is **true** when there are less resources available than a query is requesting or when paging is disabled or when paging is not possible because:

+```azurecli

+> - **All** output columns are either `dynamic` or `null` type.

+<!-- [!INCLUDE [cloud-shell-try-it.md](../../../includes/cloud-shell-try-it.md)] -->

+ ```azurecli

+ ```azurecli

+ ```azurecli

+ ```azurecli

+ ```azurecli

+```azurecli

+ ```azurecli

+ ```azurecli

+ ```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+| parse kind=regex subnetId with '/virtualNetworks/' virtualNetwork '/subnets/' subnet

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+```azurecli

+<!-- [!INCLUDE [cloud-shell-try-it.md](../../../includes/cloud-shell-try-it.md)] -->

+ ```azurecli

+ ```azurecli

+ ```azurecli

+ ```azurecli

+ ```azurecli

+ ```azurecli

+ ```azurecli

+```azurecli

+>[Release notes: Azure Health Data Services](../release-notes.md)

+> We recommend not provisioning on every reboot of the device, as this could cause some issues when reprovisioning several thousands or millions of devices at once. Instead you should attempt to use the [Device Registration Status Lookup](/rest/api/iot-dps/service/runtime-registration/device-registration-status-lookup) API and try to connect with that information to IoT Hub. If that fails, then try to reprovision as the IoT Hub information might have changed. Keep in mind that querying for the registration state will count as a new device registration, so you should consider the [Device registration limit]( about-iot-dps.md#quotas-and-limits). Also consider implementing an appropriate retry logic, such as exponential back-off with randomization, as described on the [Retry general guidance](/architecture/best-practices/transient-faults).

+> We recommend not provisioning on every reboot of the device, as this could cause some issues when reprovisioning several thousands or millions of devices at once. Instead you should attempt to use the [Device Registration Status Lookup](/rest/api/iot-dps/service/runtime-registration/device-registration-status-lookup) API and try to connect with that information to IoT Hub. If that fails, then try to reprovision as the IoT Hub information might have changed. Keep in mind that querying for the registration state will count as a new device registration, so you should consider the [Device registration limit]( about-iot-dps.md#quotas-and-limits). Also consider implementing an appropriate retry logic, such as exponential back-off with randomization, as described on the [Retry general guidance](/architecture/best-practices/transient-faults).

+Store credential information required to access database or service in secret value. In the case of compound credentials like username/password, it can be stored as a connection string or JSON object. Other information required for management should be stored in tags, i.e., rotation configuration.

+# Quickstart: Create a public load balancer to load balance VMs using the Azure CLI

+Get started with Azure Load Balancer by using the Azure CLI to create a public load balancer and two virtual machines.

+Get started with Azure Load Balancer by using Azure PowerShell to create a public load balancer and two virtual machines.

+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F)

+$rg = @{

+ Name = 'CreatePubLBQS-rg'

+ Location = 'eastus'

+}

+New-AzResourceGroup @rg

+## Create a public IP address

+## Create a load balancer

+* Create a back-end address pool with [New-AzLoadBalancerBackendAddressPoolConfig](/powershell/module/az.network/new-azloadbalancerbackendaddresspoolconfig) for traffic sent from the frontend of the load balancer. This pool is where your backend virtual machines are deployed

+* Create a health probe with [Add-AzLoadBalancerProbeConfig](/powershell/module/az.network/add-azloadbalancerprobeconfig) that determines the health of the backend VM instances

+* Create a load balancer rule with [Add-AzLoadBalancerRuleConfig](/powershell/module/az.network/add-azloadbalancerruleconfig) that defines how traffic is distributed to the VMs

+* Create a public load balancer with [New-AzLoadBalancer](/powershell/module/az.network/new-azloadbalancer)

+$pip = @{

+ Name = 'myPublicIP'

+ ResourceGroupName = 'CreatePubLBQS-rg'

+}

+$publicIp = Get-AzPublicIpAddress @pip

+$fip = @{

+ Name = 'myFrontEnd'

+ PublicIpAddress = $publicIp

+}

+$feip = New-AzLoadBalancerFrontendIpConfig @fip

+## Configure virtual network

+Create an Azure Bastion host to securely manage the virtual machines in the backend pool.

+Use a NAT gateway to provide outbound internet access to resources in the backend pool of your load balancer.

+### Create virtual network, network security group, bastion host, and NAT gateway

+* Create a virtual network with [New-AzVirtualNetwork](/powershell/module/az.network/new-azvirtualnetwork)

+* Create a network security group rule with [New-AzNetworkSecurityRuleConfig](/powershell/module/az.network/new-aznetworksecurityruleconfig)

+* Create an Azure Bastion host with [New-AzBastion](/powershell/module/az.network/new-azbastion)

+* Create a network security group with [New-AzNetworkSecurityGroup](/powershell/module/az.network/new-aznetworksecuritygroup)

+* Create the NAT gateway resource with [New-AzNatGateway](/powershell/module/az.network/new-aznatgateway)

+* Use [New-AzVirtualNetworkSubnetConfig](/powershell/module/az.network/new-azvirtualnetworksubnetconfig) to associate the NAT gateway to the subnet of the virtual network

+## Create public IP address for NAT gateway ##

+$ip = @{

+ Name = 'myNATgatewayIP'

+ AllocationMethod = 'Static'

+$publicIP = New-AzPublicIpAddress @ip

+## Create NAT gateway resource ##

+$nat = @{

+ Name = 'myNATgateway'

+ IdleTimeoutInMinutes = '10'

+ PublicIpAddress = $publicIP

+$natGateway = New-AzNatGateway @nat

+ NatGateway = $natGateway

+## Create virtual machines

+In this section, you'll create the two virtual machines for the backend pool of the load balancer.

+* Create two network interfaces with [New-AzNetworkInterface](/powershell/module/az.network/new-aznetworkinterface)

+* Set an administrator username and password for the VMs with [Get-Credential](/powershell/module/microsoft.powershell.security/get-credential)

+

+

+

+

+

+$net = @{

+ Name = 'myVNet'

+ ResourceGroupName = 'CreatePubLBQS-rg'

+}

+$vnet = Get-AzVirtualNetwork @net

+$ns = @{

+ Name = 'myNSG'

+$nsg = Get-AzNetworkSecurityGroup @ns

+## For loop with variable to create virtual machines for load balancer backend pool. ##

+for ($i=1; $i -le 2; $i++)

+ ## Command to create network interface for VMs ##

+ $nic = @{

+ Name = "myNicVM$i"

+ ResourceGroupName = 'CreatePubLBQS-rg'

+ Location = 'eastus'

+ Subnet = $vnet.Subnets[0]

+ NetworkSecurityGroup = $nsg

+ LoadBalancerBackendAddressPool = $bepool

+ }

+ $nicVM = New-AzNetworkInterface @nic

+ ## Create a virtual machine configuration for VMs ##

+ $vmsz = @{

+ VMName = "myVM$i"

+ VMSize = 'Standard_DS1_v2'

+ }

+ $vmos = @{

+ ComputerName = "myVM$i"

+ Credential = $cred

+ }

+ $vmimage = @{

+ PublisherName = 'MicrosoftWindowsServer'

+ Offer = 'WindowsServer'

+ Skus = '2019-Datacenter'

+ Version = 'latest'

+ }

+ $vmConfig = New-AzVMConfig @vmsz `

+ | Set-AzVMOperatingSystem @vmos -Windows `

+ | Set-AzVMSourceImage @vmimage `

+ | Add-AzVMNetworkInterface -Id $nicVM.Id

+ ## Create the virtual machine for VMs ##

+ $vm = @{

+ ResourceGroupName = 'CreatePubLBQS-rg'

+ Location = 'eastus'

+ VM = $vmConfig

+ Zone = "$i"

+ }

+ New-AzVM @vm -AsJob

+Ensure the **State** of the VM creation is **Completed** before moving on to the next steps.

+> Ensure the virtual machine deployments have completed from the previous steps before proceeding. Use `Get-Job` to check the status of the virtual machine deployment jobs.

+for ($i=1; $i -le 2; $i++)

+Ensure the **State** of the jobs is **Completed** before moving on to the next steps.

+ :::image type="content" source="./media/quickstart-load-balancer-standard-public-portal/load-balancer-test.png" alt-text="Screenshot of the load balancer test web page.":::

+In this quickstart, you:

+* Created an Azure Load Balancer

+* Attached 2 VMs to the load balancer

+* Tested the load balancer

+ Title: Upgrade a basic to standard public load balancer

+description: This article shows you how to upgrade a public load balancer from basic to standard SKU.

+# Upgrade from a basic public to standard public load balancer

+[Azure Standard Load Balancer](load-balancer-overview.md) offers a rich set of functionality and high availability through zone redundancy. To learn more about Azure Load Balancer SKUs, see [comparison table](./skus.md#skus).

+1. Change IP allocation method from **Dynamic** to **Static**.

+An Azure PowerShell script is available that does the following procedures:

+* Creates a standard load balancer with a location you specify in the same resource group of the basic load balancer

+* Upgrades the public IP address from basic SKU to standard SKU in-place

+* Copies the configurations of the basic load balancer to the newly standard load balancer

+* Creates a default outbound rule that enables outbound connectivity

+### Constraints

+* The script only supports a public load balancer upgrade. For an internal basic load balancer upgrade, see [Upgrade from basic internal to standard internal - Azure Load Balancer](./upgrade-basicinternal-standard.md) for instructions and more information

+* The allocation method of the public IP Address must be changed to **static** before running the script

+* If the load balancer doesn't have a frontend IP configuration or backend pool, you'll encounter an error running the script. Ensure the load balancer has a frontend IP and backend pool

+### Change allocation method of the public IP address to static

+The following are the recommended steps to change the allocation method.

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

+2. Select **All resources** in. the left menu. Select the **basic public IP address associated with the basic load balancer** from the resource list.

+3. In the **Settings** of the basic public IP address, select **Configurations**.

+4. In **Assignment**, select **Static**.

+

+5. Select **Save**.

+

+>[!NOTE]

+>For virtual machines which have public IPs, you must create standard IP addresses first. The same IP address is not guaranteed. Disassociate the VMs from the basic IPs and associate them with the newly created standard IP addresses. You'll then be able to follow the instructions to add VMs into the backend pool of the Standard Azure Load Balancer.

+### Create new VMs to add to the backend pool of the new standard load balancer

+* To create a virtual machine and associate it with the load balancer, see [Create virtual machines](./quickstart-load-balancer-standard-public-portal.md#create-virtual-machines).

+Download the migration script from the [PowerShell Gallery](https://www.powershellgallery.com/packages/AzurePublicLBUpgrade/6.0).

+There are two options depending on your local PowerShell environment setup and preferences:

+* If you donΓÇÖt have the Azure Az modules installed, or donΓÇÖt mind uninstalling the Azure Az modules, use the `Install-Script` option to run the script.

+* If you need to keep the Azure Az modules, download the script and run it directly.

+### Install with Install-Script

+To use this option, don't have the Azure Az modules installed on your computer. If they're installed, the following command displays an error. Uninstall the Azure Az modules, or use the other option to download the script manually and run it.

+```azurepowershell

+Install-Script -Name AzurePublicLBUpgrade

+```

+### Install with the script directly

+If you do have Azure Az modules installed and can't uninstall them, or don't want to uninstall them,you can manually download the script using the **Manual Download** tab in the script download link. The script is downloaded as a raw **nupkg** file. To install the script from this **nupkg** file, see [Manual Package Download](/powershell/scripting/gallery/how-to/working-with-packages/manual-download).

+2. Use `Import-Module Az` to import the Az modules.

+3. Examine the required parameters:

+ * **oldRgName: [String]: Required** ΓÇô This parameter is the resource group for your existing basic load balancer you want to upgrade. To find this string value, navigate to the Azure portal, select your basic load balancer source, and select the **Overview** for the load balancer. The resource group is located on that page

+

+ * **oldLBName: [String]: Required** ΓÇô This parameter is the name of your existing the basic load balancer you want to upgrade.

+

+ * **newLBName: [String]: Required** ΓÇô This parameter is the name for the standard load balancer to be created

+4. Run the script using the appropriate parameters. It may take five to seven minutes to finish.

+### Create a NAT gateway for outbound access

+The script creates an outbound rule that enables outbound connectivity. Azure Virtual Network NAT is the recommended service for outbound connectivity. For more information about Azure Virtual Network NAT, see [What is Azure Virtual Network NAT?](../virtual-network/nat-gateway/nat-overview.md).

+To create a NAT gateway resource and associate it with a subnet of your virtual network see, [Create NAT gateway](quickstart-load-balancer-standard-public-portal.md#create-nat-gateway).

+Yes. See [Constraints](#constraints).

+It usually takes a few minutes for the script to finish and it could take longer depending on the complexity of your load balancer configuration. Keep the downtime in mind and plan for failover if necessary.

+### Does the script switch over the traffic from my basic load balancer to the newly created standard load balancer?

+Yes. The Azure PowerShell script upgrades the public IP address, copies the configuration from the basic to standard load balancer, and migrates the virtual machine to the newly created public standard load balancer.

+[Learn about Azure Load Balancer](load-balancer-overview.md)

+ Title: Upgrade an internal basic load balancer - Outbound connections required

+description: Learn how to upgrade a basic internal load balancer to a standard public load balancer.

+# Upgrade an internal basic load balancer - Outbound connections required

+A standard [Azure Load Balancer](load-balancer-overview.md) offers increased functionality and high availability through zone redundancy. For more information about Azure Load Balancer SKUs, see [Azure Load Balancer SKUs](./skus.md#skus). A standard internal Azure Load Balancer doesn't provide outbound connectivity. The PowerShell script in this article, migrates the basic load balancer configuration to a standard public load balancer.

+There are four stages in the upgrade:

+1. Migrate the configuration to a standard public load balancer

+2. Add virtual machines to the backend pools of the standard public load balancer

+3. Create Network Security Group (NSG) rules for subnets and virtual machines that require internet connection restrictions

+This article covers a configuration migration. Adding the VMs to the backend pool may vary depending on your specific environment. See [Add VMs to the backend pools](#add-vms-to-the-backend-pool-of-the-standard-load-balancer) later in this article for recommendations.

+## Upgrade overview

+An Azure PowerShell script is available that does the following procedures:

+* Creates a standard public load balancer in the resource group and location that you specify

+* Copies the configurations of the basic internal load balancer to the newly created standard public load balancer.

+* Creates an outbound rule that enables outbound connectivity

+### Constraints

+* The script supports an internal load balancer upgrade where outbound connectivity is required. If outbound connectivity isn't required, see [Upgrade an internal basic load balancer - Outbound connections not required](upgrade-basicinternal-standard.md).

+* The standard load balancer has a new public address. ItΓÇÖs impossible to move the IP addresses associated with existing basic internal load balancer to a standard public load balancer because of different SKUs.

+* If the standard load balancer is created in a different region, you wonΓÇÖt be able to associate the VMs in the old region. To avoid this constraint, ensure you create new VMs in the new region.

+* If the load balancer doesn't have a frontend IP configuration or backend pool, you'll encounter an error running the script. Ensure the load balancer has a frontend IP and backend pool

+## Download the script

+Download the migration script from the [PowerShell Gallery](https://www.powershellgallery.com/packages/AzureLBUpgrade/2.0).

+## Use the script

+There are two options depending on your local PowerShell environment setup and preferences:

+* If you donΓÇÖt have the Azure Az modules installed, or donΓÇÖt mind uninstalling the Azure Az modules, use the `Install-Script` option to run the script.

+* If you need to keep the Azure Az modules, download the script and run it directly.

+To determine if you have the Azure Az modules installed, run `Get-InstalledModule -Name az`. If you don't see any installed Az modules, then you can use the `Install-Script` method.

+### Install with Install-Script

+To use this option, don't have the Azure Az modules installed on your computer. If they're installed, the following command displays an error. Uninstall the Azure Az modules, or use the other option to download the script manually and run it.

+

+Run the script with the following command:

+```azurepowershell

+Install-Script -Name AzureLBUpgrade

+```

+This command also installs the required Az modules.

+### Install with the script directly

+If you do have Azure Az modules installed and can't uninstall them, or don't want to uninstall them,you can manually download the script using the **Manual Download** tab in the script download link. The script is downloaded as a raw **nupkg** file. To install the script from this **nupkg** file, see [Manual Package Download](/powershell/scripting/gallery/how-to/working-with-packages/manual-download).

+To run the script:

+1. Use `Connect-AzAccount` to connect to Azure.

+2. Use `Import-Module Az` to import the Az modules.

+3. Examine the required parameters:

+ * **oldRgName: [String]: Required** ΓÇô This parameter is the resource group for your existing basic load balancer you want to upgrade. To find this string value, navigate to the Azure portal, select your basic load balancer source, and select the **Overview** for the load balancer. The resource group is located on that page

+

+ * **oldLBName: [String]: Required** ΓÇô This parameter is the name of your existing the basic load balancer you want to upgrade

+ * **newRgName: [String]: Required** ΓÇô This parameter is the resource group where the standard load balancer is created. The resource group can be new or existing. If you choose an existing resource group, the name of the load balancer must be unique within the resource group.

+

+ * **newLocation: [String]: Required** ΓÇô This parameter is the location where the standard load balancer is created. We recommend you choose the same location as the basic load balancer to ensure association of existing resources

+

+ * **newLBName: [String]: Required** ΓÇô This parameter is the name for the standard load balancer to be created

+4. Run the script using the appropriate parameters. It may take five to seven minutes to finish.

+ **Example**

+ ```azurepowershell

+ AzureLBUpgrade.ps1 -oldRgName "test_publicUpgrade_rg" -oldLBName "LBForPublic" -newRgName "test_userInput3_rg" -newLocation "centralus" -newLbName "LBForUpgrade"

+ ```

+### Add VMs to the backend pool of the standard load balancer

+Ensure that the script successfully created a new standard public load balancer with the exact configuration from your basic internal load balancer. You can verify the configuration from the Azure portal.

+Send a small amount of traffic through the standard load balancer as a manual test.

+

+The following scenarios explain how you add VMs to the backend pools of the newly created standard public load balancer, and our recommendations for each scenario:

+* **Move existing VMs from the backend pools of the old basic internal load balancer to the backend pools of the new standard public load balancer**

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

+

+ 2. Select **All resources** in the left menu. Select the **new standard load balancer** from the resource list.

+

+ 3. In the **Settings** in the load balancer page, select **Backend pools**.

+

+ 4. Select the backend pool that matches the backend pool of the basic load balancer.

+

+ 5. Select **Virtual Machine**

+

+ 6. Select the VMs from the matching backend pool of the basic load balancer.

+

+ 7. Select **Save**.

+

+ >[!NOTE]

+ >For virtual machines which have public IPs, you must create standard IP addresses first. The same IP address is not guaranteed. Disassociate the VMs from the basic IPs and associate them with the newly created standard IP addresses. You'll then be able to follow the instructions to add VMs into the backend pool of the Standard Azure Load Balancer.

+* **Create new VMs to add to the backend pools of the new standard public load balancer**.

+

+ * To create a virtual machine and associate it with the load balancer, see [Create virtual machines](./quickstart-load-balancer-standard-public-portal.md#create-virtual-machines).

+### Create a NAT gateway for outbound access

+The script creates an outbound rule that enables outbound connectivity. Azure Virtual Network NAT is the recommended service for outbound connectivity. For more information about Azure Virtual Network NAT, see [What is Azure Virtual Network NAT?](../virtual-network/nat-gateway/nat-overview.md).

+To create a NAT gateway resource and associate it with a subnet of your virtual network see, [Create NAT gateway](quickstart-load-balancer-standard-public-portal.md#create-nat-gateway).

+### Create NSG rules for subnets and virtual machines that require internet connection restrictions

+For more information about creating Network Security Groups and restricting internet traffic, see [Create, change, or delete an Azure network security group](../virtual-network/manage-network-security-group.md).

+## Common questions

+### Are there any limitations with the Azure PowerShell script to migrate the configuration from v1 to v2?

+Yes. See [Constraints](#constraints).

+### Does the Azure PowerShell script switch over the traffic from my basic load Balancer to the new standard load balancer?

+No. The Azure PowerShell script only migrates the configuration. Actual traffic migration is your responsibility and in your control.

+## Next steps

+[Learn about Azure Load Balancer](load-balancer-overview.md)

+ * [Visual Studio 2019, 2017, or 2015 (Community or other edition)](https://aka.ms/download-visual-studio). The Azure Logic Apps extension is currently unavailable for Visual Studio 2022. This quickstart uses Visual Studio Community 2019, which is free.

+ * The latest Azure Logic Apps Tools extension for the Visual Studio version that you want. You can either [learn how install this extension from inside Visual Studio](/visualstudio/ide/finding-and-using-visual-studio-extensions), or you can download the respective versions of the Azure Logic Apps Tools from the Visual Studio Marketplace:

+* For another example using Azure Logic Apps and Azure Functions, try [Tutorial: Automate tasks to process emails by using Azure Logic Apps, Azure Functions, and Azure Storage](tutorial-process-email-attachments-workflow.md)

+Azure portal users will always find the latest image available for provisioning the Data Science Virtual Machine. For CLI or Azure Resource Manager (ARM) users, we keep images of individual versions available for 12 months. After that period, particular version of image is no longer available for provisioning.

+## March 18, 2022

+[Data Science Virtual Machine - Windows 2019](https://azuremarketplace.microsoft.com/marketplace/apps/microsoft-dsvm.dsvm-win-2019?tab=Overview)

+Version: 22.03.09

+Main changes:

+- Updated R environment - added libraries: Cluster, Devtools Factoextra, GlueHere, Ottr, Paletteer, Patchwork, Plotly, Rmd2jupyter, Scales, Statip, Summarytools, Tidyverse, Tidymodels and Testthat

+- Further `Log4j` vulnerability mitigation - although not used, we moved all `log4j` to version v2, we have removed old log4j jars1.0 and moved `log4j` version 2.0 jars.

+- Azure CLI to version 2.33.1

+- Redesign of Conda environments - we're continuing with alignment and refining the Conda environments so we created:

+ - `azureml_py38`: environment based on Python 3.8 with preinstalled [AzureML SDK](/python/api/overview/azure/ml/?view=azure-ml-py) containing also [AutoML](/azure/machine-learning/concept-automated-ml) environment

+ - `azureml_py38_PT_TF`: complementary environment `azureml_py38` with preinstalled with latest TensorFlow and PyTorch

+ - `py38_default`: default system environment based on Python 3.8

+ - we removed `azureml_py36_tensorflow`, `azureml_py36_pytorch`, `py38_tensorflow` and `py38_pytorch` environments.

+Users using Azure Resource Manager (ARM) template / virtual machine scale set (VMSS) to deploy the Windows DSVM machines, should configure the SKU with `winserver-2019` instead of `server-2019`, since we'll continue to ship updates to Windows DSVM images on the new SKU from March, 2022.

+- Fixed a bug where git wasn't available

+- Spark 3.1 incl. mmlspark, connectors to Blob Storage, Data Lake, Cosmos DB

+Added docker. To save resources, the docker service isn't started by default. To start the docker service, run the

+# Create a text labeling project and export labels

+- Coordinate data, labels, and team members to efficiently manage labeling tasks.

+1. To create a project, select **Add project**. Give the project an appropriate name. The project name canΓÇÖt be reused, even if the project is deleted in future.

+ :::image type="content" source="media/how-to-create-text-labeling-projects/text-labeling-creation-wizard.png" alt-text="Labeling project creation for text labeling":::

+ * Choose **Text Classification Multi-class** for projects when you want to apply only a *single label* from a set of labels to each piece of text.

+ * Choose **Text Classification Multi-label** for projects when you want to apply *one or more* labels from a set of labels to each piece of text.

+ * Choose **Text Named Entity Recognition (Preview)** for projects when you want to apply labels to individual or multiple words of text in each entry.

+ > [!IMPORTANT]

+ > Text Named Entity Recognition is currently in public preview.

+ > The preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.

+ > For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

+## Select or create a dataset

+ * Select **Tabular** if you're using a .csv or .tsv file, where each row contains a response. Tabular isn't available for Text Named Entity Recognition projects.

+ * Select **Tabular** if you're using a .csv or .tsv file, where each row is a response. Tabular isn't available for Text Named Entity Recognition projects.

+The exact number of labeled items necessary to start assisted labeling isn't a fixed number. This can vary significantly from one labeling project to another, depending on many factors, including the number of labels classes and label distribution.

+The progress chart shows how many items have been labeled, skipped, in need of review, or not yet done. Hover over the chart to see the number of items in each section.

+* Enable or disable **incremental refresh at regular intervals**, or request an immediate refresh.

+For all project types other than **Text Named Entity Recognition**, you can export:

+For **Text Named Entity Recognition** projects, you can export:

+* An [Azure Machine Learning dataset with labels](how-to-use-labeled-dataset.md).

+* A CoNLL file. For this export, you'll also have to assign a compute resource. The export process runs offline and generates the file as part of an experiment run. When the file is ready to download, you'll see a notification on the top right. Select this to open the notification, which includes the link to the file.

+ :::image type="content" source="media/how-to-create-text-labeling-projects/notification-bar.png" alt-text="Notification for file download.":::

+ * For segmentation models, you may see polygons and labels already present. Correct any that are incorrect before submitting the page.

+> [!Important]

+To correct a mistake, select the "**X**" to clear an individual tag or select the images and then select the tag, which clears the tag from all the selected images. This scenario is shown here. Selecting "Land" will clear that tag from the two selected images.

+3. Select and drag diagonally across your target to create a rough bounding box. To adjust the bounding box, drag the edges or corners.

+To delete a bounding box, select the X-shaped target that appears next to the bounding box after creation.

+Use the **Regions manipulation** tool  or "M" to adjust an existing bounding box. Drag the edges or corners to adjust the shape. Select in the interior to be able to drag the whole bounding box. If you can't edit a region, you've probably toggled the **Lock/unlock regions** tool.

+1. Select for each point in the polygon. When you've completed the shape, double-click to finish.

+To delete a polygon, select the X-shaped target that appears next to the polygon after creation.

+If you want to change the tag for a polygon, select the **Move region** tool, select the polygon, and select the correct tag.

+Use the **Add or remove polygon points** tool  or "U" to adjust an existing polygon. Select the polygon to add or remove a point. If you can't edit a region, you've probably toggled the **Lock/unlock regions** tool.

+## <a name="label-text"></a>Label text

+There are three text project types:

+|Project type | Description |

+| Classification Multi-Class | Assign a single tag to the entire text entry. You can only select one tag for each text item. Select a tag and then select **Submit** to move to the next entry. |

+| Classification Multi-Label | Assign one *or more* tags to each text entry. You can select multiple tags for each text item. Select all the tags that apply and then select **Submit** to move to the next entry. |

+| Named entity recognition (preview) | Tag different words or phrases in each text entry. See directions in the section below.

+> [!IMPORTANT]

+> Named entity recognition is in public preview.

+> The preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.

+> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

+### Tag words and phrases (preview)

+If your project is set up for named entity recognition, you tag different words or phrases in each text item. To label text:

+1. Select the label or type the number corresponding to the appropriate label

+1. Double-click on a word, or use your mouse to select multiple words.

+To change a label, you can:

+* Delete the label and start again.

+* Change the value for all or some of a specific label in your current item:

+ * Select the label itself, which will select all instances of that label.

+ * Select again on the instances of this label to unselect any instances you don't want to change.

+ * Finally, select a new label to change all the labels that are still selected.

+When you've tagged all the items in an entry, select **Submit** to move to the next entry.

+## Search for assets across a workspace (preview)

+With the public preview search capability, you can search for machine learning assets such as jobs, models, components, environments, and datasets across all workspaces, resource groups, and subscriptions in your organization through a unified global view.

+### Free text search

+Type search text into the global search bar on the top of portal and hit enter to trigger a 'contains' search.

+A contains search scans across all metadata fields for the given asset and sorts results relevance.

+You can use the asset quick links to navigate to search results for jobs, models, and components that you created.

+Also, you can change the scope of applicable subscriptions and workspaces via the 'Change' link in the search bar drop down.

+### Structured search

+Select any number of filters to create more specific search queries. The following filters are supported:

+* Job:

+* Model:

+* Component:

+* Tags:

+* SubmittedBy:

+* Environment:

+* Dataset:

+If an asset filter (job, model, component) is present, results are scoped to those tabs. Other filters apply to all assets unless an asset filter is also present in the query. Similarly, free text search can be provided alongside filters, but are scoped to the tabs chosen by asset filters, if present.

+> [!TIP]

+> * Filters search for exact matches of text. Use free text queries for a contains search.

+> * Quotations are required around values that include spaces or other special characters.

+> * If duplicate filters are provided, only the first will be recognized in search results.

+> * Input text of any language is supported but filter strings must match the provided options (ex. submittedBy:).

+> * The tags filter can accept multiple key:value pairs separated by a comma (ex. tags:"key1:value1, key2:value2").

+### View search results

+You can view your search results in the individual **Jobs**, **Models** and **Components** tabs. Select an asset to open its **Details** page in the context of the relevant workspace. Results from workspaces you don't have permissions to view are not displayed.

+If you've used this feature in a previous update, a search result error may occur. Reselect your preferred workspaces in the Directory + Subscription + Workspace tab.

+ from azureml.core import Dataset

+ from azureml.data.datapath import DataPath

+

+ Dataset.File.upload_directory(src_dir='data',

+ target=DataPath(datastore, "datasets/cifar10")

+ )

+1. Select the **Deploy** menu in the top-left and select **Deploy to web service**.

+ Compute type | Select Azure Container Instance (ACI)

+This number represents the count of **Call to Action** button clicks completed on the offer listing page (product detail page). _Calls to action_ are counted when users select the **Get It Now**, **Free Trial**, **Contact Me**, or **Test Drive** buttons. *Consent given* represents the total count of clicks for customer-provided consent to Microsoft or the partner. The following two examples show where *Consent given* clicks appear:

+ [  ](./media/saas-basic-pricing.png#lightbox)

+ [  ](./media/saas-premium-pricing.png#lightbox)

+ [  ](./media/saas-enterprise-pricing.png#lightbox)

+[  ](media/metering-service-dimensions.png#lightbox)

+1. In the **Subscriptions** page, select the subscription in which you want to create a project.

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.

+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+ | Setting | Value |

+ | | |

+ | Role | Contributor or Owner |

+ | Assign access to | User |

+ | Members | azmigrateuser |

+ 

+1. Before initiating discovery, you can choose to disable the slider to not perform software inventory and agentless dependency analysis on the added servers. You can change this option at any time.

+1. In the **Subscriptions** page, select the subscription in which you want to create a project.

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.

+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+ | Setting | Value |

+ | | |

+ | Role | Contributor or Owner |

+ | Assign access to | User |

+ | Members | azmigrateuser |

+ 

+1. Before initiating discovery, you can choose to disable the slider to not perform software inventory and agentless dependency analysis on the added servers. You can change this option at any time.

+1. In the **Subscriptions** page, select the subscription in which you want to create a project.

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.

+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+ | Setting | Value |

+ | | |

+ | Role | Contributor or Owner |

+ | Assign access to | User |

+ | Members | azmigrateuser |

+ 

+1. In case the 'App registrations' settings is set to 'No', request the tenant/global admin to assign the required permission. Alternately, the tenant/global admin can assign the **Application Developer** role to an account to allow the registration of Azure Active Directory App. [Learn more](../active-directory/fundamentals/active-directory-users-assign-role-azure-portal.md).

+1. In the **Subscriptions** page, select the subscription in which you want to create an Azure Migrate project.

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.

+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+ | Setting | Value |

+ | | |

+ | Role | Contributor or Owner |

+ | Assign access to | User |

+ | Members | azmigrateuser |

+ 

+1. In the portal, search for users, and under **Services**, select **Users**.

+1. In **User settings**, verify that Azure AD users can register applications (set to **Yes** by default).

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.

+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+ | Setting | Value |

+ | | |

+ | Role | Contributor or Owner |

+ | Assign access to | User |

+ | Members | azmigrateuser |

+ 

+1. In case the 'App registrations' settings is set to 'No', request the tenant/global admin to assign the required permission. Alternately, the tenant/global admin can assign the **Application Developer** role to an account to allow the registration of Azure Active Directory App. [Learn more](../active-directory/fundamentals/active-directory-users-assign-role-azure-portal.md).

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.

+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+ | Setting | Value |

+ | | |

+ | Role | Contributor or Owner |

+ | Assign access to | User |

+ | Members | azmigrateuser |

+ :::image type="content" source="../../includes/role-based-access-control/media/add-role-assignment-page.png" alt-text="Add role assignment page in Azure portal.":::

+1. If **App registrations** is set to **No**, request the tenant or global admin to assign the required permissions. Alternately, the tenant or global admin can assign the Application Developer role to an account to allow Azure AD app registration by users. [Learn more](../active-directory/fundamentals/active-directory-users-assign-role-azure-portal.md).

+ Title: 'Quickstart: Deploy an Azure Red Hat OpenShift cluster with an ARM template or Bicep'

+description: In this Quickstart, learn how to create an Azure Red Hat OpenShift cluster using an Azure Resource Manager template or a Bicep file.

+keywords: azure, openshift, aro, red hat, arm, bicep

+#Customer intent: I need to use ARM templates or Bicep files to deploy my Azure Red Hat OpenShift cluster.

+zone_pivot_groups: azure-red-hat-openshift

+# Quickstart: Deploy an Azure Red Hat OpenShift cluster with an Azure Resource Manager template or Bicep file

+This quickstart describes how to use either Azure Resource Manager template (ARM template) or Bicep to create an Azure Red Hat OpenShift cluster. You can deploy the Azure Red Hat OpenShift cluster with either PowerShell or the Azure command-line interface (Azure CLI).

+Bicep is a domain-specific language (DSL) that uses declarative syntax to deploy Azure resources. In a Bicep file, you define the infrastructure you want to deploy to Azure, and then use that file throughout the development lifecycle to repeatedly deploy your infrastructure. Your resources are deployed in a consistent manner.

+## Prerequisites

+* Install [Azure CLI](/cli/azure/install-azure-cli)

+* [Bicep](../azure-resource-manager/bicep/install.md)

+* An Azure account with an active subscription is required. If you don't already have one, you can [create an account for free](https://azure.microsoft.com/free/).

+* Ability to assign User Access Administrator and Contributor roles. If you lack this ability, contact your Azure Active Directory admin to manage roles.

+* A Red Hat account. If you don't have one, you'll have to [register for an account](https://www.redhat.com/wapps/ugc/register.html).

+* A pull secret for your Azure Red Hat OpenShift cluster. [Download the pull secret file from the Red Hat OpenShift Cluster Manager web site](https://cloud.redhat.com/openshift/install/azure/aro-provisioned).

+* If you want to run the Azure PowerShell code locally, [Azure PowerShell](/powershell/azure/install-az-ps).

+* If you want to run the Azure CLI code locally:

+ * A Bash shell (such as Git Bash, which is included in [Git for Windows](https://gitforwindows.org)).

+ * [Azure CLI](/cli/azure/install-azure-cli).

+## Create an ARM template or Bicep file

+Choose either an Azure Resource Manager template (ARM template) or an Azure Bicep file. Then, you can deploy the template using either the Azure command line (azure-cli) or PowerShell.

+### Create an ARM template

+The following example shows how your ARM template should look when configured for your Azure RedHat OpenShift cluster.

+The template defines three Azure resources:

+* [**Microsoft.Network/virtualNetworks**](/azure/templates/microsoft.network/virtualnetworks)

+* [**Microsoft.Network/virtualNetworks/providers/roleAssignments**](/azure/templates/microsoft.network/virtualnetworks/providers/roleassignments)

+* [**Microsoft.RedHatOpenShift/OpenShiftClusters**](/azure/templates/microsoft.redhatopenshift/openshiftclusters)

+More Azure Red Hat OpenShift template samples can be found on the [Red Hat OpenShift web site](https://docs.openshift.com/container-platform/4.9/installing/installing_azure/installing-azure-user-infra.html).

+Save the following example as *azuredeploy.json*:

+```json

+{

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "location" : {

+ "type": "string",

+ "defaultValue": "eastus",

+ "metadata": {

+ "description": "Location"

+ }

+ },

+ "domain": {

+ "type": "string",

+ "defaultValue": "",

+ "metadata": {

+ "description": "Domain Prefix"

+ }

+ },

+ "pullSecret": {

+ "type": "string",

+ "metadata": {

+ "description": "Pull secret from cloud.redhat.com. The json should be input as a string"

+ }

+ },

+ "clusterVnetName": {

+ "type": "string",

+ "defaultValue": "aro-vnet",

+ "metadata": {

+ "description": "Name of ARO vNet"

+ }

+ },

+ "clusterVnetCidr": {

+ "type": "string",

+ "defaultValue": "10.100.0.0/15",

+ "metadata": {

+ "description": "ARO vNet Address Space"

+ }

+ },

+ "workerSubnetCidr": {

+ "type": "string",

+ "defaultValue": "10.100.70.0/23",

+ "metadata": {

+ "description": "Worker node subnet address space"

+ }

+ },

+ "masterSubnetCidr": {

+ "type": "string",

+ "defaultValue": "10.100.76.0/24",

+ "metadata": {

+ "description": "Master node subnet address space"

+ }

+ },

+ "masterVmSize" : {

+ "type": "string",

+ "defaultValue": "Standard_D8s_v3",

+ "metadata": {

+ "description": "Master Node VM Type"

+ }

+ },

+ "workerVmSize": {

+ "type": "string",

+ "defaultValue": "Standard_D4s_v3",

+ "metadata": {

+ "description": "Worker Node VM Type"

+ }

+ },

+ "workerVmDiskSize": {

+ "type" : "int",

+ "defaultValue": 128,

+ "minValue": 128,

+ "metadata": {

+ "description": "Worker Node Disk Size in GB"

+ }

+ },

+ "workerCount": {

+ "type": "int",

+ "defaultValue": 3,

+ "minValue": 3,

+ "metadata": {

+ "description": "Number of Worker Nodes"

+ }

+ },

+ "podCidr": {

+ "type": "string",

+ "defaultValue": "10.128.0.0/14",

+ "metadata": {

+ "description": "Cidr for Pods"

+ }

+ },

+ "serviceCidr": {

+ "type": "string",

+ "defaultValue": "172.30.0.0/16",

+ "metadata": {

+ "decription": "Cidr of service"

+ }

+ },

+ "clusterName" : {

+ "type": "string",

+ "metadata": {

+ "description": "Unique name for the cluster"

+ }

+ },

+ "tags": {

+ "type": "object",

+ "defaultValue" : {

+ "env": "Dev",

+ "dept": "Ops"

+ },

+ "metadata": {

+ "description": "Tags for resources"

+ }

+ },

+ "apiServerVisibility": {

+ "type": "string",

+ "allowedValues": [

+ "Private",

+ "Public"

+ ],

+ "defaultValue": "Public",

+ "metadata": {

+ "description": "Api Server Visibility"

+ }

+ },

+ "ingressVisibility": {

+ "type": "string",

+ "allowedValues": [

+ "Private",

+ "Public"

+ ],

+ "defaultValue": "Public",

+ "metadata": {

+ "description": "Ingress Visibility"

+ }

+ },

+ "aadClientId" : {

+ "type": "string",

+ "metadata": {

+ "description": "The Application ID of an Azure Active Directory client application"

+ }

+ },

+ "aadObjectId": {

+ "type": "string",

+ "metadata": {

+ "description": "The Object ID of an Azure Active Directory client application"

+ }

+ },

+ "aadClientSecret" : {

+ "type":"securestring",

+ "metadata": {

+ "description": "The secret of an Azure Active Directory client application"

+ }

+ },

+ "rpObjectId": {

+ "type": "String",

+ "metadata": {

+ "description": "The ObjectID of the Resource Provider Service Principal"

+ }

+ }

+ },

+ "variables": {

+ "contribRole": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]"

+ },

+ "resources": [

+ {

+ "type": "Microsoft.Network/virtualNetworks",

+ "apiVersion": "2020-05-01",

+ "name": "[parameters('clusterVnetName')]",

+ "location": "[parameters('location')]",

+ "tags": "[parameters('tags')]",

+ "properties": {

+ "addressSpace": {

+ "addressPrefixes": [

+ "[parameters('clusterVnetCidr')]"

+ ]

+ },

+ "subnets": [

+ {

+ "name": "master",

+ "properties": {

+ "addressPrefix": "[parameters('masterSubnetCidr')]",

+ "serviceEndpoints": [

+ {

+ "service": "Microsoft.ContainerRegistry"

+ }

+ ],

+ "privateLinkServiceNetworkPolicies": "Disabled"

+ }

+ },

+ {

+ "name": "worker",

+ "properties": {

+ "addressPrefix": "[parameters('workerSubnetCidr')]",

+ "serviceEndpoints": [

+ {

+ "service": "Microsoft.ContainerRegistry"

+ }

+ ]

+ }

+ }]

+ }

+ },

+ {

+ "type": "Microsoft.Network/virtualNetworks/providers/roleAssignments",

+ "apiVersion": "2018-09-01-preview",

+ "name": "[concat(parameters('clusterVnetName'), '/Microsoft.Authorization/', guid(resourceGroup().id, deployment().name, parameters('aadObjectId')))]",

+ "dependsOn": [

+ "[resourceId('Microsoft.Network/virtualNetworks', parameters('clusterVnetName'))]"

+ ],

+ "properties": {

+ "roleDefinitionId": "[variables('contribRole')]",

+ "principalId":"[parameters('aadObjectId')]"

+ }

+ },

+ {

+ "type": "Microsoft.Network/virtualNetworks/providers/roleAssignments",

+ "apiVersion": "2018-09-01-preview",

+ "name": "[concat(parameters('clusterVnetName'), '/Microsoft.Authorization/', guid(resourceGroup().id, deployment().name, parameters('rpObjectId')))]",

+ "dependsOn": [

+ "[resourceId('Microsoft.Network/virtualNetworks', parameters('clusterVnetName'))]"

+ ],

+ "properties": {

+ "roleDefinitionId": "[variables('contribRole')]",

+ "principalId":"[parameters('rpObjectId')]"

+ }

+ },

+ {

+ "type": "Microsoft.RedHatOpenShift/OpenShiftClusters",

+ "apiVersion": "2020-04-30",

+ "name": "[parameters('clusterName')]",

+ "location": "[parameters('location')]",

+ "tags": "[parameters('tags')]",

+ "dependsOn": [

+ "[resourceId('Microsoft.Network/virtualNetworks', parameters('clusterVnetName'))]"

+ ],

+ "properties": {

+ "clusterProfile": {

+ "domain": "[parameters('domain')]",

+ "resourceGroupId": "[concat('/subscriptions/', subscription().subscriptionId,'/resourceGroups/aro-', parameters('domain'))]",

+ "pullSecret": "[parameters('pullSecret')]"

+ },

+ "networkProfile": {

+ "podCidr": "[parameters('podCidr')]",

+ "serviceCidr": "[parameters('serviceCidr')]"

+ },

+ "servicePrincipalProfile": {

+ "clientId": "[parameters('aadClientId')]",

+ "clientSecret": "[parameters('aadClientSecret')]"

+ },

+ "masterProfile": {

+ "vmSize": "[parameters('masterVmSize')]",

+ "subnetId": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('clusterVnetName'), 'master')]"

+ },

+ "workerProfiles": [

+ {

+ "name": "worker",

+ "vmSize": "[parameters('workerVmSize')]",

+ "diskSizeGB": "[parameters('workerVmDiskSize')]",

+ "subnetId": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('clusterVnetName'), 'worker')]",

+ "count": "[parameters('workerCount')]"

+ }

+ ],

+ "apiserverProfile": {

+ "visibility": "[parameters('apiServerVisibility')]"

+ },

+ "ingressProfiles": [

+ {

+ "name": "default",

+ "visibility": "[parameters('ingressVisibility')]"

+ }

+ ]

+ }

+ }

+ ],

+ "outputs": {

+ "clusterCredentials": {

+ "type": "object",

+ "value": "[listCredentials(resourceId('Microsoft.RedHatOpenShift/OpenShiftClusters', parameters('clusterName')), '2020-04-30')]"

+ },

+ "oauthCallbackURL": {

+ "type": "string",

+ "value": "[concat('https://oauth-openshift.apps.', parameters('domain'), '.', parameters('location'), '.aroapp.io/oauth2callback/AAD')]"

+ }

+ }

+}

+```

+### Create a Bicep file

+The following example shows how your Azure Bicep file should look when configured for your Azure Red Hat OpenShift cluster.

+The Bicep file defines three Azure resources:

+* [Microsoft.Network/virtualNetworks](/azure/templates/microsoft.network/virtualnetworks)

+* [Microsoft.Network/virtualNetworks/providers/roleAssignments](/azure/templates/microsoft.network/virtualnetworks/providers/roleassignments)

+* [Microsoft.RedHatOpenShift/OpenShiftClusters](/azure/templates/microsoft.redhatopenshift/openshiftclusters)

+More Azure Red Hat OpenShift templates can be found on the [Red Hat OpenShift web site](https://docs.openshift.com/container-platform/4.9/installing/installing_azure/installing-azure-user-infra.html).

+Create the following Bicep file containing the definition for the Azure Red Hat OpenShift cluster. The following example shows how your Bicep file should look when configured.

+Save the following file as *azuredeploy.json*:

+```bicep

+@description('Location')

+param location string = 'eastus'

+@description('Domain Prefix')

+param domain string = ''

+@description('Pull secret from cloud.redhat.com. The json should be input as a string')

+param pullSecret string

+@description('Name of ARO vNet')

+param clusterVnetName string = 'aro-vnet'

+@description('ARO vNet Address Space')

+param clusterVnetCidr string = '10.100.0.0/15'

+@description('Worker node subnet address space')

+param workerSubnetCidr string = '10.100.70.0/23'

+@description('Master node subnet address space')

+param masterSubnetCidr string = '10.100.76.0/24'

+@description('Master Node VM Type')

+param masterVmSize string = 'Standard_D8s_v3'

+@description('Worker Node VM Type')

+param workerVmSize string = 'Standard_D4s_v3'

+@description('Worker Node Disk Size in GB')

+@minValue(128)

+param workerVmDiskSize int = 128

+@description('Number of Worker Nodes')

+@minValue(3)

+param workerCount int = 3

+@description('Cidr for Pods')

+param podCidr string = '10.128.0.0/14'

+@metadata({

+ description: 'Cidr of service'

+})

+param serviceCidr string = '172.30.0.0/16'

+@description('Unique name for the cluster')

+param clusterName string

+@description('Tags for resources')

+param tags object = {

+ env: 'Dev'

+ dept: 'Ops'

+}

+@description('Api Server Visibility')

+@allowed([

+ 'Private'

+ 'Public'

+])

+param apiServerVisibility string = 'Public'

+@description('Ingress Visibility')

+@allowed([

+ 'Private'

+ 'Public'

+])

+param ingressVisibility string = 'Public'

+@description('The Application ID of an Azure Active Directory client application')

+param aadClientId string

+@description('The Object ID of an Azure Active Directory client application')

+param aadObjectId string

+@description('The secret of an Azure Active Directory client application')

+@secure()

+param aadClientSecret string

+@description('The ObjectID of the Resource Provider Service Principal')

+param rpObjectId string

+var contribRole = '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c'

+resource clusterVnetName_resource 'Microsoft.Network/virtualNetworks@2020-05-01' = {

+ name: clusterVnetName

+ location: location

+ tags: tags

+ properties: {

+ addressSpace: {

+ addressPrefixes: [

+ clusterVnetCidr

+ ]

+ }

+ subnets: [

+ {

+ name: 'master'

+ properties: {

+ addressPrefix: masterSubnetCidr

+ serviceEndpoints: [

+ {

+ service: 'Microsoft.ContainerRegistry'

+ }

+ ]

+ privateLinkServiceNetworkPolicies: 'Disabled'

+ }

+ }

+ {

+ name: 'worker'

+ properties: {

+ addressPrefix: workerSubnetCidr

+ serviceEndpoints: [

+ {

+ service: 'Microsoft.ContainerRegistry'

+ }

+ ]

+ }

+ }

+ ]

+ }

+}

+resource clusterVnetName_Microsoft_Authorization_id_name_aadObjectId 'Microsoft.Network/virtualNetworks/providers/roleAssignments@2018-09-01-preview' = {

+ name: '${clusterVnetName}/Microsoft.Authorization/${guid(resourceGroup().id, deployment().name, aadObjectId)}'

+ properties: {

+ roleDefinitionId: contribRole

+ principalId: aadObjectId

+ }

+ dependsOn: [

+ clusterVnetName_resource

+ ]

+}

+resource clusterVnetName_Microsoft_Authorization_id_name_rpObjectId 'Microsoft.Network/virtualNetworks/providers/roleAssignments@2018-09-01-preview' = {

+ name: '${clusterVnetName}/Microsoft.Authorization/${guid(resourceGroup().id, deployment().name, rpObjectId)}'

+ properties: {

+ roleDefinitionId: contribRole

+ principalId: rpObjectId

+ }

+ dependsOn: [

+ clusterVnetName_resource

+ ]

+}

+resource clusterName_resource 'Microsoft.RedHatOpenShift/OpenShiftClusters@2020-04-30' = {

+ name: clusterName

+ location: location

+ tags: tags

+ properties: {

+ clusterProfile: {

+ domain: domain

+ resourceGroupId: '/subscriptions/${subscription().subscriptionId}/resourceGroups/aro-${domain}-${location}'

+ pullSecret: pullSecret

+ }

+ networkProfile: {

+ podCidr: podCidr

+ serviceCidr: serviceCidr

+ }

+ servicePrincipalProfile: {

+ clientId: aadClientId

+ clientSecret: aadClientSecret

+ }

+ masterProfile: {

+ vmSize: masterVmSize

+ subnetId: resourceId('Microsoft.Network/virtualNetworks/subnets', clusterVnetName, 'master')

+ }

+ workerProfiles: [

+ {

+ name: 'worker'

+ vmSize: workerVmSize

+ diskSizeGB: workerVmDiskSize

+ subnetId: resourceId('Microsoft.Network/virtualNetworks/subnets', clusterVnetName, 'worker')

+ count: workerCount

+ }

+ ]

+ apiserverProfile: {

+ visibility: apiServerVisibility

+ }

+ ingressProfiles: [

+ {

+ name: 'default'

+ visibility: ingressVisibility

+ }

+ ]

+ }

+ dependsOn: [

+ clusterVnetName_resource

+ ]

+}

+```

+## Deploy the azuredeploy.json template

+This section provides information on deploying the azuredeploy.json template.

+### azuredeploy.json parameters

+The azuredeploy.json template is used to deploy an Azure Red Hat OpenShift cluster. The following parameters are required.

+| Property | Description | Valid Options | Default Value |

+|-|-|||

+| `domain` |The domain prefix for the cluster. | | none |

+| `pullSecret` | The pull secret that you obtained from the Red Hat OpenShift Cluster Manager web site.

+| `clusterName` | The name of the cluster. | |

+| `aadClientId` | The application ID (a GUID) of an Azure Active Directory (Azure AD) client application. | |

+| `aadObjectId` | The object ID (a GUID) of the service principal for the Azure AD client application. | |

+| `aadClientSecret` | The client secret of the service principal for the Azure AD client application, as a secure string. | |

+| `rpObjectId` | The object ID (a GUID) of the resource provider service principal. | |

+The template parameters below have default values. They can be specified, but they aren't explicitly required.

+| Property | Description | Valid Options | Default Value |

+|-|-|||

+| `location` | The location of the new ARO cluster. This location can be the same as or different from the resource group region. | | eastus

+| `clusterVnetName` | The name of the virtual network for the ARO cluster. | | aro-vnet

+| `clusterVnetCidr` | The address space of the ARO virtual network, in [Classless Inter-Domain Routing](https://wikipedia.org/wiki/Classless_Inter-Domain_Routing) (CIDR) notation. | | 10.100.0.0/15

+| `workerSubnetCidr` | The address space of the worker node subnet, in CIDR notation. | | 10.100.70.0/23

+| `masterSubnetCidr` | The address space of the control plane node subnet, in CIDR notation. | | 10.100.76.0/24

+| `masterVmSize` | The [virtual machine type/size](../virtual-machines/sizes.md) of the control plane node. | | Standard_D8s_v3

+| `workerVmSize` | The virtual machine type/size of the worker node. | | Standard_D4s_v3

+| `workerVmDiskSize` | The disk size of the worker node, in gigabytes. | | 128

+| `workerCount` | The number of worker nodes. | | 3

+| `podCidr` | The address space of the pods, in CIDR notation. | | 10.128.0.0/14

+| `serviceCidr` | The address space of the service, in CIDR notation. | | 172.30.0.0/16

+| `tags` | A hash table of resource tags. | | `@{env = 'Dev'; dept = 'Ops'}`

+| `apiServerVisibility` | The visibility of the API server (`Public` or `Private`). | | Public

+| `ingressVisibility` | The ingress (entrance) visibility (`Public` or `Private`). | | Public

+The following sections provide instructions using PowerShell or Azure CLI.

+## PowerShell steps

+Perform the following steps if you are using PowerShell.

+### Before you begin - PowerShell

+Before running the commands in this quickstart, you might need to run `Connect-AzAccount`. Check to determine whether you have connectivity to Azure before proceeding. To check whether you have connectivity, run `Get-AzContext` to verify whether you have access to an active Azure subscription.

+> [!NOTE]

+> This template uses the pull secret text that was obtained from the Red Hat OpenShift Cluster Manager website. Before proceeding, ensure you have the pull secret saved locally as `pull-secret.txt`.

+```powershell

+$rhosPullSecret= Get-Content .\pull-secret.txt -Raw # the pull secret text that was obtained from the Red Hat OpenShift Cluster Manager website

+```

+### Define the following parameters as environment variables - PowerShell

+```powershell

+$resourceGroup="aro-rg" # the new resource group for the cluster

+$location="eastus" # the location of the new ARO cluster

+$domain="mydomain" # the domain prefix for the cluster

+$aroClusterName="cluster" # the name of the cluster

+```

+### Register the required resource providers - PowerShell

+Register the following resource providers in your subscription: `Microsoft.RedHatOpenShift`, `Microsoft.Compute`, `Microsoft.Storage` and `Microsoft.Authorization`.

+```powershell

+Register-AzResourceProvider -ProviderNamespace Microsoft.RedHatOpenShift

+Register-AzResourceProvider -ProviderNamespace Microsoft.Compute

+Register-AzResourceProvider -ProviderNamespace Microsoft.Storage

+Register-AzResourceProvider -ProviderNamespace Microsoft.Authorization

+```

+### Create the new resource group - PowerShell

+```powershell

+New-AzResourceGroup -Name $resourceGroup -Location $location

+```

+### Create a new service principal and assign roles - PowerShell

+```powershell

+$suffix=Get-Random # random suffix for the Service Principal

+$spDisplayName="sp-$resourceGroup-$suffix"

+$azureADAppSp = New-AzADServicePrincipal -DisplayName $displayName -Role Contributor

+New-AzRoleAssignment -ObjectId $azureADAppSp.Id -RoleDefinitionName 'User Access Administrator' -ResourceGroupName $resourceGroup -ObjectType 'ServicePrincipal'

+New-AzRoleAssignment -ObJectId $azureADAppSp.Id -RoleDefinitionName 'Contributor' -ResourceGroupName $resourceGroup -ObjectType 'ServicePrincipal'

+```

+### Get the Service Principal password - PowerShell

+```powershell

+$aadClientSecretDigest = ConvertTo-SecureString -String $azureADAppSp.PasswordCredentials.SecretText -AsPlainText -Force

+$aadClientSecretDigest = ConvertTo-SecureString -String $azureADAppSp.PasswordCredentials.SecretText -AsPlainText -Force

+```

+### Get the service principal for the OpenShift resource provider - PowerShell

+```powershell

+$rpOpenShift = Get-AzADServicePrincipal -DisplayName 'Azure Red Hat OpenShift RP' | Select-Object -ExpandProperty Id -Property Id -First 1

+```

+### Check the parameters before deploying the cluster - PowerShell

+```powershell

+# setup the parameters for the deployment

+$templateParams = @{

+ domain = $domain

+ clusterName = $aroClusterName

+ location = $location

+ aadClientId = $azureADAppSp.AppId

+ aadObjectId = $azureADAppSp.Id

+ aadClientSecret = $aadClientSecretDigest

+ rpObjectId = $rpOpenShift.Id

+ pullSecret = $rhosPullSecret

+}

+Write-Verbose (ConvertTo-Json $templateParams) -Verbose

+```

+### Deploy the Azure Red Hat OpenShift cluster using the ARM template - PowerShell

+```powershell

+New-AzResourceGroupDeployment -ResourceGroupName $resourceGroup @templateParams `

+ -TemplateParameterFile azuredeploy.json

+```

+### Connect to your cluster - PowerShell

+To connect to your new cluster, review the steps in [Connect to an Azure Red Hat OpenShift 4 cluster](tutorial-connect-cluster.md).

+### Clean up resources - PowerShell

+Once you're done, run the following command to delete your resource group and all the resources you created in this tutorial.

+```powershell

+Remove-AzResourceGroup -Name $resourceGroup -Force

+```

+## Azure CLI steps

+Perform the following steps if you are using Azure CLI.

+### Before you begin - Azure CLI

+You might need to run `az login` before running the commands in this quickstart. Check whether you have connectivity to Azure before proceeding. To check whether you have connectivity, run `az account list` and verify that you have access to an active Azure subscription.

+> [!NOTE]

+> This template will use the pull secret text that was obtained from the Red Hat OpenShift Cluster Manager website. Before proceeding

+> make sure you have that secret saved locally as `pull-secret.txt`.

+```azurecli-interactive

+PULL_SECRET=$(cat pull-secret.txt) # the pull secret text

+```

+### Define the following parameters as environment variables - Azure CLI

+```azurecli-interactive

+RESOURCEGROUP=aro-rg # the new resource group for the cluster

+LOCATION=eastus # the location of the new cluster

+DOMAIN=mydomain # the domain prefix for the cluster

+CLUSTER=aro-cluster # the name of the cluster

+```

+### Register the required resource providers - Azure CLI

+Register the following resource providers in your subscription: `Microsoft.RedHatOpenShift`, `Microsoft.Compute`, `Microsoft.Storage` and `Microsoft.Authorization`.

+```azurecli-interactive

+az provider register --namespace 'Microsoft.RedHatOpenShift' --wait

+az provider register --namespace 'Microsoft.Compute' --wait

+az provider register --namespace 'Microsoft.Storage' --wait

+az provider register --namespace 'Microsoft.Authorization' --wait

+```

+### Create the new resource group - Azure CLI

+```azurecli-interactive

+az group create --name $RESOURCEGROUP --location $LOCATION

+```

+### Create a service principal for the new Azure AD application

+- Azure CLI

+```azurecli-interactive

+az ad sp create-for-rbac --name "sp-$RG_NAME-${RANDOM}" --role Contributor > app-service-principal.json

+SP_CLIENT_ID=$(jq -r '.appId' app-service-principal.json)

+SP_CLIENT_SECRET=$(jq -r '.password' app-service-principal.json)

+SP_OBJECT_ID=$(az ad sp show --id $SP_CLIENT_ID | jq -r '.objectId')

+```

+### Assign the Contributor role to the new service principal - Azure CLI

+```azurecli-interactive

+az role assignment create \

+ --role 'User Access Administrator' \

+ --assignee-object-id $SP_OBJECT_ID \

+ --resource-group $RESOURCEGROUP \

+ --assignee-principal-type 'ServicePrincipal'

+az role assignment create \

+ --role 'Contributor' \

+ --assignee-object-id $SP_OBJECT_ID \

+ --resource-group $RESOURCEGROUP \

+ --assignee-principal-type 'ServicePrincipal'

+```

+### Get the service principal object ID for the OpenShift resource provider - Azure CLI

+```azurecli-interactive

+ARO_RP_SP_OBJECT_ID=$(az ad sp list --display-name "Azure Red Hat OpenShift RP" --query [0].objectId -o tsv)

+```

+### Deploy the cluster - Azure CLI

+```azurecli-interactive

+az deployment group create \

+ --name aroDeployment \

+ --resource-group $RESOURCEGROUP \

+ --template-file azuredeploy.json \

+ --parameters location=$LOCATION \

+ --parameters domain=$DOMAIN \

+ --parameters pullSecret=$PULL_SECRET \

+ --parameters clusterName=$ARO_CLUSTER_NAME \

+ --parameters aadClientId=$SP_CLIENT_ID \

+ --parameters aadObjectId=$SP_OBJECT_ID \

+ --parameters aadClientSecret=$SP_CLIENT_SECRET \

+ --parameters rpObjectId=$ARO_RP_SP_OBJECT_ID

+```

+### Connect to your cluster - Azure CLI

+To connect to your new cluster, review the steps in [Connect to an Azure Red Hat OpenShift 4 cluster](tutorial-connect-cluster.md).

+### Clean up resources - Azure CLI

+Once you're done, run the following command to delete your resource group and all the resources you created in this tutorial.

+```azurecli-interactive

+az aro delete --resource-group $RESOURCEGROUP --name $ARO_CLUSTER_NAME

+```

+> [!TIP]

+> Having issues? Let us know on GitHub by opening an issue in the [Azure Container Apps repo](https://github.com/microsoft/azure-container-apps).

+## Next steps

+In this article, you learned how to create an Azure Red Hat OpenShift cluster running OpenShift 4 using both ARM templates and Bicep.

+Advance to the next article to learn how to configure the cluster for authentication using Azure Active Directory.

+* [Rotate service principal credentials for your Azure Red Hat OpenShift (ARO) Cluster](howto-service-principal-credential-rotation.md)

+* [Configure authentication with Azure Active Directory using the command line](configure-azure-ad-cli.md)

+* [Configure authentication with Azure Active Directory using the Azure portal and OpenShift web console](configure-azure-ad-cli.md)i

+| [Microsoft.Chaos](#microsoftchaos) |

+### Microsoft.Chaos

+Azure service: [Azure Chaos Studio](../chaos-studio/index.yml)

+> [!div class="mx-tableFixed"]

+> | Action | Description |

+> | | |

+> | Microsoft.Chaos/register/action | Registers the subscription for the Chaos Resource Provider and enables the creation of Chaos resources. |

+> | Microsoft.Chaos/unregister/action | Unregisters the subscription for the Chaos Resource Provider and enables the creation of Chaos resources. |

+> | Microsoft.Chaos/artifactSetDefinitions/write | Creates an Artifact Set Definition which describes the set of artifact to capture for a given Chaos Experiment. |

+> | Microsoft.Chaos/artifactSetDefinitions/read | Gets all Artifact Set Definitions that extend a Chaos Experiment resource. |

+> | Microsoft.Chaos/artifactSetDefinitions/delete | Deletes all Artifact Set Definitions that extend a Chaos Experiment resource. |

+> | Microsoft.Chaos/artifactSetSnapshots/read | Gets all Artifact Set Snapshots that extend a Chaos Experiment resource. |

+> | Microsoft.Chaos/artifactSetSnapshots/artifactSnapshots/read | Gets all Artifact Snapshots that extend a Artifact Set Snapshot. |

+> | Microsoft.Chaos/experiments/write | Creates or updates a Chaos Experiment resource in a resource group. |

+> | Microsoft.Chaos/experiments/delete | Deletes a Chaos Experiment resource in a resource group. |

+> | Microsoft.Chaos/experiments/read | Gets all Chaos Experiments in a resource group. |

+> | Microsoft.Chaos/experiments/start/action | Starts a Chaos Experiment to inject faults. |

+> | Microsoft.Chaos/experiments/cancel/action | Cancels a running Chaos Experiment to stop the fault injection. |

+> | Microsoft.Chaos/experiments/executionDetails/read | Gets all chaos experiment execution details for a given chaos experiment. |

+> | Microsoft.Chaos/experiments/statuses/read | Gets all chaos experiment execution statuses for a given chaos experiment. |

+> | Microsoft.Chaos/locations/targetTypes/read | Gets all TargetTypes. |

+> | Microsoft.Chaos/locations/targetTypes/capabilityTypes/read | Gets all CapabilityType. |

+> | Microsoft.Chaos/operations/read | Read the available Operations for Chaos Studio. |

+> | Microsoft.Chaos/skus/read | Read the available SKUs for Chaos Studio. |

+> | Microsoft.Chaos/targets/write | Creates or update a Target resource that extends a tracked resource. |

+> | Microsoft.Chaos/targets/delete | Deletes a Target resource that extends a tracked resource. |

+> | Microsoft.Chaos/targets/read | Gets all Targets that extend a tracked resource. |

+> | Microsoft.Chaos/targets/capabilities/write | Creates or update a Capability resource that extends a Target resource. |

+> | Microsoft.Chaos/targets/capabilities/delete | Deletes a Capability resource that extends a Target resource. |

+> | Microsoft.Chaos/targets/capabilities/read | Gets all Capabilities that extend a Target resource. |

+| [Knowledge Store (hosted in Azure Storage)](knowledge-store-create-rest.md) | Yes ²| No |

+² If your indexer has an attached skillset that writes back to Azure Storage (for example, it creates a knowledge store or caches enriched content), a managed identity won't work if the storage account is behind a firewall or has IP restrictions. This is a known limitation that will be lifted when managed identity support for skillset scenarios becomes generally available. The solution is to use a full access connection string instead of a managed identity if Azure Storage is behind a firewall.

+> If your indexer has an attached skillset that writes back to Azure Storage (for example, it creates a knowledge store or caches enriched content), a managed identity won't work if the storage account is behind a firewall or has IP restrictions. This is a known limitation that will be lifted when managed identity support for skillset scenarios becomes generally available. The solution is to use a full access connection string instead of a managed identity if Azure Storage is behind a firewall.

+|February | [PII Detection skill](cognitive-search-skill-pii-detection.md) | A cognitive skill that extracts and masks personal information. |

+|February | [Custom Entity Lookup skill](cognitive-search-skill-custom-entity-lookup.md) | A cognitive skill that finds words and phrases from a list and labels all documents with matching entities. |

+|January | [IP rules for in-bound firewall support](service-configure-firewall.md) | New **IpRule** and **NetworkRuleSet** properties in [CreateOrUpdate API](/rest/api/searchmanagement/2020-08-01/services/create-or-update). |

+|January | [Create a private endpoint](service-create-private-endpoint.md) | Set up a Private Link for secure connections to your search service. This preview feature has a dependency [Azure Private Link](../private-link/private-link-overview.md) and [Azure Virtual Network](../virtual-network/virtual-networks-overview.md) as part of the solution. |

+|November | [Document Extraction skill](cognitive-search-skill-document-extraction.md) | A cognitive skill to extract the contents of a file from within a skillset.|

+|November | [Azure Data Lake Storage Gen2](search-howto-index-azure-data-lake-storage.md) and [Cosmos DB Gremlin API (preview)](search-howto-index-cosmosdb.md) | New indexer data sources in public preview. |

+[Service update announcements](https://azure.microsoft.com/updates/?product=search&status=all) for Azure Cognitive Search can be found on the Azure web site.

+ - **All networks** (default). This option enables public access from all networks using an access key. If you select the **All networks** option, the Service Bus namespace accepts connections from any IP address (using the access key). This setting is equivalent to a rule that accepts the 0.0.0.0/0 IP address range.

+- **DonΓÇÖt always use SAS**: Sometimes the risks associated with a particular operation against your Service Bus outweigh the benefits of SAS. For such operations, create a middle-tier service that writes to your Service Bus after business rule validation, authentication, and auditing.

+When an actor is deactivated, references to the actor object are released and it can be garbage collected normally by the common language runtime (CLR) or Java virtual machine (JVM) garbage collector. Garbage collection only cleans up the actor object; it does **not** remove state stored in the actor's State Manager. The next time the actor is activated, a new actor object is created and its state is restored.

+This article shows you how to collect Spring Cloud Resilience4j Circuit Breaker Metrics with Application Insights Java in-process agent. With this feature you can monitor metrics of resilience4j circuit breaker from Application Insights with Micrometer.

+You can launch applications directly from Java source code or from a pre-built JAR. This article explains the deployment procedures.

+For a Java application, you can choose **Load into trust store** for the selected certificate. The certificate will be automatically added to the Java default TrustStores to authenticate a server in SSL authentication.

+2. In the **Default repository** section, set **URI** to `https://github.com/azure-samples/spring-petclinic-microservices-config`.

+> [!CAUTION]

+> It's best to suspend all StorSimple backup retention policies before you select a backup for migration. </br>Migrating your backups takes several days or weeks. StorSimple offers backup retention policies that will delete backups. Backups you have selected for this migration may get deleted before they had a chance to be migrated.

+ **Job definition name**</br>This name should indicate the set of files you're moving. Giving it a similar name as your Azure file share is a good practice. </br></br>**Location where the job runs**</br>When selecting a region, you must select the same region as your StorSimple storage account or, if that isn't available, then a region close to it. </br></br><h3>Source</h3>**Source subscription**</br>Select the subscription in which you store your StorSimple Device Manager resource. </br></br>**StorSimple resource**</br>Select your StorSimple Device Manager your appliance is registered with. </br></br>**Service data encryption key**</br>Check this [prior section in this article](#storsimple-service-data-encryption-key) in case you can't locate the key in your records. </br></br>**Device**</br>Select your StorSimple device that holds the volume where you want to migrate. </br></br>**Volume**</br>Select the source volume. Later you'll decide if you want to migrate the whole volume or subdirectories into the target Azure file share. </br></br> **Volume backups**</br>You can select *Select volume backups* to choose specific backups to move as part of this job. An upcoming, [dedicated section in this article](#selecting-volume-backups-to-migrate) covers the process in detail.</br></br><h3>Target</h3>Select the subscription, storage account, and Azure file share as the target of this migration job.</br></br><h3>Directory mapping</h3>[A dedicated section in this article](#directory-mapping), discusses all relevant details.

+> Selecting more than 50 StorSimple volume backups is not supported. Jobs with a large number of backups may fail. Make sure your backup retention policies don't delete a selected backup before it got a chance to be migrated!

+ Initially, the migration job will have the status: **Never ran**. </br>When you are ready, you can start this migration job. (Select the image for a version with higher resolution.) </br> When a backup was successfully migrated, an automatic Azure file share snapshot will be taken. The original backup date of your StorSimple backup will be placed in the *Comments* section of the Azure file share snapshot. Utilizing this field will allow you to see when the data was originally backed up as compared to the time the file share snapshot was taken.

+> [!CAUTION]

+> Backups must be processed from oldest to newest. Once a migration job is created, you can't change the list of selected StorSimple volume backups. Don't start the job if the list of Backups is incorrect or incomplete. Delete the job and make a new one with the correct backups selected. For each selected backup, check your retention schedules. Backups may get deleted by one or more of your retention policies before they got a chance to be migrated!

+ - Uploaded blobs are of the Block Blob type. Thus, any uploaded VHD or VHDX can't be used in Azure Virtual Machines.

+- When the display scale factor of the screen isn't at 100% and you've set the video window to a certain size, you might see a gray patch on the screen. In most cases, you can get rid of the gray patch by resizing the window.

+ Title: Exchange Online Integration for Email-Outbound from SAP NetWeaver | Microsoft Docs

+description: Learn about Exchange Online integration for email outbound from SAP NetWeaver.

+# Exchange Online Integration for Email-Outbound from SAP NetWeaver

+Sending emails from your SAP backend is a standard feature widely distributed for use cases such as alerting for batch jobs, SAP workflow state changes or invoice distribution. Many customers established the setup using [Exchange Server On-Premises](/exchange/exchange-server). With a shift to [Microsoft 365](https://www.microsoft.com/microsoft-365) and [Exchange Online](/exchange/exchange-online) comes a set of cloud-native approaches impacting that setup.

+This article describes the setup for **outbound** email-communication from NetWeaver-based SAP systems to Exchange Online.

+## Overview

+Existing implementations relied on SMTP Auth and elevated trust relationship because the legacy Exchange Server on-premises could live close to the SAP system itself and was governed by customers themselves. With Exchange Online there's a shift in responsibilities and connectivity paradigm. Microsoft supplies Exchange Online as a Software-as-a-Service offering built to be consumed securely and as effectively as possible from anywhere in the world over the public Internet.

+Follow our standard [guide](/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365) to understand the general configuration of a "device" that wants to send email via Microsoft 365.

+> [!IMPORTANT]

+> Microsoft disabled Basic Authentication for Exchange online as of 2020 for newly created Microsoft 365 tenants. In addition to that, the feature gets disabled for existing tenants with no prior usage of Basic Authentication starting October 2020. See our developer [blog](https://devblogs.microsoft.com/microsoft365dev/deferred-end-of-support-date-for-basic-authentication-in-exchange-online/) for reference.

+> [!IMPORTANT]

+> SMTP Auth was exempted from the Basic Auth feature sunset

+process. However, this is a security risk for your estate, so we advise

+against it. See the latest [post](https://techcommunity.microsoft.com/t5/exchange-team-blog/basic-authentication-and-exchange-online-september-2021-update/ba-p/2772210)

+by our Exchange Team on the matter.

+> [!IMPORTANT]

+> Current OAuth support for SMTP is described on our [Exchange Server documentation for legacy protocols](/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth).

+## Setup considerations

+Given the sunset-exception of SMTP Auth there are four different options supported by SAP NetWeaver that we want to describe. The first three correlate with the scenarios described in the [Exchange Online documentation](/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365).

+1. SMTP Authentication Client Submission

+2. SMTP Direct Send

+3. Using Exchange Online SMTP relay connector

+4. Using SMTP relay server as intermediary to Exchange Online

+For brevity we'll refer to the [**SAP Connect administration tool**](https://wiki.scn.sap.com/wiki/display/SI/SCOT+-+SAPconnect+Administration) used for the mail server setup only by its transaction code SCOT.

+## Option 1: SMTP Authentication Client Submission

+Choose this option when you want to send mail to **people inside and outside** your organization.

+Connect SAP applications directly to Microsoft 365 using SMTP Auth endpoint **smtp.office365.com** in SCOT.

+A valid email address will be required to authenticate with Microsoft 365. The email address of the account that's used to authenticate with Microsoft 365 will appear as the sender of messages from the SAP application.

+### Requirements for SMTP AUTH

+- **SMTP AUTH**: Needs to be enabled for the mailbox being used. SMTP AUTH is disabled for organizations created after January 2020 but can be enabled per-mailbox. For more information, see [Enable or disable authenticated client SMTP submission (SMTP AUTH) in Exchange Online](/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission).

+- **Authentication**: Use Basic Authentication (which is simply a username and password) to send email from SAP application. If SMTP AUTH is intentionally disabled for the organization, you must use Option 2, 3 or 4 below.

+- **Mailbox**: You must have a licensed Microsoft 365 mailbox to send email from.

+- **Transport Layer Security (TLS)**: Your SAP Application must be able to use TLS version 1.2 and above.

+- **Port**: Port 587 (recommended) or port 25 is required and must be unblocked on your network. Some network firewalls or Internet Service Providers block ports, especially port 25, because that\'s the port that email servers use to send mail.

+- **DNS**: Use the DNS name smtp.office365.com. Don't use an IP address for the Microsoft 365 server, as IP Addresses aren't supported.

+### How to Enable SMTP auth for mailboxes in Exchange Online

+There are two ways to enable SMTP AUTH in Exchange online:

+1. For a single account (per mailbox) that overrides the tenant-wide setting or

+2. at organization level.

+> [!NOTE]

+> if your authentication policy disables basic authentication for SMTP, clients cannot use the SMTP AUTH protocol even if you enable the settings outlined in this article.

+The per-mailbox setting to enable SMTP AUTH is available in the [Microsoft 365 Admin Center](https://admin.microsoft.com/) or via [Exchange Online PowerShell](/powershell/exchange/connect-to-exchange-online-powershell).

+1. Open the [Microsoft 365 admin center](https://admin.microsoft.com/) and go to **Users** -> **Active users**.

+ :::image type="content" source="media/exchange-online-integration/admin-center-active-user-sec-1-1.png" alt-text="Admin Center - Active Users":::

+2. Select the user, follow the wizard, click **Mail**.

+3. In the **Email apps** section, click **Manage email apps**.

+ :::image type="content" source="media/exchange-online-integration/admin-center-sec-1-3.png" alt-text="Admin Center - Manage email":::

+4. Verify the **Authenticated SMTP** setting (unchecked = disabled, checked = enabled)

+ :::image type="content" source="media/exchange-online-integration/admin-center-sec-1-4.png" alt-text="Admin Center - SMTP setting":::

+5. **Save changes**.

+This will enable SMTP AUTH for that individual user in Exchange Online that you require for SCOT.

+### Configure SMTP Auth with SCOT

+1. Ping or telnet **smtp.office365.com** on port **587** from your SAP application server to make sure ports are open and accessible.

+ :::image type="content" source="media/exchange-online-integration/telnet-scot-sec-1-1.png" alt-text="Screenshot of ping":::

+2. Make sure SAP Internet Communication Manager (ICM) parameter is set in your instance profile. See below an example:

+ | parameter | value |

+ |||

+ | icm/server-port-1 | PROT=SMTP,PORT=25000,TIMEOUT=180,TLS=1 |

+3. Restart ICM service from SMICM transaction and make sure SMTP service is active.

+ :::image type="content" source="media/exchange-online-integration/scot-smicm-sec-1-3.png" alt-text="Screenshot of ICM setting":::

+4. Activate SAPConnect service in SICF transaction.

+ :::image type="content" source="media/exchange-online-integration/scot-smtp-sec-1-4.png" alt-text="SAP Connect setting in SICF":::

+5. Go to SCOT and select SMTP node (double click) as shown below to proceed with configuration:

+ :::image type="content" source="media/exchange-online-integration/scot-smtp-sec-1-5.png" alt-text="SMTP config":::

+ Add mail host **smtp.office365.com** with port **587**. Check the [Exchange Online docs](/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365#how-to-set-up-smtp-auth-client-submission) for reference.

+ :::image type="content" source="media/exchange-online-integration/scot-smtp-sec-1-5-1.png" alt-text="SMTP config continued":::

+

+ Click on the "Settings" button (next to the Security field) to add TLS settings and basic authentication details as mentioned in point 2 if required. Make sure your ICM parameter is set accordingly.

+

+ Make sure to use a valid Microsoft 365 email ID and password. In addition to that it needs to be the same user that you've enabled for SMTP Auth at the beginning. This email ID will show up as the sender.

+

+ :::image type="content" source="media/exchange-online-integration/scot-smtp-security-serttings-sec-1-5.png" alt-text="SMTP security config":::

+

+ Coming back to the previous screen: Click on "Set" button and check "Internet" under "Supported Address Types". Using the wildcard "\*" option will allow to send emails to all domains without restriction.

+

+ :::image type="content" source="media/exchange-online-integration/scot-smtp-address-type-sec-1-5.png" alt-text="SMTP address type":::

+

+ :::image type="content" source="media/exchange-online-integration/scot-smtp-address-areas-sec-1-5.png" alt-text="SMTP address area":::

+

+ Next Step: set default Domain in SCOT.

+

+ :::image type="content" source="media/exchange-online-integration/scot-default-domain-sec-1-5.png" alt-text="SMTP default domain":::

+

+ :::image type="content" source="media/exchange-online-integration/scot-default-domain-address-sec-1-5.png" alt-text="SMTP default address":::

+6. Schedule Job to send email to the submission queue. From SCOT select "Send Job":

+ :::image type="content" source="media/exchange-online-integration/scot-send-job-sec-1-6.png" alt-text="SMTP schedule job to send":::

+

+ Provide a Job name and variant if appropriate.

+

+ :::image type="content" source="media/exchange-online-integration/scot-send-job-varient-sec-1-6.png" alt-text="SMTP schedule job variant":::

+

+ Test mail submission using transaction code SBWP and check the status using SOST transaction.

+### Limitations of SMTP AUTH client submission

+- SCOT stores login credentials for only one user, so only one Microsoft 365 mailbox can be configured this way. Sending mail via individual SAP users requires to implement the "[Send As permission](/exchange/recipients-in-exchange-online/manage-permissions-for-recipients)" offered by Microsoft 365.

+- Microsoft 365 imposes some sending limits. See [Exchange Online limits - Receiving and sending limits](/office365/servicedescriptions/exchange-online-service-description/exchange-online-limits#receiving-and-sending-limits) for more information.

+## Option 2: SMTP Direct Send

+Microsoft 365 offers the ability to configure [direct send](/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365#option-2-send-mail-directly-from-your-printer-or-application-to-microsoft-365-or-office-365-direct-send) from the SAP application server. This option is limited in that it only permits mail to be routed to addresses in your own Microsoft 365 organization with a valid e-mail address therefore cannot be used for external recipients (e.g., vendors or customers).

+## Option 3: Using Microsoft 365 SMTP Relay Connector

+Only choose this option when:

+- Your Microsoft 365 environment has SMTP AUTH disabled.

+- SMTP client submission (Option 1) isn't compatible with your business needs or with your SAP Application.

+- You can't use direct send (Option 2) because you must send email to external recipients.

+SMTP relay lets Microsoft 365 relay emails on your behalf by using a connector that's configured with your public IP address or a TLS certificate. Compared to the other options, the connector setup increases complexity.

+### Requirements for SMTP Relay

+- **SAP Parameter**: SAP instance parameter configured and SMTP service are activated as explained in option 1, follow steps 2 to 4 from "Configure SMTP Auth with SCOT" section.

+- **Email Address**: Any email address in one of your Microsoft 365 verified domains. This email address doesn't need a mailbox. For example, `noreply@*yourdomain*.com`.

+- **Transport Layer Security (TLS)**: SAP application must be able to use TLS version 1.2 and above.

+- **Port**: port 25 is required and must be unblocked on your network. Some network firewalls or ISPs block ports, especially port 25 due to the risk of misuse for spamming.

+- **MX record**: your Mail Exchanger (MX) endpoint, for e.g., yourdomain.mail.protection.outlook.com. Find more information on the next section.

+- **Relay Access**: A Public IP address or SSL certificate is required to authenticate against the relay connector. To avoid configuring direct access it's recommended to use Source Network Translation (SNAT) as described in this article. [Use Source Network Address Translation (SNAT) for outbound connections](/azure/load-balancer/load-balancer-outbound-connections).

+### Step-by-step configuration instructions for SMTP relay in Microsoft 365

+1. Obtain the public (static) IP address of the endpoint which will be sending the mail using one of the methods listed in the [article](/azure/load-balancer/load-balancer-outbound-connections) above. A dynamic IP address isn\'t supported or allowed. You can share your static IP address with other devices and users, but don't share the IP address with anyone outside of your company. Make a note of this IP address for later.

+ :::image type="content" source="media/exchange-online-integration/azure-portal-pip-sec-3-1.png" alt-text="Where to retrieve the public ip on the Azure Portal":::

+> [!NOTE]

+> Find above information on the Azure portal using the Virtual Machine overview of the SAP application server.

+2. Sign in to the [Microsoft 365 Admin Center](https://admin.microsoft.com/).

+ :::image type="content" source="media/exchange-online-integration/m365-admin-center-sec-3-2.png" alt-text="Microsoft 365 AC sign in":::

+3. Go to **Settings** -> **Domains**, select your domain (for example, contoso.com), and find the Mail Exchanger (MX) record.

+ :::image type="content" source="media/exchange-online-integration/m365-admin-center-domains-sec-3-3.png" alt-text="Where to retrieve the domain mx record":::

+ The Mail Exchanger (MX) record will have data for **Points to address or value** that looks similar to `yourdomain.mail.protection.outlook.com`.

+4. Make a note of the data of **Points to address or value** for the Mail Exchanger (MX) record, which we refer to as your MX endpoint.

+5. In Microsoft 365, select **Admin** and then **Exchange** to go to the new Exchange Admin Center.

+ :::image type="content" source="media/exchange-online-integration/m365-admin-center-exchange-sec-3-5.png" alt-text="Microsoft 365 Admin Center":::

+6. New Exchange Admin Center (EAC) portal will open.

+ :::image type="content" source="media/exchange-online-integration/exchange-admin-center-sec-3-6.png" alt-text="Microsoft 365 Admin Center mailbox":::

+7. In the Exchange Admin Center (EAC), go to **Mail flow** -> **Connectors**. The **Connectors** screen is depicted below. If you are working with the classical EAC follow step 8 as described on our [docs](/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365#step-by-step-configuration-instructions-for-smtp-relay).

+ :::image type="content" source="media/exchange-online-integration/exchange-admin-center-add-connector-sec-3-7.png" alt-text="Microsoft 365 Admin Center connector":::

+8. Click **Add a connector**

+ :::image type="content" source="media/exchange-online-integration/exchange-relay-connector-add-sec-3-8.png" alt-text="Microsoft 365 Admin Center connector add":::

+ Choose "Your organization's email server".

+ :::image type="content" source="media/exchange-online-integration/new-connector-sec-3-8.png" alt-text="Microsoft 365 Admin Center mail server":::

+9. Click **Next**. The **Connector name** screen appears.

+ :::image type="content" source="media/exchange-online-integration/connector-name-section-3-9.png" alt-text="Microsoft 365 Admin Center connector name":::

+10. Provide a name for the connector and click **Next**. The **Authenticating sent email** screen appears.

+ Choose *By verifying that the IP address of the sending server matches one of these IP addresses which belong exclusively to your organization* and add the IP address from Step 1 of the **Step-by-step configuration instructions for SMTP relay in Microsoft 365** section.

+ :::image type="content" source="media/exchange-online-integration/connector-authenticate-ip-add-section-3-10-1.png" alt-text="Microsoft 365 Admin Center verify IP":::

+

+ Review and click on **Create connector**.

+

+ :::image type="content" source="media/exchange-online-integration/review-connector-section-3-10-2.png" alt-text="Microsoft 365 Admin Center review":::

+

+ :::image type="content" source="media/exchange-online-integration/connector-created-sec-3-10-3.png" alt-text="Microsoft 365 Admin Center review security settings":::

+11. Now that you're done with configuring your Microsoft 365 settings, go to your domain registrar's website to update your DNS records. Edit your **Sender Policy Framework** (SPF) record. Include the IP address that you noted in step 1. The finished string should look similar to this `v=spf1 ip4:10.5.3.2 include:spf.protection.outlook.com \~all`, where 10.5.3.2 is your public IP address. Skipping this step may cause emails to be flagged as spam and end up in the recipient's Junk Email folder.

+### Steps in SAP Application server

+1. Make sure SAP ICM Parameter and SMTP service is activated as explained in Option 1 (steps 2-4)

+2. Go to SCOT transaction in SMTP node as shown in previous steps of Option 1.

+3. Add mail Host as Mail Exchanger (MX) record value noted in Step 4 (i.e. yourdomain.mail.protection.outlook.com).

+Mail host: yourdomain.mail.protection.outlook.com

+Port: 25

+4. Click "Settings" next to the Security field and make sure TLS is enabled if possible. Also make sure no prior logon data regarding SMTP AUTH is present. Otherwise delete existing records with the corresponding button underneath.

+ :::image type="content" source="media/exchange-online-integration/scot-smtp-connection-relay-tls-sec-3-4.png" alt-text="SMTP security config in SCOT":::

+5. Test the configuration using a test email from your SAP application with transaction SBWP and check the status in SOST transaction.

+## Option 4: Using SMTP relay server as intermediary to Exchange Online

+An intermediate relay server can be an alternative to a direct connection from the SAP application server to Microsoft 365. This server can be based on any mail server that will allow direct authentication and relay services.

+The advantage of this solution is that it can be deployed in the hub of a hub-spoke virtual network within your Azure environment or within a DMZ to protect your SAP application hosts from direct access. It also allows for centralized outbound routing to immediately offload all mail traffic to a central relay when sending from multiple application servers.

+The configuration steps are the same as for the Microsoft 365 SMTP Relay Connector (Option 3) with the only differences being that the SCOT configuration should reference the mail host that will perform the relay rather than direct to Microsoft 365. Depending on the mail system that is being used for the relay it will also be configured directly to connect to Microsoft 365 using one of the supported methods and a valid user with password. It is recommended to send a test mail from the relay directly to ensure it can communicate successfully with Microsoft 365 before completing the SAP SCOT configuration and testing as normal.

+The example architecture shown illustrates multiple SAP application servers with a single mail relay host in the hub. Depending on the volume of mail to be sent it is recommended to follow a detailed sizing guide for the mail vendor to be used as the relay. This may require multiple mail relay hosts which operate with an Azure Load Balancer.

+## Next Steps

+[Understand mass-mailing with Azure Twilio - SendGrid](https://docs.sendgrid.com/for-developers/partners/microsoft-azure-2021)

+[Understand Exchange Online Service limitations (e.g., attachment size, message limits, throttling etc.)](/office365/servicedescriptions/exchange-online-service-description/exchange-online-limits)

+* Outbound connectivity can be defined for each subnet with a NAT gateway. Multiple subnets within the same virtual network can have different NAT gateways associated. Multiple subnets within the same virtual network can use the same NAT gateway. A subnet is configured by specifying which NAT gateway resource to use. All outbound traffic for the subnet is processed by the NAT gateway without any customer configuration. A NAT gateway takes precedence over other outbound scenarios and replaces the default Internet destination of a subnet

+* Presence of custom UDRs for virtual appliances and ExpressRoute override NAT gateway for directing internet bound traffic (route to the 0.0.0.0/0 address prefix). See [Troubleshooting NAT gateway](./troubleshoot-nat.md#virtual-appliance-udrs-and-vpn-expressroute-override-nat-gateway-for-routing-outbound-traffic) to learn more

+* Virtual Network NAT supports TCP and UDP protocols only. ICMP isn't supported

+* Virtual Network NAT is compatible with standard SKU public IP addresses or public IP prefix resources or a combination of both. You can use a public IP prefix directly or distribute the public IP addresses of the prefix across multiple NAT gateway resources. The NAT gateway will groom all traffic to the range of IP addresses of the prefix. Basic resources, such as basic load balancer or basic public IPs aren't compatible with Virtual Network NAT. Basic resources must be placed on a subnet not associated to a NAT gateway. Basic load balancer and basic public IP can be upgraded to standard to work with a NAT gateway

+* To upgrade a basic load balancer too standard, see [Upgrade a public basic Azure Load Balancer](../../load-balancer/upgrade-basic-standard.md)

+* Virtual Network NAT is the recommended method for outbound connectivity. A NAT gateway doesn't have the same limitations of SNAT port exhaustion as does [default outbound access](../ip-services/default-outbound-access.md) and [outbound rules of a load balancer](../../load-balancer/outbound-rules.md)

+* A NAT gateway canΓÇÖt be associated to an IPv6 public IP address or IPv6 public IP prefix. It can be associated to a dual stack subnet

+* A NAT gateway allows flows to be created from the virtual network to the services outside your virtual network. Return traffic from the Internet is only allowed in response to an active flow. Services outside your virtual network canΓÇÖt initiate an inbound connection through NAT gateway

+* A NAT gateway canΓÇÖt span multiple virtual networks

+* Multiple NAT gateways canΓÇÖt be attached to a single subnet

+* Virtual machine instances or other compute resources, send TCP reset packets or attempt to communicate on a TCP connection that doesn't exist. An example is connections that have reached idle timeout. The next packet received will return a TCP reset to the private IP address to signal and force connection closure. The public side of a NAT gateway doesn't generate TCP reset packets or any other traffic. Only traffic produced by the customer's virtual network is emitted

+* A default TCP idle timeout of 4 minutes is used and can be increased to up to 120 minutes. Any activity on a flow can also reset the idle timer, including TCP keepalives

+* To create and validate a NAT gateway, see [Tutorial: Create a NAT gateway using the Azure portal](tutorial-create-nat-gateway-portal.md)

+* To view a video on more information about Azure Virtual Network NAT, see [How to get better outbound connectivity using an Azure NAT gateway](https://www.youtube.com/watch?v=2Ng_uM0ZaB4)

+* Learn about the [NAT gateway resource](./nat-gateway-resource.md)

+You can also deploy the Shared Address space reserved in [RFC 6598](https://datatracker.ietf.org/doc/html/rfc6598), which is treated as Private IP Address space in Azure:

+* 100.64.0.0 - 100.127.255.255 (100.64/10 prefix)

+> [!NOTE]

+> Set the **CaptureSingleDirectionTrafficOnly** option to **false** if you want to capture both inner and outer packets.

+> [!NOTE]

+> Do not select the **Capture Single Direction Traffic Only** option if you want to capture both inner and outer packets.

+There are specific rules regarding resizing vs. changing a gateway SKU. In this section, we'll resize the SKU. For more information, see [Gateway settings - resizing and changing SKUs](vpn-gateway-about-vpn-gateway-settings.md#resizechange).

+ Title: Monitoring metrics for Azure Application Gateway Web Application Firewall metrics

+description: This article describes the Azure Application Gateway WAF monitoring metrics.

+# Azure Web Application Firewall Monitoring and Logging

+Azure Web Application Firewall (WAF) monitoring and logging are provided through logging and integration with Azure Monitor and Azure Monitor logs.

+## Azure Monitor

+WAF with Application Gateway log is integrated with [Azure Monitor](../../azure-monitor/overview.md). Azure Monitor allows you to track diagnostic information including WAF alerts and logs. You can configure WAF monitoring within the Application Gateway resource in the portal under the **Diagnostics** tab or through the Azure Monitor service directly.

+## Logs and diagnostics

+WAF with Application Gateway provides detailed reporting on each threat it detects. Logging is integrated with Azure Diagnostics logs and alerts are recorded in a json format. These logs can be integrated with [Azure Monitor logs](../../azure-monitor/insights/azure-networking-analytics.md).

+

+For additional information on diagnostics log, visit [Application Gateway WAF resource logs](../ag/web-application-firewall-logs.md)

+## Application Gateway WAF V2 Metrics

+New WAF metrics are only available for Core Rule Set 3.2 or greater, or with bot protection and geo-filtering. The metrics can be further filtered on the supported dimensions.

+

+|**Metrics**|**Description**|**Dimension**|

+| :| :-| :--|

+|**WAF Total Requests**|Count of successful requests that WAF engine has served.| Action, Country/Region, Method, Mode|

+|**WAF Managed Rule Matches**|Count of total requests that a managed rule has matched.| Action, Country/Region, Mode, Rule Group, Rule Id |

+|**WAF Custom Rule Matches**|Count of total requests that match a specific custom rule. | Action, Country/Region, Mode, Rule Group, Rule Name|

+|**WAF Bot Protection Matches**|Count of total requests that have been blocked or logged from malicious IP addresses. The IP addresses are sourced from the Microsoft Threat Intelligence feed.| Action, Country/Region, Bot Type, Mode|

+For metrics supported by Application Gateway V2 SKU, see [Application Gateway v2 metrics](../../application-gateway/application-gateway-metrics.md#metrics-supported-by-application-gateway-v2-sku)

+## Application Gateway WAF V1 Metrics

+|**Metrics**|**Description**|**Dimension**|

+| :| :-| :--|

+|**Web Application Firewall Blocked Requests Count**|Count of total requests that have been blocked by the WAF engine||

+|**Web Application Firewall Blocked Requests Distribution**|Total number of rules hit distribution for the blocked requests by Rule Group and Rule ID|Rule Group, Rule ID|

+|**Web Application Firewall Total Rule Distribution**|Count of total matched requests distribution by Rule Group and Rule ID |Rule Group, Rule ID|

+For metrics supported by Application Gateway V1 SKU, see [Application Gateway v1 metrics](../../application-gateway/application-gateway-metrics.md#metrics-supported-by-application-gateway-v1-sku)

+ ## Access WAF Metrics in Azure portal

+1. From the Azure portal menu, select **All Resources** >> **\<your-Application-Gateway-profile>**.

+2. Under **Monitoring**, select **Metrics**:

+3. In **Metrics**, select the metric to add:

+

+

+4. Select Add filter to add a filter:

+ 5. Select New chart to add a new chart

+

+ ## Configure Alerts in Azure portal

+1. Set up alerts on Azure Application Gateway by selecting **Monitoring** >> **Alerts**.

+1. Select **New alert rule** for metrics listed in Metrics section.

+Alert will be charged based on Azure Monitor. For more information about alerts, see [Azure Monitor alerts](../../azure-monitor/alerts/alerts-overview.md).

+## Next steps

+- Learn about [Web Application Firewall](../overview.md).

+- Learn about [Web Application Firewall Logs](../ag/web-application-firewall-logs.md).