summaryrefslogtreecommitdiffstats
path: root/docs/files/pm-validation.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/files/pm-validation.rst')
-rw-r--r--docs/files/pm-validation.rst202
1 files changed, 202 insertions, 0 deletions
diff --git a/docs/files/pm-validation.rst b/docs/files/pm-validation.rst
new file mode 100644
index 0000000..5a593af
--- /dev/null
+++ b/docs/files/pm-validation.rst
@@ -0,0 +1,202 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 Nokia
+
+.. _pm-validation:
+
+VNFSDK PM Dictionary Validation User Guide
+==========================================
+
+Library was created to validate PM Dictionary YAML files which are used in a xNF ETSI NFV onboarding packages - CSAR files.
+
+Basic information
+------------------
+
+The PM Dictionary validation library has two versions:
+
+- validation-pmdictionary-<version>.jar contains PM Dictionary YAML validation logic which can be used by any ONAP component. Currently it is used by VNFSDK and SDC.
+
+- validation-pmdictionary-<version>-standalone.jar contains PM Dictionary YAML validation logic which can be run from command line.
+
+Release Note
+------------
+
+The standalone version of PM Dictionary validation library is available from Honolulu release.
+
+How to download standalone version
+----------------------------------
+
+All available jars are available at
+::
+ https://nexus.onap.org/#nexus-search;quick~validation-pmdictionary
+
+To download a standalone version of PM Dictionary validation library you need to prepare a link for selected version of file or
+manually download the file from Nexus (Viewing Repository: Releases).
+
+Template
+::
+ wget -O validation-pmdictionary-<VERSION>-standalone.jar https://nexus.onap.org/service/local/artifact/maven/redirect?r=releases&g=org.onap.vnfsdk.validation&a=validation-pmdictionary&v=<VERSION>&e=jar&c=standalone
+
+For example link for version 1.2.16 looks like
+::
+ wget -O validation-pmdictionary-1.2.16-standalone.jar https://nexus.onap.org/service/local/artifact/maven/redirect?r=releases&g=org.onap.vnfsdk.validation&a=validation-pmdictionary&v=1.2.16&e=jar&c=standalone
+
+Application return codes
+------------------------
+
+=========== ===========
+Return code Description
+=========== ===========
+0 No errors, validation passed
+1 Validation fails
+2 Internal application error
+=========== ===========
+
+Application outputs
+-------------------
+
+================ ===========
+Output Description
+================ ===========
+Console All information's about operation progress, result and errors are logged at user console.
+Log file Application creates a log file where all information's generated by application are logged.
+Result json file Validation result is also available in the file with postfix '-validation-results.json'. The File is stored in a folder with input PM dictionary file.
+================ ===========
+
+How to run application?
+-----------------------
+
+1. Install Java 11 JRE
+2. Download standalone version of PM Dictionary YAML validation application
+
+For example
+::
+ wget -O validation-pmdictionary-1.2.16-standalone.jar https://nexus.onap.org/service/local/artifact/maven/redirect?r=snapshots&g=org.onap.vnfsdk.validation&a=validation-pmdictionary&v=1.2.16&e=jar&c=standalone
+
+3. Go to folder with downloaded application and run it
+::
+ java -jar validation-pmdictionary-1.2.16-standalone.jar <path to pm_dictionary_file.yaml>
+
+Examples
+--------
+
+1. Successful validation
+::
+ ❯ java -jar validation-pmdictionary-1.2.16-standalone.jar /home/username/yaml_schema/Simple_Valid_Schema.yaml
+
+ # Executing a 'Validate PM Dictionary yaml' operation ...
+ # ... Done.
+
+ # Operation result:
+
+ {
+ "file": "/home/username/yaml_schema/Simple_Valid_Schema.yaml",
+ "status": "PASS",
+ "errors": []
+ }
+
+ # Result was stored in a file: '/home/username/yaml_schema/Simple_Valid_Schema-validation-results.json'
+
+ # Application exits successfully.
+
+ ❯ echo $?
+ 0
+
+ ❯ cat Simple_Valid_Schema-validation-results.json
+
+ {
+ "file": "/home/username/yaml_schema/Simple_Valid_Schema.yaml",
+ "status": "PASS",
+ "errors": []
+ }
+
+
+2. Failing validation
+::
+ ❯ java -jar validation-pmdictionary-1.2.16-standalone.jar /home/username/yaml_schema/PM_Dictionary.yaml
+
+ # Executing a 'Validate PM Dictionary yaml' operation ...
+ # ... Done.
+
+ # Operation result:
+
+ {
+ "file": "/home/username/yaml_schema/PM_Dictionary.yaml",
+ "status": "FAILED",
+ "errors": [
+ {
+ "yamlDocumentNumber": 1,
+ "path": "/pmMetaData/pmFields/measResultType",
+ "message": "Value(s) is/are not in array of accepted values.\n value(s): integer\n accepted value(s): [float, uint32, uint64]"
+ },
+ {
+ "yamlDocumentNumber": 1,
+ "path": "/pmMetaData/pmFields/",
+ "message": "Key not found: measChangeType"
+ },
+ {
+ "yamlDocumentNumber": 2,
+ "path": "/pmMetaData/pmFields/",
+ "message": "Key not found: measChangeType"
+ },
+ {
+ "yamlDocumentNumber": 3,
+ "path": "/pmMetaData/pmFields/measAdditionalFields/vendorField1",
+ "message": "Value(s) is/are not in array of accepted values.\n value(s): [Z, A]\n accepted value(s): [X, Y, Z]"
+ }
+ ]
+ }
+
+ # Result was stored in a file: '/home/username/yaml_schema/PM_Dictionary-validation-results.json'
+
+ # Application exits successfully.
+
+ ❯ echo $?
+ 1
+
+ ❯ cat /home/username/yaml_schema/PM_Dictionary-validation-results.json
+
+ {
+ "file": "/home/username/yaml_schema/PM_Dictionary.yaml",
+ "status": "FAILED",
+ "errors": [
+ {
+ "yamlDocumentNumber": 1,
+ "path": "/pmMetaData/pmFields/measResultType",
+ "message": "Value(s) is/are not in array of accepted values.\n value(s): integer\n accepted value(s): [float, uint32, uint64]"
+ },
+ {
+ "yamlDocumentNumber": 1,
+ "path": "/pmMetaData/pmFields/",
+ "message": "Key not found: measChangeType"
+ },
+ {
+ "yamlDocumentNumber": 2,
+ "path": "/pmMetaData/pmFields/",
+ "message": "Key not found: measChangeType"
+ },
+ {
+ "yamlDocumentNumber": 3,
+ "path": "/pmMetaData/pmFields/measAdditionalFields/vendorField1",
+ "message": "Value(s) is/are not in array of accepted values.\n value(s): [Z, A]\n accepted value(s): [X, Y, Z]"
+ }
+ ]
+ }
+
+3. Validation internal error
+::
+ ❯ java -jar validation-pmdictionary-1.2.16-standalone.jar /home/username/Not_Yaml_File.txt
+
+ # Executing a 'Validate PM Dictionary yaml' operation ...
+ # Command error:
+ Provided yaml file has invalid structure!, more information in log file.
+
+ # Application fails with internal error.
+
+ ❯ echo $?
+ 2
+
+ ❯ cat pmdictionary-validate.log
+
+ 2020-12-14 08:23:31,054 ERROR o.o.v.y.YamlLoader [main] Failed to load multi document YAML file
+ ...