.. comment
	
	all inline tags to start with _how_dm_

.. index:: pair: Domain Model; How to
.. index:: pair: Appplication Domain Model; How to

.. _how_dm_top:

####################################################
How to model the Application Domain Model of STEPLIB
####################################################

.. include:: /pages/common/pageunderconstruction.txt
	:start-line: 3

.. contents:: Contents:
	:local:
	:depth: 1
	:backlinks: top
  
********
Overview
********

.. figure:: /images/howto/STEParchitectureDM.png 
	:align: right
	:scale: 55%
	
	The STEP Architecture

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. 

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


******************
Step by Step guide
******************

.. contents:: The modelling steps are:
		:local:
		:depth: 2
		:backlinks: top
  
  
===========
Preparation
===========

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

.. important:: Prerequistes

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



	
.. _how_dm_template:

.. rst-class:: expand

=====================================================
Original instructions from PLCSlib
=====================================================

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

.. caution:: 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

.. raw:: html

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

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

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

.. raw:: html

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

.. todo::

	the step-by-step for this section
	
	#. create a new package (no longer needed)

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

		Adding a new Package for the Template

	#. Add a block

	.. figure:: /images/howto/DM_addnewtemplate.png 
		:scale: 100%
	
		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 
		:scale: 100%
	
		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 
		:scale: 100%
	
		Adding a Template to a diagram



	Add owner above
	
	.. figure:: /images/howto/ht_common_displayNamespace.png 
		:scale: 100%
	
		Add Owner **Above Element Name**
	
	Change colours
	

	
============
Descriptions
============

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

.. rst-class:: expand

------------------
Description format
------------------

.. include:: howtoDescription.txt


.. index:: Domain Model; How to - document problems and rationale

================================
Problem and Rationale Comments
================================

.. include:: howtoProblemComment.txt



.. index:: Domain Model; How to - Diagrams
.. index:: Application Domain Model; How to - Diagrams
.. index:: Diagrams; How to - Block Definition diagrams for the Domain Model

.. _how_dm_bdd:

=========================================
Block Definition Diagrams - general rules
=========================================

.. include:: 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);
* For the R-G-B to use see :ref:`BDD Colours<how_colours_bdd>`;
* 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 
	:scale: 100%
	
	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

.. figure:: /images/howto/ht_dm_bdd_aux.png
	:scale: 100%
	
	Layout when many members (this example is for illustration, the grid layout is not nessary and the overlay above would be more appropriate)
	
============
Entity Types
============	

.. contents:: The modelling steps are:
		:local:
		:depth: 1
		:backlinks: top
	
.. index:: Domain Model; How to - Blocks
.. index:: Blocks; How to - Domain Model
.. index:: Application Domain Model; How to - Blocks
.. index:: Blocks; How to - Application Domain Model

.. _how_dm_blocks:

------
Blocks	
------

.. todo::
	
	text for this section
	
.. index:: Domain Model; How to - AbstractBlocks
.. index:: AbstractBlocks; How to - Domain Model
.. index:: Application Domain Model; How to - AbstractBlocks
.. index:: AbstractBlocks; How to - Application Domain Model



.. _how_dm_abstract:

---------------
Abstract Blocks	
---------------

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


.. todo::
	
	text for this section
	
	see :ref:`Blocks<how_dm_blocks>`
	then set abstract=true
	
.. index:: Domain Model; How to - SelectTypes
.. index:: SelectTypes; How to - Domain Model
.. index:: Domain Model; How to - Auxiliary
.. index:: Auxiliary; How to - Domain Model
.. index:: Application Domain Model; How to - Auxiliary
.. index:: Auxiliary; How to - Application Domain Model

.. _how_dm_auxiliary:

----------------------------------
Auxiliary or "Select Types" Blocks
----------------------------------

.. tip::
	
	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.

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 
	:scale: 100%
	
	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.
	
.. note::

	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.
	
The Steps are:
	
#. Create a new block (in auxiliaries package - optional)
#. Add a name that reflects the intended use (no official convention)
#. Add description
#. 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.)
#. 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 
	:scale: 100%
	
	Auxiliaries (or SelectTypes) specification
	
See also :ref:`how_dm_bdd`

.. index:: Domain Model; How to - Enumerations
.. index:: Enumerations; How to - Domain Model
.. index:: Application Domain Model; How to - Enumerations
.. index:: Enumerations; How to - Application Domain Model

.. _how_dm_enumerations:

------------
Enumerations
------------

.. todo::

	#. 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 
		:scale: 100%
	
		Reference data added to an enumeration. 

===========================		
Properties and Associations
===========================

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.

.. contents:: The Types of Assocation are:
		:local:
		:depth: 1
		:backlinks: top

.. include:: /pages/sysmlConstructsRelationTables.txt

.. index:: Domain Model; How to - Redefined properties
.. index:: Redefined; How to - Domain Model
.. index:: Application Domain Model; How to - Redefined properties
.. index:: Redefined; How to - Application Domain Model

.. _how_dm_redefined:

====================
Redefined Properties
====================

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. 

1. Double-click on the property to open the Relation Diaglog
2. in **Redefined Property** select the property from the supertype
3. Change the **multiplicity** if needed

.. figure:: /images/howto/ht_dm_derived02.png 
	:scale: 100%
	
	Redefined property set to readonly with a default

If the refeined property is to have a fixed value:

4. set **Is Read Only** to true
5. 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 
		:scale: 100%
	
		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 
		:scale: 100%
	
		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 
		:scale: 100%
	
		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 
		:scale: 100%
	
		InstanceSpecification with Reference Data URI
		
6. 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 
		:scale: 100%
	
		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 
	:scale: 100%
	
	Redefined property set to readonly with a default on diagram


======================
Validation Constraints
======================

.. include:: howtoAddValidationConstraints.txt
	
For details on validating against the constraints see :doc:`howtoValidationConstraints`


		
.. index:: Domain Model; How to - Query Services
.. index:: Query Services; How to - Domain Model
.. index:: Application Domain Model; How to - Query Services
.. index:: Query Services; How to - Application Domain Model

.. _how_dm_queryservices:

===================
Query-like services
===================

.. todo::

	text of this section
	
	.. image:: /images/common/construction.png
		:width: 100
		:align: left
	
	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:`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.

  
	
.. sectionauthor:: |Judith Crockford|

.. include:: /keywords.rst