The new Jira tooling does support importing ballot results from spreadsheets. In the near term, this is limited to HL7 participants with 'Manager' access - generally co-chairs or facilitators responsible for conducting the ballot. The intention is for balloters to eventually be able to import content from spreadsheets themselves (and to be responsible for ensuring the spreadsheet imports cleanly).
Ballot administrator steps
Before imports are possible, the ballot coordinator (someone with administrator privileges) must create the relevant ballot definitions for all closed ballots. This involves the following steps:
- Create a CSV that looks like this either by exporting information from the ballot desktop database or creating it manually.
- In Jira, use System, External System Import and select the spreadsheet file. Choose "Use an existing configuration file" and use the file maintained here.
- Click 'next' three times and complete the import
- Go to each of the imported projects and
- click on the Product Family to bring up a window that allows setting the appropriate Specification and, if necessary, Related Artifacts and/or Related Pages.
- Open the ballot
- Close the ballot
Ballot manager steps
To import a spreadsheet, first go to the HL7 Balloter dashboard. If you are a manager it should display a control that looks like this:
- You'll need to consolidate all of the ballot spreadsheets using the macro available from the HL7 ballot desktop
- The consolidation process will include submitter comments that say things like "see comments submitted by xxx" or "see attached spreadsheet". All of those rows should be removed. We only want comments that are actually 'comments' that ask for changes to the specification or that actually comment on the specification
- Simply choose the ballot file to import and click on "Import ballot comments". (Do not click 'ignore warnings' on your first import attempt.) The process takes a while to complete, so be patient. When complete one of two things will happen:
- You'll get a message indicating that the ballot content has been successfully imported into Jira (including an indication of how many issues were created and how many existing issues were linked to the ballot)
- More likely, you'll receive a message indicating that there were errors and/or warnings and letting you know that a revised spreadsheet has been emailed to you highlighting the problems
The email will take a few minutes to arrive (or longer, depending on your typical experience with emails). The updated spreadsheet will change the background color of all problematic cells (orange for errors, yellow for warnings) and will have a comment on each impacted cell indicating what the issue is. Fix your issues and try again. If you run into an issue you don't understand, raise the question on the Jira stream on chat.fhir.org.
Ballot Spreadsheet Import QA Guidance
There are a number of QA issues that need to be resolved before you can import a spreadsheets.
|1||Email address of submitter not copied to comment when Amalgamation Macro is run to merge spreadsheets||Copy the email address to each comment from the first tab of the original spreadsheet submitted by the voter|
|2||Amalgamation macro incorrectly adds a validation to columns that should not have validation||Move validations from all columns except "Vote" and "Type" columns|
|3||Submitter name and/or email address does not match JIRA - will be identified on import||Search Jira to find correct name and/or email address for submitter|
|4||Submitter does not have a JIRA Account - will be identified on import||Contact firstname.lastname@example.org to request that a JIRA account be created for the user - provide name and email address|
|5||Missing "Vote" and/or "Type" for a comment|
Attempt to determine vote from the comment
May need to contact the voter
|6||Missing or inappropriate "sub-category"|
Delete the sub-category if it should not be present or choose an appropriate sub-category if missing
|7||Incorrect "Ballot" information||Look up Ballot information in JIRA and update spreadsheet|
|8||Missing "Resource" and/or "HTML" information||Derive the resource and HTML from the Section and from their comments.|
|9||Incorrect "Resource" information - invalid artifact included|
Derive the missing resource from the Section and from their comments.
Incorrect content in HTML Page Name - this is not a URL but rather the name of the page in the specification.
Derive the missing HTML from the Section and from their comments.
Voters with a tracker# have filled in extra columns that should be left blank.
Remove content from columns that should not have content.
Summary is too long, missing or duplicate
Add a summary for the comment
Adjust a summary it too long
Change the summary to ensure it is not a duplicate