SysML/MBSE: Cameo/MagicDraw: MagicGrid® and the MagicGrid® Book of Knowledge: A pragmatic review of some selected aspects by Dr Darren of Webel IT Australia

Icon class
fas fa-book
DISCLAIMER: Content on this Webel IT Australia concerning MagicGrid® is not officially endorsed by Dassault or No Magic Inc.

With thanks to Aistė Aleksandravičienė and Aurelijus Morkevičius, the authors of the MagicGrid® Book or Knowledge. Any feedback and remarks here are offered constructively in the hope they help MagicDraw/Cameo users and the wider SysML and MBSE communities.

The MagicGrid® is a model-based systems engineering "dashboard" along with a set of principles for organising a typical MBSE project, influenced largely by ISO/IEC/IEEE 15288 and many similar SE standards. It is supported by the MagicGrid® Book of Knowledge PDF, which shall be denoted here MGBoK, with MGBok2 referring to the 2nd Edition.

No Magic Inc./Dassault retain copyright in small text extracts quoted from the MGBoK for educational purposes.

This Webel IT review of MagicGrid is currently organised as a single page with comments on selected sections of the MGBoK and some tool specific aspects. There are so far no images, just descriptions and MGBoK page references.

Dr Darren of Webel IT Australia says:

Webel IT does not directly use the MagicGrid, and does not directly recommend its use to customers or training clients (although Webel IT can help them use MagicGrid if they choose to indeed use it).

There are more flexible alternatives, including what in Webel terminology are described as SE Bridging Diagrams, an approach used in various forms by many of the early SysMLers under various different names. There are also some specific modelling strategies which, although they work, are not the recommended Webel Best Practices for SysML.

But it is definitely worth knowing about, and it might suit your purposes especially on completely fresh projects. The MGBoK is definitely worth reading, and you can learn a lot from the worked example problem, and you can always just use or adapt selected aspects of it as suits. Please be aware, however, that it is not intended as an "industrial strength" approach, it is not intended to cover as much as a big defence framework, and it is best suited to smaller projects.

The MagicGrid approach is a bit too static in many respects. It is described as a "framework", which is perhaps a bit overblown, I would describe it more as an MBSE "navigation dashboard", the use of which requires some quite specific and fiddly package organisation, and it relies for my taste way too much on ownership (as opposed to more forgiving logical modelling strategies). There are some more flexible ways of achieving the same thing, some of which could be used in parallel with MagicGrid as a kick starter.

But the basic identification of typical SE layers is robust, including nice examples of tool-friendly UseCase scenario drill-down strategies and of black box vs white box and one (only) approach to functional analysis breakdown.

I suggest also that it also does not make optimal use of some cross-navigability strategies, such as the SysML Refine relationship, there are some traceability weaknesses between Requirements, UseCases, and the final design solution via the functional analysis breakdown approach, although those matters can be addressed also with some extra migration work and/or in parallel.

Please be aware: As so often in many other tutorials and guides on SysML, some things in the MGBoK are described or at least implied to be "THE" way of doing it in SysML, whereas they are in fact specific recommendation for a specific MBSE recipe in a specific tool and the MagicGrid approach, not "facts" or constraints enforced by the SysMLv1 spec or underlying UML spec.

One of the hardest things for those new to SysML and SysML tools is that there are so many different ways of achieving the same thing using the underlying SysML language. This is a good thing! SysML is a set of building blocks (only), and over-specifying "THE" way of doing everything would not permit its flexible use for so many different tasks and for so many different domains. Besides, many modellers find a pet way that works well for them.

The MGBok VCCS example model does not use the non-normative SystemContext, System, External etc., even though available in the tool. They are definitely worth using instead of basic Blocks.

Consider also extending External as a custom block-based «actor», which you can also Trace to a matching UML-style Actor if desired, rather than just directly using a basic Block for SysML-friendly "actors" as used in the MGBoK sample. And Webel recommends just an explicit custom «actor» stereotype with an icon, rather than a basic Block with an image attached.

From MGBok2 p.46:
'We recommend using blocks rather than actors (stick man notation) to capture even human-nature entities (for example, users of the SoI) because the actor cannot be a part of the system context in the SysML model.'.

The 1st part, using (typically customised) blocks as "actors" is definitely a very good recommendation, one widely adopted by many SysML users.

The 2nd claim is not quite so; a UML-style Actor can't be a SysML PartProperty of a Block, but you can definitely have a UML-style Actor within a context Block as a basic property, just create an Association between the context Block and the UML-style Actor. It may not be the best way to go, and it may not have prominent tool support, but it is definitely allowed, and the SysML spec itself shows UML-style actors on an example system context IBD diagram.

From MGBok2 p.44:
'Each use case must belong to one or more system contexts defined in the System Context cell (see Chapter System Context).'

That is MagicGrid and MagicDraw/Cameo specific recommendation - one with advantages in the tool (as explained below) - but not a "must", and there is no SysML or UML spec constraint for it, and indeed the SysML spec HSUV sample problem shows UseCases belonging directly to the System (of Interest) not the SystemContext. BTW the 'belong' is likely referring to the subject of each UseCase, although, maybe the MGBoK authors meant 'belong' in the sense of via the System (being used as a part of every SystemContext variant).

The 'subject' of a UseCase is managed nicely in the tool. You can move a UseCase between various SysMLv1 Block symbol compartments in the tool and it will catch the change.

From MGBok2 p.45:
'Entities that perform one or more use cases of the system context should be represented as blocks in the use case diagram. Here you should remember that these blocks type part properties of the system context.'

[ASIDE: The blocks that actually 'perform one or more use cases of the system context' aren't shown that way in the MGBok2 sample, which shows the system context Vehicle In Use only - unless it actually means that the Vehicle In Use is the block performing 'one or more use cases of the system context'. The statement would seem to contradict the above quoted one about use cases in systems contexts. Maybe it could just be better expressed.]

[ASIDE: And there's no reason that a UseCase with the System directly as 'subject' can't handle multiple systems context descriptions at once; from the point of view of the System it can handle all scenarios thrown at it, and subsets of its Use Cases may address various system contexts via its scenarios.]

In any case, associating highest level UseCases with the SystemContext directly - rather than with the System as shown in the SysMLv1 spec HSUV sample problem - has advantages in the tool when using usage-based allocation swimlanes, since the SystemContext then has part properties corresponding to each block-based «actor» and the System, and the tool has nice support for automatically detecting them.

For a wider discussion visit also:

Please be aware of the following if NOT using the MagicGrid approach exactly:

From MGBok2 p.45:
'Each use case must have a name and primary scenario. Alternative scenarios are optional.'

Having a 'primary scenario' is a common and very sensible modelling convention/recipe, but it's not part of the SysML or UML specs, which don't mention this as part of the metamodels. A scenario is just a useful concept. Try searching the SysML and UML specs for 'scenario' and 'primary'!

That said, a UseCase without at least a primary scenario is not much use. There are various ways of relating such a primary scenario to/from a UseCase, but you won't find a 'scenario' field in the spec box in the SysML tool. The SysML spec HSUV sample just shows Refine relationships for drill-downs, such as Sequence Diagrams for Interactions. A SysML Activity with swimlanes works well with SysML Allocations, but it is not suitable for indicating timings. Pros and cons. Your best choice depends on the system, your domain, and the stakeholder audience also.

TIP: Sorry not showing images yet, just try in the tool:

Use edit compartments on the UseCase Provide Comfortable Temperature to show 'Owned Member', which here shows the same as 'Participates in Activity', and 'Subject'. Try also created a custom RefinedBy relationship and notice that is NOT in the MGBoK approach refined by, say an Activity (compare with SysML HSUV sample).

Try this. Create a UseCase somewhere. Then show the 'Participates in Activity' via edit compartments. Now create an Activity under (owned by) that UseCase, and note how the tool catches it via 'Participates in Activity'. Then move it out of (up from) the UseCase in the model browser so that it does NOT own the Activity, and note how it drops off the 'Participates in Activity' list. Note how this is completely independent of any actual content of the Activity!

ASIDE: Some older pre-SysML approaches use a UseCase itself on a 2nd Lifeline in a Sequence Diagram or as represented by a 2nd Swimlane of a refining (or otherwise drill-down) Activity. This is an older UML-influenced practice; it has some advantages for very fine-grained UseCase analysis, but it introduces an extra level of indirection, and Webel does not recommend the practice. For simpler cases, just use the System (of Interest) on the 2nd Lifeline or Swimlane, with custom «actor» Blocks and Externals on the 1st Lifeline or Swimlane (as usages if that's how you are working).

About verbose MagicGrid custom stereotypes naming
ConceptualComponent, ConceptualInterfaceBlock, ElectricalComponent, MechanicalComponent, OpticalComponent, OpticalInterfaceBlock, ...

Recommend be more concise the Webel way and let the metaclass or base stereotype do the taking. As keywords: «conceptual», «electrical», «mechanical», «optical» etc.

If 'Component' has a special meaning, use it orthogonally as a separate additional «component» stereotype, i.e., something else in the model be «optical» but not a «component».

And there is no need to have a family of specific ones for InterfaceBlock!. If it's applied to an InterfaceBlock, we know already that it is an InterfaceBlock. Done.

You can then query on ALL elements to extract engineering layers by stereotype like «electrical» to create a stakeholder view, and if you want, then restrict it to, say, InterfaceBlock. Likewise, you can query on the orthogonal «component» stereotype if 'Component' has special meaning.

BTW If one absolutely must use such verbose stereotype names (you don't) then at least use concise «keywords» defined through the corresponding Customizations to reduce clutter in Diagrams (and they read better).

From MGBoK2 p.53:
'The Activity Decomposition Map does not include call behavior actions. To ensure you have the entire decomposition of the use case steps, you need to have them captured as activities.'

More specifically, it catches an Activity (a Behavior) assigned to a CallBehaviorAction, but not the CallBehaviorAction itself. The UML.2.5.1 spec requires each CallBehaviorAction to have 1 'behavior', but in the tool one can definitely create a CallBehaviorAction initially without an assigned 'behavior', and none of the validation suites seem to report it as an error.

In any case, the recommendation to use Behavior Creation Mode helps prevent such untyped CallBehaviorActions. Under Webel Best Practice, modellers are always encouraged to always "Trust The Type" and where possible to use anonymous CallBehaviorActions with descriptive Behaviors assigned (typically Activities). Note that an Activity, which is a Behavior, is a Type.

The MGBoK2 illustration and walk-through of the handy Item Flow Manager feature (p.60+) is useful. Webel has a very minimal example with a single image overview of the setups and steps and how to use it here:
From MGBoK2 p.61:
'We also need to specify that the Ambient Temperature signal is obtained by the Reach Desired Temperature action'
Probably a typo, I think they mean received by. Dr Darren says:
It think if I had to write that document in Lithuanian I'd have far more typos!

From MGBok2 p.73: 'Let’s say you want to decompose the function captured in your model as theReach Desired Temperature activity. You will need to create a SysML activity diagram inside that activity.. Additionally, you need to change the location of the Reach Desired Temperature activity in your model by moving it to the 3 Functional Analysis package, a sub-package of the 2 White Box package (created in the previous step of this cell tutorial).' From the point of view of that tutorial it makes sense to do it as a single illustrative sense, but in practical modelling it is a good idea to simply identify all white-box Activities at once. Webel recommends additionally immediately applying a custom stereotype:

Learn SysML for MBSE with the Webel IT Australia Live Online web seminar or On-Site course!

Please email or phone Webel IT Australia on +61 405 029 008 to arrange On-Site, Off-Site, or Live Online remote web training seminars and workshops.
Relevant snippets (from other sources)
Visit also
Visit also (backlinks)
External links