In this page

What is Insight?

(supported since Better PDF Exporter 1.6.0)

Insight is the leading asset management app for Jira, that allows implementing CMDB, CRM, HR, ITSM or ITIL functionality on the Jira platform.

Insight integration features

  • You can export Insight-managed objects from the custom fields of the Assets type to PDF. (Note that Jira Cloud is using a single custom field type named Assets to integrate objects managed by various asset management apps to Jira issues.)
  • You can configure the export format to include object names (e.g. "My awesome server"), object keys (e.g. "My awesome server [SRVR-123]"), object attributes (e.g. "My awesome server [SRVR-123] (Manufacturer=Cray Research, Vector Processors=4, Type=Supercomputer)") and any combination of these.

(Need more features? Tell us in a support ticket!)

Insight integration vs. the Insight built-in PDF exports

You may want to ask: if Insight has a built-in PDF export feature, why would you use another app for the same?

While the Insight built-in PDF exports may be sufficient for basic use cases, the Better PDF Exporter integration is more powerful in, at least, these:

If at least one of these is important for you, give the app a try.

Tutorial video

Watch this short introductory video to see how fast you can export your Insight data to PDF! (Although the video below was captured about the app's Server version, the Cloud version is very similar.)

Insight PDF export samples

Jira issue with Insight objects

This straightforward PDF document (created using the default issue-fo.vm template) contains a single Jira issue with two Insight custom fields. In addition to object names and keys, attributes are exported as comma-separated name-value pairs in brackets (the format is completely customizable).

jira-insight-fields-single-issue.pdf

Jira issue list with Insight objects

Insight custom fields (see the 2 rightmost columns) are also supported when bulk-exporting Jira issues to a table in a PDF document. In this example, attributes are turned off for a more compact content.

jira-insight-fields-issue-navigator.pdf

Configuration

What is "legacy" and "new" Insight?

Starting from March 31, Insight became part of Jira Service Management. It has been a separate Jira app previously, but Atlassian acquired Mindville (the original developer of the app) and integrated Insight to Jira Service Management.

The "legacy" app has been removed from the Atlassian Marketplace, and will reach its end-of-life on March 31, 2022. In order to get access to the "new" Insight, you have to be on the Jira Service Management Premium plan.

Which one are you using?

Until the legacy app is completely removed, you can have the legacy Insight app, the new Insight in Jira Service Management or even both installed to your Jira Cloud instance!

How do you know which one are you using?

  1. If you can see the menu Insight available at the top, you have Insight in Jira Service Management installed.
  2. If you can see the Insight menu item available in the Apps menu at the top, you have the legacy app installed.
How to configure "legacy" and "new"?

The configuration steps to access the two types of REST APIs are slightly different. We offer a guide for both below, follow the one that matches your Insight.

How to migrate from "legacy" to "new"?

After you migrated your data from the legacy app using the official Atlassian guide, we strongly suggest verifying if all your objects and field values were correctly migrated.

Then, re-configure the integration to use Insight in Jira Service Management as data source with these steps:

  1. Disable the REST API access for the legacy app by commenting out the access token (to inactivate this as data source).
  2. Enable the REST API access for Insight in Jira Service Management (to activate this as data source).

Exporting Insight objects

The Insight and Better PDF Exporter integration relies on the Jira REST API (Insight in Jira Service Management) or the Insight REST API (legacy app). After configuring the API access once (based on the guide below), Better PDF Exporter will automatically recognize the Insight-managed objects and export them accordingly.

Configuring REST API access for Insight in Jira Service Management

As this integration relies on the Jira REST API, you need to set your Jira email address and Jira API token for the REST API calls in the templates:

  1. Follow the steps on this page to get a Jira API token.
  2. Click the cog icon "⚙" in the top right → Apps → PDF Templates (under Better PDF Exporter).
  3. Open the issue-fo.vm template for editing. Find $insightUserEmail, uncomment it, and add your own Jira email address between the quotation marks (don't remove the apostrophes around the string!).
  4. In the next row you will find $insightApiToken. Uncomment it, and paste the Jira API token from the clipboard between the quotation marks (don't remove the quotation marks around the string!):
    ## Insight in Jira Service Management authentication
    #set($insightUserEmail = 'john.doe@example.com') ## Jira Cloud user email address
    #set($insightApiToken = 'Ybx59oFTFnFzLKWwR9aj21BC') ## Jira Cloud API token
    
  5. Save the changes. (Don't worry about storing tokens here: this file is visible only for Jira administrators, who would have super-user permissions anyway.)
  6. Similarly, set the same in the issue-navigator-fo.vm template.
  7. Similarly, set the same in the traceability-report-fo.vm template.

Configuring REST API access for Insight Asset Management (legacy app)

As this integration relies on the Insight REST API, you need to configure the access token for the REST API calls in the templates:

  1. Go to JiraAppsInsightInsight Access Tokens.
  2. Click Create a token, enter a name for the token and click Generate.
  3. Copy the access token from the dialog (using the Copy button).
  4. Click the cog icon "⚙" in the top right → AppsPDF Templates (under Better PDF Exporter).
  5. Open the issue-fo.vm template for editing, uncomment this variable in the top part, and paste the security token from the clipboard to the value (don't remove the apostrophes around the string!):
    ## Insight Asset Management (legacy app) authentication
    #set($insightAccessToken = 'fc77e1e41274052ba0645a1669c62aaceb3c8102')
    
  6. Save the changes. (Don't worry about storing tokens here: this file is visible only for Jira administrators, who would have super-user permissions anyway.)
  7. Similarly, set the same token in the issue-navigator-fo.vm template.
  8. Similarly, set the same token in the traceability-report-fo.vm template.

Configuring the export format for the Insight objects

The default behaviour is that object names and object keys will be exported (e.g. "My awesome server [SRVR-123]"). You can include object name, object key and attributes by setting these configuration variables in the top part of the issue-fo.vm and issue-navigator-fo.vm templates:

## Insight
#set($exportInsightObjectNames = true) ## set to "true" to export Insight object names
#set($exportInsightObjectKeys = true) ## set to "true" to export Insight object keys
#set($exportInsightObjectAttributes = false) ## set to "true" to export Insight object attributes

If you want full control over the export format, look at the Velocity macro definition marked with this comment in issue-fo.vm, issue-navigator-fo.vm and traceability-report-fo.vm:

## Insight custom field
## ...

Note: you can absolutely have different export formats in the two templates, as issue-fo.vm typically has more space for details.

Learn more about Insight