Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/features/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ All data is stored as OpenRegister objects (no own database tables). OpenRegiste
| [Health and metrics](observability.md) | A public health check for uptime probes and Prometheus metrics for administrators, configured in the manifest |
| [Open Data Publishing](#open-data-publishing) | Expose the catalogue as a public open-data API |
| [GEMMA Compliance](#gemma-compliance) | Built around VNG GEMMA Softwarecatalogus reference |
| [Reference Component Coverage](reference-component-coverage.md) | Which GEMMA reference components an organisation covers, where it has gaps and where applications overlap |
| [Reference Component Coverage](reference-component-coverage.md) | Which GEMMA reference components an organisation covers, where it has gaps and where applications overlap, per GEMMA view, with what comparable organisations use |
| [Catalogue Exports and Custom Reports](catalogue-exports-and-reports.md) | Export lists, faceted lists and one organisation as ArchiMate, and define your own reports |

## Software Registration
Expand Down
26 changes: 24 additions & 2 deletions docs/features/reference-component-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@ applications in use cover, where it has a gap and where two or more
applications cover the same component. It answers the information manager's
question "where are we missing something, and where do we have too much?"

Specification:
[`openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md`](https://github.com/ConductionNL/stackiq/blob/development/openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md).
Specifications:
[`reference-component-coverage`](https://github.com/ConductionNL/stackiq/blob/development/openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md)
and
[`gemma-plate`](https://github.com/ConductionNL/stackiq/blob/development/openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md).

> Screenshots of the coverage table, the map and the Overlap section are
> still pending a live-instance capture; the Playwright-captured images
Expand Down Expand Up @@ -53,6 +55,26 @@ then says "Import the GEMMA model to see coverage." instead of an empty table.
- a detail panel for the chosen component, naming the applications in use
that could fill a fillable gap.

### Grouping the plate by a GEMMA view

The **GEMMA view** picker lists the GEMMA views imported with the GEMMA model, each with its GEMMA release when the import recorded one. Pick a view, for example *GEMMA Applicatiearchitectuur, gemeentebreed*, and the plate draws that view's reference components in the view's own groups (such as Front-office, Mid-office, Back-office en basisregistraties), each with its state and the organisation's applications. Clear the picker to see the whole model grouped by the components' own GEMMA grouping.

The chosen view is kept in the address as `?view=<id>`, so a link opens the same plate. Without an imported GEMMA model the picker is empty and the page says the model is needed.

### What comparable organisations use

Under **Layers**, switch on **What comparable organisations use**. The table below the plate then shows per reference component your own applications and the applications comparable organisations use for it, with how many organisations use each. Select a component on the plate and its side panel lists the same applications with their counts, so a gap shows what others fill it with.

Comparable means the same organisation type (for example municipality) and the same inhabitants band: under 30,000; 30,000 to 60,000; 60,000 to 100,000; 100,000 to 250,000; above 250,000. Set the number of inhabitants on the organisation's page. An organisation without that number is compared with every organisation of its type. The table's heading names the type and band compared with.

#### The anonymity rule

The counts are computed on the server over all usages, and the answer never contains another organisation's id or name. An application used by fewer than 3 comparable organisations shows **fewer than 3** instead of a count, so a single organisation's choice cannot be read off the table. Only members of the organisation can open its comparison.

### GEMMA definitions in place

Select a reference component on the plate and the side panel shows its GEMMA definition. On the **Applications** and **Services** pages, the list *What the reference components are* under the GEMMA filters gives each reference component an information button. It opens the component's name *from GEMMA*, its definition, and a link **More in GEMMA Online**. A component without a definition shows only its name and the link.

### Coverage on a GEMMA view

Below the plate, **Coverage on a GEMMA view** lets the user pick an imported
Expand Down
19 changes: 19 additions & 0 deletions l10n/en.js
Original file line number Diff line number Diff line change
Expand Up @@ -2280,6 +2280,25 @@ OC.L10N.register(
"{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.",
"{role} removed from {person}": "{role} removed from {person}",
"Review": "Review",
"The whole GEMMA model": "The whole GEMMA model",
"Import the GEMMA model to pick a GEMMA view.": "Import the GEMMA model to pick a GEMMA view.",
"{min} to {max} inhabitants": "{min} to {max} inhabitants",
"{name} ({count})": "{name} ({count})",
"{name} (fewer than {min})": "{name} (fewer than {min})",
"above {min} inhabitants": "above {min} inhabitants",
"Comparable organisations use": "Comparable organisations use",
"Comparable organisations: {count}": "Comparable organisations: {count}",
"Layers": "Layers",
"Own applications": "Own applications",
"under {max} inhabitants": "under {max} inhabitants",
"What comparable organisations use": "What comparable organisations use",
"What comparable organisations use could not be loaded.": "What comparable organisations use could not be loaded.",
"What comparable organisations use: {type}": "What comparable organisations use: {type}",
"What comparable organisations use: {type}, {band}": "What comparable organisations use: {type}, {band}",
"{name}, from GEMMA": "{name}, from GEMMA",
"More in GEMMA Online": "More in GEMMA Online",
"What is {name}?": "What is {name}?",
"What the reference components are": "What the reference components are",
"blocked by the SSRF guard": "blocked by the SSRF guard",
"Error: {reason}": "Error: {reason}",
"Last pulled {date}": "Last pulled {date}",
Expand Down
19 changes: 19 additions & 0 deletions l10n/en.json
Original file line number Diff line number Diff line change
Expand Up @@ -2321,6 +2321,25 @@
"{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.",
"{role} removed from {person}": "{role} removed from {person}",
"Review": "Review",
"The whole GEMMA model": "The whole GEMMA model",
"Import the GEMMA model to pick a GEMMA view.": "Import the GEMMA model to pick a GEMMA view.",
"{min} to {max} inhabitants": "{min} to {max} inhabitants",
"{name} ({count})": "{name} ({count})",
"{name} (fewer than {min})": "{name} (fewer than {min})",
"above {min} inhabitants": "above {min} inhabitants",
"Comparable organisations use": "Comparable organisations use",
"Comparable organisations: {count}": "Comparable organisations: {count}",
"Layers": "Layers",
"Own applications": "Own applications",
"under {max} inhabitants": "under {max} inhabitants",
"What comparable organisations use": "What comparable organisations use",
"What comparable organisations use could not be loaded.": "What comparable organisations use could not be loaded.",
"What comparable organisations use: {type}": "What comparable organisations use: {type}",
"What comparable organisations use: {type}, {band}": "What comparable organisations use: {type}, {band}",
"{name}, from GEMMA": "{name}, from GEMMA",
"More in GEMMA Online": "More in GEMMA Online",
"What is {name}?": "What is {name}?",
"What the reference components are": "What the reference components are",
"blocked by the SSRF guard": "blocked by the SSRF guard",
"Error: {reason}": "Error: {reason}",
"Last pulled {date}": "Last pulled {date}",
Expand Down
19 changes: 19 additions & 0 deletions l10n/nl.js
Original file line number Diff line number Diff line change
Expand Up @@ -2342,6 +2342,25 @@ OC.L10N.register(
"on the contact person": "op de contactpersoon",
"{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} van {total} personen moeten worden beoordeeld. Een beoordeling is nodig als de toegang niet in de afgelopen {days} dagen is beoordeeld.",
"{role} removed from {person}": "{role} verwijderd bij {person}",
"The whole GEMMA model": "Het hele GEMMA-model",
"Import the GEMMA model to pick a GEMMA view.": "Importeer het GEMMA-model om een GEMMA-view te kiezen.",
"{min} to {max} inhabitants": "{min} tot {max} inwoners",
"{name} ({count})": "{name} ({count})",
"{name} (fewer than {min})": "{name} (minder dan {min})",
"above {min} inhabitants": "meer dan {min} inwoners",
"Comparable organisations use": "Vergelijkbare organisaties gebruiken",
"Comparable organisations: {count}": "Vergelijkbare organisaties: {count}",
"Layers": "Lagen",
"Own applications": "Eigen applicaties",
"under {max} inhabitants": "minder dan {max} inwoners",
"What comparable organisations use": "Wat vergelijkbare organisaties gebruiken",
"What comparable organisations use could not be loaded.": "Wat vergelijkbare organisaties gebruiken kon niet worden geladen.",
"What comparable organisations use: {type}": "Wat vergelijkbare organisaties gebruiken: {type}",
"What comparable organisations use: {type}, {band}": "Wat vergelijkbare organisaties gebruiken: {type}, {band}",
"{name}, from GEMMA": "{name}, uit GEMMA",
"More in GEMMA Online": "Meer in GEMMA Online",
"What is {name}?": "Wat is {name}?",
"What the reference components are": "Wat de referentiecomponenten zijn",
"blocked by the SSRF guard": "geblokkeerd door de SSRF-beveiliging",
"Error: {reason}": "Fout: {reason}",
"Last pulled {date}": "Laatst opgehaald {date}",
Expand Down
19 changes: 19 additions & 0 deletions l10n/nl.json
Original file line number Diff line number Diff line change
Expand Up @@ -2383,6 +2383,25 @@
"on the contact person": "op de contactpersoon",
"{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} van {total} personen moeten worden beoordeeld. Een beoordeling is nodig als de toegang niet in de afgelopen {days} dagen is beoordeeld.",
"{role} removed from {person}": "{role} verwijderd bij {person}",
"The whole GEMMA model": "Het hele GEMMA-model",
"Import the GEMMA model to pick a GEMMA view.": "Importeer het GEMMA-model om een GEMMA-view te kiezen.",
"{min} to {max} inhabitants": "{min} tot {max} inwoners",
"{name} ({count})": "{name} ({count})",
"{name} (fewer than {min})": "{name} (minder dan {min})",
"above {min} inhabitants": "meer dan {min} inwoners",
"Comparable organisations use": "Vergelijkbare organisaties gebruiken",
"Comparable organisations: {count}": "Vergelijkbare organisaties: {count}",
"Layers": "Lagen",
"Own applications": "Eigen applicaties",
"under {max} inhabitants": "minder dan {max} inwoners",
"What comparable organisations use": "Wat vergelijkbare organisaties gebruiken",
"What comparable organisations use could not be loaded.": "Wat vergelijkbare organisaties gebruiken kon niet worden geladen.",
"What comparable organisations use: {type}": "Wat vergelijkbare organisaties gebruiken: {type}",
"What comparable organisations use: {type}, {band}": "Wat vergelijkbare organisaties gebruiken: {type}, {band}",
"{name}, from GEMMA": "{name}, uit GEMMA",
"More in GEMMA Online": "Meer in GEMMA Online",
"What is {name}?": "Wat is {name}?",
"What the reference components are": "Wat de referentiecomponenten zijn",
"blocked by the SSRF guard": "geblokkeerd door de SSRF-beveiliging",
"Error: {reason}": "Fout: {reason}",
"Last pulled {date}": "Laatst opgehaald {date}",
Expand Down
84 changes: 78 additions & 6 deletions lib/Service/FacetService.php
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,7 @@ private function computeFacetsForRequest(ObjectServiceInterface $objectService,
baseObjects: $baseObjects
);

$dimValsByObjId = $this->buildDimensionValueMap(modulesByObjectId: $modulesByObjectId);
[$dimValsByObjId, $definitions] = $this->dimensionValuesAndDefinitions(modulesByObjectId: $modulesByObjectId);

// Supplier (insight-supplier-facet D3): the base object's OWN provider,
// for a service too, keyed by organisation id and labelled by name (D2).
Expand All @@ -272,6 +272,7 @@ private function computeFacetsForRequest(ObjectServiceInterface $objectService,
selectedFilters: $request['filters'],
labels: ['supplier' => $this->organisationNames(objectService: $objectService, identifiers: array_values(array_unique($supplierIds)))]
);
$facets['referenceComponent'] = self::withDefinitions(buckets: $facets['referenceComponent'], definitions: $definitions);

$matchedObjectIds = $this->filterObjectIds(
dimValsByObjId: $dimValsByObjId,
Expand Down Expand Up @@ -740,15 +741,17 @@ private function fetchModulesByIdentifiers(ObjectServiceInterface $objectService
* Build the per-object GEMMA dimension value map: for every base object,
* the set of referenceComponent/standard names it carries directly, and
* the set of domain/applicationService names resolved transitively via its
* linked `element` objects.
* linked `element` objects. From the same element lookup, the GEMMA
* definition of each referenceComponent value by its display name.
*
* @param array<string,array<int,array>> $modulesByObjectId Object id => module objects.
*
* @return array<string,array<string,string[]>> Object id => dimension => distinct values.
* @return array{0: array<string,array<string,string[]>>, 1: array<string,array{documentation: string, gemmaUrl: string}>}
*
* @spec openspec/specs/gemma-faceted-search/spec.md#requirement-facet-aggregation-endpoint-returns-gemma-dimension-counts
* @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-gemma-terms-show-their-definition-where-they-appear-req-gpl-003
*/
private function buildDimensionValueMap(array $modulesByObjectId): array {
private function dimensionValuesAndDefinitions(array $modulesByObjectId): array {
// Pass 1: direct fields (referenceComponent identifiers + standard identifiers).
$direct = array_map(fn (array $modules): array => $this->directDimensions(modules: $modules), $modulesByObjectId);
$allRefCompIds = array_values(array_unique(array_merge([], ...array_values(array_column($direct, 'refCompIds')))));
Expand All @@ -765,8 +768,77 @@ private function buildDimensionValueMap(array $modulesByObjectId): array {
);

// Assemble the final per-object dimension map.
return array_map(fn (array $values): array => $this->objectDimensions(resolution: $resolution, direct: $values), $direct);
}//end buildDimensionValueMap()
return [
array_map(fn (array $values): array => $this->objectDimensions(resolution: $resolution, direct: $values), $direct),
$this->definitionsByName(elementsById: $elementsById, refCompIds: $allRefCompIds),
];
}//end dimensionValuesAndDefinitions()

/**
* The GEMMA definition and GEMMA Online link of each referenceComponent,
* by the display name its facet value carries. The first element with a
* name keeps it.
*
* @param array<string,array> $elementsById Element identifier => element object.
* @param array<int,string> $refCompIds The referenceComponent identifiers.
*
* @return array<string,array{documentation: string, gemmaUrl: string}>
*
* @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-gemma-terms-show-their-definition-where-they-appear-req-gpl-003
*/
private function definitionsByName(array $elementsById, array $refCompIds): array {
$definitions = [];
foreach ($refCompIds as $refCompId) {
$element = ($elementsById[$refCompId] ?? []);
$name = $this->elementDisplayName(element: $element, fallbackIdentifier: $refCompId);
if (isset($definitions[$name]) === true) {
continue;
}

$definitions[$name] = [
'documentation' => self::trimmedString(value: ($element['documentation'] ?? null)),
'gemmaUrl' => self::trimmedString(value: ($element['gemmaUrl'] ?? null)),
];
}

return $definitions;
}//end definitionsByName()

/**
* A value as a trimmed string, '' when it is not a string.
*
* @param mixed $value The value.
*
* @return string The string.
*/
private static function trimmedString(mixed $value): string {
if (is_string($value) === true) {
return trim($value);
}

return '';
}//end trimmedString()

/**
* The referenceComponent buckets, each with its GEMMA definition and
* GEMMA Online link ('' when the element has none).
*
* @param array<int,array{value:string,label:string,count:int}> $buckets The buckets.
* @param array<string,array{documentation: string, gemmaUrl: string}> $definitions By display name.
*
* @return array<int,array{value:string,label:string,count:int,documentation:string,gemmaUrl:string}>
*
* @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-gemma-terms-show-their-definition-where-they-appear-req-gpl-003
*/
private static function withDefinitions(array $buckets, array $definitions): array {
return array_map(
static fn (array $bucket): array => array_merge(
$bucket,
($definitions[$bucket['value']] ?? ['documentation' => '', 'gemmaUrl' => ''])
),
$buckets
);
}//end withDefinitions()

/**
* The referenceComponent identifiers and the standard names an object's modules carry, each distinct.
Expand Down
Loading
Loading