Artifacts and the System Landscape

Artifacts for the Future

When someone mentions artifacts, historical relics found in an archaeological dig often come to mind. Software development also has artifacts, forward-looking documents describing a solution intended to improve an organization’s operations. 

Carl Brundage, a Salesforce Certified Technical Architect, presented “Building Artifacts from Requirements” at the Spring 2021 Salesforce Business Analyst Summit. He defines artifacts as “solution diagrams to communicate decisions” that:

• Provide a high-level solution overview, including external systems

• “Quickly and clearly articulate a point of view” of solution design

• “Derive a shared understanding” of the solution

Artifact diagrams provide stakeholders a visual model of a solution, facilitating discussion about design flaws or omissions. When stakeholders engage in this discussion, they develop a shared understanding of a solution, bringing it closer to meeting its requirements.

Carl introduced examples of artifacts:

• System Landscape – describes a solution’s systems and how they interact

• Object Model – shows the solution’s data model (objects and their relationships)

• Security/Sharing Model – describes the access controls for record sharing

• Testing Strategy – describes how to validate a solution’s various aspects and phases

• Branching Strategy – describes how a solution’s versions are created and released

• Sandbox Strategy – describes the environments needed to test the solution

• Other solution modeling diagrams, such as process and concept maps

Staking Out the System Landscape

Carl focused on building a system landscape diagram. He started by identifying systems that will host and exchange data with the solution, including systems outside of Salesforce. 

Here is an example of a system landscape diagram showing a Salesforce B2C solution that integrates with a content management system (CMS), Service Cloud, order management, and an external enterprise resource planning (ERP) system:

The diagram puts the solution in the center, leaving space for additional elements.

Filling Gaps in the Landscape

Capturing functional requirements can overlook services provided outside of a solution. Carl recommends discussing with stakeholders what other systems will need to exchange data with the solution. He points out that it’s better to discover system integration gaps sooner rather than later.

The system landscape above overlooked payment processing, along with identity and access management. It also needs to generate documents and have them e-signed. The diagram below fills those gaps:

Connecting the Systems

Now that stakeholders have specified all the external systems that will exchange data with a solution, what will connect them? In this case, a Mulesoft enterprise service bus (ESB) will tie the external systems to the B2C solution:

Showing With the Flow

A system landscape shows the data flow between systems with arrows indicating the flow’s direction:

The diagram above is the “big picture” system landscape template from the Salesforce Architects site on the Documentation and Implementation Templates page.

Finishing Touches

Carl recommends adding layers to an artifact for specific audiences. For example, technical stakeholders need to know data exchange protocols. The diagram below adds a layer showing protocols on the custom data flows:

Artifact Drawing Tools

Business analysts and architects agree that artifacts enable quick understanding of a solution and ease identification of gaps. Carl shared some diagramming tools he has used:

• Visio (Windows, Web)

• Lucidchart (Web) 

• draw.io (Web, Windows, Mac, Linux, ChromeOS)

• OmniGraffle (Mac, iOS)

• Gliffy Diagram (Web)

• Google Slides/PowerPoint – only if nothing else

• Freehand – great on the whiteboard

Visio and Lucidchart top his list, two powerful subscription-based tools. Draw.io is free and features many templates and shapes to enrich a diagram. He recommends Google Slides or PowerPoint only as a last resort, as they focus more on creating presentations than diagrams.

The Value of Artifacts

Carl concluded his presentation suggesting, “Strive for information density. Make your picture worth a thousand words.” An artifact should convey as much information as possible while maintaining clarity. Balancing an artifact’s density and clarity enables stakeholders to evaluate it thoroughly and quickly. Exposing incomplete or incorrect information as soon as possible saves considerable time, energy, and frustration in the development process.

When stakeholders have a clear picture of the various aspects of the solution, they become more engaged in the design process. Customized layers enable the tailored presentation of relevant to different audiences. For example, the diagram with data flow protocols works well for technical stakeholders but would distract business stakeholders. Removing the labels clarifies the artifact and engages business stakeholders. 

Engaged stakeholders have more confidence about a solution’s design and opportunities to improve it. They provide superior feedback to the development team, enabling them to build a better-fitting solution for the business needs. 

Artifacts offer a clear, complete picture of a solution’s design, engaging stakeholders to improve the design through meaningful feedback.