The Janrain Console User Guide
Welcome to the Janrain Console User Guide. Here you’ll find links to documentation that explores every nook and cranny of the Console, including information on ground-breaking new features such as user search and Console agents. And what if we missed a nook or cranny somewhere along the way? In that case, click the Provide Feedback link off to the right and let us know. We’ll try to fill that documentation hole as quickly as we can.
And if you’re wondering, “OK, but what exactly is the Janrain Console?” you might want to start by taking a peek at the topic Overview of the Janrain Console.
Using the Janrain Console
- Overview of the Janrain Console
- Searching for and Exporting User Profiles
- Managing User Profiles
- Managing Agents
- Managing Schemas
More About the Janrain Console
- Configuring Customer Care Portal Settings
- Comparing the Capture Dashboard and the Janrain Console
- Frequently-Asked Questions About the Janrain Console
What’s New/What’s Cool?
- Guided Search
- Search History and Search Filters
- Suppressing Default Searches and Empty Searches
- Agent Groups
What Would You Like to Know?
I’d like to know …
- … why I should even care about the Janrain Console.
- … what I can search for in the Janrain Console.
- … how to change the user attributes displayed in the Janrain Console search results.
- … how to write my own search queries.
- … how to write search queries that use Boolean operators.
- … how to write search queries that use wildcard characters.
- … how to create user profiles for people.
- … how to export user profile data.
- … how to manage access to the Janrain Console.
- … how to assign a Janrain Console role to a user.
- … how to export data about all my Janrain Console agents.
- … how to view my Janrain schemas.
An Overview of the Janrain Console
The Janrain Console is the next generation of Janrain management tools, and the eventual successor to both the Janrain Dashboard and the Customer Care Portal. Which brings up an important question: what if you’re perfectly content with the Janrain Console and the Customer Care Portal? After all, if the old tools already do everything you need them to (or at least if they seem to do everything you need them to), why would you want to go through the time and trouble required to learn something else? Does the Janrain Console really offer something that these other tools don’t?
Funny you should ask. As it turns out, the Console offers a number of things that its predecessors don’t:
A single location for all your management tools, with a unified look and feel.
Delegation of administrative authority by using a single mechanism: roles. This differs from the Janrain Dashboard, where access to the Capture Dashboard and to the Engage Dashboard are managed in different places, and by using different methodologies.
Full-fledged user profile search capabilities, including the ability to write queries that employ wildcard characters and Boolean operators such AND and OR.
The ability to export user profile data. The Console also allows you to export audit data for a specified user; this data provides a blow-by-blow account of every change that has been made to a user profile in the past 90 days, including the identity of the person who made the change, what they changed, and when they changed it.
For more background on the Console, including information on how to access the tool, take a look at these two topics:
Elsewhere in this documentation you’ll find detailed information on all the Console’s features and capabilities, including:
And what if you’ve already started using the Janrain Console, but things aren’t working the way you expected them to? In that case you might want to take a look at the article Frequently Asked Questions About the Janrain Console.
Accessing the Janrain Console
If you’re wondering how you can get access to the Janrain Console, well, here’s the secret: if you hold the admin role in your organization’s Capture Dashboard, then you already have access to the Janrain Console. To start using the Console, just point your web browser towards https://console2.janrain.com:
From there, log on using the same credentials you use to log on to the Capture Dashboard.
Note. The preceding illustration shows the default Janrain Console logon screen. The logon screen that you see could look slightly different, based on any customizations and modifications that your organization might have made. Note that your URL could different as well, depending on your setup and configuration. See your Janrain representative for more information.
After you log on, and depending on your access credentials, you’ll be able to manage three key aspects of your Janrain implementation:
Note. After logging on to the Console you will automatically be logged out if: 1) 15 minutes have elapsed without you taking any action; or, 2) 8 hours have elapsed since you logged on, regardless of your activity level. So what happens if your session times out? Nothing much: you’ll be logged out, but you can immediately log back in.
- An Overview of the Janrain Console
- Comparing the Capture Dashboard and the Janrain Console
- Frequently Asked Questions About the Janrain Console
Configuring Customer Care Portal Settings
After your Janrain implementation has been deployed, you can log on to Console and begin work, with no additional configuration required.
Well, like we said, with no additional configuration required. However, if you are using the Customer Care Portal feature, you might want to (or need to) optionally modify some of the Console’s default settings. For example, suppose you have multiple API clients and you want to configure those clients differently; for example, the clients might be assigned different flows or use a different registration form. In that case. you’ll need to change one or more of the following settings:
|ccp_edit_form||Form used when editing a user profile in the Customer Care Portal.|
|ccp_enable_email_send_buttons||Indicates whether the Resend Verification and the Send Password buttons are visible when editing a user profile in the Customer Care Portal.|
|ccp_flow_locale||Flow locale used for Customer Care Portal actions such as creating and editing user profiles and sending emails.|
|ccp_flow_name||Name of the flow used for Customer Care Portal actions such as creating and editing user profiles and sending emails.|
|ccp_flow_version||Version number of the flow used for Customer Care Portal actions such as creating and editing user profiles and sending emails.|
|ccp_recover_password_form||Form used when sending password reset emails from the Customer Care Portal.|
|ccp_registration_form||Form used when creating user profiles in the Customer Care Portal.|
|ccp_verify_email_form||Form used when sending email verification emails from the Customer Care Portal.|
|entity_type_search_distinguisher_field||Attribute used to restrict agent access to a specified set of user profiles.|
|entity_type_search_distinguisher_field_values||Used with entity_type_search_distinguisher_field to define the user profiles an agent can access.|
|entity_type_search_display_fields||Defines the attribute values that are returned when you do a Console search.|
|entity_type_search_allow_empty||When enabled, search results are not shown by default when you open the Manage Profiles page.|
|password_recover_url||Base URL used when generating a password reset link.|
|verify_email_url||Base URL used when generating an email verification link.|
Configure Console Settings by Using the Janrain Dashboard
Console settings can be configured by using either the Janrain Dashboard or the Janrain Client APIs. To add a setting by using the Dashboard, complete the following procedure:
- Log on to the Janrain Dashboard, and then click the Manage Capture app icon:
- From the Capture app home page, click Settings:
- On the Settings tab, click the Client Settings header for the login client you want to add the new setting to. When you click the header, two blanks fields are added to the client settings pane:
- In the first blank field, type the name of the setting that you want to add (for example, console_enable_email_send_buttons). In the second field, type the setting value (for example, false). Your screen will look similar to this:
- Click Save. The new setting is added to the Settings section:
To change the value of a setting, click anywhere on the setting to enable edit mode (you’ll know you’re in edit mode if you see the Save and Cancel buttons):
Make your change and then click Save.
To delete a setting (which restores the setting’s default value), hover the mouse anywhere over the setting and then click the trash can icon:
When the confirmation dialog box appears, click OK to delete the setting:
Configuring Console Settings by Using the Client API
- Configure Postman to use Basic authentication and to connect to your Capture URL. If you aren’t sure what your Capture URL is, you can usually find that URL in your domain whitelist. From the Janrain Dashboard, click the Manage Engage app icon and then, from the Engage app home page, click the Manage Settings icon:
- In Postman, set the method type to Post and then enter the configuration settings endpoint (for example, https://greg-stemp.us.dev.janraincapture.com/settings/set) :
- Click Params to expose the parameters section. You’ll need to add three parameters to this section:
- To add the first parameter, in the Key field, type key. In the Value field, type the name of the setting to be added (for example, console_enable_mail_send_buttons).
- To add the second parameter, in the Key field, type value and then, in the **Value **field, type the setting value (for example, false).
- To add the final parameter, in the Key field, type for_client_id. In the Value field, type the client ID for the API client the new setting is to be associated with. Your screen will look similar to this:
- Click Send. If you get back an OK message the setting has been successfully added:
This process is also used to modify an existing value. If the specified setting already exists, the API call will change the value. If the setting does not exist, the API call will add the new setting. To delete a client setting, use the Delete method.
Specifies the form used when editing a user profile in the Console. If the setting is not configured, Console will default to using the editProfileForm form.
To change the form used for editing user profiles, add the ccp_edit_form setting and set the value to the new form name.
If you use an alternate form for editing user profiles in the Console, it’s recommended that you preface the form name with the string value ccp_.
Specifies whether the Resend Verification and the Send Password buttons are visible when editing a user profile in the Console. By default, agents who have the appropriate agent roles will see these buttons any time they access a user profile:
If you click Resend Verification, you’ll send an email to the user asking him or her to verify their email address. If you click Send Password, you’ll email the user a link they can click if they need to reset their password.
However, these options work only if you are using Janrain to send Console emails (i.e., your email_method setting is set to ses_synch). If you are not using Janrain to send Console emails, these buttons are useless: they won’t actually send email address verification or password reset emails. In that case, you might want to hide the two buttons by setting ccp_enable_email_send_buttons to false.
Do that, and the two buttons will no longer be visible in the Console:
To re-enable the buttons, either delete the ccp_enable_email_send_buttons setting or set its value to true.
Specifies the flow locale used for Console actions such as creating and editing user profiles and sending emails. By default, the locale is set to US English (en-US). However, you can change the locale by adding the ccp_flow_locale setting and assigning it the appropriate IETF language tag.
Note that the flow locale only affects certain actions within the Console: it does not localize or otherwise change the Console UI. Note, too that you might get unexpected results if you set ccp_flow_locale to a flow locale that does not exist. If you get unexpected results after changing the flow locale, delete the ccp_flow_locale setting. The Console will then use default flow locale.
Specifies the name of the flow used for Console actions such as creating and editing user profiles and sending emails. By default, the flow name is set to standard. However, you can change the name by adding the ccp_flow_name setting and assigning it the flow name.
You might get unexpected results if you set ccp_flow_name to a flow name that does not exist. If you get unexpected results after changing the flow name, delete the ccp_flow_name setting. The Console will then use the default flow name.
Specifies the version number of the flow used for Console actions such as creating and editing user profiles and sending emails. By default, the flow version is set to HEAD, which indicates that Console uses the latest version of the flow. However, you can cause Console to use a specific version of the flow by adding the ccp_flow_version setting and assigning it the version number.
You might get unexpected results if you set ccp_flow_version to a version number that does not exist. If you get unexpected results after changing the version number, delete the ccp_flow_version setting. The Console will the use the HEAD flow version.
Specifies the form used when sending password reset emails from the Console. If this setting is not configured, Console will default to using the forgotPasswordForm form.
To change the form used for sending password reset emails, add the ccp_recover_password_form setting and set the value to the new form name.
If you use an alternate form for sending password reset emails, it’s recommended that you preface the form name with the string value ccp_ (e.g., ccp_custom_password_form).
Specifies the form used when creating user profiles in the Console. If the setting is not configured, Console will default to using the registrationForm form.
To change the form used for creating user profiles, add the ccp_registration_form setting and set the value to the new form name.
If you use an alternate form for creating user profiles, it’s recommended that you preface the form name with the string value ccp_ (e.g., ccp_custom_registration_form).
Specifies the form used when sending email verification emails from the Console. If this setting is not configured, Console will default to using the resendVerificationForm form.
To change the form sending verification emails, add the ccp_verify_email_form setting and set the value to the new form name.
If you use an alternate form for sending verification emails, it’s recommended that you preface the form name with the string value ccp_ (e.g., ccp_custom_verify_email_form).
The base URL used when generating a password reset link. For example, in the password reset email shown below, the base URL is http://customer-dev.janrain.com/widgets/d4771c3c6fae/?screenToRender=resetPasswordRequestCode:
The base URL used when generating an email verification link. For example, in the password reset email shown below, the base URL is http://customer-dev.janrain.com/widgets/d4771c3c6fae/?screenToRender=verifyEmail:
Comparing the Capture Dashboard and the Janrain Console
The Janrain Console will eventually replace both the Capture Dashboard and the Engage Dashboard. As of this writing, however, the Console doesn’t have all the features and capabilities found in the Capture Dashboard, and has none of the features found in the Engage Dashboard. The following table compares Capture Dashboard pages with their Console counterparts:
|Capture Dashboard Page||Console Page||Notes|
|Analytics||N/A||Download daily logon activity reports. Not available in the Console.|
|Schema||Manage Schemas||Access to your Janrain schemas. The Console provides full access to your schemas, including information about all schema attributes. However, you must be an Administrator to access the Manage Schemas page.|
|API Clients||N/A||Access to API client information, including client IDs and secrets. Planned, but not yet available in the Console.|
|People||Manage Agents||Manage administrative access. Note that the Console supports different roles and access permissions than the ones found in the Capture Dashboard.|
|Settings||N/A||Configure API client settings. Planned, but not yet available in the Console.|
- An Overview of the Janrain Console
- Comparing the Capture Dashboard and the Janrain Console
- Frequently Asked Questions About the Janrain Console
Frequently-Asked Questions About the Janrain Console
You say you’ve got questions about how to use the Janrain Console, questions about why you’re not seeing what you thought you’d see, or why this one error message keeps popping up every time you try to do something? No problem: you’ll find the answers to many of those most-frequently asked questions (and those most-frequently encountered issues) right here.
And if you don’t see your question anywhere on that’s page? In that case, click the Provide Feedback button and send us your question. We’ll post an answer as quickly as we can.
General Management Questions
How do I access the Janrain Console?
Point your web browser towards https://console2.janrain.com and then log on using the same credentials you use to log on to the Janrain dashboard.
I logged on to the Janrain Console, but I don’t see the Manage Agents link. Why not?
That usually means that you’ve been assigned the CCP Agent or CCP Agent – Update Only role; users holding those roles won’t see the Manage Agents link. That link is only visible to CCP Agent Managers and Administrators.
For more information about agents and agent roles, see Console Roles and Permissions.
I tried to log on to the Janrain Console, but all I saw was a page with the message You do not have any applications associated with your account. What does that mean?
That means that you haven’t been assigned a Console role. You’ll need to have an Administrator or a CCP Agent Manager assign you a role.
For more information about agents and agent roles, see Console Roles and Permissions.
It’s nice that the creation date for all my user profiles is shown on the Manage Profiles page, but I’d rather see the country that my users are from. Is there any way to change the display?
Yes, there is. In fact, not only can you display any attribute you want in the search results, but you can also display those attributes in any order that you want. All you have to do is modify the user_search_display_fields setting.
For information on how to modify this setting, see Modifying the Search Display Fields.
I’d like to sort my user profiles by last name, but I can’t figure out how to do that. Can I sort profiles by last name?
Yes. (Well, yes but ….) If an attribute has been indexed, you can sort user profiles on that attribute simply by clicking the appropriate column header (for example, Last Name). However, that only applies to attributes that have been indexed; if your search results display an unindexed attribute (such as primaryAddress.city) is not indexed. If you want to sort on a user’s city, you’ll need to have the primaryAddress.city attribute indexed. And to do that, you’ll need to contact your Janrain representative. Currently neither the Console nor the Janrain Dashboard provides a way for you to index attributes yourself.
How do I set a user’s password at the same time I create their user profile?
You can’t: allowing administrators to set user passwords is not a security best practice. The only password-related activity you can carry out is to access the user’s profile and click Send Password. That sends the user an email that includes a link to a page where they can create their own password.
For more information on setting/resetting user passwords, see Resetting a User Password.
I wanted to delete a couple of inactive user profiles, but I can’t find the Delete Profile button anywhere. Where is it?
Delete Profile is found at the bottom of each user profile:
That said, you won’t see Delete Profile if you hold the CCP Agent – Update Only role. Users with that role can view and modify profiles, but they can can’t create or delete profiles.
Incidentally, user profiles must be deleted one-by-one. At the moment, there is no way (at least not in the Console or the Dashboard) to select a number of profiles and delete all of them in a single operation.
For more information on agents and agent roles, see Console Roles and Permissions.
Searching for User Profiles
I tried to search for a user using the query displayname = “Bob Jones”, but all I got back was the error message The attribute with path ‘displayname’ does not exist. The displayname attribute doesn’t exist?!?
Technically, no, it doesn’t. That’s because letter casing is crucial when it comes to attribute names. As far as the Console is concerned, there is no attribute named displayname; instead, there’s an attribute named displayName (note the uppercase N). Try this query instead:
displayName = "Bob Jones"
For more information on letting casing and when it matters, see Attribute Names.
I tried searching for all the users who live in the state of Oregon, but all I got back was the error message Some fields are not queryable: primaryAddress.stateAbbreviation. What does that mean?
It might not be obvious, but that error message means that you can only search on attributes that have been indexed; by default, primaryAddress.stateAbbreviation is not an indexed (i.e., searchable) attribute. And how are you supposed to know which attributes have been indexed? One easy way to determine that is to click the Searchable fields link on the Manage Profiles page:
Clicking that link displays a dialog box that lists all your searchable attributes:
But what do you do if you need to search on the primaryAddress.stateAbbreviation attribute? Here’s your answer: contact your Janrain representative and ask him or her to index the attribute for you.
For more information on indexed attributes, see What You Can Search On.
I tried searching for all the users who have Gmail accounts by using this query: email = “*@gmail.com”. All I got back was the error message Some fields are not reverse-queryable: email. What’s the problem here?
The problem here is this: in order to use a wildcard character at the beginning of a string, the attribute you are searching on (in this case, email) must be configured as a reverse-queryable attribute. (Which, for our purposes, simply means that you can use a wildcard at the beginning of a search value that references that attribute.) To have an attribute marked as reverse-queryable, contact your Janrain representative.
For more information on wildcards and how they can (and cannot) be used in the Console, see Wildcard Characters.
I tried searching for all the user accounts created on or after September 25, 2017 using this query: created >= “9/25/2017”, but I got the error message Invalid date string ‘9/25/2017’: expected ISO8601 format. Did I do something wrong?
As a matter of fact, you did do something wrong: you used an invalid format when specifying the date. As the error message states, you need to use the ISO 8601 format when specifying dates and times. With ISO 8601, a simple date is specified like this:
Or, in your case:
To get back the data you were hoping to get back, try this query instead:
created >= "2017-09-25"
For more information about searching for dates in the Janrain Console, see Searching for Datetime Values.
I tried searching for a user using the query uuid = “834-962*”, but all I got back was the error message Invalid UUID string “834-962*”: Expected hexadecimal UUID string. Why did I get this error message?
You got that error message because you can’t search for UUIDs using a wildcard; wildcards are reserved for string values. And what if you aren’t sure about the datatype (e.g., string; integer; Boolean; etc.) used by an attribute? Don’t worry about it; you can find this information on the Manage Schemas page:
For more information on wildcard characters, see Wildcard Characters.
I searched for all the user profiles created after September 25, 2017 (that is, September 26 or later) by using the query created > “2017-09-25”. However, the returned results include users whose profiles were created on September 25. Why?
That’s because, in the Console, the datetime value 2017-09-25 is actually short for this:
Effectively, that refers to the exact instance at which the date clicked over to September 25th. Any date or time later than that (including, for example, a time one second into September 25th) is greater than your specified date.
To find all the accounts created on September 26, 2017 or later (which is what you really want), use this query instead:
created >= "2017-09-26"
That returns the data you’re looking for.
For more information on searching for datetime values in the Janrain Console, see Searching for Datetime Values.
I want to look at all my user profiles. I tried using the query displayName = “*” but all I got back was an Invalid string %: cannot begin and end with a wildcard error message. How do I display all my user accounts?
You’re getting the “invalid string” error message because you started (and ended) your search value with an asterisk, and that’s not allowed. That said, however, you don’t need to go to that much trouble just to display all of your user accounts; after all, that’s what the Console does by default. If you want to display all your user accounts simply delete any query currently shown in the Search for profiles field. For example, suppose your Search for profiles field currently looks like this:
Select the query created > “2017-09-25” and then press Delete. As soon as the query is deleted the screen will refresh, and all your user accounts will be displayed.
Exporting User Data
I’m trying to export all my user data, but I’m only getting a subset of those users. Why?
The Console only exports information for the user profiles that currently appear in the search results. For example, suppose you just searched for all the users who live in the state of Oregon, and those profiles are currently displayed in the search results. If you export the data, your export will only include information about the users who live in the state of Oregon. Like we said, you can only export information for the user profiles currently in the search results.
So how do you export information for all your users? To do that, just make sure that all your user profiles appear in the search results. And to do that, select and delete any query currently in the Search for profiles field. With no query in effect, Console displays information for all your users. Export the profiles now, and you’ll get back data for each and every user in your database.
However (and this is an important however), before you export all your user accounts you should read the topic Exporting Profile Information.
I want to export my user data, but I’d like to get back the user’s city and state. How do I do that?
When you export user data in the Janrain Console, you export the data currently shown in the search results. By default, that means you export the following attributes:
- First Name (givenName)
- Last Name (familyName)
- Email (email)
- Phone (primaryAddress.phone)
- Birthday (birthday)
- Created (created)
If you want to get back different attributes (such as primaryAddress.city and/or primaryAddress.stateAbbreviation), you need to reconfigure the search display so that those new attributes show up in the search results. That can be done by modifying the user_search_display_fields setting.
For information on modifying this setting, see Modifying the Search Display Fields.
Is there a way to limit an agent to a specific set of profiles?
Yes, there is, although there are some limitations on your ability to place these limits, starting with this: you can only restrict agent access to profiles based on the value of a single attribute (per entity type). For example, if you want to allow an agent to only access profiles from Canada, you can select primaryAddress.country as the “distinguisher field” and then configure Canada as one of the distinguisher values. When configuring the agent’s account, all you have to do is specify that the agent in question can only access profiles where the primaryAddress.country attribute is set to Canada.
As noted, however, you can only select one such distinguisher field, and this attribute must apply to an entire entity type. What if you wanted to limit some agents to accessing profiles only from Canada and wanted to limit other agents to accessing profiles only from Mexico? That’s fine; you can do that because you only need to work with one attribute (primaryAddress.country). But what if you wanted to limit some agents to only accessing profiles from Canada, and limit other agents to only accessing profiles from the state of Oregon? That’s something that you can’t do, because that requires two distinguisher fields (primaryAddress.country and primaryAddress.stateAbbreviation). The Console only allows you to specify a single distinguisher field.
For more information on limiting access to profiles, see Restricting Agent Activity by Profile Type.
How can I print a list of all my agents?
Well, from within the Console you can’t, not unless you want to print each web page that includes agent information. However, you can export the agent data, load the exported data into an application that can read and format comma-separated value (CSV) files, and then print the agent data from there.
For more information on exporting agent data, see Exporting Agent Data.
I tried to search for all my agents that have an email address that starts with the letter e, but when I typed the e I continued to see all of my agents. Is that the expected behavior?
In this case, yes. The problem you’re running into is the fact that the Manage Agents page uses a very simple, very rudimentary type of searching. When you type the letter e, the Console doesn’t search for agents who have an email address that starts with the letter e; instead, it searches for agents who have that letter anywhere in their email address or display name. (Not just at the beginning, but anywhere.) For example, if you type ed you’ll see email addresses like firstname.lastname@example.org or email@example.com; you’ll also see email addresses like firstname.lastname@example.org or display names like Fred Smith.
Is there a way to work around this issue? Not really; about the best you can do is export all your agent data, then use a different program to sift through the exported information.
For more information on filtering your list of agents, see Filtering for Agents.