Merge pull request #202429 from AbbyMSFT/workbooks

Workbooks

Author: v-ccolin

.openpublishing.redirection.azure-monitor.json

@@ -181,6 +181,16 @@
             "redirect_url": "/azure/azure-monitor/visualize/workbooks-overview",
             "redirect_document_id": false
         },
+        {
+            "source_path_from_root": "/articles/azure-monitor/visualize/workbooks-add-text.md",
+            "redirect_url": "/azure/azure-monitor/visualize/workbooks-add-workbook-elements",
+            "redirect_document_id": false
+        },
+        {
+            "source_path_from_root": "/articles/azure-monitor/visualize/workbooks-combine-data.md",
+            "redirect_url": "/azure/azure-monitor/visualize/workbooks-data-sources",
+            "redirect_document_id": false
+        },
         {
             "source_path_from_root": "/articles/azure-monitor/alerts/itsmc-service-manager-script.md",
             "redirect_url": "/azure/azure-monitor/alerts/itsmc-connections",

articles/azure-monitor/toc.yml

@@ -56,15 +56,15 @@ items:
     - name: Azure portal
       displayName: Custom logs
       href: logs/tutorial-custom-logs.md
-    - name: Resource manager templates
+    - name: Resource Manager templates
       displayName: Custom logs
       href: logs/tutorial-custom-logs-api.md
   - name: Ingestion-time transformations
     items:
     - name: Azure portal
       displayName: Ingestion-time transformations
       href: logs/tutorial-ingestion-time-transformations.md
-    - name: Resource manager templates
+    - name: Resource Manager templates
       displayName: Ingestion-time transformations
       href: logs/tutorial-ingestion-time-transformations-api.md
 - name: Samples
@@ -1349,7 +1349,7 @@ items:
       href: visualize/workbooks-overview.md 
     - name: Working with workbooks
       items:
-        - name: Getting Started with workbooks
+        - name: Getting started with workbooks
           href: visualize/workbooks-getting-started.md
         - name: Data sources
           href: visualize/workbooks-data-sources.md         
@@ -1375,17 +1375,17 @@ items:
             href: visualize/workbooks-honey-comb.md
           - name: Composite bar
             href: visualize/workbooks-composite-bar.md
-        - name: Workbook Result Limits
+          - name: Renderers
+            href: visualize/workbooks-renderers.md
+        - name: Workbook result limits
           href: visualize/workbooks-limits.md
-    - name: Creating a new workbook
+    - name: Creating a workbook
       items:
         - name: Using workbook templates
           href: visualize/workbooks-templates.md
-        - name: Create a new workbook
+        - name: Creating a new workbook
           href: visualize/workbooks-create-workbook.md
-        - name: Add text to your workbook
-          href: visualize/workbooks-add-text.md
-        - name: Add parameters to your workbook
+        - name: Working with parameters
           items:
           - name: Workbook parameters
             href: visualize/workbooks-parameters.md
@@ -1402,9 +1402,7 @@ items:
           - name: Resource parameters
             href: visualize/workbooks-resources.md
           - name: Multi-value parameters
-            href: visualize/workbooks-multi-value.md
-        - name: Combine data from different sources
-          href: visualize/workbooks-combine-data.md       
+            href: visualize/workbooks-multi-value.md     
     - name: Configuration
       items:
       - name: Deploy with Azure Resource Manager

articles/azure-monitor/visualize/workbooks-add-text.md

@@ -1,5 +1,5 @@
 ---
-title: Create an Azure Workbook
+title: Creating an Azure Workbook
 description: Learn how to create an Azure Workbook.
 services: azure-monitor
 author: AbbyMSFT
@@ -9,24 +9,92 @@ ms.date: 05/30/2022
 ms.reviewer: gardnerjr 
 ---
 
-# Create an Azure Workbook
+# Creating an Azure Workbook
+This article describes how to create a new workbook and how to add elements to your Azure Workbook.
 
 This video provides a walkthrough of creating workbooks.
 
 > [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE4B4Ap]
 
-## To create a new Azure Workbook
+## Create an Azure Workbook
 To create a new Azure workbook:
 1. From the Azure Workbooks page, select an empty template or select **New** in the top toolbar.
-1. Combine any of these steps to include the elements you want to the workbook:
-   - [Add text to your workbook](workbooks-add-text.md)
-   - [Add parameters to your workbook](workbooks-parameters.md)
-   - Add queries to your workbook
-   - [Combine data from different sources](workbooks-combine-data.md)
-   - Add Metrics to your workbook
-   - Add Links to your workbook
-   - Add Groups to your workbook
-   - Add more configuration options to your workbook
+1. Combine any of these elements to add to your workbook:
+   - [Text](#text)
+   - Parameters
+   - [Queries](#queries)
+   - Metrics
+   - Links
+   - Groups
+   - Configuration options
+
+## Text
+
+Workbooks allow authors to include text blocks in their workbooks. The text can be human analysis of the telemetry, information to help users interpret the data, section headings, etc. 
+
+   :::image type="content" source="media/workbooks-add-text/workbooks-text-example.png" alt-text="Screenshot of adding text to a workbook.":::
+
+Text is added through a markdown control into which an author can add their content. An author can use the full formatting capabilities of markdown. These include different heading and font styles, hyperlinks, tables, etc. This allows authors to create rich Word- or Portal-like reports or analytic narratives.  Text can contain parameter values in the markdown text, and those parameter references will be updated as the parameters change.
+
+**Edit mode**:
+   :::image type="content" source="media/workbooks-add-text/workbooks-text-control-edit-mode.png" alt-text="Screenshot showing adding text to a workbook in edit mode.":::
+
+**Preview mode**:
+   :::image type="content" source="media/workbooks-add-text/workbooks-text-control-edit-mode-preview.png" alt-text="Screenshot showing adding text to a workbook in preview mode.":::
+
+### Add text to an Azure workbook
+1. Make sure you are in **Edit** mode. Add a query by doing any one of the following:
+    - Select **Add**, and **Add text** below an existing element, or at the bottom of the workbook.
+    - Select the ellipses (...) to the right of the **Edit** button next to one of the elements in the workbook, then select **Add** and then **Add text**.
+1. Enter markdown text into the editor field.
+1. Use the **Text Style** option to switch between plain markdown, and markdown wrapped with the Azure portal's standard info/warning/success/error styling.
+   
+   > [!TIP]
+   > Use this [markdown cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to see the different formatting options.
+
+1. Use the Preview tab to see how your content will look. While editing, the preview will show the content inside a scrollable area to limit its size, but when displayed at runtime, the markdown content will expand to fill whatever space it needs, with out a scrollbar.
+1. Select **Done Editing**.
+
+### Text styles
+These text styles are available:
+
+| Style     | Description                                                                             |
+| --------- | --------------------------------------------------------------------------------------- |
+| plain| No other formatting is applied                                                     |
+|info| The portal's "info" style, with a `ℹ` or similar icon and blue background     |
+|error| The portal's "error" style, with a `❌` or similar icon and red background     |
+|success| The portal's "success" style, with a `✔` or similar icon and green background |
+|upsell| The portal's "upsell" style, with a `🚀` or similar icon and purple background  |
+|warning| The portal's "warning" style, with a `⚠` or similar icon and blue background  |
+
+
+You can also choose a text parameter as the source of the style. The parameter value must be one of the above text values. The absence of a value, or any unrecognized value will be treated as `plain` style.
+
+### Text style examples
+
+**Info style example**:
+   :::image type="content" source="media/workbooks-add-text/workbooks-text-control-edit-mode-preview.png" alt-text="Screenshot of adding text to a workbook in preview mode showing info style.":::
+
+**Warning style example**:
+   :::image type="content" source="media/workbooks-add-text/workbooks-text-example-warning.png" alt-text="Screenshot of a text visualization in warning style.":::
+
+## Queries
+
+Azure Workbooks allow you to query any of the supported workbook [data sources](workbooks-data-sources.md). 
+
+For example, you can query Azure Resource Health that helps you view any service problems affecting your resources, or you can query Azure Monitor Metrics, which are numeric data that is collected at regular intervals and describe some aspect of a system at a particular time.
+
+### Add a query to an Azure Workbook
+
+1. Make sure you are in **Edit** mode. Add a query by doing any one of the following:
+    - Select **Add**, and **Add query** below an existing element, or at the bottom of the workbook.
+    - Select the ellipses (...) to the right of the **Edit** button next to one of the elements in the workbook, then select **Add** and then **Add query**.
+1. Select the [Data source](workbooks-data-sources.md) for your query. The other fields are determined based on the data source you choose.
+1. Select any other values that are required based on the data source you selected.
+1. Select the [Visualization](workbooks-visualizations.md) for your workbook.
+1. In the query section, enter your query, or select from a list of sample queries by selecting **Samples**, and then edit the query to your liking.
+1. Select **Run Query**.
+1. When you are sure you have the query you want in your workbook, select **Done editing**.
 
 
 ## Next steps