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 <[email protected]> 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
