DSL Decompilation from JSON

[tulrichtrimble]

I'm in the midst of writing a workspace to DSL exporter to support collaborative enterprise workflows and would like to verify that these efforts are not redundant or ill-conceived for the ends.

This diagram depicts the only feasible workflow I've found to support federated contributions to our enterprise environment.

Many teams own many systems. The Backstage.io service catalog is the system of record for most applications and services. Scripts using the Java libraries periodically seed the SoftwareSystems and shared Landscape of an OnPrem Structurizr instance. The scripts also clone the workspaces to a Git repo and decompile them into DSL.

Architects may then augment a workspace's DSL with people, relationships, views, containers, documents, etc then use scripts to push them back to their home workspace OnPrem.

Before continuing to invest in this workflow, I'd like to check some assumptions:

• An OnPrem Workspace will not parse DSL. This is only done through Java, Lite, or the CLI.
• There is no supported way to export a workspace to DSL that reliably compiles back to the workspace.

Are those accurate?

The DSL generation is straight-forward enough by reverse engineering the parser, but it's laborious and likely to break with updates. If there is a way to add content through Java while retaining the ability for humans to tweak the DSL, I am all ears!

There is tremendous value in this for our enterprise. If there is no alternatives, and there is expressed community value, I'd take a bit more care to open the possibility of a PR.

Thanks!

[simonbrowndotje]

If there is a way to add content through Java while retaining the ability for humans to tweak the DSL, I am all ears!

When generating your workspace from Backstage, including an element property named structurizr.dsl.identifier, and then saving to a JSON file will allow that element to be extended via the DSL. There will be a post on the Patreon about this in the next few weeks, but there's an example in the tests that illustrates this -> https://github.com/structurizr/java/blob/master/structurizr-dsl/src/test/resources/dsl/extend/extend-workspace-from-json-url.dsl#L4

[tulrichtrimble]

I'd added that property but hadn't considered an adjacent workspace until I saw your note:)

Since this option wasn't entirely clear to me at the outset, this is the workflow I'll implement in case it helps clarify for others.

1. Pull all workspace metadata from OnPrem (inspired by recently moved enterprise examples)
2. Pull systems and containers from the service catalog and match/create OnPrem metadata. Create a workspace for every metadata adding SoftwareSystem and Container elements with a structurizr.dsl.identifier property. Add properties like themes if desired.
3. Add Systems to the landscape.
4. In local repository, create a /workspace-name data folder for each workspace. in each folder
   1. Add the corresponding workspace-catalog.json file from the generated workspaces. It might not contain a system if there isn't one in the catalog.
   2. Ensure the presence of a workspace.dsl starting with workspace extends workspace-catalog.json { and a !element [structurizr.dsl.identifier.value]{ in the model for each catalog SoftwareSystem. The landscape may have multiple.
5. The workspace.dsl in each /workspace-name folder is extended to add software system properties and add containers, relationships, views, animations, etc. These are automatically compiled/previewed locally using Structurizr Lite to produce a combined catalog+localDSL workspace.json.
6. The workspace.json can then be pushed OnPrem to its corresponding workspace using the CLI, optionally through a CI/CD action upon PR review.

Seems workable for multiple shared-model contributors with some minimal complexity and governance. Thanks for any other tips and the nudge in the right direction (assuming I read you right)!

Please let me know if there's value in contributing to the enterprise examples if they are still planned.