diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 9a8838c1..41836a0b 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.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 diff --git a/docs/ee/reporting/functions/faq.md b/docs/ee/reporting/functions/faq.md new file mode 100644 index 00000000..301636fa --- /dev/null +++ b/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. diff --git a/docs/ee/reporting/functions/reporting_assets.md b/docs/ee/reporting/functions/reporting_assets.md new file mode 100644 index 00000000..12e514d5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/ee/reporting/functions/reporting_basetemplates.md b/docs/ee/reporting/functions/reporting_basetemplates.md new file mode 100644 index 00000000..131583c3 --- /dev/null +++ b/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 + + + + + + {% block content%}{% endblock %} + + +``` + +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 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 + + + + + + + +
+ {% block content %}{% endblock %} +
+ + + + +``` + +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. diff --git a/docs/ee/reporting/functions/reporting_basics.md b/docs/ee/reporting/functions/reporting_basics.md new file mode 100644 index 00000000..330b8a9c --- /dev/null +++ b/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 `` 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. \ No newline at end of file diff --git a/docs/ee/reporting/functions/reporting_dataqueries.md b/docs/ee/reporting/functions/reporting_dataqueries.md new file mode 100644 index 00000000..b7015c2c --- /dev/null +++ b/docs/ee/reporting/functions/reporting_dataqueries.md @@ -0,0 +1,563 @@ +# Data Queries + +## Introduction + +Data queries allow you to pull information from the Tactical RMM database to use in your +Templates. Data queries are defined in the variables editor under the data_sources object. +There is a predefined format that the data query must follow and it is defined using a JSON +or yaml syntax. + +At it's simplest form, a data query just specifies a model. Doing this will pull all of the +records and columns available from the table. + +This is an example of a data query that pulls all columns and rows from the sites table. + +```yaml +data_sources: + sites: + model: site +``` + +Once this is specified in the variables, you can use this data in the template like this: +`{{data_sources.sites}}`. This will just dump the data into the template, but it isn't very +useful. We can actually loop over this data query to format it using a Jinja +for loop. + +``` +{% for item in data_sources.sites %} +{{item.name}} +{% endfor %} +``` + +This will print out the name of every site on a new line. + +We can have multiple data_sources specified also like so. + +```yaml +data_sources: + sites: + model: site + clients: + model: client +``` + +The same rules apply for the second query. You can reference it in your templates using +`{{data_sources.clients}}`. + +## Template Dependencies + +Template dependencies allow you to pass information to a report at runtime. This could be +a client, site, or agent. These are covered in detail in the documentation, but just know +that you can use template dependencies in your data queries by using the `{{ }}` in place of the +data you want to replace. See the example below for a client dependency: + +```yaml +data_sources: + sites: + model: site + filter: + client_id: '{{ client.id }}' +``` + +!!!note + Note that quotes are required around `{{}}` tags in the variables section + +## Data Query Editor + +There is a data query editor that supports auto-complete so that you can more easily +determine which columns and relations are available. *It is recommended to always use +this editor to avoid typos and errors when generating reports.* You can open the query +editor by going to **Reports Manager > Data Queries > New** or in the template editor by +clicking **Add Data Query** or **Edit Data Query** toolbar button in the template. + +Do note that the Query Editor uses JSON syntax to provide the auto-complete functionality. +You can either start typing to trigger the auto-complete list, or press the Ctrl+Alt key. + +## Syntax + +Below are the allowed properties in a data query. You can combine these properties together +is the same data query unless specifically noted. + +### model - string + +The only required field for a data query is the **model**. This tells the system which database +table to pull the data from. The available models are: + +* agent +* agentcustomfield +* agenthistory +* alert +* auditlog +* automatedtask +* check +* checkhistory +* checkresult +* chocosoftware +* client +* clientcustomfield +* debuglog +* globalkeystore +* pendingaction +* policy +* site +* taskresult +* winupdate +* winupdatepolicy + +### [only](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#only) - array of strings + +**Only** is useful for only pulling certain columns. This is recommended if you are +pulling data from the agents table since **services** and **wmi_detail** columns are +very large and can take a long time to run. + +A few examples of using only. + +```yaml +data_sources: + sites: + model: site + only: + - name + - failing_checks + clients: + model: client + only: + - name + - failing_checks + agents: + model: agent + only: + - hostname + - operating_system + - plat +``` + +### [defer](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#defer) + +To not load some fields by default to limit data from being pulled, unless it is needed later for some reason. + +### custom_fields - array of strings + +This is only applicable to the **client**, **site**, and **agent** model. You can +pass an array of strings with names of custom fields and it will inject them into +the data. + +Lets say we have these custom fields configured: + +Client +- custom_field +- Custom Field 2 + +Site +- another Custom Field +- no_spaces + +Agent +- agent_custom_field + +We can pull this data in a data query like this: + +```yaml +data_sources: + clients: + model: client + only: + - name + - failing_checks + custom_fields: + - custom_field + - Custom Field 2 + sites: + model: site + only: + - name + - failing_checks + custom_fields: + - another Custom Field + - no_spaces + agents: + model: agent + only: + - hostname + - operating_system + - plat + custom_field: + - agent_custom_field +``` + +The custom field names are case sensitive and the custom field must be configured in +the system or no custom data will be pulled. A custom_fields object is added to the +data and is accessible in the template. + +You can access the custom field data for the clients data query like this: + +``` +{% for item in data_source.clients %} +{{ item.custom_fields.custom_field }} +{{ item.custom_fields["Custom Field 2"] }} +{% endfor %} +``` + +Note that you can't use dot notation for a property if it has spaces. See the above +example for the **Custom Field 2** property + +### [filter](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#filter) - object + +Using the filter property, you can filter the amount of rows that are returned. This +is useful if you only want a agents for a particular client or site, or you only +want agents tht are pending a reboot. + +See below for an example: + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + filter: + needs_reboot: True +``` + +This data query will only return agents that need a reboot. We can also add a second +filter like so. + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + filter: + needs_reboot: True + plat: "windows" +``` + +The above is just doing an *equals* comparison to make sure the rows match. You can also +use other operations like greater than, contains, etc. + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + filter: + operating_system__contains: "22H2" +``` + +To use the contains filter, we need to append two underscores (_) and type in the field lookup. +This just uses the django built in field lookups.A full list can be found +[Here](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#field-lookups) + +### [exclude](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#exclude) - object + +We can use this to exclude rows from our data. The same rules apply for filter apply here. (See above) + +Example + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + exclude: + plat: "linux" +``` + +### limit - number + +This will limit the number of returned rows in the data. + +Example + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + limit: 400 +``` + +### [get](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#get) - boolean + +Instead of returning a list, the data query will attempt to return a single object. This is +best used with a filter that guarantees a single row returned, i.e: filtering by id. This will +error out if the query returns more than one object. + +Example + +```yaml +data_sources: + agent: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + filter: + agent_id: hjk1hj23hj23hkj2hjh3j2h3 + get: true +``` + +In the template, you can use the properties directly instead of looping + +``` +{{data_sources.agent.hostname}} +{{data_sources.agent.operating_system}} +``` + +### [first](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#first) - boolean + +This will return the first row in a table. This is guaranteed to always return one result. +You can apply other properties (like filter or exclude) also to limit the data. + +Example + +```yaml +data_sources: + agent: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + first: true +``` + +In the template, you can use the properties directly instead of looping + +``` +{{data_sources.agent.hostname}} +{{data_sources.agent.operating_system}} +``` + +### [count](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#id9) - boolean + +This allows you to return the number of rows found. Can be used with filter or exclude. + +Example + +```yaml +data_sources: + agent: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + count: true +``` + +### order_by - string + +This allows you to reorder the returned data based on a specific column. Putting a '-' +before the column puts it in descending order and the default is ascending order + +Ascending Example + +```yaml +data_sources: + agent: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + order_by: hostname +``` + +Descending Example + +```yaml +data_sources: + agent: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + order_by: -hostname +``` + +### csv - boolean | object + +This is a shorthand to return a string formatted as a csv. + +Example + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + - site__name + - site__client__name + filter: + site__client__name: "Client Name" + csv: true +``` + +This will add a **site__name** and **site__client__name** column on the returned data. We use a +double underscore every time we want to go to another table. The site column exists directly on +the agents table. So in order to get the name (which resides on the sites table) we need to use +the double underscore. Same thing with the client name. We need to go through the sites table +in order to get the client name so we use another double underscore. + +Usage in template + +{{data_sources.agents}} + +Output will look something like: + +``` +hostname,operating_system, plat,needs_reboot,site__name,site__client__name +data,data,data,data,data,data +``` + +You can also rename the columns by passing a mapping into csv like so: + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + - site__name + - site__client__name + filter: + site__client__name: "Client Name" + csv: + hostname: Hostname + operating_system: Operating System + plat: Platform + needs_reboot: Needs Reboot + site__name: Site Name + site__client__name: Client Name +``` + +Which would return something like + +``` +Hostname,Operating System,Platform,Needs Reboot,Site Name,Client Name +data,data,data,data,data,data +``` + +### json - boolean + +This will return a json string representation of the object. This is useful +if you are passing the data source to be processed by javascript. + +Example + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + - site__name + - site__client__name + filter: + site__client__name: "Client Name" + json: true +``` + +Usage in template + +`{{data_sources.agents}}` + +Output will look something like: + +``` +hostname,operating_system, plat,needs_reboot,site__name,site__client__name +data,data,data,data,data,data +``` + +## Relations + +You can include columns from a related model by using the double underscore syntax. You may have +a data query using the agents table, but want to include the Site name and the Client name. +See the example below: + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + - site__name + - site__client__name +``` + +This will add a **site__name** and **site__client__name** column on the returned data. We use a +double underscore every time we want to go to another table. The site column exists directly on +the agents table. So in order to get the name (which resides on the sites table) we need to use +the double underscore. Same thing with the client name. We need to go through the sites table +in order to get the client name so we use another double underscore. + +All available combinations are listed in the query editor + +To display these columns in the template you can do this: + +This will return a json string representation of the object. This is useful if you are passing the +data source to be processed by javascript or you just want to create your own custom api endpoint. + +``` +{% for item in data_source.agents %} +{{ item.site__name }} +{{ item.site__client__name }} +{% endfor %} +``` + +We can also filter based on relations. See below: + +```yaml +data_sources: + agents: + model: agent + only: + - hostname + - operating_system + - plat + - needs_reboot + - site__name + - site__client__name + filter: + site__client__name: "Client Name" +``` \ No newline at end of file diff --git a/docs/ee/reporting/functions/reporting_variables.md b/docs/ee/reporting/functions/reporting_variables.md new file mode 100644 index 00000000..777c5b6a --- /dev/null +++ b/docs/ee/reporting/functions/reporting_variables.md @@ -0,0 +1,175 @@ +# Variables + +Variables provide a way to enrich your report with data. Variables are entered using +YAML syntax and can be edited directly in the template by using the variables +editor on the right. Everything with YAML is case-sensitive, so make sure to check for typos! + +YAML syntax and features reference can be found [Here](https://quickref.me/yaml) + +## Some sample variables and how to use them in the template + +**Variables** + +```yaml +title: Title Name +listOfData: [12, 13, 14] +an_object: + key: value + key2: value2 + key with a space: value3 +an_array_of_objects: + - key: value + key2: value2 + the space: value3 + - key: value + key2: value2 + the space: value3 +``` + +**Markdown Template** +```md +# {{title}} + +## A list of numbers +{% for item in listOfData %} +* {{item}} +{% endfor %} + +## List the object keys +* {{an_object.key}} +* {{an_object.key2}} +* {{an_object["key with a space"]}} + +## List of objects +{% for item in an_array_of_objects %} +* {{item.key}} +* {{item.key2}} +* {{item["the space"]}} +{% endfor %} +``` + +**Rendered Output** + +```md +# Title Name + +## List of numbers +* 12 +* 13 +* 14 + +# List the object keys +* value +* value2 +* value3 + +## List of objects +* value +* value2 +* value3 +* value +* value2 +* value3 +``` + +## Dependencies + +Dependencies offer a way to provide information to the templating engine at the reports +runtime. The three built in dependencies are **client**, **site**, and **agent**. The +dependencies dropdown also allows for custom values to be entered. When you run the +report, a dialog box will show that requires you to provide the values for the dependencies. +If you ran the report from a right-click context menu item for client, site, or agent, the +dependency will auto-populate in the report. + +Dependencies are actually merged into the variables behind the scenes, so any properties on +the dependency are available to the template to use. + +## Built-in dependencies + +You can access the built-in dependencies directly in the template using {{client.name}}, +{{agent.hostname}}, etc. + +## Custom dependencies + +You can type in custom dependencies in the dropdown to prompt for other information at +report runtime. Custom dependencies only support string values at this time and are +referenced in the template using {{ custom_dependency_name }}. + +## Using Template Dependencies in variables + +Note: You can use dependencies in data queries to filter data. See [Data Queries](reporting_dataqueries.md) + +You can also use dependencies in the variables section. The syntax is still the same +as using them in the template, but you need to make sure that the {{}} is surrounded +with quotes. + +Example with client and a custom_dep dependency + +```yaml +title: '{{client.name}} Summary' +dependency: '{{custom_dep}} some value' +``` + +## Variable Analysis + +If you want to see what your data will look like and how to use it in your template, you can +click on the **>** icon on the top-left of the editor windows. (Under the Template Name field). +This will run the report template variables server-side and send the results back. This is +really useful for data queries and other dynamic information that isn't immediately apparent. + +You can also click on the property to copy the template tag to the clipboard. There is also +a button for arrays to generate a for loop. You can clip in the loop button and it will put +the text in the clipboard to be pasted into the template. + +If you are using dependencies, you will need to click on the Preview tab and fill in the +dependencies before the variables analysis will run. + +## Custom processors + +Custom processors are provided to the yaml parser and allow shortcuts or provide functionality +that isn't possible using the template and variables alone. + +### !!now + +Provides a timestamp at the report runtime. + +Example + +```yaml +report_run_timestamp: !!now +``` + +You can also get a timestamp in the future or the past by passing a parameter. The supported time +intervals are: + +* weeks +* days +* hours +* minutes +* seconds +* microseconds + +If you want a timestamp in the future 5 days you would do: + +```yaml +five_days_from_now: !!now days=5 +``` + +If you want a timestamp 4 hours in the past you would do: + +```yaml +four_hours_ago: !!now hours=-4 +``` + +You can also specify a value from a dependency. + +Note: The !!now must be outside of the quotes. + +```yaml +last_seen_time: !!now 'hours=-{{last_seen}}' +``` + +If we ran the report and put in 5 it would output +```yaml +last_seen_time: !!now 'hours=-5' +``` \ No newline at end of file diff --git a/docs/ee/reporting/functions/tipsntricks.md b/docs/ee/reporting/functions/tipsntricks.md new file mode 100644 index 00000000..d9e873f2 --- /dev/null +++ b/docs/ee/reporting/functions/tipsntricks.md @@ -0,0 +1,14 @@ +# Tips n' Tricks + +## Formatting matters + +Make sure your tabs are at the right level. + +![tabs matter](../images/reporting_tabs_matter.png) + +## Quickly generate reports from client/site tree + +Right click on a client or site to quickly run/download a report. + + +![quick report](../images/quick_report.png) \ No newline at end of file diff --git a/docs/ee/reporting/images/quick_report.png b/docs/ee/reporting/images/quick_report.png new file mode 100644 index 00000000..1b3a1926 Binary files /dev/null and b/docs/ee/reporting/images/quick_report.png differ diff --git a/docs/ee/reporting/images/reporting_tabs_matter.png b/docs/ee/reporting/images/reporting_tabs_matter.png new file mode 100644 index 00000000..b9311afd Binary files /dev/null and b/docs/ee/reporting/images/reporting_tabs_matter.png differ diff --git a/docs/ee/reporting/reporting_overview.md b/docs/ee/reporting/reporting_overview.md new file mode 100644 index 00000000..f91b9931 --- /dev/null +++ b/docs/ee/reporting/reporting_overview.md @@ -0,0 +1,25 @@ +# Reporting Overview + +*Released in TRMM v0.17.0 (Nov 1, 2023)* + +The reporting addon allows you to access your Tactical RMM data and represent in the format +of your choice. This could be a PDF file, a simple csv, or a complex interactive web dashboard. + +It is best to get started with using the [shared templates](https://github.com/amidaware/reporting-templates) and go from there (you can import these directly from the TRMM web UI with 1 click.) The pages below +will help you get familiar with the terminology and the syntax. + +Check back here frequently in the coming days/weeks/months as we will be constantly updating and improving the Reporting docs and adding video tutorials. + +[FAQ](functions/faq.md) + +[The Basics](functions/reporting_basics.md) + +[Base Templates](functions/reporting_basetemplates.md) + +[Variables](functions/reporting_variables.md) + +[Data Queries](functions/reporting_dataqueries.md) + +[Report Assets](functions/reporting_assets.md) + +[Tips and Tricks](functions/tipsntricks.md) \ No newline at end of file diff --git a/docs/sponsor.md b/docs/sponsor.md index 12a850cd..55716971 100644 --- a/docs/sponsor.md +++ b/docs/sponsor.md @@ -12,7 +12,7 @@ We are always looking for feedback and ways to improve Tactical RMM to better ad Stripe is our preferred payment processor, please use Stripe instead of Paypal if you can. -If you need automatic invoicing for your company, please use Stripe as it will automatically generate invoices for you with each payment. +If you need an invoices, please use Stripe as it will automatically generate invoices for you with each payment. If you cannot use Stripe and must use Paypal and still need automatic invoicing then please [contact us](https://support.amidaware.com/) first before subscribing so we can setup a custom invoice for you. @@ -22,8 +22,8 @@ After sponsoring, follow [the instructions](code_signing.md#code-signing) to get | Package | Price | Description | Sign up | | --- | --- | --- | --- | - | Tier 1 | $55/month | - minimum for code signing
- suggested sponsorship for less than 200 agents | [Paypal](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-8GF46962LC4592048MPWTBJY)
[Stripe](https://buy.stripe.com/cN228t4lD6Qc1Ak7ss) | - | Tier 2 | $80/month | - suggested sponsorship for less than 400 agents | [Paypal](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-8N5333625F157823NMPWTDQI)
[Stripe](https://buy.stripe.com/4gwdRb6tL1vSceYeUW) | + | Tier 1 | $55/month | - Minimum tier required for [code signing](code_signing.md)
- suggested sponsorship for less than 200 agents | [Paypal](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-8GF46962LC4592048MPWTBJY)
[Stripe](https://buy.stripe.com/cN228t4lD6Qc1Ak7ss) | + | Tier 2 | $80/month | - Minimum tier required for [Reporting](./ee/reporting/functions/faq.md) (excluding Founders)
- suggested sponsorship for less than 400 agents | [Paypal](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-8N5333625F157823NMPWTDQI)
[Stripe](https://buy.stripe.com/4gwdRb6tL1vSceYeUW) | | Tier 3 | $105/month | - suggested sponsorship for less than 600 agents | [Paypal](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-63E24030E6802431TMPWURDY)
[Stripe](https://buy.stripe.com/aEU28t19r0rOfraeUX) | | Tier 4 | $155/month | - suggested sponsorship for less than 1,000 agents | [Paypal](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-3D6045112C172261AMPWURVI)
[Stripe](https://buy.stripe.com/fZe8wR8BT0rOgvedQU) | | Tier 5 | $310/month | - suggested sponsorship for less than 3,000 agents | [Paypal](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-20P602963T9792143MPWU43I)
[Stripe](https://buy.stripe.com/fZecN719r6Qc1Ak3ch) | @@ -34,8 +34,8 @@ After sponsoring, follow [the instructions](code_signing.md#code-signing) to get | Package | Price | Description | Sign up | | --- | --- | --- | --- | - | Tier 1 | $600/year | - minimum for code signing
- suggested sponsorship for less than 200 agents | [Stripe](https://buy.stripe.com/3cs7sNdWd1vSen6fYZ) | - | Tier 2 | $900/year | - suggested sponsorship for less than 400 agents | [Stripe](https://buy.stripe.com/3cs4gB7xPeiE3Is4gt) | + | Tier 1 | $600/year | - Minimum tier required for [code signing](code_signing.md)
- suggested sponsorship for less than 200 agents | [Stripe](https://buy.stripe.com/3cs7sNdWd1vSen6fYZ) | + | Tier 2 | $900/year | - Minimum tier required for [Reporting](./ee/reporting/functions/faq.md) (excluding Founders)
- suggested sponsorship for less than 400 agents | [Stripe](https://buy.stripe.com/3cs4gB7xPeiE3Is4gt) | | Tier 3 | $1,200/year | - suggested sponsorship for less than 600 agents | [Stripe](https://buy.stripe.com/dR6dRbf0h4I4gvebIQ) | | Tier 4 | $1,800/year | - suggested sponsorship for less than 1,000 agents | [Stripe](https://buy.stripe.com/7sIfZjcS91vS0wg00e) | | Tier 5 | $3,600/year | - suggested sponsorship for less than 3,000 agents | [Stripe](https://buy.stripe.com/3csfZj5pHdeA3IsbIX) | diff --git a/mkdocs.yml b/mkdocs.yml index af2ec288..a3aea641 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,6 +35,16 @@ nav: - "User Interface Preferences": functions/user_ui.md - "Reference: Script Variables": script_variables.md - "Examples": functions/examples.md + - Reporting: + - "Overview": ee/reporting/reporting_overview.md + - "- FAQ": ee/reporting/functions/faq.md + - "- The Basics": ee/reporting/functions/reporting_basics.md + - "- Base Templates": ee/reporting/functions/reporting_basetemplates.md + - "- Variables": ee/reporting/functions/reporting_variables.md + - "- Data Queries": ee/reporting/functions/reporting_dataqueries.md + - "- Assets": ee/reporting/functions/reporting_assets.md + - "- Tips n' Tricks": ee/reporting/functions/tipsntricks.md + - Backup: backup.md - Restore: restore.md - Antivirus Exclusions: av.md diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..1af18673 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,29 @@ +certifi==2022.9.24 +charset-normalizer==2.1.1 +click==8.0.4 +colorama==0.4.6 +ghp-import==2.0.2 +idna==3.4 +importlib-metadata==4.11.3 +Jinja2==3.0.3 +Markdown==3.3.6 +MarkupSafe==2.1.1 +mergedeep==1.3.4 +mkdocs==1.5.3 +mkdocs-material==8.5.11 +mkdocs-material-extensions==1.1.1 +packaging==21.3 +pathspec==0.11.2 +platformdirs==3.11.0 +Pygments==2.14.0 +pymdown-extensions==10.3.1 +pyparsing==3.0.7 +python-dateutil==2.8.2 +PyYAML==6.0 +pyyaml_env_tag==0.1 +regex==2022.10.31 +requests==2.28.1 +six==1.16.0 +urllib3==1.26.12 +watchdog==2.1.6 +zipp==3.7.0