PingDirectory

Customizing the message content

Before the server parses the template file to generate a message, it pre-processes the file with the Apache Velocity templating engine. This enables you to customize the message content with information from the account status notification, details from the associated user entry, and other information. For more information about Apache Velocity, see https://velocity.apache.org/.

The following variables are defined for use with custom directives.

Variable Description

$account_entry

The entry for the user associated with the account status notification.

$notification_type

The name of the notification type for the account status notification.

$notification_message

A human-readable message that provides a basic description of the account status notification.

$before_entry

A version of the associated entry as it appeared before the operation was processed.

This is only available for notifications generated as a result of modify or modify distinguished name (DN) operations.

$after_entry

A version of the associated entry as it appeared after the operation was processed.

This is only available for notifications generated as a result of modify or modify DN operations.

In addition to the built-in directives provided by Velocity, the following custom directives are also available.

Directive Syntax Description

#getEntryDN

entry, variableName

Retrieves a string representation of the provided entry’s DN and stores it in the specified Velocity context variable.

#getHasAttribute

entry, attributeName, variableName

Determines if the provided entry includes the specified attribute.

If it contains the specified attribute, a value of true is stored in the specified Velocity context variable. If not, a value of false is stored.

#getUserAttributeNames

entry, variableName

Retrieves a list of the names of the user attributes contained in the provided entry and stores this list in the specified Velocity context variable.

#getOperationalAttributeNames

entry, variableName

Retrieves a list of the names of the operational attributes contained in the provided entry and stores this list in the specified Velocity context variable.

#getAttributeValue

entry, attributeName, variableName

Retrieves the first value for the indicated attribute from the provided entry and stores it in the specified Velocity context variable.

If the attribute is not present in the entry, the variable is removed from the context.

#getAttributeValues

entry, attributeName, variableName

Retrieves the list of values for the indicated attribute from the provided entry and stores this list in the specified Velocity context variable.

If the attribute is not present in the entry, an empty list is stored.

#getEntryMatchesLDAPFilter

entry, filterString, variableName

Determines if the provided entry matches the LDAP filter with the given string representation.

If the entry matches, a value of true is stored in the Velocity context variable. Otherwise, a value of false is stored.

#getJSONObjectValue

entry, attributeName, variableName

Retrieves the first value that can be parsed as a JSON object for the indicated attribute and stores this object in the specified variable in the Velocity context.

If the attribute does not exist in the provided entry, or if none of its values can be parsed as a JSON object, the variable is removed from the context.

#getJSONObjectValues

entry, attributeName, variableName

Retrieves a list of all values that can be parsed as JSON objects for the indicated attribute and stores this list in the specified variable in the Velocity context.

If the attribute does not exist in the provided entry, or if none of its values can be parsed as JSON objects, an empty list is stored.

#getJSONFieldValue

jsonObject, fieldName, variableName

Retrieves the first value for the indicated field from the provided JSON object and stores its string representation in the specified Velocity context variable.

Nested fields can be targeted by using the period as a delimiter between field names.

For example, name.first targets the first field inside a JSON object that is a value for the outer name field.

If the field does not exist in the provided object, the variable is removed from the context.

#getJSONFieldValues

jsonObject, fieldName, variableName

Retrieves all values for the indicated field from the provided JSON object and stores a list of their string representations in the specified Velocity context variable.

Nested fields can be targeted by using the period as a delimiter between field names.

For example, name.first targets the first field inside a JSON object that is a value for the outer name field.

If the field does not exist in the provided object, or if its value is an empty array, an empty list is stored.

#getJSONObjectMatchesFilter

jsonObject, jsonObjectFilterString, variableName

Determines if the provided JSON object matches the JSON object filter with the given string representation.

If the JSON object matches, a value of true is stored in the specified Velocity context variable. Otherwise, a value of false is stored.

#getEntry

entryDN, variableName

Retrieves the entry with the provided DN from the server and stores it in the specified Velocity context variable.

If the entry does not exist, the variable is removed from the context.

#searchForEntries

baseDN, scopeString, filterString, variableName

Performs an internal search with the provided base DN; scope, which must be one of base, one, sub, or subordinates; and filter; and stores the list of matching entries in the specified variable in the context.

If the search does not match any entries, if it matches more than 20 entries, or if the search criteria is not indexed, then an empty list is stored.

#getParentDN

entryDN, variableName

Determines the parent DN for the provided entry DN and stores it in the specified Velocity context variable.

If the provided DN contains only a single component, an empty string is stored.

If the provided DN is the null DN, and therefore does not have a parent, the variable is removed from the context.

#getIsAttributeModified

beforeEntry, afterEntry, attributeName, variableName

Determines if the indicated attribute has been modified between the provided before and after representations of the entry.

If the attribute has been modified, a value of true is stored in the specified Velocity context variable. Otherwise, a value of false is stored.

#getIsAnyAttributeModified

beforeEntry, afterEntry, attributeName1, attributeName2, …​, variableName

Determines if at least one of the listed attributes has been modified between the provided before and after representations of the entry.

If at least one of the listed attributes has been modified, a value of true is stored in the specified Velocity context variable. Otherwise, a value of false is stored.

The first two arguments to this directive must be the before and after representations of the target entry, and the last argument must be the name of the variable in which to store the result. All arguments in between these are treated as the names or OIDs of the attributes for which to make the determination. At least one attribute name or OID must be provided.

#getModifiedAttributeNames

beforeEntry, afterEntry, variableName

Determines which attributes have been modified between the provided before and after representations of the entry, and stores a list of their names in the specified Velocity context variable

If the provided entries are identical, an empty list is stored.

#getModifiedAttributeAddedValues

beforeEntry, afterEntry, attributeName, variableName

Retrieves a list of the values that have been added between the provided before and after representations of an entry for the indicated attribute, and stores this list in the specified Velocity context variable.

If the attribute was not altered, or if values were only removed from the attribute, an empty list is stored.

#getModifiedAttributeRemovedValues

beforeEntry, afterEntry, attributeName, variableName

Retrieves a list of the values that have been removed between the provided before and after representations of an entry for the indicated attribute, and stores this list in the specified Velocity context variable.

If the attribute was not altered, or if values were only added to the attribute, an empty list is stored.

#getOperationMatchesConnectionCriteria

criteriaDN, variableName

Determines if the operation that triggered the notification matches the connection criteria defined in the entry with the specified DN.

If it matches, a value of true is stored in the specified Velocity context variable. Otherwise, a value of false is stored.

#getOperationMatchesRequestCriteria

criteriaDN, variableName

Determines if the operation that triggered the notification matches the request criteria defined in the entry with the specified DN.

If it matches, a value of true is stored in the specified Velocity context variable. Otherwise, a value of false is stored.

#getNotificationPropertyNames

variableName

Retrieves a list of the names of the account status notification properties that are defined for the notification and stores this list in the specified Velocity context variable.

#getNotificationPropertyValue

propertyName, variableName

Retrieves the first value for the given account status notification property and stores it in the specified Velocity context variable. If the property is not defined, the variable is removed from the context.

See the following table for propertyName values.

#getNotificationPropertyValues

propertyName, variableName

Retrieves the list of values for the given account status notification property and stores this list in the specified Velocity context variable.

If the property is not defined, an empty list is stored.

See the following table for propertyName values.

#getFormattedTimestamp

timestamp, formatString, variableName

Retrieves a representation of the provided timestamp, which must be in generalized time form, formatted with the provided format string, which must be compatible with the java.text.SimpleDateFormat class, and stores it in the specified Velocity context variable.

The default time zone of the JVM is used.

#getFormattedTimestamp

timestamp, formatString, timeZone, variableName

Retrieves a representation of the provided timestamp, which must be in generalized time form, formatted with the given format string, which must be compatible with the java.text.SimpleDateFormat class, in the indicated time zone, which must be compatible with the java.time.ZoneId class, and stores it in the specified Velocity context variable.

#getFileExistsInTemplateDirectory

fileName, variableName

Determines if a file with the provided name, which must not contain path information, exists in the same directory as the template.

If the file exists, a value of true is stored in the specified Velocity context variable. Otherwise, a value of false is stored.

The following account status notification properties are available for use in conjunction with the #getNotificationPropertyValue and #getNotificationPropertyValues directives.

Property Description

notification-type

The name of the account status notification type.

notification-time

A generalized time representation of the time that the notification was generated.

account-dn

The DN of the entry for the associated user account.

password-policy-dn

The DN of the password policy that governs the associated user account.

password-changed-time

A generalized time representation of the time the user’s password was last changed.

seconds-since-password-change

The number of seconds since the account’s password was last changed.

time-since-password-change

A human-readable duration indicating the length of time since the user’s password was last changed.

account-is-usable

The value is true if the account is considered usable, or false if it is not usable.

The account is considered unusable if, for example, the account is locked, expired, or not yet active; if the password is expired; if the user must choose a new password; and so on.

account-usability-errors

A list of human-readable strings providing information about any errors that currently affect the account’s usability.

account-usability-warnings

A list of human-readable strings providing information about any warning conditions that have the potential to affect the account’s usability in the near future.

account-usability-notices

A list of human-readable strings providing information about any notable account state conditions that are not expected to affect the account’s usability in the near future.

account-is-disabled

The value is true if the account has been administratively disabled, or false if it has not been administratively disabled.

account-is-not-yet-active

The value is true if the account has an activation time in the future, or false if not.

account-activation-time

A generalized time representation of the account activation time, if defined.

seconds-until-account-activation

The number of seconds until the account becomes active if it has an activation time in the future.

time-until-account-activation

A human-readable duration indicating the length of time until the account becomes active if it has an activation time in the future.

seconds-since-account-activation

The number of seconds since the account became active if it has an activation time in the past.

time-since-account-activation

A human-readable duration indicating the length of time since the account became active if it has an activation time in the past.

account-is-expired

The value is true if the account has an expiration time in the past, or false if not.

account-expiration-time

A generalized time representation of the account expiration time, if defined.

seconds-until-account-expiration

The number of seconds until the account expires if it has an expiration time in the future.

time-until-account-expiration

A human-readable duration indicating the length of time until the account expires if it has an expiration time in the future.

seconds-since-account-expiration

The number of seconds since the account expired if it has an expiration time in the past.

time-since-account-expiration

A human-readable duration indicating the length of time since the account expired if it has an expiration time in the past.

account-is-failure-locked

The value is true if the account has been temporarily or permanently locked because of too many failed authentication attempts, or false if not.

failure-locked-time

A generalized time representation of the time that the account became failure-locked, if applicable.

account-unlock-time

A generalized time representation of the time that the account will be automatically unlocked, if it is temporarily locked because of too many failed authentication attempts.

seconds-until-unlock

The number of seconds until the account unlock time, if applicable.

time-until-unlock

A human-readable duration indicating the length of time until the account unlock time, if applicable.

failure-lockout-count

The number of failed authentication attempts required to lock an account, if configured.

failure-lockout-duration-seconds

The number of seconds that a failure-locked account will be prevented from authenticating, if defined.

failure-lockout-duration

A human-readable duration that indicates how long a failure-locked account will be prevented from authenticating, if defined.

account-is-idle-locked

The value is true if the account is locked because it has been too long since the user last authenticated, or false if not.

idle-lockout-interval-seconds

The maximum number of seconds that can pass between successful authentications before an account becomes idle-locked, if configured.

idle-lockout-interval

A human-readable duration that indicates how much time can pass between successful authentications before an account becomes idle-locked, if configured.

last-login-time

A generalized time representation of the time that the user last successfully authenticated, if available.

seconds-since-last-login

The number of seconds that have passed since the user last successfully authenticated, if available.

time-since-last-login

A human-readable duration indicating the length of time that has passed since the user last successfully authenticated, if available.

last-login-ip-address

The IP address of the client from which the user last authenticated, if available.

account-is-reset-locked

The value is true if the account is locked because the user failed to choose a new password in a timely manner after an administrative password reset, or false if not.

maximum-password-reset-age-seconds

The maximum number of seconds that a user has to choose a new password after an administrative password reset before the account becomes reset-locked, if defined.

maximum-password-reset-age

A human-readable duration indicating the maximum length of time that a user has to choose a new password after an administrative password reset before the account becomes reset-locked, if defined.

must-change-password

The value is true if the user will be required to choose a new password before they are allowed to perform any other operations on the server, or false if not.

account-was-unlocked

The value is true if the account had been locked but was just unlocked by the associated operation, or false if not.

password-is-expired

The value is true if the account has an expired password, or false if not.

password-is-expiring

The value is true if the account has a password that will expire in the near future, as determined by the password-expiration-warning-interval property in the associated password policy, or false if not.

maximum-password-age-seconds

The maximum number of seconds that an account is permitted to keep the same password before it expires, if defined.

maximum-password-age

A human-readable duration indicating the maximum length of time that an account is permitted to keep the same password before it expires, if defined.

maximum-password-age

A human-readable duration indicating the maximum length of time that an account is permitted to keep the same password before it expires, if defined.

password-expiration-time

A generalized time representation of the time that the account’s password did or will expire, if applicable.

seconds-until-password-expiration

The number of seconds until the account’s password will expire, if it has an expiration time in the future.

time-until-password-expiration

A human-readable duration indicating the length of time until the account’s password will expire, if it has an expiration time in the future.

seconds-since-password-expiration

The number of seconds since the account’s password expired, if it has an expiration time that is in the past.

time-since-password-expiration

A human-readable duration indicating the length of time since the account’s password expired, if it has an expiration time in the past.

old-password

The clear-text password that the account had before the associated operation was processed, if available.

new-password

The clear-text password that the account has after the associated operation was processed, if available.

new-generated-password

The clear-text password that was generated for the account by the associated operation, if applicable.

requester-ip-address

The IP address of the client that requested the associated operation, if available.

requester-dn

The DN of the account that requested the associated operation.

operation-type

The name of the operation type for the associated operation.

operation-id

A string representation of the operation ID for the associated operation.

connection-id

A string representation of the connection ID for the associated operation.

server-uuid

A string representation of the unique identifier generated for the server instance that processed the associated operation.

instance-name

The instance name for the server instance that processed the associated operation.