What kind of artifacts you need to generate and why

A Salesforce Architect is always aiming to create a secure and scalable solution that meets all required functionalities, and document them in a way that allows them to communicate them effectively with the stakeholders. This is applicable during the review board and while tackling a real-life implementation project. An architecture diagram is a graphical representation of a set of concepts that are part of an architecture. They are heavily used in software architecture and, when used effectively, can become a common language for documenting and communicating your solution.

Based on my experience, there are normally several discrepancies with projects in the way architectural diagrams are created. I have seen a lot of inconsistencies, a lack of detail, a lack of discipline, and fragmentation. In several cases, this can be traced back to the misuse of an architectural description language (for example, UML), or in some cases, the lack of using any standard at all. Sometimes, this is due to misunderstanding the value of the diagrams and relying on improper or inconsistent guidelines – and in some cases, a lack of architectural education.

In order to describe your Salesforce Technical Solution Architecture, you need the following artifacts:

• Must-haves:

  Actors and licenses

  Data model diagram

  System landscape architecture diagram

  Role hierarchy

  Development life cycle diagram

• Good to have:

  Process flows (in real-life projects, this is considered a must-have)

  Environment diagram (in real-life projects, this is considered a must-have)

  Contextual SSO flow

• Other diagrams, such as a data flow diagram, mind maps, and so on

  Remember

  You can deliver your artifacts/diagrams using one or more of the following tools:

  PowerPoint presentations

  Flipcharts

  Whiteboard (this is not transportable)

  A combination of these

  There is no right tool. You need to build your own habits and plans and use whatever works best for you.

There are a few things to keep in mind regarding these diagrams:

• Quality: During the review board exam, you have a very limited amount of time to craft your solution and create your artifacts. The quality of your diagrams is not expected to be top-notch, but they can't be scribbled scratches. Keep this golden rule in your mind while creating your artifacts and diagrams: they have to be pretty and must be worthy of being presented to a CXO. In the real world, these diagrams must look perfect. During the review board exam, however, they can look less perfect, but they still have to be readable, understandable, communicate the right message, and show your professional attention to detail.
• Use the tool that best suits your skillset: Some architects are sharper when it comes to using PowerPoint, while others are better with hand-drawn diagrams. Don't feel restricted – choose the tool that works best for you and that you feel more comfortable working with.
• Horses for courses: Some tools work better for specific diagrams. Some diagrams are explained in a better way if they're drawn in an interactive environment – for instance, where the audience can see the diagram being created in front of them and relate it to a story that you are telling. A good example of this is an SSO sequence diagram. However, other diagrams are better shown pre-drawn due to the amount of time needed to create them. The data model diagram is a good example of this. Here, you need to choose the right tool for the right diagram (you must also consider the way you are planning to set your review board; in-person or virtual). For an in-person review board, I find the whiteboard more suitable for interactively drawn diagrams, while flipcharts and PowerPoints and better suited for pre-drawn diagrams and artifacts.

Now, let's discover each of these artifacts in detail.

The actors and licenses diagram

The importance of this diagram is derived from the need to clearly communicate the required Salesforce, feature, and third-party licenses with your stakeholders based on concrete use cases expected from each set of users. This diagram will help you do the following:

• Identify the key use cases for each actor. These will help you determine the right license to use.
• Clearly communicate the role of each actor within your solution. In the real world, this should also help you calculate the number of required licenses, feature licenses, or third-party licenses. Moreover, documenting the scope of each role will help you answer the common What are these users expected to be doing? question, which tends to become more difficult to answer with time.

For this diagram, you need to consider the following:

• Include all the actors mentioned in the scenario.
• Include all the required licenses, including feature and third-party licenses. Pay extra attention to community licenses. You need to understand the capabilities and limitations of each Salesforce license.
• Go for the best justified technical solution (license-wise). Don't think of non-standard approaches to cut down the cost. Avoid any pattern that could breach Salesforce terms and conditions.
• This doesn't have to be a diagram, but the standard actors and use cases diagram is a great fit for the purpose mentioned here. I personally find it particularly useful when it's drawn on a flipchart or a paper, but a bit difficult to create using PowerPoint, given the time restrictions. In this case, a bullet point list for the actors and licenses, along with a sub-list for activities/use cases, should do the trick.

  What if I made the wrong decision and selected a license type that is not sufficient to cover the requirement?

  Don't panic – accept the fact that you picked the wrong license, rectify that on the fly, and explain your rationale behind selecting the original license to the judges. We all make mistakes; it is how we handle the situation that matters most.

Now, let's take a look at an example. The following simplified actors and licenses diagram illustrates the activities/use cases related to three different personas, and the license(s) required by each:

Figure 1.1 – Actors and licenses diagram example

If there was an unclear reason for picking one license over the other, add the additional rationale behind your decision to the diagram/documentation. This will help the judges – or in real life, the stakeholders – further understand your vision and the drivers behind your decision.

The data model diagram

The data model diagram is one of the most crucial diagrams that you need to create. Without it, you can't explain your solution properly, neither during the exam nor in real life. This diagram will help you with the following:

• Identify the custom objects versus standard objects used in your solution. Remember that standard objects come with pre-built functionalities and limitations, while custom objects have a different set of considerations (for example, some licenses have a limit on the number of custom objects that it can access). This diagram will help you identify and communicate your data model and the planned use of every object.
• Identify LDV objects. Although identifying LDVs requires more than the data model (it requires performing calculations based on the given scenario), having a well-documented data model can help you identify where things are likely to go wrong and where the data is likely going to grow more rapidly (for example, junction objects), which can help you craft a mitigation strategy.
• This diagram is also crucial for your sharing and visibility requirements. The type of relationships between objects has a direct impact on the records' visibility. This is something you cannot easily identify without a diagram that you can digest by taking a quick look at it.
• Your data model has a direct impact on your reporting strategy. By looking at this diagram, you should be able to tell where the data that's required for a particular report should be coming from.
• You can't create a solid integration strategy without understanding your underlying data model.

This diagram should include the following:

• Relation types (master-detail versus lookup).
• Cardinality (one to many, many to many, and so on).
• Object type (standard versus custom versus external objects).
• Org-Wide Defaults (OWD) for each object.
• Must highlight LDV objects, though you must do the math for this (it is a good practice to include these somewhere on this diagram).
• The logical data model level should be fine for the review board exam (showing the key fields for each object). In real life, you have to create a physical-level data model (showing all fields).

Now, let's take a look at an example. The following simplified data model shows the relationships between a set of standard and custom objects:

Figure 1.2 – Data model diagram example

Highlighting the owner of the records of each object type will help you illustrate part of your sharing and visibility strategy. A legend to explain your diagram would also be a nice professional touch.

The system landscape diagram

This system landscape diagram will help you illustrate the systems included within your solution and the relationships between them. This is extremely important because it's likely that you are going to end up creating an integrated solution that spans multiple systems. The diagram will also help you identify and document high-level information about your integration interfaces. This will be the main diagram for describing how the data will be moving across the systems (unless you decide to create a data flow diagram).

Remember

You are creating all these artifacts to help you explain the end-to-end solution to your audience. It is important to understand why you need each diagram and how to use it. There is no point in creating the diagram if you don't know how to use it.

For this diagram, you will need to do the following:

• Show all systems involved in the landscape architecture (including third parties, such as AppExchange products or external systems). In real life, you may also want to extend the landscape architecture so that it includes the key functionalities that are delivered by each system. During the review board, this might take more time than what you can allocate.
• Include the systems that you are planning to retire. Find a way to differentiate them from the other systems that you want to add or keep. Color coding is a good idea, but you can simply add a symbol next to the system to indicate its status. In real life, you are probably going to create multiple copies of this diagram, with each representing a snapshot in time.
• Show the proposed integration interfaces. You also need to include information such as the integration pattern, how you are planning to secure your channel, and the authentication standard used. You might find that adding all of that directly to the diagram makes it a bit too busy. Alternatively, you can use an interface reference/code on the diagram and create a supporting table with full details. Then, you can use both during the review board to explain your integration strategy.
• Remember to include SSO interfaces.
• Also, include any mobile devices that are part of your landscape. Add the type of the mobile app right next to that (Salesforce Mobile, Native Custom App, Hybrid App, or HTML5-based).

Now, let's take a look at an example. The following diagram shows the systems involved in a landscape where Salesforce is replacing a legacy CRM. You will also notice that it is integrated with external systems through an integration middleware (MuleSoft):

Figure 1.3 – System landscape diagram example

The following table describes the proposed integration interfaces:

Figure 1.4 – Proposed integration interfaces

Typically, you don't include data migration interfaces in a landscape architecture diagram. However, this could be beneficial, particularly during the review board, to explain what tools you are planning to use and what your proposed migration strategy is. Ensure you clearly differentiate that from the integration interfaces. Mixing data migration and data integration concepts is a common mistake.

The role hierarchy diagram

Data security and visibility is a key topic for a Salesforce architecture. The wrong data sharing and visibility architecture can significantly impact the performance of the solution and can create a major risk to compliance and security. There are several elements that form your overall data sharing and visibility architecture, including your data model, role hierarchy, territory structure, and the capabilities and limitations of some Salesforce licenses. The role hierarchy diagram is a common sharing mechanism, and that is why creating this diagram will help you explain your overall data sharing and visibility strategy. In real life, you might even want to include full documentation of your sharing rules.

This diagram should include the following:

• A review board, where you must create a full role hierarchy for at least one branch. You don't need to create all the branches if they are simply copied variations of the illustrated branch. For example, if you are going to create a role hierarchy that includes the head of sales for each state in USA, there is no need to create branches for all the states, as long as you can show one or two full branches for some states and indicate that a similar approach will be followed for other states. In real life, you will have enough time to create documentation for the full hierarchy.
• Roles for partner community and customer community licenses as well.
• Any license type limitations. The actors and licenses diagram will be handy at this stage.

Now, let's take a look at an example. The following diagram shows a company hierarchy based on the USA:

Figure 1.5 – Role hierarchy diagram example

Additionally, you can also include a list of sharing roles and other sharing mechanisms that you are planning to use, likely as an annexed table.

The business process flow diagram

The business process flow diagram will help you illustrate and communicate the targeted user experience for a given process. This is a good to have diagram during the review board in terms of the value it adds, but also in terms of the time it takes to create. Practice creating these types of diagrams and decide if you will include them as part of your generated artifacts or not. Again, remember that we create these diagrams to help us explain the end-to-end solution, not just for the sake of creating diagrams. In real life, diagrams that explain each business process is a must-have. It is also strongly recommended that it's in standard BPMN 2.0 format as this creates a common language between team members and avoids you losing the required details and precision.

This diagram should include the following:

• Systems included in a particular process flow. I personally prefer to use swim lanes.
• The starting action and actor.
• Activities included at each stage, and whether they are manual or automated.
• The logic that controls moving from one step to the other or from one system to the other.
• Data that's been exchanged between systems.

Now, let's take a look at an example. The following business process diagram describes a partner onboarding process. You can add as much detail as you wish for the given hypothetical scenario. In real life, this diagram is likely to be much more detailed:

Figure 1.6 – Business process flow diagram example

Subprocesses help create reusable elements. It is recommended that you use subprocesses whenever applicable. However, this is perhaps more suitable for real-life scenarios rather than the review board.

The environment diagram

Governance is another key knowledge area that you have to cover as part of your end-to-end solution. Part of it is your environment strategy; that is, what kind of environments you are planning to use and for what. If you don't create this diagram as part of your presentation, then you are likely going to be asked to draw it during the Q&A session. This diagram is a must-have in real life and can also drive some budget-related discussions.

This diagram should include the following:

• What environment types are being planned at each stage.
• Justification for sandbox-type selection and how this is associated with the test plan. However, this probably isn't going to be something you document on the diagram itself.
• The activities you've planned for each environment and the types of tests included.
• Details about who will be deployed to each branch and at what stage.
• Make sure you fully understand the Continuous Integration and Continuous Deployment (CI/CD) concepts. Hands-on experience is very important here.
• Any third parties that you are planning to use (for example, automated build tools, source controls, and so on).

We'll cover examples and more details related to this diagram in the chapters to come.

I recommend that you combine this with your source code branching diagram, assuming you have enough time to do so.

The contextual SSO flow diagram

Most scenarios you get will have SSO requirements. This diagram (you might need more than one, depending on the used SSO standards) will help you walk your audience through the details of the target user experience without missing any points. If you didn't create this diagram as part of your presentation, then you are likely going to be asked to draw it during the Q&A session. A standard sequence diagram is highly recommended. This is one of the diagrams I personally find more suitable to be drawn in an interactive way (for instance, using a whiteboard).

For this diagram, take the following into consideration:

• You need to know how to fully draw the following flows like the back of your hand, along with all the required details:

  SAML IDP initiated

  SAML SP initiated with deep linking

  OAuth 2.0/OpenID Connect web server/Auth code

  OAuth 2.0/OpenID Connect User-Agent

  OAuth 2.0/OpenID Connect refresh token

  OAuth 2.0/OpenID Connect JWT flow

  OAuth 2.0 Asset token flow

• You need to understand when to use each of these standards.
• Pay extra attention to the use cases when you need to include them as part of your integration architecture (for example, an external system authenticating with Salesforce) or mobile architecture (for example, a native app authenticating with Salesforce).
• Social sign-on comes with a few caveats that you need to keep an eye on and be able to explain.

We'll cover examples and more details related to this diagram in the chapters to come.

It is recommended that you include information regarding the data that's exchanged at each step of the sequence diagram.