Operation-resource-cds-hook.json

Operation Definition

{
  "resourceType": "OperationDefinition",
  "id": "Resource-cds-hook",
  "text": {
    "status": "generated",
    "div": "<div>!-- Snipped for Brevity --></div>"
  },
  "url": "http://hl7.org/fhir/OperationDefinition/Resource-cds-hook",
  "name": "The CDS Hook operation is the core API request for CDS Hooks",
  "status": "draft",
  "kind": "operation",
  "date": "2016-03-31T08:01:25+11:00",
  "publisher": "HL7 (FHIR Project)",
  "contact": [
    {
      "telecom": [
        {
          "system": "other",
          "value": "http://hl7.org/fhir"
        },
        {
          "system": "email",
          "value": "fhir@lists.hl7.org"
        }
      ]
    }
  ],
  "description": "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": "cds-hook",
  "system": true,
  "instance": false,
  "parameter": [
    {
      "name": "activity",
      "use": "in",
      "min": 1,
      "max": "1",
      "documentation": "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": "Coding"
    },
    {
      "name": "activityInstance",
      "use": "in",
      "min": 1,
      "max": "1",
      "documentation": "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:\n\nEHR invokes CDS hook\nCDS service returns app link card\nUser clicks app link and interacts with app\nFlow returns to EHR, which re-invokes CDS hook\nCDS service returns decision with user's choice\nNote: the activityInstance is globally unique and should contain enough entropy to be un-guessable.",
      "type": "string"
    },
    {
      "name": "fhirServer",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "Base URL for the calling EHR's FHIR server. The scheme should be https",
      "type": "uri"
    },
    {
      "name": "oauth",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "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": "token",
          "use": "in",
          "min": 1,
          "max": "1",
          "documentation": "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:\n\nAuthorization: Bearer {{token}}",
          "type": "string"
        },
        {
          "name": "scope",
          "use": "in",
          "min": 1,
          "max": "1",
          "documentation": "Represents the set of scopes assigned to this token (see SMART on FHIR scopes)",
          "type": "string"
        },
        {
          "name": "expires",
          "use": "in",
          "min": 1,
          "max": "1",
          "documentation": "Expresses the token lifetime as an integer number of seconds",
          "type": "integer"
        }
      ]
    },
    {
      "name": "redirect",
      "use": "in",
      "min": 1,
      "max": "1",
      "documentation": "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 \"degenerate\" use case for app link cards: pointing to static content. See below for details.)",
      "type": "uri"
    },
    {
      "name": "user",
      "use": "in",
      "min": 0,
      "max": "1",
      "type": "string"
    },
    {
      "name": "patient",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "The FHIR resource id of the current patient. For example, 123.",
      "type": "id"
    },
    {
      "name": "encounter",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "The FHIR resource id of the current encounter. For example, 123",
      "type": "id"
    },
    {
      "name": "context",
      "use": "in",
      "min": 0,
      "max": "*",
      "documentation": "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": "Any"
    },
    {
      "name": "preFetchData",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "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": "Bundle"
    },
    {
      "name": "card",
      "use": "in",
      "min": 1,
      "max": "1",
      "documentation": "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": "summary",
          "use": "in",
          "min": 1,
          "max": "1",
          "documentation": "one-sentence, <140-character summary message for display to the user inside of this card.",
          "type": "string"
        },
        {
          "name": "detail",
          "use": "in",
          "min": 0,
          "max": "1",
          "documentation": "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 \"view more details...\".)",
          "type": "string"
        },
        {
          "name": "indicator",
          "use": "in",
          "min": 1,
          "max": "1",
          "documentation": "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": "code"
        },
        {
          "name": "source",
          "use": "in",
          "min": 1,
          "max": "1",
          "documentation": "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 \"drill-down\" view of the information on this card. For that, use link.url instead.",
          "part": [
            {
              "name": "label",
              "use": "in",
              "min": 1,
              "max": "1",
              "documentation": "human-readable description (in source.label) of the source of the information displayed on this card",
              "type": "string"
            },
            {
              "name": "url",
              "use": "in",
              "min": 0,
              "max": "1",
              "documentation": "Link (in source.url) where the user can learn more about the organization or data set that provided the information on this card",
              "type": "uri"
            }
          ]
        },
        {
          "name": "suggestion",
          "use": "in",
          "min": 0,
          "max": "*",
          "documentation": "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": "label",
              "use": "in",
              "min": 0,
              "max": "1",
              "documentation": "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": "string"
            },
            {
              "name": "create",
              "use": "in",
              "min": 0,
              "max": "*",
              "documentation": "new resource(s) that this suggestion applies within the current activity (e.g. for medication-prescribe, this holds the updated prescription as proposed by the suggestion).",
              "type": "Resource"
            },
            {
              "name": "delete",
              "use": "in",
              "min": 0,
              "max": "*",
              "documentation": "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 \"content\" resource is ever relevant, this field may be omitted",
              "type": "id"
            }
          ]
        },
        {
          "name": "link",
          "use": "in",
          "min": 0,
          "max": "*",
          "documentation": "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": "label",
              "use": "in",
              "min": 0,
              "max": "1",
              "documentation": "human-readable label to display for this link (e.g. the EHR might render this as the underlined text of a clickable link)",
              "type": "string"
            },
            {
              "name": "url",
              "use": "in",
              "min": 0,
              "max": "1",
              "documentation": "URL to load when a user clicks on this link. Note that this may be a \"deep link\" 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": "uri"
            }
          ]
        }
      ]
    },
    {
      "name": "decision",
      "use": "out",
      "min": 0,
      "max": "*",
      "documentation": "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": "create",
          "use": "out",
          "min": 0,
          "max": "*",
          "documentation": "new resource(s) that the EHR should create within the current activity (e.g. for medication-prescribe, this would be the updated prescription that a user had authored in an app session).",
          "type": "Resource"
        },
        {
          "name": "delete",
          "use": "out",
          "min": 0,
          "max": "*",
          "documentation": "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 \"content\" resource is ever relevant, this field may be omitted",
          "type": "id"
        }
      ]
    }
  ]
}