.. comment all inline tags to start with _how_dmcore_ .. _how_dmcore_top: .. index:: Domain Model; How to Map to Core Model .. index:: Mapping; How to - Domain Model to Core Model ###################################################################### How to model the mapping between the Domain and Core models of STEPLIB ###################################################################### .. include:: /pages/common/pageunderconstruction.txt :start-line: 3 .. contents:: Contents: :local: :depth: 1 :backlinks: top ******** Overview ******** .. figure:: /images/howto/STEParchitectureDMtoCore.png :align: right :scale: 55% The STEP Architecture This page uses a simple example to describe how to model the mapping between the :ref:`Domain ` and :ref:`Core ` models using SysML in MagicDraw 18.4. =========== Preparation =========== .. contents:: The modelling steps in this section are: :local: .. important:: Prerequists This assumes that the environment is already set up. See |gs md| for more details .. comment ---------------------------------- Adding internal structure an ports ---------------------------------- .. _how_dmcore_video1: ^^^^^ Video ^^^^^ .. caution:: This video is out of date. It shows the steps from PLCSlib using Magicdraw 17.4 This video shows the steps for adding the internal structure and ports, then publication to XMI and images .. raw:: html
******* Common ******* .. contents:: :local: :depth: 1 :backlinks: top .. index:: Diagrams; How to - Parametric Diagrams for mapping Domain to Core .. _how_dmcore_diagrams: =============== Diagram Rules =============== .. include:: howtoDiagramsCommon.txt The following are rules applicable to layout and formatting of elements in Parametric Diagrams: * Domain object properties are conventionally placed on the left side of the diagram * The private property typed to "target" Core object is conventionally placed on the extreme right side of the diagram * The "target" flow port is conventionally placed on the extreme right-hand edge of the diagram ============= Colours ============= For the R-G-B to use for the Domain Model and Core Model entities, and for constraints and flow ports, see |colours|. ================================ Problem and Rationale Comments ================================ .. include:: howtoProblemComment.txt ****************** Step by Step guide ****************** .. contents:: The modelling steps are: :local: :depth: 1 :backlinks: top ================= Setup the diagram ================= The first step is to add a new **SysML Parametric Diagram** to the Block/template, and select the local properties. The inherited properties should be mapped as part of their owning block/template. See also video in :ref:`how_dmcore_first_mapping`. .. figure:: /images/howto/ht_dmcore_newdiagram01.png :scale: 100% Create a new diagram and add the local properties .. figure:: /images/howto/ht_dmcore_newdiagram02.png :scale: 100% Selected Properties are shown on the diagram .. _how_dmcore_first_mapping: ============================= Adding elements from the Core ============================= The block and its properties are mapped to elements from the Core (or other AP). These are added to the block as private part properties. (see |naming| and |colours|) .. todo:: protected rather than private on the superclass (TBC) see also :ref:`how_dmcore_redefined` .. warning:: The colours convention has been updated since this video was created. See |colours| for the latest colours. .. index:: Video; How to map simple property ADM to Core The video shows creating a new parametric diagram adding a private property using a type from the core, and mapping it to a property of the block. .. raw:: html .. comment .. raw:: html
.. todo:: steps for this section ===================== Adding flow-out ports ===================== Flow-out ports are used to expose internal (private) structure of the block/template that are needed by other blocks/templates. The type and cardinality of these ports are declared to ensure that connections defined in other templates are appropriate. .. tip:: It is recommended that only the ports that are really needed are exposed. One way to achieve this is to add the ports when they are found to be needed rather than anticipate the need. .. tip:: To make the "Select" constraints simpler, it is recommended that a naming convention is applied to the flow ports. For example in AP243, the following convention was used: * **item** for the main object e.g. Document, Part, Activity, Collection, Association, etc * **version** for when there is also a version-like port e.g. DocumentVersion, RealizedIndividualPart CollectionVersion etc * **view** for when there is also a view-like port e.g. PartView, IndividualPartView, RequirementView, CollectionView etc The constraint can then simply be "out = input.version" (see |naming|) .. todo:: steps for this section .. index:: Domain Model; How to - Map single Classification using Instances of Reference Data .. index:: Application Domain Model; How to - Map single Classification using Instances of Reference Data .. index:: Mapping; How to - use Reference Data Instances to map single Classification ADM-Core .. index:: Reference Data; How to - use Reference Data Instances to map single Classification ADM-Core .. index:: Video; How to map a single ADM classification to Core .. _how_dmcore_single_classification: =============================== Mapping a single Classification =============================== This shows how to add a mapping for a single classification. For more complex, combined and enumeration classification mapping see :ref:`how_dmcore_combined_classification` The mapping uses :ref:`how_rd_class` from the :ref:`Reference data ` that is set as the default value of an instance specification . The selected :term:`OWL` class should be a sub class of the block to which the classification is mapped. In the following example, the classification is mapped to the Core model block ApprovingParty, and therefore the selected OWL class is a sub class of "approving party". .. figure:: /images/howto/ht_dmcore_classrd01.png :scale: 100% .. rst-class:: expand -------------------------------- Classification naming convention -------------------------------- .. include:: howtoUUIDnamingClassification.txt ----- Video ----- .. figure:: /images/common/comingsoon.png :scale: 100% .. comment .. raw:: html .. raw:: html
----- Steps ----- The steps are: #. Create a new **Instance Specification** in the Instances Package (create the package if needed) #. Set the **Classifier** to **ExternalOWLClass** from Core_model::CommonRessources::ModelElements #. Set the Slot value for the **Class** property to a **Literal String** with the value set to the :term:`IRI` of the :term:`OWL` Class. The options for the IRI are: * :term:`IRI` copy functionality in Protégé (ctrl-U) can be used to copy the IRI to paste into the slot value (when the STEPlib :term:`RDL` is setup). Note: the class can be in the AP :term:`RDL` or the Core Model :term:`RDL` .. figure:: /images/howto/ht_rd_copyiri.png :scale: 100% * Use the UUID for a selected object. A macro has been written which will print the UUID of the selected object to the notifications window. If this macro is not already loaded into MagicDraw it can be found in STEPlib/utils/MagicDraw/getUUIDmacro.js. Note: this will then need to be added as an :term:`OWL` class to the AP :term:`RDL` .. figure:: /images/howto/ht_dmcore_getUUID.png :scale: 100% * Create an arbitrary :term:`IRI` (while waiting for AP :term:`RDL` to be set up) Note: this will then need to be added as an :term:`OWL` class to the AP :term:`RDL` .. figure:: /images/howto/ht_dmcore_ExtOwl01.png :scale: 100% #. Add a new **Reference Property** to the parametric diagram for the block * set the **type** to **ExternalOWLClass** * set the **Default Value** to the **Instance Specification** above * set the **multiplicity** ([1] or [0..1] depending on what it is connected to) .. todo:: visibility = public - TBC .. figure:: /images/howto/ht_dmcore_ExtOwl02.png :scale: 100% #. In the diagram, display **Compartment** for the **Default Value** .. figure:: /images/howto/ht_dmcore_ExtOwl03.png :scale: 100% #. Add a Rationale comment (comment stereotyped to rationale) showing the :ref:`how_rd_class_preflabel` of the class and of the :ref:`how_rd_class_subclassof`. .. figure:: /images/howto/ht_dmcore_ExtOwl05.png :scale: 100% #. Add a new **Part Property** to the parametric diagram for the block * set the **type** to **Classification** * set the **Visibility** to **Private** * set the multiplicity. This should be either [1] for compulsory objects or [0..1] for optional. * display the **Class** property #. Create a **Binding Connector** from reference property to the Classification.Class #. Create a **Binding Connector** from Classification part property to the Classification in the core element .. figure:: /images/howto/ht_dmcore_ExtOwl04.png :scale: 100% .. index:: Domain Model; How to - Map combined Classification using Instances of Reference Data .. index:: Application Domain Model; How to - Map combined Classification using Instances of Reference Data .. index:: Mapping; How to - use Reference Data Instances to map combined Classification ADM-Core .. index:: Reference Data; How to - use Reference Data Instances to map combined Classification ADM-Core .. index:: Enumerations; How to - use Reference Data Instances to map as Classification ADM-Core .. index:: Video; How to map a combined ADM classification to Core .. _how_dmcore_combined_classification: ================================== Mapping a combined Classification ================================== .. warning:: The colours and naming convention has been updated since this video was created. See |colours| for the latest colours and |naming| for the latest naming. .. rst-class:: expand --------------------------------- Classification naming convention --------------------------------- .. include:: howtoUUIDnamingClassification.txt .. rst-class:: expand ----------------------------- Enumeration naming convention ----------------------------- .. include:: howtoUUIDnamingClassification.txt ----- Video ----- .. raw:: html .. comment .. raw:: html
----- Steps ----- The steps are: .. todo:: text for this section .. index:: Domain Model; How to - Constraints in mapping to Core .. index:: Application Domain Model; How to - Constraints in mapping to Core .. index:: Constraints; How to - Domain Model mapping to Core ================= Select Mapping ================= See also :ref:`how_mapex_select` Process for a given "source select" e.g. "ActivityAssignmentSelect": #. decide on the "target select" to map to. #. Add a flow port to the "source select", typed to the "target select" and named with the first letters of the words of the "target select" (or similar to get unique name) #. In the mapping diagrams, add the flow port to the property that is typed to the source select. #. bind this to the property in the target that is typed to the "target select" #. for each block that is a specialization of the "source Select", * create a diagram for the select mapping (if it does not already exist) * add the flow port to this diagram * drag the appropriate private (mapping) property onto the diagram and create a binding connector to the flow port. #. if there are no private properties that can have binding connectors to the flow port, then either one must be created, or the block cannot be a specialization of the "source select". .. figure:: /images/howto/ht_dmcore_select01.png :scale: 100% .. figure:: /images/howto/ht_dmcore_select02.png :scale: 100% .. todo:: For 6. above, is it possible to have more flow ports of different types for a source select and then use a constraint for when there is more than one mapping? ================= Adding Contraints ================= .. contents:: :local: :depth: 1 :backlinks: top .. _how_dmcore_create_constraint: --------------------------- Create a Simple Constraint --------------------------- .. todo:: Note: this should actually be done using a select mapping This example is creating a **constraint block** for a "select type", so it needs two **constraint parameters**, the input of the Domain Model "select type" and an output typed to the appropriate object from Core Model. The **contraint** is then a if-then-else conditional. .. figure:: /images/howto/ht_dmcore_constraint01.png :scale: 100% Example for using a constraint .. index:: Video; How to Create a Constraint Block for use in mapping ^^^^^ Video ^^^^^ .. todo:: update to add "is readonly" to the output ports .. raw:: html ^^^^^ Steps ^^^^^ The steps are: #. **Search** to see if there is an existing **Constraint Block** for what is needed. * if yes, then skip these steps and go on to :ref:`Using a Constraint ` #. Create a "Constraints" **package** if it does not already exist #. Create a new **Constraint Block** .. figure:: /images/howto/ht_dmcore_constraint02.png :scale: 100% #. Add **Constraint Parameters** .. figure:: /images/howto/ht_dmcore_constraint04.png :scale: 100% #. Set the **type** for each Constraint Parameter as follows: * remove constraint parameter stereotype * set the type needed * reset constraint parameter stereotype .. figure:: /images/howto/ht_dmcore_constraint03.png :scale: 100% #. For the **output** Constraint Parameters set the **Is Read Only** to true .. figure:: /images/howto/ht_dmcore_constraint09.png :scale: 100% #. Edit the **specification** "{}", using **Language** of **OCL2.0** .. figure:: /images/howto/ht_dmcore_constraint05.png :scale: 100% .. _how_dmcore_use_constraint: --------------------------- Using a Constraint --------------------------- .. index:: Video; How to use a constraint in mapping ^^^^^ Video ^^^^^ .. important:: This video does not hide the constraint on the constraint property. See the detailed steps for the correct display. .. raw:: html ^^^^^ Steps ^^^^^ The steps are: #. Add a new **Constraint Property** to the Parametric Diagram #. Specify the **Type** to be an existing Constraint Block .. figure:: /images/howto/ht_dmcore_constraint06.png :scale: 100% #. Display the Parameters .. figure:: /images/howto/ht_dmcore_constraint07.png :scale: 100% #. Add **Binding Connectors** between the parameters and elements on the diagram #. Optionally display the parameter types .. figure:: /images/howto/ht_dmcore_constraint08.png :scale: 100% ------------------- Complex constraints ------------------- .. todo:: see examples of describeSelector or idSelector in the core .. comment =========== Other tasks =========== ------------------ Publication to XMI ------------------ .. todo:: to do video, see :ref:`video ` .. todo:: the step-by-step for this section ---------------- Export of images ---------------- .. todo:: to do, see :ref:`how_dmcore_video1` .. todo:: the step-by-step for this section .. index:: Domain Model; How to - Missing mandatory properties in mapping to Core .. index:: Application Domain Model; How to - Missing mandatory properties in mapping to Core ============================ Missing mandatory properties ============================ In some cases the template in the lower layer has compulsory properties that are not present in the upper layer. When this happens a **dummy** entity must be created. In the below example it can be seen that the property "name" in the upper layer has multiplicity of [0..1] whereas the lower layer has [1]. This means that sometimes the upper layer will not have a name. This is resolved by creating a **dummyName** and using a constraint that will use this if the input is not provided. This is illustrated below. .. figure:: /images/howto/ht_dmcore_dummy.png :scale: 100% .. index:: Domain Model; How to - Redefined properties mapping to Core .. index:: Redefined; How to - Domain Model mapping to Core .. index:: Application Domain Model; How to - Redefined properties mapping to Core .. index:: Redefined; How to - Application Domain Model mapping to Core .. _how_dmcore_redefined: =========================================== Redefined properties and inherited mappings =========================================== .. todo:: Should just be able to use the inherited. Assumes the redefined are sub-types of the objects they are redefining. See also :ref:`how_dm_redefined` .. figure:: /images/howto/ht_dmcore_redefined01.png :scale: 100% The steps are: #. Drag the inherited part property onto the diagram .. figure:: /images/howto/ht_dmcore_refactor01.png :scale: 100% #. **Refactor > Redefine To** and select the subtype .. figure:: /images/howto/ht_dmcore_refactor02.png :scale: 100% #. Add a new flow port typed to subtype #. Select **Redefined Port** and select the supertype port. #. Add a binding connector .. figure:: /images/howto/ht_dmcore_refactor03.png :scale: 100% protected rather than private on the superclass (TBC) (from https://trello.com/c/ajMU2USq/100-n-standing-doc-method-to-map-subtypes-using-supertype-mapping) .. figure:: /images/howto/ht_dmcore_protected01.jpg :scale: 100% Inherited showing protected and refactor->redefine PS: Dragged the protected part property view from PartView onto the parametric diagram for AssemblyView. (JC - I do this using the Display parameters/properties as it is safer; can see all inherited so can do multiple at same time ) Right click->Refactor->Redefine to then selected Assembly_definition This creates the redefined view part in the current mapping Option 1 (display the original binding connector on the diagram): * use text box and horizontal separator to add some visual separation to the diagram * drag the Protected part property view from PartView onto the diagram again (this time placing it in the inherited section of the diagram) * drag the Protected part property idAsgn from PartView into the inherited section of the diagram. * select ^idAsgn right click->Display Parts, then selected items from the list. This then automatically showed the binding connector created in the PartView parametric diagram Option 2 (see the binding connector to the redefined object): * Create a new binding connector * add a name to the original binding connect (so it can be found in the tree, any text will do) * set the **redefined connector** in the new, to the orginal * remove the name from the original .. figure:: /images/howto/ht_dmcore_refactor04.png :scale: 100% Inherited redefined binding connector The advantage of this approach is: * We can (with some effort!) show the mapping inherited from the supertype in the parametric diagram of the subtype * We can show protected properties from the supertype that have been redefined (however there is no graphical symbol to indicate the redefinition relationship between two properties) and explicitly show any mappings required at the subtype level that are not required at the supertype level. .. index:: Domain Model; How to - PatternBlocks .. index:: PatternBlocks; How to - Domain Model .. index:: Application Domain Model; How to - PatternBlocks .. index:: PatternBlocks; How to - Application Domain Model .. _how_dmcore_pattern: ======== Patterns ======== Patterns are used to show how a "concept" in one level is represented by objects in the same level. .. todo:: text for this section Notes from Trello Our understanding: * a template/pattern use parametric diag with domain elements inside * the template/pattern tells you that the set of domain elements inside has to be instantiated as described in the parametric (relationship and values * it can avoids, for instance, 2 way of setting property information to an object (either prop assignment , either using owned attributes, etc.), which add a constraint to the model to better use it * Each template is a block (a kind of concept, with a parametric), but is is NOT an ENTITY, which is NOT mapped to the lower level (eg ARM), but each Domain Objects are, of course are mapped to the lower level => let's not mix Template and Parametric Mapping ! * the Template's attributes (properties in the left in the Parametric) are the main information to manage and store/assign (old attributes from original ENTITY) Example: ContentProperty has a description, which is represented by additional descriptions being associated with the DocumentDefinition or File, these extra descriptions being classified as ContentDescriptions. Similarly the DetailLevel of the ContentProperty is represented as additional descriptions classified as DetailedLevel being associated with the target object. .. figure:: /images/howto/ht_dm_patterns_example.jpg :scale: 100% Exmaple for ContentProperty .. sectionauthor:: |Judith Crockford| .. include:: /keywords.rst