The domain taxonomy, what the work is, apart from who does it.

A domain taxonomyDomain taxonomyThe list of business areas, their owners and the teams or services that do the work in each area. is the business view of the organisation, gathered in one workshop. It names the business domainsDomainA business area defined by the work it does, such as purchasing or customs. It may involve several teams, and one team may serve several areas., the person accountable for each, and the map cellsMapThe view of teams, services and their dependencies for the selected part of the organisation. Details appear beside the map. that serve it. A domain such as freight movement can be served by several teams, and a team can serve several domains. The taxonomy records the business view beside the team view from the org chart.

The taxonomy is a declared claim made by the business. NovusLens records it as the business stated it. It is not a system of record, and NovusLens does not curate it. Where the business and team views disagree, the disagreement is a findingFindingA difference in the records that needs a decision. It includes its sources and can describe a slow handoff, disputed fact or missing owner. for people to resolve.

What the taxonomy carries

Each domain has an id, an optional display name, an optional description, an optional accountable ownerAccountable ownerThe person recorded as answerable for a team, service or agent. NovusLens does not assume that this person is also the one who runs it day to day., and a list of cell ids. Each cell id is one of the team cells the org chart created, or another cell already in the map. Domains are business-level concepts, so a domain is not a team, a person or an infrastructure unit.

Docker commands

For the Compose installation, run commands from the checkout that holds .novuslens.env and compose.yml. Prepare the input described below, then import it with ./lens, which uploads the file into the running reasoning containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host.:

./lens connectors domain-taxonomy --org harbour --fixture taxonomy.json

Use your organisation id and the chosen account wherever a command asks for them.

Follow the complete Operations manual for accounts, configuration and command access.

Before you start

• Import the org chart first. The taxonomy’s cell ids must match cells that already exist in the map, and the org chart creates the team cells.
• Write the taxonomy as a single .json file, with one entry per domain.
• Run the command from the installation directory. ./lens runs it in the installation’s reasoning service, with the installation’s configuration. It first copies any local file named by --fixture, --file, --mapping or --enrolment into the service.

The JSON shape

Top level

Each domain

Worked example

{
  "domains": [
    {"domain_id": "freight", "label": "Freight movement", "accountable_owner": "Chief Operating Officer",
     "cells": ["bookings", "warehousing"]},
    {"domain_id": "compliance", "label": "Border compliance", "accountable_owner": "Head of Customs",
     "cells": ["customs"]}
  ]
}

The repository holds a Meridian Grid taxonomy, meridian_domain_taxonomy.json in apps/connectors/fixtures. Meridian Grid is a fictional demonstration organisation, and its taxonomy is not a real export.

How to send it

From the installation directory:

./lens connectors domain-taxonomy --org harbour --fixture taxonomy.json

• --org is a top-level option, so it comes before the subcommand name domain-taxonomy.
• --fixture is the path to the taxonomy file.
• --solicited-by is optional. It links the import to an open request for this artefactArtifactA stored source file or evidence body that a record can cite. Keeping the exact content lets a reader check what supported the record., if one exists.
• --host and --port default to the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. address in the environment, as described on the org chart format.

The taxonomy has no browser import. Send it from the command line only.

How cells are matched

The connector matches each id in cells by the words in existing cell ids. It does not require an exact character match. An exact cell id is the safest choice. A cell that matches nothing is not invented. It raises an undeclared-domain-cell finding, described below.

What a re-run does

The table below is the connector’s behaviour, quoted from the taxonomy guide. Where the code differs, the difference is stated below the table.

Two differences from the table, as the code behaves:

• A label left out of a domain on a later run resets its display name to the domain id. The description and accountable_owner fields keep their old values when they are left out. Keep the label in every file that should keep it.
• A file with no domains list is not refused. It is recorded as an artefact and reports zero domains. A file that is not valid JSONJSONJavaScript Object Notation: a text format for data, using named fields, lists and values. Configuration files and service messages use it. stops the command with a traceback.

What you will see

On success the command exits without error and prints one summary line. The shape of the line is:

domain taxonomy: 2 domain(s) → 3 Cell mapping(s) documented (compliance, freight; artifact 3f9a1c0b2d4e…)

If any cell did not match, the line ends with UNDECLARED cells flagged: <ids>. The figures above belong to the illustrative example, not to a real run. The map shows the result after the projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default. service’s next pass, about 30 seconds by default.

Each domain appears in the map with its label and owner, documented at the shown rungRungOne of three levels of support for a recorded value: told, shown or measured. The level appears beside the value.. Each matched cell is linked to its domains.

The misalignment check

IngestIngestRead supplied records or documents and add their information to NovusLens, after the required checks. does not compare the business and team views. The comparison is a separate command, which you run when you want the result:

./lens exec -- python -m conway_graph.misalignment --org harbour

The command ends with a line that reads boundary misalignment: N finding(s) surfaced. Each finding describes a place where the business domains and the team structure do not line up. A finding is a question for the people who own the business and team views, and it is not a verdict on either one.

When something goes wrong

Most problems do not stop the command. A cell the map lacks raises a finding and is left unmapped, and the summary line lists it under UNDECLARED cells flagged. Fix the cell id, or create the missing cell, and run the import again. The finding does not close by itself, so check the findings page after the next pass.

A refusal stops the command before anything is written. The command prints a Python traceback. The reason is the last line of the traceback. The next line names a file with the full traceback. That file can hold secrets: see Configuration. The only refusal that applies to this file is a file that is not valid JSON, which fails with a JSON decoding error.