Model and Syntax

Landscape

A landscape is defined as a collection of items which somehow belong together, be it for technical or business reasons. For example, a company department might model ALL its applications in production as one landscape and use grouping or tagging to further separate the applications. A second landscape could be used to model a future layout with a different infrastructure. Both landscapes could have items in common (like a database, load balancer, etc.), so their configuration can be reused.

LandscapeDescription

Name Type Description Remarks Example
color String   optional, defaults to null null
config LandscapeConfig<LandscapeConfig>   optional, defaults to null null
contact String Primary contact method, preferably an email address. optional, defaults to null null
description String A brief description of the landscape. optional, defaults to null null
groups Map<GroupDescription> Description of item groups (optional, can also be given in sources). optional, defaults to null null
icon String   optional, defaults to null null
identifier String Immutable unique identifier. Maybe use an URN. required, defaults to null null
items List<ItemDescription> List of configuration sources. Handled in the given order, latter extend/overwrite earlier values like items etc. optional, defaults to null null
labels Map   optional, defaults to null null
links Map<Link> Key-value pairs of related links. Some keys like 'github' cause that the endpoint data is parsed and added to to corresponding landscape component. optional, defaults to null github: https://github.com/dedica-team/nivio
name String Human readable name. required, defaults to null null
owner String The business owner (person or team), preferably an email address. optional, defaults to null null
partial Boolean marks that the landscape is not complete, but an update optional, defaults to null null
sources List<SourceReference>   optional, defaults to null null
templates Map<ItemDescription> Item descriptions to be used as templates. All values except identifier and name will be applied to the assigned items. optional, defaults to null null

SourceReference

This is a reference to a configuration file.

Name Type Description Remarks Example
assignTemplates Map<array> A map with template identifier as key and item identifier matchers as value optional, defaults to null endOfLife: [web, “java6*”]
basicAuthPassword String   optional, defaults to null null
basicAuthUsername String   optional, defaults to null null
deprecation String deprecation info (typically used in OpenAPI specs) optional, defaults to null null
format String The input format. optional, defaults to null null
headerTokenName String   optional, defaults to null null
headerTokenValue String   optional, defaults to null null
href String The link target. required, defaults to null null
hreflang String hateoas language optional, defaults to null null
media String hateoas media type optional, defaults to null null
name String HateOAS / OpenAPI name optional, defaults to null null
rel String hateoas relation type optional, defaults to null null
title String hateoas title optional, defaults to null null
type String   optional, defaults to null null
url String A URL, but can also be a relative path. optional, defaults to null ./a/items.yaml

LandscapeConfig

Configuration of key performance indicators (i.e. status indicators) and layouting tweaks.

Name Type Description Remarks Example
branding Branding<Branding>   optional, defaults to null null
greedy Boolean Flag that enables instant creation items based relation targets that cannot be found in the sources. optional, defaults to null null
groupBlacklist List Names or patterns of groups that should be excluded from the landscape. Used to improve automatic scanning results. optional, defaults to null .*infra.*
groupLayoutConfig LayoutConfig<LayoutConfig>   optional, defaults to null null
itemLayoutConfig LayoutConfig<LayoutConfig>   optional, defaults to null null
kpis Map<KPIConfig> Key performance indicator configs. Each KPI must have a unique identifier. optional, defaults to null null
labelBlacklist List Names or patterns of labels that should be ignored. Used to improve automatic scanning results. optional, defaults to null .*COMPOSITION.*

KPIConfig

The configuration of landscape specific key performance indicators that derive status information from landscape components. Usually the KPIs work on labels

Name Type Description Remarks Example
description String Description of the purpose of the KPI optional, defaults to null null
enabled Boolean A flag indicating that the KPI is active. Can be used to disable default KPIs. optional, defaults to null null
label String Key of the label to evaluate required, defaults to null costs
matches Map A map of string based matchers that determine the resulting status (GREEN|YELLOW|ORANGE|RED|BROWN). Use a semicolon to separate matchers. optional, defaults to null RED: BAD;err.*
messageTemplate String Template for the displayed message, containing a placeholder for the assessed value '%s optional, defaults to null The current value is: %s
ranges Map A map of number based ranges that determine the resulting status (GREEN|YELLOW|ORANGE|RED|BROWN). Use a semicolon to separate upper and lower bounds. Tries to evaluate label values as numbers. optional, defaults to null GREEN: 0;99.999999

LayoutConfig

Layout configuration. See https://jgraph.github.io/mxgraph/java/docs/com/mxgraph/layout/mxFastOrganicLayout.html

Name Type Description Remarks Example
forceConstantFactor Float A factor to influence the attracting and repulsive forces in a layout. optional, defaults to null null
maxDistanceLimitFactor Float A factor to influence maximum distance where forces are applied. optional, defaults to null null
maxIterations Integer The maximum number of iterations. More iterations theoretically lead to better results. optional, defaults to null null
minDistanceLimitFactor Float A factor to influence minimum distance where forces are applied. optional, defaults to null null

Branding

Map branding (tweaks visuals)

Name Type Description Remarks Example
mapStylesheet String A resolvable URL pointing to a CSS stylesheet. This stylesheet is included in the generated SVG map. Use is to style the appearance of the map. optional, defaults to null https://acme.com/css/acme.css

GroupDescription

A group of items. Could be used as bounded context, for instance.

Name Type Description Remarks Example
color String The HTML (hexcode only!) color used to draw the group and its items. If no color is given, one is computed. optional, defaults to null 05ffaa
contact String A contact method, preferably email. optional, defaults to null null
contains List A list of item identifiers or SQL-like queries to easily assign items to this group. optional, defaults to null identifier LIKE ‘DB1’
description String A brief description. optional, defaults to null null
identifier String A unique identifier for the group (also used as name). Descriptions are merged based on the identifier. required, defaults to null shipping
labels Map   optional, defaults to null null
links Map<Link> Key-value pairs of related links. Some keys like 'github' cause that the endpoint data is parsed and added to to corresponding landscape component. optional, defaults to null github: https://github.com/dedica-team/nivio
name String   optional, defaults to null null
owner String The business owner of the group. optional, defaults to null null

ItemDescription

List of configuration sources. Handled in the given order, latter extend/overwrite earlier values like items etc.

Name Type Description Remarks Example
address String The technical address of the item (should be an URI). Taken into account when matching relation endpoints. optional, defaults to null null
color String Overrides the group color. Use an HTML hex color code without the leading hash. optional, defaults to null 4400FF
contact String The primary way to contact a responsible person or team. Preferably use an email address. optional, defaults to null johnson@acme.com
description String A brief description. optional, defaults to null null
frameworks Map The parts used to create the item. Usually refers to technical frameworks. optional, defaults to null java: 8
group String The identifier of the group this item belongs in. Every item requires to be member of a group internally, so if nothing is given, the value is set to common. optional, defaults to null shipping
icon String An icon name or URL to set the displayed map icon. The default icon set is https://materialdesignicons.com/ and all names can be used (aliases do not work). optional, defaults to null null
identifier String Immutable unique identifier (maybe use an URN). Primary means to identify items in searches. required, defaults to null null
interfaces Set<InterfaceDescription> A collection of low level interfaces. Can be used to describe HTTP API endpoints for instance. optional, defaults to null null
labels Map   optional, defaults to null null
lifecycle String The lifecycle state of an item. optional, defaults to null null
links Map<Link> Key-value pairs of related links. Some keys like 'github' cause that the endpoint data is parsed and added to to corresponding landscape component. optional, defaults to null github: https://github.com/dedica-team/nivio
name String A human readable name/title. The name is considered when items are searched. optional, defaults to null my beautiful service
owner String The business owner of the item. Preferably use an email address. optional, defaults to null johnson@acme.com
providedBy List A collection of identifiers which are providers for this item (i.e. hard dependencies that are required). This is a convenience field to build relations. optional, defaults to null shipping-mysqldb
status List<map> A list of statuses that works like hardcoded KPIs. optional, defaults to null null
statuses List<map> A list of statuses that works like hardcoded KPIs. optional, defaults to null null
tags List   optional, defaults to null null
type String The type of the item. A string describing its nature. If no icon is set, the type determines the displayed icon. optional, defaults to null service|database|volume

InterfaceDescription

Describes a low-level interface of an item.

Name Type Description Remarks Example
deprecated Boolean   optional, defaults to null null
description String A brief description. optional, defaults to null null
format String The payload format. optional, defaults to null null
name String   optional, defaults to null null
parameters String   optional, defaults to null null
path String   optional, defaults to null null
payload String   optional, defaults to null null
protection String A description of the interface protection method. optional, defaults to null null
summary String   optional, defaults to null null
url String A URL describing the endpoint. optional, defaults to null null

Item Groups

Groups can have the following attributes:

  • identifier: A unique identifier in the landscape. Provided automatically via the dictionary key, so do not set it.
  • contains Array of references to other items (identifiers and CQN queries).
  • owner Owning party (e.g. marketing).
  • description A short description.
  • team Technical owner.
  • contact Support/notification contact (email). May be addressed in case of errors.
  • color A hex color code for rendering.
  • links A map/dictionary of URLs to more information.

Group configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 groups:
   content:
     description: All services responsible to provide information on the web.
     owner: Joe Armstrong
     team: Team Content
     contact: joe@acme.org
     color: "#345345"
     links:
       wiki: http://wiki.acme.org/teamContent

   infrastructure:
     team: Admins

Item Identification and Referencing

An item can be uniquely identified by its landscape, its group, and its identifier. A fully qualified identifier is composed of these three: mylandscape, agroup, and theitem. Since the group is optional, items with unique identifier can also be addressed using mylandscape and theitem, or just theitem. Nivio tries to resolve the correct item and raises an error if it cannot be found or the result is ambiguous.

Service references are required to describe a provider relation or dataflow.

1
2
3
4
5
6
7
8
 items:
   - identifier: theservice
     group: agroup
     relations:
       - target: anothergroup/anotherservice
         format: json
         type: dataflow
         label: Data Sync