search

sdhealthconnect / leap-cds

LEAP Consent Decision Service
https://sdhealthconnect.github.io/leap
GNU General Public License v3.0
10 stars 5 forks source link

readme

LEAP-CDS

LEAP Consent Decision Service (LEAP-CDS) enables clients to query about the patient consents applicable to a particular workflow or exchange context. The client provides information about the context of the workflow and the LEAP-CDS responds whether the activity in question is authorized by the patient consent and whether any obligations must be enforced. Patient consents are assumed to be stored in FHIR servers known as Consent Stores which must be introduced to the LEAP-CDS as part of the service configuration. For more details on the general architecture of LEAP-CDS, see here.

API

LEAP-CDS provides two API endpoints interfacing to this service:

CDS Hook Interface

The CDS Hook interface is based on the specifications for Clinical Decision Support (CDS) Hooks. The CDS hook is named patient-consent-consult and, following the CDS Hooks specifications, it resides at the following endpoint:

/cds-services/patient-consent-consult

Request

A POST request to this endpoint must have the header Content-Type set to application/json and have a body similar to the following example:

{
  "hook":"patient-consent-consult",
  "hookInstance":"hook-instance-123",
  "context":{
    "patientId":[
      {
        "system":"http://hl7.org/fhir/sid/us-ssn",
        "value":"111111111"
      }
    ],
    "category": [ 
      {
        "system": "http://terminology.hl7.org/CodeSystem/consentscope",
        "code": "patient-privacy"
      }
    ],
    "class":[
      {
        "system":"http://hl7.org/fhir/resource-types",
        "code":"MedicationStatement"
      }
    ],
    "purposeOfUse":["TREAT"],
    "actor":[
      {
        "system":"urn:ietf:rfc:3986",
        "value":"2.16.840.1.113883.20.5"
      }
    ]
  }
}

The hook attribute must be set to the hook name, in this case patient-consent-consult. The hook instance must be set to a unique value identifying the request (these are the requirements from the CDS Hooks specifications and currently have no effects in the behaviour of the LEAP-CDS).

The context attribute must be present and record the context of the query using the following attributes:

Attribute Description
category An array of codes specifying the broad context of the request (e.g., the workflow context) in order to narrow down the applicable consent types. If more than one category codes are provided, at least one of them should be present for the consent to be deemed applicable. This parameter is optional and not providing it will cause the Consent Decision Service to look at every valid consent otherwise applicable to the request context.
actor (required) An array containing different identifiers of the actor involved in the context of the query (e.g., recipient organization, the clinician engaged in the workflow, etc.). Consents could match based on any of these identifiers. This allows identifying the actor to various degrees of granularity (e.g., organization, end-user, etc.) and match with consents applicable to any of the actors. It also ensures that the applicable consents are found even if different FHIR servers know the actor by different identifiers.
patientId (required) An array containing all the different patient identifiers to ensure that the patient is matched even if identified by different identifiers across different FHIR servers. Each identifier is in the form of a system and value pair. A patient who has an identifier matching any of the identifiers in this array is considered a matching patient and any consents associated with that patient will be processed for making consent decisions.
purposeOfUse The purpose(s) of use in the workflow context. This should be in the form of a string array, or a single string value (in case there is only one purpose) of the codes from the FHIR Purpose of Use valueset. Note that only the code (i.e., without the code system) should be given, as shown in the example below. Rules matching any of the values in the purpose of use array will be considered in making the final consent decision.
class An array of content classes in the workflow context. These are codes from the Content Class Valueset.

The JSON Schema for request is included in the repository here.

Response

The response object is similar to the following example:

{
  "cards":[
    {
      "summary":"CONSENT_PERMIT",
      "detail":"There is a patient consent permitting this action.",
      "indicator":"info",
      "source":{
        "label":"Sample",
        "url":"https://sample-cdms.org"
      },
      "extension":{
        "decision":"CONSENT_PERMIT",
        "obligations":[
          {
            "id":{
              "system":"http://terminology.hl7.org/CodeSystem/v3-ActCode",
              "code":"REDACT"
            },
            "parameters":{
              "codes":[
                {
                  "system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                  "code":"R"
                }
              ]
            }
          }
        ],
        "basedOn": "http://fhir.server.example/fhir/Consent/10023"
      }
    }
  ]
}

Based on the CDS Hooks specifications, the response is in the form of an array of card objects. The LEAP-CDS returns a single card in the response array. The mandatory source attribute is currently set to carry the name and URL of the LEAP-CDS service (defined by environment variables).

The summary is set to one of the following according to the consent decision:

Value Description
NO_CONSENT No applicable consent to the context was found (even though the patient may have consents partially matching the request context). The indicator attribute is set to warning in this case.
CONSENT_PERMIT Patient consent permits the current request. The indicator attribute is set to info in this case..
CONSENT_DENY Patient consent denies the current request. The indicator attribute is set to critical in this case..

The extension attribute in the card contains a machine-readable object recording the decision with the following attributes:

Attribute Description
decision Same as the summary attribute discussed above.
obligations An array of obligations (as discussed below) conveying additional requirements to be followed by the client.
basedOn The full URI of the consent resource based on which the decision has been made. Note that this is the URI from the Consent Decision Service's perspective and it may not be accessible to the client.

Each obligation object has an id attribute which identifies the obligation and a parameters attribute which specifies the parameters for the obligation. Currently, only the REDACT obligation from the obligation policy valueset is supported and is used on CONSENT_PERMIT decisions with either of the following parameters:

Obligation ID Description
codes Any resources associated with these codes (e.g., tagged with these security labels) must be redacted. In other words, access is permitted except to any resource associated with the codes identified by this attribute.
exceptAnyOfCodes All resources other than the ones associated with these codes (e.g., marked with one or more of these security labels) must be redacted. In other words, access is only permitted to the resources associated with the codes identified by this attribute, and not authorized otherwise. The array is interpreted disjunctively, meaning that access to a resource associated with any (and not all) of the codes in this array is authorized.

Special FHIR Content Mode

For very thin clients dealing with FHIR data, there is a special facility to directly provide the data in question to the LEAP-CDS, alongside the request, and have the LEAP-CDS apply the consent decision on the data. This can make it easier for the client to ensure compliance with the consent without implementing the parts of the enforcement logic that entails labeling and modifying the data.

The client can submit a FHIR bundle (containing a collection of FHIR resources) in the request as an optional attribute content in the request context. The LEAP-CDS invokes its internal privacy labeling service to segment this data and also enforces any applicable obligation (e.g. redacting some resources based on the consent rules). The modified data is included in the LEAP-CDS response in the content attribute.

The labeling rules are provided in the form of strings-encoded JSONs in two environment variables SENSITIVITY_TAGGING_RULES and CONFIDENTIALITY_TAGGING_RULES. Samples for the rule data structures are provided here and here (note that the aliases for code system identifiers are defined here).

XACML Interface

The XACML interface is based on a limited implementation of the XACML JSON Profile and resides at the following endpoint:

/xacml

Request

A POST request to this endpoint must have the header Content-Type set to application/json and have a body similar to the following example:

{
  "Request":{
    "AccessSubject":[
      {
        "Attribute":[
          {
            "AttributeId":"actor",
            "Value":[
              {
                "system":"urn:ietf:rfc:3986",
                "value":"2.16.840.1.113883.20.5"
              }
            ]
          }
        ]
      }
    ],
    "Action":[
      {
        "Attribute":[
          {
            "AttributeId":"category",
            "Value":[ 
              {
                "system": "http://terminology.hl7.org/CodeSystem/consentscope",
                "code": "patient-privacy"
              }
            ]
          },
          {
            "AttributeId":"purposeOfUse",
            "Value":["TREAT"]
          }
        ]
      }
    ],
    "Resource":[
      {
        "Attribute":[
          {
            "AttributeId":"patientId",
            "Value":[
              {
                "system":"http://hl7.org/fhir/sid/us-ssn",
                "value":"111111111"
              }
            ]
          },
          {
            "AttributeId":"class",
            "Value":[
              {
                "system":"http://hl7.org/fhir/resource-types",
                "value":"MedicationStatement"
              }
            ]
          }
        ]
      }
    ]
  }
}

The attributes patientId and actor are mandatory while category and purposeOfUse are optional. These attributes have the same meanings as in the CDS Hooks interface request context discussed above.

The XCAML request follows the XACML JSON Profile; a JSON schema for the limited subset of this profile applicable for this request is included in the repository here.

Response

The response from the XACML interface is similar to the following example:

{
  "Response":[
    {
      "Decision":"Permit",
      "Obligations":[
        {
          "Id":{
            "system":"http://terminology.hl7.org/CodeSystem/v3-ActCode",
            "code":"REDACT"
          },
          "AttributeAssignment":[
            {
              "AttributeId":"codes",
              "Value":[
                {
                  "system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                  "code":"R"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

The response follows the JSON Profile of XACML and includes a Response object with the following attributes:

Attribute Description
Decision Permit, Deny, or NotApplicable (for the case where no applicable consent is found, i.e. NO_CONSENT).
Obligations An array of Obligation objects conveying additional requirements to be followed by the client.

Based on the XACML specifications, each Obligation objects has an Id which identifies the obligation and an AttributeAssignment array which specifies a number of parameters for the obligation, in the form of AttributeId and Value pairs. Currently, only the REDACT obligation from the obligation policy valueset is supported and is used on Permit decisions with the same parameters as discussed in the CDS Hooks interface above.

Test Server

An instance of this service is deployed at:

https://sdhc-leap.appspot.com

linked to the FHIR Consent Store at:

https://sdhc-hapi-fhir-leap-wafxyq4bza-uc.a.run.app/fhir

Setup

Local Set Up

In order to set up this project for development, you need to have node.js and yarn installed on your system.

  1. Copy .env.example to .evn and adjust values according to your local setup.
  2. Copy .env.test.example to .env.test and adjust values according to your local setup.
  3. Get the dependencies: 
    $ yarn
  4. To run the tests call: 
    $ yarn test
  5. Run the LEAP-CDS service: 
    $ yarn start

Test

You can use load-fixtures.js (in the test-scripts directory) to set up a quick set of resources on your FHIR server to test this service. This script loads a patient resource, two organization resources, and a consent resource of choice, (from the samples provided in test/fixtures) to a FHIR server, preparing it to be used as the Consent Store for the LEAP-CDS. The usage is as the following:

$ cd test-scripts
$ node load-fixtures.js FHIR_BASE CONSENT_FILE_NAME

in which FHIR_BASE is the base URL for your FHIR server and CONSENT_FILE_NAME is the file name for one of the consent resources in test/fixtures/r4/consents). For example:

$ node load-fixtures.js http://localhost:8080/fhir consent-boris-deny-restricted-label.json

Note that this script sets the dateTime attribute of the consent resource to the current date and time, so that the loaded consent is considered the most recent.