Contribution in general and how to post them in EHRBase

Implementation Platform
1

Hi,
I’d like to learn how/when to use the contributions. Due to my ignorance my questions are very basic and maybe naive.
1)The first thing is that I don’t have any example of contribution, to learn from, other than the one in the API openEHR specification [EHR API] .
Do you have a meaningful example of a contribution?
2)Then I was wondering what’s the difference between posting a composition and posting a contribution with the same composition inside or as well if I should use the REST put to update a composition or should I update it through a contribution. What’s the recommended approach?
3)How do you post a contribution to EHRBase? I tried with the contribution I mentioned before with no success.

2

Here is a bit of explanatory background on Contributions:

Short summary of the concepts:

  • a Contribution is the same idea as a change set in versioning theory - a collection of all changes to be committed at one time to some repository or file system.
  • whenever anything is committed to the openEHR EHR, a Contribution is created, whether you are explicitly aware of it or not.
  • ideally, a repository should advance from one valid state to the next in contribution steps - i.e. no commit should create an invalid state.

An API that supports Contributions should enable you to commit multiple changes in one set, i.e.

  • updated Compositions - e.g. Medications list, Problem List.
  • new Encounter Composition
  • even logical deletes (rare in openEHR)

hope this helps.

1 Like
3

thank you Mr Beale,
I just read them and returning to point 2) in the original post if i understood it correctly there’s no difference in the two approaches. I mean if I have only a composition to create I can do it through the composition API or through the contribution API with AUDIT_DETAILS.change_type set to create. There’s not a preferred approach.
But what happens if I post a contribution where multiple action occur and one fails? Being change-set means that everything in the contribution is rejected or the action that fails is removed and the rest form an accepted contribution?

4

If you just want to commit a single Composition, which is a common thing to need to do in many situations, then the Composition API will be easier. It will cause a Contribution to be created for you.

If you try to commit a Contribution, and it contains one item that doesn’t validate against its template, the Contribution will fail. But the same can happen with just a single Composition.

It might be useful for us to think about an additional API that can validate structures before trying to do a commit.

1 Like
5

and for point 1) and 3) that is I would need an example of a contribution accepted by EHRBase, @birger.haarbrandt can you help me? As I tried the example composition from the openEHR specification and tried to overcome the errors that comes out with no success.

6

Hi @surfer,

you will find some examples in our integration tests: https://github.com/ehrbase/ehrbase/tree/develop/tests/robot/_resources/test_data_sets/contributions/valid

If I remember correctly there were still some variations between the serializations. This should hopefully be resolved and completely standardized. Hope this helps!

7

yeah. It sure helps. thanks
And the parameters and headers are the ones in https://specifications.openehr.org/releases/ITS-REST/latest/ehr.html#contribution , aren’t they?

8

Hey @surfer!

Here’s a working example from our integration tests to get you started, if it didn’t work out yet.

Precondition: Create an EHR and remember the EHR_ID.

To get EHRbase prepared for this example contribution and the compositions it contains you first need to upload the required template. Create a POST request to http://localhost:8080/ehrbase/rest/openehr/v1/definition/template/adl1.4 and set the headers

  • Content-Type = application/xml because the body payload will be XML.
  • prefer = return=representation if you want the uploaded template directly returned to you.

Add the following body payload to the request:
obs_eva.en.v1.xml (17.2 KB)

Execute the request. The response should have a 201 Created status and the template as body.

(Note: This step obviously depends on the content of the contribution. For instance, if a contribution modifies an EHR_STATUS objects no specific template is required. If it adds or modifies a different kind of composition the matching template is required, instead of the one I provided.)

For the contribution itself:

Create a POST request pointing at the endpoint URI http://localhost:8080/ehrbase/rest/openehr/v1/ehr/{{ehrId}}/contribution.

The following headers are important

  • Content-Type = application/json because the body payload is json.
  • prefer = return=representation if you want the created objects directly returned to you.

Add the following body payload to the request:
request-body-payload.json (15.5 KB)

This example contains two compositions, which should now be successfully created, after executing the request. The response should have a 201 Created status and an overview of the objects in the body.

Hope this helps you getting started!

1 Like
9

thank you. it should help a lot indeed