From 29d9ca05e5dd72f6f6478f24a6b053d6dc43ded3 Mon Sep 17 00:00:00 2001 From: ewuerger Date: Wed, 3 Jan 2024 14:06:00 +0100 Subject: [PATCH 1/6] docs: Update documentation --- docs/source/configuration.rst | 49 ++++++++++------- docs/source/index.rst | 37 ++++++++----- docs/source/pipeline templates/gitlab.rst | 38 +++++++++++++ tests/data/model_elements/config.yaml | 66 +++++++++++------------ 4 files changed, 125 insertions(+), 65 deletions(-) create mode 100644 docs/source/pipeline templates/gitlab.rst diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 6dc13803..a4682b40 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -2,40 +2,51 @@ 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, the type in Polarion, the class type for matching objects in +capellambse, the serializer to use. 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. .. 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. +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 type that exists in all layers, links +specific to ``Class`` can be specified here to avoid duplication within the +file. + +.. _polarion-config: 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. +created via the Rest API but it will be handled as 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 0c194844..303ac391 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,20 +7,25 @@ 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 ` 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 ` on Polarion +and an according :ref:`config YAML file ` 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 @@ -28,6 +33,12 @@ execute the model-elements migration after the diagram migration. configuration +.. toctree:: + :maxdepth: 2 + :caption: CI/CD Template: + + pipeline templates/gitlab + .. toctree:: :maxdepth: 3 :caption: API reference diff --git a/docs/source/pipeline templates/gitlab.rst b/docs/source/pipeline templates/gitlab.rst new file mode 100644 index 00000000..060787de --- /dev/null +++ b/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 diff --git a/tests/data/model_elements/config.yaml b/tests/data/model_elements/config.yaml index 1bed2569..905adcbe 100644 --- a/tests/data/model_elements/config.yaml +++ b/tests/data/model_elements/config.yaml @@ -2,43 +2,43 @@ # 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 + - parent # Specify workitem links + - description_reference # Custom attribute + - Class: + - state_machines + - Diagram: + - diagram_elements + - Constraint oa: # Specify below - - OperationalCapability: # Capella Type with references - - involved_activities # Specify workitem links - - involved_entities + - 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 + - OperationalActivity # Capella Type w/o references + - OperationalEntity # Custom Type maps to Entity + - OperationalInteraction # Custom Type maps to FunctionalExchange + - CommunicationMean + - Class + - StateMachine 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: + - allocated_functions + - SystemActor: # Custom Type that doesn't exist in Capella + - allocated_functions + - SystemFunction + - ComponentExchange: + - allocated_functional_exchanges + - ComponentPort + - FunctionalExchange: + - exchanged_items + - ExchangeItem + - Class pa: - - PhysicalComponent: - - allocated_functions - - PhysicalActor: - - allocated_functions + - PhysicalComponent: + - allocated_functions + - PhysicalActor: + - allocated_functions From 446491386b8440e22857383ba4a4e1dda9b3df95 Mon Sep 17 00:00:00 2001 From: ewuerger Date: Fri, 5 Jan 2024 14:02:19 +0100 Subject: [PATCH 2/6] docs: Fix Polarion config description --- docs/source/configuration.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index a4682b40..e8f66c3f 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -28,10 +28,10 @@ file. Polarion ======== -In general, if an attribute is not configured, it will still be accepted and -created via the Rest API but it will be handled as 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 +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. From 8508bc8f5fd501ca37a21ac33c62f47ff4b5153f Mon Sep 17 00:00:00 2001 From: ewuerger Date: Thu, 11 Jan 2024 11:46:45 +0100 Subject: [PATCH 3/6] docs: Update documentation --- docs/source/configuration.rst | 33 ++++++--- tests/data/model_elements/config.yaml | 97 ++++++++++++++++++--------- 2 files changed, 91 insertions(+), 39 deletions(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index e8f66c3f..eace129f 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -8,23 +8,38 @@ YAML ==== 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, the type in Polarion, the class type for matching objects in -capellambse, the serializer to use. 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. +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 +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 type that exists in all layers, links -specific to ``Class`` can be specified here to avoid duplication within the -file. +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. -.. _polarion-config: +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 ======== diff --git a/tests/data/model_elements/config.yaml b/tests/data/model_elements/config.yaml index 905adcbe..84d40934 100644 --- a/tests/data/model_elements/config.yaml +++ b/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: + "*": # All class types + links: # Specify workitem links + - parent + - description_reference + Class: + links: - state_machines - - Diagram: + Diagram: + links: - diagram_elements - - Constraint + 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 +oa: + FunctionalExchange: + polarion_type: operationalInteraction + links: + - exchange_items + OperationalCapability: + serializer: include_pre_and_post_condition + links: + - involved_activities - involved_entities - - - OperationalActivity # Capella Type w/o references - - OperationalEntity # Custom Type maps to Entity - - OperationalInteraction # Custom Type maps to FunctionalExchange - - CommunicationMean - - Class - - StateMachine + OperationalActivity: + Entity: + polarion_type: operationalEntity + CommunicationMean: sa: - - SystemComponent: - - allocated_functions - - SystemActor: # Custom Type that doesn't exist in Capella - - allocated_functions - - SystemFunction - - ComponentExchange: + SystemComponent: + - links: + - allocated_functions + - actor: false + polarion_type: systemComponent + - actor: true + polarion_type: systemActor + SystemFunction: + ComponentExchange: + links: - allocated_functional_exchanges - - ComponentPort - - FunctionalExchange: + FunctionalExchange: + links: - exchanged_items - - ExchangeItem - - Class + 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 From bd605c349129386b6a5702117c1f4277ee7f9c82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ernst=20W=C3=BCrger?= <50786483+ewuerger@users.noreply.github.com> Date: Thu, 11 Jan 2024 17:30:41 +0100 Subject: [PATCH 4/6] docs: Update docs/source/configuration.rst Co-authored-by: micha91 --- docs/source/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index eace129f..3e5e48b7 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -45,7 +45,7 @@ Polarion ======== 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 +attribute. As we use rich text instead, 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. From 518efc936f1bd6f994db125cf555f2381f4bc7eb Mon Sep 17 00:00:00 2001 From: ewuerger Date: Thu, 11 Jan 2024 17:35:21 +0100 Subject: [PATCH 5/6] docs: Changes from code review --- docs/source/configuration.rst | 2 +- docs/source/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 3e5e48b7..f567d537 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -44,7 +44,7 @@ configure a generic config and for each specific config you can also add a Polarion ======== 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 +the Rest API will raise a 400 HTTPError since it expects a plain string attribute. As we use rich text instead, 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 303ac391..eaea7ca2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,7 +14,7 @@ Migrate any model element from a ``capellambse.MelodyModel`` to Polarion as a 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. +The SVG is attached to the respective work item. With appropriate :ref:`configuration ` on Polarion and an according :ref:`config YAML file ` for From a6bf31b346a772dc4ec16abf854933c140118a05 Mon Sep 17 00:00:00 2001 From: ewuerger Date: Thu, 11 Jan 2024 18:13:06 +0100 Subject: [PATCH 6/6] fix: Update config --- tests/data/model_elements/config.yaml | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/tests/data/model_elements/config.yaml b/tests/data/model_elements/config.yaml index 58f7fb20..012caefe 100644 --- a/tests/data/model_elements/config.yaml +++ b/tests/data/model_elements/config.yaml @@ -32,17 +32,15 @@ oa: # Specify below - involved_activities - involved_entities OperationalActivity: - Entity: - polarion_type: operationalEntity CommunicationMean: sa: SystemComponent: - links: - allocated_functions - - actor: false + - is_actor: false polarion_type: systemComponent - - actor: true + - is_actor: true polarion_type: systemActor SystemFunction: ComponentExchange: @@ -57,25 +55,25 @@ pa: PhysicalComponent: - links: - allocated_functions - - actor: false + - is_actor: false nature: UNSET polarion_type: physicalComponent - - actor: false + - is_actor: false nature: NODE polarion_type: physicalComponentNode - - actor: false + - is_actor: false nature: BEHAVIOR polarion_type: physicalComponentBehavior - - actor: true + - is_actor: true nature: NODE polarion_type: physicalActorNode - - actor: true + - is_actor: true nature: BEHAVIOR polarion_type: physicalActorBehavior la: LogicalComponent: - - actor: true + - is_actor: true polarion_type: logicalActor - - actor: false + - is_actor: false polarion_type: logicalComponent