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 2022/10/28 14:43:53 UTC
[unomi] branch UNOMI-686-profile-alias-doc created (now c470acb3d)
This is an automated email from the ASF dual-hosted git repository.
shuber pushed a change to branch UNOMI-686-profile-alias-doc
in repository https://gitbox.apache.org/repos/asf/unomi.git
at c470acb3d UNOMI-686 Profile alias documentation - Added new recipe about profile aliases to explain what they are and how to use them - Added data model reference documentation
This branch includes the following new commits:
new c470acb3d UNOMI-686 Profile alias documentation - Added new recipe about profile aliases to explain what they are and how to use them - Added data model reference documentation
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[unomi] 01/01: UNOMI-686 Profile alias documentation - Added new recipe about profile aliases to explain what they are and how to use them - Added data model reference documentation
Posted by sh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
shuber pushed a commit to branch UNOMI-686-profile-alias-doc
in repository https://gitbox.apache.org/repos/asf/unomi.git
commit c470acb3d1bccc3fb570a9cea1f998ad673a5c19
Author: Serge Huber <sh...@jahia.com>
AuthorDate: Fri Oct 28 16:43:47 2022 +0200
UNOMI-686 Profile alias documentation
- Added new recipe about profile aliases to explain what they are and how to use them
- Added data model reference documentation
---
manual/src/main/asciidoc/datamodel.adoc | 34 ++++++++++++
.../main/asciidoc/images/profile-alias-example.png | Bin 0 -> 29130 bytes
.../asciidoc/images/profile-alias-external-ids.png | Bin 0 -> 18239 bytes
.../asciidoc/images/profile-alias-overview.png | Bin 0 -> 10654 bytes
manual/src/main/asciidoc/recipes.adoc | 58 +++++++++++++++++++++
manual/src/main/asciidoc/whats-new.adoc | 2 +-
6 files changed, 93 insertions(+), 1 deletion(-)
diff --git a/manual/src/main/asciidoc/datamodel.adoc b/manual/src/main/asciidoc/datamodel.adoc
index c4ac43a79..e45748f47 100755
--- a/manual/src/main/asciidoc/datamodel.adoc
+++ b/manual/src/main/asciidoc/datamodel.adoc
@@ -370,6 +370,40 @@ image::profile.png[]
}
----
+=== Profile aliases
+
+Profile aliases make it possible to reference profiles using multiple identifiers.
+The profile alias object basically contains a link between the alias ID and the profile ID. The `itemId` of a profile alias is the actual alias ID, which the `profileID` field contains the reference to the aliased profile.
+
+==== Structure definition
+
+Inherits all the fields from: <<Item>>
+
+|===
+| *Field name* | *Type* | *Description*
+
+| profileID | String | The identifier of the profile this aliases points to
+
+| creationTime | DateTime | The date and time of creation of the alias
+
+| modifiedTime | DateTime | The date and time of last modification of the alias
+
+|===
+
+==== Example
+
+In the following example we show an alias ID `facebook_johndoe` for the profile with ID `f72242d2-3145-43b1-8be7-d1d47cf4ad0e`
+
+[source,json]
+----
+ {
+ "profileID": "f72242d2-3145-43b1-8be7-d1d47cf4ad0e",
+ "itemId" : "facebook_johndoe",
+ "creationTime" : "2022-09-16T19:23:51Z",
+ "modifiedTime" : "2022-09-16T19:23:51Z"
+ }
+----
+
=== Persona
A persona is a specialized version of a <<Profile>> object. It basically represents a "typical" profile and can be used
diff --git a/manual/src/main/asciidoc/images/profile-alias-example.png b/manual/src/main/asciidoc/images/profile-alias-example.png
new file mode 100644
index 000000000..aa418513a
Binary files /dev/null and b/manual/src/main/asciidoc/images/profile-alias-example.png differ
diff --git a/manual/src/main/asciidoc/images/profile-alias-external-ids.png b/manual/src/main/asciidoc/images/profile-alias-external-ids.png
new file mode 100644
index 000000000..6e20e56b5
Binary files /dev/null and b/manual/src/main/asciidoc/images/profile-alias-external-ids.png differ
diff --git a/manual/src/main/asciidoc/images/profile-alias-overview.png b/manual/src/main/asciidoc/images/profile-alias-overview.png
new file mode 100644
index 000000000..db41defdf
Binary files /dev/null and b/manual/src/main/asciidoc/images/profile-alias-overview.png differ
diff --git a/manual/src/main/asciidoc/recipes.adoc b/manual/src/main/asciidoc/recipes.adoc
index a074ebce1..592c31db9 100644
--- a/manual/src/main/asciidoc/recipes.adoc
+++ b/manual/src/main/asciidoc/recipes.adoc
@@ -488,3 +488,61 @@ upon successful login using an email, Unomi will look for other profiles that ha
a single profile. Because of the merge, this should only be done for authenticated profiles, otherwise this could be a
security issue since it could be a way to load data from other profiles by merging their data !
+==== What profile aliases are and how to use them
+
+Profile aliases make it possible to reference profiles using multiple identifiers.
+The profile alias object basically contains a link between the alias ID and the profile ID. The `itemId` of a profile alias is the actual alias ID, which the `profileID` field contains the reference to the aliased profile.
+
+===== What they are
+
+image::profile-alias-overview.png[Profile alias overview]
+
+Profile aliases:
+
+- Make it possible to lookup profiles by main (Unomi) ID or by any other alias ID
+- Aliases are just IDs stored in a dedicated index
+- A profile may have an unlimited number of aliases attached to it.
+
+===== How to use them
+
+image::profile-alias-external-ids.png[Profile with external IDs]
+
+Here are different use cases for profile aliases:
+
+- Connect different systems to Unomi such as a CRM, CMS and native mobile app that all have their own iD for a single customer
+- Merging profiles when a visitor is identified
+- Adding new IDs at a later time
+
+===== Example
+
+Here is an example of multiple external aliases pointing to a single Unomi profile
+
+image::profile-alias-example.png[Profile alias example]
+
+===== Interactions with merging
+
+Profile merges have been modified to use aliases starting Unomi 2
+
+Upon merge:
+
+- Properties are copied to the master profile as before
+- An alias is created for the "master" profile with the ID of the merged profile
+- Merged profiles are now deleted
+- "mergedWith" property is no longer used since we deleted the merged profiles
+
+===== API
+
+/context.json and /eventcollector will now look up profiles by profile ID or aliases from the same cookie (`context-profile-id`) or body parameters (`profileId`)
+
+|===
+| *Verb* | *Path* | *Description*
+
+| GET | /cxs/profiles/PROFILE_ID_OR_ALIAS | Retrieves a profile by ID or Alias ID (useful if an external system wants to get a profile)
+
+| GET | /cxs/profiles/PROFILE_ID/aliases | Get all the aliases for a profile
+
+| POST | /cxs/profiles/PROFILE_ID/aliases/ALIAS_ID | Add an alias to a profile
+
+| DELETE | /cxs/profiles/PROFILE_ID/aliases/ALIAS_ID | Remove an alias from a profile
+
+|===
diff --git a/manual/src/main/asciidoc/whats-new.adoc b/manual/src/main/asciidoc/whats-new.adoc
index 764309d59..7efb0e4ff 100644
--- a/manual/src/main/asciidoc/whats-new.adoc
+++ b/manual/src/main/asciidoc/whats-new.adoc
@@ -21,7 +21,7 @@ This new release also introduces a first (beta) version of the Unomi GraphQL API
==== Introducing profiles aliases
-Profiles may now have alias IDs, which is a new way to reference profiles using multiple IDs. The Unomi ID still exists, but a new index with aliases can reference a single Unomi profile. This enables more flexible integrations with external systems, as well as provide more flexible and reliable merging mechanisms. A new REST API makes it easy to define, update and remove aliases for profiles.
+Profiles may now have alias IDs, which is a new way to reference profiles using multiple IDs. The Unomi ID still exists, but a new index with aliases can reference a single Unomi profile. This enables more flexible integrations with external systems, as well as provide more flexible and reliable merging mechanisms. A new REST API makes it easy to define, update and remove aliases for profiles. You can read more about <<What profile aliases are and how to use them,profile aliases here>>.
==== Scopes declarations are now required