Constructed Virtual Attribute

This virtual attribute constructs values for an attribute by using a combination of fixed test and values of other attributes from the entry. As with most virtual attributes, searching on the attribute is not indexed.

Parent Component Properties dsconfig Usage

Parent Component

The Constructed Virtual Attribute component inherits from the Virtual Attribute

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  require-explicit-request-by-name
 enabled  multiple-virtual-attribute-evaluation-order-index
 attribute-type  multiple-virtual-attribute-merge-behavior
 base-dn  allow-index-conflicts
 group-dn
 filter
 client-connection-policy
 conflict-behavior
 value-pattern

Basic Properties

description

Description
A description for this Virtual Attribute
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

enabled

Description
Indicates whether the Virtual Attribute is enabled for use.
Default Value
None
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

attribute-type

Description
Specifies the attribute type for the attribute whose values are to be dynamically assigned by the virtual attribute.
Default Value
None
Allowed Values
The name or OID of an attribute type defined in the server schema.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

base-dn

Description
Specifies the base DNs for the branches containing entries that are eligible to use this virtual attribute. If no values are given, then the server generates virtual attributes anywhere in the server.
Default Value
The location of the entry in the server is not taken into account when determining whether an entry is eligible to use this virtual attribute.
Allowed Values
A valid DN.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

group-dn

Description
Specifies the DNs of the groups whose members can be eligible to use this virtual attribute. If no values are given, then group membership is not taken into account when generating the virtual attribute. If one or more group DNs are specified, then only members of those groups are allowed to have the virtual attribute.
Default Value
Group membership is not taken into account when determining whether an entry is eligible to use this virtual attribute.
Allowed Values
A valid DN.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

filter

Description
Specifies the search filters to be applied against entries to determine if the virtual attribute is to be generated for those entries. If no values are given, then any entry is eligible to have the value generated. If one or more filters are specified, then only entries that match at least one of those filters are allowed to have the virtual attribute.
Default Value
None
Allowed Values
Any valid search filter string.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

client-connection-policy

Description
Specifies a set of client connection policies for which this Virtual Attribute should be generated. If this is undefined, then this Virtual Attribute will always be generated. If it is associated with one or more client connection policies, then this Virtual Attribute will be generated only for operations requested by clients assigned to one of those client connection policies.
Default Value
None
Allowed Values
The DN of any Client Connection Policy.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

conflict-behavior

Description
Specifies the behavior that the server is to exhibit for entries that already contain one or more real values for the associated attribute.
Default Value
real-overrides-virtual
Allowed Values
real-overrides-virtual - Indicates that any real values contained in the entry are preserved and used, and virtual values are not generated.

virtual-overrides-real - Indicates that the virtual attribute provider suppresses any real values contained in the entry and generates virtual values and uses them.

merge-real-and-virtual - Indicates that the virtual attribute provider is to preserve any real values contained in the entry and merge them with the set of generated virtual values so that both the real and virtual values are used.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

value-pattern

Description
Specifies a pattern for constructing the virtual attribute value using fixed text and attribute values from the entry. By default, any text provided in the value-pattern is copied verbatim into the target value with the exception of attribute names embedded in '{}'s. Attributes are substituted using their value, e.g. {uid} will select the uid attribute from the entry and use that value in place of {uid} in the value-pattern. At most one attribute may be multivalued. If one attribute is multivalued then the constructed virtual attribute value will be multivalued with the same number of values minus any duplicates. For example a pattern of '{givenName} {sn}' would produce values ['Jim Smith', 'James Smith'] if givenName had values of ['Jim', 'James'] and sn had a value of 'Smith'. If the entry has no value or if there are multiple multivalued attributes, the attribute value construction will fail and the virtual attribute will not have a value. To include a '{' in the constructed value use '{{' in the value-pattern. Likewise, '}}' will result in '}' in the value pattern.

Furthermore, a regular expression with a substitution pattern can be used to further manipulate an individual attribute value. The java.util.regex.Pattern and java.util.regex.Matcher classes are used to perform the substitution. The regular expression with replacement value uses this syntax '{attr-name:/regex/replacement/flags}'.

'attr-name' is an attribute name such as 'cn'.

'regex' is a regular expression using the syntax described in the java.util.regex.Pattern javadoc. The optional flags value can also be used to change how this regular expression is interpreted.

'replacement' is a replacement value that is passed to the java.util.regex.Matcher#replaceFirst or java.util.regex.Matcher#replaceAll method to perform the replacement. The 'g' (global) flag controls whether replaceFirst or replaceAll is called.

'flags' is an optional set of single character flags that control how the regular expression is interpreted and how the replacement is performed. The flags are:

  • 'g' : Matcher#replaceAll is called instead of Matcher#replaceFirst to replace all matching values instead of just the first one.
  • 'i' : the regex pattern is compiled with Pattern.CASE_INSENSITIVE.
  • 'x' : the regex pattern is compiled with Pattern.COMMENTS.
  • 's' : the regex pattern is compiled with Pattern.DOTALL.
  • 'm' : the regex pattern is compiled with Pattern.MULTILINE.
  • 'u' : the regex pattern is compiled with Pattern.UNICODE_CASE.
  • 'd' : the regex pattern is compiled with Pattern.UNIX_LINES.
The substitution value is constructed using Java code equivalent to:

Pattern pattern = Pattern.compile(regex, flagsMask);
Matcher matcher = pattern.matcher(attributeValueInput);
String substitutionValueOutput = matcher.replaceFirst(replacement);

To extract JSON fields within JSON attributes append '.' and then the JSON field to extract to the attribute name. For example, if 'ubidEmailJSON' is a JSON attribute and the 'value' field is to be extracted then 'ubidEmailJSON.value' could be specified for the attribute name resulting in '{ubidEmailJSON.value}' or '{ubidEmailJSON.value:/regex/replacement/flags}' if a regular expression is to be used.

In addition, a JSON object filter may be provided in parentheses after the JSON field name to indicate that the field value will only be extracted if the attribute value matches the provided filter. For example, if 'ubidEmailJSON' is a JSON attribute and the 'value' field is to be extracted only for values where the 'type' field is equal to 'work', then the value pattern that would specify this would be '{ubidEmailJSON.value({{"filterType":"equals","field":"type","value":"work"}})}' or '{ubidEmailJSON.value({{"filterType":"equals","field":"type","value":"work"}})}:/regex/replacement/flags' if a regular expression is to be used. Note that all instances of '{' and '}' need to be escaped as '{{' and '}}' within the constructed value including those in the JSON object filter.

To apply modifiers to the values extracted append ':' and then the name of the modifier to apply. For example, if attribute 'mail' is to be included in a constructed JSON value then modifier 'jsonEscape' could be specified resulting in '{{ "userMail":"{mail:jsonEscape}" }}' or '{{ "userMail":"{mail:/regex/replacement/flags:jsonEscape}" }}' if a regular expression is to be used. Note that '{{' expands to '{' and '}}' to '}'. The modifiers are:

  • 'jsonEscape' : Escape text for use in a JSON value.
  • 'lowerCase' : Convert text to lower case.
  • 'trim' : Remove leading and trailing whitespace.
  • 'upperCase' : Convert text to upper case.
Here is an example to summarize these points. Suppose, the 'uid' virtual attribute needs to be populated with the initials of the first and last name followed by the user's employee number which is stored in the 'eid' attribute. For example, 'John Smith' with an employee id of 12345, would get a uid of 'js12345'. The value-pattern would be '{givenname:/^(.)(.*)/$1/s:lowerCase}{sn:/^(.)(.*)/$1/s:lowerCase}{eid}'. The employee's initials are extracted from the 'givenname' and 'sn' attributes. The '^(.).*' regular expression used for these attributes matches the entire value and stores the initial character in the $1 variable, which is used for the replacement. (The 's' flag is used to guard against the unlikely event that the user's 'givenname' or 'sn' attribute includes a newline character.) The lowerCase modifier converts the character to lowercase. The mapping will fail if the givenname or sn attributes are not present on an entry or if both attributes have multiple values.
Default Value
None
Allowed Values
The pattern to use to construct the attribute value.
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action


Advanced Properties

require-explicit-request-by-name (Advanced Property)

Description
Indicates whether attributes of this type must be explicitly included by name in the list of requested attributes. Note that this will only apply to virtual attributes which are associated with an attribute type that is operational. It will be ignored for virtual attributes associated with a non-operational attribute type. If this is true and the associated attribute type is operational, then virtual attributes of this type will only be returned in a search result entry if the attribute type was specifically included in the list of requested attributes but will not be returned if the client only requested "+" (to indicate all operational attributes) but did not explicitly mention this attribute. This should generally only be set to "true" for virtual attributes which may be expensive to construct and for which it is known that the attribute will always be explicitly requested by the client when it is needed.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

multiple-virtual-attribute-evaluation-order-index (Advanced Property)

Description
Specifies the order in which virtual attribute definitions for the same attribute type will be evaluated when generating values for an entry. Evaluation will occur in ascending order, so a virtual attribute definition with an evaluation order index of one will be evaluated before a definition with an evaluation order index of two. Virtual attribute definitions with no evaluation order index will be evaluated after those which do have a defined order. It is not necessary for evaluation order index values to be in consecutive order, and there may be gaps between values.
It is also acceptable for multiple virtual attribute definitions for the same attribute to have the same evaluation order index value. In that case, definitions with the same evaluation order index for the same attribute type will be evaluated in case-insensitive lexicographic order based on the name of the config definition.
For virtual attribute definitions pertaining to single-valued attributes, only the first applicable virtual attribute definition will be applied to the entry. For multi-valued attributes, it is possible for multiple virtual attribute definitions to be merged or to only use the first definition encountered, based on the value of the multiple-virtual-attribute-merge-behavior configuration property.
Default Value
None
Allowed Values
An integer value. Lower limit is 1. Upper limit is 2147483647 .
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

multiple-virtual-attribute-merge-behavior (Advanced Property)

Description
Specifies the behavior that will be exhibited for cases in which multiple virtual attribute definitions apply to the same multivalued attribute type. This will be ignored for single-valued attribute types. Although it is possible that multiple virtual attribute definitions exist for the same attribute type with different multiple-virtual-attribute-merge-behavior values, only the merge behavior specified in the first definition evaluated for an attribute type will be used for all subsequent definitions for that attribute. Similarly, the conflict behavior specified for the first definition evaluated for an attribute type will be used for all subsequent definitions for that attribute.
Default Value
use-all-definitions
Allowed Values
use-first-definition - Only the first applicable virtual attribute definition should be applied to the entry, even if there are other definitions with the same evaluation order index. See the documentation for the multiple-virtual-attribute-evaluation-order-index property for more information on the order in which virtual attribute definitions are evaluated.

use-only-definitions-with-the-lowest-evaluation-order-index - Only virtual attribute definitions with the same evaluation order index as the first applicable definition evaluated should be applied to the entry. Multiple definitions with the same evaluation order index may be applied to the entry, but only if that evaluation order index is the lowest of all applicable virtual attribute definitions for that attribute type.

use-all-definitions - All applicable virtual attribute definitions should be applied to the entry, regardless of the evaluation order index values for those definitions.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

allow-index-conflicts (Advanced Property)

Description
Indicates whether the server should allow creating or altering this virtual attribute definition even if it conflicts with one or more indexes defined in the server. In general, virtual attributes should not be used to generate values for indexed attributes. Any search targeting an indexed attribute will only return entries with real values matching the filter and will not return entries with matching virtual values.
It is recommended that you only permit the use of virtual attributes for indexed attribute types if you are certain that the conflict will not be significant (e.g., if you are certain that indexed searches will only target real values, or if you are certain that virtual values will only be generated for non-indexed backends).
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured Virtual Attributes:

dsconfig list-virtual-attributes
     [--property {propertyName}] ...

To view the configuration for an existing Virtual Attribute:

dsconfig get-virtual-attribute-prop
     --name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Virtual Attribute:

dsconfig set-virtual-attribute-prop
     --name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new Constructed Virtual Attribute:

dsconfig create-virtual-attribute
     --name {name}
     --type constructed
     --set enabled:{propertyValue}
     --set attribute-type:{propertyValue}
     --set value-pattern:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Virtual Attribute:

dsconfig delete-virtual-attribute
     --name {name}