D### 1) Choose Recipient - Direct

[eReferral Diagram]: https://content.screencast.com/users/jdoleweerd/folders/Snagit/media/9c0fe487-f934-4052-a181-d6dd0991f08f/2017-10-02_16-35-11.png "eReferral Process Flow Map"

[healthcareService relationships]: https://content.screencast.com/users/jdoleweerd/folders/Snagit/media/6db7f0f6-ac33-4e1e-8b59-2d2fc89f8776/2018-01-27_23-45-20.png "healthcareService Resource Relatinships"

![alt text][eReferral Diagram]

### Description
The first step in sending an eReferral is to select the target recipient. There are two types of searches that differ depending on the type of service being targeted:
* */ProviderRole* - When searching for a an individual provider, such as a speialist.
* */HealthcareService* - When searching for a service, such as an education class. This is used for most non-specialist services.

Once an appropriate /ProviderRole or /HealthcareService is identified, it is attached to the HealthcareService.performer attribute to inform the recipient of the desired service, and the related HealthcareService.endpoint or ProviderRole.endpoint is used to route the referral.

Note: /Practitioner & /Organization are not used to with HealthcareService.performer, because they do not contain sufficient information to support a referral. 

### Key FHIR Resources
The key resources referenced in a /HealthcareService search are:
1) [/HealthcareService](https://simplifier.net/CanadianeReferral/MyHealthcareService) - This is the primary resource of a healthcare service, which references all other relevant resources
    i) [/Organization](https://simplifier.net/CanadianeReferral/MyOrganization) - Organization of the target service
    ii) [/Location](https://www.hl7.org/fhir/location.html) - Location(s) of the target service
    iii) [/Endpoint](https://www.hl7.org/fhir/endpoint.html) - Endpoint URL which receives the eReferral payload

The key resources referenced in a /PractitionerRole search are:
1) [/PractitionerRole](https://www.hl7.org/fhir/practitionerrole.html) - Connects practitioners to the HealthcareService
    i) [/Practitioner](https://www.hl7.org/fhir/practitioner.html) - Practitioners connected to the target service

Note: A well structured directory should have at least one corresponding /HealthcareService for each active /PractitionerRole, So that *all* services can be found via a /HealthcareService search.

Note: The /Organization and /Location resources are referenced from both the /HealthcareService and /PractitionerRole resources. In most cases, it is expected that the /Organization and /Location resources would match no matter whether you do the serach via /PractitionerRole or /HealthcareService, but it is possible to be different (e.g., a specialist is an independant contractor who works for a different /HealthcareService on different days of the week).


![alt text][healthcareService relationships]

### Request - Choose Recipient
A referral directory search is performed to find a /HealthcareService or /ProviderRole resource, for the purpose of routing a /ReferralRequest.

Search is performed accoring to the standard [FHIR search](https://www.hl7.org/fhir/search.html) mechanism. 

`GET [base]/[type]?name=value&...{&_format=[mime-type]}}`

### Response
The search response will return a [/Bundle](https://www.hl7.org/fhir/healthcareservice.html) resource which includes the /HealthcareService or /PractitionerRole plus all additional resources requested via _include and _revinclude.

### Search parameters - /HealthcareService
- **characteristic**: Search for one of the HealthcareService's characteristics (e.g., = wheelchair accessible)
- **??? endpoint.connectionType ??? **: used to represent possible connection type profile values.
- **identifier**: Search for services by a formal identifier. This is only available for some service types, such as pharmacies.
- **location**: Search by services at a specific location
- **name**: Search by name of the service (e.g., = Sunnyside Day Program)
- **near**: Search near a lat/long. Normally *near-address* is used instad of *near*. (e.g., =-83.694810:42.256500)
- **organization** Search by the organization that provides the service(e.g., =Red Cross)
- **type**: Search for a ServiceType, includes both clinical and non-clinical categorizations (e.g., =Breast Screen)


Note: It is assumed that if the .endpoint attribute has a value, then the service is available for referral via eReferral.


### Search Parameters - /PractitionerRole
- **identifier**: A practitioner's identifier
- **location**: One of the location's at which this practitioner provides care
- **organization**: The identity of the organization the practitioner represents / acts on behalf of
- **practitioner**: Practitioner that is able to provide the defined services for the organization	
- **service**: The list of healthcare services that this worker provides for this role's Organization/Location(s)
- **specialty**: The practitioner has this specialty at an organization


### Primary Search Cases 
The following examples represent the primary search cases that an eReferral HealthcareService directory supports. Note that these cases includes two search extensions, *near-address* and *practitioner-name* 

Search for a **HealthcareService by ID, and include all relevant resources**

`GET [base]/HealthcareService?_ID=1234567
&_include=HealthcareService:organization
&_include=HealthcareService:location
&_include=HealthcareService:endpoint
&_revinclude=PractitionerRole:service
&_revincldue=PractitionerRole:practitioner`

Search for a **HealthcareService by ServiceType, near lat/long**

`GET [base]/HealthcareService?type=Breast+Screen
&location.near=-83.694810:42.256500&location.near-distance=11.20||km`

Search for a **HealthcareService by Service Name, near a lat/long**

`GET [base]/HealthcareService?name=West Side Breast Clinic
&location.near=-83.694810:42.256500&location.near-distance=11.20||mi_us`

Search for **HealthcareService by Practitioner name**

`GET [base]/HealthcareService?_has:PractitionerRole:service:practitioner.name:contains=Jones`

Search for **PractitionerRole by Specialty, near a lat/long**

`GET [base]/PractitionerRole?specialty.text=Carediology
&location.near=-83.694810:42.256500&Llocation.near-distance=11.20||km`

`GET [base]/PractitionerRole?specialty.coding=394579002
&location.near=-83.694810:42.256500&location.near-distance=11.20||km`


### Extensions
- **XXX near-address XXX** - This is a search parameter extension that can be used to search for a HealthcareService by proximity to a full address (e.g., 1 Yonge St. Toronto Ontario) instead of supplying the *near* search paramater as a lat/long.

- **_has** - The _has parameter provides limited support for reverse chaining - that is, selecting resources based on the properties of resources that refer to them (instead of chaining, above, where resources can be selected based on the properties of resources that they refer to).


### Notes
- The ServiceType is exclusively used for searching for a type of service (instead of parallel taxonomy fields of *category* or *specialty*)
- When referring to a practitioner (such as a specialist or physiotherapist), instead of setting the recipient as a /Practitioner resource, the directory should provide a corresponding /HealthcareService resource that includes a reference to the relevant /Practitioner.
- If an organization wants to make it possible to refer to the whole "organization" instead of a specific service (for example, when the organization has a central intake process to multiple services), then a corresponding /HealthcareService should be created by the directory.
- Use the **identifier** element for external code classifications of services (e.g., pharmacy codes)

### MORE INVESTIGATION NEEDED
- How to connect the /Practitioner to the Healthcareservice via the /practitionerRole resource? See [David Hay Blog] Should we search by specialty via the practitionerRole resource instead of via healthcareService (thought... a practitioner could have a specialty but it still might not apply to the service, better to stick to the type of specialty field)? (https://fhirblog.com/2017/03/13/provider-registries-in-fhir/)

### FOR FURTHER DISCUSSION:
- Q: should having an endpoint be suficcient to determine that is available for eReferral? What if the provider has an endpoint, but's meant for something other than eReferral (such as /Communication or /CommunicationRequest?)
- Q: What ([ServiceType Dataset](https://www.hl7.org/fhir/valueset-service-type.html) to use?
    - A: Referral directories can define their own datasets, or use existing datasets. However, design a method for an application calling the API to GET the dataset of the eReferral directory being used. Should also provide an API to get the list of possible ServiceTypes that a target directory provides
- Q: How to track specialist interest?
    - A: ? Using the _____ field?
- Q: Consider canning the "Search for HealthcareService by Practitioner name, near an address" ... e.g., would I want to search for Dr.Jones, and return the heart clinic?
- note: version of electronic referral... I using the referralMethod to specify the version of the "elec" provided, or maybe an extension to do this. Go ask chat.fhir.
- Should we be able to accept an address? **near-address (EXTENSION)**: Search near an address (e.g., 1 yonge st Toronto Ontario)
- Search on Category vs. Type
- healthcareservice.name vs healthcareservice.programname