Use Static Resources
Summary
Since JEMH 2.1.15
Static Resources are files which can be uploaded to JEMH to be attached to outbound email notifications. Static resources support being attached directly to an outbound email as an attachment, or as an inlined image in the email HTML body when the resource is an image file. Static Resources can be used when a specific file is required to be attached to outbound notifications.
Management of resources
Static Resources can be created for global use, or scoped to a particular project. Static Resources can be configured from the Static Resources tab within the JEMH configuration area, or within project settings when a user has project administration permission.
JEMH Configuration | Project Settings |
|---|---|
|
 |
Creation
Within the Static Resources tab click New Static Resource:
A form will appear below after pressing New Static Resource:
After you have entered the desired settings and selected a file to be used as a Static Resource, press the Submit button. A new Static Resource will be created with the associated settings and displayed in the list of resources.
Images are not dynamically rendered for page load performance, to see a preview of an image click on "click to preview", the image will be downloaded and dynamically injected into the page.
Configuration options
Project
The Project that the Static Resource will be scoped to
IMG Width
Sets the width that will be used to render the image at runtime (pixels)
IMG Height
Sets the height that will be used to render the image at runtime (pixels)
Pick a file
File picker dialogue to select the file to be uploaded as a Static Resource
Description
A description of the Static Resource
Editing
The Static Resources tab within JEMH allows existing Static Resources to be edited.
Static resources can be filtered in several ways to scope the listed resources.
A list of Static Resources is shown:
Editing an existing Static Resource by clicking the pencil icon within the actions menu on the right side of a resource:
| The Edit Static Resource form allows you to modify the current configuration of a Static Resource. You can re-scope a resource project by modifying the Project field. Image width and height can be modified via the IMG Width and IMG Height fields. Resource description can be modified via the Description field. You can also upload a new file which will overwrite the existing file mapped to the resource, choosing a new file via the Pick a file field and then pressing Submit. The new file will replace the existing file mapped to the resource whilst retaining the configuration options defined for the original file. |
Adding Static Resources to notifications
By Workflow Configuration
From v2.7.12 and v3.0.0 we also add a Static Resource picker so that specific attachments can be picked for specific transitions. Given workflow is cross project, all StaticResources are pickable.
By Script
Static Resources can be added to notifications by using JEMH's Template Sets system. Velocity script is added to a custom template, defining which resources are to be attached to outbound notifications using that Template Set.
In this example we are creating a Template Set for the Issue Created event. We will be attaching a PDF document, along with an image of a goldfish that will be embedded in the HTML body. The outcome of this example will be that a user receives an email when the Issue Created event is fired, the email will contain some text and the goldfish image within the body and the email will also have a PDF file containing terms of service attached as an email attachment.
First create an Issue Created template, for more in-depth information on the configuration of Template Sets see: Use Template Sets (Custom Templates):
Edit the newly created template by selecting the Edit action next to the item. You will now be shown the template edit screen. Enter a preview context issue key which will be used to generate template previews for use whilst designing Template Sets:
To access a Static Resource you will need to know it's unique ID, this can be found on the left hand side of the Static Resource when it is listed within the Static Resources tab.
The unique ID for our PDF document's Static Resource is 4, the unique ID for our goldfish image's Static Resource is 3.
Velocity methods
Method signature | Usage example | Description |
|---|---|---|
renderStaticResourceImage(Project project, Integer resourceId) | $jemhUtils.renderStaticResourceImage($issue.getProjectObject(), 123) | Embeds static resource images as in-line HTML images. |
renderStaticResourceImage(Integer resourceId) | $jemhUtils.renderStaticResourceImage(123) | since 2.4.1 Same as above, however can only be used for adding resources with a global scope. |
addStaticResourceAttachment(Project project, Integer resourceId) | $jemhUtils.addStaticResourceAttachment($issue.getProjectObject(), 123) | Attaches the defined Static Resource ID to the outbound notification as an email attachment. |
addStaticResourceAttachment(Integer resourceId) | $jemhUtils.addStaticResourceAttachment(123) | since 2.4.1 Same as above, however can only be used for adding resources with a global scope. |
If the notification event has a related issue, the current project object for an issue can be accessed via velocity using:
$issue.getProjectObject()Combining this all, the final velocity code to inline our goldfish image within the email whilst attaching our PDF document to the email will be:
$jemhUtils.addStaticResourceAttachment($issue.getProjectObject(), 4)
$jemhUtils.renderStaticResourceImage($issue.getProjectObject(), 3)Append the above velocity code to the Template Set HTML section, the rendered template can be previewed using the button below the text field, when a preview context issue key has been supplied in the preview section:
The image of the goldfish is embedded as part of the HTML template, the attached PDF document can not be previewed at this time but can be tested by sending an email using this template set. Press submit to save the changes to the Template Set.
Now that the Template Set has been configured it needs to be mapped to the JEMH Event Listener mapping for a project:
To test your Static Resource Template Set, create a new issue either via a test case or an email. An Issue Created event will be triggered, the Template Set configured in the Event Listener mapping will be used to generate the notification.
The notification email will contain the goldfish image embeeded in the HTML body, the PDF document will also be attached to the received email.
Adding resources to JEMH Post Function notifications
https://thepluginpeople.atlassian.net/browse/JEMH-6681 covers the ability to pick static resources from the post-function config screen.
Static Resources can also be added to workflow-triggered notifications created by the JEMH Post Function. This can be achieved by using a modified Ad-Hoc Template Set (see next section), or Custom Content entered directly in the Post Function configuration.
In this example we will configure custom content and add two resources :
A PDF file with resource ID 24
An image file with resource ID 25
Create or edit an existing JEMH Post Function and ensure that the Template selection is set to Custom Content. Modify the Custom Content field and set the Content Markup to Velocity.
Once you are happy with the visible content you have entered, append the Velocity script to add the static resources to the content field. For example:
$jemhUtils.addStaticResourceAttachment($issue.getProjectObject(), 24)
$jemhUtils.renderStaticResourceImage($issue.getProjectObject(), 25)The content of the post function can be previewed by supplying an example issue key in the Preview Context section. You can preview the custom content by pressing the small blue preview button below the content field.
Pressing the Test button in the Preview Context window will send out a test notification email to the addressed defined in the To,Cc, Bcc fields defined within the post function configuration:
The final post function email should display the goldfish Static Resource image as an embedded image in the HTML body, the PDF document should also be attached to the email.
Adding resources to Ad-Hoc notifications
Static Resources can also be used as part of a JEMH Ad-Hoc notification, Template Sets can be configured for Ad-Hoc notifications or custom velocity markup can be provided on the fly via the Custom Content template option. In this example we will create a custom Ad-Hoc Template Set and then use it to send an Ad-Hoc notification containing Static Resources. The attached Static Resources will be an inlined image of a goldfish and a PDF document as an attachment.
Create an Ad-Hoc Template Set:
Edit the Ad-Hoc Template Set:
Edit the Ad-Hoc Template Set HTML content, in this example we have included some bold text followed by an image of a goldfish embedded via a Static Resource, we have also included a PDF document as an attachment.
The notification rendering can be previewed by supplying a preview context issue key in the preview section and then pressing the preview button below the content.
Save the newly configured Ad-Hoc Template Set by pressing submit and then trigger an Ad-Hoc notification dialog from an issue, select the newly created Ad-Hoc Template Set:
Select a recipient in the To: tab and then press send. The resulting email should arrive with the goldfish image Static Resourced embedded in the HTML body, and the PDF document attached to the email.
Ad-Hoc Scriptlets
Insertion of static attachments via scriptlets
Insertion of static attachments via scriptlets is currently not supported. Inserting inlined images via scriptlets is supported however.
Create a Template Set for an Ad-Hoc Scriptlet:
Modify the scriptlet content to add a Static Resource as an inline image, in this example we are using a Static Resource to inline an image of a goldfish at the bottom of the scriptlet.
The rendering of the scriptlet can be previewed by entering an issue key in the preview section and then pressing the preview button below the scriptlet content field.
Save the Scriptlet content by pressing submit.
Insert the Scriptlet into an Ad-Hoc notification by triggering the Ad-Hoc notification dialog and then using the insert menu: