Stream: ihe
Topic: MHD update and status
Simone Heckmann (Dec 08 2021 at 15:41):
If I understand it correctly, MHD currently only allows for POST-Interactions on DocumentReference and Binaries. Deletion and Update are our of scope, right?
So an new Document can be provided with a "replaces"-Relation to an existing one, but the status of the existing document could never be changed to "superseded"? Nor could a DocRef be changed to the "entered-in-error"-state.
Wouldn't this imply that all DocumentReference in the MHD scope must be, and always will be "current"?
Oliver Egger (Dec 08 2021 at 16:01):
if you have MHD with the XDS on FHIR Option you can have afterwards a DocumentReference in superseded state as per https://profiles.ihe.net/ITI/TF/Volume3/ch-4.2.html#4.2.2.2.3. I don't see this behaviour specified in MHD directly.
John Moehrke (Dec 08 2021 at 16:09):
MHD does support replacing documents, just like XDS did. That is to say these are NOT an "Update" action. They are a "Create" of a new DocumentReference for the new instance of a Binary document; with a .relatesTo that deprecated the previous DocumentReference/Binary.
https://profiles.ihe.net/ITI/MHD/ITI-65.html#23654123-replace-transform-signs-and-append-associations
Oliver Egger (Dec 08 2021 at 16:46):
@John Moehrke where is this behaviour stated in https://profiles.ihe.net/ITI/MHD/ITI-65.html#23654123-replace-transform-signs-and-append-associations? Also from the semantics of the Bundle transaction I would have assumed the same behaviour as @Simone Heckmann described it, a new DocumentReference would be added with a relatesTo link to the other DocumentReference.
John Moehrke (Dec 08 2021 at 16:47):
that is what that section (intends) to say
John Moehrke (Dec 08 2021 at 16:50):
In early versions of MHD we didn't cover this well, because replace was not a high priority use-case. But the current should be covering it. Welcome improvement recommendations.
John Moehrke (Dec 08 2021 at 16:52):
MHD is just the interface, so it is just there to convey the intent. There is further explaination of replace in XDS, and also in MHDS
John Moehrke (Dec 08 2021 at 16:53):
MHDS work in progress to move to html -- https://github.com/IHE/ITI.MHDS/blob/master/index.md
Oliver Egger (Dec 08 2021 at 19:38):
But if MHD is just the interface and it uses a transaction Bundle then I think it should include the to be updated relateTo DocumentReference or alternatively an operation should be defined. I offer to write a CP.
John Moehrke (Dec 08 2021 at 19:39):
as indicated, I thought the section I pointed to did say that. It just didn't have an example. right?
Oliver Egger (Dec 08 2021 at 19:48):
The Document Recipient shall process the bundle atomically, analogous to both the Provide and Register Document Set-b [ITI-41] transaction and FHIR “transaction” as specified in http://hl7.org/fhir/R4/http.html#transaction.
You cannot expect to be compliant to [ITI-41] and to the FHIR "transaction" for the replaceTo behaviour. Either the replaceTo behaviour is excluded, the transaction needs to add the updated DocumentReference or an operation is defined.
John Moehrke (Dec 08 2021 at 19:52):
I don't understand why you say that
John Moehrke (Dec 08 2021 at 19:52):
are you meaning in the context of MHDS that there is a problem? There is not really a problem in the case of XDS, as that is already the behaviour of the XDS Provide and Register Document Set
Oliver Egger (Dec 08 2021 at 19:58):
in the context of MHD without the XDS on FHIR option selected
John Moehrke (Dec 08 2021 at 20:13):
okay, so in MHDS
John Moehrke (Dec 08 2021 at 20:15):
I have had comments to public-comment about moving ITI-65 as an operation. It feels very much like it is an operation more than a transaction. It is what it is because of history, and lack of comments to the contrary. I am happy to have Trial-Implementation improve it.
John Moehrke (Dec 08 2021 at 20:21):
@Oliver Egger you can just put in github issues. You don't need to write formal CP.
Oliver Egger (Dec 13 2021 at 15:37):
added issue 100 with a proposition for clarification of the text.
Simone Heckmann (Dec 14 2021 at 11:42):
I can't really wrap my head around how a Document's status could be changed to "entered in error" using ITI-65. Can it even?
John Moehrke (Dec 14 2021 at 13:02):
not really, there is no functionality called for in the use-cases to do that. Even the case where we have had a need for a Delete, we did that with a replace with an empty document. We don't have a use for the status entered in error.
John Moehrke (Dec 14 2021 at 13:02):
that is not to say that it couldn't ever be set, just no use-case means for setting it using ITI-65.
Simone Heckmann (Dec 17 2021 at 08:58):
After giving this some additional thought, I absolutely agree with the idea, that MHD should move to operations instead of transactions. I often tell my customers that the difference between the two is the location of the business logic. With transactions it's on the client side (client decides whether to PUT or POST, what's the appropriate matching criteria for conditional create/update etc). Operations however have all of that happening on the server side, and the client simply provides the necessary input.
With MHD it feels like it should be the latter rather than the former.
I am currently working on a national spec for Germany where we want to describe simplified intra-organisational document exchange but align with MHD as much as possible to enable communications with the XDS based PHR withount much of an additional effort.
I'd be very much interested in preadopting the operations approach. Maybe we can start the discussion right here...?
John Moehrke (Dec 17 2021 at 12:50):
is there a downside to changing to an operation? (it is not an operation purely because this is an old enough spec that there was no operation support when MHD was first written).
John Moehrke (Dec 17 2021 at 12:52):
IHE process would run this change to an operation as a "Change Proposal". This would at-best be balloted in January, and thus be at-best final in February.
The CP needs to explain why, and exact textual changes. (The github issue with a pull-request would be fantastic)
Oliver Egger (Dec 17 2021 at 18:48):
I would suggest to introduce the operation only as an addition for covering the replace document if the client cannot handle himself the replace logic. Why introduce an operation for all Usecases when those are semantically very nice handled with the transaction? Not every client needs to replace documents and would be perfectly fine to just use the transaction bundle as defined now. Not to forget that MHD has been tested during multiple connectathons with the transactions semantics and the NIST tooling built for it. Defining operations sounds for me like rewriting WSDL's ...
John Moehrke (Dec 17 2021 at 18:50):
that would keep from breaking things... but it also replicates alot of functionality, as all the functionality the current transaction is needed in the operation. as it is very possible to submit a replacement with a signature, ammendment, folder change, etc...
John Moehrke (Dec 17 2021 at 18:59):
other, relatively non-breaking, is to just require Document Source to include the old DocumentReference with the changes. Not that much of a bigger burden, just not something an XDS Document Source needs to do.
John Moehrke (Dec 17 2021 at 19:00):
so, we have three alternatives for discussion
Oliver Egger (Dec 17 2021 at 19:01):
i would prefer additions then alternatives :smiley:
John Moehrke (Dec 17 2021 at 19:03):
I meant alternatives for how we solve the problem. not options to be written into the profile.
Luke Duncan (Dec 17 2021 at 19:08):
John Moehrke said:
is there a downside to changing to an operation? (it is not an operation purely because this is an old enough spec that there was no operation support when MHD was first written).
One downside is that currently, you can support MHD in a standard FHIR server, so if it's an operation, that would need to be written for any default FHIR server that wants to support it. I'm not saying this is necessarily a good enough reason, but it would affect implementations.
John Moehrke (Dec 17 2021 at 20:05):
right, but replacing a document is a normal lifecycle action, so that FHIR server would certainly need to support the replace functionality.
This point about a normal FHIR server, would tend to require pushing the responsibility to the Document Source. But even this alternative would require the FHIR server to not allow a replace without the old DocumentReference.
Simone Heckmann (Jan 17 2022 at 15:49):
Luke Duncan said:
John Moehrke said:
is there a downside to changing to an operation? (it is not an operation purely because this is an old enough spec that there was no operation support when MHD was first written).
One downside is that currently, you can support MHD in a standard FHIR server, so if it's an operation, that would need to be written for any default FHIR server that wants to support it. I'm not saying this is necessarily a good enough reason, but it would affect implementations.
But would a default server's behaviour be correct according to the spec? If a Client sends an updated Document via transaction to an out-of-the-box FHIR Server, there would be duplicate documents with the same master identifier and both status "current". That can't be right...
John Moehrke (Jan 17 2022 at 15:52):
well, master identifier is expected to change on version changes too... see this in CDA and FHIR-Document.
Simone Heckmann (Jan 17 2022 at 15:56):
Guess I meant identifier, then...?
John Moehrke (Jan 17 2022 at 15:57):
so, yes there could be problems.. agreed.
John Moehrke (Jan 17 2022 at 16:14):
Note there is a "new work item" proposed to be picked up in February... if there is enough interest...
John Moehrke (Jan 17 2022 at 16:14):
https://github.com/IHE/IT-Infrastructure/issues/175#issuecomment-1002122712
Simone Heckmann (Jan 17 2022 at 16:19):
I think the current specification contradicts the description of a transaction. We expect our POSTs to have consequence beyond the creation of the new resource (update status of old version) which is not what transactions do.
I see three options here:
- Keep the transaction as it is and accept that MHD in this form does not support updates
- Keep the transaction but in case of an Update, the Transaction must include a PATCH or PUT on the old DocumentReference to set the status to 'superseded'
- Drop the transaction and introduce an Operation and leave it to the server to deprecate the old version if a new one is added.
What I am uncertain about is if the prospective Operation should differ between Create and Update. Is it up to the Server to figure out if a Document with the same identifier already exists or not and behave accordingly or is it up to the client? Does a client always know or care if an older version of the document already exists on the server?
Simone Heckmann (Jan 21 2022 at 14:58):
Regardless of whether Transaction or Operation, I think I would like to have a little more information on the expected server side behaviour in case of an update, specifically potential error scenarios:
- What triggers the specific update logic on the server?
- Is it the fact, that a document is submitted with an identifier that already exists on the server?
- Is it the existence of the relatesTo-element? (and what if the relatesTo.code is anything other than "replaces")?
- Is the server expected to treat a submission as an update if only one of the conditions above are met or both?
- what if the identifier of the DocumentReference behind the relatesTo-Link differs from the submitted DocumentReference.identifier?
- what if the relatesTo.reference points to a DocumentReference that doesn't exist on the server? Should it treat the interaction as a (successful) create or error on the update?
We just had a meeting with the stakeholders for the German ISiK specification and we are uncertain on how to continue... Keep the Transaction and clarify the expected behaviour in our IG? Create our own Operation and aim for future alignment with MHD or wait for IHE to decide on how to move forward? We are scheduled to publish in June, so it might be a close call...
I'm open for suggestions...
John Moehrke (Jan 21 2022 at 15:03):
These are excellent comments/questions. Thankyou.
John Moehrke (Jan 21 2022 at 15:04):
One clarification, are you speaking of the MHDS environment, or MHD as an API to XDS?
John Moehrke (Jan 21 2022 at 15:07):
I am not sure where IHE might go relative to changing to an Operation. BUT, your experience would be fantastic influence. so your overall question about if you should wait for IHE, I really don't think you should wait; but I do think engaging (like you are now) with discussion is fantastic.
John Moehrke (Jan 21 2022 at 15:07):
There are three forums where stakeholders might be. This one, Github repo, and the mhd implmementers mailing list.
René Spronk (Jan 21 2022 at 15:22):
Agree that some transactions call for server side (replacement) logic, and therefore FHIR operations. MHD covers the bulk of the workflows, but just like with XDS the more complex stuff (ITI-41, ITI-86, ITI-62) will take longer to flesh out. Right now you should probably go for whatever seems most practical and in the spirit of FHIR & REST, MHD(S) can still be changed at this point in time.
IMHO one can't, and shouldn't, define nor assume any particular server side logic to happen on a simple POST or PUT, besides simply updating its back end store.
Simone Heckmann (Jan 21 2022 at 20:03):
John Moehrke said:
One clarification, are you speaking of the MHDS environment, or MHD as an API to XDS?
That's a difficult one...
We're currently aiming for a simplified spec where only single documents are exchanged within a single organiziation, but we are trying to align as much as possible with MHD, so the documents exchanged between systems using our spec can easily be forwarded to MHD/XDS environments (e.g. our DocumetReferences already have appropriate metadata, but we don't use SubmissionSets).
We might as well have gone and said we just do simple RESTful updates because it terms of compatibility it doesn't matter what the document's prior history looks like * before* it's been forwarded to MHD/XDS.
However, today's meeting has shown that the vendors prefer to use XDS logic for updates (creating a new DocumentReference and linking to the old one) even for the simplified exchange.
Also, everyone agreed, that the decision of how to correctly perform an update should be up to the server, not the client (this cuts out transaction).
...so we're basically at the point where we need to fix the same problem as IHE.
I'm cautiously leaning towards something like a $submit-document operation, with a DocumentReference and a Binary input parameter plus some verbiage around how Clients can express the intent for update (e.g. through the relatesTo property) but eventually leaving it to the server whether to treat it as regular RESTful update of the submitted DocumentReference on the relatesTo-target or to update "XDS-style" and whether to error on invalid relatesTo references or default to a create interaction...
Either way, the expected result of the operation is that for each Document, there is eventually only one version with the status "current" on the server.
...but these are just initial thoughts that need a lot more thinking about...
John Moehrke (Jan 21 2022 at 21:04):
thanks for the thinking. I suspect IHE should move to an operation for many of these reasons.
John Moehrke (Jan 21 2022 at 21:04):
would your group be completely against one more List resource that is marked as a SubmissionSet? That tells the server WHY the operation is being done.
John Moehrke (Jan 21 2022 at 21:05):
is your primary use-case more of a PUSH, rather than a publish?
Simone Heckmann (Feb 02 2022 at 12:17):
More like a publish. We want to support full metadata as well as search.
Simone Heckmann (Feb 02 2022 at 14:46):
I tentatively drafted a $submit-document operation: https://simplifier.net/isik-dokumentenaustausch/submit-document
Points I'm still unclear about:
- Are we going to need more modes than just create/update, and if so, will this approach scale well?
- What should the out parameter(s) be other than an OperationOutcome?
- Can this be easily scaled up to an XDS compatible Operation by adding the SubmissionSet-List as an additional Parameter?
- Would it be better to define distinct operations for update and create rather than putting the mode switch into parameters?
- Are the expectations on Client/Server behaviour plausible?
Please let me hear your thoughts!
John Moehrke (Feb 02 2022 at 14:58):
I think minimally create (mostly) is all that we need. Lesson learned from XDS days. yes there are XDS ways to soft-delete, and hard-delete. Folders can be updated, but DocumentReference and SubmissionSet are create only (they do get updated by the Registry triggered by things like Replace, soft-delete, and hard-delete); but those actions are independent of the publish flow.
John Moehrke (Feb 02 2022 at 14:58):
I think OperationOutcome is all that is needed, right? Good question.
John Moehrke (Feb 02 2022 at 15:00):
yes, SubmissionSet is needed. I understand your use-case doesn't understand the need, but the degenerate form of publishing one document is automatable to a minimal SubmissionSet. The SubmissionSet is useful for provenance, and traceability.
René Spronk (Feb 02 2022 at 20:03):
The closest equivalent to this operation is a PUT/POST of a bundle, so you could consider having a bundle as the OUT parameter. This exposes the client to whatever (filtered/modified/limited) version of the resources as supported/stored by the FHIR server, who may not wish/be able to support all things contained in the IN bundle. The resources in the IN bundle could be richer than that which is required by IHE, or may contain extensions, all of which may or may not be supported by the server.
John Moehrke (Feb 02 2022 at 21:34):
and that is what this operation is replacing... the current transaction bundle.
Simone Heckmann (Feb 03 2022 at 09:07):
I was thinking that returning the DocumentReference (and the SubmissionSet, if present) with the id would be useful, so the client can cache the URL for easier user access (list of last documents, also, the client needs these urls for update/replace). My operation doesn't make assumptions about whether the server replaces or updates the Document (I wanted to leave this decision to the server and make the Operation usable in both scenarios). So the returned DocumentReference with either a new id or a new version is the only way, the client can tell, how the server processed the update.
What I wouldn't wat to have as part of the return parameters is the Binary. I think that would just make things bulky and slow for no good reason.
Simone Heckmann (Feb 03 2022 at 09:12):
The OD I created is already tied to our current use case (ISiK Profiles). But I was hoping that maybe we could infer a common base operation which could be constrained for both our purpose and MHD without deviating too far from the base definition.
René Spronk (Feb 03 2022 at 10:13):
Indeed, Binary should not be returned..
Simone Heckmann (Feb 04 2022 at 10:29):
René Spronk said:
The closest equivalent to this operation is a PUT/POST of a bundle, so you could consider having a bundle as the OUT parameter. This exposes the client to whatever (filtered/modified/limited) version of the resources as supported/stored by the FHIR server, who may not wish/be able to support all things contained in the IN bundle. The resources in the IN bundle could be richer than that which is required by IHE, or may contain extensions, all of which may or may not be supported by the server.
I believe, the original idea in MHD was, to return a transaction-response with only the URLs of the created resources. But I agree with René that returning the created resources as the server understood them is of value to the client. So I'll just use the same Parameters construct for return values but without the Binary.
Last updated: Apr 12 2022 at 19:14 UTC
