Workspace linking

When using one of the client libraries to create software architecture models as code, it's relatively straightforward to share code 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. 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.

Example

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:


Paid subscriptions only

Linking and unlinking workspaces

Linking and unlinking workspaces is done via your dashboard. Find the child workspace on your dashboard, and click the "Show more..." button to expand the workspace summary. Choose the desired parent workspace in the dropdown list, and click the button.

Linking a workspace

Linking and unlinking elements

Linking and unlinking elements is done via the "Workspace Linking" tab of the browser-based workspace editor.

Linking elements

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:

  1. Export the JSON from the workspace that you would like to split.
  2. Create a new workspace.
  3. Import the JSON into the new workspace.
  4. Rename both workspaces, so that you know which is the parent, and which is the child.
  5. Link the child workspace to the parent workspace, via your dashboard.
  6. 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.
  7. Save the child workspace.
  8. 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:

Known issues

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 structurizr.com/share).
  • Embedded diagrams.

As a workaround, open the workspace in the workspace editor to sync any changes, and then save the workspace.