Merge pull request #106101 from PatrickFarley/formre-updates

[cog serv] Formre updates

Author: ShannonLeavitt

articles/cognitive-services/form-recognizer/deploy-label-tool.md

@@ -0,0 +1,41 @@
+---
+title: How to deploy the Form Recognizer sample labeling tool
+titleSuffix: Azure Cognitive Services
+description: Learn the different ways you can deploy the Form Recognizer sample labeling tool to help with supervised learning.
+author: PatrickFarley
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: forms-recognizer
+ms.topic: conceptual
+ms.date: 02/28/2020
+ms.author: pafarley
+---
+
+# Deploy the sample labeling tool
+
+The Form Recognizer sample labeling tool is an application that runs in a Docker container. It provides a helpful UI that you can use to manually label form documents for the purpose of supervised learning. The [Train with labels](./quickstarts/label-tool.md) quickstart shows you how to run the tool on your local computer, which is the most common scenario. 
+
+This guide will explain alternate ways you can deploy and run the sample labeling tool. 
+
+## Deploy with Azure Container Instances
+
+You can run the label tool in a Docker web app container. First, [create a new Web App resource](https://ms.portal.azure.com/#create/Microsoft.WebSite) on the Azure portal. Fill in the form with your subscription and resource group details. Enter the following information in the required fields:
+* **Publish**: Docker Container
+* **Operating** System: Linux
+
+On the next page, fill in the following fields for the Docker container setup:
+
+* **Options**: Single Container
+* **Image Source**: Azure Container Registry
+* **Access Type**: public
+* **Image and tag**: mcr.microsoft.com/azure-cognitive-services/custom-form/labeltool:latest
+
+The steps that follow are optional. Once your app has finished deploying, you can run it and access the label tool online.
+
+### Connect to Azure AD for authorization
+
+We recommend to connect your web app to Azure Active Director (AAD) so that only someone with your credentials can sign in and use the app. Follow the instructions in [Configure your App Service app](https://docs.microsoft.com/azure/app-service/configure-authentication-provider-aad) to connect to AAD.
+
+## Next steps
+
+Return to the [Train with labels](./quickstarts/label-tool.md) quickstart to learn how to use the tool to manually label training data and do supervised learning.

articles/cognitive-services/form-recognizer/includes/create-resource.md

@@ -7,7 +7,7 @@ ms.date: 06/12/2019
 ms.author: pafarley
 ---
 
-Go to the Azure Portal and [create a new Form Recognizer resource](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer). In the **Create** pane, provide the following information:
+Go to the Azure portal and <a href="https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer" title="Create a new Form Recognizer resource" target="_blank">create a new Form Recognizer resource <span class="docon docon-navigate-external x-hidden-focus"></span></a>. In the **Create** pane, provide the following information:
 
 |    |    |
 |--|--|
@@ -20,4 +20,4 @@ Go to the Azure Portal and [create a new Form Recognizer resource](https://ms.po
 > [!IMPORTANT]
 > Normally when you create a Cognitive Service resource in the Azure portal, you have the option to create a multi-service subscription key (used across multiple cognitive services) or a single-service subscription key (used only with a specific cognitive service). However, because Form Recognizer is a preview release, it is not included in the multi-service subscription, and you cannot create the single-service subscription unless you use the link provided in the Welcome email.
 
-When your Form Recognizer resource finishes deploying, find and select it from the **All resources** list in the portal. Then select the **Quick start** tab to view your subscription data. Save the values of **Key1** and **Endpoint** to a temporary location. You'll use them in the following steps.
+When your Form Recognizer resource finishes deploying, find and select it from the **All resources** list in the portal. Then select the **Quick start** tab to view your subscription data. Save the values of **Key1** and **Endpoint** to a temporary location. You'll use them in the following steps.

articles/cognitive-services/form-recognizer/index.yml

@@ -8,7 +8,7 @@ metadata:
   description: Azure Form Recognizer is a cognitive service that uses machine learning technology to identify and extract key-value pairs and table data from form documents. It then outputs structured data that includes the relationships in the original file. Unsupervised learning allows the model to understand the layout and field data without manual data labeling or intensive coding. You can also do supervised learning with manually labeled data. Models trained with labeled data can perform better and can work with more complicated documents. # Required; article description that is displayed in search results. < 160 chars.
   services: cognitive-services
   ms.service: cognitive-services #Required; service per approved list. service slug assigned to your service by ACOM.
-  ms.subservice: form-recognizer
+  ms.subservice: forms-recognizer
   ms.topic: landing-page # Required
   author: PatrickFarley #Required; your GitHub user alias, with correct capitalization.
   ms.author: pafarley #Required; microsoft alias of author; optional team alias.

articles/cognitive-services/form-recognizer/quickstarts/label-tool.md

@@ -31,12 +31,19 @@ To complete this quickstart, you must have:
 ## Set up the sample labeling tool
 
 You'll use the Docker engine to run the sample labeling tool. Follow these steps to set up the Docker container. For a primer on Docker and container basics, see the [Docker overview](https://docs.docker.com/engine/docker-overview/).
-1. First, install Docker on a host computer. The host computer can be your local computer ([Windows](https://docs.docker.com/docker-for-windows/), [macOS](https://docs.docker.com/docker-for-mac/), or [Linux](https://docs.docker.com/install/)). Or, you can use a Docker hosting service in Azure, such as the [Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/index), [Azure Container Instances](https://docs.microsoft.com/azure/container-instances/index), or a Kubernetes cluster [deployed to an Azure Stack](https://docs.microsoft.com/azure-stack/user/azure-stack-solution-template-kubernetes-deploy?view=azs-1910). The host computer must meet the following hardware requirements:
+1. First, install Docker on a host computer. This guide will show you how to use local computer as a host. If you want to use a Docker hosting service in Azure, see the [Deploy the sample labeling tool](../deploy-label-tool.md) how-to guide. 
+
+   The host computer must meet the following hardware requirements:
 
     | Container | Minimum | Recommended|
     |:--|:--|:--|
     |Sample labeling tool|2 core, 4-GB memory|4 core, 8-GB memory|
-    
+
+   Install Docker on your machine by following the appropriate instructions for your operating system: 
+   * [Windows](https://docs.docker.com/docker-for-windows/)
+   * [macOS](https://docs.docker.com/docker-for-mac/)
+   * [Linux](https://docs.docker.com/install/).
+
 1. Get the sample labeling tool container with the `docker pull` command.
     ```
     docker pull mcr.microsoft.com/azure-cognitive-services/custom-form/labeltool
@@ -112,17 +119,23 @@ Click **Run OCR on all files** on the left pane to get the text layout informati
 
 ### Apply labels to text
 
-Next, you'll create labels and apply them to the text elements that you want the model to recognize.
+Next, you'll create tags (labels) and apply them to the text elements that you want the model to recognize.
 
-1. First, use the tags editor pane to create the tags (labels) you'd like to identify.
+1. First, use the tags editor pane to create the tags you'd like to identify.
+  1. Click **+** to create a new tag.
+  1. Enter the tag name.
+  1. Press Enter to save the tag.
 1. In the main editor, click and drag to select one or multiple words from the highlighted text elements.
+1. Click on the tag you want to apply, or press the corresponding keyboard key. The number keys are assigned as hotkeys for the first 10 tags. You can reorder your tags using the up and down arrow icons in the tag editor pane.
+    > [!Tip]
+    > Keep the following tips in mind when you're labeling your forms.
+    > * You can only apply one tag to each selected text element.
+    > * Each tag can only be applied once per page. If a value appears multiple times on the same form, create different tags for each instance. For example: "invoice# 1", "invoice# 2" and so on.
+    > * Tags cannot span across pages.
+    > * Label values as they appear on the form; don't try to split a value into two parts with two different tags. For example, an address field should be labeled with a single tag even if it spans multiple lines.
+    > * Don't include keys in your tagged fields—only the values.
+    > * Table data should be detected automatically and will be available in the final output JSON file. However, if the model fails to detect all of your table data, you can manually tag these fields as well. Tag each cell in the table with a different label. If your forms have tables with varying numbers of rows, make sure you tag at least one form with the largest possible table.
 
-    > [!NOTE]
-    > You cannot currently select text that spans across multiple pages.
-1. Click on the tag you want to apply, or press corresponding keyboard key. You can only apply one tag to each selected text element, and each tag can only be applied once per page.
-
-    > [!TIP]
-    > The number keys are assigned as hotkeys for the first ten tags. You can reorder your tags using the up and down arrow icons in the tag editor pane.
 
 Follow the above steps to label five of your forms, and then move on to the next step.
 

articles/cognitive-services/form-recognizer/toc.yml

@@ -46,6 +46,8 @@
   items:
   - name: Build a training data set
     href: build-training-data-set.md
+  - name: Deploy the sample labeling tool
+    href: deploy-label-tool.md
   - name: Use containers
     items:
     - name: Install and run containers