Jira Ballot Process

Starting in January 

The Jira ballot process uses HL7's Jira environment and the Jira-based Specification Feedback process to help manage HL7 Balloting.

The initial steps for the balloting process - notification of potential balloters, balloter registration, achieving a balanced pool of balloters, etc. are all managed through the HL7 Ballot Desktop.  Once ballot registration is closed, a set of Jira Ballot Administrative Processes occur that propagate information about both the ballot itself and registered balloters into the Jira environment. 

This page describes how the Jira environment can be used by balloters to manage their ballot submission.  For organizational and affiliate balloters, additional guidance on Coordinating Ballot Submissions is also available.

Jira components

Jira organizes its content into a set of "Projects".  Each project contains a collection of records, or "issues".  To support the ballot process, HL7 uses three project types: 

Ballot Definition

This project identifies what ballots "exist".  It include information about what specification (or subsets of a specification) are subject to ballot and when the ballot is scheduled to open and close.  As the ballot process progresses, it will also provide a summary of the results (i.e. a count of votes, whether quorum is met, whether the ballot meets criteria to pass, etc.)  This information is kept up-to-date as users directly adjust their Ballot Submissions as well as when they flag specification feedback comments as Affirmative or Negative, when they Un-vote a comment and when they Retract or Withdraw a comment.  It will also reflect the deletion of any ballot submissions (e.g. due to lapse of membership during the ballot period).

The ballot definitions are maintained by HL7 staff.  The ballot administrator will ask co-chairs or content leads for particular ballots to review ballot definitions and ensure the information is correct prior to ballot opening - particularly for ballots that are focused on a subset of a publication rather than an entire specification.

Balloters may find it helpful to consult the ballot specification as a reminder about ballot open and close dates and ballot scope, but will never need to interact directly with issues in this project.

NOTE: It's possible to "watch" a Ballot Definition issue.  This will cause you to get an email every time the Ballot Definition changes.  That means one email every single time the vote total changes.  If you're really desperate to increase your email volume, this is a good way to do it, but otherwise you're better off just coming and taking a look every once in a while.

Ballot Definitions have 4 statuses.  What can happen with a ballot is governed by both ballot status and by the start and end dates associated with the Ballot Definition.

Ballot Definitions are created and managed by the Ballot Administrator based on work groups’ submission of “Notice of Intent to Ballot” (NIB) forms and approvals from the Technical Steering Committee .  Changes made to the status of a Ballot Definition will automatically cause equivalent changes in all associated Ballot Submissions.

Ballot Submission

A ballot submission record will exist for every voter that signs up to vote in a particular ballot.  The submission records are created through an export process from the HL7 Ballot Desktop.  The ballot submission maintains the record of that user's vote.  It aggregates all comments made about the ballot and shows the balloter's overall vote.  The overall vote is determined as follows:

• The overall vote starts out as No-Vote.  If no action is taken by the balloter, this will be their final vote
• The balloter can link their ballot submission to that of another voter.  This can only occur when:
  • The linking balloter's vote is set to No-Vote
  • The target ballot submission has a vote that is something other than No-Vote
  • The target ballot submission is associated with the same organization as the balloter's submission.  (This means that linking of votes is only possible for organizational and affiliate members.  See guidance on Coordinating Ballot Submissions for more discussion.)
• The balloter can manually adjust the overall vote to be either Affirmative or Abstain.  They can also manually adjust their vote back to No-Vote.  Changing a vote from No-Vote will remove any linkage to another ballot submission
• The overall vote is automatically set if the balloter ties any Specification Feedback items to their Ballot Submission as either affirmative or negative Ballot Votes.  If the balloter has any non-withdrawn and non-retracted negative ballot votes tied to their ballot submission, the vote is automatically locked to Negative.  Otherwise, if the balloter has any affirmative comments tied to their ballot submission, the overall vote is locked to Affirmative.  In both cases, the overall vote cannot be edited or linked to anyone else's vote so long as specification feedback comments are tied to the ballot submission.  Note that users can “un-vote” Specification Feedback items while a vote is still open.  This may change the overall vote (to ‘Affirmative’ if only affirmative comments remain or to ‘Abstain’ if no comments remain).

Each ballot submission has a status element.  The status indicates what actions the user can take.  The statuses mirror the states on the Ballot Submission.  Typically, all Ballot Submissions for a ballot will share the same status.  However, in very rare cases, certain users may be offered an extension to their ballot period, resulting in a different status.  E.g. A natural disaster, technical issues with voter registration, etc.

Ballot Votes

A Ballot Vote is a "sub-item" associated with a Ballot Submission that ties the submission to a single Specification Feedback item associated with that ballot.  When establishing the linkage, the balloter identifies the vote as being either Affirmative or Negative.  The feedback items associated to the Ballot Submission through Ballot Votes indicate the feedback that will need to be considered as part of the ballot reconciliation process.  For a Ballot Submission to have an overall vote of Negative, it must have at least one non-withdrawn and non-retracted negative vote.

Specification Feedback

The Specification feedback process is not specific to balloting.  It represents a general-purpose mechanism for all interested parties to provide feedback about HL7 specifications throughout the life of the specification.  The general capabilities of the Specification Feedback process can be found here.  This page focuses on how Specification Feedback items relate to voting.

In HL7 ballots, affirmative votes can be and negative votes must be supported by specific feedback from the voter.  The Specification Feedback Jira projects each HL7 product family are the mechanism by which this feedback is provided.  Voters can link submitted feedback items to their ballot submissions to provide support for their overall vote.  This process also "elevates" the priority of the linked feedback item by requiring the work group responsible for that portion of the specification to address the comment as part of the ballot reconciliation process.

Voting on a Specification Feedback Item

When a specification feedback item is eligible for vote, appropriate Vote Affirmative and Vote Negative transitions will become available for that feedback item.  The eligibility criteria are as follows:

• The current user must be signed up for a ballot.  (I.e. A Ballot Submission record must exist with the current user listed as the 'creator')
• The Ballot Definition associated with that ballot submission must have a status of In Progress
• The current time (based on the Eastern timezone) must be between the scheduled open and close dates for that Ballot Definition
• The specification feedback item needs to be associated with the same specification as the ballot definition
• If the ballot definition is limited in scope to specific artifacts or pages, the feedback item must list at least one of those artifacts or pages as part of the focus of the feedback
• The specification feedback item can't already have been resolved.  I.e. It needs to still be in the Submitted, Triaged or Waiting for Input states.  (The presence of a preliminary disposition on an item that has not yet been transitioned doesn't prevent voting.)
• The user can't already have submitted a ballot comment against the item (for any ballot).  I.e. A given specification feedback item can only be associated with a single ballot per user
• In order to vote Negative, the type of feedback must be Change Proposal.  (Technical Corrections, Questions and Comments can only be associated with Affirmative votes.)

Notes:

• Voters are free to vote on comments that have been submitted by other users - including specification feedback items created by individuals outside their affiliate or organization
• "creating a feedback item" and "voting on a feedback item" are two separate steps.  If a feedback item is created but no corresponding Ballot Vote is created, the feedback item will not be considered to be part of the balloter's ballot submission.
• The Ballot Vote isn't actually created until the user has confirmed the vote submission on the confirmation screen
• When a vote is submitted, it may result in changes to the user's Ballot Submission and may also adjust the vote totals shown on the Ballot Definition.

Un-voting a specification feedback item

In some cases, a voter might change their mind about including a particular specification feedback item as part of their ballot - or they might decide they want to change the vote strength associated with the item from Affirmative to Negative or vice versa.  Once a user has voted on a specification feedback item, they will have the option of Un-voting on that item until the associated ballot closes.  Once the ballot has closed, the Ballot Vote is considered a final part of the user's Ballot Submission and cannot be removed.  (It can however be Retracted or Withdrawn - see below.)

Reconciliation

Once a specification feedback item has been voted on, that comment becomes a portion of the feedback the work group is expected to review and decide on a resolution for. 

Reconciliation, Withdrawal and Re-circulation

After all comments have agreed upon resolutions, and are implemented in the specification, the committee posts a completed ballot reconciliation file to the Ballot Desktop. The instructions for creating the excel are posted on the Reconciliation spreadsheets page.