Repository: incubator-unomi Updated Branches: refs/heads/master ef24a79ff -> f994d99a1
UNOMI-133 Quick documentation of Apache Unomi consent management Signed-off-by: Serge Huber <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/f994d99a Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/f994d99a Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/f994d99a Branch: refs/heads/master Commit: f994d99a1c9131dc87e115712787391964c68102 Parents: ef24a79 Author: Serge Huber <[email protected]> Authored: Tue May 22 20:16:04 2018 +0200 Committer: Serge Huber <[email protected]> Committed: Tue May 22 20:16:04 2018 +0200 ---------------------------------------------------------------------- src/site/markdown/index.md | 9 +- src/site/markdown/main.md | 1 + .../markdown/versions/master/consent-api.md | 135 +++++++++++++++++++ 3 files changed, 144 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f994d99a/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 0965ad2..42381ce 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -21,7 +21,14 @@ ## Apache Unomi in one sentence Apache Unomi is __a Java Open Source customer data platform__, a Java server designed to manage customers, -leads and visitorsâ data and help personalize customersâ experiences. +leads and visitorsâ data and help personalize customersâ experiences while also offering features to respect visitor +privacy rules (such as [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) + +## *NEW* Privacy (GPDR consent management) upcoming features in version 1.3 +New to release 1.3 (currently in development, nearing completion) are features to manage visitor consents, in order to +make it easier to comply with new privacy regulations such as the [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation) +If you are interested in these new features, you must for the moment build the master branch from source. A quick guide +to these new features is also available [here](versions/master/consent-api.html) ## For developers * Uses ElasticSearch for data storage, dynamic data structure http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f994d99a/src/site/markdown/main.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/main.md b/src/site/markdown/main.md index 00cd81f..be7e0ac 100644 --- a/src/site/markdown/main.md +++ b/src/site/markdown/main.md @@ -48,6 +48,7 @@ In this section we regroup the documentation by Apache Unomi version. - [Cluster setup](versions/master/clustering.html) - [Concepts](versions/master/concepts.html) - [Custom extensions](versions/master/custom-extensions.html) +- [Consent API](versions/master/consent-api.html) # Migration documentation http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f994d99a/src/site/markdown/versions/master/consent-api.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/versions/master/consent-api.md b/src/site/markdown/versions/master/consent-api.md new file mode 100644 index 0000000..43f39db --- /dev/null +++ b/src/site/markdown/versions/master/consent-api.md @@ -0,0 +1,135 @@ +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to You 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 (still in development), 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 [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation). + +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 + +Here is an example of a Profile with a consent attached to it: + + { + "profileId": "8cbe380f-57bb-419d-97bf-24bf30178550", + "sessionId": "0d755f4e-154a-45c8-9169-e852e1d706d9", + "consents": { + "example/newsletter": { + "scope": "example", + "typeIdentifier": "newsletter", + "status": "GRANTED", + "statusDate": "2018-05-22T09:44:33Z", + "revokeDate": "2020-05-21T09:44:33Z" + } + } + } + +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: + + { + "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: + + curl -H "Content-Type: application/json" -X POST -d '{"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"}}}]}' http://localhost:8181/context.json?sessionId=1234 + +How it works (internally) +------------------------- + +Upon receiving this event, Apache Unomi will trigger the modifyAnyConsent rule that has the following definition: + + { + "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 +[ModifyConsentAction Java class](https://github.com/apache/incubator-unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/actions/ModifyConsentAction.java) + +This class will update the current visitor profile to add/update/revoke any consents that are included in the event. \ No newline at end of file
