needsequence

New in version 0.5.5.

needsequence adds a sequence-chart to your documentation.

Example

.. needsequence:: My sequence chart
   :start: USER_A, USER_D
   :link_types: links, triggers

Result

@startuml

' Nodes definition 

participant "Mr. A" as USER_A
participant "Ms. B" as USER_B
participant "Expert C" as USER_C
participant "Office Dog" as USER_D

' Connection definition 

USER_A -> USER_B: Creates issue
USER_B -> USER_B: Analysis issue
USER_B -> USER_C: Provides solution
USER_C -> USER_C: Reviews solution
USER_C -> USER_A: Informs reporter
USER_D -> USER_D: Barks for support

@enduml

My sequence chart

Show used needs for above example…

User: Mr. A USER_A ../_images/arrow-right-circle.svg
style: blue_border
links outgoing: ACT_ISSUE
links incoming: ACT_INFORM
Action: Creates issue ACT_ISSUE ../_images/arrow-right-circle.svg
style: yellow_border
links outgoing: USER_B
links incoming: USER_A
User: Ms. B USER_B ../_images/arrow-right-circle.svg
style: blue_border
links outgoing: ACT_ANALYSIS, ACT_SOLUTION
links incoming: ACT_ISSUE, ACT_ANALYSIS
Action: Analysis issue ACT_ANALYSIS ../_images/arrow-right-circle.svg
style: yellow_border
links outgoing: USER_B
links incoming: USER_B
Action: Provides solution ACT_SOLUTION ../_images/arrow-right-circle.svg
style: yellow_border
links outgoing: USER_C
links incoming: USER_B
User: Expert C USER_C ../_images/arrow-right-circle.svg
style: blue_border
links outgoing: ACT_REVIEW, ACT_INFORM
links incoming: ACT_SOLUTION, ACT_REVIEW
Action: Reviews solution ACT_REVIEW ../_images/arrow-right-circle.svg
style: yellow_border
links outgoing: USER_C
links incoming: USER_C
Action: Informs reporter ACT_INFORM ../_images/arrow-right-circle.svg
style: yellow_border
links outgoing: USER_A
links incoming: USER_C
User: Office Dog USER_D ../_images/arrow-right-circle.svg
style: blue_border
triggers: ACT_BARKS
triggered by: ACT_BARKS
Action: Barks for support ACT_BARKS ../_images/arrow-right-circle.svg
style: yellow_border
triggers: USER_D
triggered by: USER_D

Sequence diagrams supports special needs-combinations, in which one type represents some kind of a participant and another, linked need is representing the message.
Examples for this relationship are: Sender-Receiver communication , Role-Activity processes or Tool-Artifact relations.

needsequence needs at least one start-need, defined by its id in the :start: option.

The first need represents the participant. The next, linked need(s) is representing the message. Needs linked from a message are interpreted as participant again and so on.
So the linking must be really clean to get nice, meaningful sequence diagrams out of it.

The used need-type is unimportant.

@startuml

skinparam defaultTextAlignment center

rectangle "Interpreted as\n**PARTICIPANT 1**\n(start)" as p1 #ccc
rectangle "Interpreted as\n**PARTICIPANT 2**" as p2 #ccc
rectangle "Interpreted as\n**PARTICIPANT 3**" as p3 #ccc


rectangle "Interpreted as\n**MESSAGE 1**" as m1 #ffcc00
rectangle "Interpreted as\n**MESSAGE1 **" as m2 #ffcc00

p1 -> m1 : link
m1 -> p2 : link
p2 -> m2 : link
m2 -> p3 : link
@enduml

Participant-Message flow

The above, linked example gets interpreted for needsequence as follows:

@startuml

participant "Participant 1\n (start)" as p1
participant "Participant 2" as p2
participant "Participant 3" as p3

p1 -> p2: Message 1
p2 -> p3: Message 2



@enduml

Options

start

The :start: option takes a comma separated list of need ids and uses it as the starting point for further examination of sequence data.

First need of :start: gets painted first. The need includes all related messages and other participants.

After the first need, we take the next need id from the :start: option. And if it was not already part of the prior examination, we handle it the same way, otherwise, we ignore it.

:link_types: option takes a comma separated list of link type names followed during examination.
Because of that, we ignore other link_types and all participants or messages accessible by the ignored link_types.

Default: links

filter

You can use the :filter: option to filter participants. We ignore all participants that does not fulfill the filter_string. See Filter string for more information.

Default: None (no active filtering)

You can use this function to filter out a specific participant. As an example, we use the same needsequence from the beginning, but without USER_C / Expert:

Example

.. needsequence:: My filtered sequence chart
   :start: USER_A, USER_D
   :link_types: links, triggers
   :filter: "Expert" not in title

Result

@startuml

' Nodes definition 

participant "Mr. A" as USER_A
participant "Ms. B" as USER_B
participant "Office Dog" as USER_D

' Connection definition 

USER_A -> USER_B: Creates issue
USER_B -> USER_B: Analysis issue
USER_D -> USER_D: Barks for support

@enduml

My filtered sequence chart