Webel Best Practice

This it the tag/keyword search page for Webel Best Practice. For a more collated list of best practice tips for Unified Modeling Language (UML^®) and Systems Modeling Language (SysML^®) with explanations please visit also Webel's Best Practice policy notes for UML and SysML and the MagicDraw/Cameo tools.

Webel: SysMLv1.x: TIP: The name and documentation of a ValueType can indicate and specify more than just the unit and quantity kind. Example: A ClockFrequency may document how the frequency is measured. Example: WeightOnEarth.

Webel electronics modelling recipe for SysML: Diagrams can be made less verbose by using stereotype icon shape display mode, by not showing names and types on obvious Ports, by hiding context-specific values, and by omitting {net} tagged values.

Webel: SysML: Electronics modelling: TIP: Use a custom Connector stereotype '<>' with the keyword '<>' to carry a 'net' property. (Use of punctuation in Stereotype names is not usually recommended and the keyword is not usually displayed.)

SysML: Naming: You may include Block, ValueType, and Signal names in the names of Behaviors (such as Activities) as long as this does not undermine the principles of functional analysis and allocation.

UML/SysML: In Internal Block Diagrams: If you have a Port with a name that indicates a unique role AND and if there is an ItemFlow on a Connector that implies or suggests the Type of the Port, consider hiding the Type on the Port symbol.

SysML+SysPhS: Flows: If you intend to use a Classifier to type the itemProperty of an ItemFlow on a Connector for a physical interaction you MUST use a Block (not a ValueType or Signal) so your can extend ConservedQuantityKind.

SysML: Flows: If you intend to use a Classifier to type the itemProperty of an ItemFlow on a Connector use a ValueType or Block rather than a Signal, otherwise you'll get probably-unwanted signal receptions on the owning context Block.

SysML: Whether you use a Block, ValueType, or Signal to represent something that flows (and can be applied to an ItemFlow) depends on what you want to achieve. If you want to indicate something structured with value properties with Units use a Block.

Progressively "exporting" internal Ports of usages of Blocks to the boundary of their using Block may seem like a bit of extra work, but it means you can progressively develop with clean black box views without the Connectors crossing Block boundaries.

In the Webel terminology for a basic control loop there is an 'aim' value (controlled via an actuator) and a 'got' value (a value read from a sensor). The 'got' value is NOT necessarily exactly the same as the actual physical value.

SysML-1.6/1.7: You can introduce a custom (user-defined) stereotype keyword «item» to indicate Properties that are to be used as "packets" for ItemFlows on Connectors. (SysMLv2 will have a formal way of treating such items/packets.)

Webel: SysML: DO NOT sacrifice modelling naming conventions for the mere sake of carrying organisation-specific names! Instead use tagged values of custom stereotypes as metadata to carry alternative names in parallel with systematic model element names.

SysML/SysPhS-1.1: Anonymous Property or Action names may not be an option if: You are exporting to Modelica or Simulink; You absolutely need names for generated query reports (such as generated Interface Control Documents).

Webel: In some SysML trails ValueType names with Unit indicator suffixes have been used for dimensional analysis and illustrative purposes. This practice is NOT otherwise recommended here. Instead just use consistent custom ValueTypes across your system!

SysML: When using Property::defaultValue and Property::redefinedValue to carry a "shadow hierarchy" of redefinitions across an entire system hierarchy, considering using a user-defined keyword such as «configuration» or «scenario» on each redefining Block

UML/SysML: Navigation: Try to offer a way out of a diagram (usually up a hierarchy, but possibly across) using a navigable symbol (linked to a diagram) and/or a diagram symbol. Avoid "cul-de-sacs"!

Block naming: If you find you've got similar blocks named 'Thing' and 'Thing2' then 'Thing' is probably better renamed 'Thing1'

The use of an additional «port» keyword on a Port is usually redundant and causes clutter. The use of an additional «port» keyword on a basic Property is an obsolete trick. Please don't imitate it even if you see it in some specification sample diagrams!

Webel Best Practice: SysML/SysPhS: DO NOT use overlapping Connector lines from/to one Port (can be misunderstood as "summed" flow and/or physical node/fork/junction).

UML/SysML: A Boolean "state flag" attribute corresponding to a State can be useful for indicating states in some diagram types (but must be synchronised with Transitions to States carefully).

UML/SysML: During modelling it can really help to create little instance (object) diagrams as you go! This can also help communicate with non-SysML stakeholders.

UML/SysML: If you have a Boolean "state flag" attribute corresponding to a State you MUST set it on an 'entry' of the State, not on the 'effect' of a Transition into the State (otherwise with multiple incoming Transitions it could be WET and breaks SSoT).

Webel Twin Pattern: Convention: [MIGHT CHANGE]: A '*' prefix in a Property name of a «digital» @Block in a DigitalTwin model indicates a mapped block property, which must be typed by a non-digital «mappable» Block, and must have the «@» keyword applied.

WARNING: In natural language casual conversation one often hears people speaking of a digital twin "replicating" or "twinning" a physical entity. If you do it that way literally, you will NOT have anything to manage the control system loop!

Webel Twin Pattern: A PotentialPhysicalAsset is «digital», not «physical». It is used to acquire (an existing) or create (build, manifest, make) an «physical» ActualPhysicalAsset, which is a special case of «physical» PhysicalEntity.

Webel Twin Pattern: A DigitalTwin manages a control loop including a PhysicalEntity and a DigitalEntity (a.k.a. @Entity) that «replicates» it. It typically includes at least one Sensor and at least one Actuator.

Webel Twin Pattern: It is a DigitalEntity (a.k.a. @Entity) - not the DigitalTwin that owns it - that directly «replicates» geometrical, spatial, and material aspects (only) of a single PhysicalEntity.

Webel Twin Pattern: A DigitalTwin must model processes and the entities they act on separately.

Webel Twin Pattern: A «digital» DigitalEntity (a.k.a. @Entity) encapsulates strictly geometrical, spatial, and material aspects of a «physical» PhysicalEntity only. BY DEFINITION of this pattern it DOES NOT encapsulate processes!

Webel: Convention: [MIGHT CHANGE]: An '@' prefix in a DigitalTwin model indicates a «digital» Block that maps a non-digital «mappable» Block.

SysML: Some users employed the ~ tilde prefix for a conjugated Port type long before it was introduced for ~InterfaceBlock and you MAY use it to name a regular Block that is not an ~InterfaceBlock

Webel: SysML-1.7/SysMLv2: WISHLIST: Constraint: A BindingConnector used for pure proxying MUST NOT be typed by an AssociationBlock by definition, because the associated information can be mis-appropriated to undermine the proxy equality!

You can use custom stereotypes keywords «i» and «o» to indicate value properties that are intended to be used as (i)nputs and (o)utput when bound to constraint parameters for SysML Parametrics

Computed category membership test values are sometimes adequate and can prevent Class/Block explosion. However, a dedicated Class/Block encapsulating a clear domain concept offers a clear documentation point and can carry other characterising features.

In professional applications of the Webel Parsing Analysis recipe for SysML, a robust reusable profile for «part»/«assembly»/«leaf» components is used, along with stereotypes keywords like «assembles» for indicating physical composition hierarchies.

In the Webel recipe for UML/SysML, the pattern of progressive redefinition of end Properties of Associations between progressively more specialised pairs of Blocks at the same level of abstraction is informally called a "redefinition ladder"

Do export your UML/SysML presentation diagrams (only, not every diagram) regularly as static images; it will help you develop diagrams that are better balanced and communicate well with stakeholders.

Webel Parsing Analysis diagrams do their job once - namely traceable elicitation of model elements - and are then only kept as a reference! The elicited model elements are then used elsewhere in the final model.

A "staging" BDD for defining the flows, ports, and item properties on blocks to be used in an IBD does not have to be a "work of art" if it is not intended as a final presentation diagram.

In Package Diagrams and Block Definition Diagrams use the owner indicator display option for Classifier symbol headers to indicate the owner (except where a containment operator suffices). The mode 'Below Element Name' is preferred.

Suffix the "focus" BDD for a Block with .bdd so that it won't clash with a corresponding IBD on diagram export.

Just because you can't see a Feature or some other aspect of a UML or SysML Element in a tool on a symbol does NOT mean it does not exist in the underlying model (repository)!

Rule #1: A UML or SysML Element in a tool is NOT just an Element symbol in a diagram! A Note is not an Element (compare with a Comment).

MagicDraw/Cameo: Keep most elements out of the top-level of a project (i.e. not directly under the project Root). Have one top-level index/content/package diagram.

Webel: Recommend maintain a basic black-and-white style file for starting new projects. Webel course attendees have access to a basic Webel.stl file (or clone and tune the 'OMG SysML style').

Webel: First recommended style and project option steps for every UML and SysML project in MagicDraw/Cameo.

Webel: SysMLv1.x: AVOID (where possible) SysML Unit names that are the same as unit symbols. Unit names SHOULD start with a lower case Latin alpha letter. Custom Unit names should be a single lower case word or lowerCamelCase.

If instances of Blocks “communicate” with each other use an Association between them.

Prefer not rename Properties when redefining unless indicating a clear change in role.

Always consider including an abstract (sometimes intermediate) base Block in your domain modelling Generalization hierarchy.

If using "French style" post-adjective naming in English use a trailing underscore after the noun and before the adjective or qualifier: Vin_rouge, Cable_digital. Can be combined with TLA acronyms: Player_DVD.

A common interpretation of composite Aggregation of a part property in SysML domain modelling is that if the owner Block is "destroyed" so is the child part property. Webel adopts these semantics always.

If an abstract Block or Class in a domain model has Associations to Blocks or Classes that are not also abstract, it's often a hint that you have not identified a correct abstraction layer.

SysML Blocks have lots of possible features and compartments, lots of capabilities, and are very powerful! But you don't have to use every aspect of a Block (or show every aspect in every diagram) at once on every project.

In SysML, unless you MUST use a DataType or PrimitiveType from an existing ModelLibrary or Profile, you SHOULD probably be using a ValueType, Enumeration ValueType, or SysML PrimitiveValueType instead so that it integrates with the value system of SysML.

Webel use editorial Sterotypes prefixed with ! and ? in and in CAPS in keywords such as: «!». «?», «!ERROR», «!ISSUE», «!CAUTION», «!WARNING», «!CAVEAT», etc.

Associative BDDs are best used as staging diagrams for you the modeller (and SysML-fluent readers). IBDs usually make better presentations diagrams for a wider audience of general engineers and other stakeholders.

The name of a «testCase» Behavior may be verbose and may use natural language, but should always start with a Capital letter.

When satisfying a Requirement with a Block, you need to ask whether the Block (all instances) satisfies the Requirement or whether only a particular usage of the Block (such as a part property) Satisfies the Requirement!

Webel: If you must name your Ports or Pins, name them simply 'i', 'o', or 'io' to indicate direction UNLESS you have to indicate a special role like 'iRole', 'oAuxiliary'. DO NOT use Port names like 'input', 'output', etc.

"Trust the Port or Pin Type!" - Often the name of the Type of an anonymous Port or Pin is completely sufficient to indicate its role, unless a clear indication of its direction or unique role is required.

UML/SysML: In Internal Block Diagrams: Consider hiding the name of a named Port or Property in a Diagram if its Type is sufficient to indicate its role.

In most Webel examples, the default is chosen to be 'out' if there is a single FlowProperty, so a Port with the type applied will act as a source. If an InterfaceBlock is used, then a Port typed by the conjugating ~InterfaceBlock will act as a sink.

Avoid mixing flow properties on the Type of a Port with directed features (operations and values); One distinguishes between "ports with flows" and "contract ports".

In general, the SysML DirectedFeature approach is more powerful and the notation is cleaner than UML provided/required Interfaces. Prefer SysML DirectedFeatures unless you have a really good reason to use Interfaces!

AVOID "mixed" functional (behavioral) allocation levels! DO NOT Allocate from Usage level (Action) to Definition level (Block) or from Definition level (Activity) to usage level (part Property) - even if formally permitted in SysML.

Use of 'this-that' with a hyphen in Connector names is admissable (where 'this' and 'that' indicate Connector ends or their types)

DO NOT use Connector names that are identical to the names of the Associations that type them!

DO NOT use Property names that are identical to the names of the Classifier (Class, DataType, Block, ValueType) that type them!

SysMLv1.x: ValueType naming: The Webel convention is 'UpperCamelCase' (a.k.a. PascalCase).

Webel: SysMLv1.x: AVOID (where possible) ValueType names that are the same as the name of units or unit symbols

Webel recommends (usually) display the header of a Package, Model, ModelLibrary, or Profile in the 'tab' (rather than 'top')

Prefer the Name Display Mode 'both' on CallBehaviorAction symbols (rather than 'Show Action Name', 'Show Behavior Name', or 'Show Both or Behavior Name')

Avoid punctuation in Property names (except when used to "quote text"). You can usually avoid underscores in Property names (even if they are used in the Type name) if you can "Trust the Type"!

MagicDraw/Cameo: Consider showing the constraint parameter name and type label inside the small rectangular parameter symbol on SysML Parametric Diagrams!

Webel: "Trust the Metaclass or Stereotype" of an Element to indicate what type of element it is (you don't have to repeat it in the name)

Webel: SysML: You don't need to call every ConstraintBlock a 'SomethingEquation'

Webel: DO NOT name the Type (Block or InterfaceBlock) of a Port with a flow the same as the name of the 'Stuff' that flows through it; use the Webel 'F_Stuff' convention!

DO NOT use spaces in Property names or Class/Block names! If you want to communicate familiar names of elements within an organisation use a custom stereotype and tagged values (such as 'aka')!

FlowProperty naming. Use anonymous or just 'i' for in, 'o' for out, and 'io' for inout. "Trust the Type". For conjugation ~InterfaceBlock use 'o' for in, 'i' for out, and 'oi' for inout.

MagicDraw/Cameo: Consider showing the Port name and type label inside the Port symbol! CAVEAT: This loses the direction indicators on Ports typed by Blocks with flow properties (but is fine if ItemFlows show the direction, or for "contract ports").

Prefer not show Port symbols on the boundary of Blocks in BDDs, just list them in compartments. One can't connect them in a BDD anyway.

DO NOT name ports with first letter capital (like 'Port'), DO NOT name ports 'port' (except for educational illustration), and DO NOT use port names that do not indicate a role.

MagicDraw/Cameo tool support for Association composition "trees" is not good, and they end up being fiddly to maintain (and they can also cause issues for InformationFlows). Avoid them!

As an alternative to composition Association "trees" consider instead using symbol resize to visually "bracket" composed items (can however be a bit fiddly).

Webel suggests using a verbose 'name' for leaf (child) Requirements but NO 'text' to prevent Single Source of Truth issues and for improved callout vs relationships (but this might not always work when syncing with external requirements management tools)

"Trust the Type!" - Often the name of the Type of an anonymous Property or instance-level element is completely sufficient to indicate its role - unless multiple Properties of the same Type have different roles!

If you are using model queries (such as table and report extraction) you may not always be able to use anonymous Property names and anonymous instance level element names

In SysML diagrams, showing the context name and type in the diagram frame can lead to clutter and is not always clear to non-SysML stakeholders (although that is the style used in the specification samples)

The Webel modelling style, naming conventions, and Best Practices for SysML are more consistent than most SysML specification diagrams. When following Webel courses please DO NOT use the spec sample diagrams as visual references!

Webel's Best Practice policy notes for UML and SysML and the MagicDraw/Cameo tools

Keywords

The Webel Best Practice items for SysML (and UML) (tuned for the MagicDraw/Cameo tools) represent the world's most comprehensive guide to robust, fluent, enjoyable, consistent modelling for Model-Based Systems Engineering (MBSE), developed over two decades, and proven to work on extremely demanding real-world projects!

Subscribe to Webel Best Practice