Specification Feedback projects are the official mechanism for providing feedback about any HL7 specification.  Each product family has its own feedback project and any specification without a product family will used a single feedback project.  The ones currently defined are:

• CDA
• FHIR
• V2
• Other - for all specifications at HL7 that do not have a product management group - for example, CIMI, V3, Domain Analysis Models, EHR-s Functional Model and profiles, etc

These projects are used for submitting feedback related to HL7's Ballot Process as well as all suggestions/issues/concerns of implementers and other users of HL7 specifications.  The mechanism becomes available once a specification has progressed to ballot or when the associated work group asks for formal feedback to be enabled.

This page covers three main topics:

• Submitting new feedback
• Participating in the feedback process
• Searching and monitoring issues

This page is aimed at those involved in submitting feedback.  Additional documentation is available for co-chairs and others who manage issue resolution or who act as administrators for the feedback process.  For those familiar with the FHIR gForge submission tool which Jira replaces, there's also a page that discusses changes from gForge.

This page provides general guidance that applies to specification feedback regardless of which HL7 product family it belongs to.  Additional family-specific guidance is also available (read this page first):

• CDA Specification Feedback
• FHIR Specification Feedback
• V2 Specification Feedback
• Other Specification Feedback

Submitting new feedback

An essential part of the standards development process is receiving and managing feedback from the community.  Without feedback, HL7 can't know if its specifications are appropriate or useful to their target community.  We welcome feedback from anyone and everyone who is willing to be constructive.  Feedback might be suggesting a feature, pointing out a place where a specification is unclear or over-restrictive, identifying a spelling or grammar issue or suggesting that an entire area needs to be rethought.  HL7 makes a special effort to solicit feedback using our ballot process, however feedback can be submitted by at any time by anyone - even if they're not an HL7 member.  (That said, we strongly encourage membership, both to support the standards community and because it allows you to give your feedback greater weight.)

Before submitting

In order to submit feedback, you must register as a user on HL7’s Confluence and Jira systems.  Individuals are encouraged to submit feedback themselves.  Submitters will automatically be notified as a submitted is commented on or achieves milestones within the review process.  They may also be asked questions about and/or invited to calls to discuss their feedback.  Therefore, it’s best for feedback to be submitted directly by the individual directly impacted by or having direct knowledge of the issue being submitted.

Before submitting feedback, users are encouraged to browse through previously submitted feedback to see if the topic has already been discussed and, if so, what discussion has already taken place.  It may also be helpful to search the appropriate chat forum.  Duplicate requests will be closed without discussion unless they raise new points for consideration.

Remember that all issues and comments submitted in Feedback issues is subject to the HL7 Acceptable Use Policy.

Submission process

Feedback can be initiated by clicking on any of the links above, by clicking on the “Create” button from http://jira.hl7.org, or in some cases, by using a link within an HL7-published specification.

General guidance

When submitting an issue, you will be prompted with two fields that determine the "kind" of issue being reported - and which in turn determine what fields are available to describe the issue and what the validation rules are for submitting the issue.

Project

When initiating feedback, do your best to select the appropriate project.  The project can also be changed as the first drop-down item in the creation screen.  Which project is chosen will determine which specifications are available to choose from when reporting the feedback.  HL7's Jira has lots of projects - some for internal work group task tracking, others for reporting tooling issues, etc.  To see the list of specification feedback projects, just start typing "Feedback".

Issue Type

After verifying the project, the next decision is to pick the appropriate Issue Type.  There are four possibilities to choose from:

The Issue Type can be important when making submissions as part of an HL7 ballot.  Of the various types, only a “Change Request” can be tied to a negative vote.  All other types are restricted to “affirmative”, meaning that the feedback item cannot block publication of a specification.

It is possible for the Project and/or Issue Type to be changed after the issue has been submitted – either because it wasn’t categorized correctly or based on the decision of the work group.  For example, an issue submitted as a “Question” might be updated to a “Change Request” if the work group decides that the specification should be changed to provide further clarity

Specification Issue Tabs

The issue submission tab is split into a Default and Advanced tab.  The advanced tab is intended for HL7 insiders who are already familiar with work groups, categorization conventions and other practices used as part of issue management.  This tab can be ignored if you aren’t sure what to fill in – someone at HL7 will do so for you when relevant.

Each tab contains several fields.  Only those marked with an asterisk are mandatory, though there are conditional requirements that mean at least some of the location-related fields must also be filled in.  While there is not need to fill in all of the available fields, submitters are encouraged to fill in as many as they can.  The more complete the feedback item is, the easier the committee will be able to evaluate it.

Specification

The next drop-down is the specification.  A specification must always be identified.  Feedback not related to a specific HL7 specification (e.g. related to the HL7 website, to staff, to meetings, software products, etc.) must be made elsewhere.

The list of available specifications is driven by the choice of feedback Project.  Each project contains specifications only for that one project.  If you can’t find the specification desired, try looking under a different project.  If you still can’t find the specification, reach out on a list serve or chat forum or contact the webmaster.  If the Project field changes, the Specification element will automatically be wiped.

Raised in Version

Issues should generally only be raised against the current version of the specification (and this field will automatically default to that once the issue has been created).  Previous versions of a specification can only be updated in the event of obvious errors, and then only in ways that would not break implementations of that version.  Enhancements should always be proposed based on the most recent version of the specification made available.

Summary

This field must be filled with a short sentence describing the issue.  This is what everyone will see in the “search” view when looking at a list of issues, so try to ensure that the description is useful and precise.  However, it should also be relatively short (generally less than 100 characters or so).  Additional information can go in the Description element further down.

Location details

The next few fields vary by Project/product family.  Each family has its own approach to publication and therefore its own way of identifying what part(s) of the specification are relevant to the feedback.  Each specification will enforce that the location is identified in some manner (or that a positive assertion is made that no specific location is relevant).  Guidance on the location fields can be found in the product-specific feedback documentation:

• • CDA Specification Feedback
  • FHIR Specification Feedback
  • V2 Specification Feedback
  • Other Specification Feedback

During the maintenance process, the set of associated artifacts might be corrected, supplemented or otherwise adjusted during the triage process or as part of work group review.

Description

This field can be omitted if the issue is fully described by the summary.  However, in most cases, additional detail will be needed.  That detail goes here.  This might include a quote of the current text, proposed replacement text, rationale for a change, links to additional examples or any other information that might be relevant to the work group evaluating the change.

This field allows formatting, including lists and tables if that is helpful to better present the information.

Attachment

Supporting information such as screen-shots, example instances or other relevant information to support an issue can be attached here.

Request in-person

HL7 processes allow a submitter to request that they be present when a submitted issue is discussed (be that at a conference call or face-to-face at a working group meeting).  The specification feedback extends that capability to identify additional people who should be present as part of the discussion.  This element can be used to list one or more Jira users who the submitter feels should be involved in any decisions relating to the outcome of the issue.

Any individuals specified here will form the initial set of “in person” users.  However, users can add and remove themselves from the list if they wish and managers can add additional individuals.

Note that a request for “in-person” consultation is not a guarantee.  Work groups will make their best effort to include those who have requested in-person in discussions.  However, if after making reasonable efforts at accommodation, the responsible workgroup is free to make a decision even if not all of the identified users are able to be present.

Note that selecting “in person” imposes an administrative hardship on the work group and can slow down the resolution process.  As a result, this feature should not be used except for feedback items the submitter considers particularly important and where they feel their presence might help to inform or sway opinion.

The remaining fields are found on the “Advanced” tab.  They will typically be filled in as part of the triage and issue management process.  They should only be filled in on submission by users familiar with HL7 processes and who are confident in their ability to pick appropriate values.

Work Group

This indicates the work group (or occasionally other HL7 group) that is currently responsible for reconciliation of the issue.  It will be based on the selected specification, the relevant location(s) within the specification and/or the nature of the of the issue raised.

In some cases, responsibility for an issue may be transferred between work groups – either due to an incorrect initial assignment or because as the understanding of the issue evolves, an alternate view-point is deemed necessary, or the type of change needed is determined to be the responsibility of another group.

Priority

All issues start with a “medium” priority.  However, work groups can alter the priority to allow them to focus review on issues they deem of greater importance – for example, those tied to negative votes, those likely to require more discussion, those likely to result in substantive change, etc.

Priority should not be asserted by anyone not part of HL7 governance processes or representing the work group currently assigned to the issue.

Pre Applied

In some cases, issues may be raised by HL7 stakeholders who have commit rights to the underlying specification.  These users might choose to pre-apply a proposed fix in order to help the reviewing work group better understand the nature of the proposed change.  In some cases, a change might be applied after submission but before work group review for the same reason.

If a change is rejected or altered, the committed change will need to be reverted or adjusted accordingly.

Grouping

This field allows one or more categories to be assigned to an item.  These might include associating the item with a particular project, linking a bunch of related issues with a shared category, identifying issues that are ready for vote or other review, etc.  Categories can be defined at will and all category values currently in use will be selectable by type-ahead.

Note: These categories span all Projects/product families.  As a result, care should be taken to make them general purpose when possible.  Tags that are no longer relevant should be removed from issues if they are unlikely to be needed for searching.

Scheduling

This field works similarly to the Grouping tag.  However, the focus here is on scheduling the item.  It could contain the date of a particular call, or something more generic such as “next call”, “WGM discussion” or even a particular WGM quarter.  Again, values are shared.  Non-general-purpose tags should be removed when they are no longer relevant.

Changes to this element will result in notifications being sent to all Request in-person users.

Note that scheduling an item represents an intention, not a commitment.  Issues can often be taken up before or after they are scheduled, though best efforts will be made to ensure participation of “in person” requesting individuals.

Related Issues

Some issues may be related to pre-existing issues.  For example, a feedback item might be a request to re-open a previously resolved issue, might be proposing a similar change to another issue (but to a different area of the specification), might be proposing a change that follows on from another issue, etc.  This field allows links to be asserted to any other issues in the HL7 Jira site and provides for easy cross-referencing between the linked issues.

TODO: Verify that asserting a link results in a bi-directional link

Participating in the feedback process

Submission of a new feedback item initiates a process of review by HL7 members.  This section describes the cycle of that review and indicates how submitters can engage in the review process at different stages.

Feedback Issue state machine

All specification feedback issues are governed by a shared state machine:

All issues will start out as "Submitted" (Blue) and will eventually end in one of the bottom states (green).  The following table provides an explanation of each of the states:

Additional elements

Once an issue has been created, a few more fields become available that you may see when looking at an issue

Understanding management actions

Interacting with issues

Once an issue has been submitted, what you can do with that issue depends on what permissions you have as an HL7 Jira user. 

• Everyone - including those who aren't registered users - can read and search against issues. 
• Registered users have an additional set of capabilities, described below. 
• Other pages describe actions available for managers and administrators.

Workflow actions

Many of the actions that can be taken on an issue fall under the category of "workflow" issues.  These are actions that involve pushing a button and potentially filling in information on a separate screen.  Depending on the active user's permissions, the issue's status and other factors, the set of available actions will vary.  Jira will only display 3 actions "on-screen".  If more actions are possible, it will display a Workflow button () that you can click to see additional actions.  (So if something you want to do isn't on the screen, check to see if it's hiding under Workflow.)

Editing an issue

Regular submitters (those without manager or administration privileges) can edit issues they've created, but can only do this while the status remains Submitted.  Once the issue has changed to Triaged or any other status, it can no longer be edited (though you can add comments - see further down).  The fields available for editing are the summary, description, location fields, attachments and linked issues.  The project, issue type and specification cannot be changed.  If those are incorrect, the issue can be closed (see below) and a new one created.

Note: Editing is only allowed if there are no links to the issue.  If it's been voted on, is the target of a duplicate reference or any other type of Jira reference, it will no longer be editable.

Closing an issue

Submitters who have opened an issue are free to "close" the issue so long as it remains in an un-resolved state (status is Submitted, Triaged or Waiting-for-Input).  Doing so will automatically transition the issue to Resolved - No Change Required with a resolution indicating that it's been withdrawn by the submitter.  Note that this can only be done by the submitter of the issue, not by anyone else (even if nominally acting on the submitters behalf).  

Note: Like editing, closing is only allowed if there are no links to the issue.  If it's been voted on, is the target of a duplicate reference or any other type of Jira reference, it will no longer be possible for a regular submitter to close their own issue.

Requesting/Un-requesting "in-person"

Any registered HL7 Jira user can add or remove themselves from the "In-person" list associated with an open issue by pressing the "In Person" or "Not In Person" buttons (the former is only available if the user is not currently on the list, the latter is only available if they are).  Work groups will do their best to ensure that individuals noted as "in-person" are aware of when the issue will be discussed and will try to arrange times such that those individuals can be present.

Managing votes on an issue

Various vote-related options will be available if an issue is deemed related to a ballot that the user is signed up for that is open and/or if the user has submitted a vote on the item.  Possibilities include Vote, Un-vote, Retract and Withdraw.  More details about these options and the situations in which they are available can be found on the Jira Ballot Process page.

Other actions

These are general actions that are available for most types of Jira trackers and have specific controls on the issue to manage them.

Watching/Un-watching an issue

Users can add themselves as "watchers" of an issue.  Watching an issue means that if the issue is changed in some way (edited, comments added, transitioned to a different state, etc.), the watching user will receive an email notifying them of what happened.  The submitter of an issue is automatically added as a watcher.  

To add yourself or remove yourself as a watcher, click on the link beside the Watchers count or choose the option from the More menu.  You can see who's watching an issue by either clicking on the "count" of watches or selecting More, Watchers from the issue menu 

Commenting on an issue

All registered users can post comments against existing issues, regardless of who created the issue.  These comments might provide additional use-cases, indicate agreement or disagreement, suggest alternatives or provide any other commentary intended to be useful to the work group in making their decision about how best to resolve the issue.  Commenting is only allowed on "open" issues.  Once an issue is resolved, only managers and administrators can make further comments.  If you have feedback on an issue that's already resolved, that needs to be provided by reaching out on the appropriate chat forum or list server or by creating a new issue (ideally with a link to the one your feedback relates to).

To make a new comment, just press the  button

Looking at the history of an issue

If you're interested in seeing what's happened to an issue over time you can look at the History, Activity or Transitions tabs near the bottom of the issue.  They each show different views of what's happened.

History provides a complete chronological list of changes to fields in the issue.

Activity provides a recent list of changes, comments, links to and from the issue

Transitions provides a list of the state changes the issue has undergone

Additional issue fields

After submission, additional fields come into play.  Two of them (Watchers and Comments are discussed above).  The additional fields are:

Assignee

For 'open' issues, this indicates who the "Waiting for input" individual is.  (If the issue is open and there's an assignee, the status will always be "Waiting for input".  For closed issues, assignee should only be present if the status is "Resolved - Change Required" and in that case, it indicates who is expected to perform the change.  If you're wanting to know when an issue will be progressed, following up with the Assignee isn't a bad idea, but keep in mind that they're a volunteer.

Change Category

This is captured if a decision is made to change the specification.  It categorizes the change as being either a correction, clarification or enhancement.  These categories are used for reporting as we examine how different parts of a specification are evolving over time.

Change Impact

This field tracks whether a change to the specification is considered 'substantive' (which has impact on the HL7 Balloting process) and whether a change is a 'breaking' change, which is generally of interest to the implementer community, and which also has implications for whether a change is allowed or not, depending on the level of standardization of that portion of the specification.

Outstanding Negatives

This indicates whether there are any outstanding negative votes associated with the issue, and if so, what the highest 'level' of outstanding negatives is.  (Normative is higher than STU which is higher than informative which is higher than draft).  It's a calculated element based on associated ballot submissions and withdrawal status.

Reporter

This is the individual who originally created the issue.

Resolution

This categorizes the decision made by the work group about the feedback issue raised.  Every closed issue will have a resolution.  The possible resolutions are:

Resolution Description

This provides additional detail about the resolution.  This must be specified for all resolutions with the exception of "Persuasive", "Considered for future use" and "Considered - No action required", "Duplicate" and "Retracted"

Resolution Vote and Vote Date

This provides a formal record of the work group decision on the issue and is required to align with HL7 policies.  It will be present on all closed Change Requests provided that the resolution is not "Duplicate" and the item has not been withdrawn.

Applied For Version

This indicates the release the change is expected to be (or has been) applied to.  Generally this will be the forthcoming release, but in some cases, applying a change might be bumped to a future release and (on very rare occasions), a change might be applied to a previous release.

Searching and monitoring issues

There are many reasons for searching through the set of Specification Feedback issues.  For example:

• Checking to see if a proposed change has already been discussed
• Checking what proposals are currently being considered for a particular specification/artifact/area
• Checking what proposals have been approved but not yet applied
• Checking what proposals require review by a specified work group
• Checking the rationale behind a change that’s been applied to a specification (which requires finding the issue that trigged the change)

To search through issues, select Issues, Search for Issues (or Current Search) from the main Jira menu.  From the search screen, you can use one of the standard pre-defined searches, open a search you've previously saved to your favorites, search for an existing search created by someone else or define your own custom search.

Pre-defined searches

Jira provides a set of pre-defined searches that apply across all HL7 Jira projects.  This section will describe what they each do and will indicate which ones are likely to be useful/relevant when working with specification feedback items.  Several of these have limited usefulness, but unfortunately Jira does not yet provide a mechanism for hiding them.  Some of these might provide a useful starting point to further constrain by adding additional filters as described below in "defining your own custom search".

Note: The pre-defined searches marked with "*" have been overridden from default Jira behavior.

Defining/constraining your own search

While the standard searches are sometimes useful, most of the time you'll want to define your own search - either by starting from scratch or using a standard or saved search as a starting point.  This allows you to narrow down the listed issues to those relevant to a particular product family (filter by project), those tied to a particular specification, those submitted by a particular user, those dealing with a particular artifact, etc.

The search dialog provides a "Basic" view and an "Advanced" view, toggled by using the link towards the right on the search bar.  The "Basic" view allows filtering on the most commonly used fields and also allows the selection of other fields using the "More" drop-down.  The "Advanced" view allows the full power of Jira's query language (JQL) and allows grouping of conditions using brackets, inclusion of OR as well as AND and a number of additional advanced filtering capabilities.  Additional guidance on search can be found in the Jira help by clicking here or by clicking on the icon in the Advanced search window.

Some fields that may be useful to search on (e.g. Related Artifact(s), Related Page(s), etc.) may not be selectable unless your search explicitly filters on Issue Type.  That's because these fields are constrained to only be enabled for certain issue types.  If you filter and select all four issue types (Proposal, Technical Correct, Question and Comment), you'll avoid constraining out any issue types and will be able to filter by the restricted fields

Examples

In addition, there's a custom function we've created specifically to help search on ballots called `inBallot`.

The syntax is as follows: `issueFunction in inBallot("[ballot]", "[filters]")`

The 'ballot' needs to be the ballot code, either just the cycle or the full ballot code.  E.g. `2020-Sep - FHIR IG HRex R1 STU` or `2020-Sep - FHIR IG HRex R1 STU`.  (It's also possible to just search on `FHIR IG HRex R1 STU`, but that's not so useful.)

The filters is a comma-separated list consisting of either "AFFIRM" or "NEG and/or "OPEN".  The first will filter to only included either affirmative or negative votes.  The latter will filter to only include balloted issues that have not yet been resolved.  (Note - when someone has withdrawn a negative comment, it will no longer be treated as a negative.)

Examples

Favorite searches and other searches

Once you've defined a search, you can choose to save the search so it's available to you in the future.  Simply click the Save as button right beside the Search label at the top of the screen.  Once saved, you can also click on the Details link which allows giving your search a description, lets you share the search with others and allows you to create a subscription.

Administrators and Managers can also share saved searches, making them available with others.  It's possible to see what searches have been shared with you as well as searches you've saved yourself by clicking on the Find filters link right under the New Search button in the left-hand panel on the search screen.  If there's a search created by yourself or others that you find particularly useful, you can click on the icon to mark the item as a favorite.  Favorites will appear in your search panel at the bottom under "Favorite Filters".

With saved filters, you can also change what columns appear in the list view (including what order the columns are in) by clicking on the Columns button.  Be sure to choose "Filter", or the changes will instead be applied to all of your queries as a default (where you haven't overridden column behavior).  Also make sure you re-save your search if you've changed the column layout.

Exporting

Once you've run a query, you have the option of exporting the results.  With the button, you can save a summary view or full view of the issues in a wide variety of formats suitable for human review (MS Word, HTML) or programmatic manipulation (XML, JSON).

Subscriptions

Once a filter has been saved (by you or someone who's shared it with you), you can "subscribe" to it.  That means that you can have Jira run the query on a regular basis and email you the results.  Note that the filter will run the search each time, so if you only want to see "new" data, you'll need to filter based on updated or some other time-based field.  Also be aware that while Jira allows you to specify a specific time for the query to be run and the email to be sent, the actual execution can be slightly variable depending on how busy the server is.  That means that if you ask for the query to run daily and to only include issues changed in the last 24 hours, it's possible that you might miss an issue or two if the queries don't run exactly 24 hours apart (so you might want to give yourself a buffer of an extra hour or so, even if that means that your emails may occasionally contain redundant information.)

If you think there's a need for a group of people to receive the same email report, contact an administrator.  They have the ability to set up shared subscriptions when appropriate.

Bulk changes

The last thing you can do from the Search screen is to perform manipulations on the issues returned in response to a search.  There's a maximum limit of 1000 resources, so if your search returns more than that, you'll need to narrow the search (e.g. by time range) and do the modification in chunks.  To perform a bulk operation:

1. select Tools, and beneath Bulk Change click on either the complete count of issues or the current page worth of issues.
2. The next screen will let you select all of the issues or some subset of them (if you wanted to exclude some of the search set from the change).  Be sure to wait until the page has fully rendered before attempting to click on the "select all" check-box, as it won't work until all issues have been loaded onto the screen.  When done, click Next
3. This screen will allow you to choose what type of change you want to perform:
   1. Watch or Unwatch are simple options.  This is a quick way to watch (or stop watching) a large number of issues
   2. Transition allows you to make a variety of state transitions.  Essentially this means duplicating the behavior of hitting one of the "Workflow" buttons on a whole bunch of issues at once.  The set of available transitions will depend on what choices are possible for the set of issues included.  The ones most appropriate for bulk change for most users are: In Person, Not in Person, Vote Affirmative, Vote Negative, Unvote, Retract or Withdraw.  Managers will have additional options.
      
      1. If you choose one of the vote options, you'll be prompted to specify the ballot to attach the vote to
4. You'll then be prompted to confirm your change.
5. In some cases, business rules may prevent all changes from occurring (e.g. if you opted to vote on all of the issues for a particular ballot, but that ballot wasn't relevant for all issues.

Note that while you can cancel a block operation in progress, doing so doesn't rollback changes already made prior to the cancelation.

WARNING - DO NOT bulk change the specification for an issue unless you also  change the pages, artifacts and versions at the same time.  Changing the specification without also updating those other elements will create 'broken' issues and will lead to problems with balloting and other Jira processes.