Synchronization allows you to automatically synchronize the topology of your stack to StackState based on information from such diverse systems as discovery tools, service registries, container management tools and CMDBs.

A synchronization is defined by a datasource and a number of mappings from the external system topology data into StackState topology elements. The following image gives an overview of a synchronization pipeline:

Broadly speaking, the synchronization framework makes two models to turn external data into StackState internal components and relation. There is an ‘External Topology’ model which interprets data and turns it into a graph as the data looks outside of StackState. The second model is ‘StackState Topology’, which are components as viewed in StackState. A synchronization pipeline takes data through these models using configurable scripts. We now explain more in-depth the concepts in the pipeline.

Data source

The data source configures the plugin to connect to a specific instance of an external system. The Plugins section of the documentation contains more details on configurations of specific plugins. It is possible to define several synchronizations for the same datasource.

Id Extraction


To turn external data into ‘External Topology’, we use id extraction. The goal of this step is to take the external data and produce the following information:

  • A ‘type’ for the component/relation for differentiation later on
  • An ‘externalId’. An identifier with which the element is uniquely identifiable in the external source
  • Multiple ‘identifiers’. A set of identifiers that identify the object internally in stackstate.

StackState comes with some default identity extractor functions, which should be suitable for most cases.


Next up is mapping. It specifies the transformation of external system topological data into StackState domain. Mapping is defined by model element type name that is coming from external system, mapping functions and mapping functions parameters.

  • Model Element Type Name - identifier of external element type, e.g. linux, hypervisor, java
  • Mapping Function - Mapping function that knows how to process the data of Model Element Type
  • Parameters - values for a mapping function parameters, e.g. selecting template function that knows how to create specific StackState objects
  • Merge Strategy - indicates the merge strategy applied in case several components form a single entity

Mapping Function

Mapping function is defined by a groovy script and input parameters that groovy script requires. The goal of mapping function is to process topology data of external system and prepare parameters for template function. Thus mapping function is likely plugin specific.

There are 2 specific to a mapping function parameters.

  • ExtTopoComponent/ExtTopoRelation - these are required, system parameters. Every Mapping Function must define one of these. They are used internally by StackState and cannot be changed using API. They indicate the type of element component or relation the mapping function supports.

  • TemplateLambda - this is optional parameter that specifies which template functions must be used with a mapping function.

The example of simple mapping function script is given below:

     def params = [
         'name': element.getExternalId(),
         'description': element.getData().getString("description").get()

     context.runTemplate(template, params)

Creating mapping functions

Mapping function can be created from the Settings page.

Template Function

Template functions is defined by a JSON template and input parameters required by the template to render elements of StackState topology - mainly components or relations. When executed template functions substitutes all handlebar {{ paramName }} parameter references with values of input parameters. Template functions must define all parameters that template body refers to.

Template functions are used in cooperation with Mapping functions to create StackState topology elements. Mapping function parse topological data of external system and prepares input parameters for Template function.

Creating Template Functions from Existing Components and Relations

An easy way to create template functions is to create them based on existing component or relation. This option is available in context menu of Component or Relations details as + Add as template. After adding component or relation as template, its template function will appear in the Templates list in the Templates pane.

Manually creating Template Functions

The example below is a simple template that creates component. Its Template Function must define the parameters with the following names: name, description, componentTypeId, layerId, domainId, environmentId.

        "_type": "Component",
        "checks": [],
        "streams": [],
        "labels": [],
        "name": "{{ name }}",
        "description": "{{ description }}",
        "type" : {{ componentTypeId }},
        "layer": {{ layerId }},
        "domain": {{ domainId }},
        "environments": [{{ environmentId }}]

The template below will create relation between components {{ sourceId }} to {{ targetId }}. Template Function must define parameters with the following names: name, description, relationTypeId, sourceId, targetId.

       "_type": "Relation",
       "checks": [],
       "streams": [],
       "labels": [],
       "name": "{{ name }}",
       "description": "{{ description }}",
       "type": {{ relationTypeId }},
       "source": {{ sourceId }},
       "target": {{ targetId }}

Note that template is not limited to rendering only components and relations. It can render json for any StackState domain object that is supported by !restapi!, e.g. Domain, Layer, Check, Stream etc. and also not only single object, but several multiple objects with one template.