Guide

Modify display attributes

Suggest Edits

When you log on to the Console, the first thing you see is the Manage Profiles page. By default, the bottom of the page displays all of your user profiles:

Although all the user profiles are displayed (note that you might have to page through the list to actually view them all), the search results do not show all the information available for each profile. Instead, values for the following six attributes are shown:

  • First Name (givenName)
  • Last Name (familyName)
  • Email (email)
  • Phone (primaryAddress.phone)
  • Birthday (birthday)
  • Created (created)

Why those six attributes? As it turns out, those are the six attributes specified, by default, in the user_search_display_fields API client setting:

[{"name": "givenName", "title": "First Name"}, {"name": "familyName", "title": "Last Name"}, {"name": "email", "title": "Email"}, 
{"name": "primaryAddress.phone", "title": "Phone"}, {"name": "birthday", "title": "Birthday"}, {"name": "created", "title": "Created"}]

📘

Technically, the name of this setting is user_search_display_fields only if you are referencing the user entity type. If you are working with a different entity type then you need to replace user with the appropriate entity type name. For example, suppose you have a custom entity type named employees. In that case, the setting name would be employees_search_display_fields.


These six attributes are used as the default search display fields even if the user_search_display_fields setting is not explicitly configured. (And, by default, the setting is not explicitly configured.) If you want to change the attributes displayed on the Manage Profiles page, you’ll need to create and then configure that setting using either the Clients and Settings API or the Capture Dashboard.


📘

What if you configure and then later delete this setting? That’s fine: in that case, the Console reverts to using the original six display fields.


The user_search_display_fields setting defines the attributes to be displayed by using the properties name and title. For example:

{"name": "givenName", "title": "First Name"}

The name property is the schema name of the attribute to be displayed; you must use correct casing when referencing the attribute name. For example, entering givenName as GivenName will prevent the attribute from being displayed; that’s because, technically, there is no attribute named GivenName. Letter casing is extremely important when specifying attribute names.

The title property (used as the column header in the search results) is a bit more free-form: you can set the title to First Name, Given Name, User Name, or anything else you want to set it to. (And using any letter casing you want: set the title to FIrsTNaME and the title will be displayed as, well, FIrsTNaME.) You can even configure all the title names to be something totally meaningless:

[{"name": "givenName", "title": "AAAAA"}, {"name": "familyName", "title": "BBBBB"}, {"name": "email", "title": "CCCCC"}, 
{"name": "primaryAddress.phone", "title": "DDDDD"}, {"name": "birthday", "title": "EEEEE"}, {"name": "created", "title": "FFFFF}]

That might be a silly thing to do, but it works:

In other words, titles, and how they are referenced, are entirely up to you. Attribute names are not entirely up to you.

You can also modify the order in which attributes are displayed in the search results list. By default the first attribute shown in the search results is the user’s first name (his or her givenName). Why? Because that’s the first attribute listed in the user_search_display_fields setting:

[{"name": "givenName", "title": "First Name"}, {"name": "familyName", "title": "Last Name"}, {"name": "email", "title": "Email"}, 
{"name": "primaryAddress.phone", "title": "Phone"}, {"name": "birthday", "title": "Birthday"}, {"name": "created", "title": "Created}]

Would you rather have users listed by last name and then by first name? That’s fine; just swap the order of the two attributes in the setting:

[{"name": "familyName", "title": "Last Name"}, {"name": "givenName", "title": "First Name"}, {"name": "email", "title": "Email"}, 
{"name": "primaryAddress.phone", "title": "Phone"}, {"name": "birthday", "title": "Birthday"}, {"name": "created", "title": "Created}]

Of course, what you’re probably most interested in is this: changing the attribute values that are actually displayed in the search results. For example, by default the account creation date is one of those default attributes. But suppose the created attribute isn’t all that important to you, suppose you’d find it more useful to see the state that the user lives in. How can you change the set of displayed attributes to display the user’s state rather than his or her account creation date?

As it turns out, that’s pretty easy: all you need to do is modify the user_search_display_fields setting, swapping the primaryAddress.stateAbbreviation attribute for the created attribute. One way to do that is to use the Capture Dashboard. (You can also do this using the settings APIs.) To use the Capture Dashboard to change the displayed attributes, complete the following procedure:

  1. Open the Capture Dashboard and then click Settings.

  2. On the Settings page, click the Default Settings to add a new setting.

  3. The new setting initially consists of a pair of empty fields. In the first field, type the setting name user_search_display_fields.

  4. In the second field, paste the default value for the setting:

[{"name": "givenName", "title": "First Name"}, {"name": "familyName", "title": "Last Name"}, {"name": "email", "title": "Email"}, 
    {"name": "primaryAddress.phone", "title": "Phone"}, {"name": "birthday", "title": "Birthday"}, {"name": "created", "title": "Created}]
  1. Click Save, and the new setting (and its default values) will be added to the Default Settings section.

📘

Does the user_search_display_fields setting have to be added to the Default Settings section? Yes. Even if you have multiple clients, all clients must use the same search display attributes: you cannot configure different display attributes for Client A than you configure for Client B. (Well, unless the two clients use different entity types.)


Up to this point we haven’t accomplished much: our search results still show the same six default display attributes. However, we now have a way to modify those attributes. To do that, complete this procedure:

  1. In the Capture Dashboard, click anywhere on the user_search_display_fields setting to put the setting into Edit mode.

  2. In the attribute value, select and delete {“name”: “created”, “title”: “Created} (be sure that you don’t delete the ] at the end of the value).

  3. In the newly-created space within the value, type {“name”: “primaryAddress.stateAbbreviation”, “title”: "State"}and then click Save.

Your user_search_display_fields setting should now look like this, with the primaryAddress.stateAbbreviation attribute replacing the created attribute:

[{"name": "givenName", "title": "First Name"}, {"name": "familyName", "title": "Last Name"}, {"name": "email", "title": "Email"}, 

{"name": "primaryAddress.phone", "title": "Phone"}, {"name": "birthday", "title": "Birthday"}, 
{"name": "primaryAddress.stateAbbreviation", "title": "State"}]

After saving your changes, allow a few minutes for the modifications to take effect (Console settings are cached for approximately 10 minutes). When the Console screen refreshes, your Manage Profiles page should look similar to this:

As you can see, the created attribute has been replaced by the primaryAddress.stateAbbreviation attribute.

Incidentally, you aren’t limited to six attributes. For example, suppose you’d like to see the city that the user lives in, but you don’t want to replace any of the other displayed attributes. That’s fine: just add the city to the list of displayed attributes:

[{"name": "givenName", "title": "First Name"}, {"name": "familyName", "title": "Last Name"}, {"name": "email", "title": "Email"}, 
{"name": "primaryAddress.phone", "title": "Phone"}, {"name": "birthday", "title": "Birthday"}, 
{"name": "primaryAddress.city", "title": "City"}, {"name": "primaryAddress.stateAbbreviation", "title": "State"}]

Save your changes, and, as before, wait 10 minutes or so. As soon as the Console settings are refreshed, you’ll have seven attributes in your user search results.

Just remember that, even though you can add any attribute to the search display, you still can’t search on those attributes (or sort on those attributes) until they have been indexed. (Displaying attributes and indexing attributes are two different operations.)

Updated almost 2 years ago