Structure input (XLSX) and report (CSV) format specification

The Structure can be populated by attaching a XLSX  (Microsoft Office 2007-365 format) file to the PPM issue and specifying this during the workflow transition by filling in the filename in a appropriate field. That field has to be configured by the Jira Administrator in the workflow's post function beforehand though.

Input file format (XLSX)

  • The structure can be "filled" by providing a file in the XLSX format (Microsoft Office 2007-365 / Microsoft Excel (OpenXML) / Mime Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).
  • Only the first sheet will be used.
  • The spelling of the column names is important
  • The "first" rows columns, i.e. from A to Q, are required headers
  • The second to n-th columns A through D require data to be present.
  • If data is required to be present for the other (second to n-th) columns E through Q, or maybe even custom field columns
    • Reminder: fields can
      • either be required through a Field Configuration Scheme
      • or a Workflow validator on the create transition
    • you may want to contact your administrator for details
  • If you want to set multiple values for a version, fix for version, component, labels or any applicable custom field (e.g. single or multiple selects, checkboxes, radioboxes), please separate the values by a linefeed in the same cell.
    • If any of the given values cannot be mapped to a valid value in Jira the importer will stop and produce an error message.
  • Referring an existing Issue Key in the second column (see list of columns below) will allow the insertion of existing Issues.
    • Filling in a dummy value will always trigger the creation of an issue.
  • An #END cell will stop the field definition if encountered in row number 1. The first legal column with such a marker is column R.
  • An #END cell is required for all subsequent rows. It has to appear in the same column as in row 1.
  • An #END cell will finish the import when encountered in column A.
  • Working with references or formulas in the first sheet will not work will and yield bogus data
    • i. e. referring to another cell value like this =$Sheet2.$B$3 will not use the referenced cells data but use or insert the formula in plain text causing either wrong data (e.g. for summary) or wrongly references issues (e.g. when used for the issuekey)
  • You can copy the example table from below and insert this directly into your Excel, LibreOffice or equivalent program.
ABCDEFGHUJKLMNOPQR...?

LAST COLUMN

levelissuekeyissuetypesummarydescriptionversionsassigneecomponentsduedateenvironmentfixVersionslabelspriorityreportersecuritytimeestimatetimeoriginalestimateAny number of custom fields may be referenced in each following row until the #END markerCustom fields may be specified by their namesor as customfield_12345#END

REQUIRED

Any positive integer from 0 to 263-1 specifying the "indentation level" or #END

REQUIRED

Placeholder, e.g. XYZ, or an existing valid Issue Key, e.g. PRJ-1

REQUIRED

Issue Type, e.g. Bug or Task

REQUIRED

Summary

OPTIONAL

Description

OPTIONAL

Versions, i.e. Affected Versions; multiple lines of versions allowed

OPTIONAL

Assignee, i.e. Username

OPTIONAL

Components; multiple lines of versions allowed

OPTIONAL

Due Date; usually YYYY-MM-DD

OPTIONAL

Environment; free text field

OPTIONAL

Fix Versions; multiple lines of versions allowed

OPTIONAL

Labels; multiple lines of free descriptive labels allowed

OPTIONAL

Priority, i.e. Major or Critical

OPTIONAL

Reporter, i.e. Username – will be the configured Project Lead in case this is not specified here

OPTIONAL

Issue Security Level; usually unused

OPTIONAL

The remaining time estimate

OPTIONAL

The original time estimate

OPTIONAL

Some data for the first custom field

OPTIONAL

Some data for the second custom field

OPTIONAL

Some data for the n-th custom field

REQUIRED

#END

Very wide example table

The example table is very wide, you may need to scroll sideways to see the full contents.

A scrollbar is available at the bottom of the table.

Examples

In this case all issues would be created and linked into the structure unless an error occurs.

levelissuekeyissuetypesummarydescriptionversionsassigneecomponentsduedateenvironmentfixVersionslabelspriorityreportersecuritytimeestimatetimeoriginalestimateSome CustomfieldCustomfield_12345CustomerStory Points#END
0PRJ001TaskProject XYZProject XYZ Description















#END
1PRJ001TaskManagementManagement















#END
2PRJ001TaskProduct ManagementProduct Management















#END
3PRJ001TaskDesignDesign















#END
4PRJ001TaskUIUI















#END
4PRJ001TaskComponentsComponents















#END
4PRJ001TaskStructureStructure















#END
4PRJ001TaskFlowFlow















#END
3PRJ001TaskControllingControlling















#END
4PRJ001TaskBillingBilling















#END
2PRJ001TaskDocumentation ManagementDocumentation Management















#END
3PRJ001TaskOngoing DocumentationOngoing Documentation















#END
#END




















In this case the issues that already exist (1,2,3 and 42) will only be linked into the structure while the other issues would be created and linked into the structure unless an error occurs.

Any data for the issues PRJ-1, PRJ-2, PRJ-3 and PRJ-42 will be ignored and but are required in the input for keeping a clear and understandable structure in the XLSX file intact.

issuetypesummarydescriptionversionsassigneecomponentsduedateenvironmentfixVersionslabelspriorityreportersecuritytimeestimatetimeoriginalestimateSome CustomfieldCustomfield_12345CustomerStory Points#END
TaskProject XYZProject XYZ Description















#END
TaskManagementManagement















#END
TaskProduct ManagementProduct Management















#END
TaskDesignDesign















#END
TaskUIUI















#END
TaskComponentsComponents















#END
TaskStructureStructure















#END
TaskFlowFlow















#END
TaskControllingControlling















#END
TaskBillingBilling















#END
TaskDocumentation ManagementDocumentation Management















#END
TaskOngoing DocumentationOngoing Documentation















#END




















Output file format (CSV)

  • The importer will generate a CSV formatted file of the first 4 columns from the input file.
  • The second column will be updated to hold the generated Jira"s Issue"e;s Key.
  • The importer will write all issues to the CSV file if no error occurred.
  • The importer will stop at a line containing an error. Refer to the generated error messages found in the comment at the original Jira Issue.
  • If requiring a re-run, the Issue Keys should be copied into the new input file.
levelissuekeyissuetypesummary
level as calculated by the processissuekey, either generated or copiedissuetype used during creationsummary used during creation

Example

levelissuekeyissuetypesummary
0PRJ-1TaskProject XYZ
1PRJ-2TaskManagement
2PRJ-3TaskProduct Management
3PRJ-4TaskDesign
4PRJ-5TaskUI
4PRJ-6TaskComponents
4PRJ-7TaskStructure
4PRJ-8TaskFlow
3PRJ-9TaskControlling
4PRJ-10TaskBilling
2PRJ-11TaskDocumentation Management
3PRJ-12TaskOngoing Documentation