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.
Pattern templates 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.
The overview section can also have an optional overrides
entry, which enables you to change the behavior of an existing mapping and to preserve those changes on subsequent TKU updates to the overridden mapping.
Here is an excerpt from an overriding mapping:
... from CMDB.Host_ComputerSystem import Host_ComputerSystem 1.2; from CMDB.SoftwareInstance_SoftwareServer import SoftwareInstance_SoftwareServer 3.2; // The mapping referred to by the overrides keyword must be imported syncmapping SoftwareInstance_SoftwareServer_override 3.2 """ Example override mapping. """ overview tags CMDB, Core_Mapping; datamodel 0, 1, 2, 3, 4, 5, 6; overrides SoftwareInstance_SoftwareServer; // The overridden pattern is imported above end overview; mapping from Host_ComputerSystem.host as host traverse Host:HostedSoftware::SoftwareInstance as si_node traverse Element:Maintainer:Pattern:Pattern as si_pattern end traverse; ...
Note
The mapping referred to by the overrides
keyword must be imported. All definitions from the original mapping section such as node kinds, traversals and names must be preserved. It is possible to add additional traversals and names in the overriding mapping.
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.
You should not use DDD directly in mappings, rather, you should copy the required DDD into the inferred model first.
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
For example:
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.
Multiple "From" expressions in the mappings block
Multiple parent mappings are supported, by using more than one "From" expression in the mapping block, for example:
SoftwareInstance_SoftwareServer 4.0 ... mapping from Host_ComputerSystem.host from Cluster.cluster as hosting_system ...
In this example the mapping input can be from a Host or a Cluster node in the (BMC Discovery model). All of the input parameters used in the mapping statement must have corresponding references in the body. An example in the case of the above mapping statement is:
hosting_ci := Cluster.cluster_ci or Host_ComputerSystem.computersystem;
The hosting system (in the CMDB model) is either a BMC_Cluster or a BMC_ComputerSystem. The order matters here; the interpreter takes the first defined object which it finds (checking from left to right).
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 nodename traversal contents... end traverse
The nodename
defined by the traversal can only be used in a for each
expression; it cannot be used in any other context.
You can also define a relationship relname
for a traverse
clause inside the mapping
. The first is the name of the relationship and the second is the name of the node.
traverse traversal_specification as relname, nodename traversal contents... end traverse
In each case the relname
and nodename
defined by the traversal can only be used in a for each
expression; they cannot be used in any other context. You can access the attributes on a relationship by using the name you assigned to the relationship followed by a dot and the attribute as specified in the syncmapping.
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
However, you cannot use search in a syncmapping. CMDB synchronization takes a graph of connected nodes in BMC Discovery and transforms them into a graph of connected CIs in the CMDB. If the where clause contains a search there is no guarantee of any such connection.
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;
For example:
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
- model
Additionally, user-defined functions are not supported.
Any date/time fields should be passed as datetime objects rather than formatted datetime strings.
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 can 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 can 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.
The Impacted
and ImpactWeight
attributes can be used to create impact relationships. They specify impact direction and percentage respectively. For example, an ImpactWeight of 25 might be appropriate when representing an impact relationship between a BMC_ComputerSystem and BMC_Cluster, where there are four computers in a cluster. The value assigned to Impacted must be the Source or Destination CI appearing in the same definition.
sync.rel.BMC_Component( Source := computersystem, Destination := cluster_ci, Name := "CLUSTEREDSYSTEM", Impacted := cluster_ci, ImpactWeight := cluster_rel.impact_weight );
Note that prior to tpl 1.10 multiple relationship definitions were needed to represent a single impact relationship in the CMDB. This was because the way in which impact is represented in the CMDB depends on the data model in effect (see below). In tpl 1.10 and later, only one definition is required.
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.
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:
Data model | CMDB versions | Effect |
---|---|---|
6 | 7.6.03 and later | HasImpact and ImpactDirection attributes are set as appropriate. |
5 | 7.6.03 and later | Only to be used with legacy SIM version 7.4. BMC_Impact relationships with Name “ImpactOnly” are created. |
4 | 7.6.03 and later | No impact details are set by BMC Discovery. They may be set by Impact Normalization in the CMDB. |
3 | 7.6 before 7.6.03 | BMC_Impact relationships with name “IMPACT” are created. |
2 | 7.5 | BMC_Impact relationships with name “IMPACT” are created. |
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 sync.rel.BMC_Dependency( Source := ci, Destination := other_ci, Name := "DEPENDENCY_NAME" ); 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 a CMDB synchronization connection.
Comments
Log in or register to comment.