Contribution in general and how to post them in EHRBase

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.

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

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?

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

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.

Hi @surfer,

you will find some examples in our integration tests:

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

yeah. It sure helps. thanks
And the parameters and headers are the ones in , aren’t they?

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!

thank you. it should help a lot indeed