Restrict agent activity by profile type

The Console gives you the ability to restrict agents holding the CCP Agent or CCP Agent – Update Only role to managing a limited set of user profiles; for example, you could give an agent access only to profiles from users who live in Oregon. This is done by modifying the API client settings user_distinguisher_field and user_distinguisher_field_values.

📘

The user_distinguisher_field and user_distinguisher_field_values settings are configured per entity type. That means that the preceding names apply only to the user entity type. For example, suppose you have an entity type named customers. In that case, the setting names would be customers_distinguisher_field and customer_distinguisher_field_values. For the sake of simplicity, this discussion will refer to user_distinguisher_field and user_distinguisher_field_values. Just remember that those names apply only to the user entity type.

Before implementing user profile restrictions, keep in mind that:

• You can only limit access based on the value of a single attribute. For example, you can limit an agent to accessing profiles from a specific city by setting the user_distinguisher_field setting to primaryAddress.city. Alternatively, you can limit an agent to accessing profiles from a specific state by setting the user_distinguisher_field setting to primaryAddress.stateAbbreviation. But how do you limit access to a particular city in a particular state (for example, allowing an agent to access profiles from Portland, OR but not from Portland, ME)? You can’t: you can limit access to a city or to a state (one attribute), but you cannot limit access to a city and a state (multiple attributes).

• The attribute specified in the user_distinguisher_field setting must be an indexed attribute ; if it’s not, the agent won’t have access to any profiles. If you want to, say, limit access to a particular state, then make sure you index the primaryAddress.stateAbbreviation attribute before doing so.

• The user_distinguisher_field applies to all API clients that are associated with the user entity type. If you decide to restrict authorization based on country, then that restriction is applied to all API clients for the user entity type. You cannot restrict authorization by country for Client A, then restrict authorization based on city or state for Client B (assuming that both clients are associated with the same entity type).

However, you can configure different settings for clients that are based on different entity types. Suppose Client A employs the user entity type while Client B employs a different entity type, one named customers. Because user restrictions are set on a per-entity type basis, you can set Client A to filter users by country and Client B to filter users by state. The net result? The two clients will filter on different attributes. However, this happens only because the two clients do not share an entity type. If you added the customers entity type to Client A, then – for that entity type – both clients will have to filter on the same attribute.

You can use either API calls or the Console to modify the user_distinguisher_field and the user_distinguisher_field_values settings. To use the Console to change these settings, log on and complete the following steps:

1. From any page in the Console, click Manage Application.

2. From the Manage Application page, click Edit Settings.

3. On the Edit Settings page, click the Add Settings icon to add a new, blank setting.

4. Click Select settings key and then, from the dropdown list, select the distinguisher_field setting for the desired entity type (for example, user_distinguisher_field).

5. In the Value field, select the schema attribute you want to use for restricting access (for example, primaryAddress.country).

6. Click Save Changes to add the new setting.

After configuring the distinguisher field setting, you must specify one or more values used for limiting access. For example, suppose you want to limit agent access to profiles from the US, Canada, and/or Mexico. In that case, you must configure the user_distinguisher_field_values setting to the following, specifying the name of each country:

["US", "CA", "MX"]

📘

The preceding example assumes you have stored country information by using country codes. If you store country information by country name, you need to specify those names when configuring the user_distinguisher_field_values setting:

["United States", "Canada", "Mexico"] 

The value entered for the user_distinguisher_field_values setting must be exact matches for the values stored in the database.

The square brackets in the preceding example indicate an array; that means that you can include one or more values in the setting. Individual values (such as US) are enclosed in double quotes, and values must be separated by using commas. We should probably mention that the square brackets and double quotes are required even if you only specify a single option:

["US"]

To add additional countries, type a comma followed by the country name enclosed within double quotes:

["US", "CA", "MX", "FR"]

Etc.

📘

Suppose you limit an agent to the four countries shown in the preceding example. Now, suppose you get a new set of user profiles for Italy, a country not listed in the user_distinguisher_field_values setting. Will the agent have access to these new profiles?

No; agents can only access the profiles explicitly assigned to them. To give the agent access to profiles from the new country (Italy), you must update the user_distinguisher_field_values setting to include the country code for Italy (IT) and then give the agent access to those profiles. (Alternatively, of course, you could give the agent full access, which allows him or her to manage all user profiles.)

Here’s the procedure for configuring the user_distinguisher_field_values setting:

1. On the Edit Settings page, click the Add Settings icon to add a new, blank setting.

2. Click Select settings key and then, from the dropdown list, select the distinguisher_field_values  setting for the desired entity type (for example, user_distinguisher_field_values).

3. In the Values field, enter the values you want to use as distinguishers.

4. Click Save Changes to add the new setting.

So what did that accomplish? To answer that question, let’s create a new agent and assign him or her a restricted set of profiles. To give a user access to a specific profile (or set of profiles), simply check the appropriate boxes. For example, to give a user access to profiles from Canada and Mexico, but not from the US, select CA and MX, but leave US unchecked:

After you enter an email address and click Save, the new agent can log on to the Console. When they do so, he or she will only see (and be able to manage) profiles from Canada and Mexico:

If you later decide to give this agent access to all the user profiles, just click the agent’s name on the Manage Agents page and then, on the Edit Agent page, change their access permissions to Full Access.

And what if you want to add or remove countries from the list? No problem: just go back into the Capture Dashboard and adjust the value of the user_distinguisher_field_values setting as needed:

["US", "CA", "MX", "FR", "IT", "CN", "BR", "JP", "ZA"]