Updated the documentation

docs/source/configuration.rst

@@ -2,40 +2,66 @@
    Copyright DB InfraGO AG and contributors
    SPDX-License-Identifier: Apache-2.0
 
-.. _config:
+.. _capella2polarion-config:
 
 YAML
 ====
-To control the migration of model elements, you can use the following YAML
-file. In this file, you can specify the layer and class type for matching
-objects. If an item is a dictionary, it means there are work item links to be
-migrated. Make sure to use the attribute names on the capellambse object
-correctly.
+To control the migration of model elements, the following YAML file serves as a
+configuration for the capella2polarion service. In this file, you can specify
+the layer, class types and attributes for matching Capella model elements.
+Additionally you have the control of adding relationships with the links key.
+Underneath the links key use attributes on the matched capellambse model
+object. Make sure that the attribute name is correct, you can use
+`capellambse's documentation`__ for that.
+
+__ https://dsd-dbs.github.io/py-capellambse/code/capellambse.model.layers.html
 
 .. literalinclude:: ../../tests/data/model_elements/config.yaml
    :language: yaml
    :lines: 4-
 
-The first section is a general configuration where you can set links to be
-migrated for all class types. For example, ``parent`` and ``description_reference``
-are links that will be applied to all specified class types. Since ``Class`` is a
-common class type that exists in all layers, links specific to ``Class`` can be
-specified here to avoid duplication.
+The "star" section is a general configuration where you can set links to be
+migrated for all class types. For example, ``parent`` and
+``description_reference`` are links that will be applied to all specified class
+types. Since ``Class`` is a common class type that exists in all layers, links
+specific to ``Class`` can be specified here to avoid duplication. This will be
+merged into layer specific configuration for ``Class`` if there is any.
+
+With ``serializer`` you can control which function is called to render the
+:py:class:`capella2polarion.data_models.CapellaWorkItem`. There is a generic
+serializer including title (name), description and requirement types, taken per
+default.
+
+Sometimes capellambse class types are not the same in Polarion. In order to
+handle this case you can use the ``polarion_type`` key to map capellambse types
+to the desired Polarion type. For the ``PhysicalComponent`` you can see this in
+action, where based on the different permutation of the attributes actor and
+nature different Polarion types are used. In capellambse however this is just a
+``PhysicalComponent``. Combining this with ``links`` is possible too. You can
+configure a generic config and for each specific config you can also add a
+``links`` section. Both will be merged.
 
 Polarion
 ========
-In general, if an attribute is not configured, it will still be accepted and
-created via the Rest API. However, to be able to make ``GET`` requests, you
-need to configure your Polarion project correctly. The matching of diagrams and
-model elements is done using the ``uuid_capella`` attribute, which needs to be
-declared in the ``Custom Fields`` section. Simply choose ``All Types`` for this
-attribute.
+In general, if an attribute is not configured, it will not be accepted and the
+the Rest API will raise a 404 HTTPError since it expects a plain string
+attribute. However, to be able to make ``GET`` requests, you need to configure
+your Polarion project correctly. For that there is the `Polarion DBS Project
+Template`_ which includes icon, custom field and enumeration configuration for
+a pleasant capella2polarion synchronization.
+
+.. _Polarion DBS Project Template: https://github.com/DSD-DBS/capella-polarion-template#polarion-dbs-project-template
+
+In the following are some requirements for the configuration if you don't want
+to use the Project Template:
+
+The matching of diagrams and model elements is done using the ``uuid_capella``
+attribute, which needs to be declared in the ``Custom Fields`` section. Simply
+choose ``All Types`` for this attribute.
 
 To have icons for your model elements, you need to declare the work item type
-in the ``workitem-type-enum.xml`` file in the Polarion administration panel.
-This file is an enumeration file where the work item type IDs should follow the
-camel case pattern (e.g., ``operationalCapability`` for
-``OperationalCapability``).
+in the ``workitem-type-enum.xml`` file in the Polarion administration panel and
+upload a 16x16 picture file.
 
 To generate clickable linked work items, you need to configure the link role
 enumerations in the ``workitem-link-role-enum.xml`` file. Here, the ID should

docs/source/index.rst

@@ -7,27 +7,38 @@ capella2polarion
 
 A tool to migrate Capella content to a Polarion project as work items.
 
-Diagrams
---------
-Migrate diagrams from a diagram cache (pipeline artifact from a capella diagram
-cache) job run to Polarion as work items. The whole folder with the
-``index.json`` and the SVGs is needed.
-
-Model-Elements
---------------
+Synchronization of Model-Elements
+---------------------------------
+
 Migrate any model element from a ``capellambse.MelodyModel`` to Polarion as a
-work item. With appropriate :ref:`configuration <config>` on Polarion and an
-according config YAML file, any attribute on the capellambse object can be
-migrated as a work item link if (and only if) the target object exists as a
-work item already. In order to generate diagram references, make sure to
-execute the model-elements migration after the diagram migration.
+work item. Diagrams are taken from a diagram cache (pipeline artifact from a
+`capella diagram cache`_) job run to Polarion as work items. The whole folder
+with the ``index.json`` and the SVGs is needed for the diagram synchronization.
+The SVG and a PNG of it are attached to the respective work item.
+
+With appropriate :ref:`configuration <capella2polarion-config>` on Polarion
+and an according :ref:`config YAML file <polarion-config>` for
+capella2polarion any model element can be migrated from a Capella model to a
+Polarion project. Attributes are migrated as links and text from requirements
+and link groups are synchronized as custom fields.
+
+The synchronization works by comparing the checksum of work items. If they
+differ the old will be patched by the new one.
+
+.. _capella diagram cache: https://github.com/DSD-DBS/capella-dockerimages/blob/main/ci-templates/gitlab/diagram-cache.yml
 
 .. toctree::
    :maxdepth: 2
    :caption: Configuration:
 
    configuration
 
+.. toctree::
+   :maxdepth: 2
+   :caption: CI/CD Template:
+
+   pipeline templates/gitlab
+
 .. toctree::
    :maxdepth: 3
    :caption: API reference

docs/source/pipeline templates/gitlab.rst

@@ -0,0 +1,38 @@
+..
+   Copyright DB InfraGO AG and contributors
+   SPDX-License-Identifier: Apache-2.0
+
+GitLab CI/CD pipeline Template
+------------------------------
+
+The capella2polarion library can be used in a CI/CD pipeline. For that the
+following template can be used inside the `.gitlab-ci.yml` file:
+
+.. literalinclude:: ../../../ci-templates/gitlab/synchronise_elements.yml
+   :language: yaml
+   :lines: 4-
+
+A `.gitlab-ci.yml` with a capella2polarion synchronization job could look like
+this:
+
+.. code:: yaml
+
+    include:
+        - remote: https://raw.githubusercontent.com/DSD-DBS/capella-dockerimages/${CAPELLA_DOCKER_IMAGES_REVISION}/ci-templates/gitlab/diagram-cache.yml
+        - remote: https://raw.githubusercontent.com/DSD-DBS/capella-polarion/ci-templates/gitlab/synchronise_elements.yml
+
+    default:
+        tags:
+            - docker
+
+    workflow: # Control job triggering
+        rules:
+            - if: $CI_COMMIT_BRANCH == "main" # execution only on main
+
+    variables:
+        CAPELLA_VERSION: 6.1.0
+        ENTRYPOINT: model.aird
+        CAPELLA2POLARION_PROJECT_ID: syncproj
+        CAPELLA2POLARION_MODEL_JSON: '{"path": "PATH_TO_CAPELLA"}'
+        CAPELLA2POLARION_CONFIG: capella2polarion_config.yaml
+        CAPELLA2POLARION_DEBUG: 1

tests/data/model_elements/config.yaml

@@ -2,43 +2,80 @@
 # SPDX-License-Identifier: Apache-2.0
 
 "*": # All layers
-      - "*": # All class types
-              - parent # Specify workitem links
-              - description_reference # Custom attribute
-      - Class:
-              - state_machines
-      - Diagram:
-              - diagram_elements
-      - Constraint
+  "*": # All class types
+    links: # Specify workitem links
+      - parent
+      - description_reference
+  Class:
+    links:
+      - state_machines
+  Diagram:
+    links:
+      - diagram_elements
+  Constraint:
+    serializer: linked_text_as_description
+  Scenario:
+    serializer: include_pre_and_post_condition
+  CapabilityRealization:
+    serializer: include_pre_and_post_condition
+  Entity:
+  StateMachine:
 
-oa: # Specify below
-      - OperationalCapability: # Capella Type with references
-              - involved_activities # Specify workitem links
-              - involved_entities
-
-      - OperationalActivity # Capella Type w/o references
-      - OperationalEntity # Custom Type maps to Entity
-      - OperationalInteraction # Custom Type maps to FunctionalExchange
-      - CommunicationMean
-      - Class
-      - StateMachine
+oa:
+  FunctionalExchange:
+    polarion_type: operationalInteraction
+    links:
+      - exchange_items
+  OperationalCapability:
+    serializer: include_pre_and_post_condition
+    links:
+      - involved_activities
+      - involved_entities
+  OperationalActivity:
+  Entity:
+    polarion_type: operationalEntity
+  CommunicationMean:
 
 sa:
-      - SystemComponent:
-              - allocated_functions
-      - SystemActor: # Custom Type that doesn't exist in Capella
-              - allocated_functions
-      - SystemFunction
-      - ComponentExchange:
-              - allocated_functional_exchanges
-      - ComponentPort
-      - FunctionalExchange:
-              - exchanged_items
-      - ExchangeItem
-      - Class
+  SystemComponent:
+    - links:
+        - allocated_functions
+    - actor: false
+      polarion_type: systemComponent
+    - actor: true
+      polarion_type: systemActor
+  SystemFunction:
+  ComponentExchange:
+    links:
+      - allocated_functional_exchanges
+  FunctionalExchange:
+    links:
+      - exchanged_items
+  ExchangeItem:
 
 pa:
-      - PhysicalComponent:
-              - allocated_functions
-      - PhysicalActor:
-              - allocated_functions
+  PhysicalComponent:
+    - links:
+        - allocated_functions
+    - actor: false
+      nature: UNSET
+      polarion_type: physicalComponent
+    - actor: false
+      nature: NODE
+      polarion_type: physicalComponentNode
+    - actor: false
+      nature: BEHAVIOR
+      polarion_type: physicalComponentBehavior
+    - actor: true
+      nature: NODE
+      polarion_type: physicalActorNode
+    - actor: true
+      nature: BEHAVIOR
+      polarion_type: physicalActorBehavior
+
+la:
+  LogicalComponent:
+    - actor: true
+      polarion_type: logicalActor
+    - actor: false
+      polarion_type: logicalComponent