systemcomposer.interaction.Message

Message between lifelines in interaction

Since R2024a

Description

A Message object represents a communication between two lifelines of an interaction. On the sequence diagram representing the interaction, a message is shown as an arrow. Messages have labels that can describe the communication occurrence either formally or informally. A message corresponds to a connector connecting ports of two components in an architecture model.

A message label has a trigger, an optional guard, and an optional constraint in the form of trigger[guard]{constraint}, where trigger represents the identifying event for this message, guard represents an additional condition to determine whether the message occurs, and constraint is an expression that is expected to be true when this message occurs.

• In signal events, the trigger follows this format: direction(signal [+|-] value) which specifies a triggering edge with a direction and an expression. The direction can be:

  • rising — The edge expression is rising from strictly below zero to a value equal to or greater than zero.

  • falling — The edge expression is falling from strictly above zero.

  • crossing — The edge expression is either rising or falling past zero.

• In message events, the trigger follows this format: port which specifies the name of the input message port and represents the arrival of a message.

• A guard in square brackets on the message label is a MATLAB^® Boolean expression which is an additional condition to determine whether the message occurs. Evaluation of the guard only occurs once a valid trigger has been detected. During execution, the sequence diagram waits to proceed to the next message until the guard expression evaluates to true.

• A constraint in curly brackets on the message label is a MATLAB Boolean expression which specifies an expected value of inputs to the destination lifeline. During execution, the evaluation of the constraint determines whether the sequence diagram shows a pass or fail for that message.

Creation

Access Message objects via the RootFragment property of the corresponding systemcomposer.interaction.Interaction object. Iterate over the root fragment to inspect the systemcomposer.interaction.MessageEvent objects within the fragments. Access the Message property of the message event to inspect the corresponding Message object.

Properties

Type — Message type

"Signal" | "Message"

Message type, specified as one of these options:

• "Signal" for signal-based communication

• "Message" for Simulink^® message-based communication

Data Types: string

Condition — Message label

string

Message label, specified as a string.

Data Types: string

Start — Start of message

message event object

Start of message, specified as a systemcomposer.interaction.MessageEvent object.

End — End of message

message event object

End of message, specified as a systemcomposer.interaction.MessageEvent object.

RelatedElements — Connectors represented by message

array of connector objects | array of physical connector objects

Connectors represented by message, specified as an array of systemcomposer.arch.Connector or systemcomposer.arch.PhysicalConnector objects.

ExternalUID — Unique external identifier

character vector

Unique external identifier, specified as a character vector. The external ID is preserved over the lifespan of the element and through all operations that preserve the UUID.

Data Types: char

UUID — Universal unique identifier

character vector

Universal unique identifier, specified as a character vector.

Example: '91d5de2c-b14c-4c76-a5d6-5dd0037c52df'

Data Types: char

Object Functions

move	Move message within interaction
destroy	Remove model element

Examples

Inspect Sequence Diagrams with Programmatic Interfaces

You can use read-only API workflows to navigate sequence diagrams in System Composer™ and display information about each element.

Open Traffic Light Example

Open the traffic light example architecture model so that you can inspect the sequence diagrams visually and confirm the programmatic outputs.

model = systemcomposer.openModel("TLExample");

To view the sequence diagrams associated with the model, on the System Composer toolstrip, navigate to Modeling > Sequence Diagram.

Programmatically Navigate Sequence Diagram

Collect the sequence diagrams represented by interactions that contain specific interactions of elements in the model.

interactions = model.getInteractions;

For the first interaction, extract the name of the sequence diagram.

disp("The first sequence diagram is called " + interactions(1).Name + ".")

The first sequence diagram is called Inhibit.

For this sequence diagram, display each lifeline and the component the lifeline represents.

for i = 1:length(interactions(1).Lifelines)
    disp("The " + interactions(1).Lifelines(i).Name + ...
    " lifeline represents the " + ...
    interactions(1).Lifelines(i).RelatedElements.Name + ...
    " component.")
end

The source lifeline represents the source component.
The poller lifeline represents the poller component.
The switch lifeline represents the switch component.
The controller lifeline represents the controller component.
The lampController lifeline represents the lampController component.

Display the contents of one message in the root fragment.

disp("The sequence diagram message starting at the " + ...
    interactions(1).RootFragment.Operands.Fragments(1).Name + ...
    " message end is of type " + ...
    string(interactions(1).RootFragment.Operands.Fragments(1).Message.Type) + ...
    " and the message label is " + ...
    interactions(1).RootFragment.Operands.Fragments(1).Message.Condition + ".")

The sequence diagram message starting at the switchout message end is of type Signal and the message label is rising(sw-1){sw==1}.

Use Iterator Utility to Step Through Sequence Diagram

Step through the Inhibit sequence diagram using the Iterator utility.

interaction = model.getInteraction('Inhibit');
interaction.open

Display the annotation from the interaction.

disp(interaction.Annotations.Content)

When inhibit is true, it means pedestrian crossing is not controlled by a walk signal on this intersection.

Use an iterator to navigate through all elements of a sequence diagram before extracting their properties.

iterator = systemcomposer.interaction.Iterator(interaction.RootFragment);
next = iterator.next;
while ~isempty(next)
    disp(class(next))
    next = iterator.next;
end

systemcomposer.interaction.RootFragment
systemcomposer.interaction.Operand
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.AltFragment
systemcomposer.interaction.Operand
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.Operand
systemcomposer.interaction.MessageEvent
systemcomposer.interaction.MessageEvent

More About

Definitions

Term	Definition	Application	More Information
sequence diagram	A sequence diagram represents the expected interaction between structural elements of an architecture as a sequence of message exchanges.	Use sequence diagrams to describe how the parts of a system interact.	Describe System Behavior Using Sequence Diagrams
lifeline	A lifeline is represented by a head and a timeline that proceeds down a vertical dotted line.	The head of a lifeline represents a component in an architecture model.	Add Lifelines and Messages
message	A message sends information from one lifeline to another. Messages are specified with a message label.	A message label has a trigger, an optional guard, and an optional constraint where a trigger represents the identifying event for this message, a guard represents an additional condition to determine whether the message occurs, and a constraint is an expression that is expected to be true when this message occurs.	Create Messages in Sequence Diagram
gate	A gate represents the root architecture of the corresponding architecture model.	Connect messages to gates to represent architecture ports.	Create Sequence Diagram Gates
annotation	An annotation describes the elements of a sequence diagram.	Use annotations to provide detailed explanations of elements or workflows captured by sequence diagrams.	Use Annotations to Describe Elements of Sequence Diagram
fragment	A fragment indicates how a group of messages execute or interact.	A fragment is used to model complex sequences, such as alternatives, in a sequence diagram.	Author Sequence Diagram Fragments
operand	An operand is a region in a fragment. Fragments have one or more operands depending on the kind of fragment. Operands can contain messages and additional fragments.	Each operand can include a constraint to specify whether the messages inside the operand execute. You can express the precondition of an operand as a MATLAB Boolean expression using the input signal of a lifeline.	Add Fragments and Operands

Version History

Introduced in R2024a