How to model the mapping between the Activity and Data Planning models of STEPLIB¶
Contents:
Figure 89 The STEP Architecture
Step by step when AAM uses Data Planning objects as Conveyed Information¶
The mapping between the Application Activity Model and Application Data Planning Model is achieved using Data Planning objects as the conveyed information on object flows between activities in the Application Activity Model. This is described in How to model the Application Activity Model of STEPLIB
Step by step when AAM includes Conveyed Information blocks¶
Contents:
Some Application Activity Model have conveyed information defined as blocks in the model. These blocks are mapped to the blocks in the Application Data Planning Model. This is shown in a (rough) video
Todo
Make a better video
Descriptions¶
Add a description to the references to explain the rationale.
Description format¶
The WG12 Review Checklist (QCN265) 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)”.
See Supplementary Directives for the official directives.
See also Naming.
The following are a summary of the 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 6.4.9.4 Plurals of “shall” “shall not” “is required to” “only...is permitted” “must” “most not” 4.8 Acceptable wording “should” “should not” “is recommended that...” “ought to...” 4.8 Acceptable wording “may” “need not” (i.e. permissable in limits of standard) “is permitted” “is allowed” 4.8 Acceptable wording 4.8 Acceptable wording “can” “cannot” (i.e. something that is possible) “to be able to” “it is possible to” 4.8 Acceptable wording <note></note> ot “that is” “i.e.” 4.8 Acceptable wording <example></example> “e.g.” “etc” (“for example” ) 4.8 Acceptable wording and/or 4.10 Words to avoid datum <xyz>s (e.g. datum points) datums 4.10 Words to avoid use utilise 4.10 Words to avoid that is which is 4.11 Frequently used words data are data is 4.11 Frequently used words between = 2 among = 2 or more than 2 4.11 Frequently used words 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.”
Tip
Care should be taken with Carridge-Return ( ) and Line-Feed ( )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>.
- 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.
- 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.
- Examples and Notes
See also 4.4.4 Examples and 4.4.3 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>
- Figures and Tables
See also 4.4.1 Figures and 4.4.2 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.
for example:
<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>
Tip
The xmi:id of a diagram can be obtained using a macro. See also Load Macros for how to load a macro.
Figure 90 Run “Get UUID” macro to see the ID and the UUID
- Lists
Bulleted lists use standard HTML notation of ul and li tags (see also 4.5 Lists)
the ”;” (all but last) and ”.” (last) must be included.
for example:
<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 4.6 References within the text)
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/>
- 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/> <ul><li>first bullet;</li><li>second bullet.</li></ul> <note>This is the first note referencing a figure (see following Figure).</note> <note>This is the second note.</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 91 How the example formatted description is displayed in the documentation