An all in one solution for embedding in your Jira Cloud dashboard gadgets and issues BETA.

Installation

See installation instruction on the Atlassian Marketplace.

Prerequisites

An active Jira Cloud instance you have sufficient permissions to install apps on.
If you cannot install apps, you can probably contact your Jira administrator for permissions, or with the jFrame Atlassian Marketplace listing.

Platforms

jFrame is a subscription based SaaS app available via the Atlassian Marketplace for the following platforms:

• Jira Cloud

Integrations

This app is designed to blend in with your Jira Cloud instance in look & feel and functionality & behavior.

For administration purposes:

1. Useful menu entries inside the Universal Plugin Manager.

For application purposes:

1. A dashboard gadget.

2. An issues content app. BETA

Getting started

Once you have the app installed you have a few option of integration…

1. Add jFrame as a:

   1. To add as a gadget in side a dashboard – select the “Embed something with jFrame“ option in the “Add gadget“ dialog

   2. To add as linked issue content panel – click the “Embed“ option inside any Jira issue.

2. Locate the online web resource you wish to embed.

   1. Try to copy-paste the plain link URL.

   2. If it didn’t work well enough, look for an embed or share option.

   3. You can use any <iframe/> based HTML embed code.

   4. Support for other HTML embed codes is not yet available. comming soon

Security

For your own cyber and legal protection, some restrictions apply on your URL address.
The same restriction apply for the src URL of any HTML <iframe/> embed code.

The address must:

• Be a secure https:// address.

• Allow sufficient CORS.

• Allow embedding as an <iframe/>.

These restrictions are built into the HTTP protocol among other web standards, and are enforced by your content vendor servers and user browsers. We embrace these too, and validate your input as much as possible, in order to let you know what is going on. We are constantly working on improving these validations, and safe alternatives for these restrictions might be available in the near future for certain cases.

Technical details

jFrame is based on the <iframe/> HTML element, and tries to bring you a simple user friendly experience by translating exactly the flexibility you need into easily configurable features that speak directly to our everyday needs. As in all of our products, we aspire to integrate seamlessly into the platform we help you enjoy. For our Atlassian apps we achieve that by consulting every decision with Atlassian design guidelines, and using Atlassian’s top of the art frameworks.

As part of our efforts to keep you safe and comfortable, we save only the data that we need, and only on your own Jira instance alongside the rest of your Jira data. For those reasons, our servers don’t take part in any data handling or logic related to you or your organization’s Jira instance. This means your connections and data are always secure at the same high standards Atlassian provide for you. This policy is of course recommended and you’ll be happy to know we use all the tools and best practices provided to achieve it.

Privacy

jFrame is served over a secure connection and saves no personal data.

Nevertheless, we understand your company or industry might require extra care. To avoid any risk, and the privacy policy hunt, we add a short readable disclosure of our data handling.

Data disclosure:

• On our servers: No data saved by the app.

• On third party servers: No data saved by the app.

• On your Jira instance:

  • Each gadget’s settings.

  • Each issue’s embed settings.

Note:

jFrame helps you embed live web content in your Jira instance while staying safe. We use the protection of an <iframe/> and all available HTML and HTTP mechanisms we can. We also verify the embedded content source against open source lists and notify you, but we don not block them, as it will block your option for embedding from your organizations internal resources. We believe you know very well what you are are embedding, and just assist you in doing is fast & easy and helping you stay safe, you should always be aware of the content you embed, especially if it came from outside of your organization. It is not likely to happen, if something went wrong due to the embedded content we can try to help , but we cannot take legal or technical responsibility over the content you choose to embed.

Screens & Navigation

jFrame has 3 screens and navigating through them uses standard Jira skills or straight forward standard web form behavior.

Embedded content

A configured dashboard gadget or issue embed will open showing the embedded content.

Navigating away is available in the following ways:

1. Using the “Edit“ item in the standard Jira dashboard gadget menu allows editing the current gadget settings in the settings form.

2. Using the pencil “Edit“ button on the embed title card actions or clicking the issue’s “Embed“ button achieves the same on our new issue integration.

Note: Permission to to edit the embed are delegated to how Jira handles them for editing the gadget or adding other issue content panels like web links.

Settings form

Appears when the source for your embed is set allowing you to edit the settings that will be used.

Navigating away is available in the following ways:

1. Click “Save“ button to save the settings you currently see and their results in the embedded content screen.

2. Click “Close“ to drop any unsaved changes and see the saved settings in the embedded content screen

3. Click “Edit“ inside the source field to start the embed process over with your saved source in the source form.

Note: The save button becomes blue if there is unsaved changes and nothing is never saved until a blue “Save“ button in clicked.

Source form

Appears when creating a new gadget or a new issue embed. You can also reach it by choosing to edit the source allowing you to use our “Embed“ button again.

Navigating away is available in the following ways:

1. Using the “Embed“ button to let our wizard analyze the source and choose the best default settings to fill in settings form.

2. Using the “Cancel“ button is available when there are already saved settings and allows going back to the settings form.

Forms

A drill down into each form and it’s fields.

Source form

Our source form is the first stop on your way to embedding your source. It has a single field for the source you wish to embed, and submitting it will analyze and try to find the best way to embed this source in a your Jira Cloud instance.

Source

Displaying the URL or embed code you wish to embed.

• Type: Text.

• Default: Your URL or embed code.

• Required: Yes.

• Validation: Non. – Embed quality prediction appears as a clickable icon.

• Disabled: Always. – Special edit button inside the field.

Settings form

Open

Our settings form offer unique useful features for a successful modern embed experience. The available settings are designed for the non technical user yet should offer all the flexibility you need. All options are opt-in and will be populated with the best fit our wizard could find for the requested embed source.

Content

Define the embedded content and general settings.

Source

Displaying the URL or embed code you wish to embed.

• Type: Text.

• Default: Your URL or embed code.

• Required: Yes.

• Validation: Non. – Embed quality prediction appears as a clickable icon.

• Disabled: Always. – Special edit button inside the field.

This field displays content you requested to embed and are editing the settings for now with insights and and option to replace it..

Title

Set a title for your embed.

• Type: Text.

• Default: Empty.

• Required: No - Feature disabled when empty (Jira uses our default title).

• Validation: Non.

  • Any character is accepted.

  • Trims leading and trailing whitespace.

• Disabled: Never.

Using this field dashboards enables an optional feature allowing you control over the title in the same context as the rest of the settings. You opt-in by just filling the field with the desired title. If you choose to opt-out, just leave this field empty, and jframe will not interfere with the gadget’s title, giving you full control from the “Rename” option in the standard Jira gadget menu.

Note: We really wanted to allow seamless synchronized mixed control over the title, but unfortunately Jira doesn’t allow it. This means you should actively empty the field in order to opt-out. if not empty, it’ll will override the gadget’s title every time you save the settings.

Refresh rate (in seconds)

Reload the embedded content periodically every interval of seconds.

• Type: Number.

• Default: Empty.

• Required: No - Feature disabled when empty.

• Validation: A positive integer.

  • Only digits “0”, …, ”9” are accepted. Any other character will be ignored. 

  • Trims leading and trailing whitespace.

  • Trims redundant leading zeros “0”.

• Disabled: Never.

Using this field enables an optional feature keeping your content properly updated by reloading it in constant intervals. You can leave the field empty to disable the feature, and have your embedded content load only when the app itself loads (e.g. on a page load or when settings are saved).

Appearance

Control the size of your embed.

Aspect ratio

Set the embed height to dynamically change depending on the width, maintaining a constant aspect ratio.

• Type: Text & List.

• Options:

  • Square: “1:1”.

  • Landscape: "2:1", "16:9", "16:10", "5:4", "3:2", "4:3".

  • Portrait: "3:4", "2:3", "4:5", "10:16", "9:16", "1:2".

• Default: “16:9”.

• Required: No - Feature disabled when empty.

• Validation: Custom values are of the same form as the list options “width:height”. All parts are mandatory, and “width” & “height” are positive integers up to 5 digits long.

  • Only digits “0-9” and the separator symbol “:” are accepted. Any other character will be ignored.

  • Trims leading and trailing whitespace.

  • Trims redundant leading zeros “0” from both numbers.

• Disabled: Never.

  • No option is ever disabled either.

Using this field enables an optional feature giving you a more modern approach of sizing your embed with a dynamic height determined by a constant aspect ratio. You should probably use this feature if an aspect ratio is the way your content is sized, if you want your dashboard more responsive so it’ll display properly on different screens, or if it just fits more naturally with the rest of the gadgets on your dashboard or elements on your issue (e.g. attachments). We complete this feature with a pair of minimum/maximum height fields (also found in this documentation), giving you an even more granular control. You can clear this field to disable the feature, and use a constant height instead.

Note: Due to security concerns, the size of the content you embed cannot be determined automatically. This means you need to determine the size of your embed (with this feature or another), or you will get the default your browser offers (should be 300 pixels).

Height (in pixels)

Set a constant static height in pixels for the embed.

• Type: Number.

• Default: Empty.

• Required: No - Feature disabled when empty (you browser will probably default to 300 pixels).

• Validation: A positive integer.

  • Maximum value is 1,000,000.

  • Only digits “0”, …, ”9” are accepted. Any other character will be ignored. 

  • Trims leading and trailing whitespace.

  • Trims redundant leading zeros “0”.

• Disabled: When an aspect ratio is used.

Minimum height (in pixels)

Set a minimum height in pixels for the embed, to limiting the dynamic height determined by the aspect ratio.

• Type: Number.

• Default: Empty.

• Required: No - Feature disabled when empty.

• Validation: A positive integer.

  • Maximum value is 1,000,000.

  • Only digits “0”, …, ”9” are accepted. Any other character will be ignored. 

  • Trims leading and trailing whitespace.

  • Trims redundant leading zeros “0”.

• Disabled: When no aspect ratio is used.

Maximum height (in pixels)

Set a maximum height in pixels for the embed, limiting the dynamic height determined by the aspect ratio.

• Type: Number.

• Default: Empty.

• Required: No - Feature disabled when empty.

• Validation: A positive integer.

  • Maximum value is 1,000,000.

  • Only digits “0”, …, ”9” are accepted. Any other character will be ignored. 

  • Trims leading and trailing whitespace.

  • Trims redundant leading zeros “0”.

• Disabled: When no aspect ratio is used.

Interactions

Control what your users can do with the embedded content.

Clicking

Enable clicking and show the mouse pointer.

• Type: Checkbox.

• Default: Enabled.

• Required: No.

• Validation: Non.

• Disabled: Never.

When this option is checked, your mouse pointer will function normally inside your embedded content, but that is not what we always want. Unchecking this option will prevent any mouse interaction with the selected content, and will make the pointer disappear while inside the content, expressing it’s unavailable.

Note:
When clicking is disabled, jFrame also disables the ability to use the keyboard on the embedded content, or even to reach it using keyboard navigation. This extra step ensures users cannot use the keyboard to bypass this important security feature, as well as minimize the tracking option for the embedded content.

Scrolling

Enable scrolling and show the scrollbars.

• Type: Checkbox.

• Default: Enabled.

• Required: No.

• Validation: Non.

• Disabled: Never.

When this option is checked the scrollbars will appear and the user will be able to scroll the embedded content. However, please note disabling clicking essentially disables the user’s ability to actually use the scrollbars.