Maintain transforms of XML facility data to support HPD and CSD profiles

[litlfred]

Once issue 62:
#62
is resolved, it would be quite easy to provide compatibility with the IHE HPD and CSD profiles via XSLT. I think that it makes some sense for this to be provided from within the FRED API "universe", rather than requiring every HPD or CSD client to write their own transforms.

For HPD, you would want to transform your ouput XML into a ProviderFeed of the "organizational providers" as in:
ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/HPD/59-Provider%20Information%20Feed%20-%20Req%20and%20Ack_HPD_%20Exampels.pdf

For CSD you could put everything under the Facilities node according to CSD's .xsd. Current version is here:
ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr11-2013-2014/Technical_Cmte/WorkItems/CareServicesDiscovery/CSD%2013-05-14.xsd
though this is not yet stable.

Through the XSLTs would be easy enough, one issue is maintaining them as the FRED API's Facility Object changes. It would be great if these XSLTs could be maintained routinely as the Facility Object changes.

I suppose that the XSLTs could be maintained as "companion resources" to the FRED API that exist outside of the web service itself (e.g via github). However, given that the Facility Object will change, this would impose on a client expecting CSD or HPD to track the version of the FRED API closely. In other words the client would need to be upgraded to a use the updated XSL whenever the FRED API changed. This seems quite fragile.

As alternatives, you could:
*expose the needed XSLT via the FRED API (e.g. the client can ask for the XSLT to produce CSD for the current version of the FRED API)
*require that implementors of FRED API perform the XSL transforms per client request

[djritz]

Given the complexities of maintaining multiple APIs depending on who is the querying application, it may be worthwhile considering consolidating around a single API for facility information. If this single interface is a standards-based API then the mapping to and fro issue goes away. Just a thought...

[edjez]

Thanks Carl. Reading all this I think it is easier to support the endpoint natively, instead of pushing complexity to the client.
This also allows the ability to deal with special cases. e.g. if CSD requires a certain data field like languages and a country just hasn't added that to their data dictionary the CSD endpoint will have to encapsulate bending over backwards to to make reality appear conformant to CSD which may be more complex to do in an XSLT.

Plus maintaining XSLTs is known to be soul destroying.

On May 31, 2013, at 4:51 AM, Carl Leitner notifications@github.com wrote:

Once issue 62:
#62
is resolved, it would be quite easy to provide compatibility with the IHE HPD and CSD profiles via XSLT. I think that it makes some sense for this to be provided from within the FRED API "universe", rather than requiring every HPD or CSD client to write their own transforms.

For HPD, you would want to transform your ouput XML into a ProviderFeed of the "organizational providers" as in:
ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/HPD/59-Provider%20Information%20Feed%20-%20Req%20and%20Ack_HPD_%20Exampels.pdf

For CSD you could put everything under the Facilities node according to CSD's .xsd. Current version is here:
ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr11-2013-2014/Technical_Cmte/WorkItems/CareServicesDiscovery/CSD%2013-05-14.xsd
though this is not yet stable.

Through the XSLTs would be easy enough, one issue is maintaining them as the FRED API's Facility Object changes. It would be great if these XSLTs could be maintained routinely as the Facility Object changes.

I suppose that the XSLTs could be maintained as "companion resources" to the FRED API that exist outside of the web service itself (e.g via github). However, given that the Facility Object will change, this would impose on a client expecting CSD or HPD to track the version of the FRED API closely. In other words the client would need to be upgraded to a use the updated XSL whenever the FRED API changed. This seems quite fragile.

As alternatives, you could:
*expose the needed XSLT via the FRED API (e.g. the client can ask for the XSLT to produce CSD for the current version of the FRED API)
*require that implementors of FRED API perform the XSL transforms per client request

—
Reply to this email directly or view it on GitHub.

[litlfred]

Sorry, I am not fully parsing your comment. Can you please clarify what you mean by supporting the endpoint natively. Are you saying that each FRED implementation on a country-by-country basis would need to support CSD (and/or HPD and/or whatever)?

I may be wrong, but I don't think producing the needed XSLTs will be to onerous. In any case, whenever the CSD XSD stabilizes it would be interesting to map the FRED Facility Object on to CSD. One could do this for HPD now. From here, developing "guidance" XSLTs would be a straight forward exercise and could be added as some kind of "companion resource" to the FRED API. It may not be 100% of what is needed but it should be close.

As to the point of the missing data fields, I would think that it is the responsibility for the client to ensure that the incoming XML message is valid. This view point is compatible with that of the role of the HIM in OpenHIE which would be the FR client in this scenario. In your example, the client/HIM would be responsible for adding in a default language value if it so desired. I think it is natural here as the client/HIM may also very well have other rules it needs to enforce that are beyond the scope of CSD or HPD. In fact HPD and CSD leave some space for this as it allows for locally defined restraints for the values of some of the data fields.

Digging a bit more into the case where the FRED client is the HIM, then I think it would be natural to leave all transformations of the FRED Facility Object XML data to the HIM as that is one of its main roles. However, I think that this would only make sense in the case where no other clients touch the FR directly -- they make all requests via the HIM -- at least in the case when they want the FR to speak CSD or HPD.

That being said, this doesn't address the issue of fragility. When the FRED API Facility Object changes, the transformations applied (XSLT or whatever) may well need to be updated and I am not sure where you are saying that the burden of responsibility for this lies. Even if we reduce this to a single FR client (the HIM) an upgrade of the FR may require a companion upgrade to the HIM to update how it does its transformations.

I think Derek's point is spot-on. If a FR speaks a single standard API, decoupled from the FRED API, then much of this headache goes away. To this end HPD provider feed may not be a bad choice as it would be trivial to implement valid DSML. Looking at the profile on page 45
http://www.ihe.net/Technical_Framework/upload/IHE_ITI_Suppl_HPD.pdf
we only have a minimal set of required attributes (name, uid and identifiers). Moreover there is an "Electronic
Service URI" which "Points to a service entry in a systems directory or to a webservices definition page defining the end points of services" which I suppose could point to the FR.

My main concerns is to ensure we are not introducing any unnecessary burdens on in-country implementation teams. I would hate to think that someone actually has to become fully conversant in the details of the FRED API, CSD, HPD and all of their underlying technologies, communities of practice etc. just to get these things connected and interoperable.

[edjez]

Thanks Carl, some inline comments

On May 31, 2013, at 10:48 AM, Carl Leitner notifications@github.com wrote:

Sorry, I am not fully parsing your comment. Can you please clarify what you mean by supporting the endpoint natively. Are you saying that each FRED implementation on a country-by-country basis would need to support CSD (and/or HPD and/or whatever)?

Hmm.. My head is starting to look like an alphabet soup. What I was trying to say is that the facility registry service should do all it can to help a country implement CSD; I don't think that is implementing the CSD interface itself as that is an aggregate of facilities, providers, organizations, etc. That is best left to an aggregator.( Whether it is physically implemented in the HIM or as a façade that is standalone or embedded in a FR or PR is a secondary issue.)

I may be wrong, but I don't think producing the needed XSLTs will be to onerous. In any case, whenever the CSD XSD stabilizes it would be interesting to map the FRED Facility Object on to CSD. One could do this for HPD now. From here, developing "guidance" XSLTs would be a straight forward exercise and could be added as some kind of "companion resource" to the FRED API. It may not be 100% of what is needed but it should be close.

Agree XSLT's are useful for cases like these, but as with everything there is a tradeoff. Fortunately this is not a one-shot decision, we can try something and iterate to find what works best for our audience. This is all pretty lightweight work.

As to the point of the missing data fields, I would think that it is the responsibility for the client to ensure that the incoming XML message is valid. This view point is compatible with that of the role of the HIM in OpenHIE which would be the FR client in this scenario. In your example, the client/HIM would be responsible for adding in a default language value if it so desired. I think it is natural here as the client/HIM may also very well have other rules it needs to enforce that are beyond the scope of CSD or HPD. In fact HPD and CSD leave some space for this as it allows for locally defined restraints for the values of some of the data fields.

Agree, and we discussed today with @djritz and we agreed. Unfortunately it seems that the XSD inherits from others and we may need to have the element with data representing 'unknown' or 'not specified', here are the specific issues (@djritz will be updating them to reflect today's conversation)
facilityregistry/ihe#6
facilityregistry/ihe#3

Digging a bit more into the case where the FRED client is the HIM, then I think it would be natural to leave all transformations of the FRED Facility Object XML data to the HIM as that is one of its main roles. However, I think that this would only make sense in the case where no other clients touch the FR directly -- they make all requests via the HIM -- at least in the case when they want the FR to speak CSD or HPD.

That being said, this doesn't address the issue of fragility. When the FRED API Facility Object changes, the transformations applied (XSLT or whatever) may well need to be updated and I am not sure where you are saying that the burden of responsibility for this lies. Even if we reduce this to a single FR client (the HIM) an upgrade of the FR may require a companion upgrade to the HIM to update how it does its transformations.

I think Derek's point is spot-on. If a FR speaks a single standard API, decoupled from the FRED API, then much of this headache goes away. To this end HPD provider feed may not be a bad choice as it would be trivial to implement valid DSML. Looking at the profile on page 45.

Well, implementers can choose whether supporting more standards is worth the headache (in our experience it's been effortless to support endpoints compliant with different contracts and expectations. In the FR code particularly, it's modularized to the point where any plug-in can add APIs to the bunch. So we support GeoJSON, GeoRSS, FRED 1.0, and the native FR api with nary a headache in sight . CSD support and FRED APIs can be addressed independently - fortunately that is not the case and there is constructive overlap.

http://www.ihe.net/Technical_Framework/upload/IHE_ITI_Suppl_HPD.pdf
we only have a minimal set of required attributes (name, uid and identifiers). Moreover there is an "Electronic
Service URI" which "Points to a service entry in a systems directory or to a webservices definition page defining the end points of services" which I suppose could point to the FR.

My main concerns is to ensure we are not introducing any unnecessary burdens on in-country implementation teams. I would hate to think that someone actually has to become fully conversant in the details of the FRED API, CSD, HPD and all of their underlying technologies, communities of practice etc. just to get these things connected and interoperable.

Agree and that's my hope too! It should just work for a broad range of expectable scenarios.
—
Reply to this email directly or view it on GitHub.

[litlfred]

There is a new .xsd to support the CSD profile. The current .xsd is here:
http://csd.ohie.org/svn/CSD/CSD_July_25.xsd
and the accompanying document is here:
ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr11-2013-2014/Technical_Cmte/WorkItems/CareServicesDiscovery/CSD%20TI%20candidate%2013-08-09.docx

Some notes: the CSD stored queries and their documentation have been updated to their more or less final form (barring any feedback). I will be doing some cleanup/further documentation/copy-edits in the next day or so, but this should be good enough to see where things are going.

There is some auto-getnerated API documentation on subversio
http://csd.ohie.org/svn/CSD/proposals/csd_consumer_multi_function_api.html

For convenience, I have put the actual xqueries in their own files which are xinclude'd as part of the xml documents containing the which defines the stored queries, for example the organization search is here:
http://csd.ohie.org/svn/CSD/proposals/organization_search.xq
with its corresponding XML here:
http://csd.ohie.org/svn/CSD/proposals/organization_search.xml

For code reusability, I have put several helper functions in an xquery module:
http://csd.ohie.org/svn/CSD/proposals/csd_base_library.xq
that should be imported by the stored queries.

The stored queries (and the underlying module) are at least syntactically correct, though they need to be tested.

I would appreciate any feedback (with concrete suggestions as to changes, of course!).