manual/src/main/asciidoc/consent-api.adoc

//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
=== Consent API

Starting with Apache Unomi 1.3, a new API for consent management is now available. This API
is designed to be able to store/retrieve/update visitor consents in order to comply with new
privacy regulations such as the https://en.wikipedia.org/wiki/General_Data_Protection_Regulation[GDPR].

==== Profiles with consents

Visitor profiles now contain a new Consent object that contains the following information:

* a scope
* a type identifier for the consent. This can be any key to reference a consent. Note that Unomi does not manage consent
definitions, it only stores/retrieves consents for each profile based on this type
* a status : GRANT, DENY or REVOKED
* a status date (the date at which the status was updated)
* a revocation date, in order to comply with GDPR this is usually set at two years

Consents are stored as a sub-structure inside a profile. To retrieve the consents of a profile
you can simply retrieve a profile with the following request:

[source]
----
curl -X POST http://localhost:8181/cxs/context.json?sessionId=1234 \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
    "source": {
        "itemId":"homepage",
        "itemType":"page",
        "scope":"example"
    }
}
EOF
----

Here is an example of a response with a Profile with a consent attached to it:

[source]
----
{
    "profileId": "18afb5e3-48cf-4f8b-96c4-854cfaadf889",
    "sessionId": "1234",
    "profileProperties": null,
    "sessionProperties": null,
    "profileSegments": null,
    "filteringResults": null,
    "personalizations": null,
    "trackedConditions": [],
    "anonymousBrowsing": false,
    "consents": {
        "example/newsletter": {
            "scope": "example",
            "typeIdentifier": "newsletter",
            "status": "GRANTED",
            "statusDate": "2018-05-22T09:27:09Z",
            "revokeDate": "2020-05-21T09:27:09Z"
        }
    }
}
----

It is of course possible to have multiple consents defined for a single visitor profile.

==== Consent type definitions

Apache Unomi does not manage consent definitions, it leaves that to an external system (for example a CMS) so that it
can handle user-facing UIs to create, update, internationalize and present consent definitions to end users.

The only thing that is import to Apache Unomi to manage visitor consents is a globally unique key, that is called the
consent type.

==== Creating / update a visitor consent

A new built-in event type called "modifyConsent" can be sent to Apache Unomi to update a consent for the current
profile.

Here is an example of such an event:

[source]
----
{
  "events": [
    {
      "scope": "example",
      "eventType": "modifyConsent",
      "source": {
        "itemType": "page",
        "scope": "example",
        "itemId": "anItemId"
      },
      "target": {
        "itemType": "anyType",
        "scope": "example",
        "itemId": "anyItemId"
      },
      "properties": {
        "consent": {
          "typeIdentifier": "newsletter",
          "scope": "example",
          "status": "GRANTED",
          "statusDate": "2018-05-22T09:27:09.473Z",
          "revokeDate": "2020-05-21T09:27:09.473Z"
        }
      }
    }
  ]
}
----

You could send it using the following curl request:

[source]
----
curl -X POST http://localhost:8181/cxs/context.json?sessionId=1234 \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
    "source":{
        "itemId":"homepage",
        "itemType":"page",
        "scope":"example"
    },
    "events": [
        {
            "scope":"example",
            "eventType":"modifyConsent",
            "source":{
                "itemType":"page",
                "scope":"example",
                "itemId":"anItemId"
            },
            "target":{
                "itemType":"anyType",
                "scope":"example",
                "itemId":"anyItemId"},
            "properties":{
                "consent":{
                    "typeIdentifier":"newsletter",
                    "scope":"example",
                    "status":"GRANTED",
                    "statusDate":"2018-05-22T09:27:09.473Z",
                    "revokeDate":"2020-05-21T09:27:09.473Z"
                }
            }
        }
    ]
}
EOF
----

==== How it works (internally)

Upon receiving this event, Apache Unomi will trigger the modifyAnyConsent rule that has the following definition:

[source]
----
{
  "metadata" : {
    "id": "modifyAnyConsent",
    "name": "Modify any consent",
    "description" : "Modify any consent and sets the consent in the profile",
    "readOnly":true
  },

  "condition" : {
    "type": "modifyAnyConsentEventCondition",
    "parameterValues": {
    }
  },

  "actions" : [
    {
      "type": "modifyConsentAction",
      "parameterValues": {
      }
    }
  ]

}
----

As we can see this rule is pretty simple it will simply execute the modifyConsentAction that is implemented by the
https://github.com/apache/unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/actions/ModifyConsentAction.java[ModifyConsentAction Java class]

This class will update the current visitor profile to add/update/revoke any consents that are included in the event.