Integrate JEMH with JIRA Service Desk

Configuration

For a streamlined guide on setting up JEMH for issue creation via email in JSD 3 onwards, see Create Issues (Jira Service Desk 3).

Setting the Customer Request Type

In order for email (a.k.a Non-Jira) users to create fully functional requests in Jira, the Service Desk custom field Customer Request Type must be set with a specific value.  This value has the format projectkey/requestid.  By default this field is not visible on edit screens.

Locating the Request Type (pre JSD 3.1)

If your version of Service Desk doesn't expose the field value in this way (recent version don't as of DEC 2014), you can access the data using REST with a URL similar to:

Once on the page, the content you are looking for will be of format:

From JSD 3.1 onwards, this way of finding the request type no longer works.  Please see the common problems wiki page here for the solution: Common Problems - Locating Customer Request Type

All Emails to a single Request Type

Setting a JEMH Default Custom Field value to Default Project Mapping will cause all issues being created to have that custom field value, so setting Customer Request Type to default001 will do that, see the JEMH Profile > Default Project Mapping > Custom Field Defaults section:

Request Type defined through Project Mappings

JEMH Project Mappings allow routing of emails to projects.   With Service Desk this method also gives you the opportunity to route incoming email into a defined Service Desk queue.  Defining the Customer Request Type can be done at the per-Project Mapping level which then becomes the default for all Mapping Rules unless overridden:

Each Mapping Rule could then provide a different value, for example:

Use of Directives

JEMH Directives can also be used to set the field remotely, JEMH Aliases can be used to simplify this to #servicedesk or similar.

@project=SD @Customer Request Type=sd/bug hello world

Example: Email only (no account)

Here is a JEMH Test Case, it has no special directives defined, the project mapping above will be used (with serv/default003 as a value):

The post-execution screen shows which Domain Rule fired:

Going to the created issue (with the Customer Request Type field visible):

As 'admin' switching views to the Service Desk, the new issue is present, and can be managed through the Service Desk UI:

The Edit option allows new columns to be added:

So, adding the Email Users custom field allows you to see who the email came from, even including the 'personal' part of the email address if stored:

Notifications

Where email users are concerned, the JEMH Default User is used as the context for the operation, this is the user who will receive email notifications via Service Desk.  With JEMH configured for non-JIRA support already, nothing changes, and standard IssueEvent notifications occur:

Issue Created Example

Issue Updated Example

Issue Created Example

Issue Updated Example

Here, a "Start Progress" transition has been triggered which results in:



Duplicate Notifications?

By default, JIRA Service Desk is set to create its own notifications, which are independent of the standard JIRA notification scheme. You may see duplicate notifications being sent if you also have JEMH sending them. To stop JSD from sending notifications, go to Project Administrator > Notifications > Actions > Use a different scheme. Here you are able to set Scheme to None.



To configure the content of the notifications, see Use Template Sets (Custom Templates).

Example with Service Desk User (with account) by email

The Portal Access user that came in with JSD 2.2 introduces some problems:

  •   https://jira.atlassian.com/browse/JSD-1473 Issue Creation for Portal Users fails through the API, this requires the workaround below

  •  Using this workaround, it is possible for any user to send an email into an issue with an issue key, and have that added as a comment.  Issue Security Schemes don't appear to help.

The following is the current workaround configuration:

 JEMH v 1.6.49+ required

Process

  1. Create an auto-join group, e.g. servicedesk-customers which is not used elsewhere

  2. Modify JEMH Profile set set the Customer Request Type custom field (described in the first section)

  3. Modify JEMH Profile

    • set User > Create users : ON

    • If your users all exist externally, not in a common LDAP repository set User > Create UserID from: email. Users in LDAP wont be created as they exist already, the next step will do what remains

    • set User > Auto Join Group(s) to refer to servicedesk-customers and set the User > Auto Join Group Condition to be "For All JIRA Users"




  4. Modify Project Role

    • Go to your service desk project and then edit Users and Roles in Project settings

    • Select Add users to a role and select the JEMH auto-join group, so that users who create issues by email without first subscribing, automatically get allocated that group, this role, and are therefore able to create issues etc.

       

  5. Modify the Permission Scheme, granting the servicedesk-customers group the below permissions.  If you give "Project Role (Customer)" permissions in the scheme instead, public sign-up will be disabled by JSD.



Commenting

Who gets internal notifications?

Any comment that is marked as internal will not be sent to Non-Jira users, achieving the intent of the JSD internal comment function.  JIRA account holders found to be in the Service Desk Customer role will not be notified of internal JSD comments.  Users who are designated as Service Desk Agents, or authorized Software/Core users will also get notified of internal comments.

Before version 1.6.50, JEMH would not be able to detect that an internal comment was made via Service Desk and therefore the above did not apply.

Controlling visibility of comments

Comments made by Service Desk Agents via JEMH are internal by default.  However, this behaviour can be changed on a per-project basis by changing the setting Profile > Project > Project Mapping > Comment > Agent comment visibility.  If Directives are enabled for comments and a suitable Field Processor is also enabled, then agents can set the visibility of their comment from the email itself during its composition.

For example, with the @Prefix field processor enabled the following would set the comment to be public:

@ Prefix Field Processor example
@internalComment=false This is the body of my email, which is to become a comment.

In your profile, you could create aliases for the directive to allow simpler usage by agents:



Alias

Value

Alias

Value

internal

internalComment=true

public

internalComment=false



The above 2 alias configurations (with the @prefix field processor enabled) would allow agents to then use @internal or @public in their email body to set their comment as internal or public respectively.

Including email recipients

terminology recap:

  • “email user” or “non-jira user” : have no account at all, who cannot login to Jira or the JSM portal

  • “Jira user” : have accounts, of some kind in the instance, whether they are portal users or interactive Jira users.

When a user emails into a JEMH managed mailbox, additional recipients of the message can be added to the created issue (or on update, if the sender is already involved), exactly how additional recipients are managed is controlled through the Profile > Email > Addressee Processing section, shown below:

Addressee Handling is the primary driver to describe how email addressees are handled. In JSM, two fields are usually involved:

  1. Selecting toCustomField will enable support for email-only non-Jira user support (email notification of updates but no ability to access the portal), where recipients are automatically merged into a text multi-line custom field (3, above).

  2. Selecting toJSDRequestParticipants will enable support for Request Participants, the addition of users here is subject to the filter (2, above).

Request Participants

The Service Desk project admin can set 'customer permissions (screenshot below), this security setting affects JEMH.

Jira is the gatekeeper of security and will reject issue update requests (by JEMH) if they violate security choices. Settings are found within the JSM Project > Customer permissions section.

“Customers who are added to the project”

When set, Jira will deny any Jira user that may exist in your site but are not actually added as customer to this particular Service Desk:

Prior to 3.3.63 Jira would reject attempts by JEMH to set customers who were not authorized, resulting in emails being Forwarded.

since 3.3.63 JEMH can be configured to react to such users, allowing exclusion (registered customers only) or partial inclusion (treating such customers as non-jira) - enabling this support does mean ‘email user support’ is also enabled.

jira-user without current portal access handling

Configuration Required

jira-user without current portal access handling

Configuration Required

Drop

  • Profile > Email > Addressee Processing > Request Participant Filter : requireCustomerRole

  • Profile > Email > Addressee Processing > Addressee Handling : includes toJSDRequestParticipants

Treat as non-Jira

  • Profile > Email > Addressee Processing > Request Participant Filter : none

  • Profile > Email > Addressee Processing > Addressee Handling : includes toCustomField, toJSDRequestParticipants

  • Profile > Email > Addressee Processing > Assign non jira-user Email to Text CustomField : set to a text multi-line field

“Customers who have an account on this Jira site”

When set, Jira will allow any Jira user to be added as a request participant. If addressees are found that do not have accounts, they will simply be excluded. Only when non-Jira support is enabled would they become involved as email only.

This is historic behaviour:

jira-user without current portal access handling

Configuration Required

jira-user without current portal access handling

Configuration Required

Drop

n/a, default behaviour

Treat as non-Jira

  • Profile > Email > Addressee Processing > Addressee Handling : includes toCustomField, toJSDRequestParticipants

  • Profile > Email > Addressee Processing > Assign non jira-user Email to Text CustomField : set to a text multi-line field

Email Processing Report Messages

since 3.3.63

When users are added as Request Participants:

Adding request participant: csdcustomer@blah.com

When a user is not authorized and is added as a non-jira email user:

When a non-customer user is excluded when either toCustomField is not enabled or a custom field is not defined for “Assign non jira-user Email to Text Custom Field”:

Related articles