Map legacy data to a 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 NameData type
First Namestring
Last Namestring
Display Namestring
Email Addressstring
Cell Phone Numberstring
Newsletter Subscriberboolean

In order to copy this data to an Identity Cloud entity type (for example, to the user entity 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 NameAkamai Attribute
First NamegivenName
Last NamefamilyName
Display NamedisplayName
Email Addressemail
Cell Phone
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, starting with these two:

  • 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 the latter approach 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"}'\

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 NameAkamai Attribute
First NamegivenName
Last NamefamilyName
Display NamedisplayName
Email Addressemail
Cell Phone
Newsletter SubscribernewsletterSubscriber

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.


Well, unless you use a data transformation, which we talk about in Create data transformations.

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.