--- title: "Advanced Questionnaires Versioning" canonical: "https://wiki.patientsknowbest.com/space/DEPLOY/5326438457/Advanced%20Questionnaires%20Versioning" format: markdown --- > Macro (toc) # Introduction This page provides an overview of how Patients Know Best (PKB) utilises the FHIR (Fast Healthcare Interoperability Resources) data standard to manage and store information, with a specific focus on PKB's Advanced Questionnaire feature. New IDs are required whenever changes are made to an advanced questionnaire; read on to find out the process and how to manage these changes depending on whether they are sent via the User Interface or the API. # PKB Advanced Questionnaires FHIR is a standardised, universal filing system that PKB uses to organise and store health information. It provides a common language for medical records, ensuring details such as patient information, clinic names, health conditions, and test results are formatted and stored consistently. Regarding the specific questionnaire terms: - Questionnaire (Resource): Think of this as the digital template or the "blank form" itself. - QuestionnaireResponse (Resource): Think of this as the final, "filled-out form" that contains the patient's specific answers to those questions. 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[ ](https://wiki.patientsknowbest.com/space/api/4474372098/Advanced+questionnaires+API+specification)[$send-questionnaire-request API](https://wiki.patientsknowbest.com/space/api/4474372098/Advanced+questionnaires+API+specification). ## 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. Meaning two versions of the same questionnaire: - There will be two IDs - There will be two version numbers (e.g. version 1.0 and 2.0) - There will be one canonical URL (e.g.[ ](http://fhir.patientsknowbest.com/questionnaire/gad-7)[http://fhir.patientsknowbest.com/questionnaire/gad-7](http://fhir.patientsknowbest.com/questionnaire/gad-7) ) # Requirement for New IDs After Changes When a professional or patient views a completed questionnaire in the PKB user interface, both the Questionnaire and QuestionnaireResponse resources 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, PKB must create a new questionnaire with a new ID if changes are needed. Since the FHIR Questionnaire and QuestionnaireResponse are so related, it would not be compliant with the FHIR specification for two different versions of a Questionnaire resource to exist with the same ID. If you're sending the questionnaire via the UI, your Success PM can replace the old version with the new one within your team. This lets you keep sending questionnaires seamlessly, with no changes required on your end. You can still export responses collected from the previous version, but you can no longer send that version. # Sending Questionnaires Using the API When sending questionnaires via the API, use the ID for the new version of the questionnaire. You can get the new questionnaire ID by calling the Questionnaire endpoint. # How to Request Changes to  Questionnaires To update a questionnaire already live in production, follow these steps: 1. Inform your Success PM you need changes to the questionnaire and send an updated spec. Send a summary of the changes, or a document containing the new version of the questionnaire. 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 the team on Sandbox. 4. The team: Review the questionnaire on Sandbox by sending it to a test patient. The team can make further changes to the questionnaire at this stage. 5. The team:  Test end to end flow with the new version of the questionnaire on Sandbox. For example, send the questionnaire, answer it using the test patient, and view the patient’s answers 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 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.