Working with distribution groups

Distribution Groups

A distribution group is used to broadcast to multiple recipients through a single address.

Windows Exchange environments

A common scenario is to want to work with distribution groups in Exchange.  

Open

An Active Directory view of a distribution group would look something like:

The list group name, and its email address	Members of the list group (users, and groups) - down	Wider higher level list groups that this could be a sub-part of

The list group name, and its email address	Members of the list group (users, and groups) - down	Wider higher level list groups that this could be a sub-part of
Open

Querying with JEMH

In 1.8.20 the new LDAP query interface allows AD to queried directly with matches rendered automatically as changes are made to the LDAP filter and required/expand attributes, here is a query showing the above:

1. Shows the LDAP filter configuration that must already exist, this defines the runtime configuration for distribution group filter (the LDAP filter (2) is used here instead to allow dynamic querying)

2. The LDAP filter that should be valid to match users within the BASE DN of the related LDAP configuration

3. The Expand Attributes are there to allow an attribute to be nominated that contains full Distinguished Name (DN) attribute values.  With Active Directory, the member attribute is the one required

4. When a structurally valid LDAP filter is present (matching bracket count!) the LDAP query will be re-executed with every query change, there is also a manual refresh button in the Results section.

5. When a group LDAP entry is found, and it has an email address associated (the 'mail' attribute is defined in the LDAP config), actions are possible, currently this is a simple TEXT export of JIRA users found (more details later)

6. When an Expand Attribute like member is identified and contains full DN's, they will be expanded and listed.  Here some default attributes like CN, sAMAccoutnName and mail attributes are listed in the concise view - they can be expanded to replicate the full view as shown in the top level record, and so on.  There is a depth maximum of 50 defined in JEMH currently.

7. Users will be listed without actions

Configuring JEMH for runtime distribution list expansion

Update LDAP Configuration

Once the distribution group has been located with an LDAP filter in the query interface above, the 'base' part of the filter needs to be setup within the LDAP configuration:

The filter given (1) executes within the BASE DN context.  At runtime it will be combined with discovered email addresses.  The Expand attribute (2) is also referred here.

Update JEMH Profile

With the LDAP configuration validated through querying and configured, the profile configuration is no more than selecting this LDAP Configuration.  See the Profile > Email section:

In order to use the broken down recipients as watchers, the toWatcher value (1) should be included in the Addressee Handling field:

When saved, the LDAP configuration will be shown (2).

Worked example

With the following example mail, the sender is a JIRA 'admin' user in JIRA.  The mailbox recipient address is changeme@thiswontwork.com (matched through the JEMH Profile > Email > Catch Email Address field), the distribution group address is on CC: dist-group@dev.ppl.com (it could be a direct To: recipient also)

The created issue gets 3 watchers, resolved through the distribution group:

The sender (Administrator@dev.ppl.com) was not added as a watcher due to Profile > Issue > Add Sender As Watcher OFF)

Log output:

 If JEMH logging is enabled, when LDAP user records are extracted from a distribution list (and its members, and recursive sub-members), they will be logged (see LDAP result: below)

LDAP query /process

The initial query to the LDAP server is made up from the LDAP configuration distribution group filter logically ANDed with an OR expression containing all the addressees of the email:

This provides the first 'set' of top level members that are groups or users.  Each sub-group is then queried and expanded individually.  As non-group user entries are found, their email addresses are added to a set of unique recipients.  On completion, these addresses are used to lookup JIRA users, where found, they are added as possible watchers, subject to further filtering/blacklisting.

Performance / Cluster Cache

For Enterprise performance, a JIRA Data Center compatible cache has been added for distribution list members, this means that where a given distribution list is already known, its members will not need to be resolved, saving lots of LDAP communication overhead.  Currently the LDAP cache self expiry is 1 hour, so new users added or removed will not appear for at most that time.  

Validating cache improvement

To confirm the performance improvement due to caching, restart JIRA or update JEMH, access the Test Cases screen and run a Test Case containing an 'interesting' distribution group address, note the Processing Time reported on the Test Case results screen, then repeat and contrast times.

Additional User / Group DN

The baseDN of your LDAP structure could be just DC=DEV,DC=PPL,DC=COM, or similar - LDAP queries that are made would traverse all structures to locate matches (possibly time consuming).  By specifying an AdditionalUserDN (e.g.  CN=Users) the structure that is searched would be started at the sub-node CN=Users,DC=DEV,DC=PPL,DC=COM.  Prior to JEMH 2.1.5 the AdditionalUserDN was prefixed to all queries, including distribution groups so if your additionalUserDN field was set, only groups under that path would be in scope (retrieved).  From JEMH 2.1.5 this has been improved, so that there is both an AdditionalUserDN as well as an AdditionalGroupDN.  The GroupDN is only used if specified otherwise the baseDN is used as-is.

Using distribution group members in notifications

You may want to use a centrally defined distribution group email address, expand that and pick out/filter some actual receipients (e.g. for inclusion in the mail content, or additional recipients).

Templates (Issue Event / Postfunction)

since 3.3.62

The helper class $jemhUtils is available in all templates, it exposes an LDAP Helper.

Accessing with $jemhUtils.getLdap()

Where a JEMH Profile is in context, the first of selected LDAP configurations will be used. If none are set, the first of the defined LDAP configurations will be used.

Using a specific LDAP Config with $jemhUtils.getLdap(nnn)

An LDAP Helper can be intialized with a specific config through $jemhUtils.getLdap(nnn) where nnn is the integer id of the LDAP config.

Logs

Lower level debug information can be found in the JEMH Log: Enabling JEMH logging

Example Adhoc velocity template

This example used Micro$oft Active Directory

Example adhoc render result:

Using distribution group members in scripting

Example Script Field Processor script

This example used Micro$oft Active Directory

Example script result

Related articles