Solution Design Guidelines

This section describes how we document projects in the Solution Design, aka SD.

The goal of the solution design is:

1. It allows us to quickly understand the setup of client platform, e.g. when there is a support request after months of silence, or when a new team member starts working on a project

2. It provides clients with a single PDF file containing the core tech documentation about their setup.

The solution design is written in English. The solution designs can be found in the client documentation under the respective client folders.

The solution design always documents the current state of the solution. This is distinct from the description in the planio order (see Create Order). The order describes the incremental changes needed for a client, given what he already has. See also Transaction vs Positions.

Structure

The solution design contains at least 3 files:
- organization.md,
- solution-overview.md,
- and one file for each perspective, e.g. project.md.

The files contain these sections:

• Organization
  • Introduction
  • Key People
• Solution Overview
  • Background
  • Data Sources
  • Data Lineage
  • Perspectives
  • Workspaces
  • Semantic Models
  • Reports
• For each Perspective
  • Introduction
  • Entities
  • Processes
  • Semantic Model
  • Reports
  • KPIs

The following sections describe the contents of each of the three files of the solution design.

Organization

Introduction

This is an introduction to the company. We describe:

• Activities
• Company Structure
• Divisions
• Legal Entities

Key People

These are bullet point lists with key people both at the client and with pwrp.

Solution Overview

Background

A short introduction to the different artifacts we have built for the client.

Data Sources

Here, we describe the source systems, such as:

• ERP and ERP modules
• CRM
• Excel

Again, a table is good enough:

Example

Source	System	Version	Access	Refresh	Other Remarks
Business Central	On prem	On prem, 21.0	Via HCM	Daily, some tables are incremental	This is managed by Christiaens
Invoice Line History	Excel on Teams		Via Power BI Connector	Daily	Contains the legacy INVOICE_LINE
Client History	Excel on Teams		"	"	Contains the legacy CLIENT

Data Lineage

Data lineage refers to the process of understanding, recording, and visualizing the journey of data as it travels from its source to its destination.

A brief overview of:

• the data sources

• the overall lineage

Example

graph LR

   BC[fa:fa-cloud BC]
   ILH[fa:fa-file-excel Invoice Line History]
   CH[fa:fa-file-excel Client History]

   BS[fa:fa-folder Blob Storage]
   DWH[fa:fa-database DWH<br>SQL Server]

   AF((fa:fa-chevron-circle-right<br>Azure<br>Function))
   ADF((fa:fa-chevron-circle-right<br>Azure<br>Data<br>Factory))
    SMS((fa:fa-star-of-life<br>Semantic<br>Model<br>Sales))
   SML((fa:fa-star-of-life<br>Semantic<br>Model<br>Stock))
    RS1(fa:fa-chart-pie Sales<br>Report)
   RS2(fa:fa-chart-pie Supplier<br>Report)

   PDFS(fa:fa-file Stock<br>PDF)
   RL(fa:fa-chart-pie Stock<br>Report)

   ILH-->BS
   CH-->BS

    BC-->AF-->ADF

   BS-->ADF-->DWH

   DWH-->SMS
   DWH-->SML

    SMS-->RS1
   SMS-->RS2
   SMS-->PDFS

    SML-->RL

    style DWH fill:#007fff
    style BS fill:#007fff
   style AF fill:#007fff
   style ADF fill:#007fff
    style SMS fill:#FFD700,color:#000
   style SML fill:#FFD700,color:#000
    style RS1 fill:#FFD700,color:#000
   style RS2 fill:#FFD700,color:#000

   style PDFS fill:red,color:#fff
   style RL fill:#FFD700,color:#000

Legend

graph LR

    ILH[fa:fa-file-excel Database/Storage/File]
    AF((fa:fa-chevron-circle-right Process))
    RL(fa:fa-chart-pie Report)

    style Azure fill:#007fff
    style PowerBI fill:#FFD700,color:#fff
    style PDFS fill:red,color:#fff

Again, don't overdo it. A simple overview is worth more than a super-detailed picture that is out of date.

The directions of the Arrows depict flow of data.

Perspectives

A table containing the perspectives.

Example

Perspective	KPQ
Project	Which projects are profitable?

Entities

This is a simple table of entities that are used for this perspective.

Example

Entity	System	Description	Count
COUNTERPARTY	BC	Counterparties are both clients and suppliers. They are discriminated by the Type flag	3700
ARTICLE	BC	Articles have a SKU code which identifies them. A challenge is that articles are replaced by newer models, and then we would like to report on a consolidated basis.	1000, plus 2000 historic
PRICE_LIST	BC	Price Lists are virtual objects that are combined by business logic from a variety of sources.
OFFER	BC	There is no sale without an offer. Offers have multiple versions.
ORDER	BC	Each Order is linked to an Offer version.
INVOICE	BC	Typically, there is a single invoice per Order, but there are exceptions. Sometimes, there are multiple invoices per order. Sometimes, an invoice is sent on multiple orders.	~15k INVOICE_LINES/mth
CHANNEL	BC	A channel is similar to a distributor, but not exactly the same thing. They are modelled as financial dimensions in BC.

Many entities are typically appearing in multiple perspectives. For this reason, we provide a single table for all perspectives.

The terms we use are in the client's language, both in the sense of EN, NL, or DE, but also in the sense of using the client's terminology.

One goal of this is precisely to understand the client

• does he call it Item or Article or Product?

• are clients and suppliers separate, or are they all together in a single counterparty table?

• does he work with work orders?

• etc.

Workspaces

A table containing the workspaces and who is using them.

Example

Workspace	Users	Access
Project Managers	Project Managers, e.g. Philipp	Users added to WS individually
Accounting	Accounting, e.g. Manuel	AD Group Accounting

Semantic Models

A table containing all the semantic models.

Example

Workspace	Description	Access
Operations	Operations stuff, e.g. Isabelle	Isabelle
OperationsEmbedded	Embed Capacity Workspace for the paginated timelog run

Files

A table containing the pbix and rdl files.

Example

File Name	Workspace	Description
time_reporting.pbix	Operations
pax8 dashboard.pbix	Operations

For Each Perspective

Introduction

This is a brief description of the Perspective, specifically

• Who are the stakeholders

• Why is this important

• What are we trying to achieve

Perspectives describe how we look at the data, who is addressed with the reports.

Often, a perspective is a view on the business by a specific team (e.g. sales), a stakeholder (e.g. directors) or from a certain angle (e.g. finance).

Examples of perspectives are:

• Sales
• Finance
• HR
• Clients

There is typically one Workspace in PBIS per perspective. Often, we have a Semantic Model per perspective, but sometimes the same Semantic Model is shared by multiple reports on different perspectives.

Below, we will have one section per perspective, so this is just a very brief overview.

Processes

Here, we describe (on a very high level) the business processes relevant for this perspective.

The typical methodology we use is a bullet list. Pay attention to highlight the Actors, the Entities and the Systems.

We use the following formatting:

• The Actor is bold

• The ENTITY is all-caps

• The System is italic

Sometimes, you may want to use an enhanced sequence diagram for visualisation, but usually this takes too much time.

Example

1. The Sales Agent signs the DEAL in Sales Force
2. The basic PROJECT parameters are synced to Business Central
3. In the weekly collab meeting, the PROJECT is assigned to a Project Manager
4. etc.

Tip

Keep it short!

Semantic Model

The Semantic Model (formerly called ADM, analytic data model) has different meanings. What we mean here is essentially the Star Schema.

Again, we keep it simple and define only the key attributes.

If there exists a standard Semantic Model that is documented, refer to it and highlight differences.

Again, we use Mermaid to document.

See also Development Guidelines for naming conventions.

Example

erDiagram
    FactAmount {
       id TransactionNumber
       eur Amount "signed amount (+/-)"
   }

   DimCalendar {
       date Date
       etc etc
   }

   DimAccount {
       int AccountCode "3402"
       txt AccountName
       txt etc "Add any level of groups, categories, etc."
   }

    DimRealisationType {
       code RealisationTypeCode "R, P"
       txt RealisationTypeName "Realised, Planned"
   }

   DimAccountingType {
       code AccountingTypeCode "AC, AL"
       txt AccountingTypeName "Accounting, Allocation"
   }

   DimDivision {
       code DivisionCode
       txt Divisionname
   }

   DimCompany {
       code CompanyCode
       txt CompanyName
   }





    DimCalendar ||--o{ FactAmount: refs
   DimAccount ||--o{ FactAmount: refs
   DimRealisationType ||--o{ FactAmount: refs
   DimAccountingType ||--o{ FactAmount: ref
   DimDivision ||--o{ FactAmount: ref
   DimCompany ||--o{ FactAmount: ref

KPIs

Here, we define the formulas used to calculate values.

This is hard, for various reasons:

• it is difficult to find the right level of detail
• it is difficult to formalise time, lags, etc

You will find some help and guidance in the Theory section, specifically:

1. variables

2. departments/delivery/theory/kpis

3. notation

4. sd-cheat-sheet

Important

While this is hard, it is also very important.
To make things easier, it is crucial to follow some standards.
The two most important standards are:

• Use the variable names as defined in sd-cheat-sheet
• Use the standard notation with Latex formulas: latex