diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 6dc13803..f567d537 100644 --- a/docs/source/configuration.rst +++ b/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 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 +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..eaea7ca2 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 is 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 0d3eaccf..012caefe 100644 --- a/tests/data/model_elements/config.yaml +++ b/tests/data/model_elements/config.yaml @@ -3,7 +3,7 @@ "*": # All layers "*": # All class types - links: + links: # Specify workitem links - parent - description_reference Class: @@ -19,6 +19,7 @@ CapabilityRealization: serializer: include_pre_and_post_condition Entity: + StateMachine: oa: # Specify below FunctionalExchange: @@ -27,8 +28,33 @@ oa: # Specify below - exchange_items OperationalCapability: serializer: include_pre_and_post_condition + links: + - involved_activities + - involved_entities + OperationalActivity: + CommunicationMean: + +sa: + SystemComponent: + - links: + - allocated_functions + - is_actor: false + polarion_type: systemComponent + - is_actor: true + polarion_type: systemActor + SystemFunction: + ComponentExchange: + links: + - allocated_functional_exchanges + FunctionalExchange: + links: + - exchanged_items + ExchangeItem: + pa: PhysicalComponent: + - links: + - allocated_functions - is_actor: false nature: UNSET polarion_type: physicalComponent @@ -44,6 +70,7 @@ pa: - is_actor: true nature: BEHAVIOR polarion_type: physicalActorBehavior + la: LogicalComponent: - is_actor: true