Enable Inline Images (Inbound and Outbound)

Owned by Andy Brook [Plugin People] (Unlicensed)
Last updated: Mar 09, 2023 by Andy Brook [Plugin People]
7 min read



 See also Create Images Inline from HTML mail

Inbound Image Support

Scenario

You would like to include inline images in issues, Inline images appear in the page, and are not just attachments.

Caveat

  • The approach taken in JEMH is that if JIRA uses the Wiki renderer for Comments and Descriptions, and there are images present using the inline wiki markup, then those images will be rendered inline in outgoing HTML email

!attached-image.png!

  • JEMH must manage the rendering of the outgoing email, this boils down to meaning (a) its a non-JIRA user notification, or (b) that it is an email whose content is defined within a TemplateSet, specifically, 'DEFAULT' templates are not currently able to be inlined as they are rendered by JIRA via an API call, this will probably change so that this kind of rendering feature is available for all notifications.

Creating your own customized content by rendering comments?

See Customize Email Templates, you need to use a specific renderer call to convert the comment markup into HTML that JEMH can inline:

$wikiRenderer.render($!message,null)

JEMH has several attachment related options.  For incoming HTML mail, with embedded images, JEMH supports the conversion to Wiki markup, this is compatible with outbound JEMH notifications.

JEMH Profile Configuration

For incoming conversion of inline images into wiki markup:

  • Email > HTML > HTML Extraction Method : standard V2 (or v1 for historic feature)

  • Email > HTML > HTML Image Handling: fullSize

  • Email > HTML > Rendered Image Attributes: (as required, e.g. align=right)

Example:

JEMH Issue Listener Project Mapping Configuration

For outgoing conversion of inline wiki markup referred images to HTML:

  • Event Listener > Email Transport > Project > Include Attachments in Notifications: ON

  • Event Listener > Email Transport > Project > Inline Images: ON

  • Event Listener > Email Transport > Project > Notification Format: HTML

    User Avatars are also be inlined:

Usage Walk-through

So, for example, I'll use a test inbound email with some images:

Test Case Execution

Paste the raw content into a JEMH Test Case, running it, we get the following Test Case summary:

The Issue

Drilling through to the created issue, thanks to JEMH incoming HTML->Wiki conversion, we get:

The Email

Checking my inbox, I find I have an email, before enabling downloading of externally referred images (icons etc) the inline images are shown:

Outbound Image Support

Why this needs to be done

Jira doesn't allow us to add attachments at the time issues are created. We have to create the issue, add the attachments, then fire new custom event, to trigger the notification. The complication is that ISSUE_CREATED (not the custom event) is fired from interactive users, so we need to cater for that, see later for how.

Before

After

Before

After

 

 

 

There are a few steps to enabling outbound inline images. See https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/2850947

Step 1 - Setup a custom event and setup JEMH Profile to fire it on create

You need to create a new Event in Jira, that is specific to JEMH Usage, based off the standard Issue Created event

Once created, edit the Default Notification Scheme to include the usual Reporter/Assignee/All Watchers combo (or whatever you need).

Then pick the custom event in the Profile, note this means JEMH will fire first ISSUE_CREATED and then the CUSTOM_EVENT. The eventID varies, it doesn't need to be 10000.

In the next step we set ‘something’ on the issue to indicate that JEMH created the issue, then during notification we can ‘ignore’ the JEMH ISSUE_CREATED notifications as we also expect the custom event.

Create a single line text Custom field called CreatedByEmail for the purpose of flagging issues create by JEMH

Now set a Default Project Mapping Custom field Default for that field, it will be inherited by all Rule-mapped Project Mappings. When selecting the field, make a note of the customfield_xxxxxx value shown, you’ll need it in step 2.

Step 2 - Setup Outbound Notifications

Outlook Compatibility SINCE 3.3.12

Outlook may fail to render the image size automatically set the correct image size dimension attributes (.i.e height, width) which causes the image to be rendered incorrectly on the outbound notification. To solve this we’ve added a configurable feature which adds the size attributes to the inlined images.

To enable this setting on the Notifications Page in the Transports > Email > Compatibility Options > Inject Image Dimensions and enable this check box as shown below:

Adding a custom template for the custom event

Create a new Email Issue Created TemplateSet, then edit it, re-title it “JEMH Custom Issue Created Template” and swap the Event for the custom event, and save.

Stopping duplicate Issue Created notifications

To recap, an Issue Created event will be fired by JEMH during issue creation but before the attachments have been added. We need to filter the email notification for Issue Created when JEMH is creating issues to avoid duplicates. The approach here is to set a custom field default value to indicate when JEMH has created an issue and ignore that notification. This ensures that interactive users who create issues (firing Issue Created events) do have their notifications sent.

Adding a custom event selector and filter

In the JEMH Notifications > mapping, there is an Event Selector and Filter script field, here we use a simple Velocity script to check the current Issue (the $issue is actually a TemplateIssue object). Below is a script to achieve this, next is a line by line description.

  1. Get the Custom Field definition (has no value)

  2. If the current Issue Event is 1 (meaning Issue Created) and the issues value of the above custom field is set then:

  3. Flag the event as ignored

  4. Give a reason for why the event is ignored

#set ($theCustomField = $customFieldManager.getCustomFieldObject("customfield_10900") ) #if ( "$issueEvent.getEventTypeId().longValue()"=="1" && $!issue.getCustomFieldValue($theCustomField) ) $result.setIgnoreEvent(true) $result.setReason("Ignoring ISSUE_CREATED by JEMH, expecting JEMH custom event") #end

Scroll down and pick the custom template just created for the Custom Issue Event (as there is no default)

Step 3 Prove outbound configuration

You need to prove the velocity script works, one typo and it will fail.

If you have JEMH logging enabled, you’ll see the following for the Ignore event ( the content between the ---- lines is debug output, effectively what is left as text between the velocity #if #else blocks)

Followed by the allow

If you get 2x the notifications likely the logic in the script is not correct.

 

Problems with Outlook thick clients

The outlook ‘app’ (not web browser based) has some peculiarities specific to its interpretation of HTML that web browser based mail clients don’t share in regard to images:

IMG tags need size attributes

Whilst not mandatory in web clients, some versions of Outlook have required the WIDTH and HEIGHT tags to be injected into the IMG tag, this means JEMH needs to ‘load’ the image and figure out the related metata, you can enable this in the JEMH Notifications (for all Notifications) where inline images are enabled:

Multipart Type needs to be mixed

JEMH defaults to sending multipart/related content type mails, some versions of Outlook have required multipart/mixed instead, also set in the Notification section (above).

Inlined images only show a strip of the content

Recently (2023) we’ve heard some versions of Outlook showing a block of inlined images:

A solution to this has been found to work https://stackoverflow.com/questions/17298867/outlook-2013-cutting-off-top-of-image, where the wrapping TD tag needs to have style applied:

You can customize this by changing the Jira macro in:

  • JIRA_INSTALL/atlassian-jira/WEB-INF/classes/templates/email/html/includes/patterns/text-paragraph.vm

Its content (Jira 9.5.0) was:

After the customization