Merge branch 'feat-reporting' into main

.github/workflows/deploy-docs.yml

@@ -14,5 +14,5 @@ jobs:
           python-version: '3.10'
       - run: pip install --upgrade pip
       - run: pip install --upgrade setuptools wheel
-      - run: pip install mkdocs mkdocs-material==8.5.11 pymdown-extensions
+      - run: pip install -r requirements.txt
       - run: mkdocs gh-deploy --force

docs/ee/reporting/functions/faq.md

@@ -0,0 +1,39 @@
+# Reporting FAQ
+
+## Pricing
+
+Existing sponsors as of Oct 31, 2023: As a thank you for all your support and patience, you will get our Founders Edition perpetual reporting license which will be included in your existing sponsorship. To enable reporting, simply update your instance as you normally do and reporting will automatically be enabled.
+
+For all others, Reporting will be included for all [Tier 2](../../../sponsor.md#sponsor-with-stripe-or-paypal) and higher packages.
+
+## How do I enable reporting as a new sponsor?
+
+1. Make sure your server has an appropriate [code signing](../../../code_signing.md) token saved ( Settings > Code Signing).
+
+2. Run the update script with the `--force` flag (see instructions below for standard vs docker installs):
+
+3. Reload the web page. Make sure you use your browser's reload button to hard reload the page.
+
+???+ note ""
+
+    === ":material-ubuntu: Standard install"
+
+        ```bash
+        cd ~
+        wget -N https://raw.githubusercontent.com/amidaware/tacticalrmm/master/update.sh
+        chmod +x update.sh
+        ./update.sh --force
+        ```
+
+    === ":material-docker: Docker install"
+
+        ```bash
+        docker compose down
+        docker compose up -d
+        ```
+
+If there's a problem, [open a ticket](https://support.amidaware.com).
+
+## How do I add charts/graphs to my report templates?
+
+A bug was discovered with the chart/graph implementation right before release and it had to be pulled. It wil be released in a future update.

docs/ee/reporting/functions/reporting_assets.md

@@ -0,0 +1,49 @@
+# Assets
+
+The Reports Manager gives the ability to upload and store static assets for use in any
+report. These can be used in html or PDF reports. 
+
+In Report Templates, report assets are referenced by their unique ID so they can be renamed and moved
+without messing up the links.
+
+## Managing Assets
+
+Open **Reports Manager** and click on the **Report Assets** button at the top. This will take you 
+to the root of the reporting assets directory. You can drill into folders by double-clicking
+and there is a right-click menu to perform other operations.
+
+### Adding folders
+
+Navigate to the directory you want to create the folder. Use the **Add Folder** button at the top and
+give the folder a name. The folder will show up in the list.
+
+### Uploading assets
+
+Navigate to the directory you want to upload the file(s). Click on the **Upload** button at the top and a 
+dialog will open. You can specify multiple assets and click Upload. If there is a name conflict, a set of random
+characters will be appended.
+
+### Downloading assets
+
+Use the right-click menu item to download report assets. If you download a folder it will
+zip it prior to download. Downloading a file will download the file without zipping.
+
+### Deleting assets.
+
+There are two ways to delete assets. You can use the right-click menu to select a folder or asset to 
+delete. This will remove the folder and anything under it.
+
+There is also a bulk delete option by selecting multiple items. Select all of the items you want to delete
+and click the **Bulk Actions** button. Select **Delete** and confirm.
+
+### Renaming assets
+
+Use the right-click menu to rename folders or files. If there is a name conflict, a set of random
+characters will be appended.
+
+## Using assets in report templates
+
+In the Report Template editor, click on the **Image** button on the toolbar. Select the **Report Assets**
+radio button and browse to the asset you want to add. Select it and press insert. This will add a link 
+with a url that looks something like `asset://{uuid}`. The reporting engine will resolve this url
+to the asset and generate an appropriate url based on if the report output format is HTML or PDF.

docs/ee/reporting/functions/reporting_basetemplates.md

@@ -0,0 +1,102 @@
+# Base Templates
+
+Base Templates are used to apply the same formatting to multiple templates. The base template
+will declare one or more "blocks" that are then filled in by the child template. Base templates
+use the Jinja syntax for inheriting and extending. You can see the reference 
+[Here](https://jinja.palletsprojects.com/en/3.1.x/templates/#template-inheritance).
+
+!!!note
+    Even though the examples for base templates are in html, you can use any format you want.
+
+## Adding base templates
+
+To add a base template you can browse to **Reports Manager > Base Templates > Add**. From there 
+you can create your base template in the editor and click save.
+
+## Using a base template in your report template
+
+To use the base template, we will need to open up the Report Template editor 
+(**Reports Manager > double-click on the template**), then select the base template from the 
+dropdown.
+
+!!!note 
+    This will automatically add the {% extends ... %} tag at the beginning of the report template
+    on the backend. If you are looking through the Jinja base template documentation, you can omit that
+    line.
+
+## Using blocks
+
+See below for a basic base template that specifies one block.
+
+```html
+<html>
+    <head>
+        <style>
+            {{css}}
+        </style>
+    </head>
+    <body>
+        {% block content%}{% endblock %}
+    </body>
+</html>
+```
+
+In the template that is inheriting the base template above, you can fill in these
+blocks like so:
+
+```
+{% block content%}
+This will show up between the <body> tags in the base template/
+{% endblock %}
+```
+
+## Multiple blocks
+
+We can also fill in multiple blocks if they are specified in the base template. Any blocks
+that aren't used will just be blank.
+
+```html
+<html>
+    <head>
+        <style>
+            {{css}}
+        </style>
+    </head>
+    <body>
+        <div id="header">
+        {% block header %}{% endblock %}
+        </div>
+
+        <div id="content">
+        {% block content %}{% endblock %}
+        </div>
+
+        <div id="footer">
+        {% block footer %}{% endblock %}
+        </div>
+    </body>
+</html>
+```
+
+In the template, we just need to use the same blocks and it will fill in the data.
+
+```
+{% block header %}
+This is the header
+{% endblock %}
+
+{% block content %}
+This is the content
+{% endblock %}
+
+{% block footer %}
+This is the footeer
+{% endblock %}
+```
+
+## Variable analysis
+
+In the Report Template editor, you can quickly see what blocks the base template has available. 
+You can click on the **>** button in the top-left of the editor (Under the report name field) and 
+at the top it will give a warning if it doesn't see the blocks listed. You can also click on the
+blocks to copy them to the clipboard to be pasted into the template.

docs/ee/reporting/functions/reporting_basics.md

@@ -0,0 +1,175 @@
+# The Basics
+
+This template will show case the basics of reporting and also give some examples on how to use them. The toolbar along the top 
+has various formating options for text and some useful functions for building dynamic reports. Reports are built using the Jinja
+templating engine. A reference guide and be found [Here](https://jinja.palletsprojects.com/en/3.1.x/templates/). 
+
+## Reporting formats
+
+You can write report templates using **Markdown**, **HTML**, or **Plain Text**. HTML and Markdown reports will look the 
+same regardless of choice. Templates cannot be converted between formats, but it would be easy enough to do the conversion
+manually between markdown and HTML
+
+### Markdown templates
+
+Do note that HTML is valid in markdown and should be used when the Markdown syntax doesn't do exactly what you need. An example
+would be for using the `<table>` tag.
+
+Also note that the markdown is rendered to HTML anyway.
+
+See [this](https://daringfireball.net/projects/markdown/syntax) reference for Markdown syntax
+
+### Plain text templates
+
+Plain Text templates are a great choice if you just want to generate some text without all of the formatting. This is very useful if you want a CSV export of some data.
+
+## The toolbar
+
+The toolbar along the top of the editor provides some shortcuts for commonly used functions. Most of the 
+buttons are used for text formatting, but there are some shortcuts for adding/editing data queries, base templates,
+and inserting charts and tables. Hovering over the button will display its function.
+
+## Variables
+
+You can add in variables in the right editor pane. The variables pane can be toggled
+on/off using the *vars* button on the toolbar. The variables are adding in yaml format
+and can be referenced using `{{variable_name}}` in the template. The value of the variable
+will be substituted when the template is rendered. If the value of the variables is nested within
+an object, you can use dot notation to render the value like `{{ object.variable_name }}`. If there is
+a space in the name you can use `{{ object["variable name"] }}`.
+
+### Variable analysis
+
+With data sources and other dynamic sources, it can be difficult to view what the data
+looks like to use in report templates. With variable analysis, the query is ran and 
+the available properties are returned. Click on the > arrow on the top left of the 
+editor window (under the toolbar) to see the available properties from the variables
+section. You can then click on them to copy and you can paste them into the template.
+
+For array values, you can click the **For loop** button and paste in a Jinja for loop
+to easily loop over the properties.
+
+## Data queries
+
+Data queries are a way to save commonly used queries and use them in templates. Data
+queries are added under the data_sources key in the variables section. If the key 
+doesn't exist, it will be created
+
+### Adding data queries
+
+Using the **Add Data Query** button on the toolbar, it will open the data query editor.
+This editor will let you know the valid syntax of the query and supports auto-complete.
+If you are stumped and need to know all of the values that are supported you can press
+Ctrl+Space and a dropdown will show. Once you add the query, it will be auto-inserted
+into the template.
+
+You can also add a data query from the **Report Manager** and open the Data Queries button
+along the top. This is the save function as using the toolbar, but it will save the query
+to allow it to be used in templates.
+
+### Inserting saved data queries
+
+You can insert a saved data query using the **Insert Data Query** button on the toolbar. You just
+have to select the data query from the drop down and it will insert it into the template.
+
+### Editing data queries
+
+You can edit data queries in the template by clicking the **Edit Data Query** button on the toolbar.
+This will list the currently added data_sources into a dropdown and allow you to edit them in the 
+auto complete editor. Clicking save will replace the data query in the variables with the updated 
+one.
+
+
+## Report output format
+
+Reports can be output in either **HTML**, **PDF**, or in **Plain Text** format.
+
+### HTML and Markdown Template types
+
+HTML and Markdown template types and be output in PDF or HTML formats. These template types don't 
+support plain text output.
+
+### Plain Text
+
+Plain text template types can be output in PDF or text. This template type doesn't support html output.
+Putting markdown or anything else in a plain text template will just output the same markdown. It isn't processed through
+the markdown library.
+
+## CSS
+
+CSS can be embedded in the report template using the CSS tab on the top right on the
+report template editor. The CSS class can be referenced in the report template for
+styling. 
+
+If you are using markdown, you can add ids and classes to html elements by
+using `{#id_name}` and `{.class_name}` beside the template.
+
+This will render an h1 html tag with an id of 'id-name' `{#id-name}`
+
+This will render an h1 html tag with a class of 'class-name' `{.class-name}`
+
+## Report assets
+
+Assets can be served from your Tactical RMM instance. They will need to be uploaded
+to the Asset Manager first. This can be accessed from the Reporting Manager windows by
+clicking on the Report Assets.
+
+Once uploaded, click on the *Image* button on the toolbar and select the **Report Asset**
+radio button. From there you can click on an asset and go to Insert.
+
+## Base templates
+
+Base Templates allow you to use the same report structure throughout multiple reports.
+The base template should be a full html document enclosed in an html tag. To specify
+content that should be overridden in the child template, you can use Jinja blocks in 
+the base template. See [this](https://jinja.palletsprojects.com/en/3.1.x/templates/#template-inheritance) 
+example in the Jinja documentation.
+
+You can add a base template from the report template editor by clicking the *base*
+button on the toolbar.
+
+When you select a base template (using the dropdown) in a report template, the **extends**
+block will automatically be inserted. You can click on the variable analysis button
+(top-left arrow) to see which blocks in the base template need to be overridden yet.
+Clicking on the block in variable analysis will copy the text to the clipboard and will
+need to be copied into the template.
+
+## Template dependencies
+
+Sometimes you need to provide data during a reports runtime. This could be a specific
+client, a date range, etc. This is achievable by setting a template dependency using
+the **Template Dependencies** dropdown on the report editor. Then default values are
+Client, Site, and Agent. You can type additional values that are required for the report.
+
+In your variables and report template, you can use these dependencies by enclosing the
+same of the dependency like so: `{{agent.hostname}}` or `{{client.name}}`. For custom
+dependencies you can just type in `{{ dependency_name }}`. These are case sensitive.
+
+## Report preview
+
+You can easily see what a report is going to look like by pressing the Preview button 
+on the top right of the editor window. You can choose between an HTML or PDF output 
+using the radio buttons.
+
+If you have report dependencies, a dialog box will show asking you to fill in the values
+that should be used to generate the report.
+
+### Debug
+
+if you need additional info showing the values of the variables and the rendered HTML,
+you can check the debug button. This will show at the bottom of the preview window.
+
+## Running a report
+
+Running a report can be done from the Reporting Manager by right-clicking on the 
+report template and either running as an HTML or PDF report. The report will open
+up in a separate window. If there are report dependencies, a dialog will prompt to 
+populate the values. 
+
+You can save the URL or bookmark it to easily generate the same report without having
+to populate the dependencies.
+
+If you have a Client, Site, or Agent dependency specified in the report, you can also
+right-click on the respective entity in Tactical RMM and go to **Integrations > Run Report**.
+You can then specify a report output type and the entity that you right-clicked on will
+automatically populate as a dependency.