Skip to main content

Document the Architectural Landscape

Learning Objectives

After completing this unit, you’ll be able to:

  • Explain how to diagram the system architecture.
  • Describe what’s in a data flow diagram.
  • List what you need to consider for import and export flows.
  • List what you need to document for third-party integrations.

Document the Landscape

Through the discovery and design phase of the project, you analyzed business requirements and converted them to technical capabilities. It’s important to fully document the system landscape to properly guide the project to completion. That means creating architectural and data flow diagrams. Review the Project Documentation for Salesforce B2C Commerce Functional Architects, “Create an Architecture Diagram” unit for details.

Architecture Diagram

An architecture diagram provides a visual overview of what systems are included in the implementation and how they interact with each other. A diagram like this helps everyone on the team understand the relationships between B2C Commerce systems, technology from LINK partners, and other third-party systems.

Sample B2C Commerce architectural diagram showing B2C Commerce integrated with back-end systems and third-party services and clients.

From Salesforce Clouds to third-party services, any of these systems can be a system of record—that’s the system that’s the authoritative source of truth for the information. Understanding the system of record for each piece of information is important for analyzing how data flows.

In the diagram, MuleSoft, for example, is a data integration platform that connects a variety of data sources and applications, which are systems of record. Mulesoft’s Commerce Cloud connector supports order management system (OMS) integrations.

The B2C Commerce LINK technology partner program certifies partner integrations such as tax and payment technology.

Completeness Check

The above diagram is incomplete. Can you find what’s missing? For example, where’s the ERP/Inventory flow? The communication format between the platform and middleware isn’t well documented. Also, the communication between middleware and the merchant’s infrastructure wouldn’t be in B2C Commerce XML format. Product import uses CSV format, while inventory and pricebooks use XML. 

Data Flow Diagram

A data flow diagram spells out how data flows from one application or transfer point to another so that you can analyze how often data transfers and each point it touches. Here’s an example of a data flow diagram you will create. 

The flow diagram, showing how product data flows from the WMS to the product PIM.

This data flow diagram shows how product data flows from the warehouse management system (WMS) to the product information management system (PIM). The main data management (MDM) system handles company data such as data about employees, customers, and so on.

From the PIM system, product data flows via daily feeds to MuleSoft, and then to the SFTP transfer server, and finally to B2C Commerce. Meanwhile, the dynamic imaging server transforms and returns images from and to B2C Commerce, respectively.

The product image agency sends product photos for approval and then on to the SFTP transfer server. It’s a manual process, so it's not in the architecture diagram.

Completeness Check

What’s missing in this diagram, or how could it be improved? Here are some ideas.

  • Provide more details about the backend/customer infrastructure; for example, what are the WMS, PIM system vendors?
  • Add the flow of product data to Einstein and affiliates to the diagram.
  • Add components for content flows from a CMS integration and customer data to/from a CRM.

Import/Export Flows

The number of import/export processes required depends on how fast data changes. Take the Salesforce B2C Commerce Import & Export Trailhead modules for some ideas. 

Imports

How many import feeds are required and how often do they run? For example, price books and inventory need to be updated more frequently than catalog data. Some objects are dependent upon other objects. Campaigns and promotions, for example, must be updated together because campaigns are collections of promotions. 

Exports

With exports, strive for efficiency. For example, create a standard export to reuse for multiple integrations, such as one catalog feed for multiple affiliates. Schedule exports in the proper sequence, so that an export that depends on an import is successful. For example, the catalog export feed depends on an external digital asset management (DAM) system providing external images locations.

Import and Export

Perform delta feeds whenever possible. These feeds contain only the differences between the current and previous feed. They are smaller and faster to import and less vulnerable to network interruptions.

Data Feeds and Replication Schedules

Document scheduled jobs like this.

Name

Schedule

From

To

Full/Delta

Resources

Catalog import






Price book import






Order export






Inventory






Order status import






Replication






For batch transaction flows, such as order history and order submission to an order management system, use SFTP to avoid web service traffic and performance issues.

Job and Replication Plan

You need to understand the dependencies between data coming from different sources so you can define your job and replication plan accordingly. You need to:

  • List integration jobs
  • Include data replication
  • Outline dependencies
  • Create a provisional schedule

For example, the merchant has catalog and image imports, which require a search index rebuild, followed by replication. Here are the considerations:

  • The catalog and image files imports take the longest, so they should start first.
  • Each import operation (ideally delta) must complete before the search index rebuild.
  • The search index rebuild must complete before data replication.
  • Data replication must complete at least 15–30 minutes before the site’s prime time (the time it takes to clear web adapter cache).

Here’s a simple job execution plan.

Job

Start Time (daily)

Catalog import

1:00

Images import

1:50

Price book import

2:20

Search index rebuild

3:10

Data replication

4:40

Integrations

B2C Commerce Support configures firewall permissions for your B2C Commerce system to allow connections to third-party servers via nonstandard ports and protocols. Merchants are responsible for business, legal, and financial coordination with third-party providers to make sure the integrated system or solution is ready for prelaunch testing.

Create a summary document like this of the third-party integrations in the architect diagram.

Integration Type

Provider

Credentials Link

Technology

Input Data Format

Output Data Format

Order management






Payment






Tax






International






Shipping






Interface Specification Document (ISD) 

Once you’ve created a list of providers, complete an ISD like this for each of them.

Interface Name:
Payment Service Provider

Description:

Payment authorization

New or Existing?

New

Source (origin):

B2C Commerce Production

Target (Destination):

Cybersource

Type:

Synchronous

Content:

Authorization request

Trigger:

Proceeding to payment step in checkout

Volume and Frequency:

Ad hoc

Per checkout transaction

Source Data Format:

HTML POST


Target Data Format:

HTTP redirect to success page

Mapping: How can data be mapped between source and target system formats?



Transport:

HSSPS



Security and Administration:

Secured by authentication with form POST. Infrastructure ensures encryption. Transports PII.


Failover and Monitoring:

Synchronous errors returned by Cybersource, including authorization failure, result in an error page. The shopper must retry by going through checkout.

Asynchronous failures handled by PayPal

Data Reconciliation: 

N/A


Open Issues:

Service level agreement is not available yet. 

Additional Information:

Required credentials from Cybersource to ensure real payments are not processed. Supplied by Cybersource LINK cartridge



Provide a link to the ISDs in your technical specification or include them in the document. Include these details.

  • Integration description
  • Code change details
  • Vendor details
  • Site preference
  • Input/output details
  • Sample request response

Key Customizations

Add details on key customization such as these to the technical specification.

  • Backend: Does the merchant want to link to or transfer data in a unique way to or from a backend system?
  • Frontend: Does the merchant want to support unique client devices?
  • Business Manager: Does the merchant want to add customizations to their Business Manager interface?

Plan for Growth

The implementation story doesn’t end here. As soon as (and maybe before) a site goes live, the merchant is already planning some changes. That means you need to:

  • Identify business expansion plans that might translate into new requirements.
  • Determine key performance indicators (KPIs) and explain how the solution meets business requirements with them in mind.
  • Identify performance implications resulting from data and operating volumes.
  • Identify gaps in given requirements and propose workarounds/alternate solutions.
  • Analyze technical design trade-offs and assess risks.

Business Expansion

Think strategically about the merchant’s growth strategy. For example, a single site design should provide a growth path to multiple sites and represent the merchant’s key markets, regions, and so on. How do you suggest they handle multiple brands?

  • Can shoppers shop several brands with one checkout?
  • Can authenticated shoppers switch brands without a re-login?
  • Can campaigns and promotions work across brands to qualify in the same basket?

Multi-Site Rollout

What’s your approach for a multi-site rollout? Here are some options.

Approach

Details

One App

  • One code base shared for multiple brands and locale
  • Multiple configuration
  • Minimal customization effort due to reuse

RefApp

  • Core components are shared across all brands or countries
  • Get the core and logic and modify them per the needs of the new brand sites

Operating and Data Volume

Consider key metrics. Several key volumetrics have corresponding object quotas, while others have a caution threshold (log-only quota). Do you need API/object quota overrides? This might cause performance degradation.

Consider the performance impact of a combination of metrics, such as the number of product line items per basket and the number of active promotions.

Customizations

Consider customization complexity.

  • What’s the business type: B2C, B2B, or B2B2C?
  • Does the merchant require or have an OMS?
  • What about a headless implementation?
  • Are they considering a cross-cloud implementation, changes in shopper purchase patterns, or non-retail verticals such as customer self-service?

With all these bright shiny new features, you’re right back to the design phase.

Next Steps

In this unit, you learned how to create architecture and data flow diagrams. You took a closer look at import and export flows, learned how to document third-party integrations, and planned for the future. Next, document the security and test processes. 

Resources

Share your Trailhead feedback over on Salesforce Help.

We'd love to hear about your experience with Trailhead - you can now access the new feedback form anytime from the Salesforce Help site.

Learn More Continue to Share Feedback