The Business Intelligence Export product adds a report to your Jira reports screen. When opened, the user sees a configuration screen that allows him or her to enter start and end dates. Issues that have been created or updated within these dates will be retrieved for export along with all their worklogs and comments.
Default dates are provided should the user not enter either the start or end date. Due to the fact that most business intelligence systems perform a daily extract of the previous day's data, the default start and end dates cover that period.
Once the user is satisfied with the start and end dats, he or che clicks the "Next" button and the data is retrieved and formatted. On the report screen, is a large button titled "Choose a Download Format". Upon clicking it a drop-down of formats is revealed and the user can select the format they desire (i.e., Native Excel, CSV, JSON, or XML). Once a format is clicked, the drop-down closes and an export file is automatically downloaded onto the user's machine.
The Business Intelligence Export can also be automated with the included web service. The user can append start and end dates to the request (as a querystring) or leave them off (in which case the default start and end dates will be used). The response includes any issues that have been created or updated within the given (or default) dates including all their worklog and comment records.
The Business Intelligence Export web service is designed for use within your organization's firewalled network. The normal use case is pulling data from Jira into a business intelligence system, a data warehouse, or directly into a report or dashboard. Attempts to call the web service from an external site will result in an HTTP 401 error because it will not pass credentials through from the client to the rest service.
Installing the Business Intelligence Export toolset is very easy.
The Business Intelligence Report and Web Service both accept start and end dates. These allow you to pull any issues (with full worklogs and comments) which were created or updated within the time period defined by the start and end dates that you entered.
The first date of the period of time over which issues will be extracted. Your report will contain any issues created or updated after midnight on this date. If you enter nothing, the default date of one day ago will be used.
The last date of the period of time over which issues will be extracted. Your report will contain any issued created or updated before 11:59:59 PM on this date. If you enter nothing, the default end date of today's date will be used.
The data can be exported from the report in any of the following formats:
The Business Intelligence Extract tools present four categories of information about an issue:
Note: A full description of the fields provided in each of these categories is provided in the Data Dictionary section below.
The names of the fields are presented with camelCased names. For example:
Each attribute is prefixed with the category to which it belongs. For example, the author of a comment is labeled as "commentAuthor" in (JSON or XML) while the author of a worklog entry is labeled as "worklogAuthor".
The data is presented as a flat file so the entire extract of new or changed issues for a period can be completed in one operation.
To aid in filtering out the data necessary for any transform or load steps, we identify issues separately from their comments or worklog entries.
This identification is done using the attribute recordType which is on every record:
Issue Records are identified with a recordType "I"
There is one of these lines for each issue that was created or updated during the user-specified (or default) period. These rows include project and issue data. So, even if no worklogs or comments have been added to the issue, you can read these records to see that an issue's original estimate or status was changed.
Comment Records are identified with a recordType "C"
There is one of these lines for each comment written on any issue that was created or updated during the user-specified (or default) period. These rows include project and issue data plus data describing the comment that was made (who made it, when it was entered/updated, what was written, etc.). So, if, for example, you were interested in how many comments are being written about issues, you could aggregate these rows to get a count.
Worklog Records are identified with a recordType "W"
There is one of these lines for each issue that was created or updated during the user-specified (or default) period. These rows include project and issue data plus data describing each worklog entered on each issue. These rows might be used for things like aggregating work time by user, issue, project, etc.
All dates are presented in YYYY-MM-DD hh:mm:ss format because this is easy to parse in almost any programming language and internationally very readable (big to small) by human users.
Each record returned includes:
| Name | Data Type | Description |
|---|---|---|
| recordType | String | A short string that indicates whether this record provides information about an issue (I), a comment made on an issue (C), or a worklog recording work done on an issue (W). |
| project | String | The abbreviation used to identify this project. For example, as a prefix on all issues created for this project like "DEV" in the issue DEV-46 which is the 46th issue created in the Development project. |
| projectId | Integer | The internal identifier used by JIRA to uniquely identify this project. |
| projectName | String | The full project name assigned to this project when it was created. For example, "Development" or "Web Design". |
| projectLeadUserName | String | The display name of the Jira user who is currently assigned as this project's project lead. |
| issueKey | String | A user-friendly way to identify each issue that concatenates the project abbreviation with an integer that is incremented each time an issue is created within this project. For example, DEV-1, DEV-2, DEV-3, etc. |
| issueId | Integer | The internal identifier used by JIRA to uniquely identify this issue. |
| issueCreated | Date | The datetime that this issue was initially created in YYYY-MM-DD hh:mm:ss format |
| issueUpdated | Date | The datetime that this issue was last updated in YYYY-MM-DD hh:mm:ss format |
| issueCreatorUserName | String | The display name of the Jira user who created this issue. |
| issueDueDate | Date | The datetime that this issue has been given as its desired completion date in YYYY-MM-DD hh:mm:ss format. |
| issueRemainingEstimate | Integer | The difference between the original estimate of the time it should take to log this work and the amount of time logged so far on this issue (in seconds). |
| issueOriginalEstimate | Integer | The amount of time that it was originally estimated it should take to complete this work (in seconds). |
| issuePriority | String | The priority currently assigned to this issue. For example, "High" or "Medium". |
| issueReporter | String | The display name of the Jira user who reported this issue. This may be selected by the issue' creator when creating the issue if they heard about it from somebody else (a very common situation in IT settings). |
| issueStatus | String | The current position of this issue as it is moving through the workflow for this project. For example, "To Do", "Selected for Development", "In Progress", or "Resolved". |
| issueTotalTimeSpent | Integer | The total amount of time logged on this issue (i.e., the sum of the time logged on all worklog entries for this issue) in seconds. |
| issueVotes | Integer | The number of votes that this issue has received from users. This is used by some teams as a measure of the importance of an issue and issues with more votes are scheduled for work ahead of issues with less votes. |
| issueWatches | Integer | The number of watchers that are following this issue. These are interested parties who receive updates as any changes are made to the issue. |
| issueResolution | String | If this issue is resolved, then this field lists the final resolution status (e.g., "Resolved" or "Duplicate" or "Will Not Fix"). |
| issueResolutionDate | Date | If this issue has been resolved, then the datetime at which it was resolved is listed here in YYYY-MM-DD hh:mm:ss format. |
| commentId | Integer | The internal identifier used by JIRA to uniquely identify this comment. |
| commentAuthor | String | The display name of the Jira user who wrote this comment on this issue. |
| commentAuthorKey | String | The unique system identifier of the Jira user who wrote this comment on this issue. |
| commentCreated | Date | The datetime that this comment was created in YYYY-MM-DD hh:mm:ss format |
| commentUpdated | Date | The datetime that this comment was last updated in YYYY-MM-DD hh:mm:ss format |
| commentUpdateAuthor | String | If the comment has been edited, this field lists the display name of the Jira user who editted this comment on this issue. |
| commentText | String | The text of the comment that was entered on this issue. |
| worklogId | Integer | The internal identifier used by JIRA to uniquely identify this worklog entry. |
| worklogAuthor | String | The display name of the Jira user who entered this worklog entry on this issue. |
| worklogAuthorKey | String | The unique system identifier of the Jira user who entered this worklog entry on this issue. |
| worklogCreated | Date | The datetime that this worklog entry was created in YYYY-MM-DD hh:mm:ss format |
| worklogStarted | Date | The datetime that this worklog entry claims that the logged work was started in YYYY-MM-DD hh:mm:ss format (this can be edited by the user). |
| worklogUpdated | Date | The datetime that this worklog entry was last updated in YYYY-MM-DD hh:mm:ss format |
| worklogTimeSpent | Integer | The amount of time logged in this worklog entry (in seconds). |
| worklogText | String | The text of the worklog entry that was entered on this issue. |
Are there any date range restrictions?
Yes, using the start and end date parameters, you can create a time period of up to 31 days long. Any longer than that and the amount of data returned may create memory problems on your Jira server or your web client.
Are issue-level security restrictions respected??
Yes. The currently logged in user only has permission to extract issues which they have permission to view. This may mean that a special user needs to be created to run the extracts.
The Business Intelligence Export report and web service can diagnose several common issues which might generate unanticipated results. It reports these to the user by showing a red error box with a description of what is wrong and the resolution steps. Here is a complete list of the errors that may be encountered.
| Error | Message | Possible Resolution |
|---|---|---|
| bad-response-code-error | ERROR: Login request unsuccessful | The report could not log into JIRA to retrieve data. The HTTP response code issued was: HTTP RESPONSE CODE: ____ It is possible that your credentials do not have permission to access JIRA REST services. If this is the case then you could try running the report under a user who has access to REST. If you do not have the necessary accces, please contact your JIRA administrator to adjust your permissions. |
| submit-request-error | ERROR: Login request unsuccessful | The report could not log into JIRA to retrieve data. The error message was: Please contact your JIRA administrator to troubleshoot this error. If they cannot resolve it, then open a support ticket ticket with the report's developer by visiting http://ionafx.com/support.html |
| rest-login-unsuccessful-error | ERROR: Login request unsuccessful | The report could not log into JIRA to retrieve data. It is possible that your credentials do not have permission to access JIRA REST services. If this is the case then you could try running the report under a user who has access to REST. If you do not have the necessary accces, please contact your JIRA administrator to adjust your permissions. |
| issue-retrieval-error | ERROR: Issue parsing failure | While retrieving data for your report, an issue was returned whose data could not be parsed. The error message was: ______ Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| issue-search-error | ERROR: Issue search failure | While retrieving data for your report, the search service encountered an error. The error message was: ______ Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| user-authentication-error | ERROR: Only authenticated users are allowed access to this report. Please login to Jira to view this data. | You have attempted to run the report without logging into JIRA. Please log into JIRA, then attempt to re-run this report. |
| license-error | ERROR: Your license for IonaFX Business Intelligence Export Report is not valid. | This product is available as a Free Trial and your trial period may have run out. Alternatively, it is possible that your license has expired or your payment method needs to be changed. In any of these cases, the solution is to simply visit our page on the Atlassian Marketplace to purchase a valid license. Then, have your Jira Server administrator enter the new license key into Jira at our report's App Management listing. |
| rest-service-error | ERROR: REST Service reported an error | The REST service which collects the data to display on this report has issued the following error: ______ Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| date-parsing-error | ERROR: The dates that you entered for the start and end of the period to analyze were not recognized. | Please return to the report's configuration page and enter new dates in dd/MMM/yy format (e.g., 01/Dec/18). Alternatively, you can use the date picker controls to select your dates. The specific error returned by the date parser was: ______ |
| response-parse-error | ERROR: Response could not be parsed | The response received from the web service could not be parsed. The error message generated was: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| records-parse-error | ERROR: Response could not be parsed | The response received from the web service was valid, but records (issues, worklogs, and comments) could not be parsed from it. The error message generated was: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| records-empty-error | ERROR: No data found | No records were found which match the search criteria. The start and end dates that you used specify a period over which no work was logged. Please return to the configuration page for this report and select a different time period for analysis. |
| xml-parse-input-error | ERROR: Unable to parse input to build the XML export file | The component which builds the XML-formatted file for downloading from this report has issued the following error: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| xml-render-error | ERROR: XML rendering error | The component which builds the XML-formatted file for downloading from this report has issued the following error: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| xml-uri-encode-error | ERROR: XML file encoding error | The component which encodes the XML-formatted file for downloading this report has issued the following error: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| json-uri-encode-error | ERROR: JSON file encoding error | The component which encodes the JSON-formatted file for downloading this report has issued the following error: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| negative-time-period-error | ERROR: The time period entered for this report is too short | The time period entered for this report must cover at least one day. Please check that the end date you provided is not equal to or before the start date. |
| negative-time-period-calculation-error | ERROR: Time period calculation error | While attempting to calculate if the time period represented by your start and end dates is not zero or negative, the server encountered the following error: _____ Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| date-limit-error | ERROR: The time period entered for this report is too long | Entering a period of more than one month is prohibited because it may consume (1) too much memory on your Jira server, (2) too much bandwidth on your network, (3) too much memory on your client, or (4) create downloads that are too large for your client to accept gracefully. "The time period entered for this report must cover no more than 31 days. Please check that your start and end dates do not cover a period of more than 31 days. |
| date-limit-calculation-error | ERROR: Maximum time period calculation error | While attempting to calculate if the time period represented by your start and end dates covers more than 31 days, the server encountered the following error: _____ Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| csv-parse-input-error | ERROR: Unable to parse input to build the CSV export file | The component which builds the CSV-formatted file for downloading from this report has issued the following error: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| csv-render-error | ERROR: CSV rendering error | The component which builds the CSV-formatted file for downloading from this report has issued the following error: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| csv-uri-encode-error | ERROR: CSV file encoding error | The component which encodes the CSV-formatted file for downloading this report has issued the following error: Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
| server-error | ERROR: The server reported an error | The component which builds this report has issued a server error containing the following message: ______ Please open a ticket with the report's developer by visiting http://ionafx.com/support.html |
1.0.0-RELEASE
First production release
1.0.3-RELEASE
The 1.0.3 release focused on UI improvements, but also includes Unicode handling upgrades and refactored error handling.
Visit our privacy policy page to see how we use your data and protect your privacy.
Privacy Policy for Business Intelligence Export