Step 3: Mapping Your Legacy Data to an Identity Cloud User Profile Schema

Although there might be some exceptions, any data currently stored in your legacy system can be migrated to your Identity Cloud user profile. The one catch is that each field in your legacy system must map directly to an attribute in the appropriate Akamai entity type. For example, suppose you have the following set of legacy data fields:

Legacy Field Name

Datatype

First Name

String

Last Name

String

Display Name

String

Email Address

String

Cell Phone Number

String

Newsletter Subscriber

Boolean

In order to copy this data to an Identity Cloud entity type (for example, to the useentity type) you must make sure that there’s a user profile attribute for each legacy field. In many cases, that will be easy:

Legacy Field Name

Akamai Attribute

First Name

givenName

Last Name

familyName

Display Name

displayName

Email Address

email

Cell Phone Number

primaryAddress.mobile

Newsletter Subscriber

 

Like we said, in many cases that’s going to be easy. However, there will be exceptions. As you can see in the preceding table, the first five fields in the legacy system correspond directly to an Identity Cloud attribute: the First Name field is the same as the givenName attribute; the Last Name field is the same as the familyName attribute; and so on. All of that data can be migrated without any problem.

Things are a little different when it comes to the Newsletter Subscriber field, however: by default, the user schema doesn’t have an attribute that directly aligns with Newsletter Subscriber. And without a matching attribute there’s no way to import the data.

That leaves you with three choices:

  • Don’t import the Newsletter Subscriber field. That’s the easiest way to work around the problem, but it also means losing all the Newsletter Subscriber data. Considering the fact that you planned on importing this field in the first place, it’s probably safe to assume that you don’t want to lose that data.
     
  • Match the Newsletter Subscriber field with an Identity Cloud attribute you don’t plan on using. Your Akamai schemas are yours: you can use them however you see fit. Because of that, you could map Newsletter Subscriber to any attribute you choose. Not planning on using the aboutMe attribute? Then you could store your newsletter data in the aboutMe attribute.

    Although that works (at least from a technical standpoint), we don’t recommend it. For one thing, you would then have data that, on the surface, makes no sense: anyone looking at the aboutMe attribute would see unexpected values like true/false or yes/no. That’s guaranteed to cause confusion. In addition to that, what happens if you decide to use aboutMe after all? Do you now store aboutMe data in, say, the middleName attribute? If you go this route, you’re asking for trouble, sooner or later.

Instead, your best bet is to go with a third option: add a new attribute to your schema, one that does map directly to the Newsletter Subscriber field. As it turns out, you can easily add attributes to a schema simply by calling the entityType.addAttribute endpoint. For example:


curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode attr_def='\
{"name":"newsletterSubscriber","type":"boolean","description":"Indicates whether the user subscribes to 
the company newsletter"}'\
    https://education-jncenter.janraincapture.com/entityType.addAttribute

The preceding Curl command does three things:

  • Adds an attribute named newsletterSubscriber to the user entity type.
  • Sets the datatype of the new attribute to Boolean.
  • Adds a brief description (Indicates whether the user subscribes to the company newsletter) to the attribute.

If you run this command and then view the user entity type schema in the Console, you’ll see this entry:

Best of all, now you can map each of your legacy data fields to a user profile attribute:

Legacy Field Name

Akamai Attribute

First Name

givenName

Last Name

familyName

Display Name

displayName

Email Address

email

Cell Phone Number

primaryAddress.mobile

Newsletter Subscriber

newsletterSubscriber

That’s a good question. The original field – Newsletter Subscriber– uses the Boolean datatype, and the new attribute we created – newsletterSubscriber– also uses the Boolean datatype. Should each field have the same datatype as its Akamai counterpart?

Ideally yes: having the same datatype will typically make the migration process simpler and smoother. Admittedly, you can sometimes get away with using different datatypes: during a migration, the value true can easily be migrated from a string field to a Boolean attribute. In other cases, however, that approach won’t work: there’s no way to stuff a string value like July 12, 1967 into a date attribute. Trying to do that is a sure-fire recipe for failure.

Note. Well, unless you use a data transformation, which we talk about here.

The moral of the story is this: try to match your datatypes as best you can.

When mapping your datafile to an Akamai user profile schema you should also make sure that the datafile includes all the required Akamai Identity Cloud attributes. For example, displayName is a required attribute. If you don’t include the display name a user’s record can still be copied over and the user can still log on. However, when users without a display name try to update their user profile, they’ll be prompted (and required) to enter a display name:

If you have questions about which attributes are (and aren’t) required, contact your Akamai representative. Required attributes will vary depending on such things as your Akamai schema or your Akamai flow.