Managing Agents

In the Janrain Console, “agents” are users who have administrative rights to the Console: depending on their roles, agents might be able to search for user profiles; they might be able to create or delete user profiles; they might be able to view schema information; they might even be able to manage other agents. Agents and agent roles are roughly analogous to the roles found on the People page in the Capture Dashboard. As you’ll see, however, the duties assigned to Console agents, and the way that you assign and manage Console agents, differs considerably from their Capture Dashboard counterparts.

The agent management section of the Console documentation includes the following topics:

Accessing the Manage Agents Page

To access the Manage Agents page, the jumping-off point for agent management activities, click Manage Agents in the Console navigation pane:

 The Manage Agents Link

That seems easy enough, and it is. But what if you don’t actually see the Manage Agents link? That means that you don’t have a role that grants you access to agent information: the Manage Agents page is only available to users holding the Administrator or the CCP Agent Manager role. See the following topics for detailed information about Console roles:

Note. Is there an easy way default way to verify your role after you’ve logged on? Yes, there is. To verify your role, just click the agent profile button in the upper right corner of the screen, and then click your name:

 The Agent Profile Dropdown

The displayed agent profile will include your assigned role:

 Viewing Your Assigned Console Role

For those of you who can access the Manage Agents page, you should see something similar to this:

 Agents on the Manage Agents Page

From here you can do such things as search for agents; create new agents; modify or delete existing agents; and export data about all of your agents.

See Also

Console Roles and Permissions

The Janrain Console uses roles to determine the activities that users can (or cannot) carry out within the Console. Before users can perform management activities of any kind, these users must be assigned a role; technically, a user not assigned a role can log on to the Console, but the only thing he or she will see upon doing so is this:

 Logging on Without a Console Role

The Janrain Console currently employs four different roles:

Before putting together your agent infrastructure, you should have a clear understanding of the permissions granted to each of these four roles. In addition, you should familiarize yourself with the following two topics:

See Also


Administrators have full control over everything that can be done in the Janrain Console. For example, Administrators have complete access to user profiles: they can create, delete, and modify user profiles; export audit data; send out email verifications or password reset notices; etc. Administrators (and only Administrators) can access the Manage Schemas page. Along with CCP Agent Managers, Administrators can also can access the Manage Agents pages. From there, Administrators can create and delete agent roles, and can change the access permissions for any user.

Note. With one exception: an Administrator cannot modify his or her role or set of permissions. That prevents you from inadvertently losing permissions or locking yourself out of the Console.

See Also

CCP Agent Manager

CCP Agent Managers have full access to user profiles from the Manage Profiles page: they can create, delete, and modify user profiles; export audit data; send out email verification or password reset notices; and so on. In addition, Agent Managers have access to the Manage Agents page. CCP Agent Managers can create and delete agents; search for agents; and assign permissions and roles. However, Agent Managers do not have access to the Manage Schemas page.

Note. Similar to Administrators, Agent Managers can assign roles to other users, and can remove other agents from their roles. However, an Agent Manager cannot modify his or her role or set of permissions.

See Also

CCP Agent

CCP Agents have full access to user profiles: they can search for and modify user profiles, and can create and delete profiles. CCP Agents can also export audit data for individual profiles and send out email verification or password reset notices. However, they do not have access to agent or schema information.

See Also

CCP Agent Update Only

Users with the CCP Agent - Update Only role can search for and modify user profiles, and can export audit data for a profile. However, Update Only agents cannot create or delete profiles. In addition, Update Only agents cannot view or manage agents and agent permissions, or access schemas.

See Also

Profile Access Filters

By default, every Console agent has access to each and every user profile. However, you can place some restrictions on the profiles that an individual agent can and cannot access. To view these options, from the Manage Agents page click Create Agent. On the Create Agent page, select either CCP Agent or CCP Agent – Update Only and then scroll to the bottom of the page. There, you’ll see your entity types and the type of access you can grant to those entities:

Entity Type Access Levels

Full Access is exactly what the name implies: the user has access to all the profiles for the entity type. This is the default setting for all agents.

Blocked access means that the user cannot access any of the profiles for this entity type. If you have one entity type and you block the agent, that agent will not be able to access any user profile. But suppose you have two entity types (for example, users and employees). If you block the agent from the user entity type, he or she will still be able to access profiles that use the employees entity. To prevent the agent from accessing any user profile, you will need to block the agent from both users and employees.

Limited Access, which appears only if you have configured the user distingisher field setting. Under the Limited Access heading you’ll see the friendly name of the attribute you configured as your user distinguisher field (e.g., Country). If you click Distinguisher values, the country values that you configured appear in a dropdown list:

The Only Allowed For Access Level

The Only Allowed For filter is explained in more detail in the next section of this documentation.

See Also

Restricting Agent Activity by Profile Type

The Janrain 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.

Note. 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 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 Capture Dashboard to modify the user_distinguisher_field and the user_distinguisher_field_values settings. To use the Capture Dashboard to change these settings, log on and complete the following steps:

  1. From the Janrain Dashboard home page, click the Manage Capture Dashboard icon.
  2. From the Capture Dashboard, click Settings.
  3. On the Settings page, click the Default Settings label. A pair of empty text fields appears on the screen.
  4. In the first field, type the setting name: user_distinguisher_field.
  5. In the second field, type the name of the attribute to be used for restricting profile access. For example, to restrict access based on country, type
  6. Click Save 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"]

Note. 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:


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

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


Note. 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 Capture Dashboard Settings page, click Default Settings. A pair of empty text fields appears on the screen.
  2. In the first field, type the setting name: user_distinguisher_field_values.
  3. In the second field, enter the restriction values. For example, to limit agent access to profiles from the US, Canada, and/or Mexico type this: [“US”, “CA”, “MX”].
  4. Click Save 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:

User Field Distinguisher Values

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:

Viewing a Limited Set of Profiles

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"]

See Also

Console Roles and Janrain Dashboard Permissions

Eventually, the Janrain Console will subsume all the capabilities of the Janrain Dashboard. Until that happens, organizations will need to use both the Console and the Dashboard to manage their Janrain implementation. For example, at this point in time social logon providers can only be configured and deployed by using the Dashboard; that capability has not been added to the Console yet.

On the other hand, full user search capabilities only appear in the Console; the Dashboard has only a limited ability to filter user records. As noted, that means that, for now, you need both the Dashboard and the Console. In turn, that makes it important to understand the relationship between the management roles used in the Console and the management permissions used in the Janrain Dashboard.

When it comes to the Engage Dashboard, it’s easy to explain its relationship to the Janrain Console: there isn’t one. A user can have full access rights to the Engage Dashboard, yet have no access rights to the Console. Likewise, a user can hold, say, the CCP Agent Manager role in the Console, yet not be able to access the Engage Dashboard. Engage Dashboard permissions and Console permissions are separate and distinct, primarily because there is currently little overlap between the tools.

That’s not the case when it comes to the Capture Dashboard, however. Instead, and as you’ll see, the relationship between the Console and the Capture Dashboard is like many other relationships: it’s complicated.

But don’t worry: we’re about to explain exactly how this relationship works, and what it means to you.

For starters, let’s point out that any time you create an agent in the Console a corresponding set of permissions is automatically added to the Capture Dashboard:

If you assign this role in the Console … … the user is assigned this role in the Capture Dashboard
Administrator admin
CCP Agent Manager ccp_agent_manager
CCP Agent ccp_agent
CCP Agent – Update Only ccp_agent_update_only

You’re probably familiar with the Capture Dashboard’s admin permissions, which give you full administrative rights to the Capture Dashboard. The other permissions are new, but are effectively meaningless: users with these permissions can log on to the Capture Dashboard, but that’s about it: they can’t do anything after logging on. Which makes sense: the corresponding Console roles only allow the user to manage user profiles, and the Capture Dashboard does not let you restrict a user to profile management and nothing but profile management.

So far that’s pretty straightforward. Be forewarned, however: this is where things start to get a little more complicated. For example, suppose Toni Ng is a CCP Agent, and suppose she holds the corresponding ccp_agent role in the Capture Dashboard. Let’s say we want to give Toni the right to perform a few management tasks in the Capture Dashboard. With that in mind, we give her operations permissions in the Dashboard:

 Assigning Capture Dashboard Permissions

Toni now has the ability to carry out a prescribed set of Dashboard tasks. But look what happened to Toni’s account in the Console:

 Agent Account has been Deleted

If you don’t see Toni’s account anywhere, that’s the point: Toni no longer is an agent. If you change a user’s permissions in the Capture Dashboard to anything other than admin, that user no longer appears in the list of Console agents. That’s because the Console only recognizes the Capture Dashboard’s admin role: all other roles are ignored. If Toni tries to log on to the Console she’ll be greeted with this:

 User No Longer has a Console Role

The takeaway? Changing permissions in the Capture Dashboard (or at least changing the role to anything other than admin) deletes the user’s role in the Console.

But wait: there’s more. Suppose we give Toni Capture Dashboard admin permissions instead of operations permissions:

 Adding Capture Dashboard admin Permissions

Here’s what happens when we do that:

 Agent Role has been Restored

Yes, Toni’s agent account is back, except now she’s an Admin.

And what if you decide to delete Toni’s Admin account? As it turns out, you can’t: you cannot delete an agent account if that agent is an admin in the Capture Dashboard. Instead, the only way to delete a Console Administrator is to delete his or her account (or change his or her permissions) in the Capture Dashboard. For example, if we assign Toni operations permissions in the Capture Dashboard, then her Console admin account will automatically be deleted. Admittedly, that’s not the most intuitive procedure in the world, but it works.

Oh, and keep in mind that this is only in the short-term: as more and more functionality is moved from the Capture Dashboard to the Console, these backward-compatibility issues will disappear.

So what does all this mean? Here’s a summary of the key points:

  • It can be tricky – at best – to allow someone to use both the Console and the Capture Dashboard. (Unless, you’re OK with them being both a Console Admin and a Capture Dashboard admin.) After all, if you give a user admin permissions in the Capture Dashboard, there is no way to prevent them from also being granted the Admin role in the Console.

  • But what if you want someone to have a Console role but only have reports permissions in the Capture Dashboard? To be honest, there’s no straightforward way to do that. The best you can do, for now, is have them use two different email accounts for admin purposes: one account for logging on to the Console, the other for logging on to the Capture Dashboard.

  • As a best practice suggestion, try to divide your workloads and responsibilities so that some operations personnel use only the Console while others use only the Capture Dashboard. That’s not necessarily a great answer, but it’s the best answer we have for now.

See Also

Agent Groups

When it comes to Console agents, what’s good for the goose isn’t necessarily good for the gander. For example, by default all agents see the exact same fields any time they conduct a user search; that means that everyone who runs a Console search sees results similar to these:

Default Search Results

Of course, you can modify which attributes are displayed in the search results; for example, instead of the default values (givenName, familyName, email,, birthday, and created) you can show a completely different set of attributes:

Alternate Search Results

That’s up to you.

The point is that, regardless of which attributes you display in the search results, by default each agent who logs on to the Console will see those same attributes. For example, suppose you replace the displayName attribute with the attribute. In that case, all of your agents will see the new attribute in their search results. One for all, and all for one.

So is that a problem, the fact that all your agents see the same fields when conducting a search? Well, it might not be a problem, but it might not be ideal, either. To go back to the goose/gander analogy, there’s a good chance that different agents in your organization have different jobs and different responsibilities. Because of that, it might be better if those agents saw different attributes in their search results.

For example, suppose you’re an agent who only works with profiles for US residents. In a case like that, seeing a column labeled Country is superfluous: based on your role, the only profiles you can access are profiles from the US. Seeing the primaryAddress.Country attribute doesn’t add much value; after all, every single entry in that column is going to read exactly the same:

US-only Search Results

In other words, seeing a different attribute – maybe, or primaryAddress.state – would probably be more useful than seeing an unending string of the exact same value.

So is there anything you can do about this? Well, now that you mention it, there is: you can assign agents to groups, then specify a different set of search result attributes for each group. For example, agents in Group A might see the following fields when they do a user profile search:

Alternate Search Results

Meanwhile, agents in Group B might see a different set of fields:

Alternate Search Results

The difference in the search result fields has nothing to do with the role held by an individual agent. Instead, the difference is dictated by the group that the agent belongs to.

Configuring Agent Groups and Assigning Group Membership

Before we go any further we need to mention that, at this point in time, agent groups must be created by Janrain (in the future, you will probably be able to create your own groups). If you want to implement agent groups, start by contacting your Janrain representative, and provide them with the following information:

  • The name of each group (you can have multiple groups, with each group associated with a different set of search display attributes).
  • The entity type (e.g., user) associated with the group. Groups can only be associated with one entity type.
  • The attributes you want to display (for example,
  • The title for each search result column. For example, you might want to label the primaryAddress.address1 column Street Address:
    Customizing a Column Name

In other words, you must supply data similar to this in order to create a group called North American Agents:

Property Data
Group name North American Agents
Entity type user
Displayed attributes givenName; familyName;;; created; login
Column names First Name; Last Name; Country; Phone No.; Registration Date; Last Login date

After your groups have been created, you’ll see a new Groups section any time you access the Create Agent or the Edit Agent pages:

Selecting an Agent Group

To assign an agent to a group, open the agent account and then complete this simple procedure:

  1. Select the group you want to assign the agent to.
  2. Save the agent profile.

If you change your mind later on, simply repeat this procedure, selecting None as the agent group and then saving the agent profile.

Note. By default, agents can only be assigned to a single group. However, in some cases, it might be possible to assign a single agent to multiple groups. For more information, contact your Janrain representative.

There are at least two things to keep in mind when working with agent groups:

  1. Agent groups only dictate the attributes displayed in the search results; they do not determine the profiles that an agent has access to. For example, you can use agent groups to prevent an agent from seeing the primaryAddress.Country attribute in the search results; however, you cannot use groups to prevent an agent from accessing profiles from a specific country or set of countries. To limit agent access, see Restricting Agent Activity by Profile Type.

  2. If you assign an agent to a group you still need to assign that agent a role: groups supplement agent roles but they do not replace agent roles. If you assign an agent to a group but do not assign that agent a role, you’ll see the following error message when you try to save your changes:

    An Agent Role is Required

It’s also worth reiterating that each group is associated with a single entity type. For example, let’s say you assign an agent to a group associated with the user entity type. When that agent searches for user profiles, he or she might see custom search fields like these:

Customized Search Results

However, when that same agent accesses a different entity type, they’ll see the default search display attributes for that type:

Default Search Results

Creating a New Agent

Creating a new agent is a simple process (assuming that you don’t have to worry about the permission differences between the Console and the Dashboard). To create an agent, enter the prospective agent’s email address, assign an agent role, and then click a button. That’s pretty much all you have to do.

Before we take a more detailed look at this process, however, we should mention that agents are not required to have user accounts on your web site. When an agent registers with your site he or she registers as an agent only; a regular user account (and a regular user profile) is not created for the new agent. In more concrete terms, that means you’ll see the user listed on the Manage Agents page but not on the Manage Profiles page.

Oh, and agents do not have to have accounts with specific domains or with specific email providers. Any user with a valid email address can be assigned an agent role.

The fact that agent accounts and user accounts are separate and distinct also means that you can delete an agent without inadvertently deleting any user account that the agent might have. If the agent does have a user account, that account is not tied to their agent account, and will not be deleted when the agent account is deleted.

To create an agent, complete the following procedure:

  1. From the Manage Agents page, click Create Agent:

    The Create Agent Button
  2. On the Create Agent page, enter the new agent’s email address in the Agent Email field, and then select the desired role.

  3. If you have enabled user profile access restrictions, you’ll have the option of limiting the profiles that the agent can access. To restrict access to a specified set of profiles, click the Only Allowed For list and then select the profile types that the agent will be able to access. (This option is available only if you have enabled access restrictions.) For example, if you limit access by country and you want the agent to only be allowed to manage profiles for users from the US and Canada, then select both US and CA from the allowed-for list:

     Restricting Agent Access to User Profiles
  4. Click Save.

After you click Save, an invitation to join the agents group is automatically sent to the agent and the agent is tentatively listed on the Manage Agents paged as Pending Invitation:

Invited Agent

To complete the agent assignment process, the prospective agent must click the link in the email and then do one of two things: 1) logon to the site if they already have an account; or, 2) complete the registration form to create a new account.

If logon/registration succeeds, a message similar to the following is displayed:

 Successful Activation of Agent Account

By clicking OK, the new agent is automatically logged on to the Console. At the same time, the Manage Agents page updates to show that the invitation has been accepted.

And that is the entire process, from start to finish.

But what if you create a new agent and then think better of that? That’s fine; from the Manage Agents page, click the invited agent’s name to display the Invitation Actions dialog box:

 The Invitation Actions Dialog Box

From there you have three choices:

  • Resend the invitation email.
  • Edit the invitation (which means changing the agent’s access permissions and then sending a new invitation).
  • Revoke the invitation altogether.

If you choose to revoke the invitation, the invited agent disappears from the Manage Agents page. If the uninvited agent clicks the link in their original invitation email and attempts to log on to the Console, their logon will succeed, but they won’t have access to any part of the Console. That’s because the invitation URL is no longer valid.

And what if you’re too late, and the agent has already registered? That’s fine: you can always delete an agent account any time you want.

See Also

Accepting an Agent Invitation and Managing Your Console Password

When an agent role is created for you, you’ll receive an email invitation similar to this:

Agent Invitation Email

To accept your role, and to log on to the Console and start working as an agent, click the invitation link included in the email. Make sure that the URL that opens includes the long identifier for the invitation. If you already have a Console account, that takes you to the Console login page:

The Console Login Screen

From here:

  1. Enter your email address in the Email Address field. (This has to be the same email address that the invitation was send to.)
  2. Enter your password in the Password field.
  3. Click Sign In.

At that point, your invitation will be activated and you’ll be logged on to the Console as an agent:

Logging on to the Console

If you don’t have a Console account, you’ll be taken to the registration page instead:

Creating a New Console Account

On the registration page:

  1. Enter your first and last name in the Name field.
  2. Enter your email address in the Email Address field. Note that this must be the same email address that your agent invitation was sent to.
  3. Enter a password in the Desired Password field, then re-enter that same password in the Confirm Password field.
  4. Click Create Account.

That’s all you need to do.

Changing Your Console Password

The login page for the Console includes a Forgot Password link that enables you to reset your password at any time:

The Forgot Password Link

If you need to change your password, just go to Console login page and click Forgot Password. That takes you to the Forgot Password page:

Resetting Your Password

Enter the email address associated with your Console account in the Email Address field and then click Send. In turn, you’ll be sent an email similar to this:

The Reset Password Email

If you click the link in the email, you’ll be taken to the Password Reset page:

Resetting Your Password

On the Password Reset page:

  1. Type a new password in the New Password field.
  2. Re-type the password in the Confirm New Password field.
  3. Click Send.

Your password will be changed, and you’ll be able to log on to the Console again.

But suppose that, right before you received the password reset email, you suddenly remembered your password. Do you have to change your password anyway? No, you don’t: if you never click the link (or even if you do click the link but don’t bother to change your password) your old password remains in force.

OK, but here’s another thought: suppose you click the link, you change your password, and then somewhere along the way you forget your new password as well. Can you just keep clicking that same email link, changing your password any time you want?

No, that won’t work. Password reset links are for one-time use only: after you’ve used a link to reset your password that link expires and cannot be used again. Yes, you can click the link, but instead of being allowed to reset your password you’ll see this error message:

Expired Password Link Error Message

To change your password a second time, you’ll have to resubmit your email address and start the process all over again.

And then there’s this: by default, password links expire after 1 day (24 hours). If you get a password reset email on Friday afternoon, but wait until Monday morning to try to reset your password, you’ll get that same Authorization code is not valid error message. Again, you’ll have to resubmit your email address and start the process all over again.

Console Passwords vs. Janrain Dashboard Passwords

Although the Janrain Dashboard is being phased out, many organizations still need to use both the Console and the Dashboard; that means you might have both a Console account and a Dashboard account. It’s important to note that, when it comes to passwords, those two accounts are not linked in any way: if you change your Console password that will not change your Dashboard password as well. For example, suppose you change your Console password and then try to logon to the Dashboard using that new password. If you do that, your Dashboard logon will fail:

Logging on to the Capture App

Why did logon fail? That’s right: because you only changed your Console password; you didn’t change your Dashboard password.

So how do you keep your two passwords in synch? For better or worse, there’s no automated way to do that. If you change your Console password to p@ssw0rd! then you’ll need to manually change your Dashboard pass to p@ssw0rd! as well. And, of course, the same thing works in reverse: changing your Dashboard password does not automatically change your Console password.

Blocking Access for an Agent

If you need to temporarily suspend an agent’s access to user profiles, there’s an easy way to do that. In the Console, click the agent’s name on the Manage Agents page, and then, for the appropriate entity type (or types), click Blocked:

Blocking Agent Access

After you click Save, the specified agent will no longer have access to the blocked entity type. The agent can still log on to the Console; however, he or she won’t be able to do much of anything, at least not when it comes to user profiles.

Note. Or at least when it comes to the blocked entity type. If you have multiple entity types and if you want to fully prevent the agent from accessing user profiles, you must block access for each of those entity types.

To restore an agent’s access, click the agent’s name on the Manage Agents page, select the appropriate access permissions for the blocked entity (either Full Access or Limited Access), and then click Save.

When you block or unblock agent access, the agent receives a Roles have changed email. However, this email does not specify how his or her role has changed. It simply alerts the agent to the fact that his or her permissions are now different.

See Also

Deleting an Agent

To delete a Console agent from your application, complete the following procedure:

  1. On the Manage Agents page, click the agent’s name.
  2. On the Edit Agent page, click Delete Agent.
  3. In the Would you like to delete this agent? dialog box, click Yes.

The agent’s permissions for the application will be deleted, and the deleted agent will receive an email informing them that their role has changed. As with other role changes, however, the email will not specify the exact change that took place. If the agent attempts on log on to the Console, their logon on will succeed, but the agent will be greeted with the following screen:

 Logging On After Your Console Role has been Deleted

See Also

Filtering for Agents

If you have a large number of agents, you might wonder how you can quickly locate a specific agent. The Manage Agents page enables you to sort agents by any of the displayed property values (Name, Email, and Role). In addition to that, the Manage Agents page also lets you use unique character strings to filter your agents by name and/or by email address.

Note. Although the Console uses the term “search,” you can’t search for agents the same way that you search for user profiles. For example, you can’t write a query similar to this:

agentRole = "CCP Agent"

Because of that, in this documentation we’ll use the term “filter” instead of search.

For example, suppose you have a list of agents that looks like this:

List of Console Agents

How do we find an agent (or specified set of agents) in that list. Let’s find out. For starters, type the letter m in the Search agents field. What happens when you do that? In this example, nothing happens:

Filtering Agent List

So why didn’t anything happen? There’s a good reason for that: if you look closely, you’ll see that all of the agents have the letter m somewhere in either their name or their email address. And that’s what the agent search feature is all about: finding character strings within a name or an email address. When we type the letter m in the search field, we’re telling the Console, “Show us all the agents who have the letter m somewhere – anywhere – in either their name or their email address.” And that’s exactly what the Console has done. For better or worse, we just happened to pick a letter that appears in either the name or email address of each of our agents.

Now type the letter p after the letter m. When you do that, two of the agents (the two agents who do not have the string value mp anywhere in their name or email address) will no longer be displayed:

Filtered List of Agents

Now you see how filtering works.

If you add the @ symbol to your search string you’ll see that – well, you’ll see that nothing happens then, either. That’s because both of the remaining agents have the string value mp@ in their email address. But if you type mp@j in the Search agents field, you’ll be left with the one agent whose email address (or name) contains that character string:

Locating a Single Agent

With just a few keystrokes, we were able to locate this one agent account. And this technique would have worked even if we had had 400 agents instead of just 4.

To restore the default display, and to view all the agents again, simply delete the text from the Search agents field.

If aren’t totally sure what this all means, here’s a quick summary: when you type a letter in the Search agents field, the Console looks for that letter anywhere in the agent’s email address or name. As we just saw, if you type the letter m, all of the agents are displayed, because they all meet the search criteria:

  • Toni Ng (
  • Li Song (
  • G Michael (
  • Greg Stemp (

When you type the string mp, we’re left with two agents, both of whom have mp somewhere in their name or email address:

  • G Michael (
  • Greg Stemp (

And when we add the characters @j, well, mission accomplished:

  • Greg Stemp (

Before you ask, no, there’s no way to limit the returned data to names or email addresses that start or end with the letter m. The Console always searches for the specified character/character string anywhere in the name or email address.

Note. Not even if you use wildcards? That’s actually a moot question, because wildcards aren’t supported when looking for agents. In fact, if you type an asterisk or a question mark, the Console will look for users who have an actual asterisk (*) or question mark (?) in their name or email address.

Basic search looks for the target characters in both the agent name and the agent email address; there’s no way around that. However, you can filter just by name or just by email address by using Advanced Search. Does that help? Well, it might. For example, suppose you’d like to view all the agents who have the letter a in their name. If you type an a on the basic search page, nothing happens:

 Filtering Agents by Name and by Email Address

Again, that’s because all four agents have the letter a in either their name or their email address. This time, however, click Advanced Search, type an a in the Name field, and then click Search. Here’s what you’ll see:

 Filtering Agents by Name Only

Now only one agent is displayed: the one agent who has the letter a in his name. The other three agents, who have the letter a in their email address but not in their name, have disappeared.

Another way to filter agents is to display only agents that have been sent invitations but haven’t registered yet. That can be done by selecting Show pending invitations only:

 Show Pending Invitations Only

To show all the agents again, clear the checkbox. Keep in mind, however, that you can’t do the inverse here: you can’t hide the invitation-pending agents and display only registered agents. At best, you can click Role to sort agents by role. That won’t suppress the display of the unregistered agents, but it will group all those agents together (because none of them have a role until they register).

See Also

Exporting Agent Data

In addition to viewing information about your agents onscreen, you can export information about those agents to a comma-separated values (CSV) file. One useful side benefit to exporting agent data? The exported file is the only way that you can tell, at a glance, which agents have been restricted to a limited set of user profiles. From the Manage Agents page, you can only determine an agent’s role; you can’t see any additional restrictions that might have been placed on that role. However, if you open an exported CSV file in a spreadsheet program, all you have to do is check the value of the distinguisherValues column and see for yourself:

 Viewing Exported Agent Information

If there’s a value of any kind in that column (other than the null value {} ) that means that the user has a restriction placed on their ability to access user profiles.

To export information about your Console agents, just go to the Manage Agents page and click Export All Agents:

 The Export All Agents Button

That’s all you need to do.

Note. Is there a way to export only some of your agents, for example, only the agents holding the CCP Agent Manager role? No: your export will always include all of your agents.

Clicking Export All Agents creates a CSV file named agents.csv. That file looks similar to this:

2017-10-04 17:33:07.421467 +0000,{},[],,Toni Ng
[""ccp_agent_manager""]",2017-09-21 05:30:30.635741 +0000,{},[],,Greg Stemp
2017-09-21 18:31:17.524073 +0000,"{"""":[""United States""]}",[],,Bob Jones

And what do the individual fields in that file represent? This:

Field Description
uuid UUID of the agent account. Note that this is for the agent account only. If the agent also has a user account, the agent account UUID will not be the same as his or her user account UUID.
roles Role assigned to the agent (e.g., ccp_agent_manager).
created Date and time that the role was assigned.
distinguisherValues Indicates whether the agent is limited to accessing a subset of profiles. For example, the syntax {“”:[“US”]} indicates that the agent can only access profiles where the attribute is set to US. If this field is blank then the agent has access to all the user profiles in the database.
groups Reserved for future use.
email Email address of the agent.
names Display name of the agent, as shown on the Manage Agents page.

See Also

Scroll ↓