docs/modelingconcepts/artifact-type.rst

   1 .. This work is a derivative of https://wiki.onap.org/display/DW/Modeling+Concepts#Concepts-1386016968
   2 .. This work is licensed under a Creative Commons Attribution 4.0
   3 .. International License. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright (C) 2020 Deutsche Telekom AG.
   5
   6 .. _artifact_type:
   7
   8 Artifact Type
   9 -------------
  10
  11 Represents the **type of a artifact**, used to **identify** the
  12 **implementation** of the functionality supporting this type of artifact.
  13
  14 `TOSCA definition <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.2/csd01/TOSCA-Simple-Profile-YAML-v1.2-csd01.html#_Toc494454213>`_
  15
  16 This node was created, derived from ``tosca.artifacts.Root`` to be the root TOSCA node for all artifact.
  17
  18 .. code-block:: json
  19    :caption: **tosca.artifacts.Implementation**
  20
  21    {
  22      "description": "TOSCA base type for implementation artifacts",
  23      "version": "1.0.0",
  24      "derived_from": "tosca.artifacts.Root"
  25    }
  26
  27 **Bellow is a list of supported artifact types**
  28
  29 .. tabs::
  30
  31    .. tab:: Velocity
  32
  33       **artifact-template-velocity**
  34
  35       Represents an Apache Velocity template.
  36
  37       Apache Velocity allow to insert **logic** (if / else / loops / etc) when processing the output of a template/text.
  38
  39       File must have **.vtl** extension.
  40
  41       The **template** can represent anything, such as device config, payload to interact with 3rd party systems,
  42       resource-accumulator template, etc...
  43
  44       Often a template will be **parameterized**, and each **parameter**
  45       must be defined within an mapping file (see 'Mapping' in this tab).
  46
  47       `Velocity reference document <http://velocity.apache.org/engine/1.7/user-guide.html>`_
  48
  49       `Velocity artifact <https://github.com/onap/ccsdk-cds/blob/master/components/model-catalog/definition-type/starter-type/artifact_type/artifact-template-velocity.json>`_
  50       is the TOSCA artifact type:
  51
  52       .. code-block:: json
  53          :caption: **artifact-template-velocity**
  54
  55          {
  56            "description": "TOSCA base type for implementation artifacts",
  57            "version": "1.0.0",
  58            "derived_from": "tosca.artifacts.Root"
  59          }
  60
  61    .. tab:: Jinja
  62
  63       **artifact-template-jinja**
  64
  65       Represents an Jinja template.
  66
  67       Jinja template allow to insert **logic** (if / else / loops / etc) when processing the output of a template/text.
  68
  69       File must have **.jinja** extension.
  70
  71       The **template** can represent **anything**, such as device config,
  72       payload to interact with 3rd party systems, resource-accumulator template, etc...
  73
  74       Often a template will be parameterized, and each parameter must be defined within an mapping file.
  75
  76       `Jinja reference document <https://jinja.palletsprojects.com/en/2.10.x/>`_
  77
  78       `Jinja artifact <https://github.com/onap/ccsdk-cds/blob/master/components/model-catalog/definition-type/starter-type/artifact_type/artifact-template-jinja.json>`_
  79       is the TOSCA artifact type:
  80
  81       .. code-block:: json
  82          :caption: **artifact-template-jinja**
  83
  84          {
  85            "description": " Jinja Template used for Configuration",
  86            "version": "1.0.0",
  87            "file_ext": [
  88              "jinja"
  89            ],
  90            "derived_from": "tosca.artifacts.Implementation"
  91          }
  92
  93    .. tab:: Mapping
  94
  95       **artifact-mapping-resource**
  96
  97       This type is meant to represent **mapping** files defining the **contract of each resource** to be resolved.
  98
  99       Each **parameter** in a template **must** have a corresponding mapping definition,
 100       modeled using datatype-resource-assignment (see :ref:`data_type`-> resources-asignment).
 101
 102       Hence the mapping file is meant to be a list of entries defined using datatype-resource-assignment
 103       (see :ref:`data_type`-> resources-asignment).
 104
 105       File must have **.json** extension.
 106
 107       The **template** can represent **anything**, such as device config,
 108       payload to interact with 3rd party systems, resource-accumulator template, etc...
 109
 110       `Mapping artifact <https://github.com/onap/ccsdk-cds/blob/master/components/model-catalog/definition-type/starter-type/artifact_type/artifact-mapping-resource.json>`_
 111       is the TOSCA artifact type:
 112
 113       .. code-block:: json
 114          :caption: **artifact-mapping-resource**
 115
 116          {
 117            "description": "Resource Mapping File used along with Configuration template",
 118            "version": "1.0.0",
 119            "file_ext": [
 120              "json"
 121            ],
 122            "derived_from": "tosca.artifacts.Implementation"
 123          }
 124
 125       The mapping file basically contains a reference to the data dictionary to use
 126       to resolve a particular resource.
 127
 128       The data dictionary defines the HOW and the mapping defines the WHAT.
 129
 130       **Relation between data dictionary, mapping and template.**
 131
 132       Below are two examples using color coding to help understand the relationships.
 133
 134       In orange is the information regarding the template. As mentioned before,
 135       template is part of the blueprint itself, and for the blueprint to know what template to use,
 136       the name has to match.
 137
 138       In green is the relationship between the value resolved within the template,
 139       and how it's mapped coming from the blueprint.
 140
 141       In blue is the relationship between a resource mapping to a data dictionary.
 142
 143       In red is the relationship between the resource name to be resolved and the HEAT environment variables.
 144
 145       The key takeaway here is that whatever the value is for each color, it has to match all across.
 146       This means both right and left hand side are equivalent; it's all on the designer to express
 147       the modeling for the service. That said, best practice is example 1.
 148
 149       .. image:: ../media/dd_mapping_template_rel.jpg
 150          :width: 500pt
 151          :align: center
 152
 153    .. tab:: Directed Graph
 154
 155       **artifact-directed-graph**
 156
 157       Represents a directed graph.
 158
 159       This is to represent a **workflow**.
 160
 161       File must have **.xml** extension.
 162
 163       Here is the list of executors currently supported (see here for explanation and full potential list:
 164       `Service Logic Interpreter Nodes <https://wiki.onap.org/display/DW/Service+Logic+Interpreter+Nodes>`_
 165
 166       * execute
 167       * block
 168       * return
 169       * break
 170       * exit
 171
 172       `Here <https://github.com/onap/ccsdk-cds/blob/master/components/model-catalog/definition-type/starter-type/artifact_type/artifact-directed-graph.json>`_
 173       is the TOSCA artifact type:
 174
 175       .. code-block:: json
 176          :caption: **artifact-directed-graph**
 177
 178          {
 179            "description": "Directed Graph File",
 180            "version": "1.0.0",
 181            "file_ext": [
 182              "json",
 183              "xml"
 184            ],
 185            "derived_from": "tosca.artifacts.Implementation"
 186          }