When creating software architecture models as code or text, it's relatively straightforward to share the source and reuse model elements across a number of workspaces. This isn't possible when using the browser-based workspace editor though, which is why Structurizr supports the ability to link workspaces together. In essence, the workspace linking feature allows you to reuse software systems and people from another workspace. Please note that workspace linking will not work if you're creating workspaces using one of the code-based client libraries or the Structurizr DSL - see FAQ below. In this page we'll use the following terminology:
- Parent workspace: the workspace that you would like reuse elements from.
- Child workspace: the workspace that you would like to add elements to.
The anticipated use case is to create one parent workspace to model the system landscape for an organisation (i.e. people and software systems), and one or more child workspaces to model each separate software system in detail. The following workspaces show an example of this:
- Big Bank plc - System Landscape (parent workspace)
- Big Bank plc - Internet Banking System (child workspace)
- Big Bank plc - Mainframe Banking System (child workspace)
Linking and unlinking workspaces
Linking and unlinking workspaces is done via the workspace settings page (click the button from the workspace summary page). Choose the desired parent workspace in the dropdown list, and click the button.
Linking and unlinking elements
Linking and unlinking elements is done via the "Workspace Linking" tab of the browser-based workspace editor.
Initially, this tab shows the people and software systems that are available to use from the parent workspace. Clicking the button will add the element to your workspace, and create a link between it and the same element in the parent workspace. With this link in place, any changes to the element in the parent workspace will be reflected in this (the child) workspace. When you add multiple elements from a parent workspace, any relationships between those elements will also be added to the child workspace. Like elements, these relationships become linked to those in the parent workspace, and any changes will be reflected.
Frequently asked questions
Does a user need access to both workspaces?
In order to link/unlink elements/relationships, or see any changes to previously linked elements/relationship, yes, any user must be able to access both the child and parent workspace. If you have role-based access setup for a child workspace, you should also ensure that those users have access to the parent workspace. Read-only access to the parent workspace is sufficient.
What happens when I unlink a workspace?
When you link an element, Structurizr actually copies that element into your workspace. Therefore, if you unlink from the parent workspace, your child workspace will still function as expected. Linked elements and relationships will be retained, although they won't be updated automatically anymore.
What happens when I delete a parent workspace?
Similarly, the child workspace will still function as expected.
What happens when I delete a linked element from the parent workspace?
Deleting an element from the parent workspace will not delete it from the child workspace. Instead, the "Workspace Linking" tab will show an "Orphaned elements" list, providing you with the choice to unlink the element or delete it from the child workspace too.
What happens when I delete a linked relationship from the parent workspace?
Deleting a relationship from the parent workspace will also delete it from the child workspace.
When are elements and relationships synchronised between the parent and child workspace?
Changes to linked elements and relationships will be seen when opening the workspace editor or a diagram (see known issues below).
Does workspace linking work with client-side encryption?
Partially. The child workspace can be client-side encrypted, but the parent workspace can't.
I have an existing workspace that I'd like to split into a parent and child; is that possible?
Yes, the basic steps are as follows:
- Export the JSON from the workspace that you would like to split.
- Create a new workspace.
- Import the JSON into the new workspace.
- Rename both workspaces, so that you know which is the parent, and which is the child.
- Link the child workspace to the parent workspace, via your dashboard.
- Open the workspace editor for the child workspace and, from the "Workspace Linking" tab, choose which elements you would like to link from the parent workspace.
- Save the child workspace.
- Open the workspace editor for parent workspace, and delete anything that you don't need. Start with views and documentation, then move onto deployment elements, containers and components.
How can I navigate from a System Landscape diagram in the parent workspace, to a System Context diagram in the child workspace?
Modelling across multiple workspaces means that you lose the ability to double-click a diagram element to zoom into it. You can replicate this behaviour by setting a URL for the element in the parent workspace. In the example, the URL for the "Internet Banking System" element in the parent workspace (Big Bank plc - System Landscape) has been set to the URL of the System Context diagram in the child workspace (Big Bank plc - Internet Banking System) as follows:
How can I use the theme from the parent workspace?
Just use the dynamic theme feature as usual. Again, with the example, the parent theme URL has been set on the child workspace as follows:
Why doesn't workspace linking work if I'm creating workspaces using a code-based client library or the Structurizr DSL?
When you use the browser-based workspace editor, all of the internal element IDs remain stable after an element has been created. You can rename an element, change its description, etc and the element ID doesn't change. When you link a child workspace to a parent workspace, elements in the child workspace become linked to elements in the parent workspace by those IDs.
This is not the case when workspaces are created using the code-based client libraries or Structurizr DSL - element IDs are generated based upon the order in which elements are created in the code/text source.
Because these IDs are not stable, there's no way to link to them.
The workspace linking feature is irrelevant if you're using a code-based client library or the Structurizr DSL anyway, as you can modularise your workspaces (reusable code, DSL
!include, etc) to reuse elements across workspaces.
Changes to linked elements/relationships is not yet implemented for the following pages on the cloud service:
- Public and shareable workspaces (i.e. when accessing the workspace with a URL that starts
- Embedded diagrams.
As a workaround, open the workspace in the workspace editor to sync any changes, and then save the workspace.