Update doc: Using version 3 to update templates-loading.rst

Now part of the document is version 2 syntax, and part of it is version 3.
So the document needs to be updated to Syntax 3 to replace Syntax 2.

Implements: blueprint doc-upgrade
Change-Id: I2f92b6409593733f1de628f74a758160bc65efe0

doc/source/contributor/templates-loading-v2.rst

@@ -0,0 +1,199 @@
+========================
+Vitrage Template Loading
+========================
+
+Overview
+========
+
+Vitrage templates are defined in yaml with specific format_. During startup,
+templates are loaded into ``TemplateData``. After that , scenarios in loaded
+templates will be added into scenario repository.
+
+This document explains the implementation details of template data to help
+developer understand how scenario_evaluator_ works.
+
+.. _format: vitrage-templates.html
+.. _scenario_evaluator: scenario-evaluator.html
+
+Example
+=======
+
+Let's take a basic template as example
+
+.. code-block:: yaml
+
+  metadata:
+   version: 2
+   name: basic_template
+   description: basic template for general tests
+  definitions:
+   entities:
+    - entity:
+       category: ALARM
+       type: nagios
+       name: HOST_HIGH_CPU_LOAD
+       template_id: alarm
+    - entity:
+       category: RESOURCE
+       type: nova.host
+       template_id: resource
+   relationships:
+    - relationship:
+       source: alarm
+       target: resource
+       relationship_type: on
+       template_id : alarm_on_host
+  scenarios:
+   - scenario:
+      condition: alarm_on_host
+      actions:
+       - action:
+          action_type: set_state
+          properties:
+           state: SUBOPTIMAL
+          action_target:
+           target: resource
+
+``TemplateData`` will build ``entities``, ``relationships`` and most importantly
+``scenarios`` out from the definition.
+
+.. code-block:: python
+
+  expected_entities = {
+    'alarm': Vertex(vertex_id='alarm',
+                    properties={'vitrage_category': 'ALARM',
+                                'vitrage_type': 'nagios',
+                                'name': 'HOST_HIGH_CPU_LOAD',
+                                }),
+    'resource': Vertex(vertex_id='resource',
+                       properties={'vitrage_category': 'RESOURCE',
+                                   'vitrage_type': 'nova.host',
+                                   })
+  }
+
+  expected_relationships = {
+    'alarm_on_host': EdgeDescription(
+      edge=Edge(source_id='alarm',
+                target_id='resource',
+                label='on',
+                properties={'relationship_type': 'on'}),
+      source=expected_entities['alarm'],
+      target=expected_entities['resource']
+    )
+  }
+
+  expected_scenario = Scenario(
+    id='basic_template-scenario0',
+    condition=[
+      [ConditionVar(symbol_name='alarm_on_host',
+                    positive=True)]],
+    actions=[
+      ActionSpecs(
+        type='set_state',
+        targets={'target': 'resource'},
+        properties={'state': 'SUBOPTIMAL'})],
+    subgraphs=template_data.scenarios[0].subgraphs,  # ignore subgraphs
+    entities=expected_entities,
+    relationships=expected_relationships
+  )
+
+Entities and relationships
+==========================
+
+Entities and relationships are loaded into dicts keyed by ``template_id`` so
+that the references in scenarios can be resolved quickly.
+
+Note that entities and relationships dicts are **NOT** added to scenario
+repository. This implies the scope of ``template_id`` is restricted to one
+template file. It is **NOT** global.
+
+It is considered invalid to have duplicated ``template_id`` in one template, but
+it is possible that two or more entities have exactly the same properties except
+``template_id``. There is an example in
+``vitrage/tests/resources/templates/evaluator/high_availability.yaml``:
+
+.. code:: yaml
+
+  - entity:
+     category: RESOURCE
+     type: nova.instance
+     template_id: instance1
+  - entity:
+     category: RESOURCE
+     type: nova.instance
+     template_id: instance2
+
+It is used to model scenario contains two or more entities of same type, such
+as high availability condition.
+
+Scenarios
+=========
+
+``Scenario`` class holds the following properties:
+
+* id
+* version
+* condition
+* actions
+* subgraphs
+* entities
+* relationships
+* enabled
+
+
+id
+--
+
+Formatted from template name and scenario index
+
+condition
+---------
+
+Condition strings in template are expressions composed of template id and
+operators. As explained in embedded comment:
+
+    The condition string will be converted here into DNF (Disjunctive
+    Normal Form), e.g., (X and Y) or (X and Z) or (X and V and not W)...
+    where X, Y, Z, V, W are either entities or relationships
+    more details: https://en.wikipedia.org/wiki/Disjunctive_normal_form
+
+    The condition variable lists is then extracted from the DNF object. It
+    is a list of lists. Each inner list represents an AND expression
+    compound condition variables. The outer list presents the OR expression
+
+        [[and_var1, and_var2, ...], or_list_2, ...]
+
+    :param condition_str: the string as it written in the template itself
+    :return: condition_vars_lists
+
+actions
+-------
+
+``actions`` is a list of ``ActionSpecs``.
+
+The action targets in the spec must be referenced in the condition definition.
+They are either linked to ``vertex_id`` of entity condition variables or
+``source_id`` and ``target_id`` in relationship condition variable extracted.
+
+In each matched subgraph in the entity graph, the targets will be resolved as
+concrete vertices or edges.
+
+subgraphs
+---------
+
+Sub graphs are built from conditions for pattern matching in the entity graph.
+Each sub-list in condition variables list is compiled into one sub graph. The
+actions will be triggered if any of the subgraph is matched.
+
+entities & relationships
+------------------------
+
+Dicts of **touched** entities and relationships during subgraph building are
+saved in scenario.
+
+This makes creation of the scenarios repository index on related entities and
+relationships easier and more efficient. You don't need to traverse the
+condition object again, which is already done once during subgraphs building.
+It also eliminate the necessity of duplication check because there is no
+duplicate entities or relationships in these dicts compared to the condition
+variables lists.

doc/source/contributor/templates-loading.rst

@@ -12,8 +12,15 @@ templates will be added into scenario repository.
 This document explains the implementation details of template data to help
 developer understand how scenario_evaluator_ works.
 
+*Note:* This document refers to Vitrage templates version 3.
+
+For previous versions, see:
+
+Version_2_
+
 .. _format: vitrage-templates.html
 .. _scenario_evaluator: scenario-evaluator.html
+.. _Version_2: https://docs.openstack.org/vitrage/latest/contributor/templates-loading-v2.html
 
 Example
 =======
@@ -23,39 +30,27 @@ Let's take a basic template as example
 .. code-block:: yaml
 
     metadata:
-   version: 2
+     version: 3
      name: basic_template
      description: basic template for general tests
-  definitions:
     entities:
-    - entity:
+      alarm:
         category: ALARM
         type: nagios
         name: HOST_HIGH_CPU_LOAD
-       template_id: alarm
+      host:
-    - entity:
         category: RESOURCE
         type: nova.host
-       template_id: resource
-   relationships:
-    - relationship:
-       source: alarm
-       target: resource
-       relationship_type: on
-       template_id : alarm_on_host
     scenarios:
-   - scenario:
+     - condition: alarm [on] host
-      condition: alarm_on_host
        actions:
-       - action:
+         - set_state:
-          action_type: set_state
-          properties:
             state: SUBOPTIMAL
-          action_target:
+            target: host
-           target: resource
 
-``TemplateData`` will build ``entities``, ``relationships`` and most importantly
+``TemplateData`` will build ``entities``, ``relationships`` and most importantly``scenarios``.
-``scenarios`` out from the definition.
+*Note:* In the third version of the template syntax, ``relationships`` is no longer defined separately in advance, but
+used directly defined in the condition in the ``scenarios``.
 
 .. code-block:: python
 
@@ -72,7 +67,7 @@ Let's take a basic template as example
   }
 
   expected_relationships = {
-    'alarm_on_host': EdgeDescription(
+    'alarm__on__host': EdgeDescription(
       edge=Edge(source_id='alarm',
                 target_id='resource',
                 label='on',
@@ -100,28 +95,31 @@ Let's take a basic template as example
 Entities and relationships
 ==========================
 
-Entities and relationships are loaded into dicts keyed by ``template_id`` so
+Entities describes the resources and alarms which are defined by the entities
+part in the template.
+
+Scenario contains condition and actions, relationships are represented inline
+in the condition, example usage condition: alarm [ on ] host.
+
+Entities and relationships are loaded into dicts keyed by ``entity key`` so
 that the references in scenarios can be resolved quickly.
 
 Note that entities and relationships dicts are **NOT** added to scenario
-repository. This implies the scope of ``template_id`` is restricted to one
+repository. This implies the scope of `` entity key`` is restricted to one
 template file. It is **NOT** global.
 
-It is considered invalid to have duplicated ``template_id`` in one template, but
+It is considered invalid to have duplicated ``entity key`` in one template, but
 it is possible that two or more entities have exactly the same properties except
-``template_id``. There is an example in
+``entity key``. There is an example in:
-``vitrage/tests/templates/evaluator/high_availability.yaml``:
 
 .. code:: yaml
 
-  - entity:
+  - instance1:
      category: RESOURCE
      type: nova.instance
-     template_id: instance1
+  - instance2:
-  - entity:
      category: RESOURCE
      type: nova.instance
-     template_id: instance2
 
 It is used to model scenario contains two or more entities of same type, such
 as high availability condition.
@@ -149,7 +147,7 @@ Formatted from template name and scenario index
 condition
 ---------
 
-Condition strings in template are expressions composed of template id and
+Condition strings in template are expressions composed of entity key and
 operators. As explained in embedded comment:
 
     The condition string will be converted here into DNF (Disjunctive

doc/source/index.rst

@@ -101,6 +101,7 @@ Design Documents
    contributor/not_operator_support
    contributor/not_operator_support_v2
    contributor/templates-loading
+   contributor/templates-loading-v2
    contributor/vitrage-ha-and-history-vision
    contributor/datasource-snmp-parsing-support
    contributor/entity_equivalence_use_cases