PingDirectory

Composed attribute plugin configuration properties

The composed attribute plugin provides the following configuration properties.

Configuration properties

plugin-type

The plugin type values for which the server is registered.

This is a mandatory multi-valued property with a default that includes all of the ldifimport, preoperationadd, preoperationmodify, and preoperationmodifydn values. In general, you should not override this default set, but this might be useful in some rare corner cases. The available options include:

ldifimport

Indicates that values should be generated for the target attribute in any appropriate entries created during LDIF import processing.

preoperationadd

Indicates that values should be generated for the target attribute in any appropriate entries created by add operations.

preoperationmodify

Indicates that values should be generated or altered for the target attribute in any appropriate entries updated by modify operations.

preoperationmodifydn

Indicates that values should be generated or altered for the target attribute in any appropriate entries updated by modify distinguished name (DN) operations.

attribute-type

The name or OID of the attribute type for which values are generated.

This attribute type must be defined in the schema. This is a mandatory, single-valued property with no default. To have multiple composed attribute types, configure a separate instance of the plugin for each attribute type. To compose multiple values for the same attribute type from different sets of source attributes, use a single instance of the plugin with multiple value patterns.

value-pattern

The value pattern that specifies the logic that should be used when composing values.

This pattern must be compatible with the format expected by the com.unboundid.directory.server.sync.mapping.ConstructedValue class. This is a mandatory, multi-valued property in which the order of the values is preserved. If this is configured with multiple values, then the behavior the plugin should exhibit is controlled by themultiple-value-pattern-behavior property.

A value pattern is only used for an entry if that entry contains all of the attributes referenced in the value pattern.

Virtual attributes are not considered when generating values.

multiple-value-pattern-behavior

The behavior that the server should exhibit if multiple value-pattern values are configured.

This is a single-valued property with a default value of use-first-non-rejected-value-pattern-with-non-empty-values-but-might-reject.

The primary reason that a rejection might occur is as a result of multivalued source attributes, but it could also occur if an unexpected error occurs while trying to generate values.

The available options include:

use-first-non-rejected-value-pattern-with-non-empty-values-but-might-reject

Indicates that the server should only use values generated from the first value pattern that is not rejected and yields a non-empty result.

If all value patterns yield empty results, for example, if the entry is missing at least one source attribute for each of the value patterns, then no composed value is generated. If no value pattern yields a non-empty result but at least one is rejected, then the operation fails, or the entry is rejected if performing an LDIF import.

use-first-non-rejected-value-pattern-with-non-empty-values-and-never-reject

Indicates that the server should only use values generated from the first value pattern that is not rejected and yields a non-empty result.

If none of the value patterns yield non-empty results, regardless of whether any of them is rejected, then no composed value is generated.

use-first-rejection-or-first-value-pattern-with-non-empty-values

Indicates that the server should only use values generated from the first value pattern that yields non-empty results, but if a rejection is encountered before a non-empty result is obtained, then the operation or LDIF entry is rejected.

If none of the value patterns is not rejected and yields a non-empty result, then no composed value is generated.

use-all-non-rejected-value-patterns-with-non-empty-values-but-might-reject

Indicates that the server should use all values generated by all of the value patterns that were not rejected for the entry.

As long as at least one value pattern generated a non-empty result, then the entire set of values generated by all value patterns is used. If none of the value patterns yielded non-empty results but none were rejected, then no composed value is generated. If none of the value patterns yielded non-empty results and at least one was rejected, then the operation fails or the LDIF entry is rejected.

use-all-non-rejected-value-patterns-with-non-empty-values-and-never-reject

Indicates that the server should use all values generated by all of the value patterns that were not rejected for the entry.

As long as at least one value pattern generated a non-empty result, then the entire set of values generated by all value patterns is used. If none of the value patterns yielded non-empty results, regardless of whether any of them was rejected, then no composed value is generated.

use-first-rejection-or-all-value-patterns-with-non-empty-values

Indicates that the server should use all of the values generated by all of the value patterns as long as none of them is rejected.

If any value pattern is rejected, then the operation fails or the LDIF entry is rejected. If none of the value patterns is rejected but none of them generates any values, then no composed values are generated.

multi-valued-attribute-behavior

The behavior that the server should exhibit if any of the attributes used in the value pattern have multiple values.

No more than one source attribute should have multiple values. If multiple source attributes have multiple values, and if this property is configured to try to use all of them, then the attempt to generate composed values for the entry might fail.

This is a single-value property with a default value of use-all-values-if-possible-but-reject-if-not. Available options include:

use-first-value

Indicates that the server should only use the first value for each source attribute referenced in the value pattern.

With this value, entries should never be rejected for having multivalued attributes.

reject-entries-with-any-multivalued-source-attribute

Indicates that the server should reject any entry that has more than one value for any of the source attributes.

use-all-values-if-possible-but-reject-if-not

Indicates that the server should use all values for the source attributes as long as at most one of them has multiple values.

If multiple source attributes have multiple values, the entry is rejected.

use-all-values-if-possible-but-only-first-value-if-not

Indicates that the server should use all values for the source attributes as long as at most one of them has multiple values.

If multiple source attributes have multiple values, then only the first value from each source attribute is used so that the entry is not rejected.

target-attribute-exists-during-initial-population-behavior

The behavior that the server should exhibit for add operations and LDIF imports for entries that already contain one or more values for the target attribute.

This is a single-valued property with a default of preserve-existing-values. The available options include:

preserve-existing-values

Indicates that the server should preserve existing values in entries that are added or imported and should only compose values for entries that do not already contain the target attribute.

overwrite-existing-values

Indicates that the server should only use generated values for the target attribute and that any values provided during an add or LDIF import is discarded.

merge-existing-and-composed-values

Indicates that the server should preserve any existing values for the target attribute and should compose any additional values.

This option can only be used if the target attribute type allows multiple values.

reject-existing-values-in-add-but-preserve-in-ldif-import

Indicates that the server should reject any add operation that attempts to provide any values for the target attribute but should preserve any existing values when performing an LDIF import.

The server does not reject entries that already contain the target attribute when performing an LDIF import since this would interfere with the ability to export data to LDIF from a server that contains composed values and then re-import the LDIF file.

reject-existing-values-in-add-but-overwrite-in-ldif-import

Indicates that the server should reject any add operation that attempts to provide any values for the target attribute but should replace any existing values in an LDIF import with the values which would be composed for that entry.

reject-existing-values-in-add-but-merge-in-ldif-import

Indicates that the server should reject any add operation that attempts to provide any values for the target attribute but should preserve any existing values when performing an LDIF import and add any additional values that should be composed for the entry.

update-source-attribute-behavior

The behavior that the server should exhibit for entries that are updated by modify or modifyDN operations that alter values for one of the attributes used in the value pattern.

This is a single-valued property with a default ofreplace-composed-values. The available options include:

replace-composed-values

Indicates that the server should only update values for the target attribute that match those that would have been generated by the plugin.

Values that would not have been generated by the plugin are preserved.

replace-all-values

Indicates that the server should always replace the target attribute with new composed values even if the existing values were not generated by the plugin.

preserve-existing-values

Indicates that the server should always preserve the existing values for the target attribute even if they were generated by the plugin.

source-attribute-removal-behavior

The behavior that the server should exhibit when an entry is updated in a manner that removes one or more source attributes needed to compose values for the target attribute.

This is a single-valued property with a default of preserve-non-composed-values. The available options include:

preserve-non-composed-values

Indicates that the server attempts to remove any values for the target attribute that would have been generated for that entry by the associated value patterns but preserves any other values that might exist for the target attribute.

If the target attribute is required by any of the object classes in the entry and if that entry only contains composed values for the target attribute, then the composed values are preserved to avoid violating the schema.

preserve-all-values

Indicates that the server preserves any values that exist for the target attribute regardless of whether they would have been composed by any of the value patterns.

remove-all-values-but-preserve-all-if-required

Indicates that the server attempts to remove all values for the target attribute from the entry, regardless of whether they would have been composed but falls back to a behavior of preserve-all-values if the target attribute type is required by any of the entry’s object classes.

remove-all-values-but-preserve-non-composed-values-if-required

Indicates that the server attempts to remove all values for the target attribute from the entry, regardless of whether they would have been composed but falls back to a behavior ofpreserve-non-composed-values if the target attribute type is required by any of the entry’s object classes.

update-target-attribute-behavior

The behavior that the server should exhibit when a client attempts to alter the target attribute with a modify or modifyDN operation.

This is a single-valued property with a default of always-allow. The available options include:

always-allow

Indicates that the server always permits clients to alter the value of the target attribute regardless of whether these values were generated.

allow-only-for-non-composed-values

Indicates that the server only permits clients to alter values for the target attribute that were not generated by the plugin.

Attempts to alter composed values are rejected.

never-allow

Indicates that the server should reject any attempt to alter the target attribute regardless of the values it might have.

include-base-dn

A base DN that might be used to restrict the set of entries for which values are composed.

The following section provides a detailed description of the include and exclude criteria configuration options.

exclude-base-dn

A base DN that might be used to restrict the set of entries for which values are composed.

The following section provides a detailed description of the include and exclude criteria configuration options.

include-filter

A search filter that might be used to restrict the set of entries for which values are composed.

The following section provides a detailed description of the include and exclude criteria configuration options.

exclude-filter

A search filter that might be used to restrict the set of entries for which values are composed.

The following section provides a detailed description of the include and exclude criteria configuration options.

updated-entry-newly-matches-criteria-behavior

The behavior that the server should exhibit if an entry that previously did not satisfy either the base DN or filter criteria, but is updated so that it does match any configured base DN or filter criteria.

This is a single-valued property with a default value of preserve-existing-values-and-compose-new-values. The available options include:

preserve-existing-values-without-composing-new-values

Indicates that if the entry already had one or more values for the target attribute, those values are preserved and no additional composed values are added.

If the entry did not contain the target attribute, then no composed values are generated for the entry.

preserve-existing-values-or-compose-new-values

Indicates that if the entry already had one or more values for the target attribute, those values are preserved and no additional composed values are added.

If the entry did not contain the target attribute, then composed values are generated for the entry.

preserve-existing-values-and-compose-new-values

Indicates that if the entry already had one or more values for the target attribute, those values are preserved and any additional values that would be composed for that entry is also added.

If the entry did not contain the target attribute, then composed values are generated for the entry.

compose-new-values-without-preserving-existing-values

Indicates that if the entry already had one more composed values for the target attribute, then those values are removed and replaced with the composed values that would be generated for it

If the entry did not contain the target attribute, then composed values are generated for it. If no composed values would be generated for the entry, for example, if it was missing at least one source attribute for each value pattern, then the entry does not include the target attribute, regardless of whether it contained existing values for the attribute.

updated-entry-no-longer-matches-criteria-behavior

The behavior that the server should exhibit if an entry previously satisfied the configured base DN and filter criteria but has been updated so that it no longer matches that criteria.

This is a single-valued property with a default of preserve-all-values. The available options include:

preserve-all-values

Indicates that the server preserves any values that exist for the target attribute regardless of whether they would have been composed by any of the value patterns.

preserve-non-composed-values

Indicates that the server attempts to remove any values for the target attribute that would have been generated for that entry by the associated value patterns but preserves any other values that might exist for the target attribute.

However, if the target attribute is required by any of the object classes in the entry, and if that entry only contains composed values for the target attribute, then the composed values are preserved to avoid violating the schema.

remove-all-values-but-preserve-all-if-required

Indicates that the server attempts to remove all values for the target attribute from the entry, regardless of whether they would have been composed but falls back to a behavior ofpreserve-all-values if the target attribute type is required by any of the entry’s object classes.

remove-all-values-but-preserve-non-composed-values-if-required

Indicates that the server attempts to remove all values for the target attribute from the entry, regardless of whether they would have been composed but falls back to a behavior of preserve-non-composed-values if the target attribute type is required by any of the entry’s object classes.

Include and exclude criteria configuration

Attribute values are composed by default for every entry in any public backend that contains all of the source attributes used in the appropriate value patterns. To restrict composed values to a specific set of entries, use the include-base-dn, exclude-base-dn, include-filter, and exclude-filter properties.

If the include-base-dn property is provided, then values are composed for entries at or below one of those base DNs. If theexclude-base-dn property is provided, then values are not composed for any entries at or below one of those base DNs. If both properties are provided and a given entry follows both an include and an exclude base DN, then the exclude base DN takes precedence and values are not generated for that entry. If neither property is specified, then the naming contexts of all public backends are used as the default set of include base DNs.

If the include-filter property is provided, then values are composed for entries that match at least one of those filters. If the exclude-filter property is provided, then values are not composed for any entries that match at least one of those filters. If both properties are provided and a given entry matches both include and exclude filters, then the exclude filter takes precedence and values are not generated for that entry. If neither property is specified, then the server behaves as if an include filter of "&" had been specified.

No virtual attributes are considered when evaluating this filter although composed values might be taken into consideration. For more information about the order in which composed attribute definitions are evaluated, see Composed attribute dependency considerations.