3 things to consider as you start building Salesforce Diagrams

At TrailheaDX, Salesforce launched a systems diagramming notation for Architects (Salesforce Diagrams). It is 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.

“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

SALESFORCE DIAGRAMS OVERVIEW

Salesforce Diagrams is a set of diagramming design standards for Architects. It is designed for system diagrams including ERDs and a great deal of design thinking has gone into the readability and useability of the diagrams. Salesforce Diagrams follows the C4 Model approach, which means that there are 4 different level diagrams.

• Level 1: The big picture. The systems landscape
• Level 2: A piece of the whole. A 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

The hierarchy is shown here using the Salesforce Diagram notation.

3 CONSIDERATIONS WHEN BUILDING SALESFORCE DIAGRAMS

The diagrams that Architects will be drawing are a valuable and enduring asset. They are not drawn and thrown away at the end of the project. They are a critical part of the configuration knowledge of the Salesforce app and its connections to the rest of the IT landscape. They are used by Business Analysts, Architects and Developers. Therefore there are a number of considerations when managing them which we have identified based on the last 20 year’s experience.

1. You are managing a hierarchy of diagrams and there are relationships between the diagrams.

• Diagram numbering so that you understand where they fit in the hierarchy: The traditional approach is the Level 1 diagram is 1. Level 2 diagram which is the child of the “shape” numbered 3 on the Level 1 diagram is 1.3. The Level 3 diagram from the 4th shape on the Level 2 diagram is 1.3.4. and so on.  You cannot rely on the titles of the diagrams because they may be different and more expansive than the text in the shape that is the parent, or gets changed.
• Hierarchical integrity when diagrams change or are deleted: If, for example, a Level 3 diagram is changed or deleted, you need to make sure that any changes are reflected in the Level 2 and all the Level 4 diagrams that were below the Level 3 diagram. The same is true if there are connections to other diagrams at the same level.
• Showing that a shape has a lower level diagram: Not every shape will have a child diagram. So it is important to be able to determine which shapes do have more detail and be able to easily navigate to the child diagram.
• Navigating through the diagrams: As you go down the structure you will have more and more diagrams. That is the power of math. If each diagram has just 4 drill downs, you will have 1 + 4 +16 + 64= 85 diagrams. Making it easy for stakeholders to navigate up and down the hierarchy, but also between diagrams at the same level is critically important to save time and prevent confusion.

2. The diagrams do not sit in isolation as there are relationships to other assets

• Linking to supporting information to support development and test; Any shape could link to notes, screenshots, specifications, requirements and user stories, Salesforce metadata- objects, integations, automation, record type, and 3rd party systems and integration technologies.
• Links to business process maps drawn using the Salesforce UPN standard: UPN business process diagrams are the operational view of the business processes which exist in parallel with the Salesforce Diagrams which describe the systems perspective.

3. The diagrams are living documents that will evolve so they need to support collaboration and versioning

• Controlling access to the diagrams: To engage stakeholders the diagrams may be developed in live, remote workshops. The stakeholders need to be able to view but not edit the diagrams. Converting all the diagrams, or just the ones that changed, to PDF and distributing them is needlessly time consuming with the potential for stakeholders to be looking at out of date diagrams. The stakeholders should be able to access the diagrams in a portal with view-only rights, and either have a link that takes them to the correct diagram or they can easily drill down or navigate to the correct diagram.
• Collaborating and feedback: To drive continuous improvement stakeholders need to be able to provide feedback and drive discussions against any diagram. So, rather like a Slack channel or Chatter group embedded in every diagram, but the diagram authors should be able to aggregate the feedback and action it.
• Version control is at a diagram level: If a change of version is applied to a Level 3 diagram, do all the Level 4 diagrams have to change version? The short answer is no.  Diagrams should be able to cycle in version independently, but you need to maintain integrity. Ideally there is a formal sign-off process and a history of changes tracked.

The final word

Managing critical information that evolves of time needs a clear strategy.  Just like managing the data in Salesforce.  There are diagramming applications which are great for drawing discrete diagrams with a huge palette of shapes. But there also are process mapping applications that have mastered the management of hierarchies of diagrams at scale, with access controls, linking and version that support regulatory compliance. Inevitably your choice will involve compromises.

Here is a 4 level Salesforce Diagram structure drawn using Elements.cloud. You will need a free user account to access the map.   Here is the post that explained how we built it.

Link to diagram

Photo by Alison Pang on Unsplash