csdmflow

Draw CSDM service models from plain text. Write down your business applications, service instances, offerings and services, say how they relate, and csdmflow lays out the diagram for you — colours, labels and arrows included.

https://github.com/user-attachments/assets/eed9276a-c35a-43be-945e-cd0eb11c9b70

BA crm: Customer Portal
SI crm-prod: Customer Portal Prod
TMSO portal-admin: Portal Administration
BSO self-service: Self Service

crm -> crm-prod
portal-admin -> crm-prod
self-service -> crm-prod

The full file is examples/hello.csdm.

Try it in the browser

Open the playground → No install needed: type a model on the left and the diagram redraws as you go.

• Examples — pick any of the bundled models, including every transcribed reference slide, as a starting point.
• Copy link — the model travels in the URL, so a link reproduces exactly the diagram you see.
• Download as — SVG, PNG, PowerPoint or draw.io. The PowerPoint and draw.io files hold real, editable shapes: each box is one shape with its text inside, lines keep their arrows and dashes, and in draw.io the lines stay glued to their boxes when you move them.
• Copy as — SVG, PNG, or draw.io shapes to paste straight onto a draw.io canvas. (Browsers can't put editable PowerPoint shapes on the clipboard; download the .pptx and copy the diagram from there.)
• Mistakes show the error and line number in place of the diagram.

To put diagrams on your own page instead, see In the browser.

---

Why

Service models in CSDM (ServiceNow's Common Service Data Model) are usually drawn by hand in slide decks. That works until the model changes, the boxes drift, and every team draws the same thing differently.

csdmflow treats the model as the source of truth and the picture as something you generate. You never place a box or pick a colour:

• Where things go follows CSDM: applications above their instances, delivery (tech offerings and services) to the left, consumption (business offerings and services) to the right, infrastructure below — each service-mapping hop (application → server → database …) one row further down.
• How a line looks follows the relationship: an offering pointing at an instance becomes a solid Depends On, an offering pointing at its service a dashed References, and so on.
• Colours follow the CSDM domain of each box.

Quick start

You need Node.js 18 or newer. There are no other dependencies.

git clone https://github.com/jessems/csdmflow.git
cd csdmflow
node bin/csdmflow.js examples/hello.csdm      # writes examples/hello.svg

Open the .svg in any browser. To see every example at once, with live reload while you edit:

npm run compare                               # opens http://localhost:4420

In the browser

Like mermaid, csdmflow can render diagrams straight into a web page. Include the script and every <pre class="csdmflow"> block becomes a diagram when the page loads:

<pre class="csdmflow">
  BA crm: Customer Portal
  SI crm-prod: Customer Portal Prod
  BSO self-service: Self Service

  crm -> crm-prod
  self-service -> crm-prod
</pre>

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/csdmflow.min.js"></script>

• Indentation inside the block is ignored, so the source can sit indented in your HTML.
• <pre class="gridflow"> renders raw gridflow (.gf) source instead.
• A block with an error shows the message below it; the rest of the page still renders. Warnings go to the browser console.

The script defines a global csdmflow, for pages that need more control:

Call	Effect
csdmflow.initialize({ startOnLoad: false })	Don't render on load (call before the page finishes loading)
csdmflow.run()	Render any blocks not yet rendered, e.g. after adding content
csdmflow.run({ root: el })	Same, but only inside el
csdmflow.render(source, { lang })	Returns { svg, width, height, warnings } without touching the page; lang is 'csdm' (default) or 'gf'
csdmflow.scene(source, { lang })	The laid-out diagram as shapes with coordinates, for the exporters below
csdmflow.toPptx(scene, title)	A .pptx file as bytes (Uint8Array)
csdmflow.toDrawio(scene, title)	A .drawio file as a string
csdmflow.toDrawioModel(scene)	Bare draw.io XML: put it on the clipboard and paste it onto a draw.io canvas

Every box in the SVG is a <g data-id="…"> holding its id from the source, so a page can make boxes clickable:

diagram.addEventListener('click', e => {
  const box = e.target.closest('[data-id]');
  if (box) open(box.dataset.id);
});

As an ES module: import csdmflow from 'https://cdn.jsdelivr.net/npm/[email protected]/src/browser.js/+esm'.

To build the bundle yourself, run npm run build (writes dist/csdmflow.min.js). examples/browser.html uses the local build. npm run site builds the playground into _site/; it is published to GitHub Pages on every push to main (.github/workflows/pages.yml).

Writing a .csdm file

A file is a list of entities and relationships, plus a title.

title "Microsoft Dynamics (Fly)"

# <TYPE> <id>: <name>
BA dynamics: Microsoft Dynamics
SI dynamics-prod: MS Dynamics Prod
SI ad-prod: Active Directory Prod
# CI class in brackets; commas = several instances
CI(Windows Server) servers: app01, app02

# <id> -> <id>
dynamics -> dynamics-prod
dynamics-prod -> servers
# override the label when you need to
ad-prod -> dynamics-prod : Sends Data to

Comments start with # and take a line of their own: on an entity or relationship line, everything after the name or label is part of it.

Variants and several instances

Two kinds of stacked boxes, written differently:

# variants: the same service in other environments
SI ea: *EA Prod [Dev, QA]
# several instances: commas in the name
CI(Windows Server) win: web01, web02

• Variants — [Dev, QA] after the name — are the same thing in another environment or location ([US, EMEA] works the same way). They draw as back cards with their name in the visible strip; the front card is the one named. Relationships attach to the stack as a whole.
• Several instances — commas in the name — draw as a plain stack with all names on the front card.

The id before the colon is what relationships refer to. You can leave it out and csdmflow will make one from the name (BA Microsoft Dynamics gets the id microsoft-dynamics); you only need explicit ids when two things share a name.

Names with commas, brackets or quotes

Put a name in double quotes and everything inside is plain text, the way mermaid does it. Useful when names come from a CMDB rather than your keyboard:

# one box, comma and all
BSO payroll: "Payroll, Benefits"
# a name, not a variant
SI sap: "SAP [Prod]"
# #quot; is a " inside quotes
BA hq: "The #quot;HQ#quot; Portal"
# several quoted names = several instances
CI(Server) web: "web, 01", "web, 02"
# variants after a quoted name; quote them as needed
SI ea: "EA, Prod" [Dev, "QA, EU"]

Inside quotes, #quot; stands for " and #<number>; for any character by its decimal code (#35; is #). The same codes work in title, subtitle and a CI's class, e.g. CI(Linux Server #40;2#41;) for a box titled "Linux Server (2)". Names without quotes behave as before.

Links

A link line makes a box clickable, for example to open the record it stands for:

SI crm-prod: Customer Portal Prod
link crm-prod "https://example.service-now.com/cmdb_ci_service_discovered.do?sys_id=…"

• SVG: the box opens the URL in a new tab.
• PowerPoint and draw.io: the shape carries the link too.

Only http and https URLs are allowed. A model can arrive in a shared link, and any other kind of URL could run code on the page that draws it. Inside the quotes, #35; stands for #, as in names.

Entity types

Type	Means	Domain colour
BC	Business Capability	design (teal)
BA	Business Application	design (teal)
SI	Service Instance (application service)	delivery (orange)
TMSO	Technology Management Service Offering	delivery (dark orange)
TMS	Technology Management Service	delivery (orange)
DCG	Dynamic CI Group	delivery (dark orange)
CI / CI(Class)	Any configuration item, e.g. CI(Database)	delivery (orange)
BSO	Business Service Offering	consumption (green)
BS	Business Service	consumption (green)
SP	Service Portfolio	consumption (green)

Relationships are inferred

Write a -> b and csdmflow picks the label and line style from the two types. You can write the arrow either way round — it is flipped to the CSDM direction.

From → To	Drawn as
BC → BA	Provided by
BA → SI	Consumes
BA → BA	dashed References (app → platform host)
BSO → SI	Depends On (green)
BSO → BS, TMSO → TMS, TMS/BS → SP	dashed References
TMSO → SI / DCG / CI	Contains (orange)
SI → DCG (the group that populates it)	Contains (orange)
DCG → CI	Query based Contains (orange)
SI → CI, CI → CI	blue service-mapping arrow, pointing down the chain
SI → SI	Depends On (orange)
BC → TMS / BS	purple Provided by::Provides, routed around the outside
any pair labelled : Sends data to (or Sends data from, Receives data from)	dash-dot data flow

Any other pair still draws, unlabelled, with a warning — a hint that either the model or the table needs a look.

Layouts

There is exactly one layout setting. Every layout keeps the same skeleton; what changes is how far each side runs sideways before it turns downward:

Tech Mgmt Service ← Tech Mgmt Offering ← [ Service Instance ] → Business Offering → Business Service
        delivery side (left)                                  consumption side (right)

layout cross — the default

Delivery fully sideways, consumption turns down after the offering. Most reference diagrams look like this.

layout tiers

Everything stacks top to bottom — applications, instances, offerings, services — with one column per application.

layout row

Everything runs sideways, so each application becomes a row.

layout lanes

Every type gets a lane of its own on both sides of the instances — tech services, tech offerings, instances, business offerings, business services — and each box sits level with what it connects to. Portfolios sit on top of their service's lane. The basic-diagram slides look like this.

layout reach <delivery> <consumption>

The presets are shorthands for two numbers, each 0–2: how many boxes that side places beside the instance before turning down. cross is reach 2 1, tiers is reach 0 0, row is reach 2 2. (lanes has no number form: it runs as far sideways as row, but keeps one column per application.) Anything in between is allowed — here is reach 1 2, where the tech service sits under its offering:

Other settings

Line	Effect
theme dark / theme light	Slide-style dark background (default) or light
linecolors domain / linecolors plain	Colour relationships by domain (default) or draw them all neutral
subtitle "…"	A line under the title

The side-by-side compare app

examples/ holds 29 models transcribed from a deck of CSDM reference diagrams. The compare app shows each reference slide next to its csdmflow render, so you can judge how close the generated layout gets:

npm run compare

• Every .csdm file in examples/ gets a panel; files named slide-NNN-….csdm are paired with slide image NNN.
• Edit a .csdm file — or the engine in src/ — and the page re-renders.
• Click any image to see it full size.

The slide images themselves are not part of this repo (they are third-party material). To get them, export your own copy of the deck into .slides/:

tools/extract-slides.sh "path/to/deck.pptx"   # macOS + Microsoft PowerPoint + pymupdf

Without slide images the app still works as a live preview of every model.

Export with PowerPoint, not Keynote. Keynote's import of .pptx files re-routes connector lines and can attach them to the wrong boxes, which silently changes what a diagram says.

Transcribing reference diagrams

docs/transcribing-slides.md is the guide used to turn the reference slides into .csdm files — what to model, what to skip, how to read a slide's layout, and how to settle the hard cases. It comes with tools/deck-passthru.py, which reads a deck's connector geometry to decide what a line running behind several boxes actually connects — and explains how to recover connectors drawn near-black on the dark background.

How it works

your.csdm ──► src/csdm.js ──► gridflow source ──► src/gridflow.js ──► scene ──┬─► SVG
              compiler:                            engine:                    └─► src/export.js ─► .pptx / .drawio
              CSDM semantics,                      grid layout, orthogonal
              placement, styles                    routing, labels

• src/csdm.js knows CSDM: the types, the relationship table, the layout rules. It writes plain gridflow source — run csdmflow file.csdm --emit-gf to see it.
• src/gridflow.js knows nothing about CSDM. It draws boxes on a grid and routes right-angled lines between them (straight, L-shaped, then Z-shaped), merging lines that share a target and hopping over crossings. You can also write .gf files by hand if you need a diagram the compiler can't express. Its output is a scene: every box, line and label with absolute coordinates (buildScene), which sceneToSvg draws.
• src/export.js turns the same scene into PowerPoint and draw.io shapes, so all formats show the same layout. No dependencies: it writes the .pptx zip itself.

Command line

node bin/csdmflow.js <file.csdm|file.gf> [-o out.svg] [--png] [--pptx] [--drawio] [--emit-gf]

Flag	Effect
-o out.svg	Output path (default: next to the input)
--png	Also write a PNG (needs rsvg-convert from librsvg)
--pptx	Also write a PowerPoint file with editable shapes
--drawio	Also write a draw.io file with editable shapes
--emit-gf	Also write the generated gridflow source as <name>.gen.gf

npm test renders and exports every example and fails on any error. npm run images regenerates the pictures in this README.

Limitations

• Layout is grid-based and automatic; very large models (30+ boxes) still get crowded lines in places.
• One global layout per diagram. A reference diagram that mixes styles within itself can only be matched approximately.
• The relationship table follows the conventions of the reference deck; review it against your own CSDM practice before relying on the labels.

License

MIT — use it however you like, commercially included. The one condition: keep the copyright notice and licence text with any copy of the code. If csdmflow helps you, a mention or a link back is appreciated.

Not affiliated

CSDM and ServiceNow are trademarks of ServiceNow, Inc. csdmflow is an independent project and is not affiliated with or endorsed by ServiceNow.