Introduction

Optionally, you can upload external data that will enrich the content of the Health Dashboard and Engineering Dashboards. External data is either Background Facts, 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:

Note that:

  • Business Value metrics (66061) can also be used for display as a simple value in the Background Facts tile  in the CAST Engineering Dashboard and also for display as a simple value in the BackgroundFactsResults tile in the 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:

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.

AFTER a snapshot is generated

This method uses a dedicated Background Facts interface in the CAST RestAPI to upload data directly into either the Measurement Service database (for display in the Health Dashboard) or into the Dashboard Service database (for display in the CAST Engineering Dashboard). To get started you will need

Access the dedicated Background Facts CAST RestAPI interface

Use the following URL to access the CAST RestAPI interface dedicated to uploading Background Facts:

http://<server>:<port>/<webapp>/static/backgroundFact.html

When this page loads you will be presented with a login interface. Login with a user (whether static list or Active Directory) that has the ADMIN role:

When successfully authenticated, the following will be displayed enabling you to select the domain (i.e. database) to which you want to upload the data. The following image shows the default AAD and AED domains. You should ensure that you choose the correct domain:

When you have chosen a domain, you will then be prompted to choose an Application into which the Background Facts will be injected - these are Applications for which snapshot data already exists either in the Dashboard Service database or in the Measurement Service database:

When you have chosen an Application, you will then be prompted to choose a snapshot into which the Background Facts will be injected - these are historic snapshots for the selected Application:

On selecting a snapshot, you will then be shown the interface for inputting the Background Fact information:

Enter the Background Fact data using the interface

The interface provides the ability to inject Background Fact data based on the following parameters (which are described in the RestAPI Reference Documentation under the Health Results Resources section) separated by semi-colons:

By default, the interface will be populated automatically with default information giving a Business Value (metric 66061) of 1 to all Applications and all child Modules, as shown in this example giving a value of 1 to the Application "MEUDON" and the default full content module "MEUDON full content":

ADG Database;Application Name;Module Name;Metric Id;Result
v81_1130_central;MEUDON;;66061;1
v81_1130_central;MEUDON;MEUDON full content;66061;1

Please note that partial configurations (i.e. the configuration of a metric for an Application but not for any of its child Modules, or the configuration of a metric for one single Module, but not the parent Application nor any sibling Modules) are NOT authorised and you will receive an error as below. You must ALWAYS configure a Background Fact for an Application and ALL its child modules. You can give a default value of 1 if you do not need to set a specific value to some of the items, but you must always include the item in the configuration.

To correct the above error, the following configuration should be used (adding a configuration for the parent Application of the Module):

Optional parameters

The following parameters are optional:

When a parameter is optional, it can be omitted, however, you must ensure that the semi-colon denoting the boundary between the parameters is always included. In the following example, both the ADG Database and the Module Name parameters have been omitted:

ADG Database;Application Name;Module Name;Metric Id;Result
;MEUDON;;66061;1
;MEUDON;MEUDON full content;66061;10

Example

To add an "Effort" (metric 66001) Background Fact with a value of 20 to the "MEUDON full content" module and a value of 1 to the parent Application, while retaining the default Business Value of 1 for the parent Application and the module, add the following lines (lines 4 and 5):

ADG Database;Application Name;Module Name;Metric Id;Result
v81_1130_central;MEUDON;;66061;1
v81_1130_central;MEUDON;MEUDON full content;66061;1
v81_1130_central;MEUDON;;66001;1
v81_1130_central;MEUDON;MEUDON full content;66001;20

Save button

Once you have configured your Background Fact data, use the Save button to commit the configuration into the selected snapshot:

Refresh button

The Refresh button will retrieve the current Background Facts configuration direct from the selected snapshot and replace all previous configurations in the interface.

Get an Example button

The Get an Example button will retrieve an example from memory to help you configure the injection correctly.

Using Excel to edit the configuration

You can use Excel to help define your Background Facts data. This is particularly useful if you have a large number of Applications/Modules. Please see Using Excel in Health Dashboard tag and category management which explains the process for editing Tags and Categories for the Health Dashboard (the process is identical).

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 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 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) 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:

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 of the development teams in the company (this is defined in the Background Facts upload file):

XML file creation

Note that you can use the BackgroundFacts.xsd file to help you build a syntactically correct XML file.

The structure of the file must use the following format:

Objects (Organizations, Teams, Developers and Modules)

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

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

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:

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:

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:

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 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:

The <OBJECT_FULL_NAME> tag is compulsory.

The <OBJECT_DESCRIPTION> tag is optional. However, if you omit it, then the CAST Engineering Dashboard will display an error message in the description cell.

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:

In other words:

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:

In other words:

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:

In other words:

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.