Users/echong/readme (#125)

* Updated readme file to explain how to add virutal category * Added categoryResources.json file under Workbooks folder * Modified test code to support a virtual category * Modified test code to support a virtual category * Updated readme based on PR comments * Updated a sample categoryKey name in readme.
microsoft · Feb 25, 2019 · ca46d43 · ca46d43
1 parent 90d48e5
commit ca46d43
Show file tree

Hide file tree

Showing 3 changed files with 75 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -161,3 +161,53 @@ There are three ways of creating a template.
     ![Image of default template](https://github.com/Microsoft/Application-Insights-Workbooks/blob/master/_assets/SavedList.png)
 
 6. Modify report as you wish and click "Advanced Editor" button from the menu. Copy all contents and create a file like "your custom template name.template". Please make sure file name ends with '.workbook'.
+
+## How to associate any existing template to an additional category in Workbooks
+We are now supporting associating any exiting templates to an additional category (virtual category). Previously, a category was always associated with templates by a folder structure but this requires to create physical folder structure which requires copying existing templates. This would introduce a lot of maintenance overhead of updating duplicated templates.
+
+First, to associate the existing template, we need to create a virtual category first.
+1. Go to Workbooks folder and locate "resourceCategory.json" file.
+2. Add new category entry under categories array as below:
+    ```
+    {
+    "categories": [{
+            "key": "YourSampleUniqueCategoryKey",
+            "settings": {
+            "en-us": {
+                "name": "Sample Category",
+                "description": "Category description",
+                "order": 100
+                }
+            }      
+        }]
+    }
+    ```
+    * key: This should be unique key value. This will be used in a template to link together.
+    * settings:
+        * name: This is a name of category. This will be localized.
+        * description: A description of this category.
+        * order: The sort order of category.
+3. Now we need to modify template settings to associate it together.
+4. Go to your template and open settings.json file
+    ```
+    {
+        "$schema": "https://github.com/Microsoft/Application-Insights-Workbooks/blob/master/schema/settings.json",
+        "name": "Bracket Retention",
+        "author": "Microsoft",
+        "galleries": [
+            {
+                "type": "workbook",
+                "resourceType": "microsoft.insights/components",
+                "order": 400
+            },
+            // This is the new section to add:
+            {
+                "type": "workbook",
+                "resourceType": "Azure Monitor",
+                "categoryKey": "YourSampleUniqueCategoryKey"
+                "order": 400
+            }
+        ]
+    }
+    ```
+    **Note that the second item in the galleries array, it has a "categoryKey". It should be match with a "key" in a virtual category.**
diff --git a/Workbooks/categoryResources.json b/Workbooks/categoryResources.json
@@ -0,0 +1,13 @@
+{
+    "categories": [{
+        "key": "YourUniqueCategoryKey",
+        "settings": {
+          "en-us": {
+            "name": "Your category name",
+            "description": "Category description",
+            "order": 100
+          }
+        }      
+      }
+    ]
+  }
diff --git a/test/jsonValidationTest.js b/test/jsonValidationTest.js
@@ -45,11 +45,11 @@ describe('Validating Cohorts...', () => {
 });
 
 describe('Validating Workbooks...', () => {
-    const cohortPath = './Workbooks';
+    const workbookPath = './Workbooks';
 
     it('Verifying .workbook files', function (done) {
         let failedList = [];
-        browseDirectory(cohortPath, (error, results) => {
+        browseDirectory(workbookPath, (error, results) => {
             results.filter(file => file.substr(-9) === '.workbook')
                 .forEach(file => {
                     validateJsonStringAndGetObject(file)
@@ -60,7 +60,7 @@ describe('Validating Workbooks...', () => {
     });
 
     it('Verifying workbook settings.json files', function (done) {
-        browseDirectory(cohortPath, (error, results) => {
+        browseDirectory(workbookPath, (error, results) => {
             if (error) throw error;
             results.filter(file => file.substr(-13) === 'settings.json')
                 .forEach(file => {
@@ -73,7 +73,7 @@ describe('Validating Workbooks...', () => {
     });
 
     it('Verifying workbook category json files', function (done) {
-        browseDirectory(cohortPath, (error, results) => {
+        browseDirectory(workbookPath, (error, results) => {
             if (error) throw error;
             results.filter(file => file.substr(-22) === 'categoryResources.json')
                 .forEach(file => {
@@ -82,11 +82,11 @@ describe('Validating Workbooks...', () => {
                 });
 
             done();
-        });
+        }, true, workbookPath);
     });
 });
 
-var browseDirectory = function (dir, done) {
+var browseDirectory = function (dir, done, hasRoot=false, rootDir="") {
     var results = [];
     fs.readdir(dir, function (err, list) {
         if (err) return done(err);
@@ -102,8 +102,12 @@ var browseDirectory = function (dir, done) {
                         next();
                     });
                 } else {
-                    results.push(file);
-                    next();
+                    if (hasRoot && dir === rootDir) {                        
+                        next();
+                    } else {
+                        results.push(file);
+                        next();
+                    }
                 }
             });
         })();