Using Scenario Builder for developing Resources

I had an email this morning from the organizers of the ‘Clinicians On FHIR’ event at the upcoming Working Group Meeting asking if it was possible to use the Scenario Builder to examine a resource type that had been altered after publication (i.e. one that was being worked on for the next release of FHIR – R4). As it turns out, this is quite straightforward to do – albeit with some limitations.

The way to approach this is to treat the altered resource type (technically a StructureDefinition resource of course) as if it were a logical model. We’ve talked about logical models a bit, but briefly they are models (or types) that use the FHIR infrastructure (conformance resources, datatypes etc) but whose contents don’t match any of the core resource types. This is not the same as profiling a resource, as you don’t use extensions to add additional elements – you just create the element. This results in a ‘non-conformant’ type, which means that you can’t easily share it and you can’t save it on a validating FHIR server, but it’s perfect for ‘trying things out’.

To use a logical model in the Scenario Builder, you click the ‘Add resource’ button, and then select the ‘Logical Models’ tab to the right. This exposes a dropdown that lists all the logical models in the current conformance server, and you just select the one you want. Here’s an image:

Then you can use it in the scenario like any other resource, including linking to others.

There are a couple of ways of creating the logical model.

The first is to use the Logical Modeller component in clinFHIR and just build whatever you want. You can create one based on an existing core type and add/remove/alter elements as needed (often good for quick ‘what if’ scenarios), or just build one from scratch (often useful for capturing requirements). Once built and saved, it will show up in the Scenario Builder as described above. (One trap is that unlike the Scenario Builder, logical models need to be explicitly saved to the server)

The second way (and the one we’ll use here) is to take the StructureDefinition for a ‘candidate’ resource type being altered (in this case it was changes to the AdverseEvent resource), change that to be a Logical Model and save it as such on the conformance server. Then – voila! – you can build instances in the Scenario Builder (but not save them to the data server of course). You will need to be comfortable downloading files and manipulating them directly in an XML (or Json) editor to do this.

Lets take a look at the steps required.

First, grab the StructureDefinition for the resource. You can find this by going to the page above and just below the resource content structure are links to the StructureDefinitions in XML and Json formats (Alternative Definitions).

Grab the XML format and open in your favourite XML editor.

Next, you need to create a new ‘type’ element value, that is different to the current one. In this case the type value is ‘AdverseEvent’. I changed it to ‘CfAdverseEvent’ by doing a global replace (AdverseEvent -> CfAdverseEvent) in the file. Note that it must start with a capital letter.

Next, I set the id to one that would be unique on the conformance server (cfAdverseEvent worked for me).

Then I changed the value of the ‘kind’ element to ‘logical’

Finally, I inserted this identifier (as this is how the ScenarioBuilder will find the right files):

<identifier>
         <system value="http:clinfhir.com"/>
         <value value="author"/>
</identifier>

After making these changes I saved the resource on to the R3 HAPI server (I PUTted it to http://fhirtest.uhn.ca/baseDstu3/StructureDefinition/cfAdverseEvent). The server did complain quite a bit as it doesn’t support logical models yet, but it did save it. (Thank you James!).

And that was it! I started up the Scenario Builder and was able to load the Logical model and build a scenario with it.

So I hope that proves useful – just remember that you can’t save instances based on the logical model to the server (Actually you probably can – but it will drop any elements it doesn’t understand). And there are likely other changes to make it a fully compliant logical model, but this is enough to get started.