Skip to content
Back to top
View this page
Edit this page

# needsequence

Added in version 0.5.5.

`needsequence` adds a sequence-chart to your documentation.

Example 1

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

My sequence chart

Show the needs used in the above example

User: Mr. A USER_A
style: blue_border links outgoing: ACT_ISSUE links incoming: ACT_INFORM

Action: Creates issue ACT_ISSUE
style: yellow_border links outgoing: USER_B links incoming: USER_A

User: Ms. B USER_B
style: blue_border links outgoing: ACT_ANALYSIS, ACT_SOLUTION links incoming: ACT_ISSUE, ACT_ANALYSIS

Action: Analysis issue ACT_ANALYSIS
style: yellow_border links outgoing: USER_B links incoming: USER_B

Action: Provides solution ACT_SOLUTION
style: yellow_border links outgoing: USER_C links incoming: USER_B

User: Expert C USER_C
style: blue_border links outgoing: ACT_REVIEW, ACT_INFORM links incoming: ACT_SOLUTION, ACT_REVIEW

Action: Reviews solution ACT_REVIEW
style: yellow_border links outgoing: USER_C links incoming: USER_C

Action: Informs reporter ACT_INFORM
style: yellow_border links outgoing: USER_A links incoming: USER_C

User: Office Dog USER_D
style: blue_border triggers: ACT_BARKS triggered by: ACT_BARKS

Action: Barks for support ACT_BARKS
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.

Participant-Message flow

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

## 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

`: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 2

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

My filtered sequence chart