docs/sections/services/ves-openapi-manager/use-cases.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 .. _ves-openapi-manager-use-cases:
   5
   6 VES OpenAPI Manager validation use-cases
   7 ========================================
   8 The main VES OpenAPI Manager use case is to verify if the schemaReferences declared in *VES_EVENT* type artifacts are
   9 present in the local DCAE run-time externalSchemaRepo and show validation results to user in SDC UI.
  10
  11 The general flow of VES OpenAPI Manager is available here :ref:`ves-openapi-manager-flow`.
  12
  13 Based on the referenced flow, there are few possible behaviours of VES OpenAPI Manager. In this section two main flows:
  14 successful and unsuccessful validation will be described step by step.
  15
  16 Validation prerequisites
  17 ------------------------
  18 Validation phase takes place only when specific conditions are met.
  19
  20 1) VES OpenAPI Manager is properly configured: client is connected to SDC and mapping file is present and pointed in configuration. Configuration is described in detail here: :ref:`ves-openapi-manager-deployment`.
  21 2) Distribution of a Service Model takes place in SDC.
  22 3) Service contains an *VES_EVENT* type artifact.
  23 4) Artifact content is correctly downloaded.
  24
  25 Validation description
  26 ----------------------
  27 When *schemaReference* field from artifact is being validated, only the part of the URI that indicates public openAPI
  28 description file location is taken into consideration.
  29
  30 For example when *schemaReference* with value
  31 *https://forge.3gpp.org/rep/sa5/MnS/blob/SA88-Rel16/OpenAPI/faultMnS.yaml#/components/schemas/NotifyNewAlarm*
  32 is found in artifact, then only the part before # sign (public openAPI description file location URI part) is being
  33 validated. This way part which would be validated is
  34 *https://forge.3gpp.org/rep/sa5/MnS/blob/SA88-Rel16/OpenAPI/faultMnS.yaml*.
  35
  36 Mapping file must have a predefined JSON format of list of objects (mappings) with publicURL and localURL fields.
  37 Example with 3 mappings:
  38
  39 .. literalinclude:: resources/schema-map-example.json
  40     :language: json
  41
  42 When *schemaReference* is split, it's compared to each publicURL from mapping file. If there is no publicURL in mapping
  43 file which matches schemaReference, then schemaReference is marked as invalid. This process is executed for all
  44 stndDefined events defined in *VES_EVENT* artifact, which declare a schemaReference. All invalid references are returned
  45 to user via SDC UI when validation of a complete artifact ends.
  46
  47 Based on returned information with invalid references user can take action and e.g. add mappings and schemas to DCAE
  48 run-time environment by editing ConfigMaps which store them.
  49
  50 +-----------------------------------------+-------------------------+
  51 | ConfigMap name                          | Content                 |
  52 +=========================================+=========================+
  53 | dcae-external-repo-configmap-schema-map | Mapping file            |
  54 +-----------------------------------------+-------------------------+
  55 | dcae-external-repo-configmap-sa88-rel16 | OpenAPI schemas content,|
  56 |                                         | example stores 3GPP     |
  57 |                                         | sa88-rel16 schemas      |
  58 +-----------------------------------------+-------------------------+
  59
  60
  61 Successful validation case
  62 --------------------------
  63 There are few ways to get a successful validation status - *DEPLOY_OK*.
  64
  65 1) When artifact *VES_EVENT* does not contain *stndDefined* events definitions. Only *stndDefined* event are validated.
  66 2) When artifact *VES_EVENT* contains *stndDefined* events definitions but *schemaReference* fields are not present.
  67 3) When artifact *VES_EVENT* contains *stndDefined* events definitions and each *schemaReference* of the event is present in the mapping file.
  68
  69
  70 *VES_EVENT* artifact may contain more than one event definition. Examples of valid artifacts with single events are
  71 below.
  72
  73 Example of valid artifact without *stndDefined* event definition (case 1):
  74
  75 .. literalinclude:: resources/artifact-no-stndDefined.yaml
  76     :language: yaml
  77
  78 Example of valid artifact with *stndDefined* event definition, but without schemaReference field (case 2):
  79
  80 .. literalinclude:: resources/artifact-stndDefined-no-schemaReference.yaml
  81     :language: yaml
  82
  83 Example of artifact with *stndDefined* event definition (case 3):
  84
  85 .. literalinclude:: resources/artifact-stndDefined.yaml
  86     :language: yaml
  87
  88 which is valid when mapping file contains a mapping of schemaReference field.
  89 Example of mapping file content which makes example artifact valid:
  90
  91 .. literalinclude:: resources/schema-map.json
  92     :language: json
  93
  94 Unsuccessful validation case
  95 ----------------------------
  96 Another case is an unsuccessful validation case which sends status *DEPLOY_ERROR* with error message containing listed
  97 *schemaReference* that are missing from mapping file. Fail case might occur:
  98
  99 1) When artifact *VES_EVENT* contains *stndDefined* events definitions and any of *schemaReference* is not present in mapping file.
 100
 101 Example of artifact with *stndDefined* event definition:
 102
 103 .. literalinclude:: resources/artifact-stndDefined.yaml
 104     :language: yaml
 105
 106 which is invalid when mapping file does not contain a mapping of schemaReference field.
 107 Example of mapping file which makes example artifact invalid:
 108
 109 .. literalinclude:: resources/schema-map-invalid.json
 110     :language: json
 111
 112 Validation results
 113 ------------------
 114 There are two ways to receive validation results.
 115
 116 1) Via SDC UI. Results are available in *Service->Distributions* view. To see results in SDC UI user has to wait up to few minutes.
 117 2) In VES OpenAPI Manager logs. They are printed right after validation.