AAP-52256 created modules for automation dashboard guide (#4181)

downstream/titles/automation-dashboard/automation-dashboard/assembly-appendix-inventory-file-automation-dashboard.adoc

@@ -0,0 +1,9 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-appendix-inventory-file-automation-dashboard"]
+= Appendix
+
+[role="_abstract"]
+The inventory variables required for installing {AutomationDashboardName} are described in the following section: 
+
+include::automation-dashboard/ref-automation-dashboard-inventory-variables.adoc[leveloffset=+1]

downstream/titles/automation-dashboard/automation-dashboard/assembly-view-key-metrics.adoc

@@ -0,0 +1,30 @@
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-view-key-metrics"]
+
+:context: assembly-view-key-metrics-ctxt
+
+= View key usage metrics with {AutomationDashboardName}
+
+The {AutomationDashboardName} utility is a web-based container application that provides key metrics related to job execution, efficiency, and the value derived from automation. {AutomationDashboardName} uses automation metrics to provide automation usage data from {PlatformNameShort}. You can use this data to determine the cost of performing tasks manually versus the cost of performing tasks through automation. This comparison is used to demonstrate the savings achievable through automation.
+
+{AutomationDashboardName} helps you to:
+
+* Get a clear overview of the automation occurring in your environment.
+
+* Track metrics, like time saved and errors reduced, to quantify the benefits of automation.
+
+* Analyze job execution times and failure rates to pinpoint areas where automation can be improved.
+
+* Use the data generated by {AutomationDashboardName} to make informed decisions about automation strategy, resource allocation, and prioritization of automation projects.
+
+By effectively utilizing {AutomationDashboardName}, you can gain valuable insights into your {PlatformNameShort} usage and drive continuous improvement in your automation practices.
+
+include::automation-dashboard/proc-installing-automation-dashboard.adoc[leveloffset=+1]
+
+include::automation-dashboard/proc-integrating-automation-dashboard.adoc[leveloffset=+1]
+
+include::automation-dashboard/proc-uninstalling-automation-dashboard.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

downstream/titles/automation-dashboard/automation-dashboard/automation-dashboard/con-filter-automation-data.adoc

@@ -0,0 +1,29 @@
+
+[id="con-filter-automation-data"]
+
+= Filter and save automation data
+
+{AutomationDashboardName} provides filtering options for analyzing your {PlatformNameShort} automation runs. You can select one or more filtering options, choose a time period and a currency, and save your report to the dashboard.
+
+== Filters
+
+You can select one or more of the following options to customize your report:
+
+* **Template:** Select one or more Job Templates.
+* **Organization:** Select one or more Organizations.
+* **Project:** Select one or more Projects.
+* **Label:** Select one or more automations by label. Labels must be preconfigured and assigned to {PlatformNameShort} before they display in {AutomationDashboardName}. For more on configuring labels, see the _Creating a job template_ procedure.
+//emurtoug update the link to Creating Job Templates procedure
+
+== Time period and currency
+
+After you select your filters, choose a time period for analysis and a currency to demonstrate automation savings.
+
+* A shorter time period is useful for specific automation use cases.
+* A longer time period is useful for overall platform usage and automation growth.
+
+Changing from one currency to another does not convert the value. You must manually change the manual and automation cost figures to reflect the currency you select.
+
+== Save a report
+
+Use *Save as report* to save this report to your {AutomationDashboardName}. You can retrieve it at any time by using *Select a report*.

downstream/titles/automation-dashboard/automation-dashboard/automation-dashboard/con-top-overview-usage.adoc

@@ -0,0 +1,17 @@
+
+[id="con-top-overview-usage"]
+
+= Summary of top and overview usage
+
+{AutomationDashboardName} displays a summary of the top and overview usage for your selected report. This includes the following data:
+
+* **Total number of successful jobs**: This indicates the number of automation jobs that were completed successfully. 
+* **Total number of failed jobs**: This shows the number of automation jobs that encountered errors. Analyzing these failures can help improve automation throughput, reduce errors, and improve efficiency. 
+* **Total number of unique hosts automated**: This is the number of controller inventory records you have automated. 
+* **Total hours of automation**: This represents the cumulative time that {PlatformNameShort} spent running jobs. 
+* **Number of times jobs were run**: This is the total number of individual job executions.
+* **Number of hosts jobs are running on**: This is the total number of hosts that jobs are executed upon. 
+* **Top 5 projects**: This section lists the top five automation projects based on the number of running jobs. 
+* **Top 5 users**: This section lists the top five users of {PlatformNameShort}, with a breakdown of the total number of jobs run by each user.
+[NOTE] 
+Scheduled jobs can affect these results, because they do not represent a real, logged-in user.

downstream/titles/automation-dashboard/automation-dashboard/automation-dashboard/proc-analyzing-costs-savings.adoc

@@ -0,0 +1,24 @@
+
+[id="proc-analyzing-costs-savings"]
+
+= Analyzing costs and savings
+
+The costs and savings analysis compares the cost of manual automation versus the cost of automation execution using {PlatformNameShort} to determine the total savings derived from automation execution.
+
+To calculate your savings, use the following procedure: 
+
+.Procedure
+
+. Use the **Average cost of an employee minut**e field to enter the average cost per minute for an engineer to manually run jobs.
+. Use the **Cost per minute of {PlatformNameShort}** field to enter an average cost per minute of running a job using {PlatformNameShort}. You can include the costs associated with creating the initial or ongoing automation execution.
+Based on these inputs, {AutomationDashboardName} provides the following data: 
+
+
+* **Cost of manual automation**: This number represents the estimated cost of manually performing all of the automated tasks. This is an estimated value, not an actual expenditure. It represents the potential expenses that the organization would incur without automation. The calculation is based on the time taken to manually execute each job, multiplied by a labor cost rate.
+* **Cost of automated execution**: This is the cost of automation execution using {PlatformNameShort}. This cost includes the resources consumed by {PlatformNameShort}, such as server time, processing power, and any other operational expenses associated with automation execution. It represents the actual cost incurred for automation execution.
+* **Total savings/cost avoided**: This is the difference between the **Cost of manual automation** and the **Cost of automated execution**. This is a key metric for demonstrating the return on investment attainable by using {PlatformNameShort}.
+* **Total hours saved/avoided**: This figure is calculated by adding host executions and automation creation time, then subtracting the running time in minutes.
+* **Time taken to manually execute (min)**: This metric represents the amount of time it would take for a user to perform the task manually on a host. It is an input provided to compare the value of manual execution and automated execution using the time taken by the organization to manually automate. 
+
+[NOTE]
+You can export the data from your cost and savings analysis as a CSV.

downstream/titles/automation-dashboard/automation-dashboard/automation-dashboard/proc-installing-automation-dashboard.adoc

@@ -0,0 +1,131 @@
+// Module included in the following assemblies:
+// assembly-view-key-metrics.adoc
+
+
+[id="proc-installing-automation-dashboard"]
+
+= Installing {AutomationDashboardName}
+
+.Prerequisites
+
+* One of the following tested configurations:
+** RHEL 9 x86 or ARM based physical or virtual host. 
+** Postgres v15 database. 
+[IMPORTANT]
+Do not attempt to install {AutomationDashboardName} on the same hosts as {PlatformNameShort}.
+* Access to _baseos_ and _{PlatformNameShort}stream_ repo packages for the RHEL 9 host.
+* A non-root login account to the RHEL 9 host for installation. This requires passwordless sudo access to root as well. By default, we use the $HOMEDIR of the user account.
+* URL details for access to your {PlatformNameShort} instances.
+* An {PlatformNameShort} 0Auth2 token, which is used for communication between the {PlatformNameShort} instances and {AutomationDashboardName}.
+* Access to download the installation bundle providing installation components for the {AutomationDashboardName}.
+* Open firewall access to allow for communications. This includes HTTPS/443 from the {AutomationDashboardName} to the {PlatformNameShort} instances, but ports are configurable.
+* Access to port 8447.
+* A supported version of `ansible-core` installed on supported RHEL versions.
+
+.Procedure
+
+Use the following steps to install {AutomationDashboardName} on your {RHEL} (RHEL) 9 host:
+
+. Copy the installation source file to your RHEL 9 host.
+. Untar the installation source. This requires approximately 500 MB of disk space. For this example, the user's home directory (`/home/ec2-user`) is used.
++
+[source,bash]
+----
+tar -xzf ansible-automation-reports-containerized-setup-bundle.tar.gz
+cd ansible-automation-reports-containerized-setup/
+----
+
+. Verify that the necessary software is installed by running the following commands:
++
+[source,bash]
+----
+sudo dnf install ansible-core
+ansible-galaxy collection install -r requirements.yml
+----
+
+. Copy the example inventory file and modify it before running the installer.
++
+[source,bash]
+----
+cp -i inventory.example inventory
+vi inventory
+----
+
+. Review and update the inventory configuration with your specific environment details, including the following variables:
+.. All RHEL 9 host occurrences from `ec2-54-147-26-173.compute-1.amazonaws.com` to your FQDN host.
+.. All `_admin_password` or `_pg_password` values. Change the word `changeme` to match your passwords.
+
++
+[source,bash]
+----
+# This is our {AutomationDashboardName} reporter front-end application
+[automationreporter]
+ec2-54-147-26-173.compute-1.amazonaws.com ansible_connection=local
+
+# These are any required vars for the installation and shouldn't be removed
+[automationreporter:vars]
+aap_auth_provider_name=AAP24-example.com-8443
+aap_auth_provider_protocol=https
+
+# aap_auth_provider_url depends on AAP version:
+#   AAP 2.4 (controller API): DNS_OR_IP/api
+#   AAP 2.5 (gateway API): DNS_OR_IP
+aap_auth_provider_url=aap24.example.com:8443/api
+
+# aap_auth_provider_user_data_endpoint depends on AAP version:
+#   AAP 2.4 (controller API): /v2/me/
+#   AAP 2.5 (gateway API): /api/gateway/v1/me/
+aap_auth_provider_user_data_endpoint=/v2/me/
+
+aap_auth_provider_user_data_endpoint=/v2/me/
+aap_auth_provider_check_ssl=false
+aap_auth_provider_client_id=changeme
+aap_auth_provider_client_secret=changeme
+initial_sync_days=1
+
+# This is for our Postgresql database, by default hosted on the same reporter host
+[database]
+ec2-54-147-26-173.compute-1.amazonaws.com ansible_connection=local
+
+# Mandatory vars needed for the installation - modify values to match your environment
+[all:vars]
+postgresql_admin_username=postgres
+postgresql_admin_password=changeme
+
+# AAP Reporter - mandatory
+# --------------------------
+reporter_pg_containerized=True
+reporter_admin_password=changeme
+reporter_pg_host=ec2-54-147-26-173.compute-1.amazonaws.com
+reporter_pg_username=aapreporter
+reporter_pg_password=changeme
+reporter_pg_database=aapreports
+
+# The installation is supplied as a bundle containing the container images
+# Modify the bundle_dir if necessary to reflect your location
+bundle_install=true
+bundle_dir=/home/ec2-user/ansible-automation-reports-containerized-setup/bundle
+----
+
+. Run the installer.
++
+[source,bash]
+----
+ansible-playbook -i inventory ansible.containerized_installer.reporter_install
+----
+
+.Verification
+
+See the following example output for reference.
+
+[source,text]
+----
+PLAY RECAP *********************************************************************************************************************************************
+ec2-54-147-26-173.compute-1.amazonaws.com : ok=126  changed=51   unreachable=0    failed=0    skipped=42   rescued=0    ignored=0
+localhost              : ok=12  changed=0    unreachable=0    failed=0    skipped=9    rescued=0    ignored=0
+----
+
+.Troubleshooting
+
+* Alternative configurations are possible (for example, the database for {AutomationDashboardName} can be set on a different host). This requires additional changes to variables in the inventory file.
+* Consult the section “Inventory variables” below for available variables.