Working with distribution groups
- Andy Brook [Plugin People] (Unlicensed)
- Ryan Clifton
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.
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 |
|---|---|---|
 |
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:
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)
The LDAP filter that should be valid to match users within the BASE DN of the related LDAP configuration
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
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.
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)
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.
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)
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <Administrator@dev.ppl.com>
To: changeme@thiswontwork.com
Cc: dist-group@dev.ppl.com
Content-Type: text/plain; charset=UTF-8
some textThe 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)
2016-01-13 15:09:42,698 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Creating InitialDirContext for LDAP server: ldap://win2003:389/DC=DEV,DC=PPL,DC=COM
2016-01-13 15:09:42,700 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] LDAP user for users: (&(&(objectClass=group)(groupType=2))(|(mail=changeme@thiswontwork.com)))
2016-01-13 15:09:42,700 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] User not found with filter: (&(&(objectClass=group)(groupType=2))(|(mail=changeme@thiswontwork.com)))
2016-01-13 15:09:42,700 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] No results found for filter: (&(&(objectClass=group)(groupType=2))(|(mail=changeme@thiswontwork.com)))
2016-01-13 15:09:42,701 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Found 0 unique LDAP users
2016-01-13 15:09:42,701 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Found 0 unique LDAP users registed in JIRA with an account (of some kind)
2016-01-13 15:09:42,701 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Query time: 4 mS
2016-01-13 15:09:42,701 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Creating InitialDirContext for LDAP server: ldap://win2003:389/DC=DEV,DC=PPL,DC=COM
2016-01-13 15:09:42,703 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] LDAP user for users: (&(&(objectClass=group)(groupType=2))(|(mail=dist-group@dev.ppl.com)))
2016-01-13 15:09:42,704 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Creating InitialDirContext for LDAP server: ldap://win2003:389/DC=DEV,DC=PPL,DC=COM
2016-01-13 15:09:42,709 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Creating InitialDirContext for LDAP server: ldap://win2003:389/DC=DEV,DC=PPL,DC=COM
2016-01-13 15:09:42,712 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Creating InitialDirContext for LDAP server: ldap://win2003:389/DC=DEV,DC=PPL,DC=COM
2016-01-13 15:09:42,715 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Creating InitialDirContext for LDAP server: ldap://win2003:389/DC=DEV,DC=PPL,DC=COM
2016-01-13 15:09:42,718 http-nio-8080-exec-4 INFO [emh.net.ldap.LDAPLookupUtil]
-------------------------------
LDAP result:
-------------------------------
[root] CN=example-dist-group,CN=Users,DC=dev,DC=ppl,DC=com
[1] group: CN=example-sub-group,CN=Users,DC=dev,DC=ppl,DC=com
[2] user: CN=Mike Harrison,CN=Users,DC=dev,DC=ppl,DC=com
[2] group: CN=example-sub-sub-group,CN=Users,DC=dev,DC=ppl,DC=com
[3] user: CN=Andy J. Brook,CN=Users,DC=dev,DC=ppl,DC=com
[2] group: CN=jira-administrators,CN=Users,DC=dev,DC=ppl,DC=com
[3] user: CN=Administrator,CN=Users,DC=dev,DC=ppl,DC=com
[3] user: CN=test1 user,CN=Users,DC=dev,DC=ppl,DC=com
[3] user: CN=test2 user,CN=Users,DC=dev,DC=ppl,DC=com
-------------------------------
2016-01-13 15:09:42,718 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Found 5 unique LDAP users
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Found 5 unique LDAP users registed in JIRA with an account (of some kind)
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [emh.net.ldap.LDAPLookupUtil] Query time: 20 mS
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [jira.emh.engine.FieldProcessorFixer] Cached 4 from distribution list: dist-group@dev.ppl.com
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [jira.emh.engine.FieldProcessorFixer] Adding as watcher due to referral through distibution list: mharrison : mharrison@dev.ppl.com
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [jira.emh.engine.FieldProcessorFixer] Adding as watcher due to referral through distibution list: test1 : test1@dev.ppl.com
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [jira.emh.engine.FieldProcessorFixer] Adding as watcher due to referral through distibution list: admin : Administrator@dev.ppl.com
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [jira.emh.engine.FieldProcessorFixer] Adding as watcher due to referral through distibution list: test2 : test2@dev.ppl.com
2016-01-13 15:09:42,721 http-nio-8080-exec-4 DEBUG [jira.emh.engine.FieldProcessorFixer] Setting new watchers list: [mharrison(normal), test1(test), admin(admin), test2(email)]
2016-01-13 15:09:42,721 http-nio-8080-exec-4 INFO [jira.emh.engine.FieldProcessorFixer] fixupWatchers() done
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:
(&(&(objectClass=group)(groupType=2))(|(mail=changeme@thiswontwork.com)(mail=dist-group@dev.ppl.com)))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