OPG-505: Update docs for OPG v12 (#1063)

synqotik · web-flow · commit b47bda47becf · 2026-03-11T18:07:11.000-04:00
* OPG-505: Update docs for OPG v12

* fixes

* Update flow histogram docs
diff --git a/docs/antora.yml b/docs/antora.yml
@@ -6,7 +6,7 @@ asciidoc:
     full-display-version: '12.0.0-SNAPSHOT'
     grafana-version-required: '12.x'
     grafana-version-tested: '12.0'
-    node-js-build-version: '20.x'
+    node-js-build-version: '22.x'
     product-name: 'OpenNMS Plugin for Grafana'
 nav:
   - modules/ROOT/nav.adoc
diff --git a/docs/modules/contributing/pages/developing.adoc b/docs/modules/contributing/pages/developing.adoc
@@ -47,6 +47,9 @@ npm ci
 [source, shell]
 npm run dev
 
+Note that `npm run dev` will generate (mostly) non-minified code which is better when debugging in a browser.
+For a release build, you can run `npm run build` to create minified and optimized code.
+
 . Symlink your `dist` directory to Grafana's plugin path:
 +
 [source, shell]
diff --git a/docs/modules/installation/assets/images/dashboard-conversion-tool.png b/docs/modules/installation/assets/images/dashboard-conversion-tool.png
diff --git a/docs/modules/installation/pages/requirements.adoc b/docs/modules/installation/pages/requirements.adoc
@@ -11,6 +11,7 @@ You also need a http://docs.grafana.org/installation[Grafana instance] (version
 
 NOTE: We have tested the plugin with Grafana version {grafana-version-tested}.
 It may work with older versions, but we have not tested them specifically.
+Most likely it will also work with Grafana 10 and 11.
 We recommend that you use matching versions of the plugin and Grafana (for example, {product-name} 9.x and Grafana 9.x).
 
 The OpenNMS Grafana Dashboard Report feature requires the https://grafana.com/grafana/plugins/grafana-image-renderer/[Grafana Image Renderer plugin] to be installed.
diff --git a/docs/modules/installation/pages/upgrading.adoc b/docs/modules/installation/pages/upgrading.adoc
@@ -56,38 +56,42 @@ perl -pi -e 's/opennms-grafana-plugin-fault-datasource/opennms-grafana-plugin-en
 wizzy export datasources
 
 [[upgrade-dashboards]]
-== Upgrade dashboards for version 9.x
+== Upgrade dashboards for version 9.x and 12.x
 
-When you upgrade your {page-component-title} installation to version 9.x, you must upgrade any previously existing dashboards.
+When you upgrade your {page-component-title} installation to version 12.x, you should upgrade any previously existing dashboards.
+Dashboards that worked with {product-name} version 9 will most likely still work, but it is recommended that you upgrade them to version 12.x.
+
+Dashboards used with {product-name} version 8 or earlier *will not* work with version 12 and must be upgraded.
 If they are not upgraded, they will not be displayed.
 
-The {product-name} version 9.x includes a dashboard conversion tool to upgrade dashboards created using previous versions.
+The {product-name} version 12.x includes a dashboard conversion tool to upgrade dashboards created using previous versions.
 
 IMPORTANT: You must export your dashboards from a previous version of the plugin.
 You can export them before you upgrade your {page-component-title} installation, or from a separate Grafana instance that is running the previous version.
 
 When you export a dashboard, a JSON file is produced containing its settings and associated data.
 
-After you export your old dashboards, upgrade your plugin to version 9.x.
+After you export your old dashboards, upgrade your plugin to version 12.x.
 Next, use the conversion tool to update your dashboards:
 
-. xref:getting_started:basic_walkthrough.adoc#bw-dashboard-create[Create a new dashboard].
-. Click the *Add Panel* symbol.
-. Click *Add New Panel*.
-. Select the *Dashboard Convert* panel.
+. Go to *Dashboards*
+. Click on *Dashboard Converter | OpenNMS Plugin for Grafana* which is already installed with {product-name} version 12.
 . On the Dashboard Convert panel, select the version of the plugin from which you exported the dashboard using the *Source Plugin Version* list.
 +
 .Dashboard Convert panel
 image::dashboard-conversion-tool.png["Dashboard Convert panel displaying blank configuration options.", 650]
 
-. Paste the contents of a dashboard JSON file in the *Enter Source Dashboard JSON* box.
+. Paste the contents of a dashboard JSON file in the *Enter Source Dashboard Json* box.
 The dashboard's name should appear in the *Dashboard Title* box.
 ** (Optional) Edit the *Dashboard Title*.
 ** (Optional) Toggle *Unhide All Queries* on or off, as desired.
 Toggling this on marks all OpenNMS datasource queries as visible, which may be useful for troubleshooting.
+** (Optional) Toggle *Convert Graph to Timeseries Panels* on or off, as desired.
+This will convert any of your Graph panels to the newer Grafana Timeseries Panels.
 . Click *Convert*.
 The converted JSON is displayed in the *Target Dashboard JSON* box.
 . Copy the converted JSON and use it to import a dashboard.
+Go to *Dashboards* > *New* > *Import* to import the converted JSON.
 
 NOTE: The conversion tool may not handle all patterns in variables and resource names.
 After you convert your dashboards, test them to ensure that all of the associated data is correct.
diff --git a/docs/modules/panel_configuration/pages/index.adoc b/docs/modules/panel_configuration/pages/index.adoc
@@ -95,7 +95,23 @@ Follow these steps to customize an alarms table panel:
 . Set other display options as desired.
 
 After the panel is configured, you can right-click on an entry to access the context menu.
-From there, you can access an alarm's *Details* and *Acknowledge*, *Escalate*, or *Clear* it:
+From there, you can access an alarm's *Details* and *Acknowledge*, *Escalate*, or *Clear* it.
+
+You can hold down the *Shift* key and click on the table to select multiple rows to (for example) *Acknowledge* multiple alarms at once.
+
+There are also two additional features in the *Panel options* section:
+
+. *Use Grafana user.* 
+Used to control whether operations on alarms are performed by the data source user, or the user that is currently logged in to Grafana.
+Supported operations are escalating, clearing, un-acknowledging alarms as well as creating/updating a journal/memo.
+*NOTE:* The data source must be configured using an user with the "admin" role in order to perform actions as other users.
+Default is off.
+
+. *Display action notice.*
+Enables a notice to be displayed after performing an action such as acknowledge, clear or escalate
+which will notify the user whether the action succeeded and prompt them to refresh the panel.
+Default is on.
+
 
 image::alarms-table-example.png["Example of an alarms table panel in edit mode. Areas of note are outlined in red.", 850]
 
@@ -119,6 +135,9 @@ NOTE: The query must include an `asTableSummary()` transform, otherwise the pane
 This sets the method by which data is grouped in the panel.
 *Stacked* displays cumulative data from all sources, grouped by incoming and outgoing data.
 ** (Optional) Update the legend settings as desired.
+*** *Show Legend* shows or hides the legend
+*** *Position* positions the legend either on the *Right Side* (the default), or else *Under Graph*
+*** *Height* is the height in `px` of the legend, default is 42. You can increase this if not all legend items are showing, perhaps if there are over 10 items.
 . Set other display options as desired.
 
 Using these settings, the flow histogram panel displays the following visualization:

Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,9 @@ npm ci`
`47`	`47`	`[source, shell]`
`48`	`48`	`npm run dev`
`49`	`49`
	`50`	+Note that `npm run dev` will generate (mostly) non-minified code which is better when debugging in a browser.
	`51`	+For a release build, you can run `npm run build` to create minified and optimized code.
	`52`	`+`
`50`	`53`	. Symlink your `dist` directory to Grafana's plugin path:
`51`	`54`	`+`
`52`	`55`	`[source, shell]`