Scenarios in Ardoq lets you select a subset of your components from across your workspaces, where you can make changes in isolation from the mainline. You can then compare, share, and present the suggested changes to your team and other stakeholders to get buy-in and alignment, and to find the best way forward.
NB: The Scenarios feature is a paid add-on. Please contact your Customer Success Manager if you want access to this feature.
Table of Contents:
Before Diving In
To create a scenario, you must be an admin or writer user and have the “Create Scenarios” privilege enabled.
To edit a scenario, you must be an admin or writer user and have been assigned a permission on the relevant scenario. Learn more about scenario permissions below.
How To Create A Scenario
In the mainline, navigate to 'Home' and open the workspace that contains the components you want to make changes.
Select the components you wish to add to your scenario. You can select single components by holding down the Command (or Cmd) ⌘ key on Mac or the Ctrl key on Windows. To bulk select, use the Shift key.
Next, click on the 'branch' icon at the top of the workspace navigator and choose:
Create scenario from view: to create a brand new scenario with the components displayed in the Block Diagram view. Please note that the components shown in the view vary according to the selected component in the workspace navigator.
Create scenario from selection: to create a brand new scenario with the components you have selected.
Add selection to scenario: to add the selected components to an existing scenario.
All references between the components will be included. 💪
Give the scenario a name, and continue to your scenario to start making changes. If you wish to add components from a different workspace, repeat the process and choose 'Add selection to scenario' in step 3 instead.
And that's it! All changes you do to components, references, and tags in your scenario will not affect the mainline.
Navigating The Scenarios Interface
In many ways, the Scenario mode is similar to the mainline mode. A few differences and key functionality are explained below.
Scenarios Navigator
The Scenarios Navigator only shows the components that have been added to your scenario so that you have full control over what you are working with. To provide context, the workspace to which the components belong are shown in gray.
Currently, it is possible to open one scenario at a time. To open a different scenario, close the one in use by clicking the 'x' button next to the name of your scenario. As soon as you confirm that you want to leave, you will be taken to 'Home' where you can filter by Scenarios to find the new scenario you would like to open.
How To Copy A Scenario
Make a copy of your scenario whenever you want to explore a different direction while keeping your original scenario unchanged.
To create a copy, click on the three vertical dots menu next to the name of your scenario and select 'Copy'. It will create a new scenario with all the changes you made to your original scenario, and any changes to your copy will not reflect in your original scenario.
You can also make a copy of your duplicated scenario to create intermediary transition states. Next, add each state as a slide to a presentation and visualize the as-is to the to-be transition of your architecture.
Related Navigator
In the 'Related' navigator, you can find the components that are not part of your scenario and that share a reference with one or more components within your scenario. However, if the component is a parent component, sharing a reference is not required to display in the navigator.
Moreover, the components shown in the 'Related' navigator are context-sensitive. In other words, the components displayed here depend on the component selected in the Scenarios navigator.
The 'Related' navigator helps you:
Understand what your scenario is directly connected to, and how it is connected so it is easier to make changes. You can use the Block Diagram view to visualize the relationship between your related components and your scenario components.
Expand the scope of your scenario. Quickly add related components to your scenario by clicking on the '+' button displayed next to each related component on hover. Alternatively, click the '+Include' button on your graph when on the Block Diagram view.
A few things to keep in mind:
The Related navigator is not a tool to model your graph. It does not respect filters and cannot be included in presentations. The related components are read-only 📖 and cannot be changed from a scenario.
Even though a scenario has its own set of user permissions, separate from your workspace permissions, the components displayed in the Related navigator are determined by your workspace permissions.
Excluding removes a component from the entire scenario, as if it never existed.
Deleting a component in scenario however will still keep track of what has been deleted.
Incompatible Metamodels
The Related navigator and the visual differentiator toggle can be unavailable when your scenario and mainline metamodels are out of sync. This happens when a new component type, reference type or field were created in the mainline and does not exist in your scenario metamodel.
To sync your metamodels and enable the Related navigator and the visual differentiator toggle, follow the steps in the Metamodel merge workflow.
Contextual Components
Contextual components are the parent components of both your scenario and related components. They show in grey in the Scenarios and Related navigators and are displayed to provide you with the necessary setting to make changes. Contextual components are not part of your scenario. Hence, references to and from contextual components are not included nor displayed in your graph.
You can quickly add contextual components to your scenario by right-clicking them and selecting the Include X component button. All their to and from references will also be added. If on the Block Diagram view, press the '+Include' button on your graph.
Visual Differentiator
Quickly spot the differences between the mainline and your scenario and understand the impact of change using the 'Visual diff' option in the Block Diagram view. Find it at the top of the Scenarios navigator or the top right corner of your screen.
When enabled, you can switch between three different viewpoints that will help you compare your current and future states :
Mainline: See how your architecture currently looks. Plus, the new components and references that were created in your scenario, but do not exist in the mainline, are outlined.
Scenario: See how your scenario currently looks. Plus, the components and references that were deleted in your scenario, but that exist in the mainline, are outlined.
Diff: Visualize all the changes made in your scenario in color for better understanding of what those changes are:
Red: The component or reference was deleted from your scenario but continues to exist in the mainline.
Blue: The component or reference in your scenario changed compared to the mainline.
Green: The component or reference was created in your scenario and does not exist in the mainline.
Grey: The component or reference was unchanged in your scenario.
All components retain their positions, so it will be easier to compare. 👀
Scenarios Privilege: How to Allow Users to Create a Scenario
In Ardoq, you can use privileges to define feature access and permissions to define asset access. For instance, permission to access a particular scenario.
For instance, you can enable the "Create Scenarios" privilege to allow users to create scenarios using the Scenario Mode. On the other hand, permissions enable you to grant access to a given scenario and define the actions your users can perform on that scenario such editing or reading data only. Learn more about scenario permissions in the section below.
How to Enable the “Create Scenarios” Privilege
Given that you are an admin user in the Ardoq app, you can allow users to create new scenarios by enabling the “Create Scenarios” privilege on their user role or individually per user.
How to Enable The “Create Scenarios” Privilege on a User Role
To grant Scenarios access to a specific user role:
Navigate to Preferences > Organization Settings > Manage User Roles
Select the user role you want to configure
Tick the “Create Scenarios” checkbox
Click “Save”
Enable the “Create Scenarios” privilege on a user role when you wish to grant users with a specific user role access to the Scenario Mode so they can either create and edit scenarios they’ve been granted a permission on only. It is the easiest way to manage who can create and edit scenarios in your organization. Once a privilege is enabled on a user role, it is not possible to disable them on specific users who have that user role.
For example, if you enable the “Create Scenarios” privilege on the Writer user role, all of your existing Writer users, and those you add in the future, will be able to create and edit scenarios they’ve been granted a permission on. Because the “Create Scenarios” privilege is enabled on the Writer user role, you won’t be able to disable the “Create Scenarios” privilege on single users who have the Writer user role assigned.
How to Enable the “Create Scenarios” Privilege per Single User
Enable the “Create Scenarios” privilege individually per user when you need specific people to create new scenarios and their user role does not allow them to.
To enable the “Create Scenarios” privilege on single users:
Navigate to Preference > Organization Settings > Manage Users
Look for the user you want to enable the “Create Scenarios” privilege on
Click on the three-dot button next to the name of a user
Select “Create Scenarios” from the dropdown
Hit "Save"
Scenarios Permissions: How to Share a Scenario With Users
Assign users a permission on a particular scenario to grant them access and determine what actions they can do on that specific scenario. It is not necessary to enable the "Create Scenarios" privilege for them to access and edit the scenario. The "Create Scenarios" privilege only allows users to create new scenarios.
The available permissions for Scenarios are:
Administrator permission: It allows users to read, edit, and delete the scenario they’ve been added to. They can also update the scenario permissions for themselves and other users who were granted access.
Writing permission: It allows users to read, edit, and delete the scenario they’ve been added to. They cannot update the scenario permissions.
Read-only permission: It allows users to read the scenario they’ve been added to. They cannot edit or delete it. They cannot update the scenario permissions.
You can grant users the Administrator, Writing or Read-only permissions depending on their role:
User Role | Scenario Permission Options |
Org Admins | Administrator, Writing, or Read-only |
Org Writers | Administrator, Writing, or Read-only |
Org Readers | Read-only |
Contributors | N/A. Contributors don't have access to the Ardoq app. Thus, it is not possible to grant them access to the Scenario Mode nor assign them a permission on a particular scenario. |
👉 Learn more about privileges and permissions in the “Assign Users Access to Assets and Functionality” KB article.
To invite users to your scenario and grant permissions, click on the three vertical dots menu next to the name of your scenario and select 'Permissions'.
Next, select 'Writing permissions' or 'Read-only permissions' on the 'All organization members' row to grant all users in your organization access to your scenario.
To give access to specific users only, choose 'No default access' in the 'All organization members' row and use the 'Find user or group' dropdown to add the users who should have access. For example, in the screenshot below, only Ian Stendera and Jacqueline S. can access the scenario. The rest of the users in the organization are not able to access it.
You can also make your scenario available to everyone in your organization while granting a specific permission to selected users only. For instance, in the screenshot below, all users in the organization can access the scenario but can only read it, while Ian Stendera and Jacqueline S. are able to make changes as they have 'Administrator' permissions.
The users added to your scenario will be able to see all the components and references in your scenario but will be limited in what they can do by the permissions they have been granted.
This has two benefits in regards to governance:
Safety for maintainers: The asset owner can restrict access to the mainline to a few maintainers, and limit everyone else to have read access. When someone else would like to make a change, this can be modeled in a scenario. The maintainers can then review and accept changes at their convenience.
Safety for Collaborators: Collaborators can create a scenario from anything they have read access to, and make changes without being afraid of affecting anyone else. When the change suggestion is consistent, changes in the scenario can be reviewed and accepted into the mainline by someone with write access to the respective workspaces.
👉 Note: Please keep in mind that it is currently possible to modify components, references, and tags only in a scenario.
Scenarios in Presentations
A presentation can contain slides from both the mainline and different scenarios at the same time. This will allow you to compare and communicate different options and alternatives in the same presentation.
To add a view in your scenario as a slide to an existing presentation:
Click on the 'Presentation Editor' button (▶️) at the top right corner of your screen and open the relevant presentation.
Double check you are on the desired view you wish to add as a slide.
Select 'Add this view as a slide' on the bottom right corner of your screen.
Done! Your scenario view is now added to your presentation.
To add a view in your scenario as a slide to a brand new presentation:
Click on the 'Export' button (↓) at the top right corner of your screen and choose 'Add to presentation'.
Type in the name you want to give to your new presentation in the dropdown and hit enter.
You will be taken to your new presentation where your scenario view has been added.
It's also possible to add the visual diff mode of Block Diagram to a presentation. The selected viewpoint (mainline, diff, or your scenario) will be shown and can be toggled from within the presentation.
In the case you want to add your scenario view as a slide to a brand new presentation, please exit the scenario and create a presentation from m
Merging Scenarios and the Mainline
The merge workflow enables you to keep your scenario up-to-date with changes from the mainline and to merge changes in your scenario back to the mainline.
Here, we'll explain how to use the merge workflow functionality to easily keep your scenarios and mainline in sync and up-to-date.
The merge workflow consists of two main sections: metamodel and data, with sub-sections for each type of change.
Only steps that require your attention will be triggered. This should normally only be a few steps, and it depends on how many changes have happened in either the scenario or in the mainline since the last merge.
Metamodel merge
The metamodel merge section handles differences in the workspace metamodel structure (rigid vs. flexible metamodels), component types, reference types, and field definitions.
Data merge
The data merge section handles differences in your components, references, and tags.
Progress bar
On the left side, there is a progress bar that highlights the steps with issues to address. The purple step is the one you're currently at, steps with filled circles have nothing to address, and steps with empty circles need attention.
Changes are applied to the target of the merge for each step. You can in most cases continue to the next step even without applying all changes, the exception is for new component types and reference types - here you need to accept the new types before continuing.
FAQ:
Excluding Components from Scenarios Without Deleting
If you need to exclude certain components from a scenario without removing them from your mainline architecture, follow this streamlined approach:
Merge Workflow: Utilize the merge workflow to reintroduce the deleted components back into your scenario from the mainline.
Exclude Components: Once reintroduced, exclude these components from the scenario. This action keeps the components in your project without affecting your scenario analysis.
If you're still left with questions, reach out to us! You can do so via our website or by using the in-app chat. 💬 We're happy to help.