ServiceNow Common Service Data Model (CSDM) is a standard framework and prescriptive guidance for modelling and managing business services and service-related data in the CMDB. As with enterprise architecture frameworks, CSDM uses standard notation and nomenclature to depict business service model components.
Consistent schematic representation of business service models helps stakeholders visualise and communicate various aspects during design, implementation and operation. Documenting a large number of CSDM models can be a challenge for organisations with large number of IT project and services.
This article describes how Diagram as Code can be leveraged to manage the creation and maintenance of CSDM diagrams.
Drawing CSDM models
A CSDM model for a solution is depicted using colour coded domains enclosing blocks representing services and other configuration data items as shown below.
Foundation domain is shaded grey and contains all the core referential data entities (non-CIs). It includes common data elements such as Company, Location, Group and User, as well as Products and Contracts.
Design domain is coloured blue and contains elements for design and planning, including Business Capability, Business Application and Information Object.
Build domain is coloured red/pink and contains data entities relating to DevOps and the build process.
Manage Technical Services domain is coloured amber/orange and represent the provider view of technology deployed to run a business. It includes Application Services, Technical Services as well as the Configuration Items (of various types).
Sell/Consume domain is coloured green and represents business portfolio and services that are consumed by customers. It includes Business Services, Portfolios and Service Offerings.
ServiceNow provides plenty of guidance to help implement CSDM including a set or example available here. One such example is shown below. It shows the component items in the Design, Sell/Consume and Manage Technical Services domains.
Diagram as Code (DaC) is a concept that promotes the idea of creating visual representations of an architecture or code artefacts using actual code. This approach aligns with the principles of infrastructure as code (IaC) and configuration as code (CaC), bringing the benefits of version control, collaboration, and automation to the realm of diagrams.
By treating diagrams as code, developers and analysts can leverage their existing skills in coding and version control systems to manage and maintain visual representations of software architecture. This ensures that diagrams stay up-to-date, consistent, and can be seamlessly integrated into the development workflow.
The benefits of using DaC for CSDM include:
Consistency: Code-based diagrams foster consistency while producing and sharing CSDM artefacts.
Automation: Automated generation of diagrams ensures efficiency and reduces the manual effort required to maintain documentation.
Collaboration: Stakeholders can collaborate on diagrams just like they do with code, fostering teamwork and knowledge sharing.
Readability: Simple, intuitive syntax makes it easy for both technical and non-technical stakeholders to understand and contribute to the documentation.
PlantUML is one example of a DaC tool. Other options include Mermaid and Diagrams. There are a number of ways to get started with PlantUML, as outlined in this Quick Start Guide. The easiest way is to use the online tool here.
I prefer to use PlantUML via the VS Code IDE extension. It allows easy rendering and preview of the diagram as you write the code in VS Code editor.
PlantUML contains a repertoire of diagram types, as specified by the @start<type> and @end<type> tags in your code. In addition to the generic UML type, there are MindMap, Gantt Chart and other types. A PlantUML diagram file contains a set of directives that create nodes and relations. Common code can be written once in a separate "library" and then reused by including in projects.
More details about PlantUML can be found in the following guides:
Creating CSDM diagrams with PlantUML
We will first start with the common boiler-plate code that we will be including in all CSDM diagrams. This creates the consistent layout and colour coding required for the CSDM standard. It also helps keep the main code representing the model clear and concise.
The common include file is available here: CSDM.puml
It includes code for the legend:
legend top right
<b>Legend</b>
<#FFFFFF,#FFFFFF>| <#24C2Ce> BC | Business Capability|
| <#24C2Ce> BA | Business Application|
| <#009156> BS | Business Service|
| <#009156> BSO | Business Service Offering|
| <#FCA822> TS | Technical Service |
| <#FCA822> TSO | Technical Service Offering|
| <#FCA822> AS | Application Service |
| <#FCA822> CI | Configuration Item |
| | <b>Not all components shown for brevity</b>|
endlegendThe above code renders the legend as follows and places it at the top right in the drawing.
The include file also contains decoration of different cards representing entities in different domains. The fragment below shows definition of the Business Capability and its corresponding rendering.
' Define Business Capability
!unquoted procedure $BusinessCapability($name)
#24C2Ce;line:black;line.bold;text:Black [
BC
----
$name
]
!endprocedure
The include file is added to the main diagram with the !include directive as shown below. The fragment also shows the package directive creating a collection of cards representing entities within the Design domain.
@startuml
!include ../CSDM.puml
title O365 Platform
' Design Domain
'
package "Design" {
top to bottom direction
card ba_o365 $BusinessApplication("O365 E5")
card ba_ad $BusinessApplication("Active Directory")
card ba_teams $BusinessApplication("MS Teams")
card ba_sp_online $BusinessApplication("Sharepoint Online")
card ba_exchange $BusinessApplication("MS Exchange")
}
Other domains can be similarly created. Relationships are created using arrow notation as shown below.
' Relationships
ba_o365-d->ba_teams
ba_o365-d->ba_sp_online
ba_o365-d->ba_exchange
sp_comms-->bs_email
sp_comms-->bs_direct_mesgThe complete code for the above diagram is available here: O365Platform.puml and rendered as follows.
PlantUML diagram code of other examples can be found in this Github repository and includes the following: