The C4 model for ServiceNow Solution Design and Documentation

Having been in the software development space for over seven years, I have observed multiple issues occurring in almost every project, regardless of industry, company size, type of implementation, tools, etc. You might have guessed already: I am talking about documentation, or rather the lack thereof.

Problem definition

Even when documentation is present, it is often written in a freeform manner, comprising a mixture of screenshots, URLs, and explanations. Each stream lead or architect has their own understanding of best practices and documentation layout, which, especially in large and complex implementations, results in many different documents that are inconsistently structured and formatted.

These documents might be readable during the implementation phase or shortly thereafter, but if a new joiner needs to quickly catch up, they will have a really hard time—trust me, I’ve been there and done that.

The list of issues with freeform documentation goes on and on. Sometimes an executive or an enterprise architect needs to quickly check something and make a decision based on it. Instead, they must read through the aforementioned documents and spend a lot of time trying to find that one piece of information. And we all know how frustrated they become when their most precious resource is wasted. We all do.

Here comes the solution: The C4 model.

Quick overview of the C4 model

The C4 model was created by the Software Architect Simon Brown between 2006 and 2011, but it became popular after the launch of an official website and an article in 2018.

According to the official website, “The C4 model was created as a way to help software development teams describe and communicate software architecture, both during up-front design sessions and when retrospectively documenting an existing codebase. It’s a way to create maps of your code, at various levels of detail, in the same way you would use something like Google Maps to zoom in and out of an area you are interested in.”

Further clarified in Wikipedia, “The C4 model documents the architecture of a software system, by showing multiple points of view that explain the decomposition of a system into containers and components, the relationship between these elements, and, where appropriate, the relation with its users.

The viewpoints are organized according to their hierarchical level:

  • Context diagrams (level 1): show the system in scope and its relationship with users and other systems;
  • Container diagrams (level 2): decompose a system into interrelated containers. A container represents an application or a data store;
  • Component diagrams (level 3): decompose containers into interrelated components, and relate the components to other containers or other systems;
  • Code diagrams (level 4): provide additional details about the design of the architectural elements that can be mapped to code. The C4 model relies at this level on existing notations such as Unified Modelling Language (UML), Entity Relation Diagrams (ERD)or diagrams generated by Integrated Development Environments (IDE).

For level 1 to 3, the C4 model uses 5 basic diagramming elements: persons, software systems, containers, components and relationships. The technique is not prescriptive for the layout, shape, color and style of these elements. Instead, the C4 model recommends using simple diagrams based on nested boxes in order to facilitate interactive collaborative drawing. The technique also promotes good modelling practices such as providing a title and legend on every diagram, and clear unambiguous labelling in order to facilitate the understanding by the intended audience.”

Different levels of zoom allow you to tell different stories to different audiences

Different levels of zoom allow you to tell different stories to different audiences. (Source: c4model.com)

The C4 model for ServiceNow Solution Architecture design and documentation

I’ve been using the C4 model for documenting ServiceNow solutions ever since I joined the architecture team I am currently working on. This kind of documentation is standard practice on every project we work on, along with a few others.

In the following paragraphs, I will go through each of the four levels with a simple example of an integration between ServiceNow and an external system, feeding foundation data into the platform.

Here is a helicopter view of the whole diagram. Do not be frustrated if you don’t understand it the first time. Bear with me.

Helicopter view of an example integration, documented according to the C4 model

Helicopter view of an example integration, documented according to the C4 model

Let’s break it down

Level 1: System Context Diagram

As stated previously, the goal of the System Context Diagram is to document the main system and its interactions with users and other systems. In our case, this is ServiceNow, which interacts with BMC Remedy, feeding foundation data. The main persona here is the Foundation Data Admin on the Remedy side, who is responsible for the data’s completeness and correctness.

System Context Diagram

Zoom-in: System Context Diagram

Level 2: Container Diagram

The documentation states that this level aims to decompose a system into interrelated containers. A container represents an application or a data store.

In the current example, we can easily see that the foundation data import is implemented through the system scheduler, which executes data imports via REST API calls to the external system, using a technical account for authentication. The data is transformed by Transform Maps and stored in the database.

Zoom-in: Container Diagram

Zoom-in: Container Diagram

Level 3: Component Diagram

Zooming in to the Component layer, we try to decompose containers into interrelated components and relate the components to other containers or systems.

We’ve mentioned the system scheduler and the data source at the Container level, but here at the Component layer, we can get further information about the specific scheduled job, its name and interval, the name of the data source, as well as more specific details about the REST message and the service account.

Zoom-in: Component Diagram

Zoom-in: Component Diagram

Level 4: Code

The goal of this layer is to provide additional details about the design of the architectural elements that can be mapped to code. In most cases, this can be skipped or partially documented for the sake of simplicity. In our practice, we try to document at least the custom code that we have implemented as part of the project.

Looking back at my simple example, at the Code level, we can see a breakdown of the Data Source code and the Script Include that it references.

Zoom-in: Code

Zoom-in: Code

Benefits

While it might look a bit confusing when seen for the first time, an implementation documented according to the C4 model has multiple benefits.

First and foremost, it is documentation readable by all personas – executives like CIOs and COOs, Enterprise and Solution Architects, Business Process Consultants, and of course, implementers and developers. A picture is worth a thousand words, right?

When this type of documentation becomes a standard practice, it becomes really easy to onboard new people to a project or communicate design decisions with various stakeholders because they already know how to read it.

On the other hand, documenting every implementation with the same standard approach quickly builds up a library of reusable reference architectures that can be used with just a few tweaks or as communication/demonstration material during the early project phases while decisions are being made.

Last but not least, frameworks like Mermaid.js allow for diagrams to be presented as code, giving us a chance to store these in centralized repositories. Furthermore, we can use AI to analyze them and help us continuously improve our solution architecture.

Recap

The C4 model, an “abstraction-first” approach to diagramming software architecture, can be applied for the design and documentation of ServiceNow solutions, introducing a new standard approach for documentation with multiple benefits for both customers and implementation partners.

Date Posted:

June 17, 2024

Share This:

One Comment

  1. Radoslav Ehlenov June 18, 2024 at 7:16 pm

    Great article and useful practice! Thanks

Comments are closed.

Categories

Tags

Loading

Related Posts

Fresh Content
Direct to Your Inbox

Just add your email and hit subscribe to stay informed.