Syncmapping block

The mappings performed during CMDB synchronization are specified in syncmapping blocks in TPL. A syncmapping is similar to a pattern, but it triggers from a queued synchronization action, rather than from data being updated in the data store.

The form of a syncmapping is:

syncmapping name version
  description
  overview
    overview_entries
  end overview;
  [constants
    constant_definitions
  end constants;]
  mapping mapping_source as source_name
    mapping_definitions
  end mapping;
  body
    body_details
  end body;
end syncmapping;

As with pattern blocks, the name, version, and description are mandatory.

Template patterns are provided to help you create your own syncmappings.

Overview section

The overview is required. It contains information about the pattern and the entities it creates. It must contain a tags entry, and can have an optional datamodel entry, as described in #Data models.

Mapping section

The mapping section declares the starting point for the mapping, the structure of source data retrieved from the Discovery model, and the target CIs created in the CMDB model. It does not describe how the source data is transformed to the target model – that is performed in the body section.

Mapping source

Each mapping is either a root mapping, meaning that it is invoked by the synchronization of a single root node with the corresponding kind, or an extension mapping, meaning that it extends another mapping at a suitable point.

Root mappings have a mapping declaration using the on keyword:

mapping on node_kind as name
  mapping content...
end mapping

For example, this specifies the root mapping for Host nodes:

mapping on Host as host_node

Extension mappings have a mapping declaration using the from keyword:

mapping from source_scoped_name as name

e.g.

mapping from ExampleMapping.host_node as host_node

The source_scoped_name is the name of a source mapping variable from another mapping block, either the source name specified in the mapping declaration, or a traversal name as described below.

Mapping traversals

The source subgraph is declared using traverse clauses inside the mapping with a syntax similar to traversals in search expressions:

traverse traversal_specification as name
  traversal contents...
end traverse

The name defined by the traversal may only be used in a for each expression; it may not be used in any other context.

Where clauses

The initial source node and the results of traversals can be filtered with where clauses, specified before the as token. where clauses in mapping blocks use the same subset of search where clauses as trigger conditions in pattern blocks.

mapping on node_kind where condition as name

mapping from source_scoped_name where condition as name

traverse traversal_specification where condition as name

Target CI declarations

As the subgraph is processed in the body, target CIs are specified. The mapping block contains declarations of the CIs that are mapped, in the form:

name -> CI_class;

e.g.

computersystem -> BMC_ComputerSystem;

Targets are specified within the traversal structure. For example, part of the mapping of virtual machines is as follows:

mapping from Host_ComputerSystem.host where virtual defined as host
  traverse ContainedHost:HostContainment:HostContainer:SoftwareInstance as vm_si

    vse -> BMC_VirtualSystemEnabler;

    traverse RunningSoftware:HostedSoftware:Host:Host as containing_host
      containing_cs -> BMC_ComputerSystem;
    end traverse;
  end traverse;
end mapping;

Grouping

In some circumstances, a number of nodes in the Discovery model must be grouped together to construct a single CI in the CMDB model. This is declared in the mapping with a group block. The form of a group block is

traverse traversal_specification as traversal_name
  group group_name
    group contents...
    expand group as expansion_name
      expansion contents...
    end expand;
  end group;
end traverse;

The declaration indicates that nodes from the containing traversal will be grouped together (according to rules specified in a group block in the body), and then the group will be expanded to the individual group members. The expand is not required if there is no need to process the individual nodes within the group.

Syncmapping body

The body of a syncmapping is responsible for implementing the mapping described in the mapping block. The majority of language features and functions available in pattern body blocks are permitted, except that functions in the following namespaces are not available since they are only appropriate for patterns that perform discovery and construct the Discovery model.

• discovery
• inference
• mail
• model

Additionally, user-defined functions are not supported.

Body execution

The body of a syncmapping is executed at a time that depends upon the mapping source definition.

The body of a root mapping (specified with mapping on) is executed at the time the root node is scheduled for synchronization.

The body of an extension mapping (specified with mapping from) that extends the source node of another mapping is executed when the body of the extended mapping completes.

The body of an extension mapping that extends a traversed-to node of another mapping is executed each time the associated for each loop (see below) completes.

When a node in the Discovery data store is marked as destroyed, only the root mapping's body is executed, and the target root CI is scheduled for deletion in the CMDB. When the delete is synchronized with the CMDB, the root CI and all the related CIs previously created by the mapping are deleted. For best performance during deletion, root mappings should not perform any traversals or other time-consuming activities.

CI definition

CIs and relationships in the CMDB are specified with functions in the sync namespace similar to those in the model namespace used within pattern blocks.

Any CMDB class can be specified with a function call of the form

value := sync.BMC_ClassName(key := some_key, attributes...);

Any class name can be specified. Specifying a class that is not defined in the CMDB results in a run-time error. The key attribute must be set, and is used to populate the ADDMIntegrationID attribute in the CMDB. Any other attribute name can be set; attributes that are not defined in the CI class are ignored.

The result of the function must be assigned to a target CI name specified in the mapping block. The class specified in the function must be the same as the one specified in the mapping or a subclass of it.

CI class namespaces

CMDB classes are assumed to be in the BMC.CORE namespace. To refer to a class in a different namespace, provide a namespace parameter to the function call:

value := sync.BMC_ClassName(key := some_key, namespace := "My.NameSpace", attributes...);

The namespace must be a literal string – it cannot be constructed at runtime.

Shared CIs

The subgraph of data in the Discovery model is transformed into a subgraph of CIs in the target CMDB model. Most of the CIs belong to a single target subgraph, but some are shared by more than one subgraph. An example is the BMC_IPConnectivitySubnet CI that is shared by all the computers on a particular subnet. For deletion to work correctly, the system must know that such CIs are shared. This is achieved by calling the function in the sync.shared namespace:

value := sync.shared.BMC_SharedClassName(key := some_key, attributes...);

External CIs

Similarly, it is sometimes necessary to specify a relationship to a CI that is not part of the target subgraph. An example is to relate the BMC_ComputerSystem for a physical host to the one for a virtual host – the two CIs belong to different subgraphs. External CIs are specified with a function in the sync.external namespace:

value := sync.external.BMC_ClassName(key := some_key [, namespace := "_NAMESPACE" ]);

The key must be specified, and namespace must be specified if required. No other attributes may be set.

It is not an error if a CI with the specified key does not exist in the CMDB. In that situation, the CI and any relationships to it are simply ignored.

Cross-reference CIs

As the mapping is processed, the CIs are specified in a tree traversal across the graph. To refer to a CI specified in a different branch of the tree, it can be specified with a function in the sync.crossref namespace:

value := sync.crossref.BMC_ClassName(key := some_key [, namespace := "_NAMESPACE" ]);

The key must be specified, and namespace must be specified if required. No other attributes may be set.

It is a runtime error to specify a cross-reference to a CI that is not fully specified elsewhere within the mapping.

Relationship definition

Relationships are specified with functions in the sync.rel namespace:

sync.rel.BMC_RelName(Source := source_val, Destination := dest_val, Name := "RELNAME" [, ... ]);

The first two parameters must be Source and Destination. Any other attributes can also be set; Name is not required, but it is conventionally always set.

Traversal looping

One of the main activities performed in the body is to iterate over the nodes reached through the traversals specified in the mapping block. A for each loop is used to iterate over the named nodes:

for each source_node do
  ...
end for

The nesting structure of for each loops in the body must match the nesting structure of the traverse expressions in the mapping block.

Note that a for each loop is required even if the corresponding traversal is expected to reach just one node. There is no other way to access the state of the traversed-to node.

Group block

When the mapping block specifies a group, there must be a corresponding group block in the body. The group block will always be inside a for each block, either directly within a single syncmapping body or in an extended source syncmapping.

A group block takes the form:

for each traversed_to_node do
  ...
  ident := group_identifier;
  group group_name with ident do
    ...

    for each expand_name do
      ...
    end for;
  end group;
end for;

The grouping is evaluated in two phases. In the first phase, every iteration of the surrounding for each loop is executed. The nodes are grouped according to the identifier provided to the group expression. After all the iterations of the for each loop, the group block is executed once for each group. If the group declaration in the mapping block contains an expand declaration, there should be a corresponding for each loop in the body.

The group content is executed in a context based on an arbitrary member of the group. Any local variables from the surrounding loop will therefore be valid for a member of the group, but there is no guarantee that it will be the same group member each time a particular group is processed.

Data models

Different versions of the CMDB have subtly different data models. Syncmappings can support multiple data models with datamodel declarations. CMDB data models are assigned simple integer values:

A syncmapping can limit itself to a particular set of data models with a datamodel declaration in the overview:

overview
  tags Some_tags;
  datamodel 3, 4;  // Only CMDB 7.6.x
end overview

The body of a syncmapping can further modify its behavior for different data models with a datamodel block. The datamodel block only executes if the data model in effect matches the declaration:

ci := sync.BMC_Thing(key := my_key, ...);

datamodel 2, 3 do
    // Create Impact relationship only for CMDB 7.5 and 7.6
    sync.rel.BMC_Impact(Source := ci; Destination := other_ci);
end datamodel;

The data model in effect is not chosen automatically. After you configure CMDB synchronization, the data model is selected. This is described in Setting up the CMDB synchronization connection.