Operation-resource-cds-hook.xml

Operation Definition

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Resource-cds-hook"/>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <h2>The CDS Hook operation is the core API request for CDS Hooks</h2>
      <p>OPERATION: The CDS Hook operation is the core API request for CDS Hooks</p>
      <div>
        <p>It represents an outbound call from the EHR, in the context of a user session, and in
           the context of a specific activity within that user sesssion (e.g. opening a patient record;
           prescribing a new med; or reviewing orders before signing them).</p>

      </div>
      <p>URL: [base]/$cds-hook</p>
      <p>Parameters</p>
      <table class="grid">
        <tr>
          <td>
            <b>Use</b>
          </td>
          <td>
            <b>Name</b>
          </td>
          <td>
            <b>Cardinality</b>
          </td>
          <td>
            <b>Type</b>
          </td>
          <td>
            <b>Binding</b>
          </td>
          <td>
            <b>Documentation</b>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>activity</td>
          <td>1..1</td>
          <td>Coding</td>
          <td/>
          <td>
            <div>
              <p>Name of the Activity (expressed as a coding, preferably drawn from SMART's activity catalog)
                 that the user is performing in the EHR, and for which this hook was triggered (e.g. patient-view,
                 or medication-prescribe)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>activityInstance</td>
          <td>1..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>While working in the EHR, a user can perform multiple activities in series or in parallel.
                 For example, a clinician might prescribe two drugs in a row; each prescription activity
                 would be assigned a unique activityInstance. The activity catalog provides a description
                 of what events should initiate and terminate a given activity. This allows an external
                 service to associate requests with activity state, which is necessary to support the following
                 app-centric decision sequence, where the steps are tied together by a common activityInstance:</p>

              <p>EHR invokes CDS hook
CDS service returns app link card
User clicks app link and interacts with app
Flow returns to EHR, which re-invokes CDS hook
CDS service returns decision with user's choice
Note: the activityInstance is globally unique and should contain enough entropy to be
                 un-guessable.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>fhirServer</td>
          <td>0..1</td>
          <td>uri</td>
          <td/>
          <td>
            <div>
              <p>Base URL for the calling EHR's FHIR server. The scheme should be https</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>oauth</td>
          <td>0..1</td>
          <td/>
          <td/>
          <td>
            <div>
              <p>Security details allowing the CDS service to connect to the EHR's FHIR server. These fields
                 allow the CDS service to access EHR data in a context limited by the current user's privileges</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>oauth.token</td>
          <td>1..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>is a bearer token to be presented with any API calls the CDS service makes to the EHR,
                 by including it in an Authorization header like:</p>

              <p>Authorization: Bearer {{token}}</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>oauth.scope</td>
          <td>1..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>Represents the set of scopes assigned to this token (see SMART on FHIR scopes)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>oauth.expires</td>
          <td>1..1</td>
          <td>integer</td>
          <td/>
          <td>
            <div>
              <p>Expresses the token lifetime as an integer number of seconds</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>redirect</td>
          <td>1..1</td>
          <td>uri</td>
          <td/>
          <td>
            <div>
              <p>This field is only used by services that will return an app link card: when a user clicks
                 the card's link to launch an app, it becomes the app's job to send the user to this redirect
                 URL upon completion of user interaction. (Design note: this field is supplied up-front,
                 as part of the initial request, to avoid requiring the EHR to append any content to app
                 launch links. This helps support an important &quot;degenerate&quot; use case for app
                 link cards: pointing to static content. See below for details.)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>user</td>
          <td>0..1</td>
          <td>string</td>
          <td/>
          <td/>
        </tr>
        <tr>
          <td>IN</td>
          <td>patient</td>
          <td>0..1</td>
          <td>id</td>
          <td/>
          <td>
            <div>
              <p>The FHIR resource id of the current patient. For example, 123.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>encounter</td>
          <td>0..1</td>
          <td>id</td>
          <td/>
          <td>
            <div>
              <p>The FHIR resource id of the current encounter. For example, 123</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>context</td>
          <td>0..*</td>
          <td>Any</td>
          <td/>
          <td>
            <div>
              <p>activity-specific contextual data (see Activity) that an external service needs. (For
                 exampe, with the order-review activity this will include MedicationOrder and Diagnostic
                 resources, among others)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>preFetchData</td>
          <td>0..1</td>
          <td>Bundle</td>
          <td/>
          <td>
            <div>
              <p>as a performance tweak, the EHR may pass along data according to the service's Prefetch-Template.
                 This helps provide the service with all the data it needs to efficiently compute a set
                 of recommendations. (Note that in the absence of preFetchData, an external service can
                 always execute FHIR REST API calls against the EHR server to obtain additional data ad-hoc.)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card</td>
          <td>1..1</td>
          <td/>
          <td/>
          <td>
            <div>
              <p>one CDS result for the EHR to present to the user. Cards can provide a combination of
                 information (for reading), suggested actions (to be applied if a user selects them), and
                 links (to launch an app if the user selects them). The EHR decides how to display cards,
                 but we recommend displaying suggestions using buttons, and links using underlined text.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.summary</td>
          <td>1..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>one-sentence, &lt;140-character summary message for display to the user inside of this
                 card.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.detail</td>
          <td>0..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>optional detailed information to display, represented in Markdown. (For non-urgent cards,
                 the EHR may hide these details until the user clicks a link like &quot;view more details...&quot;.)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.indicator</td>
          <td>1..1</td>
          <td>code</td>
          <td/>
          <td>
            <div>
              <p>Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency,
                 are: success, info, warning, hard-stop. The EHR can use this field to help make UI display
                 decisions such as sort order or coloring. The value hard-stop indicates that the workflow
                 should not be allowed to proceed.R[-12]C</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.source</td>
          <td>1..1</td>
          <td/>
          <td/>
          <td>
            <div>
              <p>grouping structure for a short, human-readable description (in source.label) of the source
                 of the information displayed on this card, with an optional link (in source.url) where
                 the user can learn more about the organization or data set that provided the information
                 on this card. Note that source.url should not be used to supply a context-specific &quot;drill-down&
                quot; view of the information on this card. For that, use link.url instead.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.source.label</td>
          <td>1..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>human-readable description (in source.label) of the source of the information displayed
                 on this card</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.source.url</td>
          <td>0..1</td>
          <td>uri</td>
          <td/>
          <td>
            <div>
              <p>Link (in source.url) where the user can learn more about the organization or data set
                 that provided the information on this card</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.suggestion</td>
          <td>0..*</td>
          <td/>
          <td/>
          <td>
            <div>
              <p>grouping structure for suggestion cards, which allow a service to suggest a set of changes
                 in the context of the current activity (e.g. changing the dose of the medication currently
                 being prescribed, for the medication-prescribe activity)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.suggestion.label</td>
          <td>0..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>human-readable label to display for this suggestion (e.g. the EHR might render this as
                 the text on a button tied to this suggestion).</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.suggestion.create</td>
          <td>0..*</td>
          <td>Resource</td>
          <td/>
          <td>
            <div>
              <p>new resource(s) that this suggestion applies within the current activity (e.g. for medication-prescr
                ibe, this holds the updated prescription as proposed by the suggestion).</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.suggestion.delete</td>
          <td>0..*</td>
          <td>id</td>
          <td/>
          <td>
            <div>
              <p>id(s) of any resources to remove from the current activity (e.g. for the order-review
                 activity, this would provide a way to remove orders from the pending list). In activities
                 like medication-prescribe where only one &quot;content&quot; resource is ever relevant,
                 this field may be omitted</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.link</td>
          <td>0..*</td>
          <td/>
          <td/>
          <td>
            <div>
              <p>grouping structure for a link to an app that the user might want to run for additional
                 information or to help guide a decision</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.link.label</td>
          <td>0..1</td>
          <td>string</td>
          <td/>
          <td>
            <div>
              <p>human-readable label to display for this link (e.g. the EHR might render this as the underlined
                 text of a clickable link)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>card.link.url</td>
          <td>0..1</td>
          <td>uri</td>
          <td/>
          <td>
            <div>
              <p>URL to load when a user clicks on this link. Note that this may be a &quot;deep link&quot;
                 with context embedded in path segments, query parameters, or a hash. In general this URL
                 should embed enough context for the app to determine the activityInstance, and redirect
                 url upon downstream launch, because the EHR will simply use this url as-is, without appending
                 any parameters at launch time.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>OUT</td>
          <td>decision</td>
          <td>0..*</td>
          <td/>
          <td/>
          <td>
            <div>
              <p>grouping structure representing a decision to be applied directly to the user session.
                 Note that a CDS service may only return a decision after interacting with the user through
                 an app link. Decisions are designed to convey any choices the user made in an app session</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>OUT</td>
          <td>decision.create</td>
          <td>0..*</td>
          <td>Resource</td>
          <td/>
          <td>
            <div>
              <p>new resource(s) that the EHR should create within the current activity (e.g. for medication-prescrib
                e, this would be the updated prescription that a user had authored in an app session).</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>OUT</td>
          <td>decision.delete</td>
          <td>0..*</td>
          <td>id</td>
          <td/>
          <td>
            <div>
              <p>id(s) of any resources to remove from the current activity (e.g. for the order-review
                 activity, this would provide a way to remove orders from the pending list). In activities
                 like medication-prescribe where only one &quot;content&quot; resource is ever relevant,
                 this field may be omitted</p>

            </div>
          </td>
        </tr>
      </table>
    </div>
  </text>
  <url value="http://hl7.org/fhir/OperationDefinition/Resource-cds-hook"/>
  <name value="The CDS Hook operation is the core API request for CDS Hooks"/>
  <status value="draft"/>
  <kind value="operation"/>
  <date value="2016-08-11T17:02:54+10:00"/>
  <publisher value="HL7 (FHIR Project)"/>
  <contact>
    <telecom>
      <system value="other"/>
      <value value="http://hl7.org/fhir"/>
    </telecom>
    <telecom>
      <system value="email"/>
      <value value="fhir@lists.hl7.org"/>
    </telecom>
  </contact>
  <description value="It represents an outbound call from the EHR, in the context of a user session, and in
   the context of a specific activity within that user sesssion (e.g. opening a patient record;
   prescribing a new med; or reviewing orders before signing them)."/>
  <code value="cds-hook"/>
  <system value="true"/>
  <instance value="false"/>
  <parameter>
    <name value="activity"/>
    <use value="in"/>
    <min value="1"/>
    <max value="1"/>
    <documentation value="Name of the Activity (expressed as a coding, preferably drawn from SMART's activity catalog)
     that the user is performing in the EHR, and for which this hook was triggered (e.g. patient-view,
     or medication-prescribe)"/>
    <type value="Coding"/>
  </parameter>
  <parameter>
    <name value="activityInstance"/>
    <use value="in"/>
    <min value="1"/>
    <max value="1"/>
    <documentation value="While working in the EHR, a user can perform multiple activities in series or in parallel.
     For example, a clinician might prescribe two drugs in a row; each prescription activity
     would be assigned a unique activityInstance. The activity catalog provides a description
     of what events should initiate and terminate a given activity. This allows an external
     service to associate requests with activity state, which is necessary to support the following
     app-centric decision sequence, where the steps are tied together by a common activityInstance:
      EHR invokes CDS hook CDS service returns app link card User clicks app link and interacts
     with app Flow returns to EHR, which re-invokes CDS hook CDS service returns decision with
     user's choice Note: the activityInstance is globally unique and should contain enough
     entropy to be un-guessable."/>
    <type value="string"/>
  </parameter>
  <parameter>
    <name value="fhirServer"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="Base URL for the calling EHR's FHIR server. The scheme should be https"/>
    <type value="uri"/>
  </parameter>
  <parameter>
    <name value="oauth"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="Security details allowing the CDS service to connect to the EHR's FHIR server. These fields
     allow the CDS service to access EHR data in a context limited by the current user's privileges"/>
    <part>
      <name value="token"/>
      <use value="in"/>
      <min value="1"/>
      <max value="1"/>
      <documentation value="is a bearer token to be presented with any API calls the CDS service makes to the EHR,
       by including it in an Authorization header like:  Authorization: Bearer {{token}}"/>
      <type value="string"/>
    </part>
    <part>
      <name value="scope"/>
      <use value="in"/>
      <min value="1"/>
      <max value="1"/>
      <documentation value="Represents the set of scopes assigned to this token (see SMART on FHIR scopes)"/>
      <type value="string"/>
    </part>
    <part>
      <name value="expires"/>
      <use value="in"/>
      <min value="1"/>
      <max value="1"/>
      <documentation value="Expresses the token lifetime as an integer number of seconds"/>
      <type value="integer"/>
    </part>
  </parameter>
  <parameter>
    <name value="redirect"/>
    <use value="in"/>
    <min value="1"/>
    <max value="1"/>
    <documentation value="This field is only used by services that will return an app link card: when a user clicks
     the card's link to launch an app, it becomes the app's job to send the user to this redirect
     URL upon completion of user interaction. (Design note: this field is supplied up-front,
     as part of the initial request, to avoid requiring the EHR to append any content to app
     launch links. This helps support an important &quot;degenerate&quot; use case for app
     link cards: pointing to static content. See below for details.)"/>
    <type value="uri"/>
  </parameter>
  <parameter>
    <name value="user"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <type value="string"/>
  </parameter>
  <parameter>
    <name value="patient"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="The FHIR resource id of the current patient. For example, 123."/>
    <type value="id"/>
  </parameter>
  <parameter>
    <name value="encounter"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="The FHIR resource id of the current encounter. For example, 123"/>
    <type value="id"/>
  </parameter>
  <parameter>
    <name value="context"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation value="activity-specific contextual data (see Activity) that an external service needs. (For
     exampe, with the order-review activity this will include MedicationOrder and Diagnostic
     resources, among others)"/>
    <type value="Any"/>
  </parameter>
  <parameter>
    <name value="preFetchData"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="as a performance tweak, the EHR may pass along data according to the service's Prefetch-Template.
     This helps provide the service with all the data it needs to efficiently compute a set
     of recommendations. (Note that in the absence of preFetchData, an external service can
     always execute FHIR REST API calls against the EHR server to obtain additional data ad-hoc.)"/>
    <type value="Bundle"/>
  </parameter>
  <parameter>
    <name value="card"/>
    <use value="in"/>
    <min value="1"/>
    <max value="1"/>
    <documentation value="one CDS result for the EHR to present to the user. Cards can provide a combination of
     information (for reading), suggested actions (to be applied if a user selects them), and
     links (to launch an app if the user selects them). The EHR decides how to display cards,
     but we recommend displaying suggestions using buttons, and links using underlined text."/>
    <part>
      <name value="summary"/>
      <use value="in"/>
      <min value="1"/>
      <max value="1"/>
      <documentation value="one-sentence, &lt;140-character summary message for display to the user inside of this
       card."/>
      <type value="string"/>
    </part>
    <part>
      <name value="detail"/>
      <use value="in"/>
      <min value="0"/>
      <max value="1"/>
      <documentation value="optional detailed information to display, represented in Markdown. (For non-urgent cards,
       the EHR may hide these details until the user clicks a link like &quot;view more details...&quot;.)"/>
      <type value="string"/>
    </part>
    <part>
      <name value="indicator"/>
      <use value="in"/>
      <min value="1"/>
      <max value="1"/>
      <documentation value="Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency,
       are: success, info, warning, hard-stop. The EHR can use this field to help make UI display
       decisions such as sort order or coloring. The value hard-stop indicates that the workflow
       should not be allowed to proceed.R[-12]C"/>
      <type value="code"/>
    </part>
    <part>
      <name value="source"/>
      <use value="in"/>
      <min value="1"/>
      <max value="1"/>
      <documentation value="grouping structure for a short, human-readable description (in source.label) of the source
       of the information displayed on this card, with an optional link (in source.url) where
       the user can learn more about the organization or data set that provided the information
       on this card. Note that source.url should not be used to supply a context-specific &quot;drill-down&
      quot; view of the information on this card. For that, use link.url instead."/>
      <part>
        <name value="label"/>
        <use value="in"/>
        <min value="1"/>
        <max value="1"/>
        <documentation value="human-readable description (in source.label) of the source of the information displayed
         on this card"/>
        <type value="string"/>
      </part>
      <part>
        <name value="url"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation value="Link (in source.url) where the user can learn more about the organization or data set
         that provided the information on this card"/>
        <type value="uri"/>
      </part>
    </part>
    <part>
      <name value="suggestion"/>
      <use value="in"/>
      <min value="0"/>
      <max value="*"/>
      <documentation value="grouping structure for suggestion cards, which allow a service to suggest a set of changes
       in the context of the current activity (e.g. changing the dose of the medication currently
       being prescribed, for the medication-prescribe activity)"/>
      <part>
        <name value="label"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation value="human-readable label to display for this suggestion (e.g. the EHR might render this as
         the text on a button tied to this suggestion)."/>
        <type value="string"/>
      </part>
      <part>
        <name value="create"/>
        <use value="in"/>
        <min value="0"/>
        <max value="*"/>
        <documentation value="new resource(s) that this suggestion applies within the current activity (e.g. for medication-prescr
        ibe, this holds the updated prescription as proposed by the suggestion)."/>
        <type value="Resource"/>
      </part>
      <part>
        <name value="delete"/>
        <use value="in"/>
        <min value="0"/>
        <max value="*"/>
        <documentation value="id(s) of any resources to remove from the current activity (e.g. for the order-review
         activity, this would provide a way to remove orders from the pending list). In activities
         like medication-prescribe where only one &quot;content&quot; resource is ever relevant,
         this field may be omitted"/>
        <type value="id"/>
      </part>
    </part>
    <part>
      <name value="link"/>
      <use value="in"/>
      <min value="0"/>
      <max value="*"/>
      <documentation value="grouping structure for a link to an app that the user might want to run for additional
       information or to help guide a decision"/>
      <part>
        <name value="label"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation value="human-readable label to display for this link (e.g. the EHR might render this as the underlined
         text of a clickable link)"/>
        <type value="string"/>
      </part>
      <part>
        <name value="url"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation value="URL to load when a user clicks on this link. Note that this may be a &quot;deep link&quot;
         with context embedded in path segments, query parameters, or a hash. In general this URL
         should embed enough context for the app to determine the activityInstance, and redirect
         url upon downstream launch, because the EHR will simply use this url as-is, without appending
         any parameters at launch time."/>
        <type value="uri"/>
      </part>
    </part>
  </parameter>
  <parameter>
    <name value="decision"/>
    <use value="out"/>
    <min value="0"/>
    <max value="*"/>
    <documentation value="grouping structure representing a decision to be applied directly to the user session.
     Note that a CDS service may only return a decision after interacting with the user through
     an app link. Decisions are designed to convey any choices the user made in an app session"/>
    <part>
      <name value="create"/>
      <use value="out"/>
      <min value="0"/>
      <max value="*"/>
      <documentation value="new resource(s) that the EHR should create within the current activity (e.g. for medication-prescrib
      e, this would be the updated prescription that a user had authored in an app session)."/>
      <type value="Resource"/>
    </part>
    <part>
      <name value="delete"/>
      <use value="out"/>
      <min value="0"/>
      <max value="*"/>
      <documentation value="id(s) of any resources to remove from the current activity (e.g. for the order-review
       activity, this would provide a way to remove orders from the pending list). In activities
       like medication-prescribe where only one &quot;content&quot; resource is ever relevant,
       this field may be omitted"/>
      <type value="id"/>
    </part>
  </parameter>
</OperationDefinition>