13. Project Structure Configuration

As explained in Dimensions and Structures, the aim of MQC is to visualize project data in a structured way. You have to configure your project structure to gain the possibilities in grouping and aggregating for your data and quality.

A project structure can be configured by importing one or multiple project structure sources, in YAML, JSON or Excel format.

13.1. Importing Project Structure Sources

A Project Structure Source has to be imported by pressing the Add button in the Project Structures dialog (see Figure 13.1).

Figure 13.1 Import multiple Project Structure Sources

It is possible to import multiple Project Structure Sources, e.g. to separate the artifact configuration from the milestone configuration.

When adding a new Project Structure Source, the content is validated for consistency and, additionally, it is checked for conflicts against the already existing Project Structure configuration defined by the previously added sources.

All changes done via the Project Structures dialog will be applied to the project first after pressing the Update Project button.

MQC provides a default project structure if no Project Structure Source has been loaded. This default project structure is based on the imported data:

• imported artifacts are shown with their names as read from the data reports, except a proper artifact mapping pattern was added via the dialog (see Artifact Mapping Patterns)

• a default milestone period is used, which is starting from the date of the first imported data report and which goes until the date of the last imported data report

Note

If you do not have a proper Project Structure Source that can be adapted, you can export one of the currently imported Project Structure Sources (see Exporting Project Structure Sources) and use it as a template. This also works for the default project structure initially applied by MQC.

Please, check the Project Structure Source schema, to get an overview about all expected and optional parameters when writing Project Structure Sources in YAML format.

It is possible to reload or remove each Project Structure Source individually as well as all source files at once.

13.2. Exporting Project Structure Sources

In the Project Structures dialog MQC allows to export each Project Structure source file individually by pressing the Export button next to a Project Structure source in the list of source files (see Figure 13.1). This will directly export a Project Structure Source of the file type is was originally imported in.

If you would like to merge the Project Structure configurations from multiple imported sources into a single Project Structure Source, press the Export button next to Add at the top. This opens an additional Export dialog as shown in Figure 13.2. With this it is possible to select the relevant source files to be combined.

Additionally, this dialog provides the option to explicitly choose the file type of the export.

Figure 13.2 Export dialog for exporting multiple Project Structure sources

13.3. Configuration Details

13.3.1. Project Naming

MQC allows to define a dedicated project name and automatically assign all artifacts for which data is collected by data sources to the given project (Figure 13.3).

Listing 13.1 Define a Project Name ‘SDOACar’ in YAML

Name: ProjectStructure
Project: SDOACar

Figure 13.3 Define a Project Name ‘SDOACar’ in Excel using the “Project Artifact Structure” sheet

13.3.2. Project Milestone Structure

The Project Milestone configuration allows you to group your data according to the milestones (phases) defined for your project.

In MQC, imported data automatically is assigned to revisions based on the timestamp the data was collected. Multiple revisions are clustered and linked to a particular milestone according to the start date of each revision and the start and due dates defined for the milestones (see Figure 13.4).

Figure 13.4 Relationship between project, milestones and revisions

Therefore, milestones in MQC are rather treated as a period with a start and an end date (where the configured end date is exactly the date of the particular milestone of your project) and a milestone duration.

Listing 13.2 Definition of milestones with start date due date and duration in YAML

Milestones:
- Name: Model Unit Start
  StartDate: 2021-04-27
  DueDate: 2021-06-28
  Duration: 63
- Name: Model Unit Extension
  StartDate: 2021-06-29
  DueDate: 2021-08-16
  Duration: 49
- Name: Model Integration
  StartDate: 2021-08-17
  DueDate: 2021-09-27
  Duration: 42
- Name: Test Improvement
  StartDate: 2021-09-28
  DueDate: 2021-10-18
  Duration: 21

Figure 13.5 Definition of milestones with start date due date and duration in Excel using the “Project Milestone Structure” sheet

It is not necessary to specify each of these parameters MilestoneStartDate, MilestoneDueDate, and MilestoneDuration.

The standard way to define your milestones is specifying just a project start date, which is the start date of the first milestone phase, in combination with a duration for each milestone. It is also possible to define start and end date per milestone without duration.

MQC is able to calculate missing milestone configuration data based on the given parameters, whereas the following order is applied:

• the duration and a given due date is used to calculate a missing start date

• if no due date is given, the duration and a given start date is used to calculate the missing due date

• if neither start date nor due date is given for a certain milestone, the start date is calculated based on the due date of the previous milestone

As long as no milestone configuration was not added at all, a “Default Milestone” is used in MQC, lasting from the time stamp of the first imported data report until the time stamp of the last imported date report.

Note

A proper milestone configuration is essential when working with target values (see Target Values).

In case your project milestone configuration contains a milestone phase that does not fit to your imported data, e.g. there are more milestones defined than data available, you can chose if MQC should include these (empty) revisions into your project. By default MQC hides all empty revisions. Nevertheless it offers a functionality to display these configured (but empty) revisions for all artifacts and measures within this project. By clicking on the checkbox Revisions without data (to be found within the Settings section of the Configuration Panel on the left side) all revisions are visualized.

13.3.3. Artifact Structure

Once you have imported a Project Structure Source, all artifacts contained in the “Artifact Structure” configuration sheet are treated as expected for your project, which means data can be imported and quality can be calculated. It also means that data, which is not imported for expected artifacts, can be stated as missing.

If you do not expect any data for a particular artifact, this artifact has to be removed from the list.

Listing 13.3 Defining expected artifacts including artifact mappings, weights, structures, and context categories in YAML

ArtifactStructures:
- Name: Artifact Structure
  Path: Software.Teams.Components
Artifacts:
- Name: EV3Control_main
  Weight: 1
  Paths:
  - EV3Control_main
  - EV3Control_demo_ec
  - EV3Control_demo_ec/EV3Control
  Structures:
  - Path: Software.Teams.Components
    Value: SDOAC SW.Team F.Integration
- Name: ObstacleDetection
  Weight: 1
  ContextCategories:
  - MLC_CC
  Paths:
  - ObstacleDetection
  - EV3Control_demo_ec/VehicleManager/ObstacleDetection
  - ObstacleDetection_demo_ec
  - Obstacledetection_demo_ec
  - ObstacleDetection_demo_ec/ObstacleDetection
  Structures:
  - Path: Software.Teams.Components
    Value: SDOAC SW.Team F.Detection
- Name: GlobalPosition
  Weight: 1
  ContextCategories:
  - Global_CC
  Paths:
  - GlobalPosition
  - EV3Control_demo_ec/VehicleManager/VehicleControl/GlobalPosition
  - GlobalPosition_demo_ec
  - GlobalPosition_demo_ec/GlobalPosition
  Structures:
  - Path: Software.Teams.Components
    Value: SDOAC SW.Team P.Control

Figure 13.6 Defining expected artifacts including weights, structures, and context categories in Excel using the “Artifact Structure” sheet

For the explanation of Context Categories please refer to Assign Context Categories to Artifacts.

As described in Artifacts and Artifact Structure, structures are used to group artifacts hierarchically. Defining such groups of artifacts offers you the possibility to filter the visualized data accordingly, e.g. to just focus on artifacts belonging to a certain group as well as to aggregate quality according to these groups.

The excel format allows for as many structure levels as needed or none at all. These levels can be defined as columns with a column name beginning with “Structure”. (e.g. ‘StructureSoftware’ for a “Software” structure level or ‘StructureTeams’ for a “Teams” structure level). Structures defined within a Project Structure Source in the excel format, are automatically considered as one hierarchy, with the order of the columns defining the level (e.g. Software > Teams > Components).

Multiple hierarchies can only be added by using the YAML or JSON formats. By following the schema definition, the Structures have to be defined first. Each artifact can then be assigned to one or multiple hierarchies. These hierarchies can have a different amount of levels. When assigning a structure hierarchy to an artifact, a structure element has to be provided for each defined level.

Listing 13.4 Defining artifact structures and artifacts with structure assignments in YAML

ArtifactStructures:
- Name: Architecture
  Path: Software.Components
- Name: Responsibility
  Path: Companies.Devisions.Teams.Employees
- Name: Programming Language
  Path: Languages
Artifacts:
- Name: EV3Control
  Structures:
  - Path: Software.Components
    Value: SDOAC SW.Integration
  - Path: Companies.Devisions.Teams.Employees
    Value: Model Engineering Solutions GmbH.Development.Team F.Employee A
  - Path: Languages
    Value: Simulink
- Name: GlobalPosition
  Structures:
  - Path: Software.Components
    Value: SDOAC SW.Control
  - Path: Languages
    Value: Simulink
- Name: EV3Control_UI
  Structures:
  - Path: Software.Teams.Components
    Value: SDOAC SW.Team F.Integration
  - Path: Companies.Devisions.Teams.Employees
    Value: Model Engineering Solutions GmbH.Development.Team C.Employee B
  - Path: Languages
    Value: Javascript

13.3.4. Artifact Mapping

“Artifact Mapping” allows you to adapt artifact names as they are used by data sources to your needs. Especially if different data sources use different denominations for the same artifact, “Artifact Mapping” may be used to define a common artifact name. All imported measure values collected by the data sources are automatically assigned to the new artifact name.

Listing 13.5 Different artifact paths are mapped to a common artifact name in YAML

Artifacts:
- Name: ObstacleDetection
  Paths:
  - ObstacleDetection
  - EV3Control_demo_ec/VehicleManager/ObstacleDetection
  - ObstacleDetection_demo_ec
  - Obstacledetection_demo_ec
  - ObstacleDetection_demo_ec/ObstacleDetection

Figure 13.7 Different artifact paths are mapped to a common artifact name in Excel using the “Artifact Structure” sheet

In Excel, as shown in Figure 13.7, in the “ArtifactPaths” column of the “Artifact Structure” sheet, all artifact paths with same artifact name are listed separated by line break or comma characters.

Note

In case the same base measures were provided for different artifact paths for the same revision and are now mapped to a common artifact name, MQC only uses the most recent of these base measures to calculate quality for the artifact.

13.3.5. Artifact Weights

With artifact weights the user is able to define that some artifacts can have more influence than others within the same project. Hereby, individual artifact parameters can be adapted with regard to the user’s interpretation of their importance, reliability, etc. For example, in our example from the Quick Start Guide chapter the importance of one artifact has to be considered higher due to the fact of being the main model and therefore should also get a bigger influence when aggregating quality according to the defined structures.

Listing 13.6 Defining weights for expected artifacts in YAML

Artifacts:
- Name: EV3Control_main
  Weight: 3

Figure 13.8 Defining weights for artifacts, e.g. a weight of 3 for the main artifact, in Excel

The influence of different artifact weights can be seen in Figure 13.9, where the size of each row in the heatmap reflects the corresponding weight and aggregated quality differs compared to the one with equal weights as shown in Figure 13.10.

Figure 13.9 Quality Heatmap page showing a project with different Artifact “sizes” / weights

If no artifact weight is defined, MQC will assume equal “size” of all artifacts and assigns a default value of 1 to all listed elements, as shown in Figure 13.10.

Figure 13.10 Quality Heatmap page showing a project with equal Artifact “sizes” / weights