Discovery Endpoint

See documentation: http://cds-hooks.org/specification/1.0/#discovery

The discovery endpoint of a CDS Service provider is like the gateway for the EHR to see what CDS Services are available and to see the metadata of each service. It is a well-known endpoint to the EHR, such that the provider's discovery URL ends at /cds-services. For example, if the base URL for a CDS Service provider is https://base-example.com, the EHR can find the discovery endpoint at https://base-example.com/cds-services.

Our services are hosted locally over the base URL of http://localhost:3000 when we start our server. Thus, our discovery endpoint will be at the path of http://localhost:3000/cds-services. The EHR will execute a GET HTTP request to this endpoint to discover the metadata of our services, so we should define this route in our application as such:

app.get('/cds-services', (request, response) => {
  ...
  {define services here}
  ...
});

Once again, we will use our response object to send a response back to the entity calling the endpoint defined here. Ultimately, we want to send back an array of services we offer, so let's look at the services we will define here for this tutorial.

const patientViewExample = {
  hook: 'patient-view',
  id: 'patient-view-example',
  title: 'Example patient-view CDS Service',
  description: 'Displays the name and gender of the patient',
  prefetch: {
    requestedPatient: 'Patient/{{context.patientId}}'
  }
};

Here, we create a variable that holds an object containing information about the patient-view-example service. You can see more about what goes into defining a service in the discovery endpoint in the spec (see link at the top of this section). Most importantly, we note that this specific service gets invoked on the patient-view hook, and has a prefetch request for the EHR. Here, we want to grab the Patient FHIR resource from the EHR, where the EHR fills in the blank for the patient ID of that resource.

For more on Prefetch, see here.

Let's look at another service we want to define in our discovery endpoint.

const medicationPrescribeExample = {
  hook: 'medication-prescribe',
  id: 'medication-prescribe-example',
  title: 'Example medication-prescribe CDS Service',
  description: 'Suggests prescribing Aspirin 81 MG Oral Tablets',
};

In this variable, we define a service that gets invoked on the medication-prescribe hook. Note that there is no prefetch needed in this case. We will see later how we get context from the EHR about what medication is being prescribed.

Now all we need is to put these variables in a services array encompassed in an object so that when we send this metadata back to the EHR calling the discovery endpoint, the EHR knows the proper way to parse the response, according to the CDS Hooks spec. Additionally, we send this response back in JSON, so we can use the native JavaScript JSON.stringify method to format the response as JSON.

const discoveryEndpointServices = {
  services: [ patientViewExample, medicationPrescribeExample ]
};
response.send(JSON.stringify(discoveryEndpointServices, null, 2));

Next step: Patient View Service