# Contribution in general and how to post them in EHRBase **Category:** [Platform](https://discourse.openehr.org/c/platform-implem/7) **Created:** 2021-01-20 15:57 UTC **Views:** 1548 **Replies:** 8 **URL:** https://discourse.openehr.org/t/contribution-in-general-and-how-to-post-them-in-ehrbase/1241 --- ## Post #1 by @surfer 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 [https://specifications.openehr.org/releases/ITS-REST/latest/ehr.html#contribution] . 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. --- ## Post #2 by @thomas.beale Here is a bit of explanatory background on Contributions: * [openEHR Architecture Overview - Versioning](https://specifications.openehr.org/releases/BASE/latest/architecture_overview.html#_versioning_2) * [EHR spec](https://specifications.openehr.org/releases/RM/latest/ehr.html#_change_control_in_the_ehr) Short summary of the concepts: * a Contribution is the same idea as a [change set](https://en.wikipedia.org/wiki/Changeset) 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. --- ## Post #3 by @surfer 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? --- ## Post #4 by @thomas.beale 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. --- ## Post #5 by @surfer 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. --- ## Post #6 by @birger.haarbrandt 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! --- ## Post #7 by @surfer 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? --- ## Post #8 by @jake.smolka 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|attachment](upload://iD9wFTGSX7JhfkNP8ror7CjTKwU.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|attachment](upload://g7xhhqejyzk7RtOrg53Z6rAo1GO.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! --- ## Post #9 by @surfer thank you. it should help a lot indeed --- **Canonical:** https://discourse.openehr.org/t/contribution-in-general-and-how-to-post-them-in-ehrbase/1241 **Original content:** https://discourse.openehr.org/t/contribution-in-general-and-how-to-post-them-in-ehrbase/1241