The Toolbar

The Toolbar in Narrative Studio is a horizontal control panel located at the top of the canvas that provides quick access to a range of functionalities. Here’s a detailed explanation of each component and its purpose:

Narrative Palette

The main toolbar of Narrative Studio contains a set of essential buttons and controls used for creating and managing narratives. Here’s a breakdown of the primary buttons:

Select Tool (arrow icon): 

Used to select and move elements around the canvas. 

Capability (magenta icon):

Adds a capability construct to the canvas, which represents a high-level feature or capability in the narrative.

Narrative (narrative script icon): 

Used to define a narrative, representing a sequence of events and interactions tied to a particular user journey.

Moment (purple icon):

Used to add a moment, which captures a specific event or user goal within the narrative.

Interface (white icon): 

Creates an interface construct that represents a UI component or interaction element visible to the user.

Action (black icon): 

Represents system-level actions that occur in the background, such as processing data or performing calculations.

Actor (person profile icon): 

Used to define who (e.g., user, system) is involved in a particular moment or action within the narrative.

Spec (blue ‘S’ icon): 

Allows the addition of specifications, which are detailed requirements or behavior descriptions for system elements.

Comment (speech bubble icon): 

Enables adding comments to elements for collaboration and annotation.

Upload (paperclip Icon): 

Allows uploading files either from “My Device” or “From URL” as seen in the dropdown menu.

Overflow Menu (three dots icon): 

This button opens an overflow menu with advanced features to enrich your narratives.

Usage: Clicking on any of these buttons changes the cursor to “placement mode,” allowing the user to place the selected element directly onto the canvas by clicking on a specific location.

Alternatively, drag-and drop is also supported.

2. Filters Menu

The Filters Menu in Narrative Studio currently supports a label-based filtering system for narrative constructs. This feature allows users to manage the visibility of specific constructs on the canvas using a whitelist-based approach. To open the filters menu, click the Filters Icon, located in the Header Bar next to the Workspace Dropdown. Here’s how it works in detail:

Functionality Overview

• Filtering by Labels: Each narrative construct (e.g., Moments, Actions, Interfaces) can be assigned a specific label. Labels help categorize and differentiate constructs based on attributes such as functionality, priority, or team ownership.‍
• Filter by Whitelist: When using the filter menu, you can select labels to include in your whitelist. This means that only constructs with the selected labels remain fully visible, while all other constructs are grayed out.‍
• Save Custom Filters: You can select any combination of labels you like and save them as a custom filter.

Key Features of the Current Filtering System

Label Whitelisting:

• The filter works like a whitelist mechanism, meaning that once a label is selected in the filter menu, only constructs with this label will remain fully highlighted.
• Constructs that do not have the selected labels will appear grayed out on the canvas, allowing users to quickly distinguish and focus on relevant components.

Visibility Control:

• This graying out effect helps in visually separating different elements without completely hiding them, making it easier to reference the complete narrative while emphasizing specific parts.
• Users can toggle the visibility by adjusting the label selection dynamically in the filter menu, or by using custom filters.

Practical Use Cases

• Highlighting Specific Scenarios: For example, in a large narrative canvas, you might want to highlight all constructs related to a “Login Process”. By applying the filter to only show the “Login” label, all other non-login-related constructs will be grayed out, allowing you to focus specifically on the login flow.
• Team or Role-Based Filtering: Use labels like “UI Design,” “Backend Operations,” or “Business Logic” to quickly switch between different perspectives depending on the team’s focus.
• Complex Narratives: For complex narratives involving multiple systems and user roles, filtering by labels can help isolate workflows or actions relevant to a specific user journey, making collaboration and analysis more manageable.

UI Behavior

• When the Filter Icon is clicked, it opens a menu with a list of available labels.
• You can select one or multiple labels from the list.
• Constructs that do not match the selected labels will be dimmed (grayed out), while constructs that match will remain highlighted.
• Each label you choose will appear in the Selected Filters section that appears above the main toolbar.
• Remove individual labels by clicking the gray X on the label boxes or clear all with the Clear All button
• Save any combination of labels as a custom filter by clicking the Save Filter button. A text field will appear and prompt you to name your filter. Be aware that the custom filter will include all the labels that appear in gray boxes in the Selected Filters section.
• When you save a custom filter, it appears in the Saved Filters section of the Filters Menu, underneath the Labels section. Click on it there to apply the filter, and the Selected Filters section will appear above the main toolbar. Here you can edit your custom filter or clear it from the canvas using the gray X button on the right side of the section.

The current filtering setup is a powerful tool for navigating complex narrative structures, offering flexibility in focusing on specific elements without losing context.

Overflow Menu

In the Overflow Menu of Narrative Studio, you will see an Advanced Palette Section as well as an Additional Attachments Section.  The Advanced Palette contains technical constructs derived from Domain-Driven Design (DDD) and Event Storming. The additional attachments section contains three attachment types—Doc, Schema, and Query—which are primarily used to attach more detailed information to existing constructs such as Moments, Interfaces, and Actions. There is also a “Show resolved comments” toggle below this section.

We’ll start by exploring these attachments. 

Additional Attachments:

Doc: 

Doc attachments are used to add rich text documentation to your narrative. They can include formatted text, lists, or even images to provide additional information about a particular construct.

Schema: 

The Schema attachment allows you to define a GraphQL schema that describes the data structure associated with a specific system action or component. It is used to define the shape of the data that will be used or manipulated in that part of the system.

Query:

The Query attachment provides a GraphQL editor to define queries that retrieve or manipulate data. It is designed to show how data will be queried or fetched in response to user interactions.

For more information on these attachments, see Working With Attachments in Narrative Studio.

Key Points to Remember:

• Naming Creates Assets: When you place a Doc, Schema, or Query attachment on the canvas, you must name it to create an asset. This asset can then be reused in other parts of the narrative, reducing redundancy and maintaining consistency.‍
• Reusable Assets: Because these assets are named and referenced, you can apply the same Schema, Doc, or Query to multiple constructs, allowing for consistent documentation, schema definitions, and queries across the narrative.

This provides greater flexibility and allows for a more modular approach to building narratives, making it easier to scale and maintain the canvas as the project evolves.

Show Resolved Comments Toggle

Purpose: The Show Resolved Comments toggle provides control over the visibility of comments that have been marked as resolved, making it easier to focus on active feedback.

Usage:

• Switch On: When the toggle is on, all previously resolved comments become visible on the canvas, allowing users to revisit past discussions or decisions.
• Switch Off: When the toggle is off, resolved comments are hidden from view, reducing visual clutter and keeping attention on ongoing discussions.

Practical Benefits:

This toggle is particularly useful for retrospective reviews or when re-engaging with a project after a period of time. It helps ensure that resolved issues and the history of changes are easily accessible without cluttering the current view.

Typical Use Case:

If a team is conducting a post-mortem or reviewing the narrative after a development sprint, turning the toggle on allows everyone to see the decisions that were made and the issues that were resolved, providing context and transparency.

Advanced Palette (top part of overflow menu): Understanding the Concepts

The Advanced Palette in Narrative Studio is designed to model complex systems using concepts borrowed from Domain-Driven Design (DDD) and Event Storming. These methodologies focus on creating a clear understanding of both business processes and technical implementations by defining distinct elements that represent commands, data flow, events, business logic, and system boundaries.

Origins in DDD and Event Storming

Event Storming is a collaborative modeling technique used to understand the flow of events in a business process and identify potential areas of improvement or conflict. Domain-Driven Design (DDD) is a software design approach focused on creating a shared understanding of complex domains by aligning the language and structure of the software system with business goals. The advanced palette in Narrative Studio incorporates elements from these methodologies to provide a structured way of visualizing how commands, events, and data flow through the system, while also defining business processes and their interactions with technical components.

The palette is divided into three main categories:

Information Flow

This section focuses on how information is transmitted, transformed, and stored within the system.

Command (blue construct icon)

A command represents an intention to change the state of the system. A command is usually triggered by a user or another system. It initiates a flow of processes or changes, such as “Place Order” or “Cancel Booking.” In Event Storming, commands are the input actions that start a business process.

Data (light green construct icon)

Data represents structured information that is passed between components. Data elements are the raw pieces of information that form the basis of queries, commands, and events. Data elements are used in modeling to specify what type of information is being manipulated, stored, or transferred within the system.

Event (orange construct icon)

An event signifies that something has happened within the system. Events are often outcomes of commands and are used to communicate changes in state, such as “Order Placed” or “Payment Completed.” Events are a key concept in Event Storming, helping teams track what’s happening and identify the sequence of actions.

Business Process Model

These elements represent high-level business logic and constraints that govern the system.

Process (light purple construct icon)

A process is a sequence of activities that are executed to achieve a particular business goal. Processes define the steps and rules required to complete a business task, such as “User Registration” or “Order Fulfillment.” They often consist of multiple commands, events, and external interactions.

Constraints (yellow construct icon)

Constraints define the business rules or conditions that must be met for a process to proceed. They control the flow of a process by specifying what actions are allowed or required, such as “Must Be Over 18 to Register” or “Minimum Order Quantity.” Constraints are essential for capturing the business logic that shapes the behavior of the system.

External System (pink construct icon)

External Systems represent dependencies that lie outside the core domain, such as third-party APIs, external services, or other applications that the system interacts with. In Event Storming and DDD, modeling external systems helps define boundaries and integration points where the core system connects to external components.

Software Model

These elements are used to represent specific technical implementations and system architecture.

Resolver (dark green construct icon)

A Resolver is used to define how data queries are processed. It maps requests to the appropriate data sources or computations, serving as a handler for retrieving information. Resolvers are commonly used in CQRS (Command Query Responsibility Segregation) patterns to handle read requests.

Read Model (teal construct icon)

Read Models are projections of data, optimized for queries. They are separate from the main data store and are specifically designed to support fast data retrieval for interfaces. In DDD and Event Sourcing, Read Models enable teams to separate read and write concerns, ensuring that each is optimized for its specific purpose.

Projection (red construct icon)

A Projection represents a derived view that is created by processing one or more events. It updates a view based on changes in the system state, making it a powerful tool for real-time reporting and analytics. Projections help build dynamic views of the system without affecting the original data sources.

Gateway (hot pink construct icon)

A Gateway acts as a bridge between different systems, allowing data and commands to pass between them. It is used to connect different subsystems, microservices, or external APIs. In DDD, Gateways are used to define bounded contexts and the flow of information across different parts of the system.

Further Learning Resources

For more information, explore these resources: “Domain-Driven Design” by Eric Evans, “Implementing Domain-Driven Design” by Vaughn Vernon, and “Event Storming” by Alberto Brandolini. Additional references include the Event Storming Explained website and the Domain-Driven Design Community.

‍

‍