Jump to: navigation, search

Contact Identification

Client applications submit requests to UCS to identify contacts. UCS takes the contact data provided to the identify request (OMContacts/Identify) and tries to match it with its existing contact records based on certain attributes.

Attributes Provided

The attributes of the request OMContacts/Identify are the following:

  • DatePattern—Defines how dates are formatted in the following attributes.
  • CreateContact—Allows the creation of a new Contact if none was found.
  • TenantId—The tenant where the Contact is to be found or created.
  • SubscriberId—The subtenant where the Contact is to be found or created.
  • MediaType—Defines how the contact should be identified, and what attributes are to be expected.
  • <Contact Attribute>—The parameters that will be used to find or create the contact.

Contact Creation

The identify request provides a media and several contact attributes.

  • Contact identification is based on lookups.
  • Lookups are specified per media.
  • Lookups can be customized per media.
  • If identification request has no media specified the media any is used.
  • Default lookups are preconfigured for media any.
  • When media has no custom lookups, the default ones are used (the same lookups as media any).
  • As UCS allows multiple contacts with the same attributes (for example multiple contacts sharing the same email address), the default lookups are non unique.
  • If CreateContact is set to true and the mandatory attributes are provided, then UCS searches for the contact in lookups related to the attributes from the identification request.
  • If the contact is not found, it is created. Then the ID of the newly created contact is returned.
  • If the contact is found, then the related ID is returned.
  • If CreateContact is set to false, then UCS does not try to create the contact, but rather tries to identify it according to the selected lookup tables.
  • By default, CreateContact is true.
  • Creation of contact can be disabled for a media. If the option create-contact in section settings in the Annex tab of the media is set to false, UCS will perform identification only (no creation) for this media. This behavior is overridden if create-contact with value true is provided in the identification request.
  • Creation of a contact can be allowed for a media only if a few mandatory attributes are present in the identification request. A comma-separated list of mandatory attributes must be set in the option minimum-creation-attributes in section settings in the Annex tab of the media. Example:
     
    minimum-creation-attributes=EmailAddress,LastName.

Identification Strategies

An identification strategy is a list of lookup tables applications use to identify a contact.

The identification strategy primarily depends on the media. For example, when receiving a phone call, the application probably wants to identify the contact with the caller phone number. However, the application that receives an email will rather use the From: address.

  • The default strategy for email is EmailAddressLookup.
  • The default strategy for voice is PhoneNumberLookup.
  • There is no default strategy for SMS. A typical strategy is PhoneNumberLookup, EmailAddressLookup.

Configuring Identification Strategies

The list of lookup tables is defined for each tenant in the corresponding Media Type Business Attribute. The media any defines the default lookup list, and each media (email, chat,...) defines its own lookup list.

In the Annex tab of the media, under the section settings, the option names are identify-contact-1, identify-contact-2, identify-contact-n .

The value can be either the name of an existing lookup or a list of contact attributes separated with comma.

  • If the value is EmailAddress, then the existing EmailAddressLastNameFirstNameLookup will be used.
  • If the value is _facebookId, then UCS will create a custom lookup at first startup, with the condition that the _facebookId attribute is unique across all the contacts.

There are a number of predefined lookups (see Default Lookups).

Lookup Table

A lookup table indexes contacts, according to one or more attributes.

FacebookIdLookup and TwitterIdLookup have a key made of only one attribute (FacebookId and TwitterId respectively), but it is possible to configure a lookup with a composite key—for example (PhoneNumber + FirstName) if different people are using the same phone line and need to be tracked separately.

The lookup tables must be created prior to starting UCS, and cannot be dynamically modified.

Unique, Multiple, and Regular Lookups

UCS defines:

  • Unique lookups, where a given key corresponds to a single item.
  • Multiple lookups, where a given key can be associated with multiple values.
  • Regular lookups, where a given key can be associated with a single item, but which allows other values when secondary keys are provided.

If a multiple lookup is selected, UCS returns the first result. In this case only, the result parameter NumberOfContactsFound can be greater than 1. You must expect unpredictable results if the lookup is not sorted. If no contact is found, no contact will be created and the parameter CreateContact is ignored.

EmailAddressLastNameFirstNameLookup and PhoneNumberLastNameFirstNameLookup are regular lookups because they can be searched with predictable results by providing the EmailAddress or the PhoneNumber alone. However, they can also be searched with unpredictable and possibly different results when providing optional parameters LastName and FirstName.

Default Lookups

The default behavior of UCS 9 provides a similar default identification algorithm as UCS 8.x. To achieve this, some lookups are configured by default.

  • The following are defined as regular lookups:
    • EmailAddressLastNameFirstNameLookup—A non-unique lookup on the Contact’s EmailAddress, LastName, and FirstName parameters.
    • PhoneNumberLastNameFirstNameLookup —A non-unique lookup on the Contact’s PhoneNumber, LastName, and FirstName parameters.
  • The following are defined as multiple lookups:
    • LastNameFirstNameLookup—A multiple lookup on the Contact’s FirstName and LastName parameters.
    • FirstNameLookup—A multiple lookup on the Contact’s FirstName parameter.

The default value for the default media any is hard-coded to:

EmailAddressLastNameFirstNameLookup, PhoneNumberLastNameFirstNameLookup,  
LastNameFirstNameLookup, FirstNameLookup.

Unless otherwise configured, and whatever the media, the contact is always identified:

  1. First by email address.
  2. Then by phone number.
  3. Then by last name plus first name, or last name only.
  4. Finally by first name only.

Custom Lookups

Users can configure their own lookups.

Lookups can be created in the configuration by adding options on the media. Then new lookups will be created in the database at the next UCS restart. Only unique lookups can be created this way (see Configuring Customization on Media).

Alternatively, the definition can be provided in a file whose location is specified by a configuration option. Unique, Multiple and Regular lookups can be created this way (see Customization Provided in File).

Configuring Customization on Media

The list of lookups must be defined for each tenant in the corresponding Media Type Business Attribute in the Annex of the media, under the section settings. As described in above, the option names are identify-contact-1, identify-contact-2, identify-contact-n and so on, and the value can be either the name of an existing lookup or a comma-separated list of contact attributes.

  • If the value is EmailAddress, then the existing EmailAddressLookup will be used. If the value is _facebookId, then UCS will create a custom lookup at first startup, with the condition that the _facebookId attribute is unique across all the contacts.
  • If the value is CustomId, then UCS will create a custom lookup at first startup, with the condition that the CustomId attribute is unique across all the contacts.

Customization Provided in File

The definition of lookups uses a JSON syntax.

For example the syntax for the EmailAddressLastNameFirstNameLookup is the following :

{
  "name": "EmailAddressLastNameFirstNameLookup",
  "type": "lookup",
  "lookup_type": "regular",
  "source": "Contact",
  "attributes": [
    {
      "name": "TenantId",
      "type": "int",
      "cipher": "none",
      "sensitive": false,
      "mandatory": true,
      "static": false,
      "columntype": "partitionKey"
    },
    {
      "name": "Segment",
      "type": "text",
      "cipher": "none",
      "sensitive": false,
      "mandatory": true,
      "static": false,
      "columntype": "partitionKey"
    },
    {
      "name": "EmailAddress",
      "type": "text",
      "cipher": "none",
      "sensitive": true,
      "casesensitive": false,
      "mandatory": true,
      "static": false,
      "columntype": "partitionKey",
      "infield": "Attributes",
      "columnsource": "name",
      "columnvalue": "StrValue"
    },
    {
      "name": "LastName",
      "type": "text",
      "cipher": "none",
      "sensitive": true,
      "casesensitive": false,
      "mandatory": false,
      "default": "",
      "static": false,
      "columntype": "clusteringKey",
      "infield": "Attributes",
      "columnsource": "name",
      "columnvalue": "StrValue"
    },
    {
      "name": "FirstName",
      "type": "text",
      "cipher": "none",
      "sensitive": true,
      "casesensitive": false,
      "mandatory": false,
      "default": "",
      "static": false,
      "columntype": "clusteringKey",
      "infield": "Attributes",
      "columnsource": "name",
      "columnvalue": "StrValue"
    },
    {
      "name": "Id",
      "type": "text",
      "cipher": "none",
      "sensitive": false,
      "mandatory": true,
      "static": false
    }
  ]
}
  • Any new JSON definition of lookup must be saved in a file having the name of the lookup and the .json extension.
  • The location for this file must be specified in the option scripts in the schema section of the UCS Application that was used to create the schema (the one with the value of the manage option set to true). The default value is ./scripts/ (which means folder scripts in the UCS installation folder).

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on May 28, 2018, at 20:31.