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
metadata: displayName: "MyBank back-end" 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
applicationTypefield in the YAML is equivalent to defining an environment variable named
applicationtypeas 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
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:
|Software Distribution Strategy||“NOT_DISTRIBUTED”, “NETWORK_SERVICE”, “DISTRIBUTED”|
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 reference, you can find the meaning of such fields detailed below:
The lifecycle phase identifiers have the following meaning:
||System lifecycle phase|
|INITIAL||Initial development (pre-production)|
|MAINTENANCE||Servicing and maintenance|
|EOL||End-of-life (in production but minimal maintenance)|
|DECOMMISSIONED||Decommissioned / Phased out (no longer in production)|
The target industry phase identifiers have the following meaning:
|ICD0500||Oil & Gas|
|ICD1750||Industrial Metals & Mining|
|ICD2350||Construction & Materials|
|ICD2710||Aerospace & Defense|
|ICD2730||Electronic & Electrical Equipment|
|ICD3350||Automobiles & Part|
|ICD3500||Food & Beverage|
|ICD3700||Personal & Household Goods|
|ICD5700||Travel & Leisure|
|ICD8630||Real Estate Investment & Services|
|ICD9530||Software & Computer Services|
|ICD9570||Technology hardware & equipment|
The deployment type identifiers have the following meaning:
|PUBLIC_FACING||A system that is accessible by users through the public internet|
|CONNECTED||A system that interacts with a public-facing system via the network. The system is not accessible via the public internet|
|INTERNAL||A system that can only be reached by users via VPN or the company intranet. The system has no interaction with public-facing systems|
|PHYSICAL||A system that can only be reached by users with access to a physical location. The system cannot be reached from an internal network and has no interaction with public-facing systems|
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.