CMS - Configuring the Background Facts upload file

Configuring the Background Facts upload file

Optionally, you can upload external data that will enrich the content of the CAST Health Dashboard and also the legacy CAST Engineering Dashboard. External data is either a Background Fact, or a Business Value Metric. This can be done BEFORE you generate a snapshot, or AFTER you generate a snapshot.

Background Facts can provide additional information in a single interface that is not based on source code analysis but that can advantageously be cross-referenced with quality and quantity information. You can declare new and update existing Background Facts (e.g., set up the unit in which Effort is uploaded, set up the currency of Cost information). These metrics are numerical values and they are attached to Modules only. To determine the Background Fact value of an Application, the dashboard will display the sum total of all contained Modules.

Background Facts (when uploaded) are displayed as follows:

• In the CAST Health Dashboard, in a dedicated tile
• In the legacy CAST Engineering Dashboard, in the dedicated Assessment Team Level view (see FRAME_PORTAL_ORGANISATION_VIEW - Assessment - Team Level). Effort and Cost metrics can also been seen in the Compare Versions view (see FRAME_PORTAL_CONTENT_EVOLUTION - Compare Versions).
• In the CAST Management Studio, Background Fact metrics are visible in the Assessment Model editor:

Note that:

- Business Value metrics (66061) can also be used to generate "business value" maps in the legacy CAST Engineering Dashboard and also for display as a simple value in the BackgroundFactsResults tile in the CAST Health Dashboard). By default, the dashboards use a default value of '1'. This metric is a free numerical value and it is attached to Modules only. To determine the business value of a System or an Application, the dashboards retrieve the maximum value of all contained Modules     - When declaring Business Value metrics (66061), you MUST ensure that the value is set to one of the following values, failure to do so will result in errors in the dashboard.
        - Low Business Value = 1 or 1.5
        - Moderate Business Value = 2 or 2.5
        - High Business Value = 3 or 3.5
        - Extreme Business Value = 4

- When using the "BEFORE" legacy upload method using the XML file, it is possible to upload some structural information about the corporate organization (Teams/Developers etc.) and map modules and metrics against this information - this information is then only visible in the legacy CAST Engineering Dashboard. This structural information cannot be configured with the "AFTER" upload method using the CAST RestAPI interface - instead only values for Background Facts can be configured.

Upload process

The upload of external data can be achieved in two ways:

• AFTER a snapshot is generated: this is the most flexible method - you can upload your Background Facts data at any time AFTER the snapshot has been generated using the CAST RestAPI interface. CAST recommends that you use this method. Note however, that it is NOT possible to configure structural information about the corporate organization (Teams/Developers etc.) and map modules and metrics against this information with this upload method - instead only values for Background Facts can be configured. If you still need to upload structural data for viewing in the legacy CAST Engineering Dashboard, please use the "BEFORE" method instead.
• BEFORE the snapshot is generated: declaration of an XML file containing the Background Facts configuration. This XML file is then taken into when the snapshot is generated. You need to keep this file up to date before each snapshot generation process (this is the legacy upload method).

AFTER a snapshot is generated

Please see http://doc.castsoftware.com and search for "Background Facts" in the most recent documentation set for more information about using the CAST RestAPI interface to upload Background Facts.

BEFORE a snapshot is generated

This legacy method requires you to declare (in the CAST Management Studio) an XML file containing the Background Facts configuration. This XML file is then taken into when a snapshot is generated. You need to keep this file up to date before each snapshot generation process.

Note

• Note that from AIP Core 8.3.46, the Background Facts upload field will be ignored during an analysis. You should instead use the "AFTER a snapshot is generated" option.

XML file declaration

The name and location of the XML file to upload is defined in the Dashboard Service editor in the CAST Management Studio:

• Enter the full name of the XML file in the dedicated Background Facts upload file section - CAST suggests using background_facts.xml, but you are free to choose any name you prefer.
• The file will be taken into account when the next snapshot is generated.

The Background Facts upload file is validated automatically by the CAST Management Studio when the Snapshot is generated. This is because it has to take into account Modules (i.e. modules called "<Application name> full content") that may be generated automatically (and that are not yet known to the CAST Management Studio) during the first stages of the Snapshot generation process.

When a Background Facts upload file is uploaded all future snapshot generation processes will automatically include the Background Facts information.

XML file structure

The XML file is composed of several types of information. Each block of information must be presented in the order listed below:

• Module mapping
• Organization links
• Module assignment
• Business Value and Background Facts

Examples are given below:

• Module mapping information, i.e., the identification of Modules for which to upload information and Organizational information, i.e., development entities to which the software components will be assigned:

• Organization links information, i.e., the inclusion relations between development entities:

• Module assignment information, i.e., the link between Developers and the Modules they are responsible for:

• Business Value and Background Facts for each Module:

Principles

• The organization and the module mapping information use object IDs which are unique in the upload file; there is no need to be consistent with object IDs in the Dashboard Service.
• ID's must be unique and must remain identical over time (one object must retain the same ID in all snapshots)
• When declaring Modules, the ID must only be unique within the Background Facts upload file (a module does not necessarily have to have the same ID as used in the Dashboard Service). However, the type and the name MUST be the same as those used for the modules that have are already present in the Dashboard Service.
• The module mapping information is used to identify existing modules; subsequent references to these modules in the upload file only require the file-wide module ID. E.g.: "MEUDON full content" is mapped with the ID "10" and is referenced through this ID in other blocks of the upload file.
• The organization information is used both to identify development entities for subsequent references and to create an object in the Dashboard Service. E.g.: "Research and Dev" organization with object ID "1" is created in the Dashboard Service and is referenced to through this ID in other blocks of the upload file.
• The organization link and module assignment information are used to create new links in the Dashboard Service between the object identified by its ID in the PREVIOUS_OBJECT_ID node and the object identified by its ID in the NEXT_OBJECT_ID node. When Background Facts are involved, the link type is '4'. The links are valid between Organization nodes and Team nodes, between Team nodes and Developer nodes, and between Developer nodes and Module nodes.
• The metric information is used to fill the Dashboard Service with a given value - provided by the METRIC_NUM_VALUE node - for the selected object and the selected metric respectively provided by the OBJECT_ID and METRIC_ID nodes.
• Information is optional. You can omit the Background Facts part, the Business Value part, or both.
• Within the Background Facts, you are allowed to skip some Productivity Metrics and some Modules.
• Within the Business Value part, you are allowed to skip some Modules however, this will impact the maps as follows: it will underestimate the Functional Weight displayed as the bubble size.
• Please avoid alternating between <DSS_IN_LINKS> and <DSS_IN_OBJECTS> tags - create the <DSS_IN_OBJECTS> first, then create the <DSS_IN_LINKS> as outlined below.

- The organization of the development teams in the company (this is defined in the Background Facts upload file):

• Organizations that contain (type 20100):
  •  Teams that contain (type 20101):
    •  Developers that create (type 20102)
      • Modules (type 20000) - i.e. User Defined Modules and those created automatically during the Snapshot generation process

XML file creation

The structure of the file must use the following format:

Objects (Organizations, Teams, Developers and Modules)

• Objects are declared within the <DSS_IN_OBJECTS> tags
• <OBJECT_NAME>, <OBJECT_TYPE_ID>, <OBJECT_ID> and <OBJECT_FULL_NAME> tags are all compulsory. You can also include optional <OBJECT_DESCRIPTION> tags to help distinguish the object.
• The <OBJECT_NAME> tag must use the same name (case sensitive and space sensitive) as is stored in the Analysis Service.
• The <OBJECT_TYPE_ID> tag must contain a specific ID for each different type of object. These are listed above in the Defining Productivity section.
• The <OBJECT_ID> tag must contain a unique ID for each object defined in the XML file. This ID is local to the XML file.

Links (for linking developers to modules and teams, teams to the organization and modules to metrics etc.)

• Objects are declared within the <DSS_IN_LINKS> tags
• <LINK_TYPE_ID>, <PREVIOUS_OBJECT_ID> and <NEXT_OBJECT_ID> tags are all compulsory.
• The <LINK_TYPE_ID> tag must always contain the type 4.
• The <PREVIOUS_OBJECT_ID> and <NEXT_OBJECT_ID> tags refer to the objects that you want to link.

Metrics (for defining which metrics you want to use to measure productivity for your organization and which metrics will be mapped to which modules)

• Objects are declared within the <DSS_IN_METRIC_RESULTS> tags
• <METRIC_ID>, <METRIC_NUM_VALUE> and <OBJECT_ID> tags are all compulsory.
• The <METRIC_ID> tag must always contain a specific ID for each different type of metric. These are listed above in the Defining Productivity section.
• The <METRIC_NUM_VALUE> tag must contain a value that will define the weight of the metric.
• The <OBJECT_ID tag defines which module the metric and its weight will be applied to

The only items that must be defined in are the Modules. You can then include any other items you want, i.e. Organization, Metrics and Links.

The organization of the development teams in the company should be defined using the following IDs:

• Organizations that contain (type 20100):
  •  Teams that contain (type 20101):
    •  Developers that create (type 20102)
      • Modules (type 20000) - i.e. User Defined Modules and those created automatically during the Snapshot generation process

To create an XML based upload file for integrating external data into the snapshot generation process, create a new empty XML file and enter the following blocks of code:

Step 1 - Header and main DATA block

<?xml version="1.0" encoding="iso-8859-1" ?><DATA model="Central Model" version="1.0.0.17" scope="Productivity"></DATA>

Step 2 - Module mapping

You now need to map the Modules you want to include with your own set of IDs - these IDs are fully independent of the Module IDs defined in the CAST Analysis and Dashboard Services. The <OBJECT_TYPE_NODE> is always 20000 for modules. Add the following blocks within the DATA root node:

<DSS_IN_OBJECTS><OBJECT_NAME>Demo-Java Analyzer</OBJECT_NAME><OBJECT_TYPE_ID>20000</OBJECT_TYPE_ID><OBJECT_ID>10</OBJECT_ID></DSS_IN_OBJECTS><DSS_IN_OBJECTS><OBJECT_NAME>Demo-C+\+ Analyzer</OBJECT_NAME><OBJECT_TYPE_ID>20000</OBJECT_TYPE_ID><OBJECT_ID>11</OBJECT_ID></DSS_IN_OBJECTS><DSS_IN_OBJECTS><OBJECT_NAME>CWMM-T-SQL Analyzer</OBJECT_NAME><OBJECT_TYPE_ID>20000</OBJECT_TYPE_ID><OBJECT_ID>12</OBJECT_ID></DSS_IN_OBJECTS>

These blocks of code:

• Map the module called "Demo-Java Analyzer" of type "20000" with the ID "10".
• Map the module called "Demo-C++ Analyzer" of type "20000" with the ID "11".
• Map the module called "CWMM-T-SQL Analyzer" of type "20000" with the ID "12".

Note that:

- IDs must be unique (i.e.: there must be no other identical IDs in the XML file), but there is no need to generate an initial snapshot as the ID scope is limited to the upload XML file. The ID does not need to be consistent with the IDs used in the Analysis or Dashboard Services.

- Names used must be identical to the names declared in the CAST Management Studio - as such, you need to define the  modules in the CAST Management Studio before you create this XML file.

- Types must be identical to the types displayed in the Assessment Model (for example, mapping a DATABASE with a SCHEMA will fail).

Step 3 - Declaring a Business Value for each module (optional)

Add the following block to the DATA root node:

<DSS_IN_METRIC_RESULTS><METRIC_ID>66061</METRIC_ID><METRIC_NUM_VALUE>4</METRIC_NUM_VALUE><OBJECT_ID>10</OBJECT_ID></DSS_IN_METRIC_RESULTS><DSS_IN_METRIC_RESULTS><METRIC_ID>66061</METRIC_ID><METRIC_NUM_VALUE>4</METRIC_NUM_VALUE><OBJECT_ID>11</OBJECT_ID></DSS_IN_METRIC_RESULTS><DSS_IN_METRIC_RESULTS><METRIC_ID>66061</METRIC_ID><METRIC_NUM_VALUE>3</METRIC_NUM_VALUE><OBJECT_ID>12</OBJECT_ID></DSS_IN_METRIC_RESULTS>

These blocks of code:

• Set the metric value to "4" for the metric "66061" (i.e.: the Business Value as defined in the Assessment Model) and for the object "10" (i.e. the module Demo-Java Analyzer" as defined in step 2) for the snapshot generation process.
• Set the metric value to "4" for the metric "66061" (i.e.: the Business Value as defined in the Assessment Model) and for the object "11" (i.e. the module "Demo-C++ Analyzer" as defined in step 2) for the snapshot generation process.
• Set the metric value to "3" for the metric "66061" (i.e.: the Business Value as defined in the Assessment Model) and for the object "12" (i.e. the module "CWMM-T-SQL Analyzer" as defined in step 2) for the snapshot generation process.

Notes 1) Object IDs must be the same IDs of the modules mapped in step 2
2) The metric value must be a number 3) To avoid "gaps" in the dashboard display, set values for all mapped modules (or set no values at all)
4) Business Value can evolve from one snapshot to the next 5) The Application Business Value is the max value of Module Business Values 6) The System Business Value is the max value of Application Business Values 7) When declaring Business Value metrics (66061), you MUST ensure that the <METRIC_NUM_VALUE> is set to one of the following values:

    - Low Business Value = 1 or 1.5
    - Moderate Business Value = 2 or 2.5
    - High Business Value = 3 or 3.5
    - Extreme Business Value = 4

Failure to do so will result in errors in the legacy CAST Engineering Dashboard.

Step 4 - Declaring the development organization (optional)

Add the following block to the DATA root node:

<DSS_IN_OBJECTS><OBJECT_NAME>Research and Dev</OBJECT_NAME><OBJECT_TYPE_ID>20100</OBJECT_TYPE_ID><OBJECT_ID>1</OBJECT_ID><OBJECT_DESCRIPTION>Main dev team</OBJECT_DESCRIPTION><OBJECT_FULL_NAME>Research and Dev</OBJECT_FULL_NAME></DSS_IN_OBJECTS><DSS_IN_OBJECTS><OBJECT_NAME>Paris</OBJECT_NAME><OBJECT_TYPE_ID>20101</OBJECT_TYPE_ID><OBJECT_ID>2</OBJECT_ID><OBJECT_DESCRIPTION>Paris team</OBJECT_DESCRIPTION><OBJECT_FULL_NAME>Paris</OBJECT_FULL_NAME></DSS_IN_OBJECTS><DSS_IN_OBJECTS><OBJECT_NAME>London</OBJECT_NAME><OBJECT_TYPE_ID>20101</OBJECT_TYPE_ID><OBJECT_ID>3</OBJECT_ID><OBJECT_DESCRIPTION>London team</OBJECT_DESCRIPTION><OBJECT_FULL_NAME>London</OBJECT_FULL_NAME></DSS_IN_OBJECTS><DSS_IN_OBJECTS><OBJECT_NAME>John</OBJECT_NAME><OBJECT_TYPE_ID>20102</OBJECT_TYPE_ID><OBJECT_ID>4</OBJECT_ID><OBJECT_DESCRIPTION>John Smith</OBJECT_DESCRIPTION><OBJECT_FULL_NAME>John Smith</OBJECT_FULL_NAME></DSS_IN_OBJECTS><DSS_IN_OBJECTS><OBJECT_NAME>David</OBJECT_NAME><OBJECT_TYPE_ID>20102</OBJECT_TYPE_ID><OBJECT_ID>5</OBJECT_ID><OBJECT_DESCRIPTION>David White</OBJECT_DESCRIPTION><OBJECT_FULL_NAME>David White</OBJECT_FULL_NAME></DSS_IN_OBJECTS><DSS_IN_OBJECTS><OBJECT_NAME>Mark</OBJECT_NAME><OBJECT_TYPE_ID>20102</OBJECT_TYPE_ID><OBJECT_ID>6</OBJECT_ID><OBJECT_DESCRIPTION>Mark Davies</OBJECT_DESCRIPTION><OBJECT_FULL_NAME>Mark Davies</OBJECT_FULL_NAME></DSS_IN_OBJECTS>

These blocks of code:

• Create an object called "Research and Development" of type "20100" (i.e. an "Organization" type), map it to ID "1" and use the description "Main dev team".
• Create an object called "Paris" of type "20101" (i.e. a "Team" type), map it to ID "2" and use the description "Paris team".
• Create an object called "London" of type "20101" (i.e. a "Team" type), map it to ID "3" and use the description "London team".
• Create an object called "John" of type "20102" (i.e. a "Developer" type), map it to ID "4" and use the description "John Smith".
• Create an object called "David" of type "20102" (i.e. a "Developer" type), map it to ID "5" and use the description "David White".
• Create an object called "Mark" of type "20102" (i.e. a "Developer" type), map it to ID "6" and use the description "Mark Davies".

Then add the following block to the DATA root node:

<DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>1</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>2</NEXT_OBJECT_ID></DSS_IN_LINKS><DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>1</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>3</NEXT_OBJECT_ID></DSS_IN_LINKS><DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>2</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>4</NEXT_OBJECT_ID></DSS_IN_LINKS><DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>2</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>5</NEXT_OBJECT_ID></DSS_IN_LINKS><DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>2</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>6</NEXT_OBJECT_ID></DSS_IN_LINKS>

These blocks of code:

• Create a link from object "1" (i.e. "Research and Dev") to object "2" (i.e. "Paris team") of type "4" (reserved for these kind of links).
• Create a link from object "1" (i.e. "Research and Dev") to object "3" (i.e. "London team") of type "4" (reserved for these kind of links).
• Create a link from object "2" (i.e. "Paris team") to object "4" (i.e. "John Smith") of type "4" (reserved for these kind of links).
• Create a link from object "2" (i.e. "Paris team") to object "5" (i.e. "David White") of type "4" (reserved for these kind of links).
• Create a link from object "2" (i.e. "Paris team") to object "6" (i.e. "Mark Davies") of type "4" (reserved for these kind of links).

In other words:

• Assign teams "2" and "3" to organization "1"
• Assign developers "4", "5" and "6" to team "2"

Note that:

- IDs must be unique (i.e.: there must be no other identical IDs in the XML file) and they must not be the same as any module ID.
- All levels are required: at least one organization, containing one team, containing one developer - Be careful with link direction, links must go from the upper levels to the lower levels.

Step 5 - Mapping developers from the development organization to the modules (using file-defined module IDs and file-defined developer IDs) (optional)

Add the following block to the DATA root node:

<DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>4</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>10</NEXT_OBJECT_ID></DSS_IN_LINKS><DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>5</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>11</NEXT_OBJECT_ID></DSS_IN_LINKS><DSS_IN_LINKS><LINK_TYPE_ID>4</LINK_TYPE_ID><PREVIOUS_OBJECT_ID>6</PREVIOUS_OBJECT_ID><NEXT_OBJECT_ID>12</NEXT_OBJECT_ID></DSS_IN_LINKS>

These blocks of code:

• Create a link from object "4" (i.e. "John Smith") to object "10" (i.e. for the module "Demo-Java Analyzer" as defined in step 2) of type "4" (reserved for these kind of links).
• Create a link from object "5" (i.e. "David White") to object "11" (i.e. for the module "Demo-C++ Analyzer" as defined in step 2) of type "4" (reserved for these kind of links).
• Create a link from object "6" (i.e. "Mark Davies") to object "12" (i.e. for the module "CWMM-T-SQL Analyzer" as defined in step 2) of type "4" (reserved for these kind of links).

In other words:

• Assign modules "10" to developer "4", module "11" to developer "5" and module "12" to developer "6"

Note that:

- Be careful with link direction: from the developer to the module.
- Assign modules only to developers only: do not create links between systems and developers nor between modules and teams.
- Assign modules to one single developer (the one responsible for the module): do not create links from one module to two developers.

Step 6 - Declaring productivity metric values for modules (optional)

Add the following block to the DATA root node:

<!-- Metrics : 66001 : Effort --><DSS_IN_METRIC_RESULTS><METRIC_ID>66001</METRIC_ID><METRIC_NUM_VALUE>10.5</METRIC_NUM_VALUE><OBJECT_ID>10</OBJECT_ID></DSS_IN_METRIC_RESULTS><DSS_IN_METRIC_RESULTS><METRIC_ID>66001</METRIC_ID><METRIC_NUM_VALUE>20.6</METRIC_NUM_VALUE><OBJECT_ID>11</OBJECT_ID></DSS_IN_METRIC_RESULTS><DSS_IN_METRIC_RESULTS><METRIC_ID>66001</METRIC_ID><METRIC_NUM_VALUE>30.7</METRIC_NUM_VALUE><OBJECT_ID>12</OBJECT_ID></DSS_IN_METRIC_RESULTS><!-- Metrics : 66002 : Cost--><DSS_IN_METRIC_RESULTS><METRIC_ID>66002</METRIC_ID><METRIC_NUM_VALUE>400</METRIC_NUM_VALUE><OBJECT_ID>10</OBJECT_ID></DSS_IN_METRIC_RESULTS><DSS_IN_METRIC_RESULTS><METRIC_ID>66002</METRIC_ID><METRIC_NUM_VALUE>800</METRIC_NUM_VALUE><OBJECT_ID>11</OBJECT_ID></DSS_IN_METRIC_RESULTS><DSS_IN_METRIC_RESULTS><METRIC_ID>66002</METRIC_ID><METRIC_NUM_VALUE>1200</METRIC_NUM_VALUE><OBJECT_ID>12</OBJECT_ID></DSS_IN_METRIC_RESULTS>

These blocks of code:

• Set the metric value to "10.5" for the metric "66001" (i.e. "workload" as defined in the Assessment Model) and for object "10" (i.e. for the module "Demo-Java Analyzer" as defined in step 2) for the snapshot generation process
• Set the metric value to "20.6" for the metric "66001" (i.e. "workload" as defined in the Assessment Model) and for object "11" (i.e. for the module "Demo-C++ Analyzer" as defined in step 2) for the snapshot generation process
• Set the metric value to "30.7" for the metric "66001" (i.e. "workload" as defined in the Assessment Model) and for object "12" (i.e. for the module "CWMM-T-SQL Analyzer" as defined in step 2) for the snapshot generation process
• Set the metric value to "400" for the metric "66002" (i.e. "cost" as defined in the Assessment Model) and for object "10" (i.e. for the module "Demo-Java Analyzer" as defined in step 2) for the snapshot generation process
• Set the metric value to "800" for the metric "66002" (i.e. "cost" as defined in the Assessment Model) and for object "11" (i.e. for the module "Demo-C++ Analyzer" as defined in step 2) for the snapshot generation process
• Set the metric value to "1200" for the metric "66002" (i.e. "cost" as defined in the Assessment Model) and for object "12" (i.e. for the module "CWMM-T-SQL Analyzer" as defined in step 2) for the snapshot generation process

In other words:

• Defines that "workload" associated to module "10" for the snapshot to be processed is "10.5"
• Defines that "workload" associated to module "11" for the snapshot to be processed is "20.6"
• Defines that "workload" associated to module "12" for the snapshot to be processed is "30.7"
• Defines that "cost" associated to module "10" for the snapshot to be processed is "400"
• Defines that "cost" associated to module "11" for the snapshot to be processed is "800"
• Defines that "cost" associated to module "12" for the snapshot to be processed is "1200"

Note that:

- Assign metric values only to modules.
- Modules and productivity metrics may be omitted (in this example, only two metrics are in use).
- Values must be numbers.

Upload file check

When the Snapshot Generation process is started in the CAST Management Studio, the declared upload file is checked for consistency - if it does not pass the check, the Snapshot Generation process will abort.