Handler - ReferenceTargetFinder
ReferenceTargetFinder handler looks for a matching target data card. The criteria for the search is defined by attribute metadata pairs.
In the picture below, there is an example of a simple software license management scenario:
License management example:
In the example above, installed software is linked to software (link A) and a computer (link B1), and license is linked to software (link A') and cost center (link B'). Appropriate license for installed software is needed in order to manage the licenses.
In this case, we have to search for a proper license where the target license maps to the same software as the installed software. In other words, links A and A' must point to the same target. Also, target license must point to the same cost center as the computer where the installed software is installed. In other words, path B1-B2 must point to the same target as link B'.
These mappings must be given in attribute metadata. Below is a configuration example for the above case.
Metadata example for a License attribute:
In the picture above, ReferenceTargetFinder is trying to find a data card from the referred template which matches the following criteria: software attribute refers to the same data card as the $software$ attribute of this data card, and cost_center attribute refers to the same data card as the cost_center attribute of data card referenced by the computer attribute. If either no cards or more than one card are found with the given conditions, then the attribute will be empty.
The following tables provide information on the attribute settings and metadata requirements for ReferenceTargetFinder handler. Compulsory metadata is provided in the Required attribute metadata table including proposals for possible metadata values.
Table 1. Attribute Settings
| Handler name | Datatype |
|---|---|
ReferenceTargetFinder |
Reference |
Table 2. Required Attribute Metadata
| Name | Value | Description |
|---|---|---|
attribute_[name]_[order] |
[$attribute_code$ or $attribute_code1:attribute_code2$]
|
Used to define the attribute of the current data card which will be used as a search criteria for the Name field In the Name field, '
Value field In the Value field, enter some reference attribute code surrounded with ' Pairing with the The value of the reference attribute defined in this metadata is compared with the value of the reference attribute defined in |
search_template_attribute_[name]_[order] |
[attribute_code] |
Used to define the attribute of the searched template which will be used as a search criteria for the Name field In the Name field, '
Value field In the Pairing with the attribute metadata The value of the reference attribute defined in this metadata is compared with the value of the reference attribute defined in attribute metadata. In other words, these two reference attributes need to refer to the same datacard. |
Configuration Examples for Software Asset Management
ReferenceTargetFinder handler is normally used in Software Asset Management (SAM). In SAM its desired behavior is to seek the appropriate software license pool for a monitored software installation, possibly from multiple license pools in specific order, and add a reference to that pool into the monitored software installation data card.
Table 3. ReferenceTargetFinder Example Configuration with Order Values
| Name | Value |
|---|---|
attribute_owner_1 |
$user$ |
attribute_owner_2 |
$cost_center$ |
attribute_owner_3 |
$company$ |
search_template_attribute_owner_1 |
user |
search_template_attribute_owner_2 |
cost_center |
search_template_attribute_owner_3 |
company |
attribute_software |
$software$ |
search_template_attribute_software |
software |
Table 4. ReferenceTargetFinder Example Configuration with Order Values and Paths
| Name | Value | Description |
|---|---|---|
attribute_owner_1 |
$user$ |
|
attribute_owner_2 |
$user:cost_center$ |
|
attribute_owner_3 |
$user:cost_center:company$ |
|
search_template_attribute_owner_1 |
owner |
owner is a reference attribute, with a reference to (at least) User, Cost Center and Company templates |
search_template_attribute_owner_2 |
owner |
owner is a reference attribute, with a reference to (at least) User, Cost Center and Company templates |
search_template_attribute_owner_3 |
owner |
owner is a reference attribute, with a reference to (at least) User, Cost Center and Company templates |
attribute_software |
$software$ |
|
search_template_attribute_software |
software |
The unordered search is in effect with each ordered search; it will look for a license pool which refers to the same software as the software installation.
The ordered searches function as follows: first the ReferenceTargetFinder is trying to find a data card, where user attribute refers to the same user as this data card. If exactly one match is found, the attribute's target will be that data card (except if no licenses are left and prevent_exceeding attribute is used). If suitable data card is not found, next ReferenceTargetFinder tries to look for a data card where cost_center attribute refers to the same data card as the cost center in this data card. If such is found, that will be the target of this reference (except if no licenses are left and prevent_exceeding attribute is used). If suitable data card is not found, next ReferenceTargetFinder tries to look for a data card where company attribute refers to the same data card as the company in this data card (except if no licenses are left and prevent_exceeding attribute is used).
In practice a configuration like this could be created in SAM, if the customer has user specific, cost center specific and company-wide licenses for software. SAM would first try to use the user-specific licenses. If none are free, next SAM would try to use cost center specific licenses. If none are free, SAM would try to use company-wide licenses. If none are free, allocating a license would fail.
If no data cards are found with any of the specified conditions, then the attribute will be empty. If more than one data card is found with any one condition, the result is handled similarly to a situation where no data cards are found (i.e., if there are more searches left, they will be carried out, if all searches have resulted in zero or multiple data cards found, the attribute will be empty).
Using prevent_exceeding Attribute for ReferenceTargetFinder Configuration
Normally, when a target (a license pool) is found, the searching ends and the next condition in order is not tried. If it is wished that the number of used licenses in license pool should not exceed the number of licenses, then the license pool can have an attribute with attribute code prevent_exceeding. If that attribute has any value, and the number of used licenses (attribute code UsedLicenses) would become bigger than the number of licenses (attribute code LicenseManagementLicenseAmount), then the reference will not point to that license pool and the searching continues with the next condition in order. In SAM, UsedLicenses attribute is typically used with ReferrerCounter handler to keep track of the amount of licenses already in use.
Using overflown_license_pool Attribute for ReferenceTargetFinder Configuration
It is also possible to track software instances that are using a license pool other than their preferred one. This can be done by adding a reference attribute with code overflown_license_pool to the software instance. If license overflow occurs (i.e., otherwise suitable match is rejected because all the licenses from that pool are already in use and prevent_exceeding is in effect), this attribute is automatically set to point to the instance's preferred license pool.
There is no way to turn off the effect of prevent_exceeding and overflown_license_pool attributes except removing the attribute codes from the template. Hence attributes with these codes must not exist in templates where their functionality is not wanted.
If you are tracking which software instances are using a license pool other than their preferred one, be careful to configure the referrer counter attribute of used licenses in license pool template to only count software instances from the correct attribute, i.e., ensure that references from the overflown pool are not included in the count. You can also count software instances that would have exceeded the limit of licenses in the pool by adding another referrer counter attribute that only counts software instances that point to it by their overflown_license_pool attribute.ReferenceTargetFinder is always executed when a data card is saved, so the amount of licenses in the license pool does not have an immediate effect on the software installations which refer to it, they must first be saved.
When Efecte Inspector is used, data cards are saved automatically during an import, so there is no need for saving them manually, unless the change must be made visible immediately.
When Sccm is used, data cards are only saved when a change occurs on the computer. This means that potentially the license information on the software installations is not up to date: they may not use the license pool in an optimal way. One way to prevent this problem is to select Show referrers in the license pool view to show all the licenses and then trigger save with multi-edit.
Table of Contents