Model functions

Model node existence functions

The 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:

model.node_kind(attributes...)

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:

key := "My unique key";
name := "My instance number %number%";
special_value := 123;
model.SoftwareInstance(key, name, value := special_value+1);

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 key_group values. When creating a grouped node, the node is given a key based on the type attribute and the key_group. If the attribute key_basis is set, that is used instead of type.

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.

Accidental maintainers

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:

my_host := // a Host from somewhere
model.Host(key := my_host.key, color := "red"); // BAD!

instead, directly set attributes on the node:

my_host := // a Host from somewhere
my_host.color := "red"; // Good!

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:

model.rel.relationship(source_role := source, dest_role := dest, attributes ...)

The function creates or updates a relationship between the source and destination nodes. The parameters are named after the relationship's roles, e.g.

si_node := // VMware SoftwareInstance
host_node := // Virtual Host
rel := model.rel.HostContainment(HostContainer := si_node, ContainedHost := host_node);

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 model.rel.inference function.

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:

model.uniquerel.relationship(source_role := source, dest_role := dest, attributes ...)

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.

Parameter order

Unlike 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:

place := // a Location node
model.uniquerel.Location(ElementInLocation := host, Location := place);

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:

// City pattern
place := // a Location node for the city
model.uniquerel.Location(ElementInLocation := host, Location := place, type := "city");

// Office pattern
place := // a Location node for the office
model.uniquerel.Location(ElementInLocation := host, Location := place, type := "office");

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".

Like 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 model.uniquerel.inference function.

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:

model.destroy
model.withdraw

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: