@backstage/plugin-tech-insights-backend-module-jsonfc

Tech Insights Backend JSON Rules engine fact checker module

This is an extension to module to tech-insights-backend plugin, which provides basic framework and functionality to implement tech insights within Backstage.

This module provides functionality to run checks against a json-rules-engine and provide boolean logic by simply building checks using JSON conditions.

Getting started

To add this FactChecker into your Tech Insights you need to install the module into your backend application:

# From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-tech-insights-backend-module-jsonfc

Add to the backend

backend.add(import('@backstage/plugin-tech-insights-backend-module-jsonfc'));

This setup requires checks to be provided using the config.

Add to the backend (old)

Modify the techInsights.ts file to contain a reference to the FactCheckers implementation.

+import { JsonRulesEngineFactCheckerFactory } from '@backstage/plugin-tech-insights-backend-module-jsonfc';

+const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({
+   checks: [],
+   logger: env.logger,
+}),

 const builder = buildTechInsightsContext({
   logger: env.logger,
   config: env.config,
   database: env.database,
   discovery: env.discovery,
   tokenManager: env.tokenManager,
   factRetrievers: [myFactRetrieverRegistration],
+  factCheckerFactory: myFactCheckerFactory
 });

By default, this implementation comes with an in-memory storage to store checks. You can inject an additional data store by adding an implementation of TechInsightCheckRegistry into the constructor options when creating a JsonRulesEngineFactCheckerFactory. That can be done as follows

 const myTechInsightCheckRegistry: TechInsightCheckRegistry<MyCheckType> = // snip
 const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({
   checks: [],
   logger: env.logger,
+  checkRegistry: myTechInsightCheckRegistry
 }),

Adding checks in code

Checks for this FactChecker are constructed as json-rules-engine compatible JSON rules. A check could look like the following for example:

import {
  JSON_RULE_ENGINE_CHECK_TYPE,
  TechInsightJsonRuleCheck,
} from '@backstage/plugin-tech-insights-backend-module-jsonfc';

export const exampleCheck: TechInsightJsonRuleCheck = {
  id: 'demodatacheck', // Unique identifier of this check
  name: 'demodatacheck', // A human readable name of this check to be displayed in the UI
  type: JSON_RULE_ENGINE_CHECK_TYPE, // Type identifier of the check. Used to run logic against, determine persistence option to use and render correct components on the UI
  description: 'A fact check for demoing purposes', // A description to be displayed in the UI
  factIds: ['documentation-number-factretriever'], // References to fact ids that this check uses. See documentation on FactRetrievers for more information on these
  rule: {
    // The actual rule
    conditions: {
      all: [
        // 2 options are available, all and any conditions.
        {
          fact: 'examplenumberfact', // Reference to an individual fact to check against
          operator: 'greaterThanInclusive', // Operator to use. See: https://github.com/CacheControl/json-rules-engine/blob/master/docs/rules.md#operators for more
          value: 2, // The threshold value that the fact must satisfy
        },
      ],
    },
  },
  successMetadata: {
    // Additional metadata to be returned if the check has passed
    link: 'https://link.to.some.information.com',
  },
  failureMetadata: {
    // Additional metadata to be returned if the check has failed
    link: 'https://sonar.mysonarqube.com/increasing-number-value',
  },
};

Adding checks in config

Example:

techInsights:
  factChecker:
    checks:
      groupOwnerCheck:
        type: json-rules-engine
        name: Group Owner Check
        description: Verifies that a group has been set as the spec.owner for this entity
        factIds:
          - entityOwnershipFactRetriever
        rule:
          conditions:
            all:
              - fact: hasGroupOwner
                operator: equal
                value: true

More than one factIds for a check.

When more than one is supplied, the requested fact MUST be present in at least one of the fact retrievers. The order of the fact retrievers defined in the factIds array has no bearing on the checks, the check will merge all facts from the various retrievers, and then check against latest fact .

Custom operators

json-rules-engine supports a limited number of built-in operators that can be used in conditions. You can add your own operators by adding them to the operators array in the JsonRulesEngineFactCheckerFactory constructor. For example:

+ import { Operator } from 'json-rules-engine';

const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({
   checks: [],
   logger: env.logger,
+  operators: [ new Operator("startsWith", (a, b) => a.startsWith(b) ]
})

And you can then use it in your checks like this:

...
rule: {
  conditions: {
    any: [
      {
        fact: 'version',
        operator: 'startsWith',
        value: '12',
      },
    ],
  },
}