summaryrefslogtreecommitdiffstats
path: root/docs/humaninterfaces.rst
diff options
context:
space:
mode:
authorLovett, Trevor <trevor.lovett@att.com>2019-07-19 16:42:50 -0500
committerLovett, Trevor (tl2972) <tl2972@att.com>2019-07-19 16:44:07 -0500
commitc28fbafaf522ef077827ac5cf289a88cbd481c8f (patch)
tree3a2cd561bb03e830a0c8714d67b8c9747b4a0264 /docs/humaninterfaces.rst
parentbf29a4651bff59e27df10caffb14eedb0fbb3900 (diff)
[VVP] Added documentation on configuring the GUI via vvp-config.yaml
This primarily is meant to address allowing users to enable terms and conditions acceptance via the new functionality added in El Alto Issue-ID: VVP-228 Change-Id: I2b5c3680facab0652a0415eb73d9558da2ff42ca Signed-off-by: Lovett, Trevor <trevor.lovett@att.com>
Diffstat (limited to 'docs/humaninterfaces.rst')
-rw-r--r--docs/humaninterfaces.rst177
1 files changed, 177 insertions, 0 deletions
diff --git a/docs/humaninterfaces.rst b/docs/humaninterfaces.rst
index 522c713..8f8ccc3 100644
--- a/docs/humaninterfaces.rst
+++ b/docs/humaninterfaces.rst
@@ -108,3 +108,180 @@ Running Validations
7. If you have questions about report output, please refer to the
:ref:`Validation Report reference material <vvp-report>` for more
information.
+
+Customizing the GUI
+-------------------
+
+The VVP GUI offers an ONAP Operator a number of ways to configure the GUI text
+and behavior via a configuration file called ``vvp-config.yaml`` located in
+the ``ice_validator`` directory. Customizing the GUI would require packaging
+the VVP GUI with a modified configuration file.
+
+
+Basic Customizations
+~~~~~~~~~~~~~~~~~~~~
+
+This section will cover what the standard configurations that can tweak the
+display and options displayed in the default GUI.
+
+Here is a sample of the current configuration file. Please note that some of
+these settings may not be used in the default ONAP configuration.
+
+.. code-block:: yaml
+
+ namespace: org.onap.vvp
+ owner: ONAP
+ ui:
+ app-name: VNF Validation Tool
+ disclaimer-text: This is a legal disclaimer in the footer
+ requirement-link-text: ONAP VNF Heat Requirements (master)
+ requirement-link-url: https://onap.readthedocs.io/en/latest/submodules/vnfrqts/requirements.git/docs/Chapter5/Heat/index.html
+ categories:
+ - name: Environment File Compliance. (Required to Onboard)
+ category: environment_file
+ description:
+ Checks certain parameters are excluded from the .env file, per HOT Requirements.
+ Required for ASDC onboarding, not needed for manual Openstack testing.
+ - name: OpenStack Heat Testing (Beta)
+ category: openstack
+ description:
+ Uses the latest OpenStack Heat community version available to validate that
+ a heat template is valid OpenStack Heat. This testing is equivalent to using
+ heat template-validate from the command line.
+ settings:
+ polling-freqency: 1000
+ default-verbosity: Standard
+
+
+*Available Configuration Settings*
+
+* ``namespace`` (**required**)
+ * **Use**: Users prior selections in the GUI are saved in an
+ OS-specific application directory for per user settings. This namespace
+ is used to segregate these cached settings from other versions of the
+ validation tool
+ * **When to Modify**: If you are packaging a new version of the application,
+ then this field should be changed to ensure a user running the standard
+ ONAP version **and** your custom version do not encounter conflicts in
+ saved settings.
+
+* ``owner`` (**required**)
+
+ * **Use**: Similar to ``namespace`` this is used to segregate the cached
+ application setting selections.
+ * **When to Modify**: If you are packaging a new version of the application,
+ then this field should be changed to ensure a user running the standard
+ ONAP version **and** your custom version do not encounter conflicts in
+ saved settings.
+
+* ``ui.app-name``: (**optional** - Default is VNF Validation Tool)
+
+ * **Use**: Controls the name of the application displayed in the title bar
+ * **When to Modify**: When you want the application to display a different
+ name. Please note that the version is displayed from the ``version.py``
+ file and will be displayed in the title bar regardless of this fields
+ setting.
+
+* ``ui.disclaimer-text``: (**optional** - no disclaimer footer if omitted)
+
+ * **Use**: If present the text will be displayed as a message in the footer
+ of the application. At some point this text may also be included on the
+ footer of the reports as well.
+ * **When to Modify**: Provide this if you need to provide any persistent
+ messaging to your users such as a legal disclaimer (not currently used
+ by ONAP)
+
+* ``ui.requirement-text``: (**optional** - no requirement link in footer if omitted)
+
+ * **Use**: If present this will describe the requirements that are validated
+ by the validation tool prepended by the word "Validating:". Example:
+ Validating: ONAP VNF Provider Heat Requirements (master)
+ * **When to Modify**: If you have modified or extended the tests and you
+ want the GUI to reference a different document than the ONAP requirements.
+ Alternatively you can remove the setting and not show link to the
+ requirements in the footer.
+
+* ``ui.requirement-url``: (**optional** - no requirement link in footer if omitted)
+
+ * **Use**: If present this will be the link to the requirement text. It should
+ be a full URL with protocol (ex: http://url.com ).
+ * **When to Modify**: If you have modified or extended the tests and you want
+ the GUI to reference a different document than the ONAP requirements.
+ Alternatively you can remove the setting and not show link to the requirements
+ in the footer.
+
+* ``categories``: (**optional**)
+
+ * **Use**: This section allows operators to customize the validation categories
+ that can be selected by the end users. Individual tests can be decorated
+ with the ``category`` decorator to mark them as distinct categories of tests.
+ These tests will **not** be executed unless they are specifically requested
+ using the ``--category`` command line option.
+
+ * **When to Modify**: If you have packaged additional test cases under the
+ ``ice_validator/tests`` directory with ``category`` decorators, then you
+ can define them in this section to make them accessible via the GUI.
+
+ * **Fields**:
+
+ * ``name``: Descriptive name to display to the user
+ * ``category``: Name used in the ``category`` decorator
+ * ``description``: Additional help text that will displayed upon
+ hovering over the label in the GUI
+
+* ``settings.polling-frequency``: (**optional** - default is 1 second)
+
+ * **Use**: The validations are run in a separate process. This setting defines
+ how frequently (in milliseconds) the GUI is updated from the background process.
+ * **When to Modify**: It's unlikely this would need to be modified, but this
+ could be tweaked to change the frequency of update if there are performance or
+ latency concerns
+
+* ``settings.default-verbosity``: (**optional** - default is Standard)
+
+ * **Use**: Controls the default level of verbosity in the pytest output.
+ * **When to Modify**: Change this if you want to increase or decrease the
+ default level of verbosity. Please note that once the user changes this
+ setting, then the GUI will use the users last selection over this value.
+ * **Available Value**:
+
+ * ``Less`` - corresponds to pytest's non verbose option
+ * ``Standard`` - corresponds to pytest's ``-v`` option
+ * ``More`` - corresponds to pytest's ``-vv`` option
+
+
+Enabling Terms and Conditions Acceptance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There may be scenarios where an ONAP Operator wishes to gather end user
+approval or consent to specific terms prior to allowing the end user to
+use the validation tool. This could be in the form of an End User License
+Agreement, Terms and Conditions, or some other artifact.
+
+This is also enabled through the ``vvp-config.yaml``. This is configured
+by defining a ``terms`` section in the file as follows:
+
+.. code-block:: yaml
+
+ terms:
+ version: <version of terms being accepted>
+ path: <relative path or url to the terms>
+ popup-link-text: <message for link to terms>
+ popup-msg-text: <message in the main body of the pop-up>
+ popup-title: <text displayed in the title bar of pop-up dialog>
+
+When this is enabled, a pop-up will be displayed blocking the users progress
+until the terms are reviewed (link clicked), and either accepted or declined.
+
+If the user accepts, then their acceptance of **version** of the terms
+will be recorded and they will not need to re-accept unless the version is
+changed.
+
+If the user declines, then the validation tool will immediately exit.
+
+.. image:: vvp-with-terms.png
+
+The actual terms and conditions will be opened in the user's default browser.
+The path can be a local file path or an HTTP URL. If you wish for the content
+to be rendered in the browser, then it is recommended that the content be
+stored as HTML.