Specialty coding in DocumentReference for Referral Report documents

[flackjapz]

Linked Issue

KOALA-734

Related Canvas PR - https://github.com/canvas-medical/canvas/pull/16358
Related Fumage PR - https://github.com/canvas-medical/fumage/pull/719

Description

When creating a Document Reference record for the documents of type Referral Report, providing a specialty is required.
On the Document Reference resource, we decided to use the practiceSetting coding property for the specialty.

[flackjapz]

@rmagier1

I put this in draft as I am not sure how to approach these example payloads.

Having this practiceSetting in the payload cannot go along with any other Document Reference category type other than Referral Report documents (category "referralreport").

Not sure if it would be good idea to change all the create and read examples so that the practiceSetting property of the payload would make sense. Otherwise, it could be misleading for API customers wanting to create other documents and trying to make use of the practiceSetting from the example payloads.

Any ideas?

[aws-amplify-us-west-2]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-421.d298pum72820gn.amplifyapp.com

[rmagier1]

@flackjapz Yeah I get that. Since the Create/Read is only one record and the documentReference encompasses multiple types of documents it is hard.

I would only show it in the Search response since you can show multiple records in there. So make a really good referral report in one of the records in the Search Response. Then it can be in the Postman collection for people to have as a template and remove if they need.

Few additions that we can include with this PR:

1. Seems like we can remove the exclude_in: create for the referralreport on line 219 with the category.coding.code
2. For the description on the context lets add another bullet point for - For Referral Reports, the context will include practiceSettings that include any specialty codings of the referral.
3. We need to mention in the patientsetting that on create that this is required for referralreports. Maybe put this in bold
4. I wasn't part of any planning conversation, but is there going to be any validation that the speciality code is coming from the data_integration.specialty_report_templates? (maybe that is an @kristenoneill question). But if we are only letting them create codings that they have defined in Admin, then we need to specify in the description where in Admin they can grab these codings or set new ones

[flackjapz]

@flackjapz Yeah I get that. Since the Create/Read is only one record and the documentReference encompasses multiple types of documents it is hard.

I would only show it in the Search response since you can show multiple records in there. So make a really good referral report in one of the records in the Search Response. Then it can be in the Postman collection for people to have as a template and remove if they need.

Few additions that we can include with this PR:

1. Seems like we can remove the exclude_in: create for the referralreport on line 219 with the category.coding.code
2. For the description on the context lets add another bullet point for - For Referral Reports, the context will include practiceSettings that include any specialty codings of the referral.
3. We need to mention in the patientsetting that on create that this is required for referralreports. Maybe put this in bold
4. I wasn't part of any planning conversation, but is there going to be any validation that the speciality code is coming from the data_integration.specialty_report_templates? (maybe that is an @kristenoneill question). But if we are only letting them create codings that they have defined in Admin, then we need to specify in the description where in Admin they can grab these codings or set new ones

Hey @rmagier1

About the point 4 - Yes, there was a discussion and planning whether to require that specialty codings must exist in the templates table or not. It was then decided to just let them (API customers) go and create Specialty Report documents from this API without relying on or having anything to do with those templates as otherwise they would bulk up and there are already problems with templates not having any structure on tenants' instances. One of the obstacles also for picking or matching codings with/within templates was that the templates are not unique in any way, so there is no guarantee that a coding won't end up matching with multiple templates. Also, an option to create a template on a fly was not ideal, so we ended up with what we have here - the API customers are responsible for the codings and display values that they choose to store, as long as they state the coding system they are using and as long they are aware of the system we expect them to refer to.

[rmagier1]

@flackjapz thanks for the update, then go ahead and ignore specifying anything in the documentation about where those codes come from since there is no validation

[kristenoneill]

@flackjapz did we leave it completely open, or did we say we wanted to restrict people to snomed / this value set? I see we list only snomed as supported. If not restricted - I would still like to encourage its use in the docs.

[flackjapz]

@flackjapz did we leave it completely open, or did we say we wanted to restrict people to snomed / this value set? I see we list only snomed as supported. If not restricted - I would still like to encourage its use in the docs.

I think we agreed to require that they provide Snomed value set, but without doing any validation of the values since it would require us to keep them stored somewhere either statically in the code, or inside of a database table. The former is not a tricky thing to do, listing values in a dedicated python file is a no brainer, however, there's always a burden of keeping those codes up to date.

UPDATE: forgot to tag you @kristenoneill - these GitHub PR comments are not that user friendly for discussions as much as the "reviews" are, as they have comment threads within them.

[kristenoneill]

UPDATE: forgot to tag you @kristenoneill - these GitHub PR comments are not that user friendly for discussions as much as the "reviews" are, as they have comment threads within them.

@flackjapz - no worries - I did see the reply. My ask is still the same. Can we link to that value set in the create description?

create_description: Specialty coding. Use to determine the Specialty on the documents of the category type 'referralreport'.

[rmagier1]

Suggested change

	**Required** for DocumentReferences of **referralreprt** for `category -> 0 -> coding -> 0 -> code`. Use to determine the Specialty on the documents of the category type 'referralreport'. Use the following value set for reference - <a href="https://hl7.org/fhir/R4/valueset-c80-practice-codes.html" target="_blank">https://hl7.org/fhir/R4/valueset-c80-practice-codes.html</a>
	**Required** for DocumentReferences of with a `category.coding.code` of **referralreprt**. Use to determine the Specialty on the documents of the category type 'referralreport'. Use [this value set for reference](https://hl7.org/fhir/R4/valueset-c80-practice-codes.html).

Linking in a markdown should work like this