Merge pull request #229797 from laujan/query-fields

add concept-query-fields

Author: JamesJBarnett

articles/applied-ai-services/form-recognizer/concept-query-fields.md

@@ -0,0 +1,49 @@
+---
+title: Query field extraction - Form Recognizer
+titleSuffix: Azure Applied AI Services
+description: Use Form Recognizer to extract query field data.
+author: laujan
+manager: nitinme
+ms.service: applied-ai-services
+ms.subservice: forms-recognizer
+ms.topic: conceptual
+ms.date: 03/07/2023
+ms.author: netahw
+monikerRange: 'form-recog-3.0.0'
+recommendations: false
+---
+<!-- markdownlint-disable MD033 -->
+
+# Azure Form Recognizer query field extraction
+
+**This article applies to:** ![Form Recognizer v3.0 checkmark](media/yes-icon.png) **Form Recognizer v3.0**.
+
+> [!IMPORTANT]
+>
+> * The Form Recognizer Studio query fields extraction feature is currently in gated preview. Features, approaches and processes may change, prior to General Availability (GA), based on user feedback.
+> * Complete and submit the [**Form Recognizer private preview request form**](https://aka.ms/form-recognizer/preview/survey) to request access.
+
+Form Recognizer now supports query field extractions using Azure OpenAI capabilities. With query field extraction, you can add fields to the extraction process using a query request without the need for added training.
+
+> [!NOTE]
+>
+> Form Recognizer Studio query field extraction is currently available with the general document model for the `2023-02-28-preview` release.
+
+## Select query fields
+
+For query field extraction, specify the fields you want to extract and Form Recognizer analyzes the document accordingly. Here's an example:
+
+* If you're processing a contract in the Form Recognizer Studio, you can pass a list of field labels like `Party1`, `Party2`, `TermsOfUse`, `PaymentTerms`, `PaymentDate`, and `TermEndDate`" as part of the analyze document request.
+
+   :::image type="content" source="media/studio/query-field-select.png" alt-text="Screenshot of query fields selection window in Form Recognizer Studio.":::
+
+* Form Recognizer utilizes the capabilities of both [**Azure OpenAI Service**](../../cognitive-services/openai/overview.md) and extraction models to analyze and extract the field data and return the values in a structured JSON output.
+
+* In addition to the query fields, the response includes text, tables, selection marks, general document key-value pairs, and other relevant data.
+
+   :::image type="content" source="media/studio/query-field-analyze.png" alt-text="Screenshot of query field analysis in Form Recognizer Studio.":::
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Try the Form Recognizer Studio quickstart](./quickstarts/try-form-recognizer-studio.md)

articles/applied-ai-services/form-recognizer/concept-w2.md

@@ -21,23 +21,23 @@ The Form Recognizer W-2 model, combines Optical Character Recognition (OCR) with
 
 ## Automated W-2 form processing
 
-Form W-2, also known as the Wage and Tax Statement, is sent by an employer to each employee and the Internal Revenue Service (IRS) at the end of the year. A W-2 form reports employees' annual wages and the amount of taxes withheld from their paychecks. The IRS also uses W-2 forms to track individuals' tax obligations. The Social Security Administration (SSA) uses the information on this and other forms to compute the Social Security benefits for all workers.
+An employer sends form W-2, also known as the Wage and Tax Statement, to each employee and the Internal Revenue Service (IRS) at the end of the year. A W-2 form reports employees' annual wages and the amount of taxes withheld from their paychecks. The IRS also uses W-2 forms to track individuals' tax obligations. The Social Security Administration (SSA) uses the information on this and other forms to compute the Social Security benefits for all workers.
 
 ***Sample W-2 tax form processed using Form Recognizer Studio***
 
 :::image type="content" source="media/studio/w-2.png" alt-text="Screenshot of sample W-2 processed in the Form Recognizer Studio.":::
 
 ## Development options
 
-The prebuilt W-2 model is supported by Form Recognizer v3.0 with the following tools:
+Form Recognizer v3.0 supports the following tools:
 
 | Feature | Resources | Model ID |
 |----------|-------------|-----------|
 |**W-2 model**|<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|**prebuilt-tax.us.w2**|
 
 ### Try W-2 data extraction
 
-Try extracting data from W-2 forms using the Form Recognizer Studio. You'll need the following resources:
+Try extracting data from W-2 forms using the Form Recognizer Studio. You need the following resources:
 
 * An Azure subscription—you can [create one for free](https://azure.microsoft.com/free/cognitive-services/)
 
@@ -92,7 +92,7 @@ Try extracting data from W-2 forms using the Form Recognizer Studio. You'll need
 | MedicareTaxWithheld | 6 | Number | Medicare tax with held | 1111 |
 | SocialSecurityTips | 7 | Number | Social security tips | 1111 |
 | AllocatedTips | 8 | Number | Allocated tips | 1111 |
-| VerificationCode | 9 | String | Verification Code on Form W-2 | A123-B456-C789-DXYZ |
+| Verification&#8203;Code | 9 | String | Verification Code on Form W-2 | A123-B456-C789-DXYZ |
 | DependentCareBenefits | 10 | Number | Dependent care benefits | 1111 |
 | NonqualifiedPlans | 11 | Number | The non-qualified plan, a type of retirement savings plan that is employer-sponsored and tax-deferred | 1111 |
 | AdditionalInfo |  | Array of objects | An array of LetterCode and Amount |  |
@@ -123,11 +123,6 @@ Try extracting data from W-2 forms using the Form Recognizer Studio. You'll need
 
 ## Next steps
 
-* Complete a Form Recognizer quickstart:
-> [!div class="checklist"]
->
-> * [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)
-> * [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)
-> * [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)
-> * [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)
-> * [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>
+* Try processing your own forms and documents with the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)
+
+* Complete a [Form Recognizer quickstart](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true) and get started creating a document processing app in the development language of your choice.

articles/applied-ai-services/form-recognizer/faq.yml

@@ -7,7 +7,7 @@ metadata:
   ms.service: applied-ai-services
   ms.subservice: forms-recognizer
   ms.topic: faq
-  ms.date: 10/20/2022
+  ms.date: 03/09/2023
   ms.author: lajanuar
   monikerRange: '>=form-recog-2.1.0'
   recommendations: false
@@ -39,7 +39,7 @@ sections:
           Learn more about [use case considerations](/legal/cognitive-services/form-recognizer/fr-transparency-note?context=/azure/applied-ai-services/form-recognizer/context/context#considerations-when-choosing-other-use-cases).
 
       - question: |
-          What languages are supported by Form Recognizer?
+          What languages does Form Recognizer support?
         answer: |
 
            Form Recognizer's deep-learning-based universal models support many languages that can extract multi-lingual text from your images and documents, including text lines with mixed languages.
@@ -100,7 +100,7 @@ sections:
       - question: |
           How can I improve accuracy scores?
         answer: |
-          The accuracy of a model is influenced by variances in the visual structure of your documents.
+          Variances in the visual structure of your documents can influence the accuracy of a model.
 
           - Ensure that all variations of a document are included in the training dataset. Variations include different formats, for example, digital versus scanned PDFs.
 
@@ -220,12 +220,12 @@ sections:
 
            - The parameter `pages`(supported in both v2.1 and v3.0 REST API) enables you to specify pages for multi-page PDF and TIFF documents. Accepted input includes the following ranges:
 
-              - Single pages (for example,'1, 2' -> pages 1 and 2 will be processed).- Finite (for example '2-5' -> pages 2 to 5 will be processed)
-              - Open-ended ranges (for example '5-' -> all the pages from page 5 will be processed & for example, '-10' -> pages 1 to 10 will be processed).
+              - Single pages (for example,'1, 2' -> pages 1 and 2 are processed).- Finite (for example '2-5' -> pages 2 to 5 are processed)
+              - Open-ended ranges (for example '5-' -> all the pages from page 5 are processed & for example, '-10' -> pages 1 to 10 are processed).
 
-            - These parameters can be mixed together and ranges are allowed to overlap (for example, '-5, 1, 3, 5-10' - pages 1 to 10 will be processed).
+            - These parameters can be mixed together and ranges are allowed to overlap (for example, '-5, 1, 3, 5-10' - pages 1 to 10 are processed).
 
-            - The service accepts the request if it can process at least one page of the document. For example, using '5-100' on a five page document is a valid input where page 5 will be processed.
+            - The service accepts the request if it can process at least one page of the document. For example, using '5-100' on a five page document is a valid input where page 5 is processed.
 
             - If no page range is provided, the entire document is processed.
 
@@ -286,7 +286,7 @@ sections:
           Learn more about Form Recognizer [service quotas and limits](service-limits.md)
 
       - question: |
-         How long will it take to analyze a document?
+         How long does it take to analyze a document?
         answer: |
           Form Recognizer is a multi-tenanted service where latency for similar documents is comparable but not always identical. The time to analyze a document depends on the size (for example, number of pages) and associated content on each page.
 
@@ -409,7 +409,7 @@ sections:
       - question: |
            If my storage account is behind a VNet or firewall, how do I give Form Recognizer access to my storage account data?
         answer: |
-            If you have an Azure storage account protected by a Virtual Network (VNet) or firewall, Form Recognizer can’t directly access your storage account. However, Private Azure storage account access and authentication are supported by [managed identities for Azure resources](../../active-directory/managed-identities-azure-resources/overview.md). Once a managed identity is enabled, the Form Recognizer service can access your storage account using an assigned managed identity credential.
+            If you have an Azure storage account protected by a Virtual Network (VNet) or firewall, Form Recognizer can’t directly access your storage account. However, Private Azure storage account access and authentication support [managed identities for Azure resources](../../active-directory/managed-identities-azure-resources/overview.md). Once a managed identity is enabled, the Form Recognizer service can access your storage account using an assigned managed identity credential.
 
             If you intend to analyze your private storage account data with FOTT, the tool must be deployed behind the VNet or firewall.
 

articles/applied-ai-services/form-recognizer/language-support.md

@@ -7,8 +7,7 @@ manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: forms-recognizer
 ms.topic: reference
-ms.date: 01/06/2023
-ms.author: lajanuar
+ms.date: 03/09/2023
 ---
 
 # Language support for Form Recognizer
@@ -26,7 +25,7 @@ This article covers the supported languages for text and field **extraction (by
 
 ## Read, layout, and custom form (template) model
 
-The following lists include the currently GA languages in the most recent v3.0 version. These languages are supported by Read, Layout, and Custom form (template) model features.
+The following lists include the currently GA languages in the most recent v3.0 version for Read, Layout, and Custom template (form) models.
 
 > [!NOTE]
 > **Language code optional**

articles/applied-ai-services/form-recognizer/media/studio/query-field-analyze.png

@@ -154,6 +154,9 @@ items:
   - name: Layout model
     displayName: tables, selection marks, structure, paragraph roles, text, headers, page numbers
     href: concept-layout.md
+  - name: 🆕 Query field extraction (preview)
+    displayName: queries, fields, OpenAI, chat
+    href: concept-query-fields.md
   - name: 🆕 Health insurance card model (preview)
     displayName: health, proof, hospital
     href: concept-insurance-card.md