Skip to main content

Publishing your Own Consultation Templates

Overview

Consultation templates are effectively custom forms that appear on the left hand side of a consultation. You can define the layout, elements (like checkboxes, text inputs, and banners), and associated conditions (e.g. insert a code into the record).

Sometimes, practices want to create and publish their own consultation templates either for themselves or for other practices too.

To create a Consultation Template go to the Consultation module and select Templates > Create template. 

Screenshot 2025-08-12 at 14.48.41.png

Getting started

Medicus supports practices in doing this and you just need to know a couple of things to get started:

1 ) Our consultation template feature uses a simple XML schema to define the content which is then dynamically rendered in the Medicus user interface (so you'll need to be able to understand simple XML like this:

<checkbox name="50e51f076881431f9e5b8cc7d552a9d3" value="I have given advice about quitting smoking today"> 
  <ifChecked> 
    <careRecordNote heading="Concept ID" code="Concept ID" note="Your free text note" /> 
  </ifChecked> 
</checkbox>

2 ) It is much easier to write templates if you have a text editor that has the XML schema (XSD) configured because this will suggest the different elements of a template for you as you type

Setting up the Consultation Template Schema in VS Code

Using an XSD in Visual Studio Code (VS Code) to validate XML files and enable autocomplete is relatively straightforward.

Follow these steps to set it up:

1. Install VS Code

2. Install the XML Extension in VS Code

  • Open VS Code.
  • Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X on Mac)
  • Search for and install the XML extension (e.g., "XML" by Red Hat)

3. Add the Consultation Template XML Schema

  • Create a new XML file in VS Code called ConsultationTemplate.xsd
  • Add the XML content from this support article
  • Save it somewhere on your computer

4. Reference the XSD in Your Consultation Template

  • Create a new XML file which you will write your first template in
  • Paste this starting point of a consultation template into your file
<?xml version="1.0" encoding="utf-8"?>
<consultationTemplate version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="path/to/your-schema.xsd">

<presentingReasonCodes>
    <code></code>
</presentingReasonCodes>

<form title="">
    
</form>

</consultationTemplate>
  • Go to your ConsultationTemplate.xsd file, right click on the tab and click “Copy relative path”
  • Replace path/to/your-schema.xsd with the relative path to your XSD file. For example: /Users/timgray/ConsultationTemplate.xsd
  • If you have setup the schema correctly then you should start to get autocomplete suggestions like this:
  • Errors or warnings will appear in the Problems tab (Ctrl+Shift+M or Cmd+Shift+M on Mac) if the XML doesn't comply with the XSD
  • Hover over the highlighted issues to see detailed error messages

You are now setup to start making templates.

Starting Your XML File

Make sure you have followed the steps to setup VS Code for using our XML schema first, it will make writing templates easier.

Every XML file should begin with this line:

<?xml version="1.0" encoding="utf-8"?>

Then, add the root element <consultationTemplate> to begin the structure of your template. It should include the version number (which is currently 1.0):

<consultationTemplate version="1.0"> 
  <!-- Content goes here --> 
</consultationTemplate>

Note: If you are using schema validation (explained above then the XML will look like this instead:

<consultationTemplate version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="/Users/timgray/consultationTemplate.xsd">
  <!-- Content goes here --> 
</consultationTemplate>
 

Adding a Form

Inside the <consultationTemplate>, you need a <form> element. The form must have a title:

<form title="Example Form Title"> 
  <!-- Form elements go here --> 
</form>

Adding Layout Elements

You can use layout elements like sections, fieldsets to organize your form. For example:

<form title="Patient Form"> 
  <section>
    <fieldset title="">
      <!-- Add form elements like textInput, date, etc. -->
    </fieldset>
  </section> 
</form>

Sections are only needed for more complex templates. It is best to ignore them when getting started.

Fieldsets apply a header and a borderline around the group of form elements.

Adding Form Elements

You can include different types of inputs or information, such as:

  • Text Input
<textInput name="patientName" label="Patient Name" />

  • Select Dropdown
<select name="gender" label="Gender"> 
  <selectOption label="Male" value="M" /> 
  <selectOption label="Female" value="F" /> 
</select>
 
[within a <form>, type < to see what available elements there are]:

More specialist elements:

  • Blood pressure

Blood pressures are specialist elements. The example below can be copied and pasted for ease but shows the exact structure of a blood pressure element:

<bloodPressure name="v09af945dfc4049929375e2facae43172" label="Blood pressure">
  <ifValueSet>
    <careRecordObservation heading="715851000000102" code="75367002" unitOfMeasure="259018001"/>
  </ifValueSet>
</bloodPressure>
  • Quantity

Quantity allows you to insert a range of different observations. The example below can be copied and pasted for ease but shows the exact structure of an observation such as BMI:

<quantity name="v0cb19274a1704d1aaac9850d2fd95dec" label="BMI" unit="kg/sq. m">
  <ifValueSet>
    <careRecordObservation heading="715851000000102" code="60621009" unitOfMeasure="258896009"/>
  </ifValueSet>
</quantity>

Adding Conditions

Some elements can have conditions based on user actions:

  • Example: Insert a coded if a checkbox is selected
<checkbox name="allergyCheck" value="I have given advice about quitting smoking today"> 
  <ifChecked> 
    <careRecordNote heading="Concept ID" code="Concept ID" note="Your free text note" /> 
  </ifChecked> 
</checkbox>

Attributes Names & Values

Most elements require a name which is the unique reference to the element within the template.

The name:

  1. Can’t start with a number
  2. Must be unique

The best way to generate them is to use Online GUID Generator Tool and then type a letter before you paste in the UUID.

For example: v0cb7c209ae02426693db980306cbc919 . This just means that you will always have a unique name. The XML will fail validation if the name isn’t unique or in the right format.

Some elements also require a value (e.g. radio options). This is how the particular form control is referenced (e.g. how Medicus knows that you selected “Yes” and not “No”.

The easiest thing is to adhere to the same principles as name.

Example Template

Here’s an example to see what it looks like as you start to build out a template:

<?xml version="1.0" encoding="utf-8"?>
<consultationTemplate version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="/Users/timgray/consultationTemplate.xsd">

<presentingReasonCodes>
    <code></code>
</presentingReasonCodes>

<form title="Title">

<fieldset title="Fieldset">

    <checkbox name="v0cb7c209-ae02-4266-93db-980306cbc919" text="Test checkbox" value="v2tw7c209-ae02-2953-93db-980306cbc871">
        <ifChecked>
            <careRecordNote heading="" code="" note=""/>
        </ifChecked>
    </checkbox>

    <textInput name="v8e802dee-0930-48de-aab2-a73b710505b8" label="Test input">
        <ifTextSet>
            <careRecordNote heading="" code="" note=""/>
        </ifTextSet>
    </textInput>

    <textarea name="v22b07d29-d30e-459b-a650-2e202fc7424b">
        <ifTextSet>
            <careRecordNote heading="" code="" note=""/>
        </ifTextSet>
    </textarea>

    <date name="v5a835843-8200-4840-b73a-0908fcc11e9a" label="Test date picker">
        <ifValueSet>
            <careRecordObservation heading="" code="" unitOfMeasure=""/>
        </ifValueSet>
    </date>

    <bloodPressure name="v252268ea-ff0c-4e9e-9287-4a3aaaff0148">
        <ifValueSet>
            <careRecordObservation heading="" code="" unitOfMeasure=""/>
        </ifValueSet>
    </bloodPressure>

    <select name="vad1919e7-6f5c-417a-ad53-7bed7498b359" label="Test select">
        <selectOption label="" value="va83cddf4-89ab-4c9b-b0d3-e2dd763be335">
            <ifSelected>
                <careRecordNote heading="" code="" note=""/>
            </ifSelected>
        </selectOption>
    </select>

    <quantity name="vbf2d7b87-854b-4723-922d-2aa51c09a0c8" label="Test observation">
        <ifValueSet>
            <careRecordObservation heading="" code="" unitOfMeasure=""/>
        </ifValueSet>
    </quantity>

</fieldset>

</form>

</consultationTemplate>

 

Was this article helpful?