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.
Table Of Contents:
NB! The Scenarios feature is an payed add-on to Ardoq! Please contact Ardoq sales if you want access to the feature.
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.
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.
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.
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 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.
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 permissions work the same way as workspace permissions. You can invite org admin/writer/reader users to a scenario and grant them the admin, writing or read-only permissions depending on their role.
You can grant:
Org admins > admin/writing/read-only scenario permission
Org writers > admin/writing/read-only scenario permission
Org readers > only read-only scenario permission can be granted
Contributors > it is not possible to add contributors to a scenario. They don't have access to Ardoq.
👉 See 'Scenarios > If granted admin/write/read' in this table to learn what each scenario permission allows a user with a particular user role to do in a scenario.
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 contributors:
Contributors 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
👉 See how scenario slides look like in our Skype for Business Application Roadmap Presentation.
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.
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.
The metamodel merge section handles differences in the workspace metamodel structure (rigid vs. flexible metamodels), component types, reference types, and field definitions.
The data merge section handles differences in your components, references, and tags.
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.
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.