Model node existence functions
model scope is automatically populated with a function named after each node kind defined in the taxonomy. The functions are used to ensure the existence of corresponding nodes. Each function takes implicitly named arguments of the form:
The function creates or updates a node with the relevant kind, and returns the node. The node's attributes are set to the values given in the function's implicitly named arguments. For example:
A Software Instance node with the specified key is created or updated. It has attributes key, name and value. If a Software Instance with the given key already exists, it is updated; otherwise a new one is created.
Any attribute name can be set in the named arguments, regardless of whether the names are defined in the taxonomy. The attributes are stored with the types of the assigned values, even if the taxonomy specifies that they should have different types.
Nodes created by patterns should have unique keys, both so they can be identified in subsequent executions of the same pattern, and to facilitate integrations that export the data. Keys should be unique across the entire datastore.
In some cases, it is not possible to generate a key that is unique in any scope. In that case, a grouped entity is created, containing a count of the number of nodes in the group, with one group node per Host. If it is possible to separate the groups into a number of sub-groups, the
key_group attribute can be set, in which case one grouping node will be created for each of the different
Node names types and keys contains some advice about choosing appropriate names, types, and keys for nodes created by patterns.
Each node created or modified by these node functions is automatically given a primary inference relationship to the node that triggered execution of the pattern, plus additional contributor inference relationships to represent the provenance of all attributes set on the node. Software Instance and Business Application Instance nodes are also automatically related to the Host(s) on which they are running.
Nodes created or modified by these functions are also given a maintainer relationship to the pattern. When a pattern is removed from the system, all the nodes it has maintainer relationships to are destroyed.
Never use the
model.nodekind functions to update attributes on a node that the pattern is not maintaining. For example, to set an attribute on a Host node, do not do this:
instead, directly set attributes on the node:
Model relationship existence functions
Where additional relationships are required, they can be created explicitly. For each relationship defined in the taxonomy, a corresponding function is also defined in the
model.rel scope. It takes the form:
The function creates or updates a relationship between the source and destination nodes. The parameters are named after the relationship's roles, e.g.
The relationship functions also accept lists of nodes in the roles, in which case, multiple relationships are created/updated between each pair of nodes and the function returns a list of the relationships.
Use of model.rel.Inference should be avoided
You should avoid using the
model.rel.inference function. The inference system expects specific attributes on the Inference relationship. If these attributes are missing there might be a traceback whenever the system attempts to update inference information. A warning is logged when you upload a pattern using the
Relationships in custom patterns
During the development and testing of a custom pattern, if the pattern creates incorrect relationships between nodes, then the pattern is responsible for removing them. Relationships are destroyed automatically when one or both of the nodes they relate is destroyed. You can also consider using Group removal functions or
model.destroy. Relationships are not destroyed when the pattern that created them is deleted. If you destroy a node to remove relationships, you should rescan the infrastructure concerned in order to recreate the removed nodes and relationships. If you are using CMDB synchronization, you should resynchronize all of the hosts associated with these nodes to ensure that the CMDB is synchronized.
Unique relationship functions
It is often useful to declare that a node is related to nothing but a specific node (or nodes). For example, if a Host is in a particular Location, it is not in any other Location. For each relationship defined in the taxonomy, a function is defined in the
model.uniquerel scope. It takes the same form as the equivalent
model.rel function, but its behaviour is different:
- If a relationship already exists between the source and destination, its attributes are updated.
- If a relationship does not exist from the source to the destination it is created.
- All other matching relationships from the source to other destinations are destroyed.
model.rel functions, in
model.uniquerel, the order the roles is specified in is important. The first listed role belongs to the node that has the unique relationship; the node with the second listed role is permitted to have more than one matching relationship. i.e. a Host can be in only one Location, but a Location can have many Hosts in it.
A relationship matches for destruction if it has the same relationship kind, same source and destination roles, and has attributes that match the values of the specified attributes.
For example, to relate a Host to a location:
The use of
uniquerel ensures that the Host nodes are only ever related to one Location.
As a more advanced example, attribute matching can be used to relate to both a city location and an office location:
With those patterns, each Host will now be related to two Location nodes. The use of
uniquerel in the first pattern will only destroy Location relationships with a type attrribute of "city", and the second one will only destroy relationships with a type of "office".
model.rel functions, lists of nodes can be provided. A list in the source role simply has the same effect as calling the function multiple times, once with each source node. A list in the destination role, however, causes the source to be related to all of the destination nodes, and destroys any relationships to other nodes.
Use of model.uniquerel.Inference should be avoided
You should avoid using the
model.uniquerel.inference function. The inference system expects specific attributes on the Inference relationship. If these attributes are missing there might be a traceback whenever the system attempts to update inference information. A warning is logged when you upload a pattern using the
The functions in
model.uniquerel were introduced in TPL 1.2.
Model containment functions
To support construction of Software Instance, Business Application Instance and virtual Host models, two containment specification functions are provided:
Model maintenance functions
The following functions also exist in the
model scope to remove nodes or their attributes:
Group removal functions
When patterns construct complicated structures, such as DatabaseDetail nodes when doing deep discovery of databases, removal must be performed by the pattern. The following functions simplify deletion of these complex structures:
The system expects nodes to be in one removal group only. Where a node is in multiple removal groups, the behavior is undefined.
Model traversal functions
The following convenience functions in the
model scope aid traversals across the model. They take positional arguments: