You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@unomi.apache.org by sh...@apache.org on 2018/05/22 18:16:11 UTC
incubator-unomi git commit: UNOMI-133 Quick documentation of Apache
Unomi consent management
Repository: incubator-unomi
Updated Branches:
refs/heads/master ef24a79ff -> f994d99a1
UNOMI-133 Quick documentation of Apache Unomi consent management
Signed-off-by: Serge Huber <sh...@apache.org>
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 <sh...@apache.org>
Authored: Tue May 22 20:16:04 2018 +0200
Committer: Serge Huber <sh...@apache.org>
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