Introducing Salesforce Diagrams: new addition to an Architect’s toolset

Share this article...

Salesforce Diagrams is a set of diagramming design standards for Architects to create system diagrams and entity relationship diagrams (ERDs). These are vital for a well-documented Salesforce org that can be easily communicated to teams across your organization.

Salesforce launched a systems diagramming notation for Architects (Salesforce Diagrams) and a business process mapping notation for Business Analysis (Salesforce UPN). This article explores what each looks like, and when to use them.

“As Architects we know that diagrams are an important tool in our toolset. When we surveyed you, we heard loud and clear that you want more diagramming tools and more standardised diagrams.”

Susannah St-Germain – Architect Evangelist

What are Salesforce Diagrams?

Salesforce Diagrams is a set of diagramming design standards for Architects to create system diagrams and entity relationship diagrams (ERDs). You can use any number of tools to draw the diagrams to match the standards – plus a great deal of design thinking has gone into the readability and useability of the diagrams.

The diagramming follows the C4 Model approach, which means that there are 4 different diagram levels.

  • Level 1: the big picture/systems landscape
  • Level 2: a piece of the whole/subset of the landscape
  • Level 3: process or interaction view, a limited view of the technologies in a solution.
  • Level 4: “double click”, the data model showing just the objects involved

Therefore there are considerations when building the diagrams as they are a critical asset as the ongoing configuration knowledge of Salesforce:

  • How are you going to manage the hierarchy of diagrams?
  • How are you going to apply access rights and version control?
  • What are the relationship between the diagrams and other assets; business process diagrams (UPN), Salesforce metadata, user stories, training material.

Salesforce Diagrams provides a style guide for each level diagram. Here are the Salesforce Diagrams Level 1-4:

Level 4 is looking at the data model, or ERD, but only including the subset of objects relevant to the scope of the higher level diagrams. Alternatively, it could describe the data flows.

How to Get Started with Salesforce Diagrams

There is training on how to draw the diagrams which supersedes the Trailhead course (its predecessor). You can download the templates for Google and Powerpoint.

When to Use Salesforce Diagrams, or UPN?

Salesforce UPN (Universal Process Notation) is a business process mapping notation for Business Analysts, which I covered in this guide.

The Trailhead team launched the Business Process Mapping for Analysts, How to draw Business Process Maps and updated Business Analysis Best Practices Trailhead badges. There is also an in depth Business Process Mapping for Architects course (accessed via the Partner Learning Camp).

The immediate question that comes to mind is “are Salesforce Diagrams and UPN competing, or complementary standards?

The answer is that they are complementary – both types of diagrams are needed if the implementation is going to be successful. There may also be a requirement for relationships between diagrams to connect the systems and business process views.

The table below is a reference for which standard you should use for each phase of a Salesforce implementation. Remember, this is critically important documentation which captures the configuration knowledge of the application, so they need to be linked back to the metadata that is changed because it is used for future releases.

Phase of ImplementationUse Salesforce DiagramsUse Salesforce UPN
IdeationYES or whiteboarding
Business AnalysisYES
Architect/DesignYES
BuildYESYES
TestYESYES
Release and Data MigrationYES
User Training and FeedbackYES

Final Thought

After spending many years involved with business process mapping, I think it’s fantastic that Salesforce is investing in driving great documentation standards.

Whilst not everyone enjoys documenting what we are about to build or what we have built, we all understand the value of walking into a well documented org.

Add Comment