/
Advanced Questionnaires Versioning

Patients Know Best Resource Hub | Deploy | Developer | Trust Centre | Manual | Research | Education | Release Notes

Advanced Questionnaires Versioning

Overview

FHIR is a data standard that PKB uses to store data in its database. FHIR resources represent concepts like patients, organisations, questionnaires, conditions, test results and measurements.

PKB’s advanced questionnaires are created in FHIR as Questionnaire resources. When patients answer the questionnaires, their answers are saved as FHIR QuestionnaireResponse resources.

Questionnaire resources exist in PKB’s FHIR store and have the following important fields:

  • ID:

    • this is the server-assigned, unique ID of the Questionnaire resource. It is unique to that specific version of the questionnaire. It cannot be changed and is assigned by the server when it is saved. You use this ID to send questionnaires using the $send-questionnaire-request API.

  • url:

    • this is a ‘canonical URL’ representing the questionnaire. It is not version specific and refers to the questionnaire template that is being used in real life. For example, if your organisation had used two versions of a GAD-7 questionnaire, the two versions would have the same canonical url, since they are both a GAD-7 questionnaire, but different IDs, since they are different FHIR Questionnaire resources.

  • version:

    • this is the ‘version number’ of the questionnaire. Sometimes, changes need to be made to questionnaires. For example, if the clinical team realise that more or different information is needed from patients. When changes are made to a questionnaire, a new Questionnaire resource is created. The new Questionnaire resource has the same url, a different version number and a different ID.

 

So, for two versions of the same questionnaire:

Why can’t I keep using the same ID after making changes?

When a professional or patient views a completed questionnaire in the PKB user interface, both the Questionnaire and QuestionnaireResponse resource are used by PKB to display the questions and answers. This means, if we make changes to a questionnaire without creating a new Questionnaire resource with a new ID, these changes will be applied to all completed responses based on this Questionnaire resource. For this reason, we have to create a new questionnaire with a new ID if there are any changes needed.

Since the FHIR Questionnaire and QuestionnaireResponse are related resources, it would not be compliant with the FHIR specification for two different versions of a Questionnaire resource to exist with the same ID.

What if I’m sending my questionnaires using the UI?

If you are sending questionnaires using the UI, your Success PM can replace the old version of the questionnaire with the new version of the questionnaire in your team. This will allow you to continue sending the questionnaire as normal - you will not have to change anything. You can still export responses that were created from the old version, but you will not be able to send it out anymore.

What if I’m sending my questionnaires using the API?

If you are sending questionnaires using the API, you will need to start using the ID that belongs to the new version of the questionnaire. You can get the ID for the new questionnaire by calling the Questionnaire endpoint.

How do I request that changes are made to my questionnaire?

To update a questionnaire that is already live in production, follow these steps:

  1. Inform your Success PM that you need changes made to the questionnaire and send them an update spec for the questionnaire. This could be a summary of the changes you need or it could be a document with the new version of the questionnaire on it.

  2. The Success PM will build the new version of the questionnaire

  3. The Success PM will add the new version of the questionnaire to your team on Sandbox.

  4. You should test the questionnaire on sandbox by sending it to a test patient. During this stage, further changes can be made to the questionnaire without issues, since the questionnaire has not been sent to any real patients.

  5. You should test your team’s end to end flow with the new version of the questionnaire on sandbox. For example, sending the questionnaire, answering the questionnaire using the test patient, and viewing the patient’s answers in the way your team usually would. This ensures that no issues will be introduced with the new questionnaire.

  6. Tell your Success PM that you would like to update the questionnaire on production with the new version.

  7. The Success PM will add the new version of the questionnaire to your team and remove the old one. You will now no longer be able to send the old version of the questionnaire, but will instead send the new version of the questionnaire. If you are an API user, you should call the Questionnaire endpoint to get the ID for the new version of the Questionnaire.