Update ARM template & documentation

private-templates-service/README.md

@@ -19,12 +19,20 @@ Prerequisites:
 - Optional: [Azure Application Insights](https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview)
 
 1. Click the blue '**Deploy to Azure**'. Select the subscription and resource group under which you wish to deploy ACMS to. 
+
 2. Enter in the URL the portal will be hosted at into the '**Sites_adaptivecms_name**' field. Make sure this URL is added under the '**Redirect URIs**' section of your AAD App Registration. Detailed instructions and screenshots are listed below. 
-3. Enter in the Azure Active Directory App Registration application (client) id into the '**App_id**' field. 
-4. Enter the id of your App Service Plan into the '**Server_farm_id**' field. 
+
+3. Enter in the Azure Active Directory App Registration application (client) id into the '**Azure_active_directory_app_registration_id**' field. 
+
+4. Enter the id of your App Service Plan into the '**App_service_plan_subscription**' field. The format should be as follows: 
+
+   `/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.Web/serverfarms/{App_service_plan_name}`
+
 5. If 'Yes' is selected for '**Telemetry_opt_in**', we will collect feedback from your instance of ACMS using App Insights. See details under 'Telemetry Privacy Statement' below. 
-6. Optional: If you possess an Azure Application Insights instance, enter the instrumentation key into the '**application_insights_instrumentation_key**' field. 
-To create an Application Insights resource or find your instrumentation key, please see [Create an Application Insights resource](https://docs.microsoft.com/en-us/azure/azure-monitor/app/create-new-resource). Also, please read the 'Telemetry Privacy Statement' below.
+
+6. Optional: If you possess an Azure Application Insights instance, enter the instrumentation key into the '**Application_insights_instrumentation_key**' field. 
+    To create an Application Insights resource or find your instrumentation key, please see [Create an Application Insights resource](https://docs.microsoft.com/en-us/azure/azure-monitor/app/create-new-resource). Also, please read the 'Telemetry Privacy Statement' below.
+
 7. Click '**Next**' and '**Deploy**'.
 
 Using the 'Deploy to Azure' button will fetch an image using the latest published version of [adaptivecards-templating-service](https://www.npmjs.com/package/adaptivecards-templating-service) and [adaptive-templating-service-typescript-node](https://www.npmjs.com/package/adaptive-templating-service-typescript-node). Once the deployment as finished, you will see the admin portal hosted at '**{Sites_adaptivecms_name}**.azurewebsites.net' and be able to hit the endpoints at the same URL. 
@@ -52,6 +60,37 @@ By accepting the **Telemetry_opt_in**, you are improving the product by sending
 
 By supplying an instrumentation key in the **application_insights_instrumentation_key** field, you acknowledge your responsibility to provide a privacy statement to your end user.
 
+### Debugging Common Issues
+
+##### Deployment Errors
+
+These errors occur on the 'Deploy to Azure' page opened after clicking the button and mean that the fields entered are invalid.  
+
+- **InvalidTemplateDeployment**: The template deployment 'AdaptiveCardsTemplates' is not valid according to the validation procedure. The tracking id is '{correlation_id}'. See inner errors for details.
+
+  If you have Azure CLI installed, try running the following command to see error details: 
+
+  ```bash
+  az monitor activity-log --correlation-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  ```
+
+  Or in PowerShell: 
+
+  ```powershell
+  Get-AzureRMLog -CorrelationId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -DetailedOutput
+  ```
+
+  The following issues may have caused the template to be invalid: 
+
+  - The value entered in the 'cosmos_database_name' field in the deployment form has already been used. This value must be unique. 
+  - The value entered in the 'Azure_active_directory_app_registration_id' field does not exist. 
+  - The value entered in the 'App_service_plan_subscription' field does not exist. Ensure that it is in the following format: `/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.Web/serverfarms/{App_service_plan_name}`
+  - The location selected is not the same as the location of the App service plan that you have selected.
+
+##### Checking on your deployment
+
+To check on the status of your deployment, you can either check on the Deploy to Azure page, which will provide updates on which resources were created, or you can check on the [Azure Portal](portal.azure.com) under the resource group where the app was deployed. On the left side navigation bar, under the 'Settings' header, click 'Deployments'. Here, you can click the deployment and check on the status of each of the resources created and operation details. 
+
 ## Running the latest changes locally with MongoDB
 
 Prerequisites:

private-templates-service/azuredeploy.json

@@ -6,14 +6,14 @@
       "defaultValue": "adaptivecmsdeploy",
       "type": "String"
     },
-    "app_id": {
+    "azure_active_directory_app_registration_id": {
       "type": "String"
     },
     "siteLocation": {
       "defaultValue": "West US",
       "type": "String"
     },
-    "server_farm_id": {
+    "app_service_plan_subscription": {
       "type": "String"
     },
     "telemetry_opt_in": {
@@ -24,13 +24,16 @@
       ]
     },
     "application_insights_instrumentation_key": {
+      "type": "String",
+      "defaultValue": ""
+    },
+    "cosmos_database_name": {
       "type": "String"
     }
   },
   "variables": {
     "linuxFxVersion": "DOCKER|gracez72/acms:1.0",
     "appInsightsInstrumentationKey": "931c613f-fdcb-40a9-bd39-314ce31bc5d6",
-    "cosmos_database_name": "acms-cosmos",
     "databaseName": "acms",
     "docker_registry_server_url": "https://index.docker.io"
   },
@@ -42,7 +45,7 @@
       "location": "[parameters('siteLocation')]",
       "kind": "app,linux,container",
       "properties": {
-        "serverFarmId": "[parameters('server_farm_id')]"
+        "serverFarmId": "[parameters('app_service_plan_subscription')]"
       },
       "resources": [
         {
@@ -53,9 +56,9 @@
             "[concat('Microsoft.Web/Sites/', parameters('sites_adaptivecms_name'))]"
           ],
           "properties": {
-            "ACMS_DB_CONNECTION": "[listConnectionStrings(resourceId('Microsoft.DocumentDB/databaseAccounts', variables('cosmos_database_name')), '2015-04-08').connectionStrings[0].connectionString]",
+            "ACMS_DB_CONNECTION": "[listConnectionStrings(resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmos_database_name')), '2015-04-08').connectionStrings[0].connectionString]",
             "ACMS_REDIRECT_URI": "[concat('https://', parameters('sites_adaptivecms_name'), '.azurewebsites.net/')]",
-            "ACMS_APP_ID": "[parameters('app_id')]",
+            "ACMS_APP_ID": "[parameters('azure_active_directory_app_registration_id')]",
             "WEBSITES_ENABLE_APP_SERVICE_STORAGE": "false",
             "DOCKER_REGISTRY_SERVER_URL": "[variables('docker_registry_server_url')]",
             "ACMS_APP_INSIGHTS_INSTRUMENTATION_KEY": "[if(equals(parameters('telemetry_opt_in'), 'Yes'), variables('appInsightsInstrumentationKey'), '')]",
@@ -135,7 +138,7 @@
     },
     {
       "type": "Microsoft.DocumentDB/databaseAccounts",
-      "name": "[variables('cosmos_database_name')]",
+      "name": "[parameters('cosmos_database_name')]",
       "apiVersion": "2019-08-01",
       "location": "[parameters('siteLocation')]",
       "kind": "MongoDB",
@@ -168,10 +171,10 @@
     },
     {
       "type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases",
-      "name": "[concat(variables('cosmos_database_name'), '/', variables('databaseName'))]",
+      "name": "[concat(parameters('cosmos_database_name'), '/', variables('databaseName'))]",
       "apiVersion": "2019-08-01",
       "dependsOn": [
-        "[resourceId('Microsoft.DocumentDB/databaseAccounts/', variables('cosmos_database_name'))]"
+        "[resourceId('Microsoft.DocumentDB/databaseAccounts/', parameters('cosmos_database_name'))]"
       ],
       "properties": {
         "resource": {