Getting Help
Naturally, your first stop should be the HAPI FHIR Documentation. We pride ourselves on our documentation and have put quite a lot of effort into it. There are "getting started" pages that include working starter projects for several of the major features in the library.
We ask that any questions about how to use HAPI FHIR be directed to the HAPI FHIR Google Group. This group is a great resource, with lots of helpful people who can assist. The HAPI FHIR developers are regular contributors to this group. The HL7/FHIR Zulip is also a great resource, especially if your question is more about FHIR itself (as opposed to being about HAPI FHIR).
Please do not email us at our personal email addressees (or send DMs, etc.) with questions about how to use HAPI! We are much more likely to respond if you post your question in the group, since there are a fixed number of hours in the day and we prefer to help in a place that benefits everyone. Also, please do not post a question on the GitHub Issue Tracker unless you are sure it is actually a bug. If you're not sure whether you have a question or a bug, please post your question on the Google Group.
When asking questions on the HAPI FHIR Google Group (or on Zulip), please include the following details:
- What is the real-word business problem you are trying to solve (e.g. what kind of software are you trying to build, who will be using it, etc.) It may not seem important to others, but it is always useful for people to understand the context in which you are using HAPI FHIR.
- What version of HAPI FHIR are you using, and is it the latest version available? Other details about your platform may be helpful too (OS, Web Server, etc.). If you have not tried using the latest version of HAPI FHIR, please try that first.
- What steps have you tried already? You are more likely to receive help if you demonstrate that you have made an effort to solve your problem on your own.
Please consider the following points of etiquette:
-
Be As Brief As Possible: Please make an effort to be concise. I can not stress this enough: If you post 10 pages of logs, your question will most likely be ignored. Please make an effort to pick out the relevant parts of the logs and include only those.
- If you are posting logs, please spend time trimming down the logs you provide so that you provide only things that are relevant. Stack traces are often particularly useful, as are any stack traces that happened before the one you are including.
- If you are posting a code snippet, please remove absolutely everything from the code snippet that isn't necessary in order to demonstrate your issue, and make sure that the snippet is complete enough that it can be run.
- If you are providing a resource body / message payload, etc., trim out every field that is not relevant to demonstrating your issue. The way we solve issues within HAPI FHIR is to build test cases, and payloads with lots of irrelevant details make lousy test cases.
- In the case of both logs and code, you should spend some time analyzing and figuring out what is relevant to the issue at hand and what is not. Remember, you are asking for someone who is probably a volunteer to give up their own time to help you. Please respect their time.
- If you find a solution to your problem (whether it is thanks to someone helping you or not) please post a follow-up indicating what the solution was, or even just mentioning that the proposed solution worked. Please remember that others are going to have the same problem, and are going to find your question in their search.
- Do not post screenshots of console/terminal windows, as these are never useful in diagnosing an issue. If you are having build troubles or something similar, please find the relevant parts of the build log and include them directly (but only the relevant parts. Nobody wants to read 10 pages of build logs!)
- If you are seeing an error when a client invokes your server, often it is more useful to check the server's log files and include them in your question.
Finally, please don't tell us that your question is super-urgent, or post the same question multiple times, or use all caps or bold font. HAPI FHIR is a free and open community project run by volunteers. If your problem is urgent, please consider buying a support package from Smile CDR.
If you have questions which are about FHIR itself (e.g. which resource should I use for a specific purpose, how to I model my data, etc.) there are two great resources that can help you:
- The chat.fhir.org server offers a live chat that is very popular with people using FHIR. That community extends far beyond just HAPI users, so there is a large pool of people who might have answers to your questions.
- You might want to also consider posting on Stackoverflow, as there are a number of FHIR experts who aren't HAPI/Java users who monitor that site.
We welcome bug reports, and do our best to address them quickly. Please do keep in mind though that HAPI FHIR is a volunteer-run project, so we can't always act immediately on every issue.
Before reporting a bug, please make sure what you have is actually a bug. If you are unsure how to do something with HAPI, you are more likely to get a helpful response on our Google Group (please see the Where can I ask questions or get help above).
When reporting a bug, please be as descriptive as possible. It is important to include details such as:
- What you are trying to accomplish
- What version of HAPI you are using (and if you are running a customized version, please mention that too)
- What platform you are using (Windows/OSX/Linux Platform, OS Version, etc)
- What version of Java you are using
Please also include any samples or other useful files that might help in diagnosing the issue. This could include resources you are using for testing, build/server logs, etc. If you are concerned about privacy you may also email James with these artifacts but please also file a bug and reference the ticket number.
Finally, if you are able to include a unit test, or even better a GitHub Pull Request we will be appreciative. Actually, one more thing:
If you discover that your bug was actually not a bug, please make sure to put an update in the ticket and close it.