fix(content-health-monitor): setup instructions (#271)

cgraham-rs · web-flow · commit 00c7c92c88b8 · 2025-08-19T14:16:25.000-04:00
* Update instructions to clarify it is intended for content owners

* Update setup instructions, GUID error instructions

* Extend update-manifest command to auto-include all images, then update the manifest file

* Add browser address bar image to instructions

* Update manifest

* Update image and manifest
diff --git a/extensions/content-health-monitor/Makefile b/extensions/content-health-monitor/Makefile
@@ -49,7 +49,9 @@ clean:
 .PHONY: update-manifest
 update-manifest:
 	cp manifest.json manifest.old.json
-	uv run rsconnect write-manifest quarto content-health-monitor.qmd content_health_utils.py images/refresh-report.png images/settings-gear-icon.png --overwrite
+	$(eval IMAGE_FILES := $(shell find images -type f | tr '\n' ' '))
+	@echo "Including image files: $(IMAGE_FILES)"
+	uv run rsconnect write-manifest quarto content-health-monitor.qmd content_health_utils.py $(IMAGE_FILES) --overwrite
 	jq -n --slurpfile old manifest.old.json --slurpfile new manifest.json \
 		'{"version": $$new[0].version, "locale": $$new[0].locale, "metadata": $$new[0].metadata, "extension": $$old[0].extension, "environment": $$old[0].environment} * ($$new[0] | del(.version, .locale, .metadata))' \
 		> manifest.merged.json
diff --git a/extensions/content-health-monitor/content-health-monitor.qmd b/extensions/content-health-monitor/content-health-monitor.qmd
@@ -93,10 +93,12 @@ if not state.show_instructions:
 # ------ DISPLAY SECTION ------ #
 # Create the about content text
 about_content = f"""<div>
+This report is intended to monitor content that you own. If you share this report with someone else it may not function properly.<br><br>
+
 This report uses <b>{current_user_name}</b>'s API key to monitor a single piece of content. It checks whether the content is 
 reachable, but does not verify that it runs without errors.<br><br>
-When scheduled to run regularly, the report will send an email alert 
-if the content becomes unreachable.
+
+When scheduled to run regularly, the report will send an email alert if the content becomes unreachable.
 To learn more about scheduling reports in Connect, see the 
 <a href="https://docs.posit.co/connect/user/scheduling/index.html" target="_blank">Scheduling documentation</a>.
 </div>"""
diff --git a/extensions/content-health-monitor/content_health_utils.py b/extensions/content-health-monitor/content_health_utils.py
@@ -68,30 +68,32 @@ def get_env_var(var_name, state, description=""):
         # Detailed instructions for MONITORED_CONTENT
         else:
             one_tab = "&nbsp;&nbsp;&nbsp;&nbsp;"  # For indentation in HTML
-            two_tabs = f"{one_tab}{one_tab}"  # For deeper indentation
             instruction = (
                 f"To monitor a piece of content you must configure the <code>{var_name}</code> environment variable.<br><br>"
                 
-                f"<b>Step 1:</b> Locate the content you want to monitor in a new browser tab or window<br>"
-                f"{one_tab}<b>Option A:</b> Copy the GUID from the Content Settings panel<br>"
-                f"{two_tabs}• Click the <b>gear icon</b> in the top right toolbar to open <b>Content Settings</b><br>"
-                f'{two_tabs}<img src="images/settings-gear-icon.png" alt="Settings gear icon location" '
-                f'style="max-width: 80%; margin: 10px 0; border: 1px solid #ddd;"><br>'
-                f"{two_tabs}• Select the <b>Info</b> tab<br>"
-                f"{two_tabs}• Scroll to the bottom and click the <b>copy</b> button next to the GUID<br>"
-                f"{one_tab}<b>Option B:</b> Copy the full URL from your browser<br>"
-                f"{two_tabs}• If the address bar contains a GUID (ex: 1d97c1ff-e56c-4074-906f-cb3557685b75), "
-                f"you can simply copy the entire URL<br><br>"
+                f"<h2>Step 1: Find the content to be monitored</h2>"
+                f"{one_tab}• In a separate tab, open the content you wish to monitor<br>"
+                f"{one_tab}• In the browser address bar, copy the entire address (URL)<br><br>"
+                f"{one_tab}<img src=\"images/address-bar.png\" alt=\"Browser address bar\" style=\"max-width: 50%; margin: 10px 0 10px 0; border: 1px solid #ddd;\"><br>"                
 
-                f"<b>Step 2:</b> Return to this report to set the environment variable<br>"
-                f"{one_tab}• Click the <b>gear icon</b> to open <b>Content Settings</b><br>"
-                f"{one_tab}• Select the <b>Vars</b> tab<br>"
-                f"{one_tab}• Add a new variable named <code>{var_name}</code><br>"
-                f"{one_tab}• Paste the GUID you copied into the value field<br>"
-                f"{one_tab}• Click <b>Add Variable</b> and then <b>Save</b> to save it<br><br>"
+                f"<h2>Step 2: Configure this report</h2>"
+                f"{one_tab}• Return to this report<br>"
+                f"{one_tab}• Click the <b>gear icon</b> at the top right of the screen to open <b>Content Settings</b><br>"
+                f"{one_tab}<img src=\"images/settings-gear-icon.png\" alt=\"Content Settings button\" style=\"max-width: 30%; margin: 10px 0 10px 0; border: 1px solid #ddd;\"><br>"
+                f"{one_tab}• Click the <b>Vars</b> tab<br>"
+                f"{one_tab}• In the <b>Name</b> field enter <code>{var_name}</code><br>"
+                f"{one_tab}• In the <b>Value</b> field paste the full address you copied in the previous step<br>"
+                f"{one_tab}• It should look like the example below<br>"
+                f"{one_tab}<img src=\"images/vars.png\" alt=\"Environment Variables tab\" style=\"max-width: 30%; margin: 10px 0 10px 0; border: 1px solid #ddd;\"><br>"                
+                f"{one_tab}• Click <b>Add Variable</b><br>"
+                f"{one_tab}• Click <b>Save</b> at the top of the screen to save your changes<br><br>"
 
-                f"<b>Step 3:</b> Click <b>Refresh Report</b> in the top right to to run a health check against the content specified in the new variable<br>"
-                f'<img src="images/refresh-report.png" alt="Refresh report button" style="max-width: 80%; margin: 10px 0; border: 1px solid #ddd;"><br><br>'
+                f"<h2>Step 3: Run the report to execute the health check</h2>"
+                f"{one_tab}• Click the <b>Refresh Report</b> button at the top right to run a health check against the monitored content<br>"
+                f"{one_tab}• The health check will run and report the status<br>"
+                f"{one_tab}• If the content is healthy, you will see a <b>PASS</b> status, otherwise you will see a <b>FAIL</b> status<br>"
+                f"{one_tab}• If you see a <b>FAIL</b> status, click the <b>View Logs</b> link to see more details about the failure<br>"
+                f"{one_tab}<img src=\"images/refresh-report.png\" alt=\"Refresh report button\" style=\"max-width: 30%; margin: 10px 0 10px 0; border: 1px solid #ddd;\"><br><br>"
 
             )
         
@@ -150,7 +152,8 @@ def extract_guid(input_string):
             f"The URL provided in <code>MONITORED_CONTENT</code> does not contain a valid GUID. "
             f"The URL should contain a GUID like: <code>1d97c1ff-e56c-4074-906f-cb3557685b75</code><br><br>"
             f"The URL provided is: <a href=\"{input_string}\" target=\"_blank\" rel=\"noopener noreferrer\">{input_string}</a><br><br>"
-            f"Please update your environment variable with a valid GUID or a URL containing a GUID."
+            f"Please update your environment variable with a valid a URL containing a GUID.<br><br>"
+            f"Or copy the GUID from the bottom of the Info tab. See the <a href=\"https://docs.posit.co/connect/user/content-settings/\" target=\"_blank\" rel=\"noopener noreferrer\">Connect Content Settings User Guide</a> instructions for more information.<br><br>"
         )
         return input_string, error_message
     
@@ -159,7 +162,8 @@ def extract_guid(input_string):
         f"The value provided in <code>MONITORED_CONTENT</code> is not a valid GUID. "
         f"A valid GUID looks like: <code>1d97c1ff-e56c-4074-906f-cb3557685b75</code><br><br>"
         f"The provided value was: <code>{input_string}</code><br><br>"
-        f"Please update your environment variable with a valid GUID or a URL containing a GUID."
+        f"Please update your environment variable with a valid GUID or a URL containing a GUID.<br><br>"
+        f"The GUID can be found at the bottom of the Info tab. See the <a href=\"https://docs.posit.co/connect/user/content-settings/\" target=\"_blank\" rel=\"noopener noreferrer\">Connect Content Settings User Guide</a> instructions for more information.<br><br>"
     )
     return input_string, error_message
 
@@ -408,9 +412,6 @@ def create_instructions_box(instructions_html_content):
     <div style="{CSS_BOX_STYLE.format(border=warning['border'], background=neutral['background'])}"> 
         <div style="{CSS_HEADER_STYLE}; color: #f0ad4e;">⚙️ Setup Required</div>
         {instructions_html_content}
-        <div style="{CSS_FOOTER_STYLE}">
-            See Posit Connect documentation for <a href='https://docs.posit.co/connect/user/content-settings/#content-vars' target='_blank'>Vars (environment variables)</a>
-        </div>
     </div>
     """
 
diff --git a/extensions/content-health-monitor/images/address-bar.png b/extensions/content-health-monitor/images/address-bar.png
diff --git a/extensions/content-health-monitor/images/vars.png b/extensions/content-health-monitor/images/vars.png
diff --git a/extensions/content-health-monitor/manifest.json b/extensions/content-health-monitor/manifest.json
@@ -32,7 +32,7 @@
     "version": "3.11.7",
     "package_manager": {
       "name": "pip",
-      "version": "24.2",
+      "version": "25.1.1",
       "package_file": "requirements.txt"
     }
   },
@@ -41,16 +41,22 @@
       "checksum": "5f89d52674b219c0b0ed85f1a5785641"
     },
     "content-health-monitor.qmd": {
-      "checksum": "f3cb8562a07f411da78748d107ffeb3e"
+      "checksum": "d108f54df865a66e2ac54a7fb3ac9772"
     },
     "content_health_utils.py": {
-      "checksum": "0ce8c4e2191fc4763492c5498626912f"
+      "checksum": "5b7c8db239c4b9e0782060b1172b2456"
     },
-    "images/refresh-report.png": {
-      "checksum": "e5680e6188eb8d659e4313cb89d0be3b"
+    "images/vars.png": {
+      "checksum": "9840b32e4adec7d5a3c70bb3373a63bb"
     },
     "images/settings-gear-icon.png": {
       "checksum": "e2bc43263eb8a9179b6e0e5ab3e22450"
+    },
+    "images/address-bar.png": {
+      "checksum": "993cc8f97996c68f30527abbcc63cf3c"
+    },
+    "images/refresh-report.png": {
+      "checksum": "e5680e6188eb8d659e4313cb89d0be3b"
     }
   }
 }
diff --git a/extensions/content-health-monitor/test_content_health_utils.py b/extensions/content-health-monitor/test_content_health_utils.py
@@ -293,7 +293,7 @@ def test_extract_guid_with_url_no_guid(self):
         assert "The URL provided in <code>MONITORED_CONTENT</code> does not contain a valid GUID" in error_message
         assert "The URL should contain a GUID like: <code>1d97c1ff-e56c-4074-906f-cb3557685b75</code>" in error_message
         assert f"<a href=\"{input_string}\" target=\"_blank\" rel=\"noopener noreferrer\">" in error_message
-        assert "Please update your environment variable with a valid GUID or a URL containing a GUID" in error_message
+        assert "Please update your environment variable with a valid a URL containing a GUID" in error_message
     
     def test_extract_guid_with_plain_text(self):
         """Test extract_guid with plain text that is not a URL and does not contain a GUID"""
