Configuring consent policies using attributes

This page describes how to configure consent policies using attributes.

Attribute definitions are resources in a consent store that determine the consent attributes that the Consent Management API processes and the permitted values for the attributes. Each attribute definition has one of the following attribute types:

  • A RESOURCE attribute is an attribute whose value is defined by the properties of the data. For example, whether the data is de-identified or identifiable.
  • A REQUEST attribute is an attribute whose value is defined by the proposed use of the data. For example, the groups that are consented for use, such as internal researchers, external researchers, or clinical administrators.

Attribute definitions also determine how an attribute is evaluated when users' consents have no information pertaining to an attribute.

The following diagram shows the data flow for configuring consent attributes:

attribute definitions

To support all the attribute definitions your use case requires, repeat the process shown in Creating a RESOURCE attribute definition and Creating a REQUEST attribute definition.

You can create additional attribute definitions or update attribute definitions without having to rebuild your consent store.

Creating a RESOURCE attribute definition

To create a RESOURCE attribute definition, use the projects.locations.datasets.consentStores.attributeDefinitions.create method. Make a POST request and specify the following information in the request:

  • The name of the parent consent store
  • A name for the attribute definition that's unique in the parent consent store. The name can be any Unicode string of 1 to 256 characters consisting of numbers, letters, underscores, dashes, and periods but it can't start with a number
  • The category of the attribute, in this case RESOURCE
  • The possible values that this attribute can represent
  • An access token

curl

The following sample shows a POST request using curl that creates a RESOURCE attribute named data_identifiable with values identifiable and de-identified:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
      'description': 'whether the data is identifiable',
      'category': 'RESOURCE',
      'allowed_values': ['identifiable', 'de-identified'],
    }" \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=data_identifiable"

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/data_identifiable",
    "description": "whether the data is identifiable",
    "category": "RESOURCE",
    "allowedValues": [
      "identifiable",
      "de-identified"
    ]
}

PowerShell

The following sample shows a POST request using Windows PowerShell that creates a RESOURCE attribute named data_identifiable with values identifiable and de-identified:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
      'description': 'whether the data is identifiable',
      'category': 'RESOURCE',
      'allowed_values': ['identifiable', 'de-identified']
    }" `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=data_identifiable" | Select-Object -Expand Content

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/data_identifiable",
    "description": "whether the data is identifiable",
    "category": "RESOURCE",
    "allowedValues": [
      "identifiable",
      "de-identified"
    ]
}

Creating a REQUEST attribute definition

To create a REQUEST attribute definition, use the projects.locations.datasets.consentStores.attributeDefinitions.create method. Make a POST request and specify the following information in the request:

  • The name of the parent consent store
  • A name for the attribute definition that's unique in the parent consent store. The name can be any Unicode string of 1 to 256 characters consisting of numbers, letters, underscores, dashes, and periods but it can't start with a number
  • The category of the attribute, in this case REQUEST
  • The possible values that this attribute can represent
  • An access token

curl

The following sample shows a POST request using curl that creates a REQUEST attribute named requester_identity:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
      'description': 'what groups are consented for access',
      'category': 'REQUEST',
      'allowed_values': ['internal-researcher', 'external-researcher', 'clinical-admin'],
    }" \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=requester_identity"

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/requester_identity",
    "description": "what groups are consented for access",
    "category": "REQUEST",
    "allowedValues": [
      "internal-researcher",
      "external-researcher",
      "clinical-admin"
    ]
}

PowerShell

The following sample shows a POST request using Windows PowerShell that creates a REQUEST attribute named requester_identity:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
      'description': 'what groups are consented for access',
      'category': 'REQUEST',
      'allowed_values': ['internal-researcher', 'external-researcher', 'clinical-admin']
    }" `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=requester_identity" | Select-Object -Expand Content

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/requester_identity",
    "description": "what groups are consented for access",
    "category": "REQUEST",
    "allowedValues": [
      "internal-researcher",
      "external-researcher",
      "clinical-admin"
    ]
}