Page created: 4 Feb 2020
|
Page updated: 22 Jul 2020
Before the server parses the template file to generate a message, it pre-processes the file
with the Apache Velocity templating engine (https://velocity.apache.org/). This enables
you to customize the message content with information from the account status
notification, details from the associated user entry, and other information. The
following variables are defined for use with custom directives:
- $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 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:
- #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 offalse
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 offalse
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 thefirst
field inside a JSON object that is a value for the outername
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 thefirst
field inside a JSON object that is a value for the outername
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 offalse
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
, orsubordinates
), 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 offalse
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 offalse
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 offalse
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 offalse
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.
- #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.
- #getFormattedTimestamp(timestamp, formatString, 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) 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 given 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 offalse
is stored.
The following account status notification properties are available for use in conjunction with
the #getNotificationPropertyValue and
#getNotificationPropertyValues directives:
- 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 -- A value of
true
if the account is considered usable, orfalse
if it is not usable (for example, if the account is locked/expired/not yet active, if the password is expired, if the user must choose a new password, etc.). - 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
true
if the account has been administratively disabled, orfalse
if it has not been administratively disabvled. - account-is-not-yet-active -- The value
true
if the account has an activation time in the future, orfalse
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 that is 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 that is in the future.
- seconds-since-account-activation -- The number of seconds since the account became active if it has an activation time that is 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 that is in the past.
- account-is-expired -- The value
true
if the account has an expiration time in the past, orfalse
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
true
if the account has been temporarily or permanently locked due to too many failed authentication attempts, orfalse
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 due to 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
true
if the account is locked because it has been too long since the user last authenticated, orfalse
if not. - idle-lockout-interval-seconds -- The maximum number of seconds that may pass between successful authentications before an account becomes idle-locked, if configured.
- idle-lockout-interval -- A human-readable duration that indicates how much time may 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
true
if the account is locked because the user failed to choose a new password in a timely manner after an administrative password reset, orfalse
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
true
if the user will be required to choose a new password before they are allowed to perform any other operations on the server, orfalse
if not. - account-was-unlocked -- The value
true
if the account had been locked but was just unlocked by the associated operation, orfalse
if not. - password-is-expired -- The value
true
if the account has an expired password, orfalse
if not. - password-is-expiring -- The value
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), orfalse
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 that is 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 that is 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 that is 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.