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 SoftwareInstance node with the specified key is created or updated. It has attributes key, name and value. If a SoftwareInstance with the given key already exists, it is updated; otherwise a new one is created.

Any attribute name may be set in the named arguments, regardless of whether the names are defined in the taxonomy. Note that 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.

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. SoftwareInstance and BusinessApplicationInstance 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. e.g. 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 may 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.

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.

e.g. 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 may 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 SoftwareInstance, BusinessApplicationInstance 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:

Was this page helpful? Yes No Submitting... Thank you

Comments