ARM endpoint and JSON Transformer Documentation (#548)

* ARM endpoint and JSON transformation

Documentation/DataSources/DataSources.md

@@ -12,6 +12,10 @@ Workbooks support these data sources:
 * [Workload Health](#workload-health)
 * [Azure Resource Health](#azure-resource-health)
 * [Custom Endpoint](#custom-endpoint)
+* [Azure Data Explorer](#azure-data-explorer)
+* [Azure Resource Manager](#azure-resource-manager)
+* JSON
+* Custom Provider
 
 You can also use the [Merge](#merge-data-from-different-sources) option in the query control to combine data from different data sources. 
 
@@ -41,7 +45,7 @@ Azure resources emit metrics that can be accessed via workbooks. Examples of met
 ![A image of a workbook with metric data for many resources](../Images/MetricDataSource2.png)
 
 ## Azure Resource Graph (ARG)
-Workbooks  support querying for resources and their metadata using Azure Resource Graph (ARG). This is primarily used to build custom query scopes for reports. The resource scope is expressed via a KQL-subset that ARG supports – which is usually enough the common use cases.
+Workbooks supports querying for resources and their metadata using Azure Resource Graph (ARG). This is primarily used to build custom query scopes for reports. The resource scope is expressed via a KQL-subset that ARG supports – which is usually enough the common use cases.
 
 To make a query control use this data source, use the _Data source_ drop down to choose _Azure Resource Graph_ and select the subscriptions to target. Use the _Query_ control to add the ARG KQL-subset that selects an interesting resource subset.
 
@@ -79,14 +83,29 @@ To avoid automatically making calls to un-trusted hosts when using templates, th
 
 `Note:  Do not write any secrets in any of the fields (headers, parameters, body, url), since they will be visible to all of the Workbook users.`
 
+This provider supports [JSON Path](../Transformations/JSONPath).
+
 ## Azure Data Explorer (preview)
-Workbooks supports quering Azure Data Explorer (ADX).
+Workbooks supports querying Azure Data Explorer (ADX).
 
 To make a query control use this data source, use the _Data source_ drop down to choose _Azure Data Explorer_ and enter the ADX cluster and database name.  The database name should be the full https url to the cluster. If not, the cluster is presumed to have a standard name based on the Azure cloud instance. Cluster name and database name support workbook parameters. At the current time, there is no intellisense/completion of table names or column names in the ADX cluster. In order to query the cluster, the current portal user will need read access to that ADX cluster.
 
 ![A image of a workbook with an Azure Data Explorer query](../Images/AzureDataExplorerDataSource.png)
 
 
+## Azure Resource Manager (preview)
+Workbook supports Azure Resource Manager (ARM) REST operations. This allows the ability to query management.azure.com endpoint without the need to provide your own authorization header token.
+
+To make a query control use this data source, use the _Data source_ drop down to choose _Azure Resource Manager_. Provide the appropriate parameters such as Http method, url path, headers, url parameters and/or body.
+
+`Note: Only GET, POST, and HEAD operations are currently supported.`
+
+![A image of a workbook with an Azure Resource Manager query](../Images/AzureResourceManagerDataSource.PNG)
+
+[Click here to view a walk-through example of this provider](../Samples/AlertDataARM.md)
+
+This provider supports [JSON Path](../Transformations/JSONPath).
+
 ## Merge data from different sources
 It is often necessary to bring together data from different sources that enhance the insights experience. An example is augmenting active alert information with related metric data. This allows users to see not just the effect (an active alert), but also potential causes (e.g. high CPU usage). The monitoring domain has numerous such correlatable data sources that are often critical to the triage and diagnostic workflow. 
 

Documentation/Parameters/Resources.md

@@ -90,5 +90,7 @@ Values from resource pickers can come from the workbook context, static list or
 | `{Applications:resourceGroup}` | The resource group of the selected resource | _acmegroup_ |
 | `{Applications:resourceType}` | The type of the selected resource | _microsoft.insights/components_ |
 | `{Applications:subscription}` | The subscription of the selected resource |  |
+| `{Applications:subscriptionid}` | The subscription guid id of a subscription or resource |  |
+| `{Applications:id}` | The guid id of a subscription |  |
 | `{Applications:grid}` | A grid showing the resource properties. Useful to render in a text block while debugging  |  |
 

Documentation/Parameters/Time.md

@@ -52,6 +52,11 @@ This is how the workbook will look like in read-mode.
 | `{TimeRange:start}` | Time range start time | 3/20/2019 4:18 PM |
 | `{TimeRange:end}` | Time range end time | 3/21/2019 4:18 PM |
 | `{TimeRange:grain}` | Time range grain | 30m |
+| `{TimeRange:startISO}` | Time range start time ISO format | 2019-11-02T01:04:00.000Z |
+| `{TimeRange:endISO}` | Time range end time ISO format | 2019-12-02T01:04:00.000Z |
+| `{TimeRange:startDateISO}` | Start date ISO format | 2019-11-02T00:00:00.000Z |
+| `{TimeRange:endDateISO}` | End date ISO format | 2019-12-02T00:00:00.000Z |
+| `{TimeRange:durationISO}` | Time range duration ISO format | PT24H |
 
 
 ### Using parameter options in a query

Documentation/Samples/AlertDataARM.md

@@ -0,0 +1,58 @@
+# Using Azure Resource Manager provider to retrieve alerts in a subscription
+
+This sample shows you how to use the Azure Resource Manager (preview) query control to list all existing alerts in a subscription. This guide will also use JSON Path transformations to format the results.
+
+## Setup parameters
+
+1. Create an empty workbook.
+2. Click `Add parameter` to create a new one. Use the following settings:
+    1. Parameter name: `Subscription`
+    2. Parameter type: `Subscription picker`
+    3. Required: `Checked`
+    4. Get data from: `Default Subscriptions`
+    5. Use the `Save` button in the toolbar to save this parameter. 
+
+To get a list of existing alerts for a subscription, we will utilize the [Alerts - Get All REST call](https://docs.microsoft.com/en-us/rest/api/monitor/alertsmanagement/alerts/getall)
+
+3. Click `Add query` to create a query control.
+    1. Data source: `Azure Resource Manager (Preview)`
+    2. Http Method: `GET`
+    3. Path: `/subscriptions/{Subscription:id}/providers/Microsoft.AlertsManagement/alerts`
+    4. Add the api-version parameter in the `Parameters` tab
+        1. Parameter: `api-version`
+        2. Value: `2018-05-05`
+
+        *Note: Supported api-versions are listed in the [Azure REST API Reference](https://docs.microsoft.com/en-us/rest/api/azure/) documentation*
+    5. Select a subscription from the created subscription parameter and click the `Run Query` button to see the results.
+
+     This is the raw JSON results returned from Azure Resource Manager (ARM).
+
+    ![Image showing an alert data JSON response using ARM Provider](../Images/ARMAlertsQueryNoFormatting.png)
+
+You may be satisfied with the information here. However, let us extract some interesting properties and format the response in an easy to read way.
+
+4. Navigate to the tab `Result Settings`
+5. Switch the Result Format from `Content` to `JSON Path`. JSON Path is a Workbook transformer. Click [here](../Transformations/JSONPath.md) to learn more about JSON Path in Workbooks.
+6. In the JSON Path Settings - JSON Path Table: `$.value.[*].properties.essentials`. This extracts all "value.*.properties.essentials" fields from the returned JSON.
+7. Click `Run Query` to see the grid.
+
+![Image showing an alert data in a grid format using ARM Provider](../Images/ARMAlertsQueryGridFormat.png)
+
+JSON Path also allows you to pick and choose information from the generated table to show as columns. For example, if you would like to filter the results to the following columns: `TargetResource`, `Severity`, `AlertState`, `Description`, `AlertRule`, `StartTime`, `ResolvedTime`
+
+8. Add the following rows in the columns table in JSON Path:
+
+| Column ID | Column JSON Path |
+| :------------- | :----------: |
+| TargetResource | $.targetResource |
+| Severity | $.severity |
+| AlertState | $.alertState |
+| AlertRule | $.alertRule |
+| Description | $.description |
+| StartTime  | $.startDateTime |
+| ResolvedTime  | $.monitorConditionResolvedDateTime |
+
+![Image showing an alert data in a grid format using ARM Provider](../Images/ARMAlertsQueryFinal.png)
+
+
+Click [here](https://docs.microsoft.com/en-us/rest/api/azure/) to see a list of other supported ARM calls.

Documentation/Samples/Samples.md

@@ -21,3 +21,9 @@
 ### Combining data from different sources using the merge control
 
 [![Combining data from different sources in workbooks](http://img.youtube.com/vi/7nWP_YRzxHg/0.jpg)](https://www.youtube.com/watch?v=7nWP_YRzxHg "Video showing how to combine data from different sources in workbooks")
+
+### Retrieving Alert data from Azure Resource Manager
+
+[![Image showing a grid with alerts data](../Images/ARMAlertsQueryGridFormat.png)](AlertDataARM.md)
+
+[See instructions](AlertDataARM.md)

Documentation/Transformations/JSONPath.md

@@ -0,0 +1,62 @@
+# JSON Path
+
+Workbooks is able to query data from many sources. Some endpoints, such as Azure Resource Manager or custom endpoint, can return results in JSON. If the JSON data returned by the queried endpoint is not configured in a format that you desire, JSONPath can be used to transform the results.
+
+JSONPath is a query language for JSON that is similar to XPath for XML. Like XPath, JSONPath allows for the extraction and filtration of data out of a JSON structure.
+
+Click [here](https://aka.ms/jsonpath) to learn more about JSON Path.
+
+By using JSONPath transformation, Workbook authors are able to convert JSON into a table structure. The table can then be used to plot Workbook [visualizations](../Visualizations/Visualizations.md).
+
+## Using JSONPath
+
+1. Switch the workbook to edit mode by clicking on the _Edit_ toolbar item.
+2. Use the _Add query_ link to add a query control to the workbook. 
+3. Select the query type as _JSON_
+4. Use the JSON editor to enter the following JSON snippet
+
+```json
+{ "store": {
+    "books": [ 
+      { "category": "reference",
+        "author": "Nigel Rees",
+        "title": "Sayings of the Century",
+        "price": 8.95
+      },
+      { "category": "fiction",
+        "author": "Evelyn Waugh",
+        "title": "Sword of Honour",
+        "price": 12.99
+      },
+      { "category": "fiction",
+        "author": "Herman Melville",
+        "title": "Moby Dick",
+        "isbn": "0-553-21311-3",
+        "price": 8.99
+      },
+      { "category": "fiction",
+        "author": "J. R. R. Tolkien",
+        "title": "The Lord of the Rings",
+        "isbn": "0-395-19395-8",
+        "price": 22.99
+      }
+    ],
+    "bicycle": {
+      "color": "red",
+      "price": 19.95
+    }
+  }
+}
+```
+
+Let’s assume we are given the above JSON object as a representation of a store's inventory. Our task is to create a table of the store's available books by listing their titles, authors, and prices.
+
+5. Select the _Result settings_ tab, and switch the result format from `Content` to `JSON Path`
+6. Apply the following JSON Path Settings:
+    1. JSON Path Table: `$.store.books`. This field represents the path to the root of the table. In this case, we care about the store's book inventory. The table path filters the JSON to the book information.
+    2. Column IDs: `Title`, `Author`, `Price`. These will be the column headers.
+    3. Column JSON Paths: `$.title`, `$.author`, `$.price`. These fields represent the path from the root of the table to the column value. For each row in the table, the path will be applied.
+
+7. Apply the above settings by clicking _Run Query_.
+
+![Image showing the creation of a grid visualization using JSON Path](../Images/JSONPath-Example-Result.PNG)

schema/workbook.json

@@ -353,6 +353,28 @@
                                 }
                             ],
                             "description": "Custom labels for charts"
+                        },
+                        "version": {
+                            "type": "string",
+                            "description": "Version of query step",
+                            "default": "KqlItem/1.0"
+                        },
+                        "size": {
+                            "type": "integer",
+                            "description": "Size enum of the step"
+                        },
+                        "queryType": {
+                            "type": "integer",
+                            "description": "The query type enum of the step"
+                        },
+                        "query": {
+                            "type": "string",
+                            "description": "The query information of the step"
+                        },
+                        "visualization": {
+                            "type": "string",
+                            "description": "The visualization type of the step",
+                            "examples": ["table", "tiles"]
                         }
                     }
                 },