Adding business context to a system using metadata

Adding business context to Sigrid makes it easier to interpret the results. For example, a below-market average maintainability rating of 2 stars might seem like a problem, but this depends entirely on the context. If the system is no longer actively maintained and will be decommissioned by the end of the year (i.e., its lifecycle phase is end-of-life, or EOL for short), such a rating might be perfectly acceptable. But if that system is new, uses modern technology, and is business critical, such a rating would be considered a red flag. In both cases the technical conclusion is identical, it’s the context that determines the urgency.

Regarding Objectives, see our Objectives page

This context information is called metadata in Sigrid. Adding metadata can be done in 4 different ways:

Option 1: Adding metadata in Sigrid

This is by far the simplest approach: in Sigrid, simply go to the system settings option in the menu and select the “metadata” option.

Note the screenshot only shows part of the metadata page. The full page contains options related to the context in which the system is being developed, such as Business criticality, Lifecycle phase, and Deployment type. All possible options can also be seen on the Sigrid API metadata end point page.

They can be set with a drop-down menu.

The “?” help buttons explain the meaning of the different types of settings.

Option 2: Using the Sigrid API to add metadata

The Sigrid API end point for metadata allows you to add metadata programmatically. This is less accessible than using the Sigrid user interface, but has the advantage that it can run automatically. This is typically used when you need to synchronize metadata from another system to Sigrid, and you want this to run in an automated way.

Option 3: Adding metadata from a YAML file in your repository

As an alternative to using the API, you can also create a YAML file called sigrid-metadata.yaml in the root of your repository. The contents of this file are then used to update the metadata when the analysis runs. This is similar to using the API, but allows you to manage your Sigrid metadata as part of the repository in your version control system.

The following examples shows an example of a sigrid-metadata.yaml file:

metadata:
  displayName: "MyBank back-end"
  externalDisplayName: "MyBank component"
  divisionName: "My division"
  teamNames:
    - "My Team"
  supplierNames:
    - "Supplier 1"
    - "Supplier 2"
  lifecyclePhase: EOL
  inProductionSince: 2012
  businessCriticality: HIGH
  targetIndustry: ICD9530
  deploymentType: PUBLIC_FACING
  applicationType: ANALYTICAL
  externalID: ab12345
  isDevelopmentOnly: false
  remark: "Some notes"

The Sigrid API documentation contains descriptions of the various fields. Note that the semantics are the same: only fields present in sigrid-metadata.yaml are updated, others are left as-is. For example, the following sigrid-metadata.yaml file would update the external ID and remove the current remark:

metadata:
  externalID: "ab12345"
  remark: null

The contents of the YAML file will be used to update the metadata whenever you publish your system to Sigrid. If you run Sigrid CI without publishing, i.e. when you run it for a branch or pull request, the metadata does not get updated. This ensures that publishing code and publishing metadata behave in a consistent way.

Option 4: Adding metadata via Sigrid CI parameters

Metadata can also be configured by passing the metadata values as parameters when running Sigrid CI. This will dynamically generate the YAML file from option 3, but does not require you to commit this YAML file to your repository.

• For all platforms, you can define environment variables to the Sigrid CI run. The name of the environment variables is the lowercase version of the metadata fields listed above. For example, defining the applicationType field in the YAML is equivalent to defining an environment variable named applicationtype as a Sigrid CI parameter.
• When using the Sigrid CI GitHub Action published to GitHub Marketplace, you can also provide these fields as input parameters instead of environment variables. The names are again lowercase, so the input parameter would be named applicationtype.

Note you can use the YAML file or environment variables, but not both.

System metadata fields and corresponding allowed values

The system metadata taxonomy used in Sigrid for adding business context to a system has a set of allowed values per field that need to match so that the context is correctly validated.

Each of the fields presented below can only assume a single value from the list of possible values shown:

Meaning of special values for metadata fields

While several of the fields shown in the table above have self-evident values, some do not. As a reference, you can find the meaning of such fields detailed below:

Additional metadata fields

Besides the fields shown above, there is support for several additional fields to enrich the metadata of a given system. These additional fields are free-text fields, in the sense that their values are not part of a specific set of values. However, there are some restrictions on the possible set of values for each of the fields, which are detailed in the table below:

Contact and support

Feel free to contact SIG’s support department for any questions or issues you may have after reading this document, or when using Sigrid or Sigrid CI. Users in Europe can also contact us by phone at +31 20 314 0953.