Sometimes the system won't have the report you want.  At this point you can ask your support provider for help, but then you are dependent on someone else (for whom your report is unlikely to be a top priority).  If you are relatively happy with tech you might find it easier to write your own report.

You can start from any existing report (they are all listed here, or use the <trick> below) and from the context menu chose "Adapt for...". You should chose a report that is pretty similar to what you want (though it is not always as obvious as you might think).

<trick> go to the the report runner for the report you want to base your new
report on and hold down Ctrl + Shift as you click the Run Report button. </trick>

Let's have a look at a blank Report Template form:

Setup Tab

We will go through each of the fields (some of which are not visible in the screen shot).


This is one of the two fields that can be matched when people search for reports (the other is Collection Name) so it is critical that you chose carefully, or your masterpiece will never be found.  This also forms the default title when the rport is run, but users can override that at run time.

Long Desc

The contents of this field appear in on the report runner page so that people know what to expect when they run the report.  You can also use it for your own comments.

Collection Name

This is mostly self explanatory - it is the name of the collection that is being reported on.  If you select event then you get a new field appear:

Include Uninstantiated?

This should be checked if you need to include future bookings (or historic recurring bookings where a care worker has not checked-in or checked-out).  If this is checked then the report is actually run from a temporary collection generated at runtime.  Because this is an intensive process, it is done on a background server, which means the report cannot be run to the browser - hence the Enable Interactive field gets hidden.
If you are going to use this option then the report needs  parameters for the start and end of the period you are interested in - these are created automatically when you save the report template if they aren't there.

 Having the system generate the start and end date parameters for you is much easier than doing it yourself, so you should always do it.  Even if you are not using uninstantiated bookings in the report, but want a range of historic events, it is worth checking the Include Uninstantiated? box saving the template and then unchecking the box again.

If you do include uninstantiated events in the report you get another new field appear:

Exclude Cancelled

This is just a convenience to save you having to remember to select out the cancelled bookings.

Feed into Mail Merge

Check this box if the report output is an email to people selected within the report.  

In the simplest case you would select person as the Collection name and put fields from the person collection surrounded by $ symbols into the body of the email (such as $givenName$ or $familyName$). More complex reports link to the person collection from another collection such as events. In this way you can email customers a list of care workers who are visiting in the next week. There is an example here - beware - it is quite gnarly.

If the Feed into Mail Merge box is checked a couple of  fields are hidden and a couple become visible.  Those that become visible are:


This field allows the body of the email to be set up.

Prevent Edit Body

This box can be checked to ensure that the mail merge goes out with the default body text - it cannot be edited by the user at run time.

Enable Interactive

(Not valid for mail merges)  This field should be checked if there is value running the report in the browser (which enables filtering / sorting etc) it is hidden for reports where Include Uninstantiated? is checked since they cannot be run in the browser.  If the field is you also get the following fields:


A checkbox that allows you to specify whether the report results can be filtered in the browser.


Allows and array of Text entries on the report's context menu, each with a link to a specified URL.


(Not valid for mail merges) Allows a link to be specified for each report row.  Fields values from within the current row of the report can be substituted into the text by surrounding the field name with  character.  So if there is a person code in the _id field of the report (which is quite common) the drilldown to open their address tab would be person/|_id|/edit/Address

Hide From Children

A badly placed field, since it only makes sense when the report template belongs to a non leaf organisation, and the organisation is the next field in the tab order for technical reasons.  A typical use case here would be to have reports that are run about branches that belong to an organisation, but the report can only be run by the main office.


(This field may be hidden, depending on your setup).  Which organisation does the report template belong to?  It will be visible by all organisations further down the tree unless Hide From Children is checked.


There is only one field on this tab, and it is the instructions about how the report is constructed.  Specifically we use a MongoDB Aggregation Pipeline.  A simple example (taken from the page linked to earlier) would be:

db.orders.aggregate( [
   // Stage 1: Filter pizza order documents by pizza size
      $match: { size: "medium" }
   // Stage 2: Group remaining documents by pizza name and calculate total quantity
      $group: { _id: "$name", totalQuantity: { $sum: "$quantity" } }
] )

We cannot actually run that example, because the report runner constructs the bit outside the outer square brackets (the pipeline is everything else) and orders is not a Collection Name.  Another problem is that - because we want to be able to pass our aggregation pipeline around and put it in URLs, we need our pipeline to be JSON. As you can see by plugging the bit in square brackets from the example into a JSON Validator - it has problems.  Specifically JSON does not support comments (if you want to put comments in your report template, put them in the Long Desc field) and almost everything in JSON has to be enclosed in double quotes.  The pipeline for the query above (assuming we had access to the orders collection) would be:

    "$match": {
      "size": "medium"
    "$group": {
      "_id": "$name",
      "totalQuantity": {
        "$sum": "$quantity"

To save you copying and pasting code into the validator site, the pipeline field has got a built in validator and formatter (though the error messages are less helpful) - just do [Ctrl] + [Alt] + [R]


This tab lets you set up parameters for each column that you want to appear in the report output.  You don't need to create any column definitions - if you leave this tab blank every column returned by the aggregation pipeline will be displayed in its default format.


This tab lets you set up input fields so the end user can be prompted for and run time parameters