This is an automated email from the ASF dual-hosted git repository.
shuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new a6c081c97 UNOMI-686 Profile alias documentation (#529)
a6c081c97 is described below
commit a6c081c975e46908dbc22cefe857ab3c92d82e4a
Author: Serge Huber <[email protected]>
AuthorDate: Mon Nov 7 14:46:03 2022 +0100
UNOMI-686 Profile alias documentation (#529)
- 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
