Welcome to the MagicDraw UML "tips and tricks" tutorials !

So Grasshopper, you come to learn the great secrets
of the powerful MagicDraw UMLTM tool and plugins !

Dr Darren takes you through some of the tried and tested "tips and tricks" for power modelling in the MagicDraw UMLTM tool. The UMLTM mountain is high and hard to climb; there are many ways up the mountain, some are most treacherous, some are very rewarding, and sometimes the best way up depends on the weather. Let your joyful journey to UML mastery begin ! We are always both students and teachers of UML.

Visit also:

Dr Darren's UML style tips

Please find here Dr Darren's style guidelines. I have found the style tips and recommendations here work on a wide range of problems. Style is a personal matter, and if you have other style preferences please do use them.

DO NOT use the diagram grid unless you are doing geometrical engineering

I recommend that you switch of the "show grid" option yet leave the grid placement behavior on, unless you really do want to exploit the grid feature for precise "geometrical" engineering diagramming.

DO use black borders and white (or no) fill for serious engineering, use colours only to highlight ERRORS and ISSUES

Dr Darren says "Use B/W and coloured pen only for exceptional states and/or test results"

The more I work with UML and SysML the more convinced I am of this, even if it is a contentious view.
And you will find that throughout this eSchool I apply this principle more often than not.

PROS of using black pen and no fill include:

  1. reduces arbitrary bias that has no place in engineering and can even be dangerous
  2. prints better
  3. emphasises UML over a particular tool's colour scheme, and thus appeals better to the wider UML community
  4. provides a suitable background for coloured states like: ERROR (I use red pen) and ISSUE (I use orange pen) and OK (I use green pen)
  5. black and white DOES reduce the noise in your head and DOES help you to concentrate on content (engineering) rather than cosmetics

In particular, I recommend that you do not work with the default MagicDraw UML colour styles for serious engineering, even though many customers are used to them:

  1. the MagicDraw UML colours are completely arbitrary, and they promote arbitrary colour associations.
  2. using the MagicDraw UML colours (or other colour schemes will strong fill and pen style) makes it much harder to use coloured pens to indicate states like ERROR and ISSUE.

Again, these are my opinions, not those of No Magic or the MagicDraw developers, so please do use whatever works for you.

Advanced example: using pen colour for themes and refactoring states

Used sensibly coloured pen styles can aid your diagramming and communication

In this example coloured pen styles are used to collect themes in a very complicated diagram.

In this example of a conformance analysis of the SysML1.0 spec's Rate stereotype against the MD SysML 15 Plugin I have used:

  • purple for things related to ActivityEdge
  • blue for things related to Parameter
  • cyan for things related to ObjectNode
  • yellow for things related to <<Continous>> and <<Discrete>> (and yes, it is hard to read)

Please note:

  • This technique ONLY works well when:
    • you use no fill colour at all
    • you use black pen colour be default otherwise (to afford contrast)
    • you DO NOT use the MagicDraw UML default colour schemes
      (which I recommend against for most work)
  • I recommend that you reserve Red, Orange, and Green for my "traffic light" system:
    • use red to flag ERRORs: (means STOP! or DANGER!)
    • use orange to flag ISSUEs or refactoring or problems: (means PAUSE, slow down, rethink.)
    • use bright green (not shown) for OK, asserts has been tested and/or analysed and it PASSED (means GO!)
    • use the project options (clone the default) and create ERROR, ISSUE, and OK styles
      (rather than constantly having to remember which colours mean which)
  • Other colours are used to collect related themes (such as in this case applications of the stereotype to different metaclasses). Note that:
    • you will run out of sensibly distinguished colours after about 5 (considering red, orange, and bright green are reserved)
    • yellow (deliberately left in) is not a good choice !

Please also always be mindful that not all people can see all colours well.

 

 

DO use Comments rather than notes (unless you need callout of Element Properties) and DO stereotype Comments strongly

PROS of using the Comment:

  1. It is a reusable Element of the model and changes made to a Comment in one diagram will propagate to other diagams
  2. It can (and should) be stereotyped strongly. If you are not using a strong stereotype please DO NOT display the <<comment>> stereotype, I suggest that in that case you simply do not show stereotypes.
  3. A Comment can be packaged, and you can show the owner (try it).

CONS of the Comment:

  1. You can't do Element Property callout into a Comment, for that you must use a Note.

Visit also:

 

DO use lower case first letter for all property, port, and instance names

I recommend Java-style field names for all property, port, and instance names.

For example:

    animal: Animal 

    in: Port

 

 

 

DO use the diagram info box on all diagrams, even ones with diagram frames, except for special publishing reasons

It is important to show the date and author and modification time of all of your diagrams, unless you have special reasons not to, like publishing conditions.

TIP: if the diagram info box and the diagram frame title clash then place the diagram info AT THE BOTTOM. This has the advantage in large diagrams that the diagram name be read easily in two places, and does not distract readers as much.

HOWTO use UML2 Components as graphical and logical wrappers

In MagicDraw UML the UML2 Component element and its rectangular symbol can be used (misappropriated well) to graphically and logically group other UML elements without "stealing ownership". This advanced strategy can greatly aid power diagramming, model organisation, and logical decomposition of complex systems.

Ownership and the parasitic wrapper Component

Here we show how elements owned by another element (such as a Model or a Package) can be visually contained within and logically grouped using "wrapper" Components.

NB: this powerful technique does NOT leverage the semantics of the UML2 Component,  it exploits merely mechanical features of the Component element and its rectangular symbol. Hopefully in the future UML will provide a semantically neutral element for this purpose. The technique is also specifically tuned to the MagicDraw UML tool.

 

Physical ownership vs. logical grouping in MagicDraw UML

in MagicDraw UML and MD SysML it is possible to have an element
contained in one Package / Model in the browser (in the actual model),
yet visually contained within the boundary of the rectangle of
a number of Components in any number of diagrams:

  • If one moves any Element from a Package/Model to a Component in
    the browser     the Component takes ownership.
  • If one moves a Classifier from anywhere on a diagram into
    (within the rectangular boundary of) a Component in a diagram,
    that Component does NOT take ownership of the Classifier, the original
    ownership is preserved. A Realization relationship is generated between the visually contained Classifier this is
    what enables me to create "Class collaborations", and "composition views" of Blocks,
    Classes, and Artifacts without disturbing ownership.
  • By contrast, if one moves a Comment on a diagam into (within the
    rectangular boundary of) a Component in a diagram,
    the Component takes ("steals") ownership.

Concise view of wrapper Component, no ownership or Realizations shown

Usually one does not show the Realizations between visually contained elements and a "wrapper" Component.

Elements related to the wrapper_ Magicdraw UML 15.0

One can leverage the Realization relationships between visually contained elements and a wrapper Component for tracing logical groupings.

Advanced example: conformance analysis of SysML specification for Rate stereotype vs. MD SysML Plugin

WARNING: This is deliberately a very advanced example with many cross references, dependencies, and associations.
Your own diagrams should be much simpler, please do divide-and-conquer into many smaller diagrams.

 

Please note the following aspects:

  1. for most text parsed from the <<SysML1.0>> spec simple stereotyped Comment elements are used
  2. for some text parsed from the <<SysML1.0>> spec stereotyped Artifact elements are used, so that dependencies to other elements can be established (which can then be shown again easily on other diagrams using Display Related Elements)
  3. all Comments and Artifacts are very carefully packaged (owned) to reflect the specification chapters
  4. the wrapper Component technique is used to package elements of the parsed context (in this case 11.3.2.8 Rate)
    1. there are many cross references to other wrapper Components, which carry hyperlinks to their focus diagrams
    2. the wrapper Components are mostly styled faint so that they do not distract from the wrapped elements
  5. there are many navigation paths to other points in the model using diagram icons

On using singleton wrapper Components to provide documentation and navigation points for read-only classes

It is often useful to parasitically wrap Class elements (like the read-only metaclasses of the UML and SysML profiles for Magicdraw).

Some reasons include:

  1. one can't add hyperlinks to read-only elements
  2. one can provide a different packaging context - such as relationship to chapters of a technical document that refers to wrapped read-only Class.
  3. one can provide a container for documentation and parsed text related to the read-only element

Example: Analysis of SysML1.0 Figure 11.8 - Abstract Syntax for SysML Activity Extensions in MD SysML 15

I use a wrapper Component 11.3.2.3 Discrete to contain information about the SysML stereotype Discrete:

  • the <<Discrete>> stereotype is in the read-only SysML Profile.Activities)
  • the 11.3.2.3 Discrete Component is the "conformance wrapper" for the stereotype:
    • it carries a hyperlink to a diagram about  the "concept" 11.3.2.3 Discrete as described in the spec (as opposed to the implementation in MD SysML
    • it has a parastic Realizes relationship to SysML Profile.Activities.Discrete (see next images)

This is repeated for each and every stereotype in the specification, which is the basis of the conformance process using UML Parsing Analysis.

Example: a singleton wrapper Component "opened up" into the "focus" diagram for its wrapped Class

If one clicks on the 11.3.2.3.Discrete conformance wrapper Component it opens up into a conformance analysis diagram.

The conformance wrapper graphically contains things determined to be directly related to the specification of the element. It DOES NOT however steal ownership of elements from outside, like the read-only metaclass (see the owner of each element). This is the feature of MD UML that makes wrapper Components possible.

TIP: provide some alternative navigation paths out of diagram using diagram icons and/or the parent wrapper (which is hyperlinked to a diagram)

 

HOWTO easily assign multiple diagram hyperlinks and GoTo to a chosen one in MagicDraw UML

The following example is from MD SysML Plugin and uses a Block with multiple Internal Block Diagrams (IBDs), however the same principle works for Composite Structure Diagrams in MD SysML.

The "active" hyperlink is the one that is used when you click on a symbol, however you can have more than one hyperlink.

Structured Classes (& Blocks) and the "focus" diagram in MagicDraw UML (& MD SysML)

By default a structured block (see the diagram menubar) in MD SysML gets a "focus" IBD of the same name and the name of it is synched to the block name: it is also set by default as the active hyperlink. (On MD UML a structured class gets a "focus" Composite Structure Diagram.) So when you first create a structured block just clicking on it will open up its "focus" IBD.

Assigning multiple diagram hyperlink targets

You can also assign and get to any of the other diagrams easily, too. Simple drag any number of diagram icons onto your block ! (The last one dragged will become active, so if you want your original focus diagram as active again, drag it on again.)

This has already been done for the example below. The aim is to have separate IBDs dedicated to electrical, mechanical, and optical systems, each one representing a different view of parts of the same block. (When doing this it is a good idea to use a lower case diagram name, so that they are not named like "focus" diagrams that correspond to Blocks.)

Now follow the trail to the next diagram to see how to choose to GoTo a given target diagram.

 

Click once on a symbol and a small hyperlink icon will appear bottom left

Make sure you only click once on the symbol (otherwise you'll already go to the currently active hyperlink target).

Click once (only) on the tiny hyperlink icon to bring up a pull-down menu of target diagrams you can GoTo

The image shows a Symbol with multiple hyperlink targets showing.

Closeup of multiple hyperlink targets

Note also the Usage in Diagrams sub-menu; please explore this alternative way to navigate.

Follow the Usage In Diagrams sub-menu on a symbol to reach other diagrams in the project that show the symbol

When you click on the little hyperlink icon bottom left of a symbol you can choose between:

  • selecting one of the (possibly multiple) assigned hyperlinks
  • going deeper into the Usage in Diagrams sub-menu, which shows every diagram where a symbol for the chosen element appears

The Usage in Diagrams option is particularly good for navigating to SysML BDDs (UML2 class diagrams) of (possibly unknown and unanticipated) "assembly" blocks that use a given Block (or Class):

  • the usage context should not be anticipated by a used element; so placing a diagram symbol for a "composing" parent on a main diagram for a used Element is not usually recommended:
    • consider that the diagram icon for a parent packaged elsewhere can block modularisation of your reusable building blocks !
  • The Usage in Diagrams feature is computed "on-the-fly"; it even works for symbols of read-only elements !

Diagram: somewhere else showing Block used by a composing "parent" Assembly

One can navigate to this diagram from the Block's symbol using the GoTo Usage in Diagrams feature.

The Internal Block Diagrams (IBDs) assigned to the Block symbol as diagram hyperlinks

Just for completeness, the full set of IBDs for the Block are given.

Block IBD

Shows all parts of the system (only stub parts are shown, they are placeholders for parts of different layers).

electrical IBD

Would show all parts of the electrical layer, only one shown.

mechanical IBD

Would show all parts of the mechanical layer, only one shown.

optical IBD

Would show all parts of the optical layer, only one is given.

HOWTO use validation in MagicDraw UML to improve model integrity

MagicDraw UML employs at least three types of model validation:

  1. Preventative Validation: it is not possible to combine certain kinds of elements and relationships that do not agree with the UML specification, for example one can't make a Connection between InstanceSpecifications (one can however make a Link).
  2. Active Validation: when constraints and validation rules from active validation suites are broken the tool flags errors in the  model "actively" with a coloured validation error box around a problematic element's symbol (the colour will depend on the severity level, a warning is yellow), and with a little red cross in the containment browser, and offers possible fixes.
  3. Passive Validation: the rules are only applied if explicitly selected under menu Analyze>Validation.

Please visit also:

HOWTO use the active validation engine to apply fixes in MagicDraw UML [INCUBATING]

Since MD15.5.

When constraints and validation rules from active validation suites are broken the tool flags errors in the  model "actively" with a coloured validation error box around a problematic element's symbol (the colour will depend on the severity level, a warning is yellow), and with a little red cross in the containment browser, and offers possible fixes

Visit also:

HOWTO: provide/require Interfaces via Ports for service orientation in MagicDraw UML: Quick Start Guide


This tutorial trail presents some of the basic steps for managing port-based service oriented systems in MagicDraw UML using the provided/required Interface mechanism of UML2.

Define port-based services first at the Class/Component level in a "focus" diagram

I recommend that you have a class or implementation "focus" diagram for each port-based class and define/declare and document its ports and required and provided services there, BEFORE connecting it up in any particular usage context.

To create an InterfaceRealization from a typed Port to "provide" an Interface you can use:

To create a Usage from a typed Port to "require" an Interface you can similarly use:

Note that the PORT MUST BE TYPED already, otherwise it makes no sense for it to realise or use anything, because it is in fact the TYPE that realises or uses the interface.
That Type (a BehavioredClassifier) of the Port will then be seen to realise (provide) and use (require) the same interfaces (see next images).

TIP: please also read the MagicDraw UML help pages for InterfaceRealization and Usage !

HOWTO display port and service information in the compartments of a Class or Component

Once ports are defined they may also be display as a lists in a compartment (rather than always showing the square-box notation which can be fiddly and leads to clutter, and is only really necessary for classifier-level "dependency wiring" in class-level diagrams or instance-level connections in structure diagrams).

In a Class simply disable the display option Suppress Ports.

In a Component you may additionally disable the display option Supress Interfaces to show the services provided and realised by the Component

Interfaces provided/required by predefined Port classes

Interfaces are in fact provided or required by Ports via the BehavioredClassifiers that type them (for most intents a purposes you may just think of the "Class" that types the Port). Here display related elements and/or display paths under the related elements menu has been used to show the Interfaces required and provided by the Classes used as types of the Ports of Class HasPorts in the previous example.

Plan connections first using architectural Dependency wiring

It is a good idea in MagicDraw UML to plan your connections "architecturally" first using Classifier-level Dependency wiring, which shows what may be validly connected, as opposed to what is connected in a particular context. This enables one to provide and require all necessary Interfaces before attempting to build a specific higher-order system. This process is supported in MagicDraw UMl; by the Display Paths and Display Related Elements features.

Connecting up "instances" of port-based service-oriented Classes within a higher usage context

In the Composite Structure Diagram for a specific usage context use drag n' drop to build your system out of part Properties (which may or may not have Ports). Each part Property is a specification of one or more instances that may be created whenever an instance of the parent context is created. Use Display Provided Interfaces and Display Required Interfaces to display the interfaces required and provided by each port as "lollipop and fork" notation. This gives information (only) about the services required and provided via ports.

Optionally, the "conjugated" service provided and required via a particular Connector may indicated by dragging the provided Interface onto the Connector to make that Interface the 'conveyed' Classifier of an InformationFlow (notational only). This can help visualise what services are connected (as opposed to which services may be validly connected).


TIP: future versions of MagicDraw UML will have active validation of connections w.r.t. provided/required interfaces

Service oriented usage context: tuning the "associative" class diagram after the composite structure is created

After you have created a composite structure (by using convenient drag n' drop to create part Properties) you may go back to the matching "architectural" class diagram used for planning the connections and generate composition associations (if you wish) by dragging the part Properties out of the context Class (i.e. they become "roles", Property ends of composing Associations from the context Class).

TIP: I recommend that you avoid trying to "compose" complex systems using associations; prefer the  structure diagram "systems-engineering" approach wherever possible ! Note also that you can't show connections in a purely classifier-level diagram, so the associative composition diagram only shows only a subset of the structural information anyway.

Scalable Vector Graphics (SVG) in MagicDraw UML

MagicDraw UML offers a wide range of diagram export formats via the menu File>Save as Image.

The W3C's Scalable Vector Graphics (SVG) format is supported, however for online presentation this may exclude some of your audience. From http://en.wikipedia.org/wiki/Scalable_Vector_Graphics:

Support for SVG in web browsers

The use of SVG on the web is in its infancy; there is a great deal
of inertia due to the long-time use of pure raster formats and other
formats like Adobe Flash or Java applets, and browser support for SVG is still uneven. Web sites which serve SVG images, for example Wikipedia, typically also provide the images in a raster format, either automatically by HTTP content negotiation or allowing the user to directly choose the file.

This is also why this eSchool also serves most images as JPEG or PNG.

We compare here file sizes and behavior under scaling of an exported test diagram in MagicDraw UML. 

Visit also:

JPEG diagram export at 300 DPI

As scaled by factor 3:

JPEG diagram export at 72 DPI (32KB)

As scaled by a factor 3:

 

PNG image export at 72DPI (20KB)

Scaled by factor 3:

SVG diagram export (84KB) [FAILS TO LOAD]

FAILS to load in Drupal

TIFF diagram export at 72 DPI (20KB) [FAILS TO LOAD]

FAILS to load in Drupal CMS.

HOWTO use editorial <<stereotype>>s in Comments [Incubating]

Examples of good ways to use sterotyped comments to refactor and annotate your UML projects.

See also:

The UML Parsing Analysis recipe

In this interesting and novel tutorial trail you will learn how to translate technical texts into UML models, using Dr Darren's innovative UML Parsing Analysis recipe - adapted to MagicDraw UML. This very powerful and effective technique can be combined with all of your requirements analysis, systems analysis, software engineering and systems engineering work, as well as with analysis and modelling of other technical, scientific, and even artistic topics.

The UML Parsing Analysis leverages two main techniques explored in related tutorial trails that you should study first:

  1. HOWTO use UML Components as logical and graphical wrappers in MagicDraw UML
  2. HOWTO use editorial stereotypes in Comments

There is a limitation to the degree and flexibility of binding afforded by handles from UML Comments drawn to model elements, since Comment handles are not true relationships, they do not appear in the UML model (repository) proper, and they are not easily traced. We will therefore also be exploring how to parse text into (misappopriated and stereotyped) Components (and optionally Artifacts) as "relatable parsing containers", and how to use Dependencies for very powerful and flexible UML Parsing Analysis. The widely practised, age-old technique of just copying technical text into Comments and relating them loosely with handles does not meet the requirements for the UML Parsing Analysis recipe; only the "happily misappropriated" stereotyped Component meets Dr Darren's conditions, and it is a truly powerful relatable parsing container.

Plenty of examples are available both within this eSchool and other sites: please do complete this tutorial trail here before visiting these resources (and then do please come back) !

Candidate source for the UML Parsing Analysis recipe

Text sources that can be parsed into Comments bound to your UML model elements include:

  • software specification documents like the UML and
    SysML specs can be mapped into conformance models (which are the
    primary examples for this tutorial trail)
  • architecture documents and systems analyses can be bound to analysis classes
  • software documentation can be bound to forward- or reverse-engineered UML design classes
  • software requirements documents can be "eaten up" and bound to requirements elements such as Use Cases or SysML requirements.
  • systems design manuals can turned into SysML block models (we will be exploring actual examples using real scientific instruments)
  • descriptions of complex systems can be translated into UML analysis models (for example we will be exploring animal taxonomies from Wikipedia articles)
  • vision statements can be translated into UML posters (including executable elements to demonstrate the achieved vision).

HOWTO use relatable UML Classifiers as parsing containers that can carry Dependencies to other Elements

It is often handy to be able to parse text into a relatable UML Elements (rather than into a Comment with just "handles") so that one can leverage Dependencies and the Display Related Elements facility of MagicDraw UML. Although a DirectedRelationship can be made between base Elements, the UML Parsing Analysis recipe employs (at least) the Dependency as the relationship, and (at least) a NamedElement. as a "parsing container" to hold the parsed analysis text.

There a number of candidate Classifiers that are suitable as relatable parsing containers, including:

  • Component offers itself very well (if clearly stereotyped as a semantic misappropriation) because:
    • it can participate in ComponentRealization dependencies, which can be
      easily traced to the contents of the Component as parsing container
    • it can nest (both graphically and physically) to form trees of parsed text
    • it can graphically contain other elements to form "parasitic" logical views:
      • TIP: In MagicDraw UML the Component symbol does not "steal ownership" of elements moved into it in a diagram
        • WARNING: the Component element in the model browser will correctly steal ownership of elements moved into it in the browser
  • Artifact also offers itself because:
    • it is traditionally associated with documentation
    • it can nest (both graphically and physically) to form trees of parsed text
    • con: it can't graphically contain other important elements, such as Class
  • Class is NOT a candidate, as it can't graphically nest, so it fails an important requirement of the UML Parsing Analysis recipe

DO NOT use Package (or Model) as a parsing container, as it steals ownership of elements, and thus is ill-suited to forming logical views !

I recommend that you parse text into Comment first then only "upgrade" to a Classifier if really necessary. Reasons for upgrading include:

  1. you want to reuse the parsed text many times in different places easily by using Display Related Elements
  2. you want to relate other elements to the parsed text in a reusable way

HOWTO use stereotyped Components as parsing containers for technical text

A very good candidate for a relatable parsing container is the Component (a Classifier): In the "self-referential spirit" of UML Parsing Analysis the example below is a UML Parsing Analysis of one of the pages from this tutorial trail.

PROS:

  1. can be packaged
  2. can carry dependencies
  3. can contain/own other elements (like other Classes, Components, Comments or Artifacts):
    • can therefore contain (nest) easily other Components used as parsing containers:
      • the nested parsing container Components form a wonderful parsed text tree in your analysis model !
      • try using Show Owner on nested parsing container Components, very powerful !
  4. The Component symbol can graphically contain other elements that it does not necessarily own:
    • WARNING: the Component element in the model browser will correctly steal ownership of elements moved into it in the browser
    • In MagicDraw UML the Component symboldoes not "steal ownership" of elements moved into it in a diagram

CONS:

  1. Not intrinsically distinguished from Class or Component as used for software engineering:
    • This very useful and powerful misappropriation of the UML2 Component seems to unnecessarily annoy certain UML2 purists.
    • Indeed as long as one does not over-use the attributes, operations, or features specific to UML2 Component  semantics there is no problem:
      • Just clearly stereotype your parsing container Component to indicate the parsing context and/or parsed text source:
        • example: «UML2», «UML2», «SysML», «design manual», «source:test-456-ITC», «fredd.bloggs@somewhere.net»
      • use pen- or fill- colour and/or italic text to distinguish the parsing container Component symbol visually from other Component symbols
      • make sure that the option Header in bold is off (use Header in bold only for regular Components adhering to strict UML semantics)
  2. One can't use HTML text style:
    • I recommend that you turn of the Header in Bold option and turn on the Word Wrap option so that the name used as text displays well
  3. In MagicDraw UML the Component is only available on diagram menus of certain diagram types
  4. In MD SysMLthe Component is not even allowed (Block extends Class) and is not offered on any SysML diagrams
    • this useful misappropriation of the Component as a relatable parsing container and/or logical wrapper of blocks seems to
      unnecessarily annoy certain fanatical devotees SysML, too.
    • please use it freely in MD SysML,, however know that your model is not compliant with SysML1.0 (although it may still be very useful).

Despite these subtleties, if you really want the most powerful tecnical analysis modelling results, this is a very, very powerful strategy !

Component as relatable parsing container (with Dependencies) vs. Comment as parsing container (with handles)

In the following image we see a parsing ot the familiar UML2.1.2 specification text for 7.3.14 Element (from Kernel) into stereotyped Components as relatable parsing containers. For comparison, the process is repeated for selected text snippets with Comments.

Pros of the Component vs Comment as a "parsing container":

  • Can package a dedicated diagram that features the relatable parsing container Component and its text, with its related elements (see next page)
    • TIP: drag that "focus" diagram from the browser onto the parsing container Component to make it the active hyperlink of the container !
    • A Comment can't even really package (let alone package a focus diagram) !
      • (Note that in MagicDraw UML and Comment can contain nested Comments, only)
  • Parsing container Components can be nested to form a parsed text tree (and traced using ComponentRealization)
  • Can parasitically "wrap" other elements to form logical views of them without "stealing ownership".
    • this is also the major advantage of Component over Artifact (or other Classifiers) as a relatable parsing container.

Cons of the Component vs Comment as "parsing container":

  • Can't be related via a Dependency easily to the Property at an Assocation end:
    • when a Property is available to target as an attribute in the attributes compartment this is no problem
    • a Comment handle can be correctly drawn to a Property at an Assocation end

Note the use of tagged values with enumeration literals to describe clearly the source and "coordinates" of the parsed text (in this case from the UML2.1.2 spec) in the parsing containers. In general, try to get as much text out of the parsing container's name, and into the model in this way.

Example: Components used as parsing containers reused via Display Related Elements

Here the elements related to a parsing container Component for the UML2.1.2 stereotype 7.3.14 Element (from Kernel) have been generated using the context menu:

Related Elements -> Display Related Elements

Then the remaining dependencies between other elements were generated using:

Related Elements -> Display Related Elements

(The diagram layout was then massaged a bit after using "Layout Organic Style".)

Note that:

  • The text parsed into Comments and related by handles only on the previous diagram have NOT been displayed !
    • This is why relatable Elements like Component are sometimes chosen as relatable parsing containers
  • The text parsed into Components on the previous diagram has been redisplayed via ComponentRealizations):
    • Con: although it is correctly generated, the parsed UML2.1.2 Attributes text for 'The Comments owned by this element. Subsets Element::ownedElement.' can't be related to a Property anywhere in the diagram.
  • One usually is not interested in all of the elements related to a parsing container, only those relevant to a given analysis context.

Using Components as relatable parsing containers offers these particular features (as well as the ability of its symbol to graphically contain elements that its text refers to). This is the key to understanding the whole UML Parsing Analysis recipe !

Example: Component used as "parsing container" that logically groups elements

The following shows an example of text from the specification of the UML2.1.2 7.3.45 Realization (from Dependencies) parsed into relatable parsing container Components, including an illustration of the notations and conventions referred to in the specification. This is a very powerful recipe, and it simply can't be done as well by only parsing technical text into Comments (which may only "relate" to elements through handles - which can't be traced - and can't graphically contain logical views):

HOWTO use sterotyped Artifacts as relatable parsing containers

Another candidate (besides a happily-misappropriated Component) for a relatable parsing container is the Artifact (a Classifier):

PROS:

  1. can be packaged
  2. can carry Dependency relationships to other "relatable" NamedElements
  3. little note icon suggests a documents (and thus is a good container for parsed text)
  4. well distinguished from software engineering elements like Class or Component
  5. can contain/own other elements (like other Comments or Artifacts)
    • can be nested to build nice logical trees of parsed text in your analysis model

CONS:

  1. One can't use HTML text style:
    • I recommend setting Header in Bold option off and word wrap on
  2. In MagicDraw UML one can't create an Artifact under a Component (so one can't easily insert an Artifact into a wrapper Component)
    1. create the Artifact under the nearest Model/Package IN THE BROWSER then
    2. move it IN THE BROWSER into the desired owrning wrapper Component
      (since you are using UML Parsing Analysis it almost certainly want to do that), then
    3. use create symbol to show the parsing Artifact in the diagram:
      • is a WORKAROUND (a bit tedious, however the results can be rewarding):
  3. In MagicDraw UML Artifact is only available on diagram menus of certain diagram types (and especially not in SysML diagrams)

Despite these subtleties, if you want powerful text analysis modelling results, this is one good strategy

TIP: consider also using a Component as a parsing container.

Example: Artifact used as container for parsed text with dependencies

In this example I have parsed some of the SysML1.0 spec text for conformance analysis vs. MD SysML.

The original SysML1.0 specification text to be analysed was:

'11.3.2.4 NoBuffer

Description
When the «nobuffer» stereotype is applied to object nodes, tokens arriving at the node are discarded if they are refused by outgoing edges, or refused by actions for object nodes that are input pins. This is typically used with fast or continuously flowing data values, to prevent buffer overrun, or to model transient values, such as electrical signals. For object nodes that are the target of continuous flows, «nobuffer» and «overwrite» have the same effect. The stereotype does not override UML token offering semantics; it just indicates what happens to the token when it is accepted. When the stereotype is not applied, the semantics are as in UML, specifically, tokens arriving at an object node that are refused by outgoing edges, or action for inpu pins, are held until they can leave the object node.

Constraints
[1] The «nobuffer» and «overwrite» stereotypes cannot be applied to the same element at the same time.'

Most of the text has been parsed into UML Comments and handles are used to relate the text to UML elements.

I have chosen to "upgrade" at least two of the parsed spec text sentences from Comment parsing container to Artifact parsing containers:

  • "For object nodes that are the target of continuous flows, «nobuffer» and «overwrite» have the same effect."

    • has been related by dependencies to some other elements, including some wrapper Components as navigation points.
  • "[1] The «nobuffer» and «overwrite» stereotypes cannot be applied to the same element at the same time."
    • has been turned into a parsed constraint container.

The result is shown in the image below.


TIP: see the next page to see how Display Related Elements is used to show which elements are related to the original subject.

Example: Artifacts used as parsing containers reused via Display Related Elements

Here the elements related to a parsing wrapper for the SysML1.0 stereotype 11.3.2.4 NoBuffer have been generated using the context menu:

Related Elements -> Display Related Elements

Note that:

  • the text parsed into Comments on the previous diagram have NOT been displayed
  • the text parsed into Artifacts on the previous diagram has been redisplayed via Dependencies

Although a bit more fuss than parsing text into Comments, parsing into Artifacts (or even into Components) brings with it this particular advantage.

Examples of the UML Parsing Analysis for software, engineering, and science


Please complete this tutorial trail here before visiting these resources !

Examples of the UML Parsing Analysis recipe using MagicDraw UML available online include:

Within this eSchool:

At other sites:

  • Literally hundreds of entertaining examples are available at the home of the UML Parsing Analysis recipe:

The technique has evolved over the years;
the recipe given here is the most up-to-date.