AWS connect: Rewrite Customer Profiles standard identifiers documentation
Summary
Restructures the standard identifiers page into sections (reference, PROFILE/SECONDARY/LOOKUP_ONLY comparison, NEW_ONLY behavior, combination rules, required identifiers per object type), replacing the old per-identifier table with a consolidated reference and adding new identifiers like DEVICE and WEB_ANALYTICS.
Security assessment
This is a documentation reorganization of Customer Profiles identifier semantics (matching, storage, and combination rules). It clarifies data-handling behavior but does not address a specific vulnerability, CVE, or security control, so it is not security documentation.
Evidence
+`LOOKUP_ONLY` | Used only to match a profile during this ingestion. The key value is not stored afterward, so it can't be used for future matches or searches. Can't be combined with `UNIQUE`.
Diff
diff --git a/connect/latest/adminguide/standard-identifiers.md b/connect/latest/adminguide/standard-identifiers.md index 99c69fbcb..6fcf9bb52 100644 --- a//connect/latest/adminguide/standard-identifiers.md +++ b//connect/latest/adminguide/standard-identifiers.md @@ -7 +7 @@ -Compatible identifiers +Standard identifiers referencePROFILE, SECONDARY, and LOOKUP_ONLY comparedNEW_ONLY behaviorCombination rulesRequired identifiers per object type @@ -9 +9 @@ Compatible identifiers -# Standard identifiers for setting attributes on the key in Customer Profiles +# Standard identifiers in Customer Profiles @@ -11,26 +11 @@ Compatible identifiers -With standard identifiers, you can set attributes on the key. Decide which identifiers to use based on how you want the data to be ingested in the profiles. For example, you mark phone number with the identifier PROFILE. This means phone number is to be treated as unique identifier. If Customer Profiles gets two contacts with the same phone number, the contacts are going to be merged into a single profile. - -Identifier name | Description ----|--- -AIR_PREFERENCE | This identifier means that this key uniquely identifies an air preference. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any air preference that has this key associated with it. - - * If an air preference is found, then the object is assigned to that air preference. - * If more than one air preference is found when searching for this key, the match is rejected. (Only keys that uniquely identify an air preference should be used as unique keys except for special circumstances.) - - -AIR_BOOKING | This identifier means that this key uniquely identifies an air booking. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any air booking that has this key associated with it. - - * If an air booking is found, then the object is assigned to that air booking. - * If more than one air booking is found when searching for this key, the match is rejected. (Only keys that uniquely identify an air booking should be used as unique keys except for special circumstances.) - - -AIR_SEGMENT | This identifier means that this key uniquely identifies an air segment. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any air segment that has this key associated with it. - - * If an air segment is found, then the object is assigned to that air segment. - * If more than one air segment is found when searching for this key, the match is rejected. (Only keys that uniquely identify an air segment should be used as unique keys except for special circumstances.) - - -HOTEL_PREFERENCE | This identifier means that this key uniquely identifies a hotel preference. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any hotel preference that has this key associated with it. - - * If a hotel preference is found, then the object is assigned to that hotel preference. - * If more than one hotel preference is found when searching for this key, the match is rejected. (Only keys that uniquely identify a hotel preference should be used as unique keys except for special circumstances.) +Standard identifiers are tags applied to a key that describe its role during ingestion. They tell Customer Profiles how each key participates in matching an object to a profile and whether the key value is stored for future use. You set standard identifiers in the `StandardIdentifiers` array of a key definition. For more information, see [Key definitions in Customer Profiles object type mappings](./mapping-key-definitions.html). @@ -37,0 +13 @@ HOTEL_PREFERENCE | This identifier means that this key uniquely identifies a ho +## Standard identifiers reference @@ -39,22 +15,12 @@ HOTEL_PREFERENCE | This identifier means that this key uniquely identifies a ho -HOTEL_STAY_REVENUE | This identifier means that this key uniquely identifies a hotel stay revenue. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any hotel stay revenue that has this key associated with it. - - * If a hotel stay revenue is found, then the object is assigned to that hotel stay revenue. - * If more than one hotel stay revenue is found when searching for this key, the match is rejected. (Only keys that uniquely identify a hotel stay revenue should be used as unique keys except for special circumstances.) - - -HOTEL_RESERVATION | This identifier means that this key uniquely identifies a hotel reservation. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any hotel reservation that has this key associated with it. - - * If a hotel reservation is found, then the object is assigned to that hotel reservation. - * If more than one hotel reservation is found when searching for this key, the match is rejected. (Only keys that uniquely identify a hotel reservation should be used as unique keys except for special circumstances.) - - -LOYALTY | This identifier means that this key uniquely identifies a loyalty. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any loyalty that has this key associated with it. - - * If a loyalty is found, then the object is assigned to that loyalty. - * If more than one loyalty is found when searching for this key, the match is rejected. (Only keys that uniquely identify a loyalty should be used as unique keys except for special circumstances.) - - -LOYALTY_TRANSACTION | This identifier means that this key uniquely identifies a loyalty transaction. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any loyalty transaction that has this key associated with it. - - * If a loyalty transaction is found, then the object is assigned to that loyalty transaction. - * If more than one loyalty transaction is found when searching for this key, the match is rejected. (Only keys that uniquely identify a loyalty transaction should be used as unique keys except for special circumstances.) +Identifier | Purpose +---|--- +`UNIQUE` | Identifies the specific object instance. Exactly one `UNIQUE` identifier is required per object type. When a new object arrives with the same `UNIQUE` value, it replaces the existing one. +`PROFILE` | Used to look up the profile the object belongs to. At least one `PROFILE` identifier is required. The key is stored so it can also be used for future matching and for `SearchProfiles` queries. +`SECONDARY` | A fallback profile-matching key. `SECONDARY` is always used in combination with `PROFILE`—the key's standard identifiers must include both. Secondary keys are only consulted when no primary `PROFILE` key produces an unambiguous match. The key is always stored. +`LOOKUP_ONLY` | Used only to match a profile during this ingestion. The key value is not stored afterward, so it can't be used for future matches or searches. Can't be combined with `UNIQUE`. +`NEW_ONLY` | The key is stored only when a new profile is created during this ingestion. If the object matches an existing profile, the key behaves like `LOOKUP_ONLY`. Can't be combined with `UNIQUE`. +`ASSET`, `ORDER`, `CASE` | Associates the object with a standard asset, order, or case record. +`AIR_PREFERENCE`, `HOTEL_PREFERENCE`, `AIR_BOOKING`, `AIR_SEGMENT`, `HOTEL_RESERVATION`, `HOTEL_STAY_REVENUE` | Associates the object with the corresponding travel record. +`LOYALTY`, `LOYALTY_TRANSACTION`, `LOYALTY_PROMOTION` | Associates the object with a loyalty record, transaction, or promotion. +`DEVICE` | Associates the object with a device record. +`WEB_ANALYTICS` | Associates the object with a web analytics event. @@ -61,0 +28 @@ LOYALTY_TRANSACTION | This identifier means that this key uniquely identifies a +## PROFILE, SECONDARY, and LOOKUP_ONLY compared @@ -63 +30 @@ LOYALTY_TRANSACTION | This identifier means that this key uniquely identifies a -LOYALTY_PROMOTION | This identifier means that this key uniquely identifies a loyalty promotion. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any loyalty promotion that has this key associated with it. +All three identify the profile an object belongs to. They differ in when they're evaluated during matching and whether the key value is stored afterward. `SECONDARY` is not used on its own—a secondary key lists both `PROFILE` and `SECONDARY` in its standard identifiers: @@ -65,2 +32,7 @@ LOYALTY_PROMOTION | This identifier means that this key uniquely identifies a l - * If a loyalty promotion is found, then the object is assigned to that loyalty promotion. - * If more than one loyalty promotion is found when searching for this key, the match is rejected. (Only keys that uniquely identify a loyalty promotion should be used as unique keys except for special circumstances.) +Aspect | `PROFILE` | `SECONDARY` | `LOOKUP_ONLY` +---|---|---|--- +Required? | Yes—at least one per object type | No | No +When it's used for matching | In the primary matching pass | Only as a fallback when primary `PROFILE` keys don't match | In the primary matching pass, alongside `PROFILE` keys +Stored after ingestion? | Yes | Yes | No +Available for future lookups and `SearchProfiles`? | Yes | Yes | No +Best for | Durable identifiers that reliably locate the profile, such as a customer ID | Lower-priority identifiers that you still want saved for future use | Transient identifiers you don't want permanently associated @@ -67,0 +40 @@ LOYALTY_PROMOTION | This identifier means that this key uniquely identifies a l +## NEW_ONLY behavior @@ -69,2 +42 @@ LOYALTY_PROMOTION | This identifier means that this key uniquely identifies a l -UNIQUE | This identifier must be specified by exactly one index for each object type. This key is used to uniquely identify objects of the object type for either fetching them or if needed update a submitted object at a later date. All the fields that make up the UNIQUE keys are required to be specified when submitting a new object or it is rejected. -PROFILE | This identifier means that this key uniquely identifies a profile. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any profile that has this key associated with it. +`NEW_ONLY` scopes a key so it's only attached to profiles this ingestion creates: @@ -72,2 +44 @@ PROFILE | This identifier means that this key uniquely identifies a profile. Whe - * If a profile is found, then the object is assigned to that profile. - * If more than one profile is found when searching for this key, the match is rejected. (Only keys that uniquely identify a profile should be used as unique keys except for special circumstances.) + * If the object matches an **existing** profile, the key is used for matching only and is not stored on that profile (same as `LOOKUP_ONLY`). @@ -74,0 +46 @@ PROFILE | This identifier means that this key uniquely identifies a profile. Whe + * If the object causes a **new** profile to be created, the key is stored on the new profile (same as `PROFILE`). @@ -76 +47,0 @@ PROFILE | This identifier means that this key uniquely identifies a profile. Whe -LOOKUP_ONLY | This identifier indicates the key is not stored after ingesting the object. The key is only to be used for determining the profile during ingestion. The key value is not associated with the profile during ingestion, which means it can't be used to allow searching for it or matching later ingested objects to the same key. @@ -78 +48,0 @@ LOOKUP_ONLY | This identifier indicates the key is not stored after ingesting th -###### Note @@ -80,2 +49,0 @@ LOOKUP_ONLY | This identifier indicates the key is not stored after ingesting th - * You cannot specify a key as both a `UNIQUE` identifier and a `LOOKUP_ONLY` identifier. - * You can only use `PROFILE` together with `LOOKUP_ONLY` if there is at least one other key that has the `PROFILE` identifier without the `NEW_ONLY` or `LOOKUP_ONLY` identifiers. The only exception is the `_profileId` key, which can have the `PROFILE` and `LOOKUP_ONLY` identifier combination on its own. @@ -82,0 +51 @@ LOOKUP_ONLY | This identifier indicates the key is not stored after ingesting th +Use `NEW_ONLY` when you want a value to help create and identify a new profile, but you don't want it added to an existing profile—where it could accidentally cause unrelated profiles to merge. @@ -84 +53 @@ LOOKUP_ONLY | This identifier indicates the key is not stored after ingesting th -NEW_ONLY | If the profile does not already exist before the object is ingested, the key is associated with the profile. Otherwise the key is only used for matching objects to profiles. +## Combination rules @@ -86 +55 @@ NEW_ONLY | If the profile does not already exist before the object is ingested, -###### Note + * `UNIQUE` can't be combined with `LOOKUP_ONLY` or `NEW_ONLY`. @@ -88,2 +57 @@ NEW_ONLY | If the profile does not already exist before the object is ingested, - * You cannot specify a key as both a `UNIQUE` identifier and a `NEW_ONLY` identifier. - * You can only use `PROFILE` together with `NEW_ONLY` if there is at least one other key that has the `PROFILE` identifier without the `NEW_ONLY` or `LOOKUP_ONLY` identifiers. + * If any key combines `PROFILE` with `LOOKUP_ONLY` or `NEW_ONLY`, at least one other key must use `PROFILE` on its own (without `LOOKUP_ONLY` or `NEW_ONLY`). This guarantees an ingested object can always be persistently associated with a profile. The `_profileId` key is exempt from this requirement. @@ -90,0 +59 @@ NEW_ONLY | If the profile does not already exist before the object is ingested, + * Standard object identifiers (`ASSET`, `ORDER`, and so on) can be combined with `PROFILE` and `UNIQUE` as needed. @@ -92,2 +61 @@ NEW_ONLY | If the profile does not already exist before the object is ingested, -SECONDARY | During the matching of an object to a profile, Customer Profiles first looks up all PROFILE keys that do not have the SECONDARY identifier. These are considered first. SECONDARY keys are only considered if no matching profile is found using these keys. -ASSET | This identifier means that this key uniquely identifies an asset. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any asset that has this key associated with it. + * If your fields target a standard object type—for example, `_asset.SerialNumber`—at least one key must carry that object type's standard identifier (`ASSET`). @@ -95,2 +63 @@ ASSET | This identifier means that this key uniquely identifies an asset. When t - * If an asset is found, then the object is assigned to that asset. - * If more than one asset is found when searching for this key, the match is rejected. (Only keys that uniquely identify an asset should be used as unique keys except for special circumstances.) + * Reserved keys such as `_profileId`, `_orderId`, `_caseId`, and `_assetId` must be declared `LOOKUP_ONLY`. @@ -99 +65,0 @@ ASSET | This identifier means that this key uniquely identifies an asset. When t -ORDER | This identifier means that this key uniquely identifies an order. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any order that has this key associated with it. @@ -101,2 +66,0 @@ ORDER | This identifier means that this key uniquely identifies an order. When t - * If an order is found, then the object is assigned to that order. - * If more than one order is found when searching for this key, the match is rejected. (Only keys that uniquely identify an order should be used as unique keys except for special circumstances.) @@ -103,0 +68 @@ ORDER | This identifier means that this key uniquely identifies an order. When t +## Required identifiers per object type @@ -105 +70 @@ ORDER | This identifier means that this key uniquely identifies an order. When t -CASE | This identifier means that this key uniquely identifies a case. When this identifier is specified, it means that during ingestion, Customer Profiles looks for any case that has this key associated with it. + * Exactly one key with a `UNIQUE` identifier. @@ -107,2 +72 @@ CASE | This identifier means that this key uniquely identifies a case. When this - * If a case is found, then the object is assigned to that case. - * If more than one case is found when searching for this key, the match is rejected. (Only keys that uniquely identify a case should be used as unique keys except for special circumstances.) + * At least one key with a `PROFILE` identifier. @@ -109,0 +74 @@ CASE | This identifier means that this key uniquely identifies a case. When this + * If fields target a standard object type, at least one key with that object type's standard identifier. @@ -112 +76,0 @@ CASE | This identifier means that this key uniquely identifies a case. When this -## Compatible identifiers @@ -114 +77,0 @@ CASE | This identifier means that this key uniquely identifies a case. When this - @@ -122 +85 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Object type mapping definition details in Connect Customer Customer Profiles +Key definitions @@ -124 +87 @@ Object type mapping definition details in Connect Customer Customer Profiles -How Customer Profiles processes key definitions +Examples of object type mappings