needsequence

New in version 0.5.5.

needsequence adds a sequence-chart to your documentation:

.. needsequence:: My sequence chart
   :start: USER_A, USER_D
   :link_types: links, triggers
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 an 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. This need is the first 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 itself 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

start takes a comma separated list of need ids, which shall be used as starting point for further examination for sequence data.

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

After that the next need id is taken from start. And if it was not already part of the prior examination, it is handled the same way otherwise it is ignored.

filter

The filter string is used to filter participants. All participants must fulfil the filter_string, otherwise they get ignored. See Filter string for more information.

Default: None (no active filtering)

This function can be used to filter out for instance a specific participant. As example, same needsequence from the beginning, but without USER_C / Expert:

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