documenation updates

manual/configuration-general.tex

@@ -281,17 +281,17 @@ \subsection{CxAnalytix Service and CLI Execution Configuration}\label{sec:runtim
         values can be found in\\
         the \hyperref[lst:outmodules]{Available Output Modules} list.}\\
         \midrule
-        \texttt{SASTScanSummaryRecordName}\\
+        \makecell[tc]{\texttt{SASTScanSummaryRecordName}\\
         \texttt{SASTScanDetailRecordName}\\
         \texttt{SCAScanSummaryRecordName}\\
         \texttt{SCAScanDetailRecordName}\\
         \texttt{ProjectInfoRecordName}\\
-        \texttt{PolicyViolationsRecordName} & N/A & Yes & \makecell[tl]{The name of the corresponding\\
-        record collection configured\\
-        in the output.}\\
-        \midrule
-        \texttt{ScanStatisticsRecordName} & N/A & No & \makecell[tl]{The name of the record for storing\\
-        scan statistics in the output.}\\
+        \texttt{PolicyViolationsRecordName}\\
+        \texttt{ScanStatisticsRecordName}} & N/A & No & \makecell[tl]{The name of the corresponding\\
+        record collection configured in the \\
+        output. If blank or omitted,\\
+        the corresponding record type\\
+        is not output.}\\
         \bottomrule
     \end{tabularx}
 \end{table}

manual/deploymentguide.tex

@@ -46,7 +46,7 @@ \section{MongoDB Sizing}
     cluster members' hardware specifics. The machine specification will also need to account for CPU required for any indexing and data ingestion.
 \end{itemize}
 
-\subsection{Bring Your Own Indexing}
+\subsection{Bring Your Own Indexing}\label{sec:bringyourownindex}
 
 The MongoDB implementation requires that the user account configured for CxAnalytix to interact with MongoDB has read/write access to tables and 
 collections specified in the configuration.  Upon the first run, tables, collections, and some default indexes will be created.

manual/installing.tex

@@ -176,11 +176,58 @@ \section{Logging Configuration}
 \texttt{cxanalytix.log4net} file is generally located in the same directory as the \texttt{cxanalytix.config} file, and will allow for
 customizing the logging output location and verbosity.
 
+\section{MongoDB Schema Initialization}\label{sec:mongotool}
 
+Versions of CxAnalytix prior to 2.1.1 initialized the MongoDB collection schema on the first run after the MongoDB output is configured. Prior 
+versions would also create several default indexes as part of the collection schema creation. This is no longer the case.
+
+\noindent\\As of CxAnalytix 2.1.1, it is now required to execute \texttt{MongoTool} prior to the first start after initial installtion, 
+upgrades or configuration changes that would change the MongoDB collection schema.  Any indexes that were created by CxAnalytix in versions 
+prior to version 2.1.1 can be safely dropped if desired.  See Section \ref{sec:bringyourownindex} for information regarding defining indexes
+appropriate for your querying needs.
+
+\noindent\\The executable \texttt{MongoTool} command line parameters are described in Table \ref{tab:mongo_tool_opts}.  \texttt{MongoTool} can be used
+to initialize the MongoDB collection schema by a user with elevated privileges that differs from the user that CxAnalytix will use to
+write output data.  \texttt{MongoTool} can optionally define a user with appropriate minimal privileges that can be used by CxAnalytix.
+
+
+\begin{table}
+    \centering
+    \begin{tabular}{|l|l|l|l|}
+        \toprule
+        \textbf{Option} & \textbf{Required} & \textbf{Default} & \textbf{Description}\\
+        \midrule
+        \makecell[cl]{\texttt{-d}\\
+        \texttt{---debug}} & No & False & \makecell[cl]{Turns on debug logging.}\\
+        \midrule
+        \makecell[cl]{\texttt{-u}\\
+        \texttt{---url}} & No & N/A & \makecell[cl]{Specify the URL to use for the MongoDB connection. This must\\
+        be provided if the \texttt{-c} flag is not provided.  This option and the \\
+        \texttt{-c} option can not be used at the same time.}\\
+        \midrule
+        \makecell[cl]{\texttt{-c}} & No & N/A & \makecell[cl]{Use the existing CxAnalytix configuration to connect to\\
+        MongoDB if the \texttt{-u} or \texttt{---url} option is not provided.  This option\\
+        can not be used with the \texttt{-u} or \texttt{---url} options.}\\
+        \midrule
+        \makecell[cl]{\texttt{-l}\\
+        \texttt{---login-db}} & No & "admin" & \makecell[cl]{The MongoDB database used for login.}\\
+        \midrule
+        \makecell[cl]{\texttt{---mongo-user}} & No & null & \makecell[cl]{If provided, the name of the MongoDB user to\\
+        create and assign to the CxAnalytix database\\
+        with minimal privileges.}\\
+        \midrule
+        \makecell[cl]{\texttt{---mongo-password}} & No & null & \makecell[cl]{The password to set for the user name defined with\\
+        the option \texttt{---mongo-user}.}\\
+        \bottomrule
+    \end{tabular}
+    \caption{MongoTool Command Line Options}
+    \label{tab:mongo_tool_opts}
+\end{table}
 
-\section{Upgrading}
 
 
+\section{Upgrading}
+
 Configuration elements found in \texttt{cxanalytix.config} are generally backwards compatible for versions
 of CxAnalytix with the same major version\footnote{The major version is the first 
 number in the version stamp.  e.g. v2.0.0 has a major version of 2.}.  New features may require additions
@@ -193,5 +240,10 @@ \section{Upgrading}
 
 
 \noindent\\Note that if installing from the CxAnalytix zip binary that there is a default version of \texttt{cxanalytix.config}
-and \texttt{cxanalytix.log4net} in the zip binary.  These default configuration files can safely be removed upon
-upgrading the CxAnalytix binaries.
+and \texttt{cxanalytix.log4net} in the zip binary.  These default configuration files are provided for first time installers to
+use to get CxAnalytix running for the first time.  These files should be removed upon upgrading the CxAnalytix binaries.  If
+CxAnalytix fails to start properly after upgrade, the example files may be loaded first according to the rules described in
+Chapter \ref{chap:installation}: \textit{Configuration File Path Resolution}.
+
+\noindent\\If your output is MongoDB and the upgrade will change the collection schema, you should run \texttt{MongoTool} as
+described in Section \ref{sec:mongotool}