How to model the mapping between the Activity and Data Planning models of STEPLIB

How to model the mapping between the Data Planning and Domain models of STEPLIB

STEPlib SysML: How To use the Scripts to Generate implementation specific test data

How to model the mapping between the Domain and Core models of STEPLIB

NamedIndividual Preferred label (skos:preflabel) mandatory property

NamedIndividual Change Note (skos:changeNote) mandatory property

NamedIndividual of Class (rdf:type rdf:resource) mandatory property

A path variable (Options->Environment->Path Variables) STEPlib needs to be added and set to the path to the STEPlib folder in the cloned Git project.

.. figure:: /images/howto/gs_md_STEPlibPath01.png
        :scale: 100%

        Setting the STEPlib path environment variable

To ensure relative paths from this start point are captured correctly this should be used whenever exporting from MagicDraw
(e.g. when separating out a :term:`CTC` into a separate file). This will enable the model to be transferred to other developer's machines.

(e.g. when separating out a 

 into a separate file). This will enable the model to be transferred to other developer's machines.

The environment needs to be set to save with UUID (Options->Environment->General->Save/Load->Save UUID).

.. figure:: /images/howto/gs_md_uuid.png

        Setting Save with UUID

ISO standards use the GB English dictionary (officially *The Concise Oxford Dictionary of Current English*). The default for |MD| is US English which should be changed.

.. figure:: /images/howto/gs_md_en_gb.png

        Setting Dictionary to GB English

Check that English GB is in the list of options (lower panel). If it is not, a copy should be in the same installation folder as the other
dictionries and can simply be added. If not, then a copy should be obtained from the internet

In the Spelling panel, change the Dictionary option to use this English GB dictionary

If you receive an error message saying your modeling tool is out of memory, the application does not have enough memory to operate. You can change the amount of allocated
memory directly in the error message dialog or by changing modeling tool properties.

.. figure:: /images/howto/gs_md_memory_error.png

        Memory Error message

If you computer has enough memory (see below) the recommended value for **Xmx** is 4000. Default is 1200.

If you computer has enough memory (see below) the recommended value for 

.. hint::
        **Memory allocation concept**

        Memory allocation for the product is the same as Java heap size. To increase the amount of memory allocated for the product, simply increase the Java heap size.

**Recommended amount of allocated memory**

The amount of allocated memory (or Java heap size) should be set to less than the available physical RAM on your computer. To calculate the approximate amount of memory you should allocate, subtract the amount of memory taken by any other processes that will run concurrently with your modeling tool from the total amount of RAM in your computer. Otherwise your JVM process will likely swap, and that will slow down the application.

.. warning::

        **Do not allocate too much memory**

        If you increase the Java heap size too much, you will get an error message that the Java virtual machine cannot be created, and a modeling tool will not start.

The maximum theoretical heap limit for the 32-bit JVM is 4G. In practice, the limit can be much lower, due to various additional constraints such as available swap, kernel address space usage, memory fragmentation, and VM overhead.

* On most 32-bit Windows systems the maximum heap size ranges from 1.4G to 1.6G.
* On 32-bit Solaris kernels the address space is limited to 2G.
* On 64-bit operating systems running the 32-bit VM, the max heap size can be higher, approaching 4G on many Solaris systems.
* On 64-bit VMs, the maximum Java heap size is limited only by the amount of physical memory and swap space your system provides.

**Changing the amount of allocated memory**

You can set the amount of memory allocated for your modeling tool either in the Environment Options dialog or in the modeling tool properties file.

To change the amount of allocated memory in the Environment Options dialog

1. In the main menu of your modeling tool, go to Options > Environment. The Environment Options dialog opens.
2. Expand the General options group on the left side of the dialog, and select the Memory Settings category.
3. In the option specification area on the right side of the dialog, change the value of the Maximum Heap Size or Thread Stack Size option.

To change the amount of allocated memory in the modeling tool properties file

1. Go to <modeling tool installation directory>\bin and open the modeling tool properties file.
2. In the JAVA_ARGS line, change the value of the -Xmx or -Xss property. For example, change the -Xmx800M to -Xmx1066M.
3. Save and close the file.
4. Restart your modeling tool.

**Memory allocation concept**

Memory allocation for the product is the same as Java heap size. To increase the amount of memory allocated for the product, simply increase the Java heap size.

**Do not allocate too much memory**

If you increase the Java heap size too much, you will get an error message that the Java virtual machine cannot be created, and a modeling tool will not start.

On most 32-bit Windows systems the maximum heap size ranges from 1.4G to 1.6G.

On 64-bit operating systems running the 32-bit VM, the max heap size can be higher, approaching 4G on many Solaris systems.

On 64-bit VMs, the maximum Java heap size is limited only by the amount of physical memory and swap space your system provides.

In the main menu of your modeling tool, go to Options > Environment. The Environment Options dialog opens.

Expand the General options group on the left side of the dialog, and select the Memory Settings category.

In the option specification area on the right side of the dialog, change the value of the Maximum Heap Size or Thread Stack Size option.

Go to <modeling tool installation directory>\bin and open the modeling tool properties file.

Go to <modeling tool installation directory>bin and open the modeling tool properties file.

In the JAVA_ARGS line, change the value of the -Xmx or -Xss property. For example, change the -Xmx800M to -Xmx1066M.

The SysML tools are accessed when using the "System Engineer" perspective which is not the default so needs to be set using **Options > Perspectives > Perspectives**.

The SysML tools are accessed when using the "System Engineer" perspective which is not the default so needs to be set using 

.. figure:: /images/howto/gs_md_seperspective.png

        Change Perspective to "System Engineer"

Some macros have been developed to aid developement. These are stored in the STEPlib\utils\MagicDraw folder.

Some macros have been developed to aid developement. These are stored in the STEPlibutilsMagicDraw folder.

Browse to select the file (e.g. STEPlib\\utils\\MagicDraw\\getUUIDmacro.js)

Browse to select the file (e.g. STEPlib\utils\MagicDraw\getUUIDmacro.js)

`MagicDraw online help - Macros <https://docs.nomagic.com/display/MD185/Adding+a+Macro+and+editing+Macro+information>`__

Before opening the model, the :ref:`STEPlib environment variables <gs_md_env>` and :ref:`Perspective <gs_md_seperspective>` must be set.

The top level model is STEPlib.mdzip and is stored in the STEPlib/dvlp folder.

.. figure:: /images/howto/gs_md_openmodel01.png

        Open STEPlib.mdzip in |MD|

Several "Loading..." windows open, and then the model as shown below.

.. figure:: /images/howto/gs_md_openmodel02.png

        STEPlib.mdzip opened in |MD|

The SysML model in STEPlib is split between several connected "projects" in separate files. In |MD| each project needs to be open to be editable.
The default behaviour is to open the projects in readonly, so on first opening most of the content is readonly (greyed out) as shown in :numref`gs_md_fig_openedModel`.

The SysML model in STEPlib is split between several connected "projects" in separate files. In 

 each project needs to be open to be editable.

A sub-project is opened using the "Project Usages" dialog which is available from the tree on the M-R menu for single projects (see :numref:`gs_md_projectusage01`).
Alternatively the settings for multiple projects can be controlled from the "Options > Project Usages" (see :numref:`gs_md_projectusage02`).
These are illustrated below. For more details see |MD help mup|.

A sub-project is opened using the "Project Usages" dialog which is available from the tree on the M-R menu for single projects (see 

).
Alternatively the settings for multiple projects can be controlled from the "Options > Project Usages" (see 

`MagicDraw online help - Managing used Projects <https://docs.nomagic.com/display/MD185/Managing+used+projects>`__

.. figure:: /images/howto/gs_md_projectusage01.png

        Opening a project from the tree

.. figure:: /images/howto/gs_md_projectusage02.png

        Options dialog for Opening multiple projects

`Judith Crockford (AP243) <mailto:judith.crockford@airbus.com?subject=STEPLib Documentation>`__

.. |gs md| replace:: :doc:`Getting Started - MagicDraw</pages/howto/gettingstarted/gettingstartedinMagicDraw>`

:doc:`Getting Started - MagicDraw</pages/howto/gettingstarted/gettingstartedinMagicDraw>`

.. |script IS| replace:: :doc:`Standard Documents Generation.</pages/howto/howtoScriptIS>`

:doc:`Standard Documents Generation.</pages/howto/howtoScriptIS>`

.. |Git Index| replace:: `Git Documentation Index <http://cvs.boost-lab.net/sphinx/Git_Gitlab_User_Guide/html/index.html>`__

`Git Documentation Index <http://cvs.boost-lab.net/sphinx/Git_Gitlab_User_Guide/html/index.html>`__

.. |git index| replace:: `Git Documentation Index <http://cvs.boost-lab.net/sphinx/Git_Gitlab_User_Guide/html/index.html>`__

.. |obp| replace:: `ISO Online Browsing platform <https://www.iso.org/obp>`__

.. |Supplementary Directives| replace:: `Supplementary Directives (SC4N2412) <https://isotc.iso.org/livelink/livelink?func=ll&objId=11571831&objAction=Open&nexturl=%2Flivelink%2Flivelink%3Ffunc%3Dll%26objId%3D11568437%26objAction%3Dbrowse%26viewType%3D1>`__

.. |ISO House Style| replace:: `ISO House Style <https://www.iso.org/ISO-house-style.html>`__

.. |WG12 Review Checklist| replace:: `WG12 Review Checklist (QCN265) <https://isotc.iso.org/livelink/livelink?func=ll&objId=16694083&objAction=Open&nexturl=%2Flivelink%2Flivelink%3Ffunc%3Dll%26objId%3D11568437%26objAction%3Dbrowse%26viewType%3D1>`__

.. |10303-1| replace:: `10303-1 <https://www.iso.org/standard/20579.html>`__

.. |MD help mup| replace:: `MagicDraw online help - Managing used Projects <https://docs.nomagic.com/display/MD185/Managing+used+projects>`__

.. |MD help macro| replace:: `MagicDraw online help - Macros <https://docs.nomagic.com/display/MD185/Adding+a+Macro+and+editing+Macro+information>`__

.. |OMG SysML 1.4| replace:: `OMG Systems Modeling Language (OMG SysML) Version 1.4 <https://www.omg.org/spec/SysML/1.4/PDF>`__

`OMG Systems Modeling Language (OMG SysML) Version 1.4 <https://www.omg.org/spec/SysML/1.4/PDF>`__

.. |OMG SysML| replace:: `OMG SysML <https://www.omg.org/spec/SysML/1.4/PDF>`__

.. |OMG UML long| replace:: `OMG Unified Modeling Language (OMG UML) <https://www.omg.org/spec/UML/2.5/PDF>`__

`OMG Unified Modeling Language (OMG UML) <https://www.omg.org/spec/UML/2.5/PDF>`__

.. |OMG UML| replace:: `OMG UML <https://www.omg.org/spec/UML/2.5/PDF>`__

.. |XMI 2.5| replace:: `XMI 2.5 <https://www.omg.org/spec/XMI/2.5.1/>`__

.. |ISO/IEC 19514| replace:: `ISO/IEC 19514:2017: *Information technology – Object management group systems modeling language* <https://www.iso.org/standard/65231.html>`__

`ISO/IEC 19514:2017: *Information technology – Object management group systems modeling language* <https://www.iso.org/standard/65231.html>`__

ISO/IEC 19514:2017: *Information technology – Object management group systems modeling language*

.. |Judith Crockford| replace:: `Judith Crockford (AP243) <mailto:judith.crockford@airbus.com?subject=STEPLib Documentation>`__

.. |Mike Ward| replace:: `Mike Ward <mailto:mike.ward@eurostep.com?subject=STEPLib Reference Data Documentation>`__

`Mike Ward <mailto:mike.ward@eurostep.com?subject=STEPLib Reference Data Documentation>`__

.. |support email| replace:: `support@boost-lab.net <mailto:support@boost-lab.net?subject=STEPLib Documentation>`__

.. |Erwan Livolant| replace:: `Erwan Livolant [Boost Conseil] <mailto:erwan.livolant@boost-conseil.com?subject=STEPLib Documentation>`__

`Erwan Livolant [Boost Conseil] <mailto:erwan.livolant@boost-conseil.com?subject=STEPLib Documentation>`__

.. |Aminata Mbengue| replace:: `Aminata Mbengue [Boost Conseil] <mailto:aminata.mbengue@boost-conseil.com?subject=STEPLib Documentation>`__

`Aminata Mbengue [Boost Conseil] <mailto:aminata.mbengue@boost-conseil.com?subject=STEPLib Documentation>`__

.. |veroDub| replace:: `Veronique Dubillot [Boost Conseil] <mailto:veronique.dubillot@boost-conseil.com?subject=STEPLib Documentation>`__

`Veronique Dubillot [Boost Conseil] <mailto:veronique.dubillot@boost-conseil.com?subject=STEPLib Documentation>`__

This page explains how to set up MagicDraw for use when developing STEP standards using STEPlib.

Before work can start (particually for new projects) it may be necessary for the :ref:`Team Leader to complete some tasks<gs_tlt_top>`.

Before work can start (particually for new projects) it may be necessary for the 

MagicDraw version 18.4 SP1 (with MERGE plugin) is used for STEPlib and this documentation

This assumes that the STEPlib Git repository has already been cloned as described in |git developer|.

This assumes that the STEPlib Git repository has already been cloned as described in 

.. image:: /images/common/construction.png
        :width: 100
        :align: left

This page is under construction.

To contribute or participate contact `support@boost-lab.net <mailto:support@boost-lab.net?subject=STEPLib Documentation>`__

Tunnelling is used to simplify diagrams where an ICOR is used as-is by the recursive decomposition of that function.
A ICOR is indicated to enter a tunnel by () on the pin of the function on the decomposition diagram, and the tunnelled ICOR and data flows hidden
on all sub-function diagrams.
If a sub-function uses the ICOR differently then it is shown on the outer node of the diagram and tunnel () added.

The tunnel is a cosmetic feature of the diagram. All ICOR and object flows must be modelled recursively.

Tunnels on **Input** and **Output** pins are identified by adding the **TunnelH** stereotype.

Tunnels on **Control** and **Mechanism** pins are identified by adding the **TunnelV** stereotype.

A tunnel is displayed on the diagram by setting the symbol propert **Show Stereotype** to **Shape Image**.

A tunnel is displayed on the diagram by setting the symbol propert 

.. figure:: /images/howto/ht_aam_tunnel.png

        Control pin entering a tunnel

Hyperlink target "howto-aam-fig-ht-aam-naming" is not referenced.

Hyperlink target "howto-aam-fig-ht-aam-colours" is not referenced.

The model shall contain a A-0 context diagram, which contains only one StructuredActivityNode.

If two flows are needed from a single pin, then a fork should be used to split the flow.

.. figure:: /images/7TheApplicationActivityModelOfAnAP/diagramSyntaxRule14SysML.png

        Use Fork so only one flow out of a pin

If two flows are needed into a single pin, then a merge should be used.

.. figure:: /images/7TheApplicationActivityModelOfAnAP/diagramSyntaxRule14SysML2.png

        Use merge so only one flow into a pin

For readability, there should be no more than nine activities per level. If more are needed it is an indication that additional levels should be inserted.

The general convention for **StructuredActivityNode** is for a level prefix and then space separated name with each word capitalized. e.g. "A2 Manage Product Development Project".

 is for a level prefix and then space separated name with each word capitalized. e.g. "A2 Manage Product Development Project".

The top level Activity **and** it's StructuredActivityNode should both be called **A-0 APname**. These are the context for the AAM

There should be one Activity representing the AP, this should start with **A0**

There should be one Activity representing the AP, this should start with 

Children of these are subsequent levels start with their parent prefix and append a sequential number (e.g. children of A3 are A31 A32 A33 etc, children of A33 are A331 A332 A333 etc)

StructuredActivityNode names and concept names shall not consist solely of the following words: function, activity, process, input, output, control or mechanism.

This is illustrated in :numref:`howto_aam_fig_ht_aam_naming` below.

.. figure:: /images/howto/ht_aam_naming.png

        Example from AP242ed2 showing naming convention

There is no strict nameing convention for the **pins** except that they should start with lowercase.

The Activity **Diagrams** should have the same name as the StructuredActivityNode they are representing.

 should have the same name as the StructuredActivityNode they are representing.

There is no convention for naming the **Object Flow**, **Fork** and **Merge** nodes as these are not normally named

In the diagrams hide the **<<structured>>** stereotype using the Symbol properties > Show Stereotypes > Do Not Display. This can be set as the default (see :ref:`tip<how_aam_tip_symbolprops>`)

 stereotype using the Symbol properties > Show Stereotypes > Do Not Display. This can be set as the default (see 

Outer StructuredActivityNode represented by the diagram

      * Fill = None (i.e. white)
      * Line = RGB 153 153 92 (i.e. |MD| default)

Pins on the outer StructuredActivityNode (not coloured so as not to be visible)

      * Line  = white

Inner StructuredActivityNodes

      * Fill = RGB 231 231 231

Pins on inner  StructuredActivityNodes

      * Fill = white
      * Line = RGB 231 231 231

Merge (i.e. |MD| default)

      * Fill = RGB 213 213 213
      * Line = RGB 124 129 109

This is illustrated in :numref:`howto_aam_fig_ht_aam_colours` below.

.. figure:: /images/howto/ht_aam_colours.png

        Example from AP242ed2 showing colour convention

The default symbol properties can be set for all new symbols using the "Set Selected Symbol style as default" button. The style can be applied to existing symbols using the
"Apply default symbol style" button.

.. figure:: /images/howto/ht_common_default_appearance.png

        Setting and Applying default symbol styles.

The following are the IDEF0 syntax rules adapted to the use of SysML in the activity diagrams used in the application activity model:

StructuredActivityNodes shall be organized diagonally from the upper left corner to the lower right, i.e., in a "staircase" configuration, unless an alternative configuration improves the readability or is a better use of space;

The name of the StructuredActivityNode shall be centred in the box;

Each StructuredActivityNode shall have a minimum of one input pin and one output pin;

A StructuredActivityNode shall have zero or more mechanism pins;

Each pin on a diagram shall be the source or target of one ObjectFlow.;

Where more than one ObjectFlow is needed at a pin, SysML Fork or SysML Merge nodes shall be used to convert between single and multiple ObjectFlows (see also :ref:`how_aam_one_out` and :ref:`how_aam_one_in`);

Where more than one ObjectFlow is needed at a pin, SysML Fork or SysML Merge nodes shall be used to convert between single and multiple ObjectFlows (see also 

ObjectFlows shall be drawn as horizontal and vertical straight-line segments. Diagonal line segments shall not be used;

.. figure:: /images/howto/ht_aam_feedback.png
       :scale: 100%

       Object Flow Feedback arrows

The flow **from a pin** must have conveyed information **(A)** unless **(B)** it is connected to a merge where all the inputs to be merged are assumed to be the same,
in which case it is assumed to have the same conveyed information as the output from the merge

 it is connected to a merge where all the inputs to be merged are assumed to be the same,

The flow **from a fork** only needs conveyed information if **(C)** it is division of the input flow conveyed information, otherwise **(D)** it is assumed to have the same conveyed information as the input to the fork

 it is division of the input flow conveyed information, otherwise 

 it is assumed to have the same conveyed information as the input to the fork

If the flows **into a merge** have:

     * **same** conveyed information **(E)**, the output flow not need conveyed information, it is assumed to have the same conveyed information as the input to the merge
     * **different** conveyed information, the output flow must have either a single conveyed information that is an aggregation the input conveyed information **(F)**, or all the input flow conveyed information added to the output flow conveyed information **(G)**.
     * **no** conveyed information, the output flow must have conveyed information **(H)**, and the input flows are assumed to also have this conveyed information

**same** conveyed information **(E)**, the output flow not need conveyed information, it is assumed to have the same conveyed information as the input to the merge

, the output flow not need conveyed information, it is assumed to have the same conveyed information as the input to the merge

**different** conveyed information, the output flow must have either a single conveyed information that is an aggregation the input conveyed information **(F)**, or all the input flow conveyed information added to the output flow conveyed information **(G)**.

 conveyed information, the output flow must have either a single conveyed information that is an aggregation the input conveyed information 

, or all the input flow conveyed information added to the output flow conveyed information 

**no** conveyed information, the output flow must have conveyed information **(H)**, and the input flows are assumed to also have this conveyed information

 conveyed information, the output flow must have conveyed information 

, and the input flows are assumed to also have this conveyed information

The preferred use for merge and fork is for a single merge with multiple inputs rather than a series of merge each merging two inputs, similarly for a single fork with multiple outputs. However if the non-preferred layout is used for cosmetic reasons, the above conventions are **recursive**.

The preferred use for merge and fork is for a single merge with multiple inputs rather than a series of merge each merging two inputs, similarly for a single fork with multiple outputs. However if the non-preferred layout is used for cosmetic reasons, the above conventions are 

.. figure:: /images/howto/ht_aam_conveyedoptions.png

        Convention for conveyed information

.. figure:: /images/howto/ht_aam_conveyedexamples.png

        Examples for conveyed information from AP242

Video does not show all the latest convensions:

* Names should be centred in boxes
* Stereotypes should be hidden
* Stereotype for "Resource" rather than "Mechanism"

<iframe width="560" height="315" src="https://www.youtube.com/embed/mpQ0ddkzZWY" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
<br/>
<br/>

the step-by-step for this section

#. Add element > Activity. Rename to  "A-0 AP243"
#. Add diagram > activity diagram to the above activity
#. Add StructuredActivtyNode to diagram, covering most of the diagram area,

        * rename "A-0 AP243".
        * Symbol Properties (Alt-Enter) UseFillColour - uncheck

Add StructuredActivtyNode to diagram, covering most of the diagram area,

     * rename "A-0 AP243".
     * Symbol Properties (Alt-Enter) UseFillColour - uncheck

This assumes that the environment is already set up. See |gs md| for more details. Also that there is an Activity_Model node, Conceptual_Model node and the Activity profile is included as shown below.

 for more details. Also that there is an Activity_Model node, Conceptual_Model node and the Activity profile is included as shown below.

.. figure:: /images/howto/ht_aam_start01.png

        Application Activity Model starting point

This page uses a simple example to describe how to model the the Application Activity Model using SysML in MagicDraw 18.4.

The Application Activity Model of an application protocol is a Functional model to identify the information flows of interest to be supported by the application protocol.

comment

For more details and rationale of the SysML usage see :ref:`what_aam_top`.

.. figure:: /images/howto/STEParchitectureAAM.png
        :align: right
        :scale: 55%

        The STEP Architecture

Stereotypes can be added to pins quickly afterwards by Drag and drop from tree to diagram

.. figure:: /images/howto/ht_aam_tip_stereotype.png

        Drag and Drop Stereotype from tree to diagram

Add element > input pin - to left edge of inner StructuredActivtyNode

     * rename to something e.g. "Input1"
     * double click to open properties,

             * add AppliedStereotype of "Input" (part of STEPlib profile)
             * change color to white and **pen to RGB 231 231 231**
             * uncheck Show Name

     .. tip::

             Stereotypes can be added to pins quickly afterwards by Drag and drop from tree to diagram

             .. figure:: /images/howto/ht_aam_tip_stereotype.png
                     :scale: 100%

                     Drag and Drop Stereotype from tree to diagram

#. Add another StructuredActivtyNode inside the first

        * rename "A0 Do M&S In Collaborative SE Context"
        * change colour to RGB 231 231 231

#. Add element > input pin - to left edge of outer StructuredActivtyNode

        * rename to something e.g. "Input1"
        * double click to open properties,

                * add AppliedStereotype of "Input" (part of STEPlib profile)
                * change color and pen to white (so it disappears)
                * uncheck Show Name

#. Add element > input pin - to left edge of inner StructuredActivtyNode

                * change color to white and **pen to RGB 231 231 231**

        .. tip::

                Stereotypes can be added to pins quickly afterwards by Drag and drop from tree to diagram

                .. figure:: /images/howto/ht_aam_tip_stereotype.png
                        :scale: 100%

                        Drag and Drop Stereotype from tree to diagram

#. Add object flow from outer pin to inner pin (see the arrow disappear from inside the inner pin)

                * Select **Conveyed Information** from menu on left
                * Select suitable block from Conceptual_model
                * Multi-selection option at bottom of window opens panel for multiple objects

        * see that the object flow arrow now has a solid black arrowhead in the centre
        * Mouse-R on object flow and select "Show Compartements", select table "Information from X to Y" and then >> to move all to right. Now the CM objects are displayed

        .. figure:: /images/howto/ht_aam_showConveyedInfo.png
                :scale: 100%

                Edit Compartements to display conveyed information

#. Fork and merge

        .. tip::

                Drag and drop to split existing flows

                .. figure:: /images/howto/ht_aam_tip_split.png

                        Drag and Drop Fork and Merge onto flow to split

#. The end

        .. figure:: /images/7TheApplicationActivityModelOfAnAP/a0NameOfA0WithInformationFlow.png

                Completed diagram - Activity diagram for Activity “A0 – Develop Product” with fork and merge

Add another StructuredActivtyNode inside the first

     * rename "A0 Do M&S In Collaborative SE Context"
     * change colour to RGB 231 231 231

Add element > input pin - to left edge of outer StructuredActivtyNode

             * change color and pen to white (so it disappears)

double click to open properties,

      * add AppliedStereotype of "Input" (part of STEPlib profile)
      * change color and pen to white (so it disappears)
      * uncheck Show Name

Add object flow from outer pin to inner pin (see the arrow disappear from inside the inner pin)

             * Select **Conveyed Information** from menu on left
             * Select suitable block from Conceptual_model
             * Multi-selection option at bottom of window opens panel for multiple objects

     * see that the object flow arrow now has a solid black arrowhead in the centre
     * Mouse-R on object flow and select "Show Compartements", select table "Information from X to Y" and then >> to move all to right. Now the CM objects are displayed

     .. figure:: /images/howto/ht_aam_showConveyedInfo.png
             :scale: 100%

             Edit Compartements to display conveyed information

      * Select **Conveyed Information** from menu on left
      * Select suitable block from Conceptual_model
      * Multi-selection option at bottom of window opens panel for multiple objects

Multi-selection option at bottom of window opens panel for multiple objects

see that the object flow arrow now has a solid black arrowhead in the centre

Mouse-R on object flow and select "Show Compartements", select table "Information from X to Y" and then >> to move all to right. Now the CM objects are displayed

.. figure:: /images/howto/ht_aam_showConveyedInfo.png

        Edit Compartements to display conveyed information

Fork and merge

     .. tip::

             Drag and drop to split existing flows

             .. figure:: /images/howto/ht_aam_tip_split.png

                     Drag and Drop Fork and Merge onto flow to split

Drag and drop to split existing flows

.. figure:: /images/howto/ht_aam_tip_split.png

        Drag and Drop Fork and Merge onto flow to split

The end

     .. figure:: /images/7TheApplicationActivityModelOfAnAP/a0NameOfA0WithInformationFlow.png

             Completed diagram - Activity diagram for Activity “A0 – Develop Product” with fork and merge

.. figure:: /images/7TheApplicationActivityModelOfAnAP/a0NameOfA0WithInformationFlow.png

        Completed diagram - Activity diagram for Activity “A0 – Develop Product” with fork and merge

Completed diagram - Activity diagram for Activity “A0 – Develop Product” with fork and merge

      * change color to white and **pen to RGB 231 231 231**

Prerequists

This assumes that the environment is already set up. See |gs md| for more details

The video is out of date as it does not include Conformance Options

The video shows creating Units of Functionality and adding dependencies to the Domain Model, then creating Conformance Classes and adding dependencies to the Units Of Functionality.
In the latest process, there should be a step between with the conformance options.

<iframe width="560" height="315" src="https://www.youtube.com/embed/VSJgHwGJFy8" frameborder="0" gesture="media" allowfullscreen></iframe>

If using a number string for the name of the conformance class, include '0' (e.g. 01 02) because the documentation sorts alphabetically and 10 comes before 2.

The scripts for the Standard Documentation auto-generate the matricies therefore, this step is only needed for generating quick reports.
Clause 6 includes simple matrices for UoF-DM, CO-UoF and CC-CO, but also a nested representation (see below).

.. figure:: /images/howto/ht_cc_doc01.png

        Standard Documentation for Clause 6: Conformance Requirements

<iframe width="560" height="315" src="https://www.youtube.com/embed/2gFocap8u0I" frameborder="0" gesture="media" allowfullscreen></iframe>

.. contents:: The modelling steps in this section are:
                :local:

.. figure:: /images/common/comingsoon.png

Video; How to add a validation constraint to the Domain model template

The video shows creating a validation constraint on a template. The example is using the Domain Model but it is equally applicable to the other layers.

<iframe width="560" height="315" src="https://www.youtube.com/embed/0uVqXwTfV0c" frameborder="0" gesture="media" allowfullscreen></iframe>

display of constraints on BDD - only the name

.. figure:: /images/howto/ht_vc_showname.png

        set "Constraint Text mode" to "Name"

text of this section

Add descrition - it is suggested that this is the same as the "Validation Rule - Error Message". If more description is needed see :doc:`howtoDescription` for details

Add descrition - it is suggested that this is the same as the "Validation Rule - Error Message". If more description is needed see 

Add the constraint from the specification window (rather than from the containment tree) as this will automatically
set the "Constrained Element" property

Some Examples

* Check that one property value does not equal another property value (Parent[1] Child[1])::

        self.Parent <> self.Child

* Check for simple circularities in single elements (InheritsFrom[0..1])::

        self.InheritsFrom <> self

* Check for simple circularities in a collection (InOrganization[0..*])::

        self.InOrganization->excludes(self)

* Check that a property value is not also in a property collection (Element[0..*] BreakdownOf[1])::

        self.Element->forAll(e | self.BreakdownOf <> e)

        [Note: syntax error if try to use self.Element->excludes(self.BreakdownOf)]

* Check that two collections of property values are mutually exclusive (Manages[0..*] Inputs[0..*])::

        self.Manages->forAll(m | self.Inputs->forAll(i | i  <> m))

Check that one property value does not equal another property value (Parent[1] Child[1])::

      self.Parent <> self.Child

Check that one property value does not equal another property value (Parent[1] Child[1]):

Check for simple circularities in single elements (InheritsFrom[0..1])::

      self.InheritsFrom <> self

Check for simple circularities in single elements (InheritsFrom[0..1]):

Check for simple circularities in a collection (InOrganization[0..*])::

      self.InOrganization->excludes(self)

Check for simple circularities in a collection (InOrganization[0..*]):

Check that a property value is not also in a property collection (Element[0..*] BreakdownOf[1])::

      self.Element->forAll(e | self.BreakdownOf <> e)

      [Note: syntax error if try to use self.Element->excludes(self.BreakdownOf)]

Check that a property value is not also in a property collection (Element[0..*] BreakdownOf[1]):

self.Element->forAll(e | self.BreakdownOf <> e)

[Note: syntax error if try to use self.Element->excludes(self.BreakdownOf)]

Check that two collections of property values are mutually exclusive (Manages[0..*] Inputs[0..*])::

      self.Manages->forAll(m | self.Inputs->forAll(i | i  <> m))

Check that two collections of property values are mutually exclusive (Manages[0..*] Inputs[0..*]):

If the constraint is  an "un-computable constraints that cannot, or cannot reasonably, be written in OCL" then the Specification Language should be set to "English".
The constaint is then known as an "Informal Proposition" and will appear as such in the documentation.

For details on validating against the constraints see :doc:`howtoValidationConstraints`

Current thinking (|TBA|) is that the "query-like" services are modelled as operations on the template.

These should then have constraints defined using :term:`OCL`

C-R-U-D-like services are covered in :ref:`Core Model Services<how_cores_top>`.

) is that the "query-like" services are modelled as operations on the template.

.. figure:: /images/howto/STEParchitectureCore.png

This page uses a simple example to describe how to model the the Domain Model using SysML in MagicDraw 18.4.

.. figure:: /images/howto/STEParchitectureCoreServices.png

This page uses a simple example to describe how to model the the Services for the Core Model using SysML in MagicDraw 18.4.

These are the **C-R-U-D like** services rather than the query-like services which are embedded in the :ref:`Core Model<core_queryservices>` templates.

 services rather than the query-like services which are embedded in the 

(|TBA|) These services are common to all templates in the Core model.

Nameing convention:

* Folders: Capitalized with spaces
* Data planning objects: Capitalized with spaces
* Properties – allow either: unnamed or all lower case with spaces

Colour - single model - anything, or like other simgle model BDD

Properties – allow either: unnamed or all lower case with spaces

.. figure:: /images/howto/STEParchitectureCM.png

This page uses a simple example to describe how to model the the Application Data Planning Model using SysML in MagicDraw 18.4.

#. create a new package (no longer needed)

.. figure:: /images/howto/DM_addnewpackage.png

        Adding a new Package for the Template

#. Add a block

.. figure:: /images/howto/DM_addnewtemplate.png

        Adding a new Block

This adds a new block in the tree. This should be renamed.

#. Add diagram to the package and add the template

.. figure:: /images/howto/DM_addnewdiagram.png

        Adding a new diagram

Add a new diagram and rename this to "Template"

Add a stylesheet (|tbd|)

Drag the template onto the diagram

.. figure:: /images/howto/DM_addtemplatetodiagram.png

        Adding a Template to a diagram

Add owner above

.. figure:: /images/howto/ht_common_displayNamespace.png

        Add Owner **Above Element Name**

Change colours

C-R-U-D-like services are covered in :ref:`Domain Model Services<how_dms_top>`.

comment - moved to mapping to Core
-----------------
Adding Contraints

.. tip::

        .. comment Email Phil Spiby, Kevin Le Tutor 6th Sept 2017

        In |MD| to type the contraint parameter, first remove constraint parameter stereotype, then set the type needed, then reset constraint parameter stereotype.

        The default behaviour in |MD| is set up for the internal evaluation engine which can only deal with value properties.

.. |assCeg| image:: /images/16sysmlConstructs/what_sysML_constructs_assCeg.png
   :scale: 100%
   :align: middle

The properties and associations are closely coupled. When creating assocations, the properties are automatically created, and the
name of the assocation ends are the same as the property names. The type of assocation imacts the property type. The following
lists the type of assocations used and the resultant properties.

.. |assA| image:: /images/16sysmlConstructs/what_sysML_constructs_assA.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assA.png

.. |assAeg| image:: /images/16sysmlConstructs/what_sysML_constructs_assAeg.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assAeg.png

1 and 2 exist independently

* If 1 is removed, 2 not removed
* If 2 is removed, 1 not removed, but the property
  is removed (or broken-link)
* 1 and 2 can be updated independently

If 2 is removed, 1 not removed, but the property
is removed (or broken-link)

RequirementSource has a single Reference Property called “Source” of
type RequirementSourceSelect (e.g. Document)

There can be zero or many RequirementSource with the “Source” reference
property pointing to the same Document

.. |assB| image:: /images/16sysmlConstructs/what_sysML_constructs_assB.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assB.png

.. |assBeg| image:: /images/16sysmlConstructs/what_sysML_constructs_assBeg.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assBeg.png

2 exists as part of 1

* If 1 is removed, 2 is also removed
* If 2 is removed, 1 not removed
* 2 can only be updated through an update of 1
* 2 can only be accessed (CRUD) through 1

RequirementView has one or more Part Properties called
“DefinitionalRepresentations” of type PropertyValue

There can be zero or one RequirementView with the
“DefinitionalRepresentations” part property pointing to the same
PropertyValue

If RequirementView is removed, PropertyValue is also automatically
removed.

As PropertyValue is part of RequirementView, it can only be accessed
(read/update/delete) through accessing RequirementView – i.e. to update
or delete the property means an update to the view

.. |assD| image:: /images/16sysmlConstructs/what_sysML_constructs_assD.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assD.png

.. |assDeg| image:: /images/16sysmlConstructs/what_sysML_constructs_assDeg.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assDeg.png

1 exists as part of 2

* If 1 is removed, 2 is not removed
* If 2 is removed, 1 is also removed
* 1 can only be updated through an update of 2
* 1 can only be accessed (CRUD) through 2

RequirementSource has a single Reference Property called “SourcedRequirement”
of type RequirementView

There can be zero or many RequirementSource with the “SourcedRequirement”
reference property pointing to the same RequirementView

If RequirementSource is removed, RequirementView is not removed.

If RequirementView is removed, RequirementSource is also automatically removed

As RequirementSource is part of RequirementView, it can only be accessed
(read/update/delete) through accessing RequirementView – i.e. to update or
delete the RequirementSource means an update to the RequirementView

.. |assE| image:: /images/16sysmlConstructs/what_sysML_constructs_assE.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assE.png

.. |assEeg| image:: /images/16sysmlConstructs/what_sysML_constructs_assEeg.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assEeg.png

One of the Reference Properties is read only (rule for
STEP Extended Architecture)

* If 1 is removed, 2 is not removed but the property is removed
* If 2 is removed, 1 is not removed but the property is removed

Person has zero or many read-only Reference Properties called
“AssociatedOrganizations” of type PersonInOrganization

There can be only one Person with the “AssociatedOrganizations” reference property
pointing to the same PersonInOrganization

PersonInOrganization has one Reference Property called “AssociatedPerson” of type
Person

If a Person is removed, the PersonInOrganization(s) are not removed and vice versa.

.. |assF| image:: /images/16sysmlConstructs/what_sysML_constructs_assF.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assF.png

.. |assFeg| image:: /images/16sysmlConstructs/what_sysML_constructs_assFeg.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assFeg.png

Either the Part Property of the Reference Properties is read
only (rule for STEP Extended Architecture)

RequirementVersion has zero or many Part Properties called “Views” of type
RequirementView

There can be only one RequirementVersion with the “Views” part property pointing to
the same RequirementView

RequirementView has one read-only Reference Property called “ViewOf” of type
RequirementVersion

If a RequirementVersion is removed, the RequirementViews(s) is also automatically
removed.

If a RequirementView is removed, RequirementVersion is not removed but the
PartProperty is removed

As RequirementView is part of RequirementVersion, it can only be accessed
(read/update/delete) through accessing RequirementVersion – i.e. to update or delete
the RequirementView means an update to the RequirementVersion

.. |assC| image:: /images/16sysmlConstructs/what_sysML_constructs_assC.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assC.png

image:: /images/16sysmlConstructs/what_sysML_constructs_assCeg.png

DistributionValueInstance has one or more Value Properties called “Type” of
type DistributionTypeEnum

If DistributionValueInstance is removed, DistributionTypeEnum is also
automatically removed.

If DistributionTypeEnum is removed, DistributionValueInstance is not removed

As DistributionTypeEnum is part of DistributionValueInstance, it can only be
accessed (read/update/delete) through accessing DistributionValueInstance –
i.e. to update or delete the property means an update to the view

A subtype can redefine a property of a supertype. This is usually to change the multiplicity, but may also be to make it a fixed value.

in **Redefined Property** select the property from the supertype

.. figure:: /images/howto/ht_dm_derived02.png

        Redefined property set to readonly with a default

Assuming the property is of type **ClassSelect** and the value is in the reference data, then create a new InstanceSpecification (on the Instances BDD diagram)

     a. Select **ExternalOwlClass" for the **Classifier**

     .. figure:: /images/howto/ht_dm_derived03.png

             InstanceSpecification of ExternalOwlClass

     b. Add a suitable name e.g. ActivityHappeningRelationshipClass
     c. double-click to open the **Specification of Instance Specification properties** dialog
     d. Click on the **slots**
     e. Select **name** and **Remove Value**

     .. figure:: /images/howto/ht_dm_derived04.png

             Remove name slot

     f. Select **Class** and **Create Value**
     g. Select **Edit Value** and click in the **Value** property.
     h. Click on the **-** icon to remove the 0.0 value
     i. Click on the **+** icon and select **Literal String**

     .. figure:: /images/howto/ht_dm_derived05.png

             Add the Class slot as a Literal String

     j. Type in the Reference data URI e.g. for ActivityHappeningRelationship use http://standards.iso.org/iso/10303/-4000/tech/refdata/core_v1#833eaad0-130a-0135-b552-598f1b1392ae

     .. figure:: /images/howto/ht_dm_derived06.png

             InstanceSpecification with Reference Data URI

 and the value is in the reference data, then create a new InstanceSpecification (on the Instances BDD diagram)

.. figure:: /images/howto/ht_dm_derived03.png

        InstanceSpecification of ExternalOwlClass

double-click to open the **Specification of Instance Specification properties** dialog

.. figure:: /images/howto/ht_dm_derived04.png

        Remove name slot

.. figure:: /images/howto/ht_dm_derived05.png

        Add the Class slot as a Literal String

Type in the Reference data URI e.g. for ActivityHappeningRelationship use http://standards.iso.org/iso/10303/-4000/tech/refdata/core_v1#833eaad0-130a-0135-b552-598f1b1392ae

Type in the Reference data URI e.g. for ActivityHappeningRelationship use 

.. figure:: /images/howto/ht_dm_derived06.png

        InstanceSpecification with Reference Data URI

Return to the redefined property, and click on **...** to the right of **Default Value**. Then select the new InstanceSpecification

     .. figure:: /images/howto/ht_dm_derived07.png

             Default Value set to the InstanceSpecification

.. figure:: /images/howto/ht_dm_derived07.png

        Default Value set to the InstanceSpecification

If the property is shown inside the block, the default value will be shown.

.. figure:: /images/howto/ht_dm_derived01.jpg

        Redefined property set to readonly with a default on diagram

Abstract blocks are not instantiated, but are used to isolate common features that are then inherited by other blocks.

text for this section

see :ref:`Blocks<how_dm_blocks>`
then set abstract=true

These are also known as "Select Types" in the :term:`EXPRESS` language.

When a part or reference property can have a value of one of several different types of object, then an **abstract Auxiliary Block** is used.
All the applicable types should be made subtypes of this auxiliary.

When a part or reference property can have a value of one of several different types of object, then an 

 is used.

For example in AP243 an "Assumption" has a reference property "Context" [1], but this item can be of many types. Therefore an auxiliary called "AssumptionContextItem"
is created and the applicable items such as Identifiableobject are made subtypes of this auxiliary.

.. figure:: /images/howto/ht_dm_auxillary_bdd.png

        Adding a Auxiliaries (or SelectTypes) for use by Template properties

Adding a Auxiliaries (or SelectTypes) for use by Template properties

Optionally the auxiliaries can be stored in a separate package to make them easier to identify as auxiliaries in the model tree.

Often a naming convention is also used to aid identification, though this is only for human understanding. Many of the :term:`AP` s use the
convention of having "Select" or "Item" as the last word in the name.

Often a naming convention is also used to aid identification, though this is only for human understanding. Many of the 

 s use the

Auxiliary (in UML) means that this type of class (block) is not directly needed for implementation, therefore they should not have properties.
If properties are added they will be ignored in the implementation models (e.g. in the XML schemas).

Abstract blocks (not Auxiliary) can be used to isolate common features of blocks.

It is possible to add operations to Auxiliaries to indicate where common query services are needed. These are treated as implementation hints.

Add a name that reflects the intended use (no official convention)

Open the specification

     * set to abstract.
     * add stereotype Auxiliary.

Drag onto the block definition diagram and change colour to green - the default (See |colours| for RGB.)

Drag onto the block definition diagram and change colour to green - the default (See 

From the Edit Compartments menu, Stereotypes tab, hide the <<block>> stereotype.

Add generalization from the applicable blocks to the auxiliary.

.. figure:: /images/howto/ht_dm_auxillary.png

        Auxiliaries (or SelectTypes) specification

#. Add Enumeration
#. Add Enumeration Literals for the enumerations, using lower_snake_case [- need to add the rdf - part of he mapping)
#. Add Base Classifier from the Data Types e.g. String or Real (not sure how to do this as cannot select from tree)
#. add the **Applied Stereotype** for **ValueType** (this must be done at the end becuase cannot add EnumerationLiterals to a ValueType)
        * to add more EnumerationLiterals the ValueType Applied Stereotype must be removed, the enumeration added and the stereotype replaced.
#. Add Documentation and/or Reference Data (see :ref:`how_dmcore_single_classification` for choice of UUID. If not already Reference data, suggest use the UUID of the Enumeration Literal)
        * The Reference data for an enumeration can be either reference data classes or named individuals depending on whether it is mapped to Class/ClassSelect or Proxy/ProxyItemSelect respectively

.. figure:: /images/howto/ht_dm_enumRefData.png

        Reference data added to an enumeration.

Add Enumeration Literals for the enumerations, using lower_snake_case [- need to add the rdf - part of he mapping)

Add Base Classifier from the Data Types e.g. String or Real (not sure how to do this as cannot select from tree)

add the **Applied Stereotype** for **ValueType** (this must be done at the end becuase cannot add EnumerationLiterals to a ValueType)
     * to add more EnumerationLiterals the ValueType Applied Stereotype must be removed, the enumeration added and the stereotype replaced.

* to add more EnumerationLiterals the ValueType Applied Stereotype must be removed, the enumeration added and the stereotype replaced.

 (this must be done at the end becuase cannot add EnumerationLiterals to a ValueType)

to add more EnumerationLiterals the ValueType Applied Stereotype must be removed, the enumeration added and the stereotype replaced.

Add Documentation and/or Reference Data (see :ref:`how_dmcore_single_classification` for choice of UUID. If not already Reference data, suggest use the UUID of the Enumeration Literal)
     * The Reference data for an enumeration can be either reference data classes or named individuals depending on whether it is mapped to Class/ClassSelect or Proxy/ProxyItemSelect respectively

* The Reference data for an enumeration can be either reference data classes or named individuals depending on whether it is mapped to Class/ClassSelect or Proxy/ProxyItemSelect respectively

 for choice of UUID. If not already Reference data, suggest use the UUID of the Enumeration Literal)

The Reference data for an enumeration can be either reference data classes or named individuals depending on whether it is mapped to Class/ClassSelect or Proxy/ProxyItemSelect respectively

Prerequistes

Descriptions should be added to all packages, blocks (including auxiliaries), Enumerations, public properties and constraints.

The |WG12 Review Checklist| states **"204. The definition of each EXPRESS/SysML construct is unambiguous and understandable, grammatically correct, and defines
the concept (not simply restates the EXRESS/SysML)"**.

**"204. The definition of each EXPRESS/SysML construct is unambiguous and understandable, grammatically correct, and defines
the concept (not simply restates the EXRESS/SysML)"**

"204. The definition of each EXPRESS/SysML construct is unambiguous and understandable, grammatically correct, and defines
the concept (not simply restates the EXRESS/SysML)"

See :ref:`Supplementary Directives<ht_desc_directives>` for the official directives.

Text in General
The following table summarises the do's and dont's for the text of descriptions and definitions.

+------------------------------------------+-----------------------------------------------------------+------------------------------------+
| do use...                                | don't use...                                              | see also                           |
+==========================================+===========================================================+====================================+
|  "instances of <entity name>"            | plural e.g. <entity name>s                                | :ref:`ht_desc_directives_plurals`  |
| "shall" "shall not"                      | "is required to" "only...is permitted" "must" "most not"  | :ref:`ht_desc_directives_wording`  |
| "should" "should not"                    | "is recommended that..." "ought to..."                    | :ref:`ht_desc_directives_wording`  |
| "may" "need not"                         | "is permitted" "is allowed"                               | :ref:`ht_desc_directives_wording`  |
| (i.e. permissable in limits of standard) |                                                           | :ref:`ht_desc_directives_wording`  |
| "can" "cannot"                           | "to be able to" "it is possible to"                       | :ref:`ht_desc_directives_wording`  |
| (i.e. something that is possible)        |                                                           |                                    |
| <note></note> ot "that is"               | "i.e."                                                    | :ref:`ht_desc_directives_wording`  |
| <example></example>                      | "e.g." "etc" ("for example" )                             | :ref:`ht_desc_directives_wording`  |
|                                          | and/or                                                    | :ref:`ht_desc_directives_avoid`    |
| datum <xyz>s (e.g. datum points)         | datums                                                    | :ref:`ht_desc_directives_avoid`    |
| use                                      | utilise                                                   | :ref:`ht_desc_directives_avoid`    |
| that is                                  | which is                                                  | :ref:`ht_desc_directives_frequent` |
| data are                                 | data is                                                   | :ref:`ht_desc_directives_frequent` |
| between = 2                              |                                                           | :ref:`ht_desc_directives_frequent` |
| among = 2 or more than 2                 |                                                           |                                    |
| better english examples are:             | sentences ending in "at" "to" "with" "from" "of" "on"     |                                    |
| "...to which XYZ belongs."               |   "...that XYZ belongs to."                               |                                    |
| "...with which the XYZ is associated."   |   "...the XYZ is associated with."                        |                                    |
| "...the XYZ used to refer to the ABC."   |   "...the XYZ by which the ABC is referred to."           |                                    |

.. tip::

        Care should be taken with Carridge-Return (&#13;) and Line-Feed (&#10;)as both these will introduce a new paragraph in the documentation for the standard.

        Different SysML tools will use the characters differently, so when porting models between tools what was visible as a new line in one tool may appear differently in another.

.. important::

        If using any of the tags described below, the result must be **well formed xml**, e.g. <br/> should be used rather than <br>.

better english examples are:
"...to which XYZ belongs."
"...with which the XYZ is associated."
"...the XYZ used to refer to the ABC."

sentences ending in "at" "to" "with" "from" "of" "on"
"...that XYZ belongs to."
"...the XYZ is associated with."
"...the XYZ by which the ABC is referred to."

Care should be taken with Carridge-Return (&#13;) and Line-Feed (&#10;)as both these will introduce a new paragraph in the documentation for the standard.

Different SysML tools will use the characters differently, so when porting models between tools what was visible as a new line in one tool may appear differently in another.

If using any of the tags described below, the result must be **well formed xml**, e.g. <br/> should be used rather than <br>.

Blocks and Constraint Blocks (description)
The text should use complete sentences and shall state clearly the following:

* the concept that the entity data type represents;
* the information about the concept that is represented in the data structure and constraints defined by the entity data type;
* the phrase “an <EntityName> is/represents …” may be used as a short hand for “An instance of the <EntityName> entity data type is/represents …”

        * if this convention is used it shall be used consistenty;
        * if this convention is used, the convention itself shall be described in the introduction of the standard.

the information about the concept that is represented in the data structure and constraints defined by the entity data type;

the phrase “an <EntityName> is/represents …” may be used as a short hand for “An instance of the <EntityName> entity data type is/represents …”

      * if this convention is used it shall be used consistenty;
      * if this convention is used, the convention itself shall be described in the introduction of the standard.

if this convention is used, the convention itself shall be described in the introduction of the standard.

Properties and Constraints (definition)
The text is a fragment of a sentence that can be used in place of the name of the property (as done in clause 3 "Terms and Definitions").

* All **optional** properties shall conclude with the sentence: **The value of this attribute need not be specified.**

All **optional** properties shall conclude with the sentence: **The value of this attribute need not be specified.**

Examples and Notes
See also :ref:`ht_desc_directives_examples` and :ref:`ht_desc_directives_notes`

* should come after the main text;
* can be in any order;
* should not be numbered, the number is added by the documentation scripts;
* Examples: **<example>...</example>**:

        * Provided to clarify the concept that is represented by the entity data type or to illustrate the population of the entity data type and its attributes. It shall be clear whether each example refers to the concept represented by the entity data type or the data that is governed by the entity data type.

* Notes: **<note>...</note>**:

        * information that is essential to the reader understanding the document can include references to other sources;

* for example::

        <note>This is the first note.</note>
        <note>This is the second note.</note>
        <example>This is the first example.</example>

should not be numbered, the number is added by the documentation scripts;

Examples: **<example>...</example>**:

      * Provided to clarify the concept that is represented by the entity data type or to illustrate the population of the entity data type and its attributes. It shall be clear whether each example refers to the concept represented by the entity data type or the data that is governed by the entity data type.

Provided to clarify the concept that is represented by the entity data type or to illustrate the population of the entity data type and its attributes. It shall be clear whether each example refers to the concept represented by the entity data type or the data that is governed by the entity data type.

Notes: **<note>...</note>**:

      * information that is essential to the reader understanding the document can include references to other sources;

information that is essential to the reader understanding the document can include references to other sources;

for example::

      <note>This is the first note.</note>
      <note>This is the second note.</note>
      <example>This is the first example.</example>

<note>This is the first note.</note>
<note>This is the second note.</note>
<example>This is the first example.</example>

Figures and Tables
See also :ref:`ht_desc_directives_figures` and :ref:`ht_desc_directives_tables`

* These are contained in a **<figuresysml></figuresysml>**, **<figure></figure>** or **<table></table>**;
* image location:

        * **figure** and **table** include a **<name></name>** tag that has the relative path from the Domain model html file to the image;
        * **figuresysml** includes an **<id></id>** tag that is the xmi:id of the diagram in the sysml model.

* They include text that is the table or figure label **only first word capitalized**;
* If they are essential to the understanding they must be referenced in the normative text of the definition so that it is itself normative.
* If they enhance but are not essential to the understanding they shall be referenced from a suitable note or example so that it is itself informative.

        <figuresysml><id>_18_4_1_6b1022a_1570541486114_761677_40761</id>Label for the figure</figuresysml>
        <figure><name>../imagename.png</name>Label for the figure</figure>
        <table><name>../imagename.png</name>Label for the table</table>

These are contained in a **<figuresysml></figuresysml>**, **<figure></figure>** or **<table></table>**;

image location:

      * **figure** and **table** include a **<name></name>** tag that has the relative path from the Domain model html file to the image;
      * **figuresysml** includes an **<id></id>** tag that is the xmi:id of the diagram in the sysml model.

**figure** and **table** include a **<name></name>** tag that has the relative path from the Domain model html file to the image;

 tag that has the relative path from the Domain model html file to the image;

**figuresysml** includes an **<id></id>** tag that is the xmi:id of the diagram in the sysml model.

They include text that is the table or figure label **only first word capitalized**;

If they are essential to the understanding they must be referenced in the normative text of the definition so that it is itself normative.

If they enhance but are not essential to the understanding they shall be referenced from a suitable note or example so that it is itself informative.

      <figuresysml><id>_18_4_1_6b1022a_1570541486114_761677_40761</id>Label for the figure</figuresysml>
      <figure><name>../imagename.png</name>Label for the figure</figure>
      <table><name>../imagename.png</name>Label for the table</table>

<figuresysml><id>_18_4_1_6b1022a_1570541486114_761677_40761</id>Label for the figure</figuresysml>
<figure><name>../imagename.png</name>Label for the figure</figure>
<table><name>../imagename.png</name>Label for the table</table>

The xmi:id of a diagram can be obtained using a macro. See also :ref:`gs_md_macros` for how to load a macro.

.. figure:: /images/howto/ht_desc_idForFiguresysml.png

        Run "Get UUID" macro to see the ID and the UUID

The xmi:id of a diagram can be obtained using a macro. See also 

Lists
Bulleted lists use standard HTML notation of ul and li tags (see also :ref:`ht_desc_directives_lists`)

* the ";" (all but last) and "." (last) must be included.

        <ul><li>first bullet;</li><li>second bullet.</li></ul>

Bulleted lists use standard HTML notation of ul and li tags (see also 

      <ul><li>first bullet;</li><li>second bullet.</li></ul>

Fixed hyperlinks
For hyperlinks not auto-generated from the entity and attribute names (see also :ref:`ht_desc_directives_refs`)

* These are contained in **<a></a>**
* They include a <path></path> tag that has the relative path from the Domain model html file to the file, or an http href,
* The include the text to be displayed.
* For Example:

        <a><path>5_main.htm#study</path>Clause 5</a>
        <a><path>https://www.iso.org</path>iso.org</a>.<br/>

For hyperlinks not auto-generated from the entity and attribute names (see also 

They include a <path></path> tag that has the relative path from the Domain model html file to the file, or an http href,

For Example:

      <a><path>5_main.htm#study</path>Clause 5</a>
      <a><path>https://www.iso.org</path>iso.org</a>.<br/>

Example
The following is an example of a formatted description where "Foo" and "Bar" are blocks in the model::

        A Foo is a type of Bar that is used as a placeholder. See also <a><path>5_main.htm#study</path>internal links</a>
        or <a><path>https://www.iso.org</path>external links</a>. It is has a bulleted list:<br/>
        <note>This is the first note referencing a figure (see following Figure).</note>
        <example>This is the first example referecing the table which is infact an image (see following Table).</example><br>
        <figure><name>sys/picturesAnnex/inverseCompositeAggregation.png</name>The title for the figure</figure><br>
        <table><name>sys/script/img/tables.png</name>The title for the table</table>
        <figuresysml><id>_18_4_1_6b1022a_1570541486114_761677_40761</id>Block Definition Diagram of the Activity CTC</figuresysml>

The following is an example of a property description where "Widget" is a block in the model::

        specifies the Widget for the Foo. The value of this attribute need not be specified.

The following shows how the example will look in the standard

.. figure:: /images/howto/ht_desc_result.png

        How the example formatted description is displayed in the documentation

The following is an example of a formatted description where "Foo" and "Bar" are blocks in the model:

A Foo is a type of Bar that is used as a placeholder. See also <a><path>5_main.htm#study</path>internal links</a>
or <a><path>https://www.iso.org</path>external links</a>. It is has a bulleted list:<br/>
<ul><li>first bullet;</li><li>second bullet.</li></ul>
<note>This is the first note referencing a figure (see following Figure).</note>
<example>This is the first example referecing the table which is infact an image (see following Table).</example><br>
<figure><name>sys/picturesAnnex/inverseCompositeAggregation.png</name>The title for the figure</figure><br>
<table><name>sys/script/img/tables.png</name>The title for the table</table>
<figuresysml><id>_18_4_1_6b1022a_1570541486114_761677_40761</id>Block Definition Diagram of the Activity CTC</figuresysml>

The following is an example of a property description where "Widget" is a block in the model:

specifies the Widget for the Foo. The value of this attribute need not be specified.

How the example formatted description is displayed in the documentation

The Application Domain model is the :term:`AP` view of the Core model.

The Application Domain model is the layer of the information model that describes the information requirements and constraints
of a specific application context.

The Application Domain model is a specific view of constrained selection and of the Core model controlled by the requirement
of the Conceptual model in order to fulfil the Application Protocol requirements.

.. figure:: /images/howto/STEParchitectureDM.png

                :depth: 1
                :local:

Comments that are not to be included in the Standard Documentation should be stereotyped to <<Problem>> or <<Rationale>>.

If the problem comment is added to a diagram the Stereotype can be added at the time the object is created by selecting the "Problem" or "Ratioinale" from the menu.
Existing comments can be converted to a "Problem" or "Rationale" by adding the stereotype in the specification window.

Problem and Rationale comments can be added directly to objects (e.g. packages, blocks etc) by adding a comment and then adding the stereotype in the specification window.

.. figure:: /images/howto/ht_comment_problem.png

        <<Problem>> stereotype on a comment

Diagrams; How to - Block Definition diagrams for the Domain Model

The diagram has a recommended maximum size of 1300px x 620px (to fit on a typical laptop screen without scrolling) and an absolute maximum size of 4960px x 3508px (A3 print at 300PPI). The following table summarises the recommended sizes for the number of elements assuming landscape.

A small gap (e.g. one grid square) should be allowed between the edge of the diagram and the elements. (This is because some SysML tools resize the diagram to enforce a gap.)

The fonts should not be changed from the default, this is controlled by the shared SysML modules (the ISO directives state 8-11pt and the |MD| default is 11);

The fonts should not be changed from the default, this is controlled by the shared SysML modules (the ISO directives state 8-11pt and the 

internal padding after source/pages/howto/howtoDiagramsCommon.txt

The following are rules applicable to layout and formatting of elements in Block Definition Diagrams:

The element or elements that are the subject of the diagram should ideally be in the centre of the diagram and the most obvious on first glance;

The Block entities should not display their stereotype all other type should be displayed e.g. <<Auxiliary>> (SelectTypes) and <<Value Type>> (Enumerations);

Links to related diagrams should be added where useful, by adding the icon - located to minimise disruption to the imact to the diagram. The recommended practise is to wrap the text and position the diagram in the corner of a block.

.. figure:: /images/common/construction.png

        Links to related diagrams

Where there are multiple generalization relationships to a single element in a diagram, these should be overlayed at the destination (target).

.. figure:: /images/howto/ht_dm_bdd_overlay.png

        Overlay Destination where multiple links

Layout of "members" diagrams, where there are too many specializations to make the above overlay method impractical, should use an alphabetical
grid layout with the Auxiliary displayed surrounding the members.

      * Place the members on the diagram
      * Select all those that are in a different package from the Auxiliary and change the symbol properties for **Show Owner** to **Above Element Name** (from the "All" set of commands)
      * Change the symbol properties to enable **Wrap Words** (from the "All" set of commands)
      * Make same size
      * Layout - Layout Grid Style
      * Place the Auxiliary on the diagram and adjust size so it covers the members

Select all those that are in a different package from the Auxiliary and change the symbol properties for **Show Owner** to **Above Element Name** (from the "All" set of commands)

Select all those that are in a different package from the Auxiliary and change the symbol properties for 

Change the symbol properties to enable **Wrap Words** (from the "All" set of commands)

Place the Auxiliary on the diagram and adjust size so it covers the members

.. figure:: /images/howto/ht_dm_bdd_aux.png

        Layout when many members (this example is for illustration, the grid layout is not nessary and the overlay above would be more appropriate)

Layout when many members (this example is for illustration, the grid layout is not nessary and the overlay above would be more appropriate)

This video is out of date. It shows the steps from PLCSlib using Magicdraw 17.4

This video explains what a template is, how it is represented and basic creation and completion tasks

<div><video width="695" height="530" controls src="http://plcslib.sourceforge.net/docs/plcslib_videos/webinars/TemplateOverview/TemplateOverview.mp4"></div>

This video show how to creating the template block and identifying public properties

<div><video width="695" height="530" controls src="http://plcslib.sourceforge.net/docs/plcslib_videos/webinars/TemplateDetail1/TemplateDetail1.mp4"></div>

step by step when aam uses data planning objects as conveyed information

how to model the mapping between the activity and data planning models of steplib

<iframe width="560" height="315" src="https://www.youtube.com/embed/7cIsy3k57Mc" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
<br/>
<br/>

Step by step when AAM uses Data Planning objects as Conveyed Information

.. figure:: /images/howto/STEParchitectureAAMtoCM.png

The mapping between the |AAM| and |ADPM| is achieved using Data Planning objects as the conveyed information on
object flows between activities in the |AAM|. This is described in :ref:`how_aam_top`

 is achieved using Data Planning objects as the conveyed information on
object flows between activities in the 

Some |AAM| have conveyed information defined as blocks in the model. These blocks
are mapped to the blocks in the |ADPM|. This is shown in a (rough) video

 have conveyed information defined as blocks in the model. These blocks
are mapped to the blocks in the 

protected rather than private on the superclass (TBC)

see also :ref:`how_dmcore_redefined`

how to model the mapping between the domain and core models of steplib

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.

,
The 

.. figure:: /images/howto/ht_dmcore_constraint01.png

        Example for using a constraint

<iframe width="560" height="315" src="https://www.youtube.com/embed/BzGUeA6mgIA" frameborder="0" gesture="media" allowfullscreen></iframe>

**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 <how_dmcore_use_constraint>`

* if yes, then skip these steps and go on to :ref:`Using a Constraint <how_dmcore_use_constraint>`

if yes, then skip these steps and go on to :ref:`Using a Constraint <how_dmcore_use_constraint>`

Create a new **Constraint Block**
     .. figure:: /images/howto/ht_dmcore_constraint02.png

.. figure:: /images/howto/ht_dmcore_constraint02.png

Add **Constraint Parameters**
     .. figure:: /images/howto/ht_dmcore_constraint04.png

.. figure:: /images/howto/ht_dmcore_constraint04.png

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

* remove constraint parameter stereotype
* set the type needed
* reset constraint parameter stereotype

.. figure:: /images/howto/ht_dmcore_constraint03.png

For the **output** Constraint Parameters set the **Is Read Only** to true

     .. figure:: /images/howto/ht_dmcore_constraint09.png

.. figure:: /images/howto/ht_dmcore_constraint09.png

Edit the **specification** "{}", using **Language** of **OCL2.0**
     .. figure:: /images/howto/ht_dmcore_constraint05.png

.. figure:: /images/howto/ht_dmcore_constraint05.png

This video does not hide the constraint on the constraint property.

See the detailed steps for the correct display.

<iframe width="560" height="315" src="https://www.youtube.com/embed/vah-jvPN1Eo" frameborder="0" gesture="media" allowfullscreen></iframe>

Specify the **Type** to be an existing Constraint Block
     .. figure:: /images/howto/ht_dmcore_constraint06.png

.. figure:: /images/howto/ht_dmcore_constraint06.png

Display the Parameters
     .. figure:: /images/howto/ht_dmcore_constraint07.png

.. figure:: /images/howto/ht_dmcore_constraint07.png

Add **Binding Connectors** between the parameters and elements on the diagram

.. figure:: /images/howto/ht_dmcore_constraint08.png

comment

===========
Other tasks

------------------
Publication to XMI

.. todo::

        to do video, see :ref:`video <how_dmcore_video1>`

.. todo::

        the step-by-step for this section

----------------
Export of images

.. todo::

        to do, see :ref:`how_dmcore_video1`

.. todo::

Domain Model; How to - Missing mandatory properties in mapping to Core

Application Domain Model; How to - Missing mandatory properties in mapping to Core

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 some cases the template in the lower layer has compulsory properties that are not present in the upper layer. When this happens a 

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.

the upper layer will not have a name. This is resolved by creating a 

 and using a constraint that will use this if the input is not provided. This is

.. figure:: /images/howto/ht_dmcore_dummy.png

Application Domain Model; How to - Redefined properties mapping to Core

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

The steps are:

#. Drag the inherited part property onto the diagram

        .. figure:: /images/howto/ht_dmcore_refactor01.png

#. **Refactor > Redefine To** and select the subtype

        .. figure:: /images/howto/ht_dmcore_refactor02.png

#. 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

(from https://trello.com/c/ajMU2USq/100-n-standing-doc-method-to-map-subtypes-using-supertype-mapping)

.. figure:: /images/howto/ht_dmcore_protected01.jpg

        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

                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.

See also 

Drag the inherited part property onto the diagram

     .. figure:: /images/howto/ht_dmcore_refactor01.png

.. figure:: /images/howto/ht_dmcore_refactor01.png

**Refactor > Redefine To** and select the subtype

     .. figure:: /images/howto/ht_dmcore_refactor02.png

.. figure:: /images/howto/ht_dmcore_refactor02.png

Add a binding connector

     .. figure:: /images/howto/ht_dmcore_refactor03.png

.. figure:: /images/howto/ht_dmcore_refactor03.png

PS:

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

add a name to the original binding connect (so it can be found in the tree, any text will do)

.. figure:: /images/howto/ht_dmcore_refactor04.png

        Inherited redefined binding connector

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.

Patterns are used to show how a "concept" in one level is represented by objects in the same level.

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

        Exmaple for ContentProperty

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)

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.

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.

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"

**item** for the main object e.g. Document, Part, Activity, Collection, Association, etc

 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

 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

 for when there is also a view-like port e.g. PartView, IndividualPartView, RequirementView, CollectionView etc

Domain Model; How to - Map single Classification using Instances of Reference Data

Application Domain Model; How to - Map single Classification using Instances of Reference Data

Mapping; How to - use Reference Data Instances to map single Classification ADM-Core

Reference Data; How to - use Reference Data Instances to map single Classification ADM-Core

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`

This shows how to add a mapping for a single classification. For more complex, combined and enumeration classification mapping see 

The mapping uses :ref:`how_rd_class` from the :ref:`Reference data <how_rd_top>` 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".

 that is set as the default value of an instance specification . The selected 

 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

(private) Part Property of type Classification
      * Prefix lowerCamelCase for classification string
      * Suffix Classification
      * e.g. modelTypeClassification

* Prefix lowerCamelCase for classification string
* Suffix Classification
* e.g. modelTypeClassification

Reference Property and Instance Specification of type ExternalOwlClass
      * Suffix OwlClass
      * e.g. modelTypeOwlClass

* Suffix OwlClass
* e.g. modelTypeOwlClass

contraint property
      * lowerCamelCase version of Constraint Block

* lowerCamelCase version of Constraint Block

.. figure:: /images/howto/ht_common_classificationNaming.png

        Naming convention for elements used in mapping classifications

comment

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/KyHk3imEaNM" frameborder="0" allowfullscreen></iframe>

<div><video controls src="../../_static/videos/ht_dmcore_AddExternalOWLClassRefData.mp4"></div>

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

     * 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

     * 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

* :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

* 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

* 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

: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`

 copy functionality in Protégé (ctrl-U) can be used to copy the IRI to paste into the slot value (when the STEPlib 

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`

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 

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`

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

* 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

set the **Default Value** to the **Instance Specification** above

set the **multiplicity** ([1] or [0..1] depending on what it is connected to)

In the diagram, display **Compartment** for the **Default Value**
     .. figure:: /images/howto/ht_dmcore_ExtOwl03.png

.. figure:: /images/howto/ht_dmcore_ExtOwl03.png

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

.. figure:: /images/howto/ht_dmcore_ExtOwl05.png

Add a Rationale comment (comment stereotyped to rationale) showing the 

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

* 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

set the multiplicity. This should be either [1] for compulsory objects or [0..1] for optional.

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

.. figure:: /images/howto/ht_dmcore_ExtOwl04.png

 from Classification part property to the Classification in the core element

Domain Model; How to - Map combined Classification using Instances of Reference Data

Application Domain Model; How to - Map combined Classification using Instances of Reference Data

Mapping; How to - use Reference Data Instances to map combined Classification ADM-Core

Reference Data; How to - use Reference Data Instances to map combined Classification ADM-Core

Enumerations; How to - use Reference Data Instances to map as Classification ADM-Core

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.

The colours and naming convention has been updated since this video was created. See 

<iframe width="560" height="315" src="https://www.youtube.com/embed/9Y1oFWlXZBM" frameborder="0" allowfullscreen></iframe>

comment

<div><video controls src="../../_static/videos/ht_dmcore_classification.mp4"></div>

Application Domain Model; How to - Constraints in mapping to Core

Duplicate implicit target name: "classification naming convention".

Hyperlink target "how-dmcore-single-classification" is not referenced.

Hyperlink target "how-dmcore-combined-classification" is not referenced.

Hyperlink target "how-dmcore-create-constraint" is not referenced.

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`.

 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 

.. figure:: /images/howto/ht_dmcore_newdiagram01.png

        Create a new diagram and add the local properties

.. figure:: /images/howto/ht_dmcore_newdiagram02.png

        Selected Properties are shown on the diagram

.. figure:: /images/howto/STEParchitectureDMtoCore.png

This page uses a simple example to describe how to model the mapping between the :ref:`Domain <how_dm_top>` and :ref:`Core <how_core_top>`
models using SysML in MagicDraw 18.4.

This page uses a simple example to describe how to model the mapping between the 

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

        <div><video width="695" height="530" controls src="http://plcslib.sourceforge.net/docs/plcslib_videos/webinars/TemplateDetail2/TemplateDetail2.mp4"></div>

Process for a given "source select" e.g. "ActivityAssignmentSelect":

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.

create a diagram for the select mapping (if it does not already exist)

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

.. figure:: /images/howto/ht_dmcore_select02.png

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?

Diagrams; How to - Parametric Diagrams for mapping Domain to Core

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

For the R-G-B to use for the Domain Model and Core Model entities, and for constraints and flow ports, see |colours|.

For the R-G-B to use for the Domain Model and Core Model entities, and for constraints and flow ports, see 

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.

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|)

These are added to the block as private part properties. (see 

The colours convention has been updated since this video was created. See |colours| for the latest colours.

The colours convention has been updated since this video was created. See 

<iframe width="560" height="315" src="https://www.youtube.com/embed/Z__9ZowgrA0" frameborder="0" allowfullscreen></iframe>

comment

<div><video controls src="../../_static/videos/ht_dmcore_pardiag.mp4"></div>

how to model the mapping between the data planning and domain models of steplib

.. figure:: /images/howto/STEParchitectureCMtoDM.png

This page uses a simple example to describe how to model the mapping between the Data Planning and Domain models using SysML in MagicDraw 18.4.

namedindividual of class (rdf:type rdf:resource) mandatory property

namedindividual preferred label (skos:preflabel) mandatory property

namedindividual change note (skos:changenote) mandatory property

The following explains how the stylesheet extracts the reference data from the AP243 domain model and saves it as OWL. It has also explains the assumptions about the structure and naming
convension used.

The stylesheet starts from a packagedElement that has an attribute name='Domain_model'

The following mapping rules are assumed by the extraction stylesheet:

* All reference data uses either ExternalOwlClass or ExternalOwlObject from the core model as the type

        * search string is set as the "ExternalOwlName" param at the start of the stylesheet

* The same constraint block is used for all combined classifications constraint properties, and the same (out) flow port is bound (using a binding connector) to the
  core model object to be used as the subClassOf

        * the xmi:id of this flow port is set as the param "combinedId" at the start of the stylesheet

* The same (inherited) private part property (named "classifiedAs") is used for all single classifications, and this is bound (using a binding connector) to the core model object
  to be used as the subClassOf

        * the xmi:id of this private part property is set as the "classifiedAsId" param at the start of the stylesheet

* The name of the template reference properrty for classification is "templateOwlClass" (this is used to exclude the template classification from the association classification)

* Enumerations have a property named "value" that is of core model type ExternalOwlClass or ExternalOwlObject

* Where the mapping of status Enumerations is to StateDefinition, a common block is used rather than replicating the mapping for each template.
  The stateSelect property of this is used to identify the status Enumerations

        * the xmi:id of this stateSelect property is set as the "StateSelectId" param at the start of the stylesheet

* For Classification Enumerations, their "value" property is mapped to the property "Class" of the core object "Classification".

        * the string "Classification::Class" is set as the "classificationClassName" param at the start of the stylesheet

* All Enumeration Literals have a slot for the "value" that is set to an Instance Specification

All reference data uses either ExternalOwlClass or ExternalOwlObject from the core model as the type

      * search string is set as the "ExternalOwlName" param at the start of the stylesheet

search string is set as the "ExternalOwlName" param at the start of the stylesheet

The same constraint block is used for all combined classifications constraint properties, and the same (out) flow port is bound (using a binding connector) to the
core model object to be used as the subClassOf

      * the xmi:id of this flow port is set as the param "combinedId" at the start of the stylesheet

the xmi:id of this flow port is set as the param "combinedId" at the start of the stylesheet

The same (inherited) private part property (named "classifiedAs") is used for all single classifications, and this is bound (using a binding connector) to the core model object
to be used as the subClassOf

      * the xmi:id of this private part property is set as the "classifiedAsId" param at the start of the stylesheet

the xmi:id of this private part property is set as the "classifiedAsId" param at the start of the stylesheet

The name of the template reference properrty for classification is "templateOwlClass" (this is used to exclude the template classification from the association classification)

Enumerations have a property named "value" that is of core model type ExternalOwlClass or ExternalOwlObject

Where the mapping of status Enumerations is to StateDefinition, a common block is used rather than replicating the mapping for each template.
The stateSelect property of this is used to identify the status Enumerations

      * the xmi:id of this stateSelect property is set as the "StateSelectId" param at the start of the stylesheet

the xmi:id of this stateSelect property is set as the "StateSelectId" param at the start of the stylesheet

For Classification Enumerations, their "value" property is mapped to the property "Class" of the core object "Classification".

      * the string "Classification::Class" is set as the "classificationClassName" param at the start of the stylesheet

the string "Classification::Class" is set as the "classificationClassName" param at the start of the stylesheet

All Enumeration Literals have a slot for the "value" that is set to an Instance Specification

In AP243 all templates have the ClassifiedAs property. In the mapping to the Core Model this is bound to the ClassifiedAs of the most significant Core model template either
directly or via the "CombinedClassification" constraint block. This is used to identify reference data for the template owl.Class.

The **prefLabel** (and **rdf:about**) is the name of the template block.

The **subClassOf** is identified by the object connected to either the "combined" port of the CombinedClassification constraint block, or connected to the inherited "classifiedAs" property.
The connected object name is found using the |MD| extension tag referenceExtension attribute referentPath

 is identified by the object connected to either the "combined" port of the CombinedClassification constraint block, or connected to the inherited "classifiedAs" property.
The connected object name is found using the 

<owl:Class rdf:about="&AP243-rdl;KeyValueType">
        <skos:prefLabel xml:lang="en">KeyValueType</skos:prefLabel>
        <rdfs:subClassOf rdf:resource="&corev1;Part"/>
        <rdfs:comment xml:lang="en">Defines a key piece of information ...</rdfs:comment>
        ...
</owl:Class>

Enumerations used as classification have their "value" property bound (using a binding connector) to the property "Class" of the core object "Classification".
This is identified using the |MD| extension tag referenceExtension attribute referentPath. The Literals for the status are also owl:Class.

This is identified using the 

 extension tag referenceExtension attribute referentPath. The Literals for the status are also owl:Class.

The following are extracted from the SysML for the Enumeration owl:Class:

The **prefLabel** (and **rdf:about**) is the name of the Enumeration.

The **subClassOf** is identified by locating the objects that have properties that are of the Enumeration type. These are all listed as subClassOf.

 is identified by locating the objects that have properties that are of the Enumeration type. These are all listed as subClassOf.

The following are extracted from the SysML for the Enumeration Literals owl:Class:

The **prefLabel** (and **rdf:about**) is the name of the Instance Specification used as the slot for "value". (This assumes use of the naming convention of enumName_literal_name)

) is the name of the Instance Specification used as the slot for "value". (This assumes use of the naming convention of enumName_literal_name)

The **comment** is the documentation from the Enumeration Literal.

<owl:Class rdf:about="&AP243-rdl;StudyTypeEnum">
        <skos:prefLabel xml:lang="en">StudyTypeEnum</skos:prefLabel>
        <rdfs:subClassOf rdf:resource="&AP243-rdl;Study"/>
        <rdfs:comment xml:lang="en">This is ...</rdfs:comment>
        ...
<!--Enumeration Literal: StudyTypeEnum Literal design InstanceSpecification: studyTypeEnum_design-->
<owl:Class rdf:about="&AP243-rdl;studyTypeEnum_design">
        <skos:prefLabel xml:lang="en">studyTypeEnum_design</skos:prefLabel>
        <rdfs:subClassOf rdf:resource="StudyTypeEnum"/>
        ...

Enumerations mapped to StateDefinition are identifed as those bound (using a binding connector) to the stateStelect property of a common block.
The Literals for the status are owl:NamedIndividual.

The **subClassOf** is hardcoded to AP243-rdl;StatusDefinition which is included at the start of the file.

 is hardcoded to AP243-rdl;StatusDefinition which is included at the start of the file.

The following are extracted from the SysML for the Enumeration Literals owl:NamedIndividual:

The **rdf:about** is the name of the Instance Specification used as the slot for "value". (This assumes use of the naming convention of enumName_literal_name)

 is the name of the Instance Specification used as the slot for "value". (This assumes use of the naming convention of enumName_literal_name)

<owl:Class rdf:about="&AP243-rdl;VerificationStatusEnum">
        <skos:prefLabel xml:lang="en">VerificationStatusEnum</skos:prefLabel>
        <rdfs:subClassOf rdf:resource="&AP243-rdl;StatusDefinition"/>
        <rdfs:comment xml:lang="en">This is the ...</rdfs:comment>
        ...
<!-- VerificationStatusEnum Literal to_be_verified InstanceSpecification: verificationStatusEnum_to_be_verified-->
<owl:NamedIndividual rdf:about="&AP243-rdl;verificationStatusEnum_to_be_verified">
        <rdf:type rdf:resource="&AP243-rdl;VerificationStatusEnum"/>
        <skos:prefLabel xml:lang="en">to_be_verified</skos:prefLabel>
        ...
</owl:NamedIndividual>

These are not yet included in the reference data - need to determine how they should be represented

This looks for block properties that are mapped to something outside of this model - this is done by selecting those that have a descendent with a tag of referenceExtension
(which is a |MD| extension).

(which is a 

named "templateOwlClass" - these are assumed to be templates (see :ref:`Templates<how_rd_xsl_templates>`)

named "templateOwlClass" - these are assumed to be templates (see 

For those that are mapped to ExternalOwlClass (anything else ignored) it then generates the owl:Class with the following:

**prefLabel**  (and **rdf:about**): this assumes that the name of the attibute is follows the convention of the xxxOwlClass where xxx is the name of the association.
It then appends this (without the OwlClass) to the name of the template. e.g. ModelType_inheritsFrom

): this assumes that the name of the attibute is follows the convention of the xxxOwlClass where xxx is the name of the association.

**subClassOf**: works out which element they are mapped to uses this as the subClassOf

: works out which element they are mapped to uses this as the subClassOf

<owl:Class rdf:about="&AP243-rdl;ModelType_inheritsFrom">
        <skos:prefLabel xml:lang="en">ModelType_inheritsFrom</skos:prefLabel>
        <rdfs:subClassOf rdf:resource="&corev1;PartVersionRelationship"/>
        ...

Association mapped to ExternalOwlObject - need to determine how they should be represented

There is a free online GUID generator at: https://www.guidgenerator.com/.

.. figure:: /images/howto/ht_rd_guid_generator.png

There is a macro that will print the UUID of an item selected in the containment tree to the notifications window.

Protégé can be downloaded freely from https://protege.stanford.edu/.  registration is required.

Select “PRODUCTS” and then “Older versions” of go to https://protegewiki.stanford.edu/wiki/Protege_Desktop_Old_Versions.

Version 4.3.0 is known to work with STEPlib and it is recommended to download the version that includes a Java VM.

There are many dedicated XML packages or text editors that are can be used for editing XML e.g.

Launch Protégé, select File > Open….

     .. figure:: /images/howto/ht_rd_open_protege.png

     Navigate to Core RDL

.. figure:: /images/howto/ht_rd_open_protege.png

Navigate to STEPlib\\Core_model\\refdata, select core_rd_v1.owl, and click Open

     .. figure:: /images/howto/ht_rd_open_file.png

     Open Core Reference Data

Navigate to STEPlib\Core_model\refdata, select core_rd_v1.owl, and click Open

.. figure:: /images/howto/ht_rd_open_file.png

If the following dialogue appears, simply click OK (This is a minor bug in this version of Protégé).

     .. figure:: /images/howto/ht_rd_ignore_error.png

     Error Message

      .. todo:: other error messages for **resolve missing import**

.. figure:: /images/howto/ht_rd_ignore_error.png

Select the Entities tab in the resulting dialogue and browse the tree of core STEPlib reference data classes.

     * The classes displayed in **normal text** are from the core_v1.owl file and they correspond to blocks in the Core Model.
     * The classes displayed in **bold text** are from the core_rd_v1.owl file and are additional RDL classes agreed on for use in the harmonized AP242 and AP239 model. Only these classes are used in classifications.

     .. figure:: /images/howto/ht_rd_core_entities.png

     Explore the Entities in the core_rd_v1

The classes displayed in **normal text** are from the core_v1.owl file and they correspond to blocks in the Core Model.

 are from the core_v1.owl file and they correspond to blocks in the Core Model.

The classes displayed in **bold text** are from the core_rd_v1.owl file and are additional RDL classes agreed on for use in the harmonized AP242 and AP239 model. Only these classes are used in classifications.

 are from the core_rd_v1.owl file and are additional RDL classes agreed on for use in the harmonized AP242 and AP239 model. Only these classes are used in classifications.

.. figure:: /images/howto/ht_rd_core_entities.png

You will note that Protégé has created a STEPlib\\Core_model\\refdata\\catalog-v001.xml file with the following content::

You will note that Protégé has created a STEPlib\Core_model\refdata\catalog-v001.xml file with the following content:

You will note that Protégé has created a STEPlib\\Core_model\\refdata\\catalog-v001.xml file with the following content:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
        <group id="Folder Repository, directory=, recursive=true, Auto-Update=true, version=2" prefer="public" xml:base="">
                <uri id="Automatically generated entry, Timestamp=1566979296562" name="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_rd_v1" uri="core_rd_v1.owl"/>
                <uri id="Automatically generated entry, Timestamp=1566979296562" name="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_v1" uri="core_v1.owl"/>
        </group>
</catalog>

The image below shows the RDL Individual with all the mandatory annotations populated.

.. figure:: /images/howto/ht_rd_ind_finish.png

        RDL Individual with mandatory annotations

This section describes how to create a new AP-based alternative Language RDL using Protégé.

Create a new file named **ap{ap_number}_{my_language_code}_v1.owl** in STEPlib\\Application_protocols\\AP{ap_number}\\refdata, where {ap_number} is the number of the AP, e.g. ap243 and {my_language_code} is a language code e.g. sv.

 in STEPlib\Application_protocols\AP{ap_number}\refdata, where {ap_number} is the number of the AP, e.g. ap243 and {my_language_code} is a language code e.g. sv.

 in STEPlib\\Application_protocols\\AP{ap_number}\\refdata, where {ap_number} is the number of the AP, e.g. ap243 and {my_language_code} is a language code e.g. sv.

Copy in the text below replacing {ap_number}, {my_date}, {my_name}, {my_comment_text_in_my_language}, and {my_coverage_text_in_my_language} with suitable values

<?xml version="1.0"?>
<!DOCTYPE rdf:RDF [
        <!ENTITY owl "http://www.w3.org/2002/07/owl#" >
        <!ENTITY dc "http://purl.org/dc/elements/1.1/" >
        <!ENTITY xsd "http://www.w3.org/2001/XMLSchema#" >
        <!ENTITY skos "http://www.w3.org/2004/02/skos/core#" >
        <!ENTITY rdfs "http://www.w3.org/2000/01/rdf-schema#" >
        <!ENTITY rdf "http://www.w3.org/1999/02/22-rdf-syntax-ns#" >
        <!ENTITY ap{ap_number}v1 "http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1#" >
        <!ENTITY ap{ap_number}{my_language_code}v1 "http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_{my_language_code}_v1#" >
        <!ENTITY corev1 "http://standards.iso.org/iso/10303/-4000/tech/refdata/core_v1#" >
        <!ENTITY corerdv1 "http://standards.iso.org/iso/10303/-4000/tech/refdata/core_rd_v1#" >
]>

<rdf:RDF xmlns="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_{my_language_code}_v1#"
         xml:base="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_{my_language_code}_v1"
         xmlns:dc="http://purl.org/dc/elements/1.1/"
         xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
         xmlns:owl="http://www.w3.org/2002/07/owl#"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
         xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:ap{ap_number}{my_language_code}v1="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_{my_language_code}_v1#"
         xmlns:ap{ap_number}v1="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1#"
         xmlns:corev1="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_v1#"
         xmlns:skos="http://www.w3.org/2004/02/skos/core#"
         xmlns:corerdv1="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_rd_v1#">
        <owl:Ontology rdf:about="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_{my_language_code}_v1">
                <dc:date xml:lang="{my_language_code}">{my_date}</dc:date>
                <rdfs:comment xml:lang="{my_language_code}">{my_comment_text_in_my_language} l&apos;ISO 10303-{ap_number}.</rdfs:comment>
                <dc:language>{my_language_code}</dc:language>
                <owl:versionInfo>v1</owl:versionInfo>
                <dc:type>WD</dc:type>
                <dc:source>ISO 10303-{ap_number}</dc:source>
                <dc:coverage xml:lang="{my_language_code}">{my_coverage_text_in_my_language}</dc:coverage>
                <dc:creator xml:lang="en">{my_name}</dc:creator>
                <owl:imports rdf:resource="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1"/>
        </owl:Ontology>
</rdf:RDF>

Open the file named catalog-v001.xml in STEPlib\Application_protocols\AP{ap_number}, where {ap_number} is the number of the AP, e.g. ap243

Open the file named catalog-v001.xml in STEPlibApplication_protocolsAP{ap_number}, where {ap_number} is the number of the AP, e.g. ap243

Replace the content with the text below replacing {ap_number}, {my_language_code}, {my_drive_letter}, and {my_local_path} with suitable values::

     <?xml version="1.0" encoding="UTF-8" standalone="no"?>
     <catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
             <uri id="User Entered Import Resolution" name="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_v1" uri="file:/{my_drive_letter}:/{my_local_path}/STEPlib/Core_model/refdata/core_v1.owl"/>
             <uri id="User Entered Import Resolution" name="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_rd_v1" uri="file:/{my_drive_letter}:/{my_local_path}/STEPlib/Core_model/refdata/core_rd_v1.owl"/>
              <uri id="User Entered Import Resolution" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1" uri="file:/{my_drive_letter}:/{my_local_path}/Application_protocols/AP{ap_number}/refdata/ap{ap_number}_v1.owl"/>

             <group id="Folder Repository, directory=, recursive=true, Auto-Update=true, version=2" prefer="public" xml:base="">
                     <uri id="Automatically generated entry, Timestamp=1554323905527" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_{my_language_code}_v1" uri="ap{ap_number}_{my_language_code}_v1.owl"/>
     <uri id="Automatically generated entry, Timestamp=1554473746619" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap999_{my_language_code}_v1" uri="ap{ap_number}_{my_language_code}_v1.owl"/>
             </group>
     </catalog>

Replace the content with the text below replacing {ap_number}, {my_language_code}, {my_drive_letter}, and {my_local_path} with suitable values:

        <uri id="User Entered Import Resolution" name="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_v1" uri="file:/{my_drive_letter}:/{my_local_path}/STEPlib/Core_model/refdata/core_v1.owl"/>
        <uri id="User Entered Import Resolution" name="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_rd_v1" uri="file:/{my_drive_letter}:/{my_local_path}/STEPlib/Core_model/refdata/core_rd_v1.owl"/>
         <uri id="User Entered Import Resolution" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1" uri="file:/{my_drive_letter}:/{my_local_path}/Application_protocols/AP{ap_number}/refdata/ap{ap_number}_v1.owl"/>

                <uri id="Automatically generated entry, Timestamp=1554323905527" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_{my_language_code}_v1" uri="ap{ap_number}_{my_language_code}_v1.owl"/>
<uri id="Automatically generated entry, Timestamp=1554473746619" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap999_{my_language_code}_v1" uri="ap{ap_number}_{my_language_code}_v1.owl"/>
        </group>

Reference Data; How to - Ammend RDL class with additional language

This section describes how to amend RDL classes with additional language annotations using Protégé

Annotations should only be added to sub-classes of STEPthing that exist in the file /STEPlib/Application_protocols/AP{ap_number}/refdata/ap{ap_number}_v1.owl

This example shows how to create an alternative language annotation for AP RDL class called “My AP activity”.

Select the existing **my AP activity** class and select **Annotations +**

Select **prefLabel** and type the alternative text then select the **correct language code**, and hit OK.

     .. figure:: /images/howto/ht_rd_language.png

     Add an alternative language annotation to an RDL class

.. figure:: /images/howto/ht_rd_language.png

Other non-English language annotations can be added in a similar fashion.

This section describes how to amend RDL individuals with additional language annotations using Protégé

Annotations should only be added to individuals of sub-classes of STEPthing that exist in the file /STEPlib/Application_protocols/AP{ap_number}/refdata/ap{ap_number}_v1.owl

This example shows how to create an alternative language annotation for AP RDL individual called “my AP activity 001”.

Select the existing **my AP activity 001** individual, select **Annotations +**

Select **prefLabel**, type the alternative text, select the **correct language code**, and hit OK.

     .. figure:: /images/howto/ht_rd_language_annotation.png

     Navigate to individual to add language annotation

.. figure:: /images/howto/ht_rd_language_annotation.png

     .. figure:: /images/howto/ht_rd_language_annotation_individual.png

     Add an alternative language annotation to an RDL individual

.. figure:: /images/howto/ht_rd_language_annotation_individual.png

Other non-English language annotations can be added to RDL individuals in a similar fashion.

This section describes how to create a new AP-based English Language RDL using Protégé.

Create a new file named ap{ap_number}_v1.owl in STEPlib\\Application_protocols\\AP{ap_number}\\refdata\\, where {ap_number} is the number of the AP, e.g. ap243

Create a new file named ap{ap_number}_v1.owl in STEPlib\Application_protocols\AP{ap_number}\refdata\, where {ap_number} is the number of the AP, e.g. ap243

Copy in the text below replacing {ap_number}, {my_date}, and {my_name} with suitable values

        <!ENTITY terms "http://purl.org/dc/terms/" >
        <!ENTITY ap{ap_number}v1 "http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1" >
]>

<rdf:RDF xmlns="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1#"
         xml:base="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1"
         xmlns:corerdv1="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_rd_v1#"
         xmlns:ap{ap_number}v1="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1">
        <owl:Ontology rdf:about="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1">
                <dc:date xml:lang="en">{my_date}</dc:date>
                <dc:language>en</dc:language>
                <rdfs:comment xml:lang="en">This ontology is the reference data for ISO 10303-{ap_number}.</rdfs:comment>
                <dc:coverage xml:lang="en">Reference data relating to a single AP.</dc:coverage>
                <owl:imports rdf:resource="http://standards.iso.org/iso/10303/-4000/tech/refdata/core_rd_v1"/>

Create a new file named catalog-v001.xml in STEPlib\\Application_protocols\\AP{ap_number}\\refdata\\, where {ap_number} is the number of the AP, e.g. ap243

Create a new file named catalog-v001.xml in STEPlib\Application_protocols\AP{ap_number}\refdata\, where {ap_number} is the number of the AP, e.g. ap243

Copy in the text below replacing {ap_number}, {my_drive_letter}, and {my_local_path} with suitable values::

                     <uri id="Automatically generated entry, Timestamp=1554323905527" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1" uri="ap{ap_number}_v1.owl"/>
             </group>

Copy in the text below replacing {ap_number}, {my_drive_letter}, and {my_local_path} with suitable values:

                <uri id="Automatically generated entry, Timestamp=1554323905527" name="http://standards.iso.org/iso/10303/-{ap_number}/tech/refdata/ap{ap_number}_v1" uri="ap{ap_number}_v1.owl"/>
        </group>

This seems a bit risky, very easy to do a typo. Is there not a way to do it in the UI?

Open the new owl file: STEPlib\\Application_protocols\\AP{ap_number}\\refdata\\ap{ap_number}_v1.owl

Open the new owl file: STEPlib\Application_protocols\AP{ap_number}\refdata\ap{ap_number}_v1.owl

Expand STEPthing

     .. figure:: /images/howto/ht_rd_entities.png

     Navigate to Core RDL classes

.. figure:: /images/howto/ht_rd_entities.png

Reference data representing a block uses RDL Class. Otherwise Reference data can be either classes or :ref:`named individuals<how_rd_htindividual>` depending on whether the entity is mapped to Class/ClassSelect or Proxy/ProxyItemSelect respectively

Reference data representing a block uses RDL Class. Otherwise Reference data can be either classes or 

 depending on whether the entity is mapped to Class/ClassSelect or Proxy/ProxyItemSelect respectively

.. figure:: /images/howto/ht_rd_choice.png

        Navigate to Core RDL classes

This section describes how to create a new RDL Class using Protégé.

Classes should only be created below sub-classes of STEPthing. This example shows how to create a new AP RDL class under the existing **approving person organization** class.

Classes should only be created below sub-classes of STEPthing. This example shows how to create a new AP RDL class under the existing 

Select class **approving person organization** and click add-subclass:

     .. figure:: /images/howto/ht_rd_new_class.png

     Create new subclass

.. figure:: /images/howto/ht_rd_new_class.png

A dialogue will appear. Either:

     * Use a UUID from a suitable object in the SysML model (using the Get UUID macro see :ref:`how_rd_UUIDMD` ), and click OK. This example uses the UUID of the public reference property.

             .. figure:: /images/howto/ht_rd_guid_md.png

             Use UUID from a SysML object

     * Generate a GUID, paste it into the Name field, and click OK. Note: if this metho is used then the GUID will need to be copied into the mapping.

             .. figure:: /images/howto/ht_rd_insert_guid.png

             Use new GUID

Use a UUID from a suitable object in the SysML model (using the Get UUID macro see :ref:`how_rd_UUIDMD` ), and click OK. This example uses the UUID of the public reference property.

      .. figure:: /images/howto/ht_rd_guid_md.png
              :scale: 100%

      Use UUID from a SysML object

Use a UUID from a suitable object in the SysML model (using the Get UUID macro see 

 ), and click OK. This example uses the UUID of the public reference property.

.. figure:: /images/howto/ht_rd_guid_md.png

Generate a GUID, paste it into the Name field, and click OK. Note: if this metho is used then the GUID will need to be copied into the mapping.

      .. figure:: /images/howto/ht_rd_insert_guid.png

      Use new GUID

.. figure:: /images/howto/ht_rd_insert_guid.png

Select **Annotations**; Expand **label**; Select **prefLabel**;

     * Type the preferred label in the **Value** field.
     * Select “en” (or other language) in the **Lang** field.
     * Click OK

     .. figure:: /images/howto/ht_rd_preflabel.png

     Add preferred label

.. figure:: /images/howto/ht_rd_preflabel.png

The class will now be identified by its preferred label.

     .. figure:: /images/howto/ht_rd_display_preflabel.png

     Display preferred label

.. figure:: /images/howto/ht_rd_display_preflabel.png

If the preflabel is not displayed, go **View > Render by annotation property** and select **prefLabel**.

The remaining class annotations should be added using the same procedure

**Description**
      * entered using the **comment** annotation;
      * see :ref:`how_rd_class_comment`

      .. figure:: /images/howto/ht_rd_cl_comment.png

      Add description (with language)

* entered using the **comment** annotation;
* see :ref:`how_rd_class_comment`

.. figure:: /images/howto/ht_rd_cl_comment.png

Add description (with language)

**Creator**
      * entered using the **creator** annotation;
      * see :ref:`how_rd_class_creator`

      .. figure:: /images/howto/ht_rd_cl_creator.png

      Add creator (with language)

* entered using the **creator** annotation;
* see :ref:`how_rd_class_creator`

.. figure:: /images/howto/ht_rd_cl_creator.png

Add creator (with language)

**Creation date**
      * entered using the **date** annotation;
      * see :ref:`how_rd_class_date`

      .. figure:: /images/howto/ht_rd_cl_date.png

      Add date (no language)

* entered using the **date** annotation;
* see :ref:`how_rd_class_date`

.. figure:: /images/howto/ht_rd_cl_date.png

Add date (no language)

**Status**
      * entered using the **type** annotation;
      * see :ref:`how_rd_class_type`

      .. figure:: /images/howto/ht_rd_cl_type.png

      Add status (no language)

* entered using the **type** annotation;
* see :ref:`how_rd_class_type`

.. figure:: /images/howto/ht_rd_cl_type.png

Add status (no language)

**Version**
      * entered using the **versionInfo** annotation;
      * see :ref:`how_rd_class_versioninfo`

      .. figure:: /images/howto/ht_rd_cl_version.png

      Add version (no language)

* entered using the **versionInfo** annotation;
* see :ref:`how_rd_class_versioninfo`

.. figure:: /images/howto/ht_rd_cl_version.png

Add version (no language)

**Change Note**
      * entered using the **changeNote** annotation;
      * see :ref:`how_rd_class_changenote`

      .. figure:: /images/howto/ht_rd_cl_change.png

      Add change note (with language)

* entered using the **changeNote** annotation;
* see :ref:`how_rd_class_changenote`

.. figure:: /images/howto/ht_rd_cl_change.png

Add change note (with language)

Alternative label
      * entered using the **altLabel** annotation;
      * see :ref:`how_rd_class_altlabel`

* entered using the **altLabel** annotation;
* see :ref:`how_rd_class_altlabel`

Deprecated label
      * entered using the  **hiddenlabel** annotation;
      * see :ref:`how_rd_class_hiddenlabel`

* entered using the  **hiddenlabel** annotation;
* see :ref:`how_rd_class_hiddenlabel`

Definition
      * entered using the **definition** annotation;
      * see :ref:`how_rd_class_definition`

* entered using the **definition** annotation;
* see :ref:`how_rd_class_definition`

Source
      * entered using the **source** annotation;
      * see :ref:`how_rd_class_source`

Source
* entered using the **source** annotation;
* see :ref:`how_rd_class_source`

Note
      * entered using the **note** annotation;
      * see :ref:`how_rd_class_note`

Note
* entered using the **note** annotation;
* see :ref:`how_rd_class_note`

Example
      * entered using the **example** annotation;
      * see :ref:`how_rd_class_example`

Example
* entered using the **example** annotation;
* see :ref:`how_rd_class_example`

Contributor
      * entered using the **contributor** annotation.
      * see :ref:`how_rd_class_contributor`

* entered using the **contributor** annotation.
* see :ref:`how_rd_class_contributor`

The image below shows the RDL Class with all the mandatory annotations populated.

.. figure:: /images/howto/ht_rd_cl_finish.png

        RDL Class with mandatory annotations

This section describes how to create a new RDL individuals using Protégé.

Individuals should only be created below sub-classes of STEPthing. This example shows how to create a new AP RDL class called “approval status failed” under the "State" class.

Select **Individuals by Class** tab and select the class **state** > **state observed**.

On the **Individuals** panel, Click on the diamond shape and a dialogue will appear

Enter a GUID for the individual, and click OK. Either:

     * Use a UUID from a suitable object in the SysML model (using the Get UUID macro see :ref:`how_rd_UUIDMD` ), and click OK. This example uses the UUID of the Enumeration Literal.

             .. figure:: /images/howto/ht_rd_individualMD.png

             Add an individual

     * Or use the GUID generator (see :ref:`how_rd_GUIDgen`)

             .. figure:: /images/howto/ht_rd_individual.png

Use a UUID from a suitable object in the SysML model (using the Get UUID macro see :ref:`how_rd_UUIDMD` ), and click OK. This example uses the UUID of the Enumeration Literal.

      .. figure:: /images/howto/ht_rd_individualMD.png

      Add an individual

 ), and click OK. This example uses the UUID of the Enumeration Literal.

.. figure:: /images/howto/ht_rd_individualMD.png

Or use the GUID generator (see :ref:`how_rd_GUIDgen`)

      .. figure:: /images/howto/ht_rd_individual.png

.. figure:: /images/howto/ht_rd_individual.png

Select my_ap_activity_001 in the list of Individuals and click **Annotations +**

Select “en” in the **Lang** field and click OK.

     .. figure:: /images/howto/ht_rd_individual_preflabel.png

     Create preferred label for individual

.. figure:: /images/howto/ht_rd_individual_preflabel.png

The remaining NamedIndividual annotations should be added using the same procedure

      * see :ref:`how_rd_individual_comment`

      .. figure:: /images/howto/ht_rd_ind_comment.png

* see :ref:`how_rd_individual_comment`

.. figure:: /images/howto/ht_rd_ind_comment.png

      * see :ref:`how_rd_individual_creator`

      .. figure:: /images/howto/ht_rd_ind_date.png

* see :ref:`how_rd_individual_creator`

.. figure:: /images/howto/ht_rd_ind_date.png

      * see :ref:`how_rd_individual_date`

* see :ref:`how_rd_individual_date`

      * see :ref:`how_rd_individual_type`

      .. figure:: /images/howto/ht_rd_ind_type.png

* see :ref:`how_rd_individual_type`

.. figure:: /images/howto/ht_rd_ind_type.png

      * see :ref:`how_rd_individual_versioninfo`

      .. figure:: /images/howto/ht_rd_ind_version.png

* see :ref:`how_rd_individual_versioninfo`

.. figure:: /images/howto/ht_rd_ind_version.png

      * see :ref:`how_rd_individual_changenote`

* see :ref:`how_rd_individual_changenote`

      * see :ref:`how_rd_individual_altlabel`

* see :ref:`how_rd_individual_altlabel`

      * see :ref:`how_rd_individual_hiddenlabel`

* see :ref:`how_rd_individual_hiddenlabel`

      * see :ref:`how_rd_individual_definition`

* see :ref:`how_rd_individual_definition`

Source
      * see :ref:`how_rd_individual_source`

Source
* see :ref:`how_rd_individual_source`

Note
      * see :ref:`how_rd_individual_note`

Note
* see :ref:`how_rd_individual_note`

Example
      * see :ref:`how_rd_individual_example`

Example
* see :ref:`how_rd_individual_example`

      * see :ref:`how_rd_individual_contributor`

* see :ref:`how_rd_individual_contributor`

Hyperlink target "how-rd-individual-subclassof" is not referenced.

Hyperlink target "how-rd-individual-preflabel" is not referenced.

Hyperlink target "how-rd-individual-altlabel" is not referenced.

Hyperlink target "how-rd-individual-hiddenlabel" is not referenced.

Hyperlink target "how-rd-individual-definition" is not referenced.

Hyperlink target "how-rd-individual-contributor" is not referenced.

Hyperlink target "how-rd-individual-versioninfo" is not referenced.

Hyperlink target "how-rd-individual-changenote" is not referenced.

The class shall be given an GUID to allow it to be uniquely identified. The identifier for the class is combined with the IRI (or the corresponding DOCTYPE !ENTITY reference)
for the RDL in which it is defined to create the identifier for the class.

For each new class added to the RDL the parent class (or superclass) shall be identified. Every class shall be a descendent of one of the core classes
(defined in STEPlib\Core_model\refdata\core_v1.owl). It is possible for a class to have more than one superclass - in other words, multiple inheritance
is allowed. The new class is added as a subclass of the appropriate superclass and other superclasses added as necessary.

(defined in STEPlibCore_modelrefdatacore_v1.owl). It is possible for a class to have more than one superclass - in other words, multiple inheritance

NOTE: Members of the new class are, by definition, members of all the identified superclasses.

<owl:Class rdf:about="{...}">
    <rdfs:subClassOf rdf:resource="{IRIorCorrespondingEntityForParentClass}{guid}"/>

Labels are used to provide human readable identification in the desired language. The provided label shall be written in lower-case only, and may consist of more
than one word separated by spaces. SKOS elements are used to provide this capability and the following are allowed:

A preferred label is the label that is favoured and shall be provided.

    <skos:prefLabel xml:lang="en">{preferred_label}</skos:prefLabel>

Comments augment the information provided in the description or definition of a class.

    <skos:note xml:lang="en">{note}</skos:note>

<skos:note>Plastic widgets are not suitable for high-temperature environments.</skos:note>

Examples are valuable for adding clarity to the meaning of the class.

There may be multiple comments and examples provided for each class. Both comments and examples should preferably only be single sentences, starting with capital
letters and ending with a full-stop.

Both the comments and examples, as well as the descriptions and the definitions should be attributed with a language identifier using the ISO 639-1 language
codes specifying the language used in the text.

    <skos:example xml:lang="en">{example}</skos:example>

The creator should be specified with theirfull name and company/organization affiliation.

    <dc:creator xml:lang="en">{creator_name_and_affiliation}</dc:creator>

A contributor is anyone who at any time has edited the class. One dc:contributor element is created for each editor.

The contributor should be specified with their full name and company/organization affiliation.

    <dc.contributor xml:lang="en">{contributor_name_and_affiliation}</dc.contributor>

<dc:contributor xml:lang="en">Mike Ward, Eurostep</dc:contributor>

    <dc.date>{date}</dc.date>

The publication status of the class is represented using the dc:type annotation.

    <dc:type>{status}</dc:type>

NOTE: This is not qualified by a language code since this is language independent.

When a class is added to an ontology the version of the ontology at the time that the class was added should be recorded. This allows the tracking of which
classes were added from one version to next.

    <owl:versionInfo>{version}</owl:versionInfo>

NOTE: This property should not be qualified by a language code since this is language independent.

Where {part_number} is the 10303 part number and {ap_name} is the name of the domain for which this RDL is being developed, and {version} is a decimal number in which the decimal point has been replaced by a hyphen.

Here the AP name should be written in all lowercase to be consistent with the naming conventions.

EXAMPLE::

        http://standards.iso.org/iso/10303/-999/tech/refdata/ap999_v1.owl

When creating an AP specific RDL, the RDL (the owl:Ontology) itself shall have the following annotations applied:

The Ontology shall be given an IRI to allow it to be uniquely identified::

The Ontology shall be given an IRI to allow it to be uniquely identified:

<owl:Ontology rdf:about="http://standards.iso.org/iso/10303/-{part_number}/tech/refdata/{ap_name}_v{version}">
</owl: Ontology >

The RDL for a specific context shall identify the scope or applicability for the context using the dc:coverage
annotation applied to the ontology itself. This shall be further qualified by a language code to allow other
language extensions of this library to declare language specific translations of the scope statement::

language extensions of this library to declare language specific translations of the scope statement:

<owl:Ontology rdf:about="{...}">
  <dc:coverage xml:lang="en">{description of the scope of the RDL}</dc:coverage>
</owl:Ontology>

<dc:coverage xml:lang="en">The classifiable objects from AP999.</dc:coverage>

The RDL may identify a source for the reference data specified in this RDL. This is represented using dc:source annotation
on the library. This shall be further qualified by a language code to allow other language extensions of this library to
declare language specific sources::

declare language specific sources:

  <dc:source xml:lang="en">{source}</dc:source>

The RDL version information is to be represented using owl:versionInfo annotation on the library. This shall be set to
the value v#.# for use by human users of the RDL::

the value v#.# for use by human users of the RDL:

  <owl:Ontology rdf:about="{...}">
<owl:versionInfo>{version}</owl:versionInfo>
  </owl:Ontology>

This should not be qualified by a language code since this is language independent.

EXAMPLE::

        <owl:versionInfo>v1.0</owl:versionInfo>

The publication status of the RDL is represented with the dc:type annotation::

The publication status of the RDL is represented with the dc:type annotation:

<owl:type><status></owl:type>

This is not qualified by a language code since this is language independent.
It should also not be specified in language extensions since this is a property of the master RDL.

The possible values are:
* Created
* InWork
* ReadyForReview
* PassedReview
* Approved
* InUse
* Cancelled

EXAMPLE::

        <owl:status>InWork</owl:status>

* Created
* InWork
* Approved
* InUse

The record of the person creating the RDL shall be specified using the dc:creator annotation. This shall be further
qualified by a language code to allow it to be identified with the language specification and not the RDL as a whole::

qualified by a language code to allow it to be identified with the language specification and not the RDL as a whole:

<owl:creator xml:lang="en"><creator></owl:creator>

A date value for when the file was created using the dc:date annotation. This shall be further qualified by a language
code to allow it to be identified with the language specification and not the RDL as a whole.

The RDL import another RDL.  This is represented using owl:imports annotation on the library.::

The RDL import another RDL.  This is represented using owl:imports annotation on the library.:

<owl:Ontology rdf:about="{…}">
  <owl:imports rdf:resource="http://standards.iso.org/{rest_of_URI_for_imported_file}.owl"/>

Classes and individuals that have meaning in this context shall be declared within this RDL following the rules
and guidelines specified below.

A language declaration that will be used to verify that all annotations created in this RDL file are valid.
This is represented as a dc:language annotation on the library itself::

This is represented as a dc:language annotation on the library itself:

  <dc:language>{lang}</dc:language>

Every time a class is edited, the change to the class should be documented as an additional change note using the same format below:

    <skos:changeNote xml:lang="en"><[{date{}] {editor_name}, {organization}: {description_of_change}</skos:changeNote>

<skos:changeNote xml:lang="en">[2019-03-29] Mike Ward, Eurostep: spelling error “widjet” corrected to “widget” in preferredLabel element</skos:changeNote>

For each new Individual to be added to the RDL, the Class that it is a member of shall be identified. It is possible that an individual may be a member of more than one Class.
The new individual is added as a member of the appropriate class and other classes that it is a member of are added as necessary.

NOTE: Members of a class are, by definition, members of all the superclasses of that class. If this is not the case then the class hierarchy should be re-considered.

The individual shall be given an GUID to allow it to be uniquely identified. The identifier for the individual is combined with the IRI (or the corresponding entity )
for the RDL in which it is defined to create the identifier for the individual.

For each new individual added to the RDL, the class (or classes) that the individual is a member of shall be identified. Every individual shall be a member of a
class descended from one of the core classes (defined in STEPlib\Core_model\refdata\core_v1.owl). It is possible for an individual to belong to more than one class.

class descended from one of the core classes (defined in STEPlibCore_modelrefdatacore_v1.owl). It is possible for an individual to belong to more than one class.

<owl:NamedIndividual rdf:about="{...}">
    <rdf:type rdf:resource="{IRIorCorrespondingEntity}{class_guid}"/>

Labels are used to provide human readable identification in the desired language. The provided label shall be written in lower-case only, and may consist of more than one word separated by spaces. SKOS elements are used to provide this capability and the following are allowed:

     <skos:prefLabel xml:lang="en">{preferred_label}</skos:prefLabel>

One or more alternative labels can be specified. These are synonyms of the preferred label.

    <skos:altlabel xml:lang="en">{alternative_label}</skos:altlabel>

This element provides the facility for listing labels that for one reason or another should not be used for the individual.

    <skos:hiddenlabel xml:lang="en">{hidden_label}</skos:hiddenlabel>

A definition should be added to all individuals that represent terminological concepts.

    <skos:definition xml:lang="en">{formal_definition_or_link_to_definition}</skos:definition>

    <skos:prefLabel xml:lang="en">{preferred_label_of_class}</skos:prefLabel>

    <skos:comment xml:lang="en">individual of the class (classes) {preferred_label(s)_of_class(classes)}></skos:comment>

<skos:prefLabel xml:lang="en">widget</skos:prefLabel>
<skos:comment xml:lang="en">individual of the class widget</skos:comment>

If the text of a description or definition has been copied from elsewhere, or derived from a definition provided elsewhere, or is a hyperlink to a
definition provided elsewhere, the original source should be specified.

    <dc:source>{source}</dc:source>

Notes and examples may be provided for the individual to add further clarity to the descriptions and definitions.

Both the comments and examples, as well as the descriptions and the definitions should be attributed with a language identifier using the ISO 639-1 language codes
specifying the language used in the text.

        <skos:example xml:lang="en">{example}</skos:example>

The creator should be specified with their full name and company/organization affiliation.

     <dc:creator xml:lang="en">{creator_name_and_affiliation}</dc:creator>

A contributor is anyone who at any time has edited the individual. One dc:contributor element is created for each editor.

        <dc.contributor xml:lang="en">{contributor_name, affiliation}</dc.contributor>

    <dc.date xml:lang="en">{date}</dc.date>

The publication status of the individual is represented using the dc:type annotation.

NOTE: The possible values are:
* Created
* InWork
* Approved
* InUse

When an individual is added to an ontology the version of the ontology at the time that the individual was added should be recorded. This allows the tracking of which
individuals were added from one version of the ontology to the next.

Every time an individual is edited, the change to the individual should be documented as an additional change note using the same format below:

    <skos:changeNote xml:lang="en"><[{date}] {editor_name}, {organization}: {description_of_change}</skos:changeNote>

<skos:changeNote xml:lang="en">[2019-03-29] Mike Ward, Eurostep: spelling error “my widjet” corrected to “me widget” in prefLabel element</skos:changeNote>

Comments augment the information provided in the description or definition of an individual.

     <skos:note xml:lang="en">{note}</skos:note>

This element provides the capability of listing labels that for one reason or another should not be used for the class.

A class might represent either an information model related concept or a terminological concept, or both.

A definition should be added to all classes capturing terminological concepts.

     <skos:definition xml:lang="en">{formal_definition_or_link_to_definition}</skos:definition>

There can be a maximum of one description and one definition in each class. They should be formatted according to the following rules:

if the class has a superclass other than STEPThing, then the text should start with the preferred label of the superclass of the class;

ideally, none of the (new) text of the preferred label for the class should be used in the text in the description;

the text should be written in a single sentence and in a way that it can replace the label in a sentence while keeping the sentence syntactically correct;

thus, there should be no full-stop at the end of the description.

     <skos:prefLabel xml:lang="en">{preferred_label_of_super_class}</skos:prefLabel>

<owl:Class rdf:about="{...}>">
     <skos:comment xml:lang="en">{preferred_label_of_super_class>that<description_of_this_class}</skos:comment>

<skos:prefLabel xml:lang="en">plastic widget</skos:prefLabel>
<skos:comment xml:lang="en">widget that is made from a synthetic organic polymer</skos:comment>

Reference Data Libraries (:term:`RDL` s) are (optionally) developed per |AP|.

:numref:`how_rd_arch_fig` illustrates the reference data architecture and the relationships between the different libraries.
Each ontology shown in the diagram is stored in an OWL file and is identified by an Internationalized Resource Identifier (IRI)::

 illustrates the reference data architecture and the relationships between the different libraries.
Each ontology shown in the diagram is stored in an OWL file and is identified by an Internationalized Resource Identifier (IRI):

Each OWL file is identified by a Uniform Resource Identifier (:term:`URI`) that resolves to that file. The URI
is used to import that :term:`OWL` ontology into other OWL ontologies.::

<owl:Ontology rdf:about="http://standards.iso.org/{rest_of_URI_for_this_file}">

http://standards.iso.org
/iso/10303/
-4000/tech/refdata/
core_v1.owl

core_v1

core_rd_v1.owl

core_rd_v1

-999/tech/refdata
/ap999_v1.owl

/ap999_v1

STEPlib\\
Application_protocols\\
AP999\\refdata\\
ap999_fr_v1.owl

/ap999_fr_v1.owl

/ap999_fr_v1

STEPlib\\
Business_contexts\\
My_Context\\refdata
\\my_context_v1.owl

STEPlib\
Business_contexts\
My_Context\refdata
\my_context_v1.owl

STEPlib\\
Business_contexts
\\My_Context\\refdata\\
my_context_rd_fr_v1.owl

STEPlib\
\My_Context\refdata\

A feature of this environment is the support for multiple natural language versions of an RDL. Language specific extension f
iles add language tagged annotations but do not add new classes or individuals.

In most cases, developers will only be interested in adding reference data within the context of an AP and so will, therefore,
only need to edit the file::

only need to edit the file:

.. figure:: /images/howto/ht_rd_architecture.png

        Reference Data Library Architecture

Here the AP name should be written in all lowercase to be consistent with STEPlib naming conventions.

EXAMPLE::

        http://standards.iso.org/iso/10303/-999/tech/refdata/ap999_v1

Where {ap_name} is the name of the domain for which this RD is being developed, and {version} is a decimal number in which the decimal point has been replaced by a hyphen.

EXAMPLE::

        ap999_v1.owl

Reference Data is the mechanism for extending the semantics of the underlying sysML Core Model. This extension mechanism can
be used within a within Application Protocols (APs).

This section outlines how to develop reference data for use with an AP, but the approaches defined here could also be applied
within projects or organizations extending reference-data for their own specialized exchange requirements.

Where {Ap_name} is the name of the AP for which this RDL is being developed.

The {Ap_name} in this usage can use appropriate capitalization.

EXAMPLE::

        AP999

:doc:`howtoMapDMtoCore` : :ref:`how_dmcore_combined_classification`

Context specific RDLs should be named according to the following naming scheme.

If the text of a description or definition has been copied from elsewhere, or derived from a definition provided elsewhere, or is a hyperlink to a definition
provided elsewhere, the original source should be specified.

     <dc:source>{source}</dc:source>

Notes and examples may be provided for the class to add further clarity to the descriptions and definitions.

find out how to use macros with "reader" |MD|. Have checked with normal |MD| in evaluation model (i.e. no SysML license) and works OK.

convert this into batch script with arguments for {core_model} and {Core} and hardcoded relative paths {Harmo}

Execute the following calls (replacing your relative path to Harmo\STEPlib\):: ::

Execute the following calls (replacing your relative path to HarmoSTEPlib)::

Execute the following calls (replacing your relative path to Harmo\STEPlib\)::

del /q AntPub\output\data\core_model\* /s
rmdir /s /q AntPub\output\data\core_model
mkdir AntPub\output\data\core_model
mkdir AntPub\output\data\core_model\pictures
mkdir AntPub\output\data\core_model\refdata
mkdir AntPub\output\data\core_model\sys
mkdir AntPub\output\data\core_model\sys\script
xcopy AntPub\input\script AntPub\output\data\core_model\sys\script /s /e

powershell Compress-Archive -Path ..\Core_model\refdata\*.owl -DestinationPath AntPub\output\data\core_model\Core_model_RD.zip
xcopy ..\Core_model AntPub\output\Core_model\ /s /exclude:savezip.txt
powershell Compress-Archive -Path AntPub\output\Core_model -DestinationPath AntPub\output\data\core_model\Core_model.zip
del /q AntPub\output\Core_model /s
rmdir /s /q AntPub\output\Core_model

del /q Antpub\input\maps\*
cd ExtractID
del /q output\html\*
java -jar ../saxon9-8-0-6.jar -t VariablesDataCore.xml CanonicalGenerateIDsXML.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core VariablesDataCore.xml CanonicalExtract_ID.xsl

// rename images if not using macro
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core relativePath=..\..\Core_model\ ./output/sysml_models_ids.xml CanonicalRenameMDimages.xsl
move output\renameimages.bat ..\..\Core_model\.
..\..\Core_model\renameimages.bat

// copy and move images and sysml_models_ids
xcopy ..\..\Core_model\_*.png ..\AntPub\output\data\core_model\pictures
xcopy output\html\* ..\AntPub\input\maps
move output\html\* ..\AntPub\output\data\core_model
copy output\sysml_models_ids.xml ..\AntPub\input\. /y

cd ../AntPub
xcopy .\input\CoreSTEPmod_files\data\* .\output\data /s /e
//xcopy ..\..\utils\AntPub\input\CoreSTEPmod_files\data\* .\output\data /s /e
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core split4=1 splitModel=1 variablesFileName=VariablesDataCore.xml ../../Core_model/Core_model.xmi CanonicalDomainModel_clause4.xsl --suppressXsltNamespaceCheck:on 2>4000_4_error.log
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml splitModel=1  ../../Core_model/Core_model.xmi CanonicalDomainModel_clause5.xsl 2>4000_5_error.log
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml ./input/sysml_models_ids.xml termtag=DMterms DomainModel_annex_bom_expg.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml termtag=DMterms ./VariablesDataCore.xml TermsDefs.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml nr_or_biblio=nr ./VariablesDataCore.xml NormRefs_Biblio.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml nr_or_biblio=biblio ./VariablesDataCore.xml NormRefs_Biblio.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml ./VariablesDataCore.xml CanonicalDomainModel_index.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml ./VariablesDataCore.xml ReferenceData.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml ./VariablesDataCore.xml Canonical_index.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core ./VariablesDataCore.xml renumber_figurestables.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core variablesFileName=VariablesDataCore.xml ../../Core_model/Core_model.xmi CanonicalDomainModel_Home.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=Core ./VariablesDataCore.xml xhtml_to_htm.xsl

del /q output\data\core_model\sys\*.xhtml
del /q output\data\core_model\sys\*.xml

move from the AntPub/output/data/* to the <root folder>/iso10303_2xx/data::

move from the AntPub/output/data/* to the <root folder>/iso10303_2xx/data:

generates ExtractID/output/html/*.htm which should then be moved to AntPub/output/data/{subfolder(s)}/

CanonicalExtract_ID/xsl

      * input xml: ExtractID/VariablesDataXXX.xml
      * input param: model_to_generate (AAM, CM, DM, CC, SM, Core)
      * uses ExtractID/output/sysml_models_ids.xml
      * generates ExtractID/output/html/*.htm which should then be moved to AntPub/output/data/{subfolder(s)}/

The Core model reuses the scripts for generating the 4xxx documentation using the core model in place of the domain model. It does not use the scripts for 2xx documents, nor the scripts for implementation models.

The image below shows the models used and generated by the scripts. It includes a step-by-step view of the scripts where the yellow numbers refer generation of files that are not HTML, and the purple numbers are the HTML files.

.. figure:: /images/howto/ht_scpt_is_process.png

        IS Document Generation Process

Start. The XHTML files generated externally to this process are copied into the output folders

The diagram images are exported from the SysML tool as png files. In |MD| this is done with a macro **STEPlib/utils/MagicDraw/exportDiagramsMacro.js**;

The diagram images are exported from the SysML tool as png files. In 

The tool SysML files are converted into Canonical XMI and DI using a tool dependent script;

The settings for the scripts are contained in **ExtractID/VariablesData243.xml** and **AntPub/VariablesData243.xml**. These should be updated or new variants created for other APs or core model. These are input arguments to the scripts.;

. These should be updated or new variants created for other APs or core model. These are input arguments to the scripts.;

**ExtractID/CanonicalGenerateIDsXML.xsl**: this script generates temporary file (sysml_models_ids.xml) containing basic information on ids and names for all entities in the models. This is used to resolve any external references instead of having to open every the Canonical XMI and DI for all the scripts;

: this script generates temporary file (sysml_models_ids.xml) containing basic information on ids and names for all entities in the models. This is used to resolve any external references instead of having to open every the Canonical XMI and DI for all the scripts;

**ExtractID/CanonicalExtract_ID.xsl**: For each of the models this generates the image html files including the image maps. These are then copied into the appropriate Antpub/output/data folder;

: For each of the models this generates the image html files including the image maps. These are then copied into the appropriate Antpub/output/data folder;

**AntImp/CanonicalDomainModel_xmi_to_xsd.xsl**: This generates the XSD for the model (note this imports **AntPub/FunctionsCanonical.xsl** and **AntImp/FunctionsCanonical.xsl**). The output is then sorted using **AntImp/DomainModel_sort_xsd.xsl** ;

**AntImp/DomainModel_xmi_to_json.xsl**: This generates the XSD for the model which is then formatted using **python -m json.tool** (note the xsl imports **AntPub/FunctionsCanonical.xsl**);

: This generates the XSD for the model which is then formatted using 

The HTML documents that are generates with the following steps (see purple numbers in figure above):

The clauses that are not dependent of any other HTML document are generated first as XHTML working files:

     a. AP Clause 4 **CanonicalAPClause4_Documentations.xsl**
     #. AP Clause 6 (for Uof, CO and CC model) **CanonicalConformanceModel_Documentations.xsl** or for single table used **CanonicalConformanceModelSingle_Documentations.xsl**
     #. AP AAM annex **CanonicalAAM_Documentations.xsl**
     #. DM/Core Clause 4 **CanonicalDomainModel_clause4.xsl**
     #. DM/Core Clause 5 **CanonicalDomainModel_clause5.xsl**
     #. Clause 3 **TermsDefs.xsl**
     #. Clause 2 and Biblography **NormRefs_Biblio.xsl**
     #. DM/Core Annex BBD list **DomainModel_annex_bom_expg**
     #. DM/Core Clause 4.3 RD **ReferenceData.xsl**
     #. DM/Core model index **CanonicalDomainModel_index.xsl**

AP Clause 6 (for Uof, CO and CC model) **CanonicalConformanceModel_Documentations.xsl** or for single table used **CanonicalConformanceModelSingle_Documentations.xsl**

All the XHTML files (including those from STEPmod) are read to generate the index that will appear at the end of the table of contents. The script locates all heading tags in each file with class=(index_entry index_entry_type_{xxx}) where {xxx} is used to filter the index. It assumes a format of "{clause.number} {clause title}", the {clause.number} us used as the text for the hyperlink and the {clause title} is prefixed before adding to the index.

     a. ToC index **Canonical_index.xsl**

All the XHTML files (including those from STEPmod) are rebuilt and output as working XML with corrected figure numbers; table numbers; note and example numbers. The script locates all tags in each file with class = figure or table that are not inside a tabcontent, and prefixes the figure or table number to the tag with class = figureTitle or tableTitle. . It finds all tags with class = note or example and if more than one between heding tags applies numbering.

     a. **renumber_figurestables.xsl**

The working XML files are read to generate the home.htm with the ToC, ToF and ToT for both AP and DM (or Core). The script locates all headings to add to the table of contents, all tags with class="figureTitle" are added to the table of figures and all tags with class="tableTitle" are added to the table of tables.

     a. **CanonicalDomainModel_Home.xsl**

All the working XML files are then converted into HTML files

     a. **xhtml_to_htm.xsl**

DomainModel_canonicalxmi_to_xsd.xsl

      * input xml: DomainModel.xmi (Canonicial XMI)
      * input param: variablesFileName=../AntPub/VariablesDataXXX.xml
      * reads AntPub/input/sysml_models_ids.xml
      * imports AntPub/FunctionsCanonical.xsl and AntImp/FunctionsCanonical.xsl
      * generates (as > argument) unsorted_DomainModel_from_cxmi.xsd

imports AntPub/FunctionsCanonical.xsl and AntImp/FunctionsCanonical.xsl

DomainModel_sort_xsd.xsl

      * input xml: unsorted_DomainModel_from_cxmi.xsd
      * generates (as > argument) DomainModel.xsd     which should then be moved to AntPub/output/data/domain_models/{APShortName}/

generates (as > argument) DomainModel.xsd     which should then be moved to AntPub/output/data/domain_models/{APShortName}/

DomainModel_canonicalxmi_to_json.xsl (imports AntPub/FunctionsCanonical.xsl)

      * input param: combined (0 or 1) - default 1.
      * input param: fileNamePost. default = 243
      * input param: debuggingMode (0 1)
      * imports AntPub/FunctionsCanonical.xsl
      * generates (as > argument) DomainModel_NotPretty{fileNamePost}.json

generates (as > argument) DomainModel_NotPretty{fileNamePost}.json

FunctionsCanonical.xsl

      * input param: variablesFileName (default AntPut/VariablesData.xml this must always be changed)

input param: variablesFileName (default AntPut/VariablesData.xml this must always be changed)

CanonicalFunctionsHTML.xsl

      * input param: model_to_generate (AP, DM, Core)
      * input param: my_model (AAM, CM ,CC, SM, Core) default is model_to_generate
      * includes AntPub/FunctionsCanonical.xsl

input param: my_model (AAM, CM ,CC, SM, Core) default is model_to_generate

CanonicalAPClause4_Documentations.xsl

      * input xml Data_planning_model.xmi
      * input param: model_to_generate=AP
      * input param: variablesFileName
      * includes AntPub/CanonicalFunctionsHTML.xsl
      * generates AntPub/output/data/application_protocols/{APShortName}/sys/4_info_reqs.xhtml

CanonicalConformanceModel_Documentations.xsl

      * input xml Domain_model_conformance.xmi
      * generates AntPub/output/data/application_protocols/{APShortName}/sys/6_ccs.xhtml

CanonicalConformanceModelSingle_Documentations.xsl

      * input xml Domain_model.xmi

CanonicalAAM_Documentations.xsl

      * input xml Activity_model.xmi
      * imports AntPub/CanonicalFunctionsHTML.xsl
      * generates AntPub/output/data/application_protocols/{APShortName}/sys/annex_aam.xhtml

CanonicalDomainModel_clause4.xsl

      * input xml Domain_model.xmi (or Core_model.xmi)
      * input param: model_to_generate=DM  (or Core)
      * input param: split4 (default 0 which will ouput all clause 4 in one file. change to 1 for clause 4 split by packages)
      * input param: splitModel (default 0 indicating the all is contained in the input xmi. Set to 1 if multiple xmi (e.g. for core)
      * generates AntPub/output/data/domain_models/{APShortName}/sys/4_info_reqs_XXX.xhtml

input param: split4 (default 0 which will ouput all clause 4 in one file. change to 1 for clause 4 split by packages)

input param: splitModel (default 0 indicating the all is contained in the input xmi. Set to 1 if multiple xmi (e.g. for core)

CanonicalDomainModel_clause5.xsl

      * input param: model_to_generate=DM (or Core)
      * generates AntPub/output/data/domain_models/{APShortName}/sys/5_main.xhtml

generates AntPub/output/data/domain_models/{APShortName}/sys/5_main.xhtml

TermsDefs.xsl

      * input xml AntPub/VariablesDataXXX.xml
      * input param: model_to_generate (AP, DM or Core)
      * input param: termtag (APterms DMterms) - tag containing the terms to use in the input xml
      * generates AntPub/output/data/{Core, AP or DM}/sys/3_defs.xhtml

input param: termtag (APterms DMterms) - tag containing the terms to use in the input xml

NormRefs_Biblio.xsl

      * input param: nr_or_biblio (nr biblio) - tag containing the terms to use in the input xml
      * generates AntPub/output/data/{Core, AP or DM}/sys/2_refs.xhtml (filename specified in input xml)
      * generates AntPub/output/data/{Core, AP or DM}/sys/biblio.xhtml (filename specified in input xml)

input param: nr_or_biblio (nr biblio) - tag containing the terms to use in the input xml

generates AntPub/output/data/{Core, AP or DM}/sys/2_refs.xhtml (filename specified in input xml)

generates AntPub/output/data/{Core, AP or DM}/sys/biblio.xhtml (filename specified in input xml)

DomainModel_annex_bom_expg.xsl

      * input xml AntPub/input/sysml_models_ids.xml
      * input param: model_to_generate (DM or Core)
      * input param: termtag=DMterms
      * generates AntPub/output/data/{Core or DM}/sys/annex_bom_expg.xhtml

generates AntPub/output/data/{Core or DM}/sys/annex_bom_expg.xhtml

ReferenceData.xsl

      * reads all reference data files as specified in input xml
      * generates AntPub/output/data/{Core or DM}/sys/4_info_reqs_refdata.xhtml

generates AntPub/output/data/{Core or DM}/sys/4_info_reqs_refdata.xhtml

CanonicalDomainModel_index.xsl

      * generates AntPub/output/data/{Core or DM}/sys/index_domain_model.xhtml

generates AntPub/output/data/{Core or DM}/sys/index_domain_model.xhtml

Canonical_index.xsl

      * reads all the previously generated xhtml
      * generates AntPub/output/data/application_protocols/{APShortName}/index_apdoc.xhtml
      * generates AntPub/output/data/domain_models/{APShortName}/index_bomdoc.xhtml
      * generates AntPub/output/data/core_model/index_bomdoc.xhtml

renumber_figurestables.xsl

      * reads all *.xhtml (including those manually created)
      * generates *.xml (as xhtml)

CanonicalDomainModel_Home.xsl

      * input xml Domain_model.xmi or Core_model.xmi
      * reads all output *.xml (from renumber_figurestables.xsl)
      * generates AntPub/output/data/application_protocols/{APShortName}/home.htm (if model_to_generate=DM)
      * generates AntPub/output/data/domain_models/{APShortName}/home.htm (if model_to_generate=DM)
      * generates AntPub/output/data/core_model/home.htm (if model_to_generate=Core)

generates AntPub/output/data/application_protocols/{APShortName}/home.htm (if model_to_generate=DM)

generates AntPub/output/data/domain_models/{APShortName}/home.htm (if model_to_generate=DM)

generates AntPub/output/data/core_model/home.htm (if model_to_generate=Core)

xhtml_to_htm.xsl

      * reads all *.xml (from renumber_figurestables.xsl)
      * generates *.htm (as html)

internal padding after source/pages/howto/howtoScriptOverview.txt

CanonicalGenerateIDsXML.xsl

      * input xml: ExtractID/VariablesDataXXX.xml this has all the xmi and di filenames
      * imports ExtractID/Functions.xsl
      * generates ExtractID/output/sysml_models_ids.xml. This is copied to AntPub/input/

input xml: ExtractID/VariablesDataXXX.xml this has all the xmi and di filenames

generates ExtractID/output/sysml_models_ids.xml. This is copied to AntPub/input/

.htm which should then be moved to AntPub/output/data/{subfolder(s)}/

.. figure:: /images/howto/ht_scpt_is_architecture_Core.png

        STEP Extended Architecture showing usage in this set of scripts

Select all the diagrams and save as png to the model folder without dvlp, overwriting existing files:

     .. figure:: /images/howto/ht_scpt_no_macro.png

             Export diagrams to png using out-of-the-box |MD|

when executing the scripts, after the **CanonicalGenerateIDsXML** labeled **rename images if not using the macro**.

.. figure:: /images/howto/ht_scpt_no_macro.png

        Export diagrams to png using out-of-the-box |MD|

Ruby (for generation of Canonical XMI) and additional Gems:

      Ruby 2.5.3 (using an internet connection without proxy/firewall)::

              gem install mini_portile2

              gem install systemu

              gem install macaddr

              gem install uuid

              gem install rubyzip

              gem install nokogiri

      Commands are assuming executingting in cmd window on PC.

      The add to path if not already there.

      .. figure:: /images/howto/ht_scpt_ruby_env.png

              Add ruby to path environment variable

work in progress

DO A SPELL CHECKING BEFORE EXPORTING.

Needs:

* java (saxon and tagsoup jar provided)
* Python json.tool (for pretty print of JSON schema)
* Ruby (for generation of Canonical XMI) and additional Gems:

        Ruby 2.5.3 (using an internet connection without proxy/firewall)::

                gem install mini_portile2

                gem install systemu

                gem install macaddr

                gem install uuid

                gem install rubyzip

                gem install nokogiri

        Commands are assuming executingting in cmd window on PC.

        The add to path if not already there.

        .. figure:: /images/howto/ht_scpt_ruby_env.png

                Add ruby to path environment variable

Ruby 2.5.3 (using an internet connection without proxy/firewall)::

Ruby 2.5.3 (using an internet connection without proxy/firewall):

gem install mini_portile2

gem install systemu

gem install macaddr

gem install uuid

gem install rubyzip

gem install nokogiri

.. figure:: /images/howto/ht_scpt_ruby_env.png

        Add ruby to path environment variable

The image output settings must be set to 100%

File/Save as image/Image format/Options

.. figure:: /images/howto/ht_scpt_imagesize.png

        set Export diagram size to 100%

It starts from the mdzip. The first script generates unordered XMI, the second orders to create the Canonical XMI.

#. Drag and drop the Core_model folder onto the STEPlib/utils/MagicDraw/genXMIFromFolder.bat
#. Drag and drop the Core_model/dvlp/core_model.mdzip onto the STEPlib/utils/MagicDraw/genXMIFromFolder.bat
        * THIS DOES NOT WORK FOR ME - SO USE THE VERSION IN THE GIT

Or execute the following calls: ::

        cd STEPlib/utils/MagicDraw

        for /D %i in (../../Core_model/*) do (ruby "to_cxmi.rb" mdzip="../../Core_model/%i/dvlp/%~ni.mdzip" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/%i/%~ni.xmi" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/%i/%~ni.di")

        //ruby "to_cxmi.rb" mdzip="../../Core_model/ProductDataManagement/dvlp/ProductDataManagement.mdzip"
        //ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/ProductDataManagement/ProductDataManagement.xmi"
        //ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/ProductDataManagement/ProductDataManagement.di"

Drag and drop the Core_model folder onto the STEPlib/utils/MagicDraw/genXMIFromFolder.bat

Drag and drop the Core_model/dvlp/core_model.mdzip onto the STEPlib/utils/MagicDraw/genXMIFromFolder.bat
     * THIS DOES NOT WORK FOR ME - SO USE THE VERSION IN THE GIT

* THIS DOES NOT WORK FOR ME - SO USE THE VERSION IN THE GIT

cd STEPlib/utils/MagicDraw

for /D %i in (../../Core_model/*) do (ruby "to_cxmi.rb" mdzip="../../Core_model/%i/dvlp/%~ni.mdzip" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/%i/%~ni.xmi" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/%i/%~ni.di")

//ruby "to_cxmi.rb" mdzip="../../Core_model/ProductDataManagement/dvlp/ProductDataManagement.mdzip"
//ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/ProductDataManagement/ProductDataManagement.xmi"
//ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Core_model/ProductDataManagement/ProductDataManagement.di"

.. figure:: /images/howto/ht_scpt_exphtml.png

        Export diagrams to png with macro

This page explains how to use the Scripts of the STEP architecture to generate the documentation for the IS for Core Model.
Other pages (in progress) explain the process for other APs which include content for more of the architecture.

The image below shows the models in the STEP Extended Architecture that are used by, and generated for, the International Standard documentation.

In |MD| use the STEPlib\utils\MagicDraw\exportDiagramsMacro.js to generate the diagram images. see :ref:`gs_md_macros` for how to load and use macros. Open the Core_model, select the Core_model package and run the macro. This should create the png in the STEPlib/Core_model folder.

 use the STEPlibutilsMagicDrawexportDiagramsMacro.js to generate the diagram images. see 

 use the STEPlib\utils\MagicDraw\exportDiagramsMacro.js to generate the diagram images. see 

 for how to load and use macros. Open the Core_model, select the Core_model package and run the macro. This should create the png in the STEPlib/Core_model folder.

If there is no |MD| license, then the macros are not available. In this case the process is to export the diagrams using
the inbuilt exporter, then generate and run a batch file which will rename the resultant images.

 license, then the macros are not available. In this case the process is to export the diagrams using

The core model must be generated before running these scripts. See :ref:`how_scpt_core_is_top`.

The core model must be generated before running these scripts. See 

The following assume exporting {243} with a short name {mossec}. These should be changed to values appropriate for the documentation being generated.

Edit the data in **ExtractID/VariablesData243.xml** and **AntPub/VariablesData243.xml**

The cover.htm and the XHTML files in subfolders of AntPub/input/AP243STEPmod_files are not touched and should be edited manually, they are copied as is into the output/data folder.

convert this into batch script with arguments e.g. for {mossec} and {243} and hardcoded relative paths {Harmo}

del /q AntPub\output\data\application_protocols\mossec /s
del /q AntPub\output\data\domain_models\mossec /s
mkdir AntPub\output\data\application_protocols\mossec
mkdir AntPub\output\data\application_protocols\mossec\pictures
mkdir AntPub\output\data\application_protocols\mossec\refdata
mkdir AntPub\output\data\application_protocols\mossec\sys
mkdir AntPub\output\data\application_protocols\mossec\sys\script
xcopy AntPub\input\script AntPub\output\data\application_protocols\mossec\sys\script /s /e
mkdir AntPub\output\data\domain_models\mossec
mkdir AntPub\output\data\domain_models\mossec\pictures
mkdir AntPub\output\data\domain_models\mossec\refdata
mkdir AntPub\output\data\domain_models\mossec\sys
mkdir AntPub\output\data\domain_models\mossec\sys\script
xcopy AntPub\input\script AntPub\output\data\domain_models\mossec\sys\script /s /e
powershell Compress-Archive -Path ..\Application_protocols\AP243\Domain_model\*.di, ..\Application_protocols\AP243\Domain_model\*.xmi  -DestinationPath AntPub\output\data\domain_models\mossec\Domain_model_XMI.zip -Force
powershell Compress-Archive -Path ..\Application_protocols\AP243\refdata\*.owl -Update -DestinationPath AntPub\output\data\domain_models\mossec\Domain_model_XMI.zip
powershell Compress-Archive -Path ..\Core_model\refdata\*.owl -Update -DestinationPath AntPub\output\data\domain_models\mossec\Domain_model_XMI.zip
powershell Compress-Archive -Path ..\Application_protocols\AP243\Activity_model\*.di, ..\Application_protocols\AP243\Activity_model\*.xmi  -DestinationPath AntPub\output\data\application_protocols\mossec\Activity_model.zip -Force
powershell Compress-Archive -Path ..\Application_protocols\AP243\Data_planning_model\*.di, ..\Application_protocols\AP243\Data_planning_model\*.xmi  -DestinationPath AntPub\output\data\application_protocols\mossec\Data_planning_model.zip -Force
java -jar ../saxon9-8-0-6.jar -t VariablesData243.xml CanonicalGenerateIDsXML.xsl

//rename images if not using the macro
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM relativePath=..\..\Application_protocols\AP243\Domain_model ./output/sysml_models_ids.xml CanonicalRenameMDimages.xsl
move output\renameimages.bat ..\..\Application_protocols\AP243\Domain_model\.
..\..\Application_protocols\AP243\Domain_model\renameimages.bat
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AAM relativePath=..\..\Application_protocols\AP243\Activity_model ./output/sysml_models_ids.xml CanonicalRenameMDimages.xsl
move output\renameimages.bat ..\..\Application_protocols\AP243\Activity_model\.
..\..\Application_protocols\AP243\Activity_model\renameimages.bat
java -jar ../saxon9-8-0-6.jar -t model_to_generate=CM relativePath=..\..\Application_protocols\AP243\Data_planning_model ./output/sysml_models_ids.xml CanonicalRenameMDimages.xsl
move output\renameimages.bat ..\..\Application_protocols\AP243\Data_planning_model\.
..\..\Application_protocols\AP243\Data_planning_model\renameimages.bat
java -jar ../saxon9-8-0-6.jar -t model_to_generate=SM relativePath=..\..\Application_protocols\AP243\Services_model ./output/sysml_models_ids.xml CanonicalRenameMDimages.xsl
move output\renameimages.bat ..\..\Application_protocols\AP243\Services_model\.
..\..\Application_protocols\AP243\Services_model\renameimages.bat

//DM
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM VariablesData243.xml CanonicalExtract_ID.xsl
move output\html\* ..\AntPub\output\data\domain_models\mossec
xcopy ..\..\Application_protocols\AP243\Domain_model\_*.png ..\AntPub\output\data\domain_models\mossec\pictures
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AAM VariablesData243.xml CanonicalExtract_ID.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=CM VariablesData243.xml CanonicalExtract_ID.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=SM VariablesData243.xml CanonicalExtract_ID.xsl
move output\html\* ..\AntPub\output\data\application_protocols\mossec
xcopy ..\..\Application_protocols\AP243\Activity_model\_*.png ..\AntPub\output\data\application_protocols\mossec\pictures
xcopy ..\..\Application_protocols\AP243\Data_planning_model\_*.png ..\AntPub\output\data\application_protocols\mossec\pictures
xcopy ..\..\Application_protocols\AP243\Services_model\_*.png ..\AntPub\output\data\application_protocols\mossec\pictures
cd ../AntImp
java -jar ../saxon9-8-0-6.jar -t variablesFileName=../AntPub/VariablesData243.xml ../../Application_protocols/AP243/Domain_model/Domain_model.xmi DomainModel_canonicalxmi_to_xsd.xsl > unsorted_DomainModel_from_cxmi.xsd
java -jar ../saxon9-8-0-6.jar -t unsorted_DomainModel_from_cxmi.xsd DomainModel_sort_xsd.xsl > DomainModel.xsd
copy DomainModel.xsd ..\AntPub\output\data\domain_models\mossec /y
java -jar ../saxon9-8-0-6.jar -t debuggingMode=0 variablesFileName=../AntPub/VariablesData243.xml ../../Application_protocols/AP243/Domain_model/Domain_model.xmi DomainModel_canonicalxmi_to_json.xsl
type DomainModel_NotPretty243.json | python -m json.tool > DomainModel.json
copy DomainModel.json ..\AntPub\output\data\domain_models\mossec /y
xcopy .\input\AP243STEPmod_files\* .\output /s /e /y
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml ../../Application_protocols/AP243/Data_planning_model/Data_planning_model.xmi CanonicalAPClause4_Documentations.xsl  --suppressXsltNamespaceCheck:on 2>243_4_error.log
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml  ../../Application_protocols/AP243/Domain_model/Domain_model.xmi CanonicalConformanceModelSingle_Documentations.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml ../../Application_protocols/AP243/Activity_model/Activity_model.xmi CanonicalAAM_Documentations.xsl --suppressXsltNamespaceCheck:on 2>243_AAM_error.log
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml termtag=APterms ./VariablesData243.xml TermsDefs.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml nr_or_biblio=nr ./VariablesData243.xml NormRefs_Biblio.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml nr_or_biblio=biblio ./VariablesData243.xml NormRefs_Biblio.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml ./VariablesData243.xml Canonical_index.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP  ./VariablesData243.xml renumber_figurestables.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM split4=1 variablesFileName=VariablesData243.xml ../../Application_protocols/AP243/Domain_model/Domain_model.xmi CanonicalDomainModel_clause4.xsl --suppressXsltNamespaceCheck:on 2>4443_4_error.log
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM splitModel=1 variablesFileName=VariablesData243.xml ../../Application_protocols/AP243/Domain_model/Domain_model.xmi CanonicalDomainModel_clause5.xsl 2>4443_5_error.log
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM ./input/sysml_models_ids.xml termtag=DMterms variablesFileName=VariablesData243.xml DomainModel_annex_bom_expg.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM variablesFileName=VariablesData243.xml termtag=DMterms ./VariablesData243.xml TermsDefs.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM variablesFileName=VariablesData243.xml nr_or_biblio=nr ./VariablesData243.xml NormRefs_Biblio.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM variablesFileName=VariablesData243.xml nr_or_biblio=biblio ./VariablesData243.xml NormRefs_Biblio.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM variablesFileName=VariablesData243.xml ./VariablesData243.xml CanonicalDomainModel_index.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM variablesFileName=VariablesData243.xml ./VariablesData243.xml ReferenceData.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM variablesFileName=VariablesData243.xml ./VariablesData243.xml Canonical_index.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM  ./VariablesData243.xml renumber_figurestables.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM variablesFileName=VariablesData243.xml ../../Application_protocols/AP243/Domain_model/Domain_model.xmi CanonicalDomainModel_Home.xsl --suppressXsltNamespaceCheck:on
java -jar ../saxon9-8-0-6.jar -t model_to_generate=DM  ./VariablesData243.xml xhtml_to_htm.xsl
java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP  ./VariablesData243.xml xhtml_to_htm.xsl

// delete interim files
del /q output\data\application_protocols\mossec\sys\*.xhtml
del /q output\data\application_protocols\mossec\sys\*.xml
del /q output\data\domain_models\mossec\sys\*.xhtml
del /q output\data\domain_models\mossec\sys\*.xml

//cd ../generate_owl
//java -jar ../saxon9.jar -t ../Domain_model.xml AP243_DomainToOWL.xsl > ../AntPub/input/domain_model.owl
//copy ..\AntPub\input\domain_model.owl ..\AntPub\output\data\application_protocols\mossec\refdata\ap243_RDL-en-v1-0.owl /y

// clause 6 using the Domain_model_conformance.xmi
//java -jar ../saxon9-8-0-6.jar -t model_to_generate=AP variablesFileName=VariablesData243.xml  ../../Application_protocols/AP243/Domain_model_conformance/Domain_model_conformance.xmi CanonicalConformanceModel_Documentations.xsl --suppressXsltNamespaceCheck:on 2>243_6_error.log
// clause 6 - single cc using Domain_model.xmi

The domain model is mapped to the Core model and this is assumed to already be present in the output folders. See :ref:`how_scpt_core_is_top`.

The domain model is mapped to the Core model and this is assumed to already be present in the output folders. See 

The following html classes are used by the scripts (Note all are xhtml) e.g.::

The following html classes are used by the scripts (Note all are xhtml) e.g.:

<div class="figure" align="center" name="{name of figure}" id="{figure id}">
        <img style="overflow: auto; max-height: 90vh;" src="{path to image file}" alt="{alt text}" border="0"></img>
        <br></br>
        <div align="center">
                <b class="figureTitle">{title of figure}</b>
        </div>
</div>

<div align="center" class="figure" id="figure_1" name="figure_1">
        <img style="overflow: auto; max-height: 90vh;" src="../study_wwwwhw.png" alt="Illustration of Fractal Studies with examples of Systems Engineering Context" border="0"/>
        <br/>
                <b class="figureTitle">Illustration of Fractal Studies with examples of Systems Engineering Context</b>
        </div>
</div>

    <div class="table" align="center" name="{name of table}" id="{id of table}">
            <div align="center">
                    <b class="tableTitle">{table title}</b>
            </div>
            <br></br>
            {<img>...</img> or <table>...</table>}
</div>

<div align="center" class="table" id="Q_table" name="Q_table">
                <b class="tableTitle">Business questions and directives concerned with traceability</b>
        </div>
        <br/>
        <table>...</table>
</div>

<{} class="index_entry index_entry_type_{}" name="{name of entry}" id="{id of entry}">{entry clause} {entry text}</{}>

<a name="ConceptSelect" id="_18_4_1_1xxx" class="index_entry index_entry_type_type">4.2.14.1.1 ConceptSelect</a>

<h3 class="index_entry index_entry_type_term">
        <a id="term_application">3.1.1</a>
        <br/>
        <a>application</a>
</h3>

<tr id="abbrev_AAM" class="index_entry index_entry_type_abbreviation">
        <td>AAM</td>
        <td>
                <defn>application activity model</defn>
        </td>
</tr>

comment

this does not display inside an expand????

+-------------------------------------------+----------------+
| index entry_type_{} Class                 | Clause         |
+===========================================+================+
| index_entry_type_part                     | e.g. for 4443  |
| index_entry_type_term                     | 3              |
| index_entry_type_abbreviation             | 3              |
| index_entry_type_reference_data_{ns} e.g. | 4xxx 4.3.x     |
| index_entry_type_reference_data_core_v1   |                |
| index_entry_type_type                     | 4xxx 4.2.x.1.x |
| index_entry_type_entity                   | 4xxx 4.2.x.2.x |
| index_entry_type_constraint               | 4xxx 5.3       |
| index_entry_type_Activity                 | 2xx AAM annex  |
| index_entry_type_data_planning            | 2xx 4.1.1.x    |
| index_entry_type_UOF                      | 2xx 6.1.x      |
| index_entry_type_CO                       | 2xx 6.2.x      |
| index_entry_type_CC                       | 2xx 6.3.x      |

Other types of index entry may be added, but the script prefixes the entry with text based on assumptions about the clause number, if the entry is another clause than those listed above the entry will be prefixed with red "TBD entry" text.

Open each of the models listed above and then select  **File > Save As Image**

.. figure:: /images/howto/ht_scpt_is_architecture_AP.png

Needs:

.. figure:: /images/howto/ht_scpt_exphtml_AP.png

NOTE: The top level package needs an annotated element that has the Nnumber for the XSD and XMI plus other text.

Either drag and drop the Application_protocols/AP2xx folder onto the STEPlib/utils/MagicDraw/genXMIFromFolder.bat

Or (if the above fails) execute the following calls: ::

        for /D %i in (../../Application_protocols/AP243/*) do (ruby "to_cxmi.rb" mdzip="../../Application_protocols/AP243/%i/dvlp/%~ni.mdzip" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Application_protocols/AP243/%i/%~ni.xmi" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Application_protocols/AP243/%i/%~ni.di")

        or if that fails hardcode the path:

        for /D %i in (C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\*) do (ruby "to_cxmi.rb" mdzip="%i/dvlp/%~ni.mdzip" ruby "..\ExpToXMI\to_cxmi.rb" xmi="%i/%~ni.xmi" ruby "..\ExpToXMI\to_cxmi.rb" xmi="%i/%~ni.di")

        or if that fails:

        (temp fix as scripts internal relative paths not working)
        cd STEPlib/utils/MagicDraw/runFromHereForAP

        for /D %i in (../../../Application_protocols/AP243/*) do (ruby "to_cxmi.rb" mdzip="../../../Application_protocols/AP243/%i/dvlp/%~ni.mdzip" ruby "..\..\ExpToXMI\runFromHereForAP\to_cxmi.rb" xmi="../../../Application_protocols/AP243/%i/%~ni.xmi" ruby "..\..\ExpToXMI\runFromHereForAP\to_cxmi.rb" xmi="../../../Application_protocols/AP243/%i/%~ni.di")

        .

For some reason the "for /D etc" does or via hard code. ::

        ruby to_cxmi.rb mdzip=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\dvlp\Domain_model.mdzip
        ruby to_cxmi.rb mdzip=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\dvlp\Domain_model_conformance.mdzip
        ruby to_cxmi.rb mdzip=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\dvlp\Domain_model_TestData.mdzip
        ruby to_cxmi.rb mdzip=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Concept_model\dvlp\Conceptual_model.mdzip
        ruby to_cxmi.rb mdzip=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Activity_model\dvlp\Activity_model.mdzip
        ruby to_cxmi.rb mdzip=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Services_model\dvlp\Services_model.mdzip
        cd ../ExpToXMI
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\Domain_model.xmi
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\Domain_model_conformance.xmi
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\Domain_model_TestData.xmi
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Concept_model\Conceptual_model.xmi
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Activity_model\Activity_model.xmi
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Services_model\Services_model.xmi
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\Domain_model.di
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\Domain_model_conformance.di
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Domain_model\Domain_model_TestData.di
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Concept_model\Conceptual_model.di
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Activity_model\Activity_model.di
        ruby to_cxmi.rb xmi=C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\Services_model\Services_model.di

        .

for /D %i in (../../Application_protocols/AP243/*) do (ruby "to_cxmi.rb" mdzip="../../Application_protocols/AP243/%i/dvlp/%~ni.mdzip" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Application_protocols/AP243/%i/%~ni.xmi" ruby "..\ExpToXMI\to_cxmi.rb" xmi="../../Application_protocols/AP243/%i/%~ni.di")

or if that fails hardcode the path:

for /D %i in (C:\Users\JCROCKFORD1\Documents\Git\ISOBoostGit\ap243branch\STEPlib\Application_protocols\AP243\*) do (ruby "to_cxmi.rb" mdzip="%i/dvlp/%~ni.mdzip" ruby "..\ExpToXMI\to_cxmi.rb" xmi="%i/%~ni.xmi" ruby "..\ExpToXMI\to_cxmi.rb" xmi="%i/%~ni.di")

or if that fails:

(temp fix as scripts internal relative paths not working)
cd STEPlib/utils/MagicDraw/runFromHereForAP

for /D %i in (../../../Application_protocols/AP243/*) do (ruby "to_cxmi.rb" mdzip="../../../Application_protocols/AP243/%i/dvlp/%~ni.mdzip" ruby "..\..\ExpToXMI\runFromHereForAP\to_cxmi.rb" xmi="../../../Application_protocols/AP243/%i/%~ni.xmi" ruby "..\..\ExpToXMI\runFromHereForAP\to_cxmi.rb" xmi="../../../Application_protocols/AP243/%i/%~ni.di")

.

This page explains how to use the Scripts of the STEP architecture to generate the documentation for the IS for AP243.

In |MD| use the STEPlib\utils\MagicDraw\exportDiagramsMacro.js to generate the diagram images. see :ref:`gs_md_macros` for how to load and use macros.

     * Open each of the following models in turn and run the macro. This should create the png in the folder that contains the dvlp for the model:

             * Activity_model/dvlp/Activity_model.mdzip
             * Data_planning_model/dvlp/Data_planning_model.mdzip
             * Services_model/dvlp/Services_model.mdzip (if required)
             * Domain_model_conformance/dvlp/Domain_model_conformance.mdzip (if required)
             * Domain_model_TestData/dvlp/Domain_model_TestData.mdzip (if required)
             * Domain_model/dvlp/Domain_model

Open each of the following models in turn and run the macro. This should create the png in the folder that contains the dvlp for the model:

      * Activity_model/dvlp/Activity_model.mdzip
      * Data_planning_model/dvlp/Data_planning_model.mdzip
      * Services_model/dvlp/Services_model.mdzip (if required)
      * Domain_model_conformance/dvlp/Domain_model_conformance.mdzip (if required)
      * Domain_model_TestData/dvlp/Domain_model_TestData.mdzip (if required)
      * Domain_model/dvlp/Domain_model

Domain_model_conformance/dvlp/Domain_model_conformance.mdzip (if required)

Domain_model_TestData/dvlp/Domain_model_TestData.mdzip (if required)

#. Generate the Core model full XMI by drag-drop STEPlib/Core_model/dvlp/Core_model.mdzip onto STEPlib/utils/MagicDraw/genXMI-full.bat. This creates the STEPlib/Core_model/Core_model_full.xmi
#. open command window in STEPlib/utils/generate_owl
#. Run ant from the STEPlib/utils/generate_owl folder

if the latter fails, or ant is not available:
#. rename STEPlib/Core_model/refdata/core_v1.owl to STEPlib/Core_model/refdata/core_v1.old
#. run::

        java -jar ../../../../scriptssteplib/saxon9-8-0-6.jar ../../Core_model/Core_model_full.xmi SysMLxmi2owl.xsl > ../../Core_model/refdata/core_v1.owl

        .

Generate the Core model full XMI by drag-drop STEPlib/Core_model/dvlp/Core_model.mdzip onto STEPlib/utils/MagicDraw/genXMI-full.bat. This creates the STEPlib/Core_model/Core_model_full.xmi

#. run::

#. run:

java -jar ../../../../scriptssteplib/saxon9-8-0-6.jar ../../Core_model/Core_model_full.xmi SysMLxmi2owl.xsl > ../../Core_model/refdata/core_v1.owl

.

Generate the OWL from the generate_owl folder using the following::

        java -jar ../saxon9.jar -t ../Domain_model.xml AP243_DomainToOWL.xsl > ../AntPub/input/domain_model.owl
        copy ..\AntPub\input\domain_model.owl ..\AntPub\output\data\application_protocols\mossec\refdata\ap243_RDL-en-v1-0.owl /y

Also need to convert to use the Canonical XMI instead of the |MD| UML export.

Generate the OWL from the generate_owl folder using the following:

java -jar ../saxon9.jar -t ../Domain_model.xml AP243_DomainToOWL.xsl > ../AntPub/input/domain_model.owl
copy ..\AntPub\input\domain_model.owl ..\AntPub\output\data\application_protocols\mossec\refdata\ap243_RDL-en-v1-0.owl /y

This page explains how to use the Reference Data Scripts of the STEP architecture to generate OWL.

steplib sysml: how to use the scripts to generate implementation specific test data

flatten the xsd that was generated as part of the is documentation

Flatten the xsd that was generated as part of the IS documentation

These scripts are work in progress and will be consolidated at a future date.

The scripts assume that the **XSD has already been generated** as described in :ref:`how_scpt_xsd_top`.

<iframe width="560" height="315" src="https://www.youtube.com/embed/Vifrx0F4w6Q" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
<br/><br/>

This script flattens the extensions in the XSD. It copies the DataContainer, and then for each complexType it flattens the extensions so that all the elements
are listed in the order expected by the sequence. It removes all the inner content for the elements making the output file
much smaller, but it is not a valid xsd - only to be used for sorting the TestData XML.

Check **scriptssteplib/AntTestData/VariablesData.xml** has the correct value for **DataContainer** and update if necessary.

(in Windows) open a cmd window from the scriptssteplib/AntTestData/ folder and run the following::

      java -jar ../saxon9.jar -t ../AntImp/DomainModel.xsd TestData_flatten_xsd.xsl > ../AntImp/DomainModel_flatten.xsd

      .

(in Windows) open a cmd window from the scriptssteplib/AntTestData/ folder and run the following:

java -jar ../saxon9.jar -t ../AntImp/DomainModel.xsd TestData_flatten_xsd.xsl > ../AntImp/DomainModel_flatten.xsd

.

Check **scriptssteplib/AntTestData/VariablesData.xml** has the correct values (including for the xsd as generated in the previous step set as domain_model_xsd_file) and update if necessary.

 has the correct values (including for the xsd as generated in the previous step set as domain_model_xsd_file) and update if necessary.

The <RootPackageName> is the name of the SysML Package below which the TestData will be gathered. All immediate child packages will be created in
their own DataContainer, but from then on packages will be flattened.

The <Header> is copied directly into the output XML so must be valid, the content for <Header> in VariablesData.xml is illustrative and the minimum valid content.

Generate the AP TestDataUnsorted.xml from the Domain_model_TestData.xml as follows:

      java -jar ../saxon9.jar -t ../Domain_model_TestData.xml TestData_to_xml.xsl > TestDataUnsorted.xml

      .

java -jar ../saxon9.jar -t ../Domain_model_TestData.xml TestData_to_xml.xsl > TestDataUnsorted.xml

.

(in Windows) to generate the results with **debugging** comments run the following::

      java -jar ../saxon9.jar -t debugMode=1 ../Domain_model_TestData.xml TestData_to_xml.xsl > TestDataUnsorted.xml

      .

java -jar ../saxon9.jar -t debugMode=1 ../Domain_model_TestData.xml TestData_to_xml.xsl > TestDataUnsorted.xml

.

The resultant file is: scriptssteplib/AntTestData/TestDataUnsorted.xml

The next step is to sort the XML into the correct sequence as specified by the flattened XSD created in the first step.
Check **scriptssteplib/AntTestData/VariablesData.xml** has the correct values. This script uses the DataContainer and domain_model_xsd_file, where the latter is
the file generated in the first step.

Check 

 has the correct values. This script uses the DataContainer and domain_model_xsd_file, where the latter is

      java -jar ../saxon9.jar -t TestDataUnsorted.xml TestData_sort_xml.xsl > TestData.xml

      .

java -jar ../saxon9.jar -t TestDataUnsorted.xml TestData_sort_xml.xsl > TestData.xml

.

      java -jar ../saxon9.jar -t debugMode=1 TestDataUnsorted.xml TestData_sort_xml.xsl > TestData.xml

      .

java -jar ../saxon9.jar -t debugMode=1 TestDataUnsorted.xml TestData_sort_xml.xsl > TestData.xml

.

Download the **scriptssteplib AP243_working** branch from: http://git2.boost-lab.net/admins/scriptssteplib/tree/AP243_working

In |MD| use **File > Export To > UML 2.5 XMI File** the following to XML files and store in **scriptssteplib**:

     * Domain Model Test Data model to file **Domain_model_TestData.xml**

Domain Model Test Data model to file **Domain_model_TestData.xml**

The **XSD has already been generated** as described in :ref:`how_scpt_xsd_top`

The scripts have been downloaded from  http://git2.boost-lab.net/admins/scriptssteplib

This page explains how to use the Scripts of the STEP architecture to generate the implementation specific Test Data files from the Test Data XML exported from |MD|.
The instructions for generating the Test Data model can be found in :ref:`ihow_testData_top`.

This page explains how to use the Scripts of the STEP architecture to generate the implementation specific Test Data files from the Test Data XML exported from 

.
The instructions for generating the Test Data model can be found in 

The steps for generating the AP243 set of documents are as follows:

Generate the AP DomainModel.xsd from the Domain_model.xml as follows:

(in Windows) open a cmd window from the scriptssteplib/AntImp/ folder and run the following::

      java -jar saxon9.jar -t ../Domain_model.xml DomainModel_xmi_to_xsd.xsl > unsorted_DomainModel.xsd
      java -jar saxon9.jar -t unsorted_DomainModel.xsd DomainModel_sort_xsd.xsl > DomainModel.xsd

(in Windows) open a cmd window from the scriptssteplib/AntImp/ folder and run the following:

java -jar saxon9.jar -t ../Domain_model.xml DomainModel_xmi_to_xsd.xsl > unsorted_DomainModel.xsd
java -jar saxon9.jar -t unsorted_DomainModel.xsd DomainModel_sort_xsd.xsl > DomainModel.xsd

Generate the AP DomainModel.json from the Domain_model.xml as follows:

      java -jar ../saxon9.jar -t ../Domain_model.xml DomainModel_xmi_to_json.xsl
      type DomainModel_NotPretty243.json | python -m json.tool > DomainModel.json

java -jar ../saxon9.jar -t ../Domain_model.xml DomainModel_xmi_to_json.xsl

This page explains how to use the Scripts of the STEP architecture to generate the XSD.

The files and folders should use the same name as the item within the file.

E.g. SysML model: Domain Model is stored in a folder/file as Domain_model/dvlp/Domain_model.mdzip

Do not use plurals in the name. This is because the :ref:`auto generation of the documentation <how_scpt_243_is_top>` strips plurality from the description words when looking for comparisons to generate hyperlinks.

:ref:`auto generation of the documentation <how_scpt_243_is_top>`

 strips plurality from the description words when looking for comparisons to generate hyperlinks.

confirm these naming conventions - Model and Package may be changed to Upper_snake_case

e.g. RequirementSource, ActivityAssignmentSelect, AlternatePartRelationship

Part, Value, Reference properties e.g. Id Description Source ClassifiedAs

e.g. name_of_the_mapped_domain_block or _breakdown if name in just one word

=> IMPORTANT : **DO NOT START WITH UPPER CASE** in parametric elements (except for the mapped domain block ...)

 in parametric elements (except for the mapped domain block ...)

.. figure:: /images/howto/Domain_model_to_ARM_mapping/namingConvention.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/NamingEnum.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/NamingProperty.png

The following are the general rules for when to call something an Association, Relationship of Assignment.

Association:
A link between two objects

* no directionality or precedence
* normally, but not always, of different types or subtypes

e.g. Zone and something in the zone

Relationship:
A dependency between two objects

* normally, but not always, of the same type or subtypes

Assignment:
An allocation of an object to a target object

* implies direction from an object to a target object

e.g. assignment of a start date to a project

Diagrams have the same convention as the model elements except additionally there is an "_xxx" suffix, where xxx indicates the diagram purpose.

The Block Definition Diagram, showing properties and associations for the blocks

ValueType Enumeration
      * Prefix: UpperCamelCase
      * Suffix: Enum
      * E.g. PropertyValueCharacteristicEnum

* Prefix: UpperCamelCase
* Suffix: Enum
* E.g. PropertyValueCharacteristicEnum

Enumeration Literal
      * lower_snake_case
      * E.g. upper_bound

Instance Specification
      * Prefix: ValueType name in lowerCamelCase
      * Suffix: _enumeration_literal_name in lower_snake_case
      * E.g. propertyValueCharacteristicEnum_upper_bound

* Prefix: ValueType name in lowerCamelCase
* Suffix: _enumeration_literal_name in lower_snake_case
* E.g. propertyValueCharacteristicEnum_upper_bound

.. figure:: /images/howto/ht_common_enumerationNaming.png

        Naming convention for elements used in mapping enmerations

The following are some syntax errors with some suggestions for the error.

Trying to compare where mulitplicity is "*" try e.g. self.InOrganization->excludes(self)

Stereotype the TestData package and sub-packages as **validationSuite**

.. figure:: /images/howto/ht_vc_validationSuite.png

        Stereotype packages as validationSuite

Launch the validation using the menu **Analyse > Validation > Validate**.

.. figure:: /images/howto/ht_vc_validate01.png

        Launch Validation

Then in the Validation dialog box, choose the **Validation Suite** as the top package containing the constraints to validate.

.. figure:: /images/howto/ht_vc_validate02.png

        Select Validation Suite

.. figure:: /images/howto/ht_vc_validate03.png

        Validation Results

To use the OCL Validation tool of MagicDraw, the MagicDraw Architecte or Enterprise version must be used.
For validating an OCL constraint, it should be stereotyped as **validationRule**.

For validating an OCL constraint, it should be stereotyped as 

.. figure:: /images/howto/ht_vc_constraintStereotype.png

        Stereotype constraints as validationRule

An error message can be attached to a WR so it can be more easily identified and understood during validation.

.. figure:: /images/howto/ht_vc_constraintErrorMsg.png

        Add an error message string

Stereotype packages as **validationSuite** if they contain elements with constraints for validation, or elements to be validated.

 if they contain elements with constraints for validation, or elements to be validated.

**References to numbered elements (Figure, Table, Formula ...)**

In the documentation use a <systemoutput /> tag instead of "below, above, following".

EXAMPLE The Figure <systemoutput>Simplified overview of the AP242 Annotated Model presentation</systemoutput> provides an overview of the capability.

In the documentation use bibitem="reference" (where reference is the <id=""> of the document in the master data. (can be normref.xml, biblio.xml or commonAdditionalRefs.xml)

EXAMPLE This annex provides the source files associated to this document, including the Domain model XMI in Canonical XMI bibitem="ISO/IEC 19509".

add the bibitem="" only if the text cites an unnumbered document. See ISO House Style https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-referencing

add the bibitem="" only if the text cites an unnumbered document. See ISO House Style 

Do not use must instead of shall (See ISO/IEC Direcives, Part 2, 2021, Clause 7)

Do not use shall, should or may in NOTES and EXAMPLES (See ISO/IEC Directives, Part 2, 2021, Clause 24 and 25)

.. contents:: The following conventions are defined:
                :local:
                :depth: 1
                :backlinks: top

.. _IDP2 home page: https://www.iso.org/sites/directives/current/part2/index.xhtml

#. Right click on the Association and select Specification
#. In the left hand pane click on the + sign beside the Roles
#. Select the unnamed role represented by a circle
#. Enter the name of the inverse attribute as the name of the role
#. Click on the Owned by field (should be association at present) and change that to Block (accept the change to navigability)
#. Specify the multiplicity
#. set the Is Read Only to true
#. click OK

Click on the Owned by field (should be association at present) and change that to Block (accept the change to navigability)

“common” attributes : id, name, description, sameas, classifiedas

example of the use of dummy instances with initial_view_definition_context

e.g. Representation and Representation_context
representation_in_context attribute is an inverse (not stereotyped, set as read-only) so no need to map it !

For example, a TwistDirection will have a counterpart enumeration in the ARM. In which case we follow a similar pattern to Select types. Create a value property on the Domain Enumeration of type ARM:enumeration (yes enumerations can have properties ;-) call this "value" [1] and public.
For each enumeration literal in the domain model set the slot for the value property to be the corresponding enumeration literal from the ARM
When using the enumeration in another mapping use the value property (containing the ARM enumeration) to bind in the parametric diagram.
If there is no correspondence between domain and ARM then we have to extend this approach.

one port defined (but no parametric diagram) every member goes out with the same types and we have one output port, knowing that each member of the SELECT should be mapped in its own parametric diagram.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/SelectMappingEx1.png

There are few of them (from the common attributes) but used everywhere.

==> when SELECT is hybrid: contains Block Types and Primitive Types

.. figure:: /images/howto/Domain_model_to_ARM_mapping/SelectMappingEx2.png

create an output port for the SELECT in the DomainModel, typed as the SELECT object in the target ARM;

for each of the specializations in the DomainModel's SELECT type, provide a SELECT mapping as a parametric diagram (inside the concerned Block), that shows how the target ARM specialization is mapped to that port.

“Common” attributes : Id, Name, Description, SameAs, ClassifiedAs

Example of the use of dummy instances with Initial_view_definition_context

.. figure:: /images/howto/Domain_model_to_ARM_mapping/idcoremodel1.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/idcoremodel2.png

**CoreModel**: the target entity has a Description/Name attribute.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/namecoremodel1.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/namecoremodel2.png

**CoreModel**: the target entity does not have a Description/Name attribute.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/descriptorselectcoremodel.png

**CoreModel**: the target entity does not have a SameAs attribute.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/sameascoremodel.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/ProxyItemSelect.png

**CoreModel**: the target entity does not have a ClassifiedAs attribute.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/classifiedascoremodel.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/mappingOfDefaultValues.png

We use /IGNORE when a mandatory attribute in the ARM is being replaced by an assignment in the core model.
/IGNORE indicates that the expected value will be find in an assignment.

**NULL** means that an attribute is not set at all . It shall not be a mandatory attribute.
When we have a mandatory attribute in the ARM which has no equivalent in the core model, we need to figure out how to give it a default value in the mapping.
If we cannot, it means that we are missing something in the model and we shall modify either the core or the ARM .
There is a preference for an update of the CoreModel or an agreement on a default mapping value.

 means that an attribute is not set at all . It shall not be a mandatory attribute.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/Initial_view_definition_context.png

A constraint block should be located in the CTC package of the related SELECT.

If the constraint block is not related to a SELECT, the constraint block specific to a CTC should be in the CTC Package.

We don't create a sub-package in the CTC for "Constraint" in the Domain Model layer (unlike the CoreModel).

.. figure:: /images/howto/Domain_model_to_ARM_mapping/constraintOutput.png

represent entities by a block, when there is a need to access to specific attributes (see n°2),

if the constraint's ouput is a “template”, drag and drop it into the view (see n°3).

Fore more information on constraints, see :ref:`how_dmcore_create_constraint` and :ref:`how_dmcore_use_constraint`

.. figure:: /images/howto/Domain_model_to_ARM_mapping/plannedActivity.png

In the **DomainModel**, the mapping of PropertyDefinitionAssignment:

.. figure:: /images/howto/Domain_model_to_ARM_mapping/propertyDefinitionAssignment.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/ClassSelect.png

.. figure:: /images/howto/Domain_model_to_ARM_mapping/ExternalItem.jpg

The proposed mapping will map the ExternalItem to an External_representation_item, then in the mapping of ExternalRepresentationItem we use this mapping (identical!) and add the name property.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/ExternalRepresentationItem.jpg

See :ref:`how_dmcore_combined_classification` and :ref:`how_dmcore_single_classification`

DomainModel mappings should usually follow the CoreModel approach.

.. figure:: /images/howto/Domain_model_to_ARM_mapping/inverse.png

From the example on a BlockDefinitionDiagram that shows InterfaceSpecification and InterfaceSpecificationVersion with the part property versions shown as an association between them do the following:

Adding a new Core Technical Capability [:term:`CTC`] to the Core Model in STEPlib uses the same process as described in :ref:`gs_tlt_newAP` above.

] to the Core Model in STEPlib uses the same process as described in 

.. figure:: /images/1theSteplibArtefacts/highLevelSteplib.png

        High level STEPLIB structure

This section shows how to import an existing self contained |MD| project into the Domain Model.
Importing into other areas and from other formats uses the same process.

 project into the Domain Model.

select **File > Import** and choose the appropriate format (|MD| will match and consolidate where appropriate)

Tidy up, moving the imported content into the correct area of the STEPlib model

<div><video width="854" height="478" controls src="../../../_static/videos/gs_tlt_importFromOtherProject.mp4"></div>

Choose (default) Select project > From predefined location. Then select the existing path that starts with <STEPlib>, and select the file

.. figure:: /images/howto/gs_md_addprofile01.png

        Steps to add an existing profile

Hyperlink target "fig-gs-tlt-steplibmodelstructure" is not referenced.

Hyperlink target "fig-gs-tlt-apexportfinished" is not referenced.

This page describes tasks done by the Team Leader before STEP standards developers can start work.

STEPlib Git repository has already been forked and branched as described in |git teamleader|

STEPlib Git repository has already been forked and branched as described in 

STEPlib Git repository has already been cloned as described in |git developer|.

The MagicDraw environment has been set up, see :ref:`gs_md_top`.

Export the model to a separate project
* Select **Project Usages > Export Package to New Project**
* The project should already be selected in the "Export Package to New Project" dialog, so select **OK**
* **Yes** to "Show Auxillary resources"
* **Yes** to "Check Dependencies"
* In the "Save Dialog"
        * make a **new folder for the AP** in the Application_Protocols folder
        * make a **new dvlp folder** in the the new AP folder
        * the default file name should be the name of the AP
        * the file type should be **mdzip** (default)
        * **save**
* In the "Use Path Variables" dialog, the STEPlib environment variable is selected (default). select *Use Selected*
* On completion a new mdzip file is created in the dvlp folder, and the ApplicationProtocols mdzip has been updated.

.. figure:: /images/howto/gs_tlt_apexport.png

        Export the model

     * Select **Project Usages > Export Package to New Project**
     * The project should already be selected in the "Export Package to New Project" dialog, so select **OK**
     * **Yes** to "Show Auxillary resources"
     * **Yes** to "Check Dependencies"
     * In the "Save Dialog"
             * make a **new folder for the AP** in the Application_Protocols folder
             * make a **new dvlp folder** in the the new AP folder
             * the default file name should be the name of the AP
             * the file type should be **mdzip** (default)
             * **save**
     * In the "Use Path Variables" dialog, the STEPlib environment variable is selected (default). select *Use Selected*
     * On completion a new mdzip file is created in the dvlp folder, and the ApplicationProtocols mdzip has been updated.

     .. figure:: /images/howto/gs_tlt_apexport.png

             Export the model

Open the ApplicationProtocols project (see :ref:`gs_md_opensubmodel`)

M-R on the ApplicationProtocols in the tree and select **Create Element** and then select **model**

     .. figure:: /images/howto/gs_tlt_ap01.png

             Create Element > Model

.. figure:: /images/howto/gs_tlt_ap01.png

        Create Element > Model

**Add a comment** with the full name of the AP

     .. figure:: /images/howto/gs_tlt_ap02.png

             Rename and add comment

.. figure:: /images/howto/gs_tlt_ap02.png

        Rename and add comment

Open the new ApplicationProtocol project (see :ref:`gs_md_opensubmodel`)

Add the Core model (and/or other needed models) by setting to **Use Local Project**
     * Select File > Use Project > Use Local Project
     * Select **1. Select project** amd then **From predefined location**
     * Select the location or add a new location using the "..." button
     * select the mdzip from STEPlib/Core_model/dvlp/Core_model.mdzip
     * click **Next** (2. Specify usage options).
             * **Accessibility** of **Read-only** should be used to prevent accidental editing
             * **Load Mode** default is **Always Load**, change to improve performance if needed
     * Finish

     .. figure:: /images/howto/gs_tlt_apuselocalproject.png

* Select File > Use Project > Use Local Project
* Select **1. Select project** amd then **From predefined location**
* Select the location or add a new location using the "..." button
* select the mdzip from STEPlib/Core_model/dvlp/Core_model.mdzip
* click **Next** (2. Specify usage options).
        * **Accessibility** of **Read-only** should be used to prevent accidental editing
        * **Load Mode** default is **Always Load**, change to improve performance if needed
* Finish

.. figure:: /images/howto/gs_tlt_apuselocalproject.png

Select **1. Select project** amd then **From predefined location**

Select the location or add a new location using the "..." button

click **Next** (2. Specify usage options).
      * **Accessibility** of **Read-only** should be used to prevent accidental editing
      * **Load Mode** default is **Always Load**, change to improve performance if needed

* **Accessibility** of **Read-only** should be used to prevent accidental editing
* **Load Mode** default is **Always Load**, change to improve performance if needed

**Accessibility** of **Read-only** should be used to prevent accidental editing

**Load Mode** default is **Always Load**, change to improve performance if needed

Under the new Model (from step 2) create a new model called **ActivityModel**

Export to a separate project stored APxx/ActivityModel/dvlp/ and set to **Use Local Project**

Export to a separate project stored APxx/ActivityModel/dvlp/ and set to 

Under the new Model (from step 2) create a new model called **ConceptualModel**

Export to a separate project stored APxx/ConceptualModel/dvlp/ and set to **Use Local Project**

Export to a separate project stored APxx/ConceptualModel/dvlp/ and set to 

Under the new Model (from step 2) create a new model called **DomainModel**

Export to a separate project stored APxx/DomainModel/dvlp/ and set to **Use Local Project**

Export to a separate project stored APxx/DomainModel/dvlp/ and set to 

The project should already be selected in the "Export Package to New Project" dialog, so select **OK**

The project should already be selected in the "Export Package to New Project" dialog, so select 

In the "Save Dialog"
      * make a **new folder for the AP** in the Application_Protocols folder
      * make a **new dvlp folder** in the the new AP folder
      * the default file name should be the name of the AP
      * the file type should be **mdzip** (default)
      * **save**

* make a **new folder for the AP** in the Application_Protocols folder
* make a **new dvlp folder** in the the new AP folder
* the default file name should be the name of the AP
* the file type should be **mdzip** (default)
* **save**

make a **new folder for the AP** in the Application_Protocols folder

In the "Use Path Variables" dialog, the STEPlib environment variable is selected (default). select *Use Selected*

In the "Use Path Variables" dialog, the STEPlib environment variable is selected (default). select 

On completion a new mdzip file is created in the dvlp folder, and the ApplicationProtocols mdzip has been updated.

.. figure:: /images/howto/gs_tlt_steplibModelStructure.png

        STEPLIB Model Structure – Package diagram

.. figure:: /images/howto/gs_tlt_apexportfinished.png

        STEPLIB Model Structure – for AP

This explains how to add a new Application Protocol [:term:`AP`] to STEPlib.

:numref:`fig_gs_tlt_steplibModelStructure` below shows the model structure of an AP.

<div><video width="854" height="478" controls src="../../../_static/videos/gs_tlt_newAP.mp4"></div>

On completion, the containment tree should be as shown in :numref:`fig_gs_tlt_apexportfinished` below:

.. figure:: /images/howto/STEParchitectureDMServices.png

This page uses a simple example to describe how to model the the Services for the Domain Model using SysML in MagicDraw 18.4.

These are the **C-R-U-D like** services rather than the query-like services which are embedded in the :ref:`Domain Model<how_dm_queryservices>` templates.

(|TBA|) These services are common to all templates in the Domain model.

) These services are common to all templates in the Domain model.

Build documentation of 10303-239, 10303-243, 10303-4000 and 10303-4442 with the VMs  (need an update)

4.6.2   References to other International Standards and documents