The composed attribute plugin provides the following configuration properties:
  • plugin-type - The plugin type values for which the server will be registered. This is a mandatory multi-valued property with a default that includes all of the ldifimport, preoperationadd, preoperationmodify, and preoperationmodifydn values. It is recommend in general that you do not override this default set, but this may 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 DN operations.
  • attribute-type - The name or OID of the attribute type for which values are to be generated. This attribute type must be defined in the schema. This is a mandatory, single-valued property with no default. If multiple composed attribute types are desired, then a separate instance of the plugin should be configured for each. However, if multiple values should be composed for the same attribute type from different sets of source attributes, then a single instance of the plugin is recommended with multiple value patterns.
  • value-pattern - The value pattern that specifies the logic that should be used when constructing 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 will be preserved. If this is configured with multiple values, then the behavior the plugin should exhibit will be controlled by the multiple-value-pattern-behavior property. Note that a value pattern will only be used for an entry if that entry contains all of the attributes referenced in the value pattern. Also note that 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 will be a single-valued property with a default value of use-first-non-rejected-value-pattern-with-non-empty-values-but-may-reject.
    Note: The primary reason that a rejection may 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-may-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 will be generated. If no value pattern yields a non-empty result but at least one is rejected, then the operation will fail, or the entry will be 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 will be 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) will be rejected. If none of the value patterns is not rejected and yields a non-empty result, then no composed value will be generated.
    • use-all-non-rejected-value-patterns-with-non-empty-values-but-may-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 will be used. If none of the value patterns yielded non-empty results but none were rejected, then no composed value will be generated. If none of the value patterns yielded non-empty results and at least one was rejected, then the operation will fail or the LDIF entry will be 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 will be used. If none of the value patterns yielded non-empty results (regardless of whether any of them was rejected), then no composed value will be 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 will fail or the LDIF entry will be rejected. If none of the value patterns is rejected but none of them generates any values, then no composed values will be 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. Note that at most one source attribute may 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 may fail. This will be 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 will be 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 will be used so that the entry will not be 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 will be 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 construct 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 will be discarded.
    • merge-existing-and-composed-values - Indicates that the server should preserve any existing values for the target attribute, but should also construct any additional values.
      Note: This option may 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 that it should preserve any existing values when performing an LDIF import. Note that the server will 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 that it 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 modify DN operations that alter values for one of the attributes used in the value pattern. This will be a single-valued property with a default of replace-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 will be 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 will be a single-valued property with a default of preserve-non-composed-values. The available options include:
    • preserve-non-composed-values - Indicates that the server will attempt to remove any values for the target attribute that would have been generated for that entry by the associated value patterns, but that it will preserve any other values that may 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 will be preserved to avoid violating the schema.
    • preserve-all-values - Indicates that the server will preserve 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 will attempt to remove all values for the target attribute from the entry, regardless of whether they would have been composed, but that it will fall 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 will attempt to remove all values for the target attribute from the entry, regardless of whether they would have been composed, but that it will fall back to a behavior of preserve-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 modify DN operation. This will be a single-valued property with a default of always-allow. The aAvailable options include
    • always-allow - Indicates that the server will always permit 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 will only permit clients to alter values for the target attribute that were not generated by the plugin. Attempts to alter composed values will be rejected.
    • never-allow - Indicates that the server should reject any attempt to alter the target attribute, regardless of the values it may have.
  • include-base-dn - A base DN that may be used to restrict the set of entries for which values will be composed. The include/exclude criteria configuration options are described in more detail below.
  • exclude-base-dn - A base DN that may be used to restrict the set of entries for which values will be composed. The include/exclude criteria configuration options are described in more detail below.
  • include-filter - A search filter that may be used to restrict the set of entries for which values will be composed. The include/exclude criteria configuration options ware described in more detail below.
  • exclude-filter - A search filter that may be used to restrict the set of entries for which values will be composed. The include/exclude criteria configuration options are described in more detail below.
  • 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 will be 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 will be preserved and no additional composed values will be added. If the entry did not contain the target attribute, then no composed values will be 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 will be preserved and no additional composed values will be added. However, if the entry did not contain the target attribute, then composed values will be 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 will be preserved and any additional values that would be composed for that entry will also be added. If the entry did not contain the target attribute, then composed values will be 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 will be 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 will be 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 will 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 will be a single-valued property with a default of preserve-all-values. The avvailable options include:
    • preserve-all-values - Indicates that the server will preserve 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 will attempt to remove any values for the target attribute that would have been generated for that entry by the associated value patterns, but will preserve any other values that may 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 will be preserved to avoid violating the schema.
    • remove-all-values-but-preserve-all-if-required - Indicates that the server will attempt to remove all values for the target attribute from the entry, regardless of whether they would have been composed, but that it will fall 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 will attempt to remove all values for the target attribute from the entry, regardless of whether they would have been composed, but that it will fall back to a behavior of preserve-non-composed-values if the target attribute type is required by any of the entry’s object classes.

By default, attribute values will be composed for every entry in any public backend that contains all of the source attributes used in the appropriate value patterns. If you wish to restrict composed values to a specific set of entries, that can be done with the include-base-dn, exclude-base-dn, include-filter, and exclude-filter properties.

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

If the include-filter property is provided, then values will only be composed for entries that match at least one of those filters. If the exclude-filter property is provided, then values will not be 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 will take precedence, and values will not be generated for that entry. If neither property is specified, then the server will behave as if an include filter of “(&)” had been specified. Note that no virtual attributes will be considered when evaluating this filter, although composed values may be taken into consideration. See Composed attribute dependency considerations for more information about the order in which composed attribute definitions will be evaluated.