This documentation and the Cisco Observability Platform functionalities it describes are subject to change. Data saved on the platform may disappear and APIs may change without notice.

Understanding Templates

Just as the underlying data model of a domain is modeled, not hardcoded, the entity centric pages visualizing this data are configured as JSON artifacts called templates.

Templates:

  • Are stored in the Knowledge Store as part of a solution.
  • Define the arrangement, configuration, and data binding of their components.
  • May contain complete pages with a pre-built design, composite components, atomic components, styling (such as fonts, colors, theme effects, background styles, icons), and more.
  • Can be nested, meaning that you can use a template within another template.
  • Streamline the process of UI development by providing working units that can be composed without writing JavaScript code.

A template is written to be applied to a topology context with a specific entity type, but with arbitrary selection criteria. This means that the template does not contain an absolute query, but rather displays the content it gets from the topology context. However, it does rely on the entity type and cardinality of that topology context for the attributes, metrics, and associations that it can render.

A template consists of two parts:

  • The header information contains the name and expected type of the topology context (target).
  • The template element contains the actual configuration data.

Here is an example of a very simple template for the rendering of one entity of type service:

Syntax

{
    "kind": "<template-type>",
    "target": "<fully-qualified-entity-type>",
    "element": {
        "instanceOf": "<building-block-type>",
        "path": "attributes(service.name)"
    }
}

Attributes

Name Description
kind The document type of the template (as required by the Knowledge Store).
target Specifies what entity type the template applies to. For example, apm:service.
element The template element, also called the building block, contains the actual configuration data:
* instanceOf specifies the type of the building block. Valid values: string, ecpList, join, related, relatedSet, union.
* path specifies what data of the focus entity is displayed, in the form of the UQL fragment required to get the data.

All other attributes in element are configuration parameters.
Building blocks can either be atomic or other templates.
If the building block is an active building block, it doesn’t require any explicit data binding information beyond the path attribute; it gets binding information (topology context) from the path attribute. An example of an active building block is one with instanceOf being string.
Passive building blocks, on the other hand, have no notion of the topology context; they are just generic rendering components. In order to make passive building blocks display data, you must add an explicit data binding, and possibly a data transformation, to element. This capability is not yet available.

Examples

{
    "kind": "template",
    "target": "apm:service",
    "element": {
        "instanceOf": "string",
        "path": "attributes(service.name)"
    }
}

In this example, the building block string has an attribute path, which contains the UQL fragment required to get the content to be rendered from the entity in the topology context.

The following example illustrates a template that represents the entire List view on an entity centric page:

{
    "kind": "template",
    "name": "apm:service-ecpList",
    "target": "apm:service",
    "element": {
        "instanceOf": "ecpList",
        "elements": [
            {
                "instanceOf": "card",
                "props": {
                    "style": {
                        "border": "solid 1px #464957",
                        "borderRadius": "5px",
                        "backgroundColor": "rgb(38, 41, 57)",
                        "padding": 0
                    },
                    "elements": [
                        {
                            "instanceOf": "apm:service-ecpListVisualizationTab"
                        }
                    ]
                }
            }
        ]
    }
}

The building block used at the top level is ecpList, which renders the structure of an entity centric page (including the Relationships map and Properties panel) and receives the elements to be rendered in the center pane as part of its configuration.

In this case, there is only one element, card, (which provides a colored background), that itself can be configured to contain further child elements. This sample template has a child element apm:service-ecpListVisualizationTab.

Instead of using a reference to a template, the element of the referred template can be embedded to the same effect. Using named templates instead of inlining the respective elements has two advantages:

  • A named template can be reused in other templates with no redundancy.
  • A named template can be referenced by template extensions.