diff --git a/en/asgardeo/docs/assets/img/guides/customer-data/feature-preview-cds-on.png b/en/asgardeo/docs/assets/img/guides/customer-data/feature-preview-cds-on.png new file mode 100644 index 0000000000..23e75b8b6d Binary files /dev/null and b/en/asgardeo/docs/assets/img/guides/customer-data/feature-preview-cds-on.png differ diff --git a/en/asgardeo/docs/assets/img/guides/customer-data/profile-attribute-view.png b/en/asgardeo/docs/assets/img/guides/customer-data/profile-attribute-view.png new file mode 100644 index 0000000000..9af5e2fa63 Binary files /dev/null and b/en/asgardeo/docs/assets/img/guides/customer-data/profile-attribute-view.png differ diff --git a/en/asgardeo/docs/assets/img/guides/customer-data/profile-list.png b/en/asgardeo/docs/assets/img/guides/customer-data/profile-list.png new file mode 100644 index 0000000000..dc045e171b Binary files /dev/null and b/en/asgardeo/docs/assets/img/guides/customer-data/profile-list.png differ diff --git a/en/asgardeo/docs/assets/img/guides/customer-data/profile-structure.png b/en/asgardeo/docs/assets/img/guides/customer-data/profile-structure.png new file mode 100644 index 0000000000..a03ff79db4 Binary files /dev/null and b/en/asgardeo/docs/assets/img/guides/customer-data/profile-structure.png differ diff --git a/en/asgardeo/docs/assets/img/guides/customer-data/scopes.gif b/en/asgardeo/docs/assets/img/guides/customer-data/scopes.gif new file mode 100644 index 0000000000..654c4422ea Binary files /dev/null and b/en/asgardeo/docs/assets/img/guides/customer-data/scopes.gif differ diff --git a/en/asgardeo/docs/assets/img/guides/customer-data/unification-rules-list.png b/en/asgardeo/docs/assets/img/guides/customer-data/unification-rules-list.png new file mode 100644 index 0000000000..0123d146ba Binary files /dev/null and b/en/asgardeo/docs/assets/img/guides/customer-data/unification-rules-list.png differ diff --git a/en/asgardeo/docs/assets/img/guides/customer-data/unification-rules.png b/en/asgardeo/docs/assets/img/guides/customer-data/unification-rules.png new file mode 100644 index 0000000000..9a8435d75d Binary files /dev/null and b/en/asgardeo/docs/assets/img/guides/customer-data/unification-rules.png differ diff --git a/en/asgardeo/docs/guides/customer-data/concepts/profile-attributes.md b/en/asgardeo/docs/guides/customer-data/concepts/profile-attributes.md new file mode 100644 index 0000000000..d4d58d4c39 --- /dev/null +++ b/en/asgardeo/docs/guides/customer-data/concepts/profile-attributes.md @@ -0,0 +1,100 @@ +# Profile attributes + +**Profile attributes** define the shape of data that can be stored on a profile for your organization. They control attribute names, types, mutability, and how values are resolved when two profiles are merged. + +Together, the set of profile attributes defined for your organization makes up the **profile attribute schema**. + +--- + +## Scopes + +Profile attributes are organised into three scopes: + +| Scope | Description | +|---|---| +| `identity_attributes` | Attributes sourced from the identity system (e.g. email, phone, name from {{ product_name }} claims) | +| `traits` | Behavioural or preference data managed by the application (e.g. language, segments) | +| `application_data` | Per-application attributes, scoped by application identifier | + +--- + +## Attribute fields + +| Field | Required | Description | +|---|---|---| +| `attribute_name` | yes | Dot-notation path including scope prefix | +| `display_name` | no | Human-readable label | +| `value_type` | yes | One of the supported data types (see below) | +| `merge_strategy` | yes | How to resolve the value when two profiles are merged | +| `mutability` | yes | Read/write behaviour (see below) | +| `multi_valued` | no | If `true`, the attribute holds an array of the declared type | +| `canonical_values` | no | Enumerated allowed values (for string attributes) | +| `sub_attributes` | no | Child attributes when `value_type` is `complex` | +| `application_identifier` | no | Scopes the attribute to a specific application (for `application_data`) | + +--- + +## Supported value types + +| Type | Description | +|---|---| +| `string` | Plain text | +| `integer` | Whole number | +| `decimal` | Floating-point number | +| `boolean` | `true` / `false` | +| `date` | Calendar date | +| `date_time` | Date and time | +| `epoch` | Unix timestamp (milliseconds) | +| `complex` | Nested object, define child fields in `sub_attributes` | + +--- + +## Mutability + +Mutability controls whether an attribute value can be changed once set. + +| Value | Meaning | +|---|---| +| `readWrite` | Can be freely read and updated | +| `readOnly` | System-managed, cannot be updated by applications (e.g. `meta.created_at`) | +| `writeOnly` | Can be written but not read back | +| `immutable` | Must be set at creation, cannot be changed (e.g. `profile_id`) | +| `writeOnce` | Can be empty initially; once set, cannot be updated (e.g. `user_id`) | + +--- + +## Merge strategies + +When two profiles are unified, the merge strategy for each attribute decides which value wins. + +| Strategy | Behaviour | +|---|---| +| `overwrite` | The incoming profile's value replaces the existing one | +| `combine` | Both values are combined into an array (requires `multi_valued: true`) | + +--- + +## Core attributes + +These attributes are built into every profile and cannot be modified: + +| Attribute | Type | Mutability | +|---|---|---| +| `profile_id` | `string` | `immutable` | +| `user_id` | `string` | `writeOnce` | +| `meta.created_at` | `date_time` | `readOnly` | +| `meta.updated_at` | `date_time` | `readOnly` | +| `meta.location` | `string` | `readOnly` | + +--- + +## Staying in sync with {{ product_name }} + +`identity_attributes` mirror the claim dialects in {{ product_name }}. When a claim is added, updated, or deleted, the service automatically reconciles its local attribute set so the two stay aligned, no manual action is needed. + +--- + +## Related + +- [Manage profile attributes]({{base_path}}/guides/customer-data/guides/manage-profile-attributes) +- [Unification rules]({{base_path}}/guides/customer-data/concepts/unification-rules) diff --git a/en/asgardeo/docs/guides/customer-data/concepts/profiles.md b/en/asgardeo/docs/guides/customer-data/concepts/profiles.md new file mode 100644 index 0000000000..cde21d9c11 --- /dev/null +++ b/en/asgardeo/docs/guides/customer-data/concepts/profiles.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/customer-data/concepts/profiles.md" %} diff --git a/en/asgardeo/docs/guides/customer-data/concepts/unification-rules.md b/en/asgardeo/docs/guides/customer-data/concepts/unification-rules.md new file mode 100644 index 0000000000..2632afbe3d --- /dev/null +++ b/en/asgardeo/docs/guides/customer-data/concepts/unification-rules.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/customer-data/concepts/unification-rules.md" %} diff --git a/en/asgardeo/docs/guides/customer-data/enable-customer-data-service.md b/en/asgardeo/docs/guides/customer-data/enable-customer-data-service.md new file mode 100644 index 0000000000..64a19a3696 --- /dev/null +++ b/en/asgardeo/docs/guides/customer-data/enable-customer-data-service.md @@ -0,0 +1 @@ +{% include "../../../../includes/guides/customer-data/enable-customer-data-service.md" %} diff --git a/en/asgardeo/docs/guides/customer-data/guides/manage-profile-attributes.md b/en/asgardeo/docs/guides/customer-data/guides/manage-profile-attributes.md new file mode 100644 index 0000000000..7ab0c73d3b --- /dev/null +++ b/en/asgardeo/docs/guides/customer-data/guides/manage-profile-attributes.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/customer-data/guides/manage-profile-attributes.md" %} diff --git a/en/asgardeo/docs/guides/customer-data/guides/manage-unification-rules.md b/en/asgardeo/docs/guides/customer-data/guides/manage-unification-rules.md new file mode 100644 index 0000000000..9396cddd51 --- /dev/null +++ b/en/asgardeo/docs/guides/customer-data/guides/manage-unification-rules.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/customer-data/guides/manage-unification-rules.md" %} diff --git a/en/asgardeo/docs/guides/customer-data/index.md b/en/asgardeo/docs/guides/customer-data/index.md new file mode 100644 index 0000000000..ef1d31013b --- /dev/null +++ b/en/asgardeo/docs/guides/customer-data/index.md @@ -0,0 +1 @@ +{% include "../../../../includes/guides/customer-data/index.md" %} diff --git a/en/asgardeo/features.json b/en/asgardeo/features.json index ff0f698922..392a51aba8 100644 --- a/en/asgardeo/features.json +++ b/en/asgardeo/features.json @@ -69,5 +69,18 @@ "guides/webhooks/setup-webhooks.md", "guides/webhooks/webhook-events-and-payloads.md" ] + }, + + "customer_data_service": { + "enabled": true, + "page": [ + "guides/customer-data/index.md", + "guides/customer-data/enable-customer-data-service.md", + "guides/customer-data/concepts/profiles.md", + "guides/customer-data/concepts/profile-attributes.md", + "guides/customer-data/concepts/unification-rules.md", + "guides/customer-data/guides/manage-profile-attributes.md", + "guides/customer-data/guides/manage-unification-rules.md" + ] } } diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index 2805ef0040..1636303986 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -32,6 +32,9 @@ theme: extra: base_path: /asgardeo/docs product: asgardeo + nav_chip: + Customer Data: + type: Preview content: sdkconfig: baseUrl: "https://api.asgardeo.io/t/" @@ -577,6 +580,16 @@ nav: - Approval workflows: guides/workflows/approval-workflows.md - Approval workflow rules: guides/workflows/workflow-rules.md - Workflow requests: guides/workflows/workflow-requests.md + - Customer Data: + - Customer Data: guides/customer-data/index.md + - Enable Customer Data Service: guides/customer-data/enable-customer-data-service.md + - Concepts: + - Profiles: guides/customer-data/concepts/profiles.md + - Profile attributes: guides/customer-data/concepts/profile-attributes.md + - Unification rules: guides/customer-data/concepts/unification-rules.md + - Manage: + - Manage profile attributes: guides/customer-data/guides/manage-profile-attributes.md + - Manage unification rules: guides/customer-data/guides/manage-unification-rules.md - Account configurations: - Account configurations: guides/account-configurations/index.md - Login security: diff --git a/en/includes/guides/customer-data/concepts/profiles.md b/en/includes/guides/customer-data/concepts/profiles.md new file mode 100644 index 0000000000..b553caf4eb --- /dev/null +++ b/en/includes/guides/customer-data/concepts/profiles.md @@ -0,0 +1,52 @@ +{% if product == "asgardeo" %} + +# Profiles + +A **profile** is the central entity in the Customer Data Service. It represents a single person's collected data, their identity attributes, behavioural traits, and per application data unified across all interactions. + +![Profile List]({{base_path}}/assets/img/guides/customer-data/profile-list.png){: width="auto" style="display: block; margin: 0;"} + +--- + +## Temporary vs permanent profiles + +Profiles are either **temporary** (anonymous) or **permanent** (identified). + +### Temporary profile + +- Created when an anonymous user first interacts (e.g. visits a website) +- Has no `user_id` +- Linked to a browser cookie (`cds_profile`) +- Accumulates behavioural data during the anonymous session + +### Permanent profile + +- Has a `user_id`, which is set when the user logs in or is created in {{ product_name }} +- Acts as the master record for that identity +- May have one or more temporary profiles merged into it over time + +--- + +## Profile structure + +| Field | Description | +|---|---| +| `profile_id` | System generated UUID. Immutable. | +| `user_id` | The user's ID from {{ product_name }}. Empty on anonymous profiles. | +| `identity_attributes` | Attributes sourced from the identity system (e.g. email, phone, name). Keyed by attribute name. | +| `traits` | Behavioural or preference data (e.g. download count, segment tags). | +| `application_data` | Per-application data, keyed by application identifier. | +| `meta.created_at` | When the profile was created. Read-only. | +| `meta.updated_at` | When the profile was last modified. Read-only. | +| `merged_from` | References to profiles that were unified into this one. | +| `merged_to` | Set on child profiles, points to the master profile they were merged into. | + +![Profile Structure]({{base_path}}/assets/img/guides/customer-data/profile-structure.png){: width="auto" style="display: block; margin: 0;"} + +--- + +## Related + +- [Profile attributes]({{base_path}}/guides/customer-data/concepts/profile-attributes) +- [Unification rules]({{base_path}}/guides/customer-data/concepts/unification-rules) +{% endif %} diff --git a/en/includes/guides/customer-data/concepts/unification-rules.md b/en/includes/guides/customer-data/concepts/unification-rules.md new file mode 100644 index 0000000000..4924a31191 --- /dev/null +++ b/en/includes/guides/customer-data/concepts/unification-rules.md @@ -0,0 +1,44 @@ +{% if product == "asgardeo" %} + +# Unification rules + +**Unification rules** tell the Customer Data Service when two separate profiles should be recognised as the same person and merged. Each rule specifies a profile attribute to match on, if two profiles share the same value for that attribute, they are candidates for merging. + +--- + +## Rule structure + +| Field | Description | +|---|---| +| `rule_name` | Human-readable name. Also recorded as the reason on a merge. | +| `property_name` | The attribute name to match on (e.g. `identity_attributes.email`) | +| `priority` | Lower number = evaluated first. Rules are sorted ascending by priority. | +| `is_active` | Only active rules are evaluated during unification | + +--- + +## How rules are evaluated + +When a profile is created or updated, the service queues it for unification. The unification worker: + +1. Fetches all active rules for the organization, sorted by `priority` ascending. +2. For each rule, checks whether any existing master profile has the same value for `property_name` as the incoming profile. +3. On the first match, merges the two profiles and stops, only one rule fires per unification run. + +Rules are evaluated **after** the system level `userId` match. If two profiles share the same `userId`, they are always merged regardless of any rules. + +--- + +## Priority guidance + +- Assign **lower** priority numbers to high-confidence identifiers (e.g. `identity_attributes.email` at priority 1). +- Assign **higher** priority numbers to weaker signals (e.g. `traits.phone` at priority 10). +- Leave gaps between priorities (e.g. 10, 20, 30) so new rules can be inserted without reordering. + +--- + +## Related + +- [Manage unification rules]({{base_path}}/guides/customer-data/guides/manage-unification-rules) +- [Profile attributes]({{base_path}}/guides/customer-data/concepts/profile-attributes) +{% endif %} diff --git a/en/includes/guides/customer-data/enable-customer-data-service.md b/en/includes/guides/customer-data/enable-customer-data-service.md new file mode 100644 index 0000000000..4c14465b16 --- /dev/null +++ b/en/includes/guides/customer-data/enable-customer-data-service.md @@ -0,0 +1,34 @@ +{% if product == "asgardeo" %} +

Enable Customer Data Service
Preview

+ +!!! Note + + The Customer Data Service is currently in **Preview**. Some features may be subject to changes in future releases. + +The Customer Data Service is hidden behind Feature Preview while in Preview. Once you enable it for your organization, a new **Customer Data** entry appears in the left navigation pane. + +## Enable from Feature Preview + +1. Click on the user dropdown in the top right corner. +2. Select **Feature Preview**. +3. In the feature preview dialog, toggle **Customer Data Service** to **Enabled** and close the dialog. +4. **Customer Data** now appears in the left navigation pane. + +![Enable Customer Data Service from Feature Preview]({{base_path}}/assets/img/guides/customer-data/feature-preview-cds-on.png){: width="auto" style="display: block; margin: 0;"} + +## Disable Customer Data Service + +To turn the feature off again: + +1. Click on the user dropdown in the top right corner. +2. Select **Feature Preview**. +3. Toggle **Customer Data Service** to **Disabled** and close the dialog. + +The **Customer Data** entry is removed from the left navigation pane. Existing profile, attribute, and unification rule data is preserved while the feature is in Preview. + +## Next steps + +- Learn what a [Profile]({{base_path}}/guides/customer-data/concepts/profiles) is and how anonymous activity gets attached to a user. +- Review the [Profile attributes]({{base_path}}/guides/customer-data/concepts/profile-attributes) defined for your organization. +- Configure [Unification rules]({{base_path}}/guides/customer-data/concepts/unification-rules) that decide when two profiles should be merged. +{% endif %} diff --git a/en/includes/guides/customer-data/guides/manage-profile-attributes.md b/en/includes/guides/customer-data/guides/manage-profile-attributes.md new file mode 100644 index 0000000000..a1f8633763 --- /dev/null +++ b/en/includes/guides/customer-data/guides/manage-profile-attributes.md @@ -0,0 +1,71 @@ +{% if product == "asgardeo" %} + +# Manage profile attributes + +Profile attributes control which fields can be stored on a profile and how they behave. Manage them from **Customer Data** → **Profile Attributes** in the console. + +For a conceptual overview of attribute types, mutability, and merge strategies see [Profile attributes]({{base_path}}/guides/customer-data/concepts/profile-attributes). + +--- + +## View profile attributes + +1. From the console, go to **Customer Data** → **Profile Attributes**. +2. The list shows every attribute defined for your organization, grouped by scope (`identity_attributes`, `traits`, `application_data`). + +Attributes sourced from {{ product_name }} claims appear under `identity_attributes` and are managed by the system — their type and mutability are read-only. + +![Profile Attribute View]({{base_path}}/assets/img/guides/customer-data/profile-attribute-view.png){: width="auto" style="display: block; margin: 0;"} + +--- + +## Add an attribute + +1. Click **New attribute**. +2. Fill in: + - **Attribute name** — including the scope prefix (e.g. `traits.preferred_language`). + - **Display name** — optional, human-readable label. + - **Value type** — see [supported value types]({{base_path}}/guides/customer-data/concepts/profile-attributes#supported-value-types). + - **Mutability** — controls whether the value can be changed once set. + - **Merge strategy** — `overwrite` or `combine`. Choose `combine` for attributes where both pre- and post-merge values should be retained (e.g. interest tags). + - **Multi-valued** — required when using `combine`. + - **Canonical values** — optional, for enumerated string values. + - **Application identifier** — required for `application_data` attributes. +3. Click **Save**. + +![Scopes]({{base_path}}/assets/img/guides/customer-data/scopes.gif){: width="auto" style="display: block; margin: 0;"} + +--- + +## Edit an attribute + +1. Click an attribute in the list. +2. Update the fields you want to change. +3. Click **Save**. + +Attributes synced from {{ product_name }} cannot be edited from here — change the corresponding claim in {{ product_name }} and the attribute set will reflect it automatically. + +--- + +## Delete an attribute + +1. Click the attribute, then click **Delete**. +2. Confirm the deletion. + +Existing profile data stored under the attribute is dropped. + +--- + +## What happens when you change `merge_strategy` + +`merge_strategy` is applied on **future** unification runs only. Existing master profiles are not re-merged when you change the strategy. + +If you switch a single-valued attribute to `combine`, also set **Multi-valued** to `true` — otherwise the merge will fall back to `overwrite`. + +--- + +## Related + +- [Profile attributes]({{base_path}}/guides/customer-data/concepts/profile-attributes) — concepts and field reference. +- [Unification rules]({{base_path}}/guides/customer-data/concepts/unification-rules) — rules match on the attributes defined here. +{% endif %} diff --git a/en/includes/guides/customer-data/guides/manage-unification-rules.md b/en/includes/guides/customer-data/guides/manage-unification-rules.md new file mode 100644 index 0000000000..e85b90bcb7 --- /dev/null +++ b/en/includes/guides/customer-data/guides/manage-unification-rules.md @@ -0,0 +1,62 @@ +{% if product == "asgardeo" %} + +# Manage unification rules + +Unification rules tell the Customer Data Service when two profiles should be recognised as the same person and merged. Manage them from **Customer Data** → **Unification Rules** in the console. + +For a conceptual overview see [Unification rules]({{base_path}}/guides/customer-data/concepts/unification-rules). + +--- + +## View unification rules + +1. From the console, go to **Customer Data** → **Unification Rules**. +2. The list shows every rule defined for your organization, ordered by priority. The lowest priority number is evaluated first. + +![Unification rules list]({{base_path}}/assets/img/guides/customer-data/unification-rules-list.png){: width="auto" style="display: block; margin: 0;"} + +--- + +## Create a rule + +1. Click **New unification rule**. +2. Fill in: + - **Rule name** — human readable name. + - **Match attribute** — the profile attribute to match on (e.g. `identity_attributes.email`). + - **Priority** — lower numbers are evaluated first. +3. Click **Save**. + +![Unification Rules]({{base_path}}/assets/img/guides/customer-data/unification-rules.png){: width="auto" style="display: block; margin: 0;"} + +--- + +## Edit or reorder a rule + +1. Click a rule in the list. +2. Change its match attribute, priority, or active state. +3. Click **Save**. + +Editing a rule does **not** retroactively merge or un-merge existing profiles — it only affects future unification runs. + +--- + +## Disable a rule + +Toggle **Active** to off. The rule is skipped during evaluation but stays in the list and keeps its priority. + +--- + +## Delete a rule + +1. Click the rule, then click **Delete**. +2. Confirm the deletion. + +Existing merges already recorded under this rule are not reversed. + +--- + +## Related + +- [Unification rules]({{base_path}}/guides/customer-data/concepts/unification-rules) — concepts and field reference. +- [Profile attributes]({{base_path}}/guides/customer-data/concepts/profile-attributes) — the attribute set rules can match on. +{% endif %} diff --git a/en/includes/guides/customer-data/index.md b/en/includes/guides/customer-data/index.md new file mode 100644 index 0000000000..d00e0af409 --- /dev/null +++ b/en/includes/guides/customer-data/index.md @@ -0,0 +1,26 @@ +{% if product == "asgardeo" %} + +# Customer Data + +The Customer Data Service (CDS) collects and unifies data about your end users across every interaction with your applications, and gives each user a single profile that represents who they are and what they have done across your applications. + +!!! note + Customer Data Service is currently in **Preview**. You need to enable it from **Feature Preview** before the **Customer Data** section appears in the console. See [Enable Customer Data Service]({{base_path}}/guides/customer-data/enable-customer-data-service). + +## What you can do with it + +- **Build a unified profile per user** by combining identity attributes from {{ product_name }}, behavioural traits, and per-application data into one record. +- **Unify anonymous and authenticated sessions** so that activity captured before sign-up stays attached to the user once they register or log in. +- **Define profile attributes** that control the shape of data each profile can hold — types, mutability, and how values are resolved when profiles are merged. +- **Configure unification rules** that decide when two separate profile records should be recognised as the same person and merged. + +## Where to start + +| Read | What it covers | +|---|---| +| [Enable Customer Data Service]({{base_path}}/guides/customer-data/enable-customer-data-service) | Turn the feature on from Feature Preview. | +| [Profiles]({{base_path}}/guides/customer-data/concepts/profiles) | The shape of a profile and how anonymous and permanent profiles relate. | +| [Profile attributes]({{base_path}}/guides/customer-data/concepts/profile-attributes) | Attribute types, mutability, and merge strategies. | +| [Unification rules]({{base_path}}/guides/customer-data/concepts/unification-rules) | When two records get merged into one. | + +{% endif %}