Components

Components

Components represent objects, elements, or entities within the system that interact with each other. They are shown as rectangles with a lifeline extending downward. If you do not declare an object to be of a particular type of component, it will be of the default participant class.

Components have lifelines that show the sequence of messages exchanged between them. They can initiate messages, receive messages, and have their own internal interactions.

Components are notated by component type: followed by the name of the new component. Different components can have different functions in the sequence. An actor component will have specific functionality and is necessary for executions. Other types of components, however are for organizational and visual disctinction only.

title: Components Sequence

participant: A participant
actor: An actor
database: A database
collection: A collection

Participant

Participants are the default class for an messagable element within the sequence. Appropriate when no other type is suitable, or if specification is not necessary. If a message is made without a components being already declared, then it will be a participant. They are represented with a diamond icon.

For example, if I have an actor: John and have him send a message to someone else John -> Someone else: A message, then Someone else will be created as a participant automatically, as they were not explicitly declared.

title: Participant
actor: John

John -> Someone else: A message

Participants are best used for non actor elements that do not need or fit a more specific type. They have no special use case and serve well for any non actor element.

Actors

Actors are special components that have extra functionality within sequencestack. Actors have a greater ability to interact with a system and usually represent users, teams, or central groups that have strong input in the outcome of a sequence. They are usually represented by a blue outline of a person over their box with a lifeline extending down.

Actors are often associated with use cases and represent the roles that initiate interactions with the system. They are notated by actor: followed by the name of the actor.

Actors can be used:

• To Execute on a sequence

  Only actors will appear in executions. Non actor components will be ignored in the creation of an execution. Declaring a component as an actor ensures that they will have actions available to them in the execution.

• To Include a shared collaborator

  Shared users can appear as a part of a sequence. They can only be included when they are declared as an actor.
  actor: MyEmail@gmail.com will work while participant: MyEmail@gmail.com will not.

• To Include a team role

  Similar to shared users/collaborators. A role can be included in a sequence when declared as an actor.
  actor: Role Name.

Declaring a component as an actor gives it the ability to be used in these contexts. Other components do not have this functionality. Because of this, the actor designation is best reserved for components that require this functionality, while components which do not require any of these features are typically better served by another designation.

Database

Databases represent automatic systems that interact with a sequence. Unlike other components, they are usually used for automatic outcomes that do not require additional input to occur. They are useful in this way to reveal the hidden steps of a sequence that are important to be aware of, but do not necessarily need to be manually activated or acted upon.

Databases are most useful for these automatic actions where a database or software is the origin of the steps. They are notated with database: .

Collection

Collections represent storages in a sequence. Places where information must be sent and retrieved or otherwise saved for later or immediate use are best represented by collections. They are wide ranging and can be used for many different kinds of storages, but are more descriptive than a default participant, and are useful to demonstrate their relationship with the sequence being related to storage and information.

They are notated by collection: .

Adding collaborators

In addition to normal types of components, you may also reference an existing user. In order to reference this user, you must share the sequence with that user using the sharing menu, detailed in the "Sharing" section. Once the sequence is shared with that user, you can reference that user in the sequence and use them as an actor.

In order to add the user to the sequence, they can be referenced using this syntax. actor: ExampleEmail@email.com. This way you can add the user, and use them as an actor. This should be the same email that you used to invite that user to your sequence.

Using the @ key when declaring an actor actor: @ will bring up an autocomplete menu for collaborators. This list will only include any valid collaborators. Any user you have shared the sequence with through teams or individual invites will appear in this list. Using the up and down keys or the mouse and scroll wheel, you can select the user you want to add as an actor in the sequence. Click or press enter to add them. Once added, they will take the place of the @ symbol. actor: selecteduser@gmail.com.

If you have shared the sequence with many users and only want a specific one, after typing actor: @, you can continue typing the email to narrow down the options. Typing actor: @selected will narrow the search to make it easier to find selecteduser@gmail.com.

title: Collaborators

actor: Email@gmail.com

Email@gmail.com -> Someone else

Adding roles

Similar to direct user references, roles can also be used inside a sequence.

Roles are created in teams and can be assigned to a user in that team. When sharing a sequence with a team, not only will the users in that team be available in the sequence for direct reference by being added as collaborators, but any roles in that team will also be usable as well.

Adding a role is similar to adding a collaborator. To add a role, an actor: must be declared, with the role name following it. actor: My Role. Adding a role does not require the email of any user assigned to that role, instead the name must be exactly matched with the name of the role in the team.

Roles operate very similarly to collaborators but have 3 main benefits.

• Up to date information A role can be updated with the current user. If a role in a team is assigned to a specific user at one point in time, but will be changed later, it is beneficial to use the generic role in the sequence rather than the currently assigned user. If the user is expected to change, it makes more sense to use a role than needing to change the user in the sequence.

• Role name - On it's own, the role name itself provides added context to the sequence, by informing the viewer of what the duties or intended role of a user is. Including Product operations lead - John Doe is much more helpful to a viewer than simply placing John Doe in the sequence without context of his role.

• Description - When created in a team, a role can have a description set to provide more info about it. When a role is added to a sequence, it can be clicked to be opened, which will display the description of the role, allowing viewers to access more information about the role if needed.

title: Roles

actor: Role Name

Role Name -> Someone else