This page describes the steps taken by the Ballot Coordinator in managing the balloting process.  Everyone is free to read this page, but many of the capabilities described here will only be available to the Ballot Coordinator.

Ballot Registration

Ballot Communications to HL7.org (all members) List

This listing below is an overview. These are typical communications. Ballot openings, changes, out-of-cycle ballots and the like are likely to require additional or different announcements.

• Formation of Review Groups – 30 days before ballot opening. Depends Upon: NIB Form Deadline, Drafting of document(s), CoChair Review
• Ballot Pool Signup Opening – At least four weeks before ballot opening
• Initial Ballot Opening – Usually a Friday, but in no cases later than 30 days before the scheduled ballot closings.
• Ballot Pool signup reminders – usually a week before the signup period closes (when ballots open), and then a final reminder a day or two before.
• Balance of Interest Notice – within 7 to 3 days before the ballot opening, review the normative pools for balance of interest and send out notice to HL7News. A copy of the email gets saved to the appropriate folder. There is a query to help with this if needed on an HQ page.
• Normative Ballot Quorum reminder – sent from the ballot desktop; a week before ballot closing and again as needed a couple days before the closing (you can also use the individual pool contact emails for this). A copy of the email gets saved to the appropriate folder.

Ballot Communications to TscAdmins and Cochairs

The listing below is typical. Depending upon the cycle, additional communications to either the full list or individual WGs are likely to be needed.

• NIB Deadline [T-6] – 1 month, two weeks, one week and three days. Depends Upon: NIB Form Deadline
• Draft of Formation of Review Groups document – ASAP after NIB deadline
• Create Ballot Cycle TSC Approval List – Create and send to Lynn and she will get it on the TSC agenda for review.
• Create list of Outstanding Reconciliation Activities – Create and send to TSCs and CoChairs for review.
• Draft Copies of Ballot Comment Spreadsheets – Create and send to CoChairs for review. This is done using a comments spreadsheet template and a NIB_Summary_template spreadsheet with embedded macros (details only on HQ Intranet).
• Reconciliation Deadline [T-3] – send out reminder(s) three weeks before final content deadline.
• Final Content Deadline [T-1 on Ballot Countdown] – send reminders Wednesday or Thursday following previous deadline.
• Ballot Opening – Wednesday or Thursday following previous deadline
• Quorum Levels – In final week of ballot
• Ballot Results – One day after ballot close

Notification of Intent to Ballot Form

During or shortly before each WGM, the on-line NIB form should be updated for the upcoming ballot cycle. For instance, during the January 2021 WGM, the NIB form for the May 2021 Ballot Cycle should go live.

This involves several steps:

• Check with Karen Van to make sure no updates to the NIB form are required.

• Ensure that the proper ballot cycle and ballot project records exist or are created in the production HL7 SQL Server DB.

• Update the config.cfm file that the NIB form uses on the web site

• When the form has been tested on Dev and pushed to production, announce the availability of the form to the cochairs and  tscadmin lists using the previous cycle's announcement as an example.

• Set the current ballot cycle in the SQL database and de-activate the prior cycle

• Set the ballot cycle for all ballot records for new ballotable items are pushed forward in the SQL database. The NIB form SQL queries are set to look for this pattern and then display these as items the WG could select to ballot, but they will display as "New Document" that have not balloted in any cycle. If you don't do this, it will look like they're already balloting in the current cycle

• After the New Project Scope deadline following the WGM, check with the PMO for new projects. Records for any ballotable items coming from these will need to be created in the  SQL DB on production. 

Ballot unique ID / Unique Ballot ID starting point

(ballot code components separated by underscores) made up of

• HL7
• Family Name e.g. FHIR, CDA, V2, or XParadigm (unless explicitly referenced by the project, exclude the release id of the base family standard)
• Artifact type abbreviation e.g. DAM, IG, FP
• Item code; acronym of project title or commonly known by e.g. CQL, HQMF, SPECMEDRX, MHEALTH_ADE
• Abbreviation for Release number for this specific ballot item e.g. R1
• "TBD"

Examples: FHIR_IG_QMEXCHANGE_R1_D4_2020SEP

JIRA Ballot set-up

Important Note: When performing transitions on Ballot Definitions (e.g. opening, closing, locking, unlocking, etc.), the process can take a while.  Sometimes, the request may even timeout and when you refresh it may appear that nothing has happened.  Wait longer.  If you give it a few minutes (maybe even 5) after timing out and refresh again, you should see the change having fully taken effect.  If there is a dialog box up (e.g. as with 'Un-open'), you may need to browse the ballot definition in another tab to see if it's now complete.  Once it is you can 'cancel' the operation, though cancelling won't actually do anything.

Once the list of ballots is finalized and information has been entered into the ballot desktop, the ballot definition information also needs to be propagated to Jira.  This can be done at any point, but should be done at least 2 weeks before ballot opening to allow time to link ballot information to relevant specifications, artifacts and pages and to allow review of that information.  The process for setting up Jira is as follows:

1. Export the ballot definitions from the Ballot Desktop as a CSV file (scripts in BitBucket)
   

   1. File includes:

   2. Header row

      1. String "BALDEF - ' plus the numerical ballot id as the ballot_id (the numerical ballot id is found in the URL construction of the detail of the ballot tally from the ballot desktop e.g. "http://www.hl7.org/ctl.cfm?action=ballots.tallydetail&ballot_id=1914" plus the remaining verbiage &ballot_voter_id=numericvoterid&ballot_cycle_id=553
      2. Case statement on the standard id (V2, CDA, FHIR, OTHER) as Family,
      3. Formatting of the ballot code (Ballot unique ID as described above) to CCYY-Mmm, concatenated with "->", then ballot code, then case statement on the ballot level to get NORM, Inform, STU, Comment as ballot_def_name,
      4. Case statement on the ballot level to get Informative, Normative, STU, Comment as ballot_level_code,
      5. Formatting the ballot code to CCYY-Mmm plus ballot name as ballot_name,
      6. Beginning date as begindate as YYYY-MM-DD hh:mm:ss.ssss,
      7. Ending date as enddate as YYYY-MM-DD hh:mm:ss.ssss,
      8. Setting the downloadURL from either the download URL or from the ballot site URL of the ballot material
      9. Counting total_voters,
      10. Setting value of 0 to affirmatives, negatives, abstensions,
      11. Setting "Non-quorate"' as ballot_status,
      12. Setting 'Ballot Definition' as issue_type

   3. 
      

1. 1. Note: If ballot information changes in the Ballot Desktop after the export has occurred, either the same changes will need to be made in the corresponding Jira Ballot Definition issues or all of the Jira Ballot Definition issues for this ballot cycle will need to be deleted and the whole Ballot set-up process run again.  (Use extreme caution in deleting Ballot Definitions - once they're gone, there's no way to get them back.)
2. Import the exported CSV file into Jira
   1. From Jira, open the Jira Administration menu (gear icon towards top-right) and select System.  If necessary, confirm administrator access.
   2. On the menu at the right-hand side, select External System Import
   3. Alternatively, just go to this link: https://jira.hl7.org/secure/admin/ExternalImport1.jspa
   4. Select CSV
   5. Select the previously exported Ballot Definition CSV file and click Use an existing configuration file
   6. Choose this file: CSV-configuration-BALDEF.txt (from Bitbucket)
   7. Click Next three times, then Begin Import
   8. You should see "1 projects and X issues imported successfully!" where "X" should be the number of ballots
3. Run the "Fix ballot code sort" process from the BallotAdmin dashboard to properly sort the ballot codes (so newest appears first instead of last and sub-codes are alphabetic).  Note that this will kick off a re-index.
4. Go to the BallotDefinition project and update all of the imported records to point to the appropriate specification, artifacts and pages
   1. To edit, simply click on the product family and that will open up an edit window
   2. The "Specification" options will be a drop-down that is controlled by the product family associated with the ballot
   3. In most cases, the ballot will cover the entire scope of the specification and nothing further needs to be done.  However, in some cases, the ballot only covers a subset of the artifacts and pages in the specification.  In that case, all of the artifacts and pages that are in-scope for the ballot need to be listed.
      
      1. Specification Feedback items will only be eligible as ballot comments if they specify at least one of the pages or artifacts that are listed as "in-scope" for the ballot
      2. It'll take 4-5 seconds per ballot definition to open the item, select a specification and update the item.  It'll take considerably longer to pick specific pages and artifacts.
   4. One common pattern for ballots is that there will be a couple of ballots with "limited scope" of only one or a small set of artifacts and then there will be a single ballot for "everything else".  Rather than having to (correctly) select 100+ artifacts and pages for the "everything else", there's a Remaining Elements option that allows you to select all resource and pages that have not been identified as part of one of the existing ballots
      1. To use this, first fill in the artifacts and pages for all of the "narrowly scoped" ballots
      2. Then fill in the "Specification" for the "everything else" ballot and save without specific artifacts to enable the Remaining Elements button which will become available on the ballot definition's issue page, and push it
      3. Some artifacts and pages might be applicable to multiple ballots, so it may be necessary to add additional items to the "everything else" ballot after choosing the "Remaining Elements" button
      4. Pushing Remaining Elements will first remove whatever elements had been selected, so you may need to re-add items
   5. NOTE: The drop-down contents for both the list of specifications and the lists of artifacts and pages for each are determined by the Jira-Spec-Artifacts Github project
      1. It is only possible to choose artifacts and pages once a specification has been chosen
      2. If you change the specification, the list of artifacts and pages will automatically be wiped and will need to be reselected (if necessary)
   6. It will not be possible to "Open" a BallotDefinition until a Specification has been selected.  However, there is no check to ensure that appropriate artifacts and pages have been selected.
      1. If artifacts and pages are edited after balloting has started, they will take effect for any new votes, but will not impact votes that have already been submitted
5. Once the specifications, artifacts and pages have been selected, this content should be double-checked with the responsible work group.  The Draft Ballots for Review filter is available for trusted users and administrators for this purpose - relevant contacts can be emailed a link to the report or it can be exported as a CSV and emailed.  The report also shows on the BallotAdmin desktop, though this will not be publicly accessible.  Be sure to use the "list view" rather than the "detail view".  
   1. Review and sign-off of this information should be added to the ballot countdown
   2. Addition of the final ballot artifact location (specification location) must be added at ballot opening
6. Lock any prior iterations of Jira BALDEF issues for items going back to ballot. Find prior Jira iterations using jql query
7. When posting ballot spreadsheets to the ballot site for users who intend to upload their own comments using a spreadsheet, the ballot manager should ensure that the "Ballot" column is filled in with the "Ballot Code" from the associated Ballot Definition.

Ballot Opening

Once the ballot registration period has closed, information about all balloters who have signed up needs to be propagated from the Ballot Desktop to Jira so that those registered voters can actually vote.  This process works as follows:

1. Export the ballot submissions from the Ballot Desktop as a CSV file (scripts in BitBucket)

   1. Taking voter information from their enrollment on the ballot desktop to participate in a particular ballot, for each voter and vote combination (e.g. one voter may sign up for five ballots so would create five records in the export:

      1. Setting Email address as reporter,
      2. Setting First and last name as reporter_name,
      3. Organization as organization,
      4. Setting String "BALDEF-" plus the numerical ballot id as ballot_def_key
      5. Setting 'Ballot Submission' as issue_type
      6. Setting 'No Vote' as Vote
      7. Constructing 'summary' from the literal 'No Vote - ' plus the name, organization in brackets, if present, formatting the ballot cycle code to CCYY-Mmm, ballot id, and ballot level,
      8. and setting the unique sequential vote_id identifier
      9. Case statement on membership type to fold to camel case as membership_type_id
   2. Review the CSV file with final edits in notepad++ with encoding as UTF-8 (no BOM)
      1. No titles or designations are allowed (MD, PhD, etc)
   3. Note: If balloter information changes in the Ballot Desktop after the export has occurred, those changes will need to manually be made in Jira as well.  (E.g. If a balloter gets added because there were technical or other issues that prevented them from registering properly, or someone's eligibility to ballot ends at some point during the ballot cycle)
      1. If someone's eligibility to ballot is removed, be sure to remove any "vote items" associated with the ballot submission.
      2. Staff or comped co-chairs (comped membership for co-chair duties does not have ballot privileges) will not be in the export file

1. Import the exported CSV file into Jira
   1. From Jira, open the Jira Administration menu (gear icon towards top-right) and select System
   2. On the menu at the right-hand side, select External System Import
   3. Alternatively, just go to this link: https://jira.hl7.org/secure/admin/ExternalImport1.jspa
   4. Select CSV
   5. Select the previously exported Ballot Submission CSV file and click Use an existing configuration file
   6. Choose this file: CSV-configuration-BALLOTSubmission.txt (from BitBucket)
   7. Click Next three times, then Begin Import
      
      1. This process can take 5-10 minutes
   8. If any of the balloters are not yet set up with a Jira account (or are registered in the HL7 ballot desktop with a different email than seen in the Jira account) you'll see a message saying "What would you like to do with created users?". 
      1. Choose Assign their application access manually and choose Jira Core
   9. Otherwise, you should see "1 projects and X issues imported successfully!" where "X" should be the number of votes/rows in the export spreadsheet
2. If new users were created in the previous step, it will be necessary to post-process the user accounts to assign the correct user name and to ensure that the user receives an email notification of their Jira account.  This can be done by running the Correct (and notify) users process from the BallotAdmin dashboard.
   1. Select the same ballot submission CSV file as was previously imported, then click on Fix and notify users.
   2. The process will go through and do a few things on the first pass:
      1. If any of the newly-created Jira users use an email address that is already associated with an existing Jira account (because the pre-existing Jira user has an "HL7Email" preference set specifying that email address), then the process moves all of the imported Ballot Submissions associated with that email address to the pre-existing Jira user and then deletes the newly-created user for that email address
      2. If there are any remaining newly-created users, it will check to see if the user name complies with the Jira naming rules (as per the NEWID project).
         • The gist of the rules are First M. Last where the middle initial is optional.  Names must generally start with an upper case character (i.e. camel case, but things like 'van' are exceptions).  Also, names can't have designations after them (so no MD, PhD, etc.)
         • Names must not have trailing spaces after designations are removed.
         • Note that the RegEx is maintained separately for this code, so if the rules for NEWID get changed, they should be changed for the fixNewUsers REST endpoint too.
      3. If the name is fine, it will use the same algorithm (see note immediately above - this too is a copy that must be maintained) as NEWID to identify candidate existing users that could potentially be a match
      4. Finally, it will spit back a 'new' CSV file that just lists the 'new' users and any errors about name formatting
   3. If the file is empty except for the header row, you're done.  Otherwise, the next step is to edit this file to determine what should happen with the new users. 
      1. Create a copy of the file for editing.
      2. Look up each of the "new" users in Jira, under Jira Administration/ User Management. There are two options
         1. Put "Y" or "Yes" in the newly added "Create User?" column if the newly created user does need to exist.  (This will cause the user's "full name" to change from their email address - as it is set during the initial creation - to the name specified in the spreadsheet. Note: If the name didn't follow the rules, you'll need to correct it.
         2. Specify the userid of an existing user (the bit before the brackets) that should be substituted
            • Note - if the specified user is already tied to an existing HL7 website email, you'll get an error message asking if you want to override the existing association.  If you do, simply put an asterisk in front of the user name in the spreadsheet.
   4. Once the CSV file has been edited, select the new CSV file and run Correct and notify users again.  Keep looping until the CSV file is empty or tells you that all users were processed successfully.
3. "Open" all of the draft Ballot Definitions.  The easiest way to do this is to open the Draft Ballots for Review search and click on Tools to do a Bulk Change.  Opening the Ballot Definition will automatically open all associated Ballot Submissions.  Note that "Opening" the ballots and submissions doesn't necessarily allow voting.  Voting won't be permitted until after the Ballot Open Datetime has been reached.  That said, it will likely be confusing to people to see "Open" Ballot Definitions or Submissions they can't actually vote against, so it's best to only open ballots when it's actually time for them to open
   1. The easiest way to open all relevant ballot definitions is to use Bulk Changes
      1. Open the Draft Ballots for Review filter (or some other filter that shows draft ballot definitions) and select Tools, Bulk Change (all X issues)
      2. Select all issues or, if appropriate, select a subset of relevant issues, possibly adding an additional filter based on the Ballot Open DateTime.  Then press Next
      3. Select Transition Issues, Next
      4. Select Open Ballot, Next
      5. Disable Send mail for this update (unless you want a bunch of email), then select Next, and Confirm
      6. If you've missed including a Specification for any of these, you'll get error messages for each problematic issue - but the rest will work.  You can bulk-transition the remainder once you've fixed the problem(s)
      7. This process takes ~5 minutes 
4. Send the ballot submissions list of emails to Sadhana so she can offer training on Jira.

Ballot Closing

Once the ballot close date-time has been reached, users will no longer be able to submit ballot comments or change their votes.  However, to officially mark the ballot as closed in Jira, the status of both the Ballot Definition and the associated BallotSubmissions should be changed to "closed".  This will allow balloters to start to withdraw ballot comments based on the resolution of their comments.

As with transitioning from Draft to In Progress, transitioning a Ballot Definition from In Progress to Closed will automatically do the same for all In Progress Ballot Submissions associated with the ballot definition.  

Once the ballot has been closed, information about the overall votes of individual balloters needs to be transferred back into the Ballot Desktop.  This process has 3 steps:

1. Export all of the Ballot Submissions
   1. A daily CF job will run to obtain the results of that JIRA query and run an update statement against the relevant vote records in the HL7 db based on the ballot_vote_id (external id - ballot submission) 
   2. From the "Ballot Tally Details" screen of the Ballot Desktop, verify the participation counts against the Ballot Definition 'Organizational Participation' summary
2. Produce a 'ballot reconciliation' spreadsheet for the ballot that includes a snapshot of all ballot comments as they were submitted - prior to any retractions or withdrawals and prior to most reconciliation processes.  (In some cases, work group reconciliation may have occurred on some items prior to the conclusion of the ballot.)  To do this, go to the Ballot Definition record associated with each relevant ballot and execute the "Reconciliation Sheet" transition. 
3. This transition can be performed on a collection of ballot definitions at once, if desired, but each spreadsheet will have to be downloaded from the Ballot Definition manually.  The files should be named based on the Ballot Code for their respective ballot. Download these files to the respective Ballot Results folders.
4. Prepare the ballot results summary and associated Ballot Participant Summary sheets and create zip file
5. Upload zip file to TSC documents area and create link on Ballot Desktop Announcements area

Ballot Locking

Locking a Ballot Definition freezes the votes entirely.  Once a ballot is locked, no further withdrawals or retractions are possible.  The ballot's tallies are frozen in both Jira and on the Ballot Desktop, with the possible exception of the recirculation process (which is currently handled with the ballot desktop).  Locking can be performed for "For comment" ballots at any time after all ballot submissions are closed.  It can only be performed for other ballots once all ballot comments have been reconciled - i.e. they have transitioned to a status other than Draft, Triaged or Waiting for Input. A ballot should also be locked upon the opening of a new ballot of the same specification. Lloyd McKenzie it would be awfully nice to get help with a query upon import of the ballot definitions for a new ballot cycle to check for prior iterations of any specification in that cycle? Can do it one by one using  Getting issues...

but need work on one that queries by specification and current ballot cycle.

Working groups will ask the ballot coordinator to lock the ballot once they feel adequate time for withdrawal/retraction has passed.  Ballots must be locked prior to opening a new ballot on the same content, beginning the recirculation process or publishing the balloted specification.  

Before transitioning the ballot to be locked, a new reconciliation spreadsheet should be generated as per the steps mentioned above on Ballot Closing.  This should be posted as the reconciliation sheet for the ballot.  (Note that this will typically be done by the ballot manager rather than the ballot administrator.)

Editing Ballot Definitions and 'Special' transitions

Ideally, everything that's in the ballot desktop will be correct and no changes will need to be made after information has been imported into Jira.  Everything will open and close cleanly and there'll be no need to mess around with manually editing any of the Ballot Definitions or Ballot Submissions.  However, sometimes the universe isn't that kind.  The Jira projects to manage balloting have been set up, as much as possible, to allow for content to be adjusted when necessary.  However, this ability is strictly limited to "administrators" for the Ballot Definition and Ballot Submission projects.  It's not something that can be done by co-chairs or others.  In most cases, the administrator roles will be limited to HL7 Staff.  As well, all such changes (with the exception of deletions) are audited, so it's possible to see what changes have occurred.

Changing ballot open or close dates

The ballot opening and closing dates can be changed either on individual Ballot Definitions or on a collection of Ballot Definitions using Issue, Search, Tools, Bulk Change.  Note that changing dates will not affect votes already made.  For example, changing a ballot opening date to be later won't reverse ballots submitted when the open date was earlier.

"Un-opening" or "Un-closing" a ballot

Removing or adding someone to a ballot pool

Variable close dates

If, for some reason it's necessary to close a ballot for most users, but not all, the following process can be used:

1. At the regularly scheduled closing time,