Searching for and Exporting User Profiles

User profiles (referred to as “records” in the Capture Dashboard) contain information about your registered users. User profiles are not new; they’ve been around for a long time. What is new, however (at least for Janrain users), is the ability to search your user profiles by writing custom searches using a robust query language.


Note. Or, believe it or not, by having the Console write search queries for you.


To help you master the art of searching Janrain user profiles, this section of the Console documentation includes the following topic areas:

What You Can Search On

The Janrain Console potentially allows you to search on any attribute in your entity type schema. (This includes any custom attributes that you might have added to the schema.) Want to search for users based on their birthday? No problem: the user schema includes an attribute named birthday. Want to search for users based on the country they live in? No problem: the user schema includes an attribute named primaryAddress.country. Want to search for users based on their opt-in status? No problem: the schema includes an attribute named optin.status. Want to – well, you get the idea.


Note. When we say that you can search on any attribute in your schema, that includes plural attributes, individual attributes that can store more than one value. However, while plural attributes can be searched, the stored values cannot be displayed in the Console search results.


But wait a second: if you can search for any attribute in your user schema (and you can), then why did we preface this topic by saying that you can potentially search for any attribute in your user schema? That’s a good question, and we have an answer for you: straight out of the box, there are only a dozen or so attributes that you can search on.

Wait: what? Are those really the only attributes you can search on? Initially, yes: those are the only attributes you can search on. By design, the Console only searches on the so-called “searchable attributes,” attributes that have been indexed. And what is an indexed attribute? To answer that question, let’s start by pointing out that, in the user profile database, all the information about a user is stored as a single record; that record contains information such as the user’s name, email address, physical address, telephone number, etc. Without indices, and without indexed attributes, searching this database would require sifting through all those user records and all that accompanying data, a very time-consuming and resource-intensive task.

So then what’s an index? For our purposes, an index is a data structure (separate from the main database) that contains two pieces of information for each user: the value of an attribute (for example, the user’s email address) and a pointer to the complete user record. If you want to search for an email address, it’s much faster and much more efficient to search the email index (which, in this case, is just a list of email addresses) than it is to search through the entire database.

For example, imagine looking for a phone number in the phone book, but having to look through not just all the phone numbers but all the names and addresses and ads and maps and everything else you might encounter in a phone book. That’s obviously going to be slower and more-cumbersome than looking for a phone number in a list that has nothing but phone numbers. If you’re trying to find a specific email address, you (or, at any rate, the computer) can quickly search through the email index, locate the target email address, then, if necessary, use the pointer to the complete user record to retrieve additional information like the user’s name or telephone number.

To make a long story short (which is kind of what an index does), an index is a data structure that speeds up searches; in turn, an indexed attribute is any attribute that has its own index. In the Console, you can only search on indexed attributes, because searches are then carried out on an index rather than on the entire database.

Admittedly, if you only have a handful of user records, well, then an index won’t make much difference. But because user profile databases have the potential to grow extremely large (it’s not unusual for organizations to have millions of records in their user profile databases), using indices and limiting search queries to indexed attributes helps ensure faster and more efficient database performance.


Note. That’s the upside to an index. The downside? Each index you create requires additional storage space. That’s one reason why only a few attributes are indexed by default: if you indexed everything, your database could instantly double or triple in size, and disk storage space might suddenly become a major concern.


By default, the following attributes come “pre-indexed,” meaning that they are searchable in the Janrain Console:

  • displayName
  • email
  • familyName
  • givenName
  • primaryAddress.phone
  • birthday
  • uuid
  • profiles.identifier
  • lastUpdated
  • clients.clientId
  • id
  • created
  • profiles.profile.preferredUsername
  • janrain.properties.managedBy.clientId

Note. To verify which of your attributes are searchable and which ones aren’t, click the Searchable fields link on the Console’s Manage Profiles page. That displays a dialog box showing all the attributes you can search on:

Searchable Fields

If you later index other attributes (such as primaryAddress.country), those attributes will also appear in this dialog box.

If you are a Console Admin, you can also find this information on the Manage Schemas page.


Out of the box, those are the only attributes that you can use in a search query. For example, suppose you try to search for an attribute (such as primaryAddress.country) that has not been indexed:

primaryAddress.country = "Japan"

The preceding search will fail with the error message Some fields are not queryable: primaryAddress.country. And why isn’t the attribute queryable? You got it: because, by default, primaryAddress.country is not an indexed attribute.

But all is not lost: if you want to search on other attributes (primaryAddress.country, deactivateAccount, etc.) you just need to create indices for those attributes. That’s done by contacting your Janrain representative.


Note. At this point in time, Janrain must do the database indexing for you; that capability is not exposed in the Janrain Console or in the Janrain Dashboard.


The point to remember: the Janrain Console lets you search for any attribute in your user profile database (including any custom attributes you might have added to the database). Just make sure that the attribute is indexed before you try searching on it.

See Also

Modifying the Search Display Attributes

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

Default User Profile Display

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

Note. 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 Janrain Settings API or the Capture Dashboard.


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

Arbitrary User Profile Display Titles

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:

    API Client Default Settings
  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}]
    
  5. Click Save, and the new setting (and its default values) will be added to the Default Settings section.


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

Adding the State to the Search Results

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.) To index an attribute, contact your Janrain representative.

See Also

Search Construction and Syntax

User profiles store a wealth of useful data, although that data is useful only if you have: 1) easy access to it, and, 2) tools available to help you retrieve the data. Fortunately, the Janrain Console introduces a number of powerful search mechanisms that make the Console a superior tool for locating the exact information you need. For example, the Console enables you to:

  • Search on more than one attribute (and/or more than one value) at a time. In the Capture Dashboard you can search for all the users who live in the state of Oregon; however, you can’t search for all the users who live in the state of Oregon or in the state of Washington. This type of search (often referred to as a Boolean search) is an integral part of the Janrain Console.

  • Use wildcards when running a search. For example, suppose you can’t remember if a user is named Cindy, Cindi, or Cyndy. In the Capture Dashboard, you would have to conduct separate searches on each of those names. In the Console, you can do a single wildcard search that can find all those names in a single operation: givenName = “C?nd?”.

  • Export user profile data. The Janrain Console includes an Export Options button that makes it easy to save user data as either a CSV (comma-separated values) file or as a JSON (JavaScript Object Notation) file. The Capture Dashboard does not allow you to export user data.

  • Sort records returned from a search. The Console lets you sort data by any indexed attribute. By comparison, Capture Dashboard records are always sorted by lastUpdate time.

  • Modify the attributes displayed in your search results. By default, a Console search displays the following six attributes: givenName; familyName; email; primaryAddress.phone; birthday; and created. However, you can modify your search results to display the values for any non-plural attribute.

Before you can use these powerful new search tools, you need to have a good understanding of how search works in the Janrain Console; as well as the syntax required for creating search queries. These topics should help you achieve that understanding:

Mandatory Parts of a Search Query

The Janrain Console employs two types of search queries (also known as a “search term”). The first type, used to conduct default searches, consists solely of the target value you are searching for. For example, if you want to return information for the user with the email address toni.luc.ng@gmail.com, all you have to do is go to the Manage Profiles page, type that email address in the Search for profiles field, and then press ENTER:

toni.luc.ng@gmail.com

That’s easy, but – as is often the case – ease-of-use comes a few limitations. For one, default searching only lets you search on the default search attributes (displayName and email). Furthermore, your search has to encompass all the default search attributes: you always have to search on display name and email address (as well as any other attributes you might define as default search attributes).

And there’s another restriction: you are limited to searches where the returned user profiles equal the target value. Is that a problem? Well, it could be. For example, suppose you want to return all the user profiles except the profile for toni.luc.ng@gmail.com. That can’t be done with a default search.

Fortunately, however, that’s not much of a problem, That’s because you can also create a custom search, a query type that does let you search on a specific attribute (or attributes) and that does return something besides user profiles that equal the target value. That’s the good news. The bad news (if you want to call it that) is that a custom search requires a bit more effort on your part. As we just saw, a default search only requires you to type in the value you’re searching for. By comparison, a custom search consists of at least three items:

  • The name of the attribute that you want to search for (i.e., familyName).
  • The operator you want to employ (i.e., =).
  • The target value for the search query (i.e., Smith).

Or, to put it a little more graphically:

The Three Parts of a Search Query

The various parts that make up a search query, and more, are discussed in the following topics:

Attribute Names

Attribute names, as you might have guessed, are the names of your attributes, the individual data fields that make up your user profile database (things like displayName or birthday or lastUpdated). If you want to search for users based on their display name, then you use the attribute named displayName:

displayName

If you want to search for users based on the city in which they live, you use this attribute:

primaryAddress.city

Etc.

No big deal there. However, there are a couple of important points to be aware of here. For starters, search query target values are almost always case insensitive; that means you can use any combination of uppercase and lowercase letters and your search will work just fine. For example, to search for users with the familyName Smith, you can use any of the following search queries:

familyName = Smith
familyName = smith
familyName = SMITH
familyName = sMItH

By default, letter casing doesn’t matter when it comes to your target values.


Note. OK, so why did we qualify the previous statement by saying “by default?” That’s because, out of the box, most attributes are case-insensitive, and letter casing doesn’t matter. However, it’s possible to configure attributes to be case-sensitive. To determine which of your attributes are case-sensitive and which ones, aren’t, take a look at the Manage Schemas page.


But case-insensitivity is typically true only with target values. When it comes to attribute names, uppercase and lowercase letters are extremely important. For example, the official attribute name for a user’s display name is written like this: displayName. To search for a user based on his or her display name, you must use the name displayName. This search query works:

displayName = "Bob Jones"

However, this next search query fails with the error message The field with path ‘DisplayName’ does not exist:

DisplayName = "Bob Jones"

Why do we get that error message? Because the attribute name must be entered as displayName; anything else results in failure. As far as the Console is concerned, there is no attribute named DisplayName.


Note. Admittedly, memorizing the casing for each and every letter in each and every attribute name might seem like a daunting task. Fortunately, you can go to the Manage Profiles page and click Searchable fields in order to bring up a dialog box that shows which attributes are searchable as well as the exact spelling and letter casing of each of these attribute names:

Searchable Fields

See Also

Operators

In a Console search query you must specify the name of the attribute you want to search on (for example, displayName) as well as the value that you want to search for (for example, Bob Jones). In addition to that, you must indicate the relationship between those two pieces of information; for example, do you want to know if the displayName equals Bob Jones or if the displayName does not equal Bob Jones? Specifying the nature of this relationship is the job of the operator.

The operators available in Console search queries are listed in the following table:

Operator Description
= Equal to. Returns all the user profiles where the attribute value is equal to the target value. Example: displayName = “Bob Jones”
!= Not equal to. Returns all the user profiles where the attribute value is not equal to the target value. Example: displayName != “Bob Jones”
> Greater than. Returns all the user profiles where the attribute value is greater than the target value. Example: created > “2017-09-25T07:59:59”
< Less than. Returns all the user profiles where the attribute value is less than the target value. Example: created < “2017-09-25”
>= Greater than or equal to. Returns all the user profiles where the attribute value is greater than or equal to the target value. Example: created >= “2017-09-25”
<= Less than or equal to. Returns all the user profiles where the attribute value is less than or equal to the target value. Example: created <= “2017-09-25”

There’s nothing special about the search operators: with the possible exception of “not equal to” (!=) these are the same operators you learned back in your school days. However, there is one interesting way in which these operators differ slightly from what you learned way back when: you can use the greater than/less than operators (>, >=, <, <=) with string values as well as with numeric or date values. What does that mean? Well, suppose you have a list of users similar to this:

List of Users

Let’s further suppose that you’d like to limit the displayed data to users who have an email address that begins with the letters H through Z. (In other words, you don’t want to see any users who have email addresses that begin with the letters A through G. And don’t worry about why you don’t want to display other email addresses. You just don’t.) This query will do exactly what you wanted:

email >= "h*"

And here’s the proof:

Using Greater Than in a String Search

We’ll discuss the details of that query (such as the target value h*) elsewhere. For now, suffice to say that the query returns only users who have an email address that begins with the letter H or with a letter greater than H (i.e., any letter than comes after H in the alphabet).

The < and <= signs can also be used to query string data. For example, this query limits returned data to users who have an email address that begins with the letters A, B, or C:

email < "d*"

While we’re at it, we should also mention that the blank spaces that come before and after the operator are optional. For example, this query also limits returned data to users who have an email address that begins with the letters A, B, or C:

email<"d*"

There’s no functional difference between the two queries; the only difference is that one is a bit easier to read than the other:

email < "d*"
email<"d*"

See Also

Target Search Values

Finally, each of your queries must include a target search value; search values define exactly what it is you are looking for. For example, suppose you have this search query:

displayName = "Bob Jones"

In this case, Bob Jones is the target search value: you only want to return information for users who have the display name Bob Jones. To search for users with the display name Marie Fuentes, use this command instead:

displayName = "Maria Fuentes"

And so on.

As usual, that seems easy enough. However, there are several rules that must be followed when configuring search values. To configure search values, and to create search queries, you’ll need to know how to search for:

See Also

Searching for String or Numeric Values

For the most part, there’s not much you need to know when searching for string or numeric values: all you have to do is specify the value you want to search for. For example, here’s how you can format a search for a specific email address:

email = bob.jones@janrain.com

And here’s how you can search for a given UUID:

uuid = 9596f146-3221-43e4-ba09-a50167992109

That said, there are two special instances to keep in mind when searching for string values:

See Also

Searching for Values that Include Blank Spaces

This restriction is easy to explain: if a search value includes a blank space that value must be enclosed in double quotes. Period. For example, to search for a user who has the display name Bob either of these constructions will work:

displayName = Bob
displayName = "Bob"

That’s because, without a blank space in the search value, double quotes are optional.

However, to search for a user named Bob Jones, only this syntax works:

displayName = "Bob Jones"

The moral of the story? To search for Bob Jones (or for any other string value that includes a blank space) you must surround the value with double quotes (“Bob Jones”). That’s an absolute must.

And before you ask, yes, the following syntax appears to work (at the very least, it doesn’t return an error):

displayName = Bob Jones

However, while the preceding syntax doesn’t return an error, it does fail to return the expected data. That’s because the Console uses blank spaces to separate individual target values. As far as the Console is concerned, the preceding query is equivalent to this:

displayName = Bob OR displayName = Jones OR email = Jones

In other words, the Console is searching for a user named Bob or for a user named Jones or for someone with the email address Jones. What it isn’t searching for is a user named Bob Jones.


Note. Why the “email = Jones” clause? Because, to the Console, you didn’t specify an attribute to search on; you only specified a value to search for (Jones). As a result, the Console searches your default search fields (typically displayName and email).


To avoid this problem, put double quotes around the entire search value. Any time you enclose a search value in double quotes that value is treated as a single string. With the following syntax, the Console does search for Bob Jones and not for user Bob or user Jones:

displayName = "Bob Jones"

Note. In this documentation, you’ll often see double quotes even when they aren’t required; for example:

givenName = "Bob"

Although there’s no technical reason for using double quotes, the quote marks can make a query more readable: it’s easier to pick out search values if they’re enclosed in double quotes. However, unless your search value contains a blank space, the double quotes are optional. It’s up to you.


Searching for Values that Include Special Characters

Admittedly, this might never come up in any of your Console searches. However, the following characters can complicate your queries (although, as you’ll see, there’s a simple workaround for those complications):

! ( ) { } [ ] " ? * : \

The preceding characters are referred to as “special characters,” which means that they must be given special treatment when used in search queries. In the case of the Console, special characters must be “escaped” whenever they are referenced in a search value, a process that simply means prefacing the character with a \ (also known as the backslash). For example, suppose you want to search for the Windows path C:\Windows\System32. If so, then each backslash in the path must be prefaced by another backslash. In other words, you must escape each \ with a second :

C:\\Windows\\System32

Likewise, to search for the company Yahoo! you must use this syntax, escaping the exclamation point:

Yahoo\!

Escaping is required any time you reference a search value without using double quotes: if you don’t use double quotes then you must escape any special characters in your search value. However, suppose your target value is enclosed in double quotes:

"Yahoo!"

In that case, things are a little different. If you enclose the search value in double quotes, then you only have to escape these four characters:

" \ * ?

That means that, as long as you’re using double quotes, there’s you don’t have to escape the ! character in Yahoo!:

"Yahoo!"

However, you still have to escape the \ character, double quotes or no double quotes:

"C:\\Windows\\System32"

If that’s confusing, well, don’t worry too much about it: try it a few times (using different search characters and alternating between double quotes and no double quotes) and you’ll soon see how it works. And, as we noted earlier, there’s a good chance you’ll never encounter special characters when working with user profiles anyway.

See Also

Searching for Datetime Values

Dates are an important part of managing user profiles. For example, you’ll often want to know the date that a profile was created. You’ll want to know the date when a user first logged on, or maybe the date when the user last user logged on. You’ll want to know when (if) an account was deactivated; you’ll want to – well, again, you get the idea. Fortunately, the Janrain Console makes it easy to search for user profiles based on the date when something (a log on, a profile update, a birthday) took place.

In fact, the only potentially-confusing thing when it comes to searching for dates is the fact that the Console employs two different date-related attributes: date attributes and datetime attributes. A datetime attribute is an attribute that contains both a date and a time; for example, October 18, 2017, 11:35 AM. By comparison, a date attribute contains only the date: October 18, 2017. The Janrain user schema includes attributes of both types, and while there’s no real difference between the two (at least when it comes to searching for user profiles), it’s useful to understand exactly what you’re dealing with.

For starters, the Console formats datetime values by using ISO (International Organization for Standardization) 8061. If you run a search that returns a datetime value (such as the created attribute), the Console returns values similar to this:

Searching for Dates

How do you interpret values like those? Here’s how:

Value Notes
2017 Year. Years must be specified using 4 digits.
10 Month. The leading zero is optional. For example, you can specify September as 09 or as 9.
20 Day. Similar to the month, the leading zero is optional.
17 Hour. Hours are displayed using a 24-hour clock: hour 17 refers to 5:00 PM, and hour 5 refers to 5:00 AM. In addition, displayed times represent UTC (Coordinated Universal Time) time instead of local time. For example, in the 24-hour format, 15:39 converts to 3:39 PM UTC time. If a user logged on at 15:39 UTC time, that means that the user logged on at 3:39 PM in Greenwich, England. Meanwhile, Portland, OR is 7 hours behind UTC time: to determine the local time when an action took place, a Portland area admin must subtract 7 hours from the time displayed in the Console. In this case, 15:39 – 7 hours equals 8:39, meaning that the local time for the logon was 8:39 AM Portland time.
31 Minute. Leading zeros are not optional when it comes to minutes: that’s because 14:02 and 14:2 (which would be interpreted as 14:20) are not the same.
24.401766 Second. Leading zeroes are also required when dealing with seconds.

Is that complicated? Maybe. But, fortunately, you don’t have to worry about the level of precision prescribed by ISO 8061. Instead, when you conduct a search in the Console you only have to deal with the date itself: the month, the day, and the year. In addition, you don’t have to use the ISO 8061 format when searching for those dates. Admittedly, ISO 8061 is still allowed; for example, if you want to find all the user accounts created on September 25, 2017, you create a query like this one (which uses the Year-Month-Day) format):

created = 2017-09-25

But what if you don’t like the ISO way of formatting dates? That’s fine; just us the standard US date format (Day/Month/Year) instead:

created = 9/25/2017

Either way, you get back all the user accounts created on September 25, 2017:

Searching for Dates

That’s how you search for datetime attributes. So how do you search for date attributes? You use the exact same approach. Because they don’t include the time of day, there’s no doubt that date attributes look different in the Console search results:

Searching for Dates

Be that as it may, you still search for birthdays (or other date attributes) using the same method employed when searching for datetime attributes:

birthday = 12/24/1963

Could it get easier? Well, maybe. But we’re not sure how.

Good question: what about date ranges? For example, can we search for all the accounts created in the year 2017 or earlier? Or what about all the accounts created in February 2018? Can we do more than just find accounts created on a specific day?

Of course we can; we just have to specify the correct operator and the correct starting/ending point. For example, suppose we do want to get back all the accounts created in the year 2017 or earlier. That means that we want to get back all the accounts that were created before January 1, 2018. In turn, that means we want to use the less than operator (<) to return all the user profiles created prior to January 1, 2018:

created < 1/1/2018

Voila:

Searching for Dates

To find all the user accounts created in the year 2018 or later, all we need to do is switch to the greater than operator and change our starting date to December 31, 2017:

created > 12/31/2017

That returns creation dates like these:

Searching for Dates

And, yes, we could have used the greater than or equal to operator (>=) and a start date of January 1, 2018.:

created >= 1/1/2018

That returns all the user profiles created sometime in the year 2018:

Searching for Dates

Again, you have some flexibility here to search for dates in the way that seems the easiest and most intuitive to you.

To find all the accounts created in a specific month, use a query similar to this:

created >= 2/1/2018 AND created <= 2/28/2018

In the preceding query we’re looking for all the profiles where the creation date is greater than or equal to 2/1/2018 and where the creation date is less than or equal to 2/28/2018. In other words, we’re looking all the profiles created in February 2018:

Searching for Dates

Keep in mind that, for the moment anyway, you’re limited to searching for dates only: although datetime attributes also keep track of the time of day when an event took place, you can’t do something like, say, search for all the user profiles created between 8:00 AM and 9:00 AM on a specified day. Granted, you can include the time of day in your query; for example, you can write a query similar to this:

created = "2017-10-02 04:16:29.017481"

When you actually run that query, however, the Console strips off the time information, leaving you with this:

created = "2017-10-02"

In turn, you get back all the profiles created on October 2, 2017, regardless of what time of day those profiles were created:

Searching for Dates

See Also

Searching for Null Values

When searching for user profiles, you might want to identify users who are “missing” an attribute value; for example, users who haven’t listed their birthday or users who haven’t designated a city or state. To search for missing values, use the keyword NULL. This syntax searches for users who haven’t entered a value for their birthday:

birthday = NULL

To return a collection of all the users who have supplied a value for the birthday attribute, use the != (not equal to) operator:

birthday != NULL

Two things to keep in mind here. First, NULL queries are only valid when using the = or the != operator; if you use NULL with any other operator (such as >) you’ll receive the following error message: ‘Null’ can only be used with exact matches.

Second, you must specify the NULL keyword using all uppercase letters. This query looks for all the user profiles that have not specified a country:

primaryAddress.country = NULL

However, this query looks for all the users who live in the country Null:

primaryAddress.country = Null

Definitely not the same thing.

See Also

Optional Parts of a Search Query

If you want to write a custom search query, that query must include an attribute name, an operator, and a search value; put those three things together and you have a search query. However, queries written for the Janrain Console can also include two useful, albeit optional, items:

  • Wildcard characters
  • The Boolean operators AND and OR

In this section of the documentation, you’ll find information on working with both wildcard characters and Boolean operators:

Wildcard Characters

In poker, a wild card (such as the joker) can be used to represent any card: for example, if you have 2 aces and a joker, you effectively have three aces, the joker being used as an ace. If you have a joker and the 4, 5, 6, and 8 of spades, you can use the joker as a 7 of spades, giving you a straight flush. Most likely you already know all that.

Wildcards perform a similar function in the Janrain Console: they can be used represent any character. When searching user profiles, the Console supports two wildcard characters:


Note. Yes, those are the only supported characters. The Console does not support any other wildcard characters, including commonly-used characters such as the period (used in regular expressions) or the range (e.g., [A-Z]).


The Question Mark Wildcard

In the Janrain Console, the question mark serves stands-in for a single character. For example, suppose you want to search for a user, but you aren’t sure if that user is named Johnson or Johnsen. This query returns users named either Johnson or Johnsen:

familyName = Johns?n

In the preceding example, the search value Johns?n means “Return all the users who have a family name that begins with the letters Johns, is followed by any other character (even a number), and then ends with the letter n.” That means that the query returns users named Johnson or Johnsen. It also means that this query returns users with names like Johnsun, Johnsin, Johnsxn, or even Johns4n. For example:

  • Johnsan
  • Johnsbn
  • Johnscn
  • Johnsdn
  • Johnsen
  • Johnsfn

And so on. Like we said, the question mark represents any character.

And yes, you can use multiple question mark wildcards in a single search query. For example:

familyName = J?ns?n

The preceding query returns names such as Jansen, Jensen, Jonson, etc., etc.

As it turns out, however, there’s even more that you can do with wildcard characters.

The Asterisk Wildcard

The question mark wildcard represents a single letter; for example, the query T?m returns both Tim and Tom. However, that query won’t return term or them. Why not? Because those words have more than one character between the T and the m. To return term or them, you need to use this construction: t??m.

Of course, that syntax specifies two characters between the T and the m; that means that the query won’t return either Tim or Tom (which both have just one character between the T and the m). The question mark wildcard is very specific in its function: one character per question mark. Period.

Is that a problem? No, not as long as you use the asterisk wildcard (also known as the “star” wildcard). As we’ve seen, the question mark has one job: each question mark stands in for one (and only one) character. By comparison, the asterisk stands in for any number of characters (including zero characters). For example, this query finds both Tim and Tom:

givenName = T*m

That query also finds term, them, transcendentalism, tearoom, tandem, thermogram, and any other word or phrase that starts with a T and ends with an M. In fact, the query even finds tm, a case in which there are no (0) characters between the T and the M.

For example, do you want to find all the users who have a last name that begins with Smith (that is, Smith, Smithers, Smithson, Smithman, Smithberg, etc.)? Here you go:

familyName = Smith*

That syntax should be easy to understand: we’re simply asking for all the users whose last name (familyName) starts with the letters Smith and ends with – well, we don’t care what those last names end with (if anything). That’s the purpose of the * wildcard.

An even better use of the * wildcard is to put it at the front of your target values. For example, suppose you are planning a targeted marketing campaign, and you need a list of all the users who have Yahoo! email accounts. This query returns that information for you:

email = "*@yahoo.com"

Or, to find all the users who don’t have Yahoo! email accounts, use this query instead:

email != "*@yahoo.com"

There’s just one catch to putting an asterisk (or a question mark) at the beginning of a search value. In order to do that, the attribute in question (e.g., email) must not only be indexed, but it must also be “reverse-queryable.” By default, none of your attributes (including the default indexed attributes such as email and displayName) are reverse queryable. As a result, searching for a value like *.@yahoo.com returns the error message Some fields are not reverse-queryable: email. To get an attribute designated as reverse-queryable, contact your Janrain representative.

Like the question mark, you can use more than one asterisk wildcard in a query. For example, this query returns (among other many possibilities) the user who has the display name Bob Jones:

displayName = "B*b*J*"

Oh, and there’s one more catch to using wildcards: wildcard characters can only be employed when searching for string values. That means that you can’t use wildcards to search for things like dates or numbers or UUIDs. For example, the following query, which tries to return all the users with the birthday December 19, fails, because birthday is not a string value:

birthday = "12/19/*"

Note. But what if you need to know which users have a birthday on a specified day? Well, if you don’t have too many users, you could search for all your users, sort on birthday, and then export the data. That’s a potentially big export with a lot of data, but at least the users with a birthday on December 19 will be grouped together.


See Also

The Boolean Operators AND and OR

One especially powerful feature of the Janrain Console is the fact that you can combine multiple search criteria in a single query. For example, you can locate all the users who live in Portland or Seattle. You can find users who live in Portland and who haven’t updated their profile in the past three months. You can even pinpoint users who live in Portland or Seattle and who haven’t updated their profile in the past three months. All of this is done through the power of the Boolean operators AND and OR. In the following sections of this documentation we’ll explain how to use:


Note. Here’s an important tip regarding letter casing. In your queries you must type the Boolean operators using all uppercase letters:

AND OR

Anything else (for example, and or And) causes the Console to treat the operator as just another search query. (That is, it will search for the string value and or the string value or.)


The OR Operator

The OR operator lets you specify multiple criteria in a search, then return any profile that meets one or more of those specifications. For example, suppose you want to return information for users who live in the city of Portland or who live in the city of Seattle. More technically, you want to find all the users whose primaryAddress.city attribute is equal to Portland or whose primaryAddress.city attribute is equal to Seattle. Here’s how you do that:

primaryAddress.city = "Portland" OR primaryAddress.city = "Seattle"

In other words:

  • Criteria A (primaryAddress.city = “Portland”).
  • The OR operator.
  • Criteria B (primaryAddress.city = “Seattle”).

If you’re familiar with other search languages, you might wonder if you really need to specify the attribute name in each search. Yes, you do. Admittedly, this query (which doesn’t repeat the attribute name) won’t result in an error:

primaryAddress.city = "Portland" OR "Seattle"

However, that query won’t return the expected data, either. Instead, it returns all the users who either live in the city of Portland, or who have a display name or an email address equal to Seattle. On top of that, it won’t return any users who live in the city of Seattle. (Well, unless you have a user with the display name Seattle who happens to in Seattle.) Why does the query fail? The query fails because its syntax causes the Console to search for:

  • Users who live in the city of Portland.
  • Users who have the display name or the email address Seattle. Because we didn’t specify an attribute name, the Console looks for the target value in the default search attributes. That’s typically going to be displayName and email.

In other words, when constructing Boolean searches, you must include the attribute name with each clause:

primaryAddress.city = "Portland" OR primaryAddress.city = "Seattle"

Always.

And what if you want to add a third city to the list of “acceptable” cities? That’s fine; just include another OR clause (again, making sure that you specify the attribute name). Here’s how we look for users who live in Portland, Seattle, or Denver:

primaryAddress.city = "Portland" OR primaryAddress.city = "Seattle" OR primaryAddress.city = "Denver"

This can be continued ad infinitum. In this query, we add both Austin and Santa Fe to the list:

primaryAddress.city = "Portland" OR primaryAddress.city = "Seattle" OR primaryAddress.city = "Denver" OR primaryAddress.city = "Austin" 
OR primaryAddress.city = "Santa Fe"

Etc.

And here’s a bonus tip that might prove useful to some people. If you’re used to working with logical operators in, say, JavaScript, you can substitute || for the term OR:

primaryAddress.city = "Portland" || primaryAddress.city = "Seattle"

In other words, you can use OR (all uppercase letters, of course) or you can use ||. That’s up to you.


Note. If you have a background in SQL, you might be familiar with the IN operator, which offers an easy way to select from a list of values:

Select * FROM users WHERE city IN ("Portland", "Seattle", "Denver", "Austin", "Santa Fe")

For now, at least, the Janrain Console does not have a search operator similar to IN. In the Console, you need to write out the entire query; there’s no way to simply specify a list of allowed values.


See Also

The AND Operator

As we’ve seen, the OR operator lets you specify multiple criteria in a search and then return user profiles that meet one (or more) of those specifications. But what if you want to specify multiple criteria and return only the profiles that meet all of those specifications? In that case, the OR operator won’t help you. Instead, that’s the job of the AND operator.

Here’s an example. Suppose we want to return a list of users who live in the city of Portland and who haven’t updated their profile since October 1, 2017. The following query returns those users:

primaryAddress.city = "Portland" AND lastUpdated < 2017-10-01

If we look at a list of locations and last update times it’s easy to see why some users (the boldfaced ones) get returned while others don’t

  • 2017-10-02 Portland
  • 2017-10-01 Seattle
  • 2017-09-29 Portland
  • 2017-09-27 Portland
  • 2017-09-25 Seattle

As you can see, we only have two users who live in the city of Portland, and haven’t updated their user profile since September 30, 2017. Those are the same two users returned by our AND query.

Generally speaking, AND searches are conducted using multiple attributes: in the previous query, we looked for values in the primaryAddress.city attribute and in the lastUpdated attribute. And that makes sense: you can’t do an AND search with, say, a user’s last name, because a user can’t have a last name of Smith and simultaneously have a last name of Jones. However, there is one exception to this general rule: plurals. A plural attribute is an attribute that can store more than one value; for example, a user who has both a Google account and a Facebook account might have the values google.com and facebook.com stored in their profiles.domain attribute. Because of that, the Console lets you search for users who have both a Google account and a Facebook account by using a query similar to this:

profiles.domain = "Google.com" AND profiles.domain = "Facebook.com"

Just make sure you reference the full path to the attribute: it’s profiles.domain, not just domain.

Similar to OR queries, you’re not limited to a single AND clause. For example, this query returns all the users who live in Portland, work for Janrain, and have not updated their profile since October 1, 2017:

primaryAddress.city = "Portland" AND lastUpdated < 2017-10-01 AND primaryAddress.company = "Janrain"

Effectively, that’s three separate queries bound together by a couple of AND operators.

Users familiar with JavaScript or a similar language can substitute the && operator instead for the AND operator. These two queries are functionally identical:

displayName = "Bob*" AND primaryAddress.city = "Portland"
displayName = "Bob*" && primaryAddress.city = "Portland"

It’s up to you.

Combining the AND Operator and the OR Operator in a Single Query

When it comes to running Boolean searches in the Janrain Console, you might find yourself wondering, “Hey, could I use both the AND operator and the OR operator in the same query?” As it turns out, you can. You just need to take a little bit of care when formatting those queries.

To explain what we mean by that, let’s take a look at a sample query that includes multiple criteria:

familyName = Johnson OR familyName = Johnston AND primaryAddress.city = Portland

That query looks simple enough, or at least it does until someone asks you: what exactly are you searching for here? That’s a good question, and the answer depends on how we (or, more correctly, how the Console) parses the query. After all, we could be asking for all the users who:

  • Have the last name Johnson or Johnston, and
  • Live in Portland

Alternatively, we could be asking for all the users who:

  • Have the last name Johnson, or
  • Have the last name Johnston and live in Portland

Two different questions, and two different answers, a conundrum reminiscent of basic math. For example, what’s the answer to this problem:

5 + 2 * 7

As you might recall from your junior high days, that depends. It could be this:

(5 + 2) * 7 = 49

Or it could be this:

5 + (2 * 7) = 19

Why are there two answers to the “same” question? That’s because, in basic math, the answer you come up with depends on how you group the individual terms in the equation (i.e., where you put the parentheses). The same thing is true when it comes to search queries. If we want all the users named Johnson or Johnston and who live in Portland, we need to write our query like this, with the parentheses around the two familyName clauses:

(familyName = Johnson OR familyName = Johnston) AND primaryAddress.city = Portland

In this example, the Console first looks for users with the familyName Johnson or Johnston. Why? Because we put parentheses around those two search clauses, and the Console always acts on items in the parentheses before it does anything else. After the Console grabs all the Johnsons and Johnstons, it then winnows the list even further by returning only the Johnsons/Johnstons who live in Portland.

And what if we really do want all the Johnsons, plus all the Johnstons who live in Portland? In that case, we need to write a query like this:

familyName = Johnson OR (familyName = Johnston AND primaryAddress.city = Portland)

This time, and based on the placement of the parentheses, the Console first returns all the Johnstons who live in Portland. It then augments the returned data with all the Johnsons, regardless of where they live.

And yes, you can make your queries as complicated as you want, as long as you keep adding parentheses:

(familyName = Johnson AND primaryAddress.city = Seattle) OR (familyName = Johnston AND primaryAddress.city = Portland)

Or even this:

(familyName = Johnson AND primaryAddress.city = Seattle) OR (familyName = Johnston AND (primaryAddress.city = Portland AND 
primaryAddress.stateAbbreviation = "OR"))

In the preceding example, the Console starts with the innermost clause (primaryAddress.city = Portland AND primaryAddress.stateAbbreviation = “OR”) and returns all the users who live in Portland, OR. It then works its way out to the next set of parentheses, and then the next set, and then the next set, until all the search criteria have been accounted for.


Note. Good question: what if you forget to use any parentheses in your query? To be honest, and depending on how complicated your query is, it’s hard to say what you’ll get back. As a general rule, however, the Console processes all the AND operators before it processes any OR operators. Take this query for example:

familyName = Johnson OR familyName = Johnston AND city = Portland

The Console processes the preceding query as if we had written it like this, first processing the AND clause, and then processing the OR clause:

familyName = Johnson OR (familyName = Johnston AND city = Portland)

See Also

Running User Profile Searches

After you’ve mastered search query syntax, your next step is to actually run your query. For now, we recommend that you run queries using basic search, which lets you write custom search queries of nearly-any type and nearly-any complexity.

Basic Searches

The Janrain Console support two two ways to carry out a basic search. You can:

Default Searches

To perform a default search of your user profiles, all you have to do is go to the Manage Profiles page, type your search value in the Search for profiles field, and then click Search (or press ENTER). For example, to search for the email address terrance_oreilly@mail.com, type that address into the Search for profiles field and then click Search:

Running a Default Search

In turn, the Console returns a collection of all the users who have the specified email address or display name. And yes, the Console automatically searches both the email attribute and the displayName attribute, whether you want it to or not. That’s the whole idea behind the default search: you specify the search value, and the Console searches all of your default search attributes.


Note. Good question: how do you restore the default and show all the user profiles again? That’s easy: just select and delete any text in the Search for profiles field. Alternatively, you can click the Clear button (X) to clear the Search profiles field (and, at the same time, delete the corresponding filter)

Clearing a Search Query

That’s a little bit easier and a bit more intuitive.


You can also use wildcard characters in a default search. For example, this syntax returns information for terrance_oreilly@mail.com:

ter*

As we learned elsewhere, the preceding syntax is interpreted as “Find all the users who have a display name or an email address that begins with the characters ter. And don’t worry about any characters that come after those first three letters, assuming there even are any.” Among other things, that means that wildcard searches often return more than one profile; for example, the preceding query returns terry@janrain.com and terkel@janrain.com as well as terrance_oreilly@mail.com. That’s not a good thing or a bad thing; it’s just something to keep in mind.


Note. One way to limit the number of returned profiles is to use multiple wildcards, or to put the wildcard in a different location. For example, this query returns users who have a display name or email address that starts with ter and that ends with @mail.com:

ter*@mail.com

If nothing else, that keeps email addresses like terry@janrain.com and terkel@janrain.com from being returned.


When doing a default search you must also be on the lookout for search queries that include blank spaces. For example, suppose you want to search for the user with the display name Bob Jones. Intuitively, you might expect this query to do the trick:

Bob Jones

As it turns out, however, that query won’t do the trick, Instead, you get back the message No records found.

What went wrong? As you might recall, the Console uses the blank space to separate search values. In this case, that means the Console thinks you’re searching for two different things: 1) all the users who have a display name or email address equal to Bob, or, 2) all the users who have a display name or email address equal to Jones. Because there aren’t any users who fulfill either condition, no records are returned.

Instead, searching for Bob Jones (or for any other term that includes a blank space) requires you to enclose the search query in double quotes:

"bob jones"

And what if you did want to search for users named either Bob or Jones? That’s fine; you can specify multiple criteria in a default search. For example, suppose you wanted to find Bob Jones and/or Maria Fuentes. This query does just that:

"Bob Jones" "Marie Fuentes"

As you can see, each search query is enclosed in double quotes, and the two terms (Bob Jones and Marie Fuentes) are separated by a blank space. As a result, the Console searches for, well, Bob Jones and Marie Fuentes, the same as if you had written out this full search query:

displayName = "Bob Jones" or email = "Bob Jones" or displayName = "Maria Fuentes" or email = "Maria Fuentes"

And, yes, you can use wildcards in a “fancy” search like the previous. For example:

"Bob*" "Marie*"

Custom Searches

Default searches can be conducted very quickly and very easily. That’s the good news. The bad news is that default searches lack power and flexibility. For example, default searches can only be performed on the default search attributes (typically the email and displayName attributes); if you want to search for the date an account was created (created) or the date when an account was last updated (lastUpdated), well, you’re out of luck.

That’s where custom searches come in. With a custom search, you take the different parts of a search query (attribute names; operators; target search values; etc.) and then put those pieces together to return user data. Best of all, you can run these searches against any of your indexed attributes.

Let’s start by composing a basic query. Suppose we have a user UUID – 64d3449b-26ed-4abe-98a3-f232494ef085 – and we want to determine which user that UUID belongs to. To do that, we need three things:

  • The name of the attribute we want to search on (uuid).
  • The operator to be used in the search (=).
  • The value we want to search for (64d3449b-26ed-4abe-98a3-f232494ef085).

If we put those pieces together, we get a query that looks like this:

uuid = "64d3449b-26ed-4abe-98a3-f232494ef085"

If we go to the Manage Profiles page, type that query into the Search for profiles field, and click Search (or press ENTER) we should get back something similar to this:

Searching for a User Profile By UUID

That’s about as easy as it gets.

Before we go any further, a couple quick reminders about formatting your search queries. To begin with, and because the query value (64d3449b-26ed-4abe-98a3-f232494ef085) doesn’t have any blank spaces, the double quote marks are optional; this syntax works equally well:

uuid = 64d3449b-26ed-4abe-98a3-f232494ef085

Double quotes or no double quotes? That’s up to you. (Although we would argue that using the double quotes makes it easier to pick out the target search value.)

Second, the blank spaces that surround the equals sign ( = ) are also optional. The blank spaces make the query a little easier to read, but if you leave them out you’ll get the expected results. There aren’t any blank spaces around the operator in this query, but it still returns the correct user profile:

uuid=64d3449b-26ed-4abe-98a3-f232494ef085

The only thing that isn’t optional is the attribute name (uuid), which must be in all lowercase letters. Anything other than uuid (for example, UUID) will not provide the expected results:

The UUID Attribute Does Not Exist

Now let’s try something a little fancier; let’s search for all the users whose who live in the city of Portland, starting with this:

primaryAddress.city = "Portland"

The preceding command works, but with one little quirk: it returns users for Portland, OR (like we wanted), but it also returns users from Portland, ME; Portland, OH, Portland, NY; Portland, TX; and any of the other 30-plus American cities named Portland. Believe it or not, that’s to be expected: we said we wanted users who lived in the city of Portland, and the query returned users who live in the (or, more correctly, live in a) city named Portland. Citizens of either town might disagree, but Portland, ME is just as much a city as Portland, OR.

To limit returned data to users from Portland, OR, we need a more specific query. In particular, we need a query that specifies both the user’s city and the user’s state. In other words, we need this:

primaryAddress.city = "Portland" AND primaryAddress.stateAbbreviation = "OR"

In this query, we use the AND operator to indicate that the returned data meet two criteria: the user’s city must equal Portland and the user’s state must equal OR. People from Salem, OR won’t make the cut because they don’t have live in the specified city; people from Portland, ME won’t make the cut because they don’t come live in the required state.

And if we do want to return data as long as a user meets just one of a specified set of criteria? That’s what the OR operator is for. For example, here’s a query that returns all the users who live in Oregon or who live in Washington:

primaryAddress.stateAbbreviation = "OR" OR primaryAddress.stateAbbreviation = "WA"

Want to add Alaska, Idaho and California to the list? Then just keep adding OR clauses:

primaryAddress.stateAbbreviation = "OR" OR primaryAddress.stateAbbreviation = "WA" OR primaryAddress.stateAbbreviation = "AK" 
OR primaryAddress.stateAbbreviation = "ID" OR primaryAddress.stateAbbreviation = "CA"

Etc., etc.

But suppose we want only the females who live in Oregon or Washington. Can we do that? You bet we can:

gender = "Female" AND (primaryAddress.stateAbbreviation = "OR" OR primaryAddress.stateAbbreviation = "WA")

In the preceding query, we’re looking for user profiles that meet two criteria:

  • The user’s preferred gender must be female.
  • The user must live in either Oregon or Washington.

In order to enforce those two conditions, we put parentheses around the OR clause. When a clause is enclosed in parentheses, the Janrain Console resolves that part of the search before it does anything else. In this case, that means we first determine the state the user lives in (either Washington or Oregon) and then we make sure that the user is also female. Note that the placement of the parentheses is very important. For example, consider this query which, on the surface, looks very similar to our previous one:

(gender = "Female" AND primaryAddress.stateAbbreviation = "OR") OR primaryAddress.stateAbbreviation = "WA"

But notice how that query gets interpreted. The Console first looks at the clause contained in the parentheses:

(gender = "Female" AND primaryAddress.stateAbbreviation = "OR")

In other words, it’s going to return all the female users who live in the state of Oregon. That’s fine. But now look at the rest of the query:

OR primaryAddress.stateAbbreviation = "WA"

Because of the way we’ve positioned our parentheses, the Console is going to return all the females who live in Oregon, and then return any user (female or not) who lives in Washington. That’s not what we were hoping to return. And the difference in our two queries lies solely in how (and where) we put the parentheses.

See Also

Exporting Profile Information

If you’d like a copy of your user profile data, you can download a JSON (JavaScript Object Notation) or CSV (comma-separated values) file from within the Janrain Console. The resulting CSV file (which can be opened in any spreadsheet program) will look similar to this:

givenName,familyName,email,primaryAddress.phone,birthday,created
Antonio,Carrera,antonio_c_carrera@aol.com,,1963-12-24,2017-09-25 15:23:14.387821
Bob,Jones,gmstemp@hotmail.com,425-555-1234,1967-07-12,2017-09-25 14:59:21.547807
Marie,Fuentes,greg.stemp@yahoo.com,,1960-10-18,2017-09-21 18:17:43.053899
Susan,Jackson,gmichaelstemp@gmail.com,,1989-12-19,2017-09-21 16:28:20.093839
Terrance,O'Reilly,terrance_oreilly@mail.com,,1990-07-05,2017-09-25 15:39:37.137609

So is there anything else you need to know when it comes to exporting user data.? Well, we can think of two things. First, export only returns values for the attributes currently shown in your Console search results. By default, the Janrain Console shows the following six attributes:

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

If you want to return values for other attributes (for example, a user’s city and state), then you need to modify the attributes shown in the Console search results.

Similarly, export only returns data for the user profiles currently shown in the search results. For example, suppose you search for all the users who live in Oregon, and only those users are displayed in the Console. If you then decide to export data, you’ll only get back information for users who live in Oregon. To get back information for all your users, highlight and delete the existing query in order to return the Console to the default display (all users).


Note. Although, before you do that, see the caution at the end of this topic.


To export user profile data, complete the following procedure:

  1. From either the Manage Profiles home page or the Advanced Search page, click the Export Options button:

    The Export Profiles Button
  2. From the Download File list, click either CSV or JSON, depending on the file format you prefer.

It’s that easy.


Caution. As a general rule, you’ll find it faster and easier to export data using the Console rather than the Janrain REST APIs. This is because the Console, unlike the APIs, requires no coding or development time. Instead, anyone – even non-developers – can conduct a search and export the results.

However, you should be cautious about exporting large datasets (for example, a dataset containing hundreds of thousands of records). We recommend that you consult with your Janrain representative before attempting to export a large dataset. And, before you ask, at this point in time there’s not a good rule of thumb for determining what constitutes a “large dataset.” That’s because the size of an export requires you to factor in such things as the number of records being exported, the number of attributes being exported, and the amount of data that might be contained in those attributes. Your best bet is to discuss data exports with your Janrain representative before you begin.


See Also

Creating Searches by Using Guided Search

With the Janrain Console, it’s easy to create search queries that let you plumb the depths of your user profiles. Want to find all the users who live in state of Oregon? No problem:

primaryAddress.state = "OR"

Or maybe you want to find all the users who have the last name Smith? Again, no problem:

familyName = "Smith"

Fast, easy, and efficient.

Well, OK: fast and efficient, but, for some people, maybe not that easy. For example, to search for all the users with the last name Smith, you need to know that last name information is stored in the familyName attribute. In addition, you need to type the attribute name like this: familyName. Type it any other way – familyname, FamilyName, FAMILYNAME – and your search will fail. And that’s only for a simple query like familyName = “Smith”.

Now, don’t let us scare you: learning the ins and outs of the Console query language isn’t hard, and it doesn’t take all that long to learn. Nevertheless, learning the query language does take at least some effort and at least some time. And even if you master the basics of the query language, keep in mind that queries have a tendency to get longer and more complicated as new situations arise. Yes, finding all the users who live in Oregon is pretty easy. But what if you need to find all the users with the gender preference male, who live in Washington, Oregon, or California, and who haven’t updated their user profile in the year 2018? This query will do the trick, albeit after a little typing and a few gyrations with parentheses:

(gender = "male" AND (primaryAddress.state = "WA" OR primaryAddress.state = "OR" OR primaryAddress.state = "CA")) AND lastUpdate < "1/1/2018"

As you can see, that’s a lot to type, and to type without making a mistake. It’s not impossible, and people have written far longer and far more complicated search queries. But our primary point remains: for a number of reasons, people aren’t always excited about writing search queries from scratch.

That’s one thing that makes the Janrain Console so exciting. After all, the Console includes the following two features:

  • Guided Search, which lets you create search queries even if you don’t know the query language; even if you can’t remember attribute names (and how those names are spelled); and even if you really, really don’t like to type.

  • Search history and saved filters, which provides a way for you to save queries, and then reuse those queries over and over again, as many times as you want, and whenever you want.

We’ll cover both of these features in detail in this section of the documentation. Before we do that, however, we need to define a couple of terms.


Note. You say you’re not really into terminology? In that case, click here and jump right to the section on using Guided Search to create search filters.


Searches vs. Filters

When working with Guided Search you’ll see the terms “searches” and “filters” used over and over again. What’s the difference between a search and a filter? Well, depending on how you want to look at it, there’s not much difference at all: both searches and filters use the Console query language to search for user profiles. For example, try this exercise. From the Manage Profiles page, in the Search profiles field, type the following query:

displayName = "Bob*"

That’s a search: a query that you typed into the Search profiles field. Click the Search button, and you’ll get back a list of all the users who have a display name that begins with the string value Bob:

Sample Console Search

So much for searches. Next, click the Show Filters link:

The Show Filters Link

When you do that, your screen should look similar to this (from now on we’ll refer to the newly-visible section as the Guided Search pane):

Sample Console Filter

As you can see, the new filter (which the Console automatically constructed for you), exactly matches the query you typed into the Search profiles field: the Search profiles field displays the query displayName = “Bob*“ and the Guided Search pane shows the exact same thing.

But wait: it gets even better. In the filter, click the is equal to operator (=) and change it to the is not equal to operator (!=):

Changing the Filter Operator

Your filter now looks like this:

A Revised Filter

And what about the query that you originally typed into the Search profiles field? As it turns out, modifying the filter automatically modifies the search query as well:

Modifying a Filter Modifies the Search Query

Here’s one more thing to try. In the Guided Search pane, click the Clear button. When you do that, both the search query and the filter are deleted:

Clearing a Search Filter

To make a long story short, if you type a query in the Search profiles field, a new filter is automatically created for you. If you create a filter using Guided Search, a new search query is automatically added to the Search profiles field. The two are inseparable: you cannot have a search query without Guided Search creating a corresponding filter, and you cannot use Guided Search to create a filter without having a corresponding search query show up in the Search profiles field.

Of course, that leads to an obvious question: if searches and filters are pretty much the same thing, then why have both of them? Why not have just searches or just filters?

To answer that question, it helps to think of searches and filters as being two means to the same end. For example, suppose you need to leave a note to a coworker, asking him to notify you when a particular job is done. If you want to you can write this note in manuscript (i.e., printing):

A Note Written in Manuscript

Alternatively, you can use cursive writing to create the note:

A Note Written in Cursive

Does it matter whether you use manuscript or cursive? No, it doesn’t: either way, Bob knows that he’s supposed to call you when he’s finished. All that really matters is whether you’re more comfortable writing in manuscript or more comfortable writing in cursive. Likewise, when it comes to searching for user profiles, are you more comfortable writing queries yourself, or would you prefer to have the Console help you write those queries. If it’s the latter, then you’ll want to read more about the Console’s new Guided Search feature.

Writing Search Queries by Using Guided Search

Writing search queries in the Console is easy, but it does require you to be familiar with the Console query language (and, depending on the size and complexity of your queries, requires you to do a lot of typing as well). If you’d prefer not to write your own search queries (or if you’d like a little help along the way), then click Show Filters to display the Console’s Guided Search feature:

The Show Filters Link

As the name implies, Guided Search walks you through the process of creating a search query; even if you have no idea what a reverse-queryable field is or what a Boolean search does, you can create – and run – queries using Guided Search.

So how does Guided Search work this magic? To explain that, let’s start by taking a look at the Guided Search user interface. When you click Show Filters (the link to click if you want to use Guided Search), you’ll see the Guided Search pane. As shown below, Guided Search breaks the filter-creation process into five parts (Logic, Grouping, Filter, Operator, Value):

The Five Parts of a Console Filter

And yes, as a matter of fact we can explain what each of these parts are for:

Logic. This is where you specify the Boolean operators AND or OR used to combine multiple clauses in a single filter (for example, primaryAddress.city = “Portland” AND primaryAddress.stateAbbreviation = “OR”). To add additional clauses to a search, click Add New Filter. Note that, when you do this, the new clause always employs the AND operator. If you need to change that, just click the AND operator and then click OR:

Selecting a Boolean Operator

Incidentally, the first clause in the list always shows AND in the Logic column. Don’t worry about that: for the first clause, the operator is disabled, and you can’t click on it or change it, meaning it can safely be ignored.

Grouping (parentheses). Although there is no label for grouping clauses, if you look carefully at the Guided Search section you’ll see that each clause has a preceding and a following parenthesis:

Clause Parentheses

These parentheses are used to group clauses, something that enables you to specify an order of precedence. The Console always starts query processing by acting on items inside parentheses and only then acting on any items outside parentheses. For example, suppose you have the following query:

A Multi-Clause Query

In this example, you want to search for users who have the display name Bob or the display name Samantha, and who live in the US. To ensure that query parsing occurs in that order, you need to put displayName = “Bob” OR displayName = “Samantha” in parentheses:

(displayName = “Bob” OR displayName = “Samantha”) AND primaryAddress.country = “US”

And to do that, you can either type those parentheses in the Search profiles field, or you can click the appropriate parentheses in your filter (parentheses turn red when selected and revert to gray if deselected):

Changing Clause Parentheses

If you change your mind and want to process the clauses in a different order, then simply change the parentheses:

Changing Clause Parentheses

By the way, the Console does not alert you if you have a nonsensical set of parentheses. For example, consider this filter, which has three open parentheses but no close parentheses:

Incorrect Parentheses

This won’t generate an error message: your query runs, and results are returned. However, because the Console makes a “best guess” at what to do here, it might be difficult to determine why those results were returned.

Filter. Specifies the attribute you want to search on. The Filter lists are particularly useful because: 1) you don’t have to remember whether a field has been indexed or not (if a field doesn’t appear in the list, then it hasn’t been indexed and it can’t be searched on); and, 2) you don’t have to remember the exact spelling/letter casing for each attribute. Attribute names are always displayed in the format required to do a search.

To add an attribute to your filter, just click the appropriate list and select the appropriate attribute:

Adding an Attribute

Note that, by default, each new clause is configured to search on the default fields (typically displayName and email). However, that can be changed at any time by selecting a different attribute.

Operator. Specifies the [type of operator]/(#operators used in the search, including:

  • = Equal to
  • < Less than
  • <= Less than or equal to
  • > Greater than
  • >= Greater than or equal to
  • != Not equal to

Value. Specifies the target search value. When you select an attribute in Guided Search, the Value field displays both the name of the attribute and the datatype of that attribute. For example, if you select the familyName attribute, the Value field will tell you that familyName uses the string attribute:

Attribute Datatypes

That gives you a clue as to what kind of data can (and cannot) be used as a target search value. For example, if the attribute uses the datetime datatype then you can’t type a string value like February 19, 2107 and expect to get any results. Likewise, wildcard characters can only be used with string attributes. If an attribute uses the uuid datatype then there’s no point in typing in a search value like 903*. It’s not going to work.

Speaking of dates (which we were speaking of a moment ago), if you select a date or datetime attribute the Value field displays a date picker that lets you use a calendar control to select a date:

Selecting a Date

Yes: very handy.

So there you have it: the 5 parts of the Guided Search interface. To actually use those parts, and to actually create a filter in Guided Search, you must (at a minimum) do the following:

  1. Select an attribute to search on (the Filter section).
  2. Choose an operator (the Operator section).
  3. Enter a target search value (the Value section).

And then, after configuring the filter, you simply need to click Search to put that filter to use. As usual, your search results will show up at the bottom of the screen:

Running Your Filter

Note. If you feel that the Guided Search section is taking up too much screen space, you can hide the section at any time by clicking Hide Filters:

Hiding Search Filters

Clicking Show Filters shows the Guided Search section again.


By default, filters and searches are not permanent. For example, suppose you click the Manage Agents link to exit the Manage Profiles page, then later return to the Manage Profiles page. When you do that, you’ll discover that both your search query and your filter have been deleted:

Search Query and Search Filter

What if you’d like to keep – and then be able to reuse – a search query or a search filter? In that case, you need to know about saved searches and saved filters.

Suppressing Default Searches and “Empty” Searches

By default, each time you log on to the Janrain Console you are routed to the Manage Profiles page. In turn, the default search query (which returns all user profiles) automatically runs and shows you results of that search:

Default Search Results

This also happens any time you access the Manage Profiles page after having logged on. Open the Manage Profiles page and you won’t be greeted by a blank screen. Instead, you’ll see a collection of your user profiles.


Note. By default, that collection consists of your 10 most-recently created user profiles. You can use the arrow buttons at the bottom of the user profile list to page through those search results.


For many organizations, this default behavior is perfectly fine. However, that isn’t true for all organizations. For example, health care organizations bound by the Health Insurance Portability and Accountability Act of 1996 (HIPPA) might not want to do automatic searches that return (and display) all user records. Instead, privacy and confidentiality concerns recommend specifically entering search criteria and then returning only records that meet that criteria. That way, you don’t see any records (i.e., any user profiles) that you didn’t ask to see.

That means that some organizations actually need to see a blank screen each time they access the Manage Profiles page. These organizations would prefer to see something like this when they open the Manage Profiles page:

No Default Search Results

These same organizations might also want to keep users from doing “empty” searches. By default, Console users can return all their user profiles simply by leaving the Search profiles field blank and then clicking Search; if no search criteria are specified, Console returns all your user profiles. Instead of empty searches, many organizations want you to manually enter something in the Search profiles field before you can search for, and return, user data.

The Janrain Console enables you to suppress both default searches and empty searches. In other words, you can configure the Console so that, when you first access the Manage Profiles page, you won’t see any user profiles; this configuration also ensures that you won’t be able to perform a search without entering a search query. In turn, this enables organizations to leverage the full power of the Janrain platform yet remain fully mindful of user privacy and confidentiality.

Perhaps best of all, configuring the Console to suppress default searches and empty searches is remarkably easy: all you need to do is add the {entity_type}_search_allow_empty client setting to your Janrain configuration. (For more information on adding client settings, see the article API Clients and Permissions). In other words, you just need to logon to the Janrain Dashboard and complete the following procedure:

  1. From the Dashboard home page, click the Manage Capture app icon:
    The Manage Capture App Icon
  2. From the Capture app home page, clicking Settings:
    Capture App Settings
  3. On the Settings tab, click the Default Settings header. This adds a blank name/value pair to the section:
    Adding a New Setting
  4. In the first new field, type the setting name; this name will be the name of the entity type followed by _search_allow_empty. For example, if you’re suppressing default and empty searches for the user entity type, enter user_search_allow_empty.
  5. In the second field, type the setting value: false. Your screen will look similar to this:
    The User Search Allow Empty Setting
  6. Click Save to add the new setting and the new setting value:
    The New Setting

After the Console settings have been refreshed (a process that might take 5 minutes or so), you’ll no longer see a set of default search results when you access the Manage Profiles page (at least not for the user entity type; search suppression is done on an entity type-by-entity type basis). Instead, you’ll see something like this:

Suppressed Search Settings

The message Please submit a search term to view records lets you know that a search query has not been executed. This differentiates a suppressed search query from a query that simply failed to find any records. In the latter case, you’ll see the message No records found instead:

A Search that Returns No Records

The _{entitytype}_search_allow_empty setting also prevents you from doing an empty search. To verify this, go to the Manage Profiles page, leave the Search profiles field blank, and then click Search. Instead of getting back all your user profiles, you’ll see the following message:

Empty Search Error Message

The preceding message tells you that you must enter a valid search query in the Search profiles field before you can return user data.

If you have additional entity types and you want to suppress default searches and empty searches for those profiles, simply add a similar setting for each entity type. For example, this setting suppresses default searches and empty searches for the test entity type:

Adding an Entity Type

To restore the default behavior (and to again allow both default searches and empty searches), either delete the search_allow_empty setting, or set the value to true:

Enabling Empty Searches

Search History and Search Filters

Nothing lasts forever, and that includes searches run in the Janrain Console. For example, suppose you create a moderately-complicated search query such as the following:

(familyName = Johnson AND primaryAddress.city = Seattle) OR(familyName = Johnston AND 
(primaryAddress.city = Portland AND 
primaryAddress.stateAbbreviation = "OR"))

Let’s further suppose that you log off the Console and then, sometime later, need to log on and re-run that very same search. How do you do that? Easy: you just retype the entire query, making sure that the attribute names are spelled – and cased – correctly and that the parentheses are all in the right places and that – well, you get the idea. And yes, that’s what we were thinking, too: surely there has got to be a better way to rerun your Console searches.

And, as it turns out, there is a better way. In fact, there are actually two ways to save and reuse search queries: search history and search filters.

Before you ask, yes, there is a difference between the two. Searches are automatically saved for you in your search history (and have a limited lifespan). By comparison, you must explicitly save filters. However, once saved, those filters can theoretically last forever. And if that doesn’t clear things up for you, that’s fine: we were just about to show you how all this works.

Let’s start by taking a peek at the search history in action. To do that, go to the Manage Profiles page and click the Searches and Filters icon located next to the Search profiles field:

The Searches and Filters Icon

When you do that, you’ll see the following pop-up menu:

The Search History and Saved Filters Dialog Box

As you might have guessed, our focus for the moment is on the first two items in the list: Show search history and Show saved filters.

Actually, we’ll focus on those two things in a moment. Before we do that, however, we need to point out that both Show search history and Show saved filters are toggle switches: when colored red, the option is enabled, and when colored gray the option is disabled. To enable/disable one of these features, just click the option as needed. For example, here’s what it looks like when Show search history is enabled (red) and Show saved filters is disabled (gray):

Disabling Saved Filters

To re-enable Show saved filters, just click the option again.

We should also mention that the search history (which maintains a record of the last 4 searches you have run) is always working; it’s just that the history isn’t always displayed. (That’s what the toggle switch controls.) For example, suppose you log on to the Console for the first time; because it’s your first login, you won’t have any search history:

No Saved Queries

Now, disable Show search history, conduct a couple of searches, and then check your search history again. It should still look empty:

No Saved Queries

So what happens if you re-enable Show search history? When you do that, the searches you ran while Show search history was disabled are displayed:

Search History is Always Tracked

In other words, your search history consists of the last four searches you’ve run, regardless of whether or not Show search history is enabled. You always have a search history (even if you can’t see it), and the search history will always contain just four entries. Suppose your search history consists of these four items:

  • Search 1
  • Search 2
  • Search 3
  • Search 4

If you run another search, your search history will now look like this:

  • Search 2
  • Search 3
  • Search 4
  • Search 5

Search 1 is removed from the history, and that deleted query cannot be restored. Does that mean Search 1 is lost forever? Yes, if you’re relying on search history alone. But that’s not the case if you decide to save your query as a saved filter.

A Few Quick Notes About the Console Search History

Let’s start by clarifying something important: search history tracks your last four searches on this computer and with this particular web browser. For example, suppose you conduct searches A, B, C, and D on your desktop workstation using Chrome, then log on to your laptop computer and conduct searches E, F, G, and H (again using Chrome). When you return to your desktop machine, the search history will consist of the last four searches that took place on that computer: A, B, C, and D.

And on your laptop? That’s right: you’ll see searches E, F, G, and H, the four searches conducted on that computer. Searches are stored locally: they are not stored in a central location accessible from any computer and/or any web browser.

Here’s a more visual example of what we’re talking about. Suppose we log on to Computer 1 and search for all the users who live in the US. That search gets added to our search history:

Sample Search History

If we now log onto Computer 2 and check our search history, we won’t see anything at all:

Searches are Saved Locally

Why not? You got it: because we haven’t conducted any searches on Computer 2. If we run a search on Computer 2, that search will be added to Computer 2’s search history, but it won’t be added to the search history for Computer 1.

But don’t go away just yet: there’s more. As noted, search histories also differ depending on your web browser. For example, log on to the Console using Chrome, and do searches A, B, C, and D. After that, and on the same computer, log on to the Console using Safari. Searches A, B, C, and D will not be visible in Safari, even though the browser is on the same computer as Chrome. That’s because the search history is maintained in local storage for each browser. If you take a look at local storage on Chrome, you can see that for yourself. Chrome might have a search history info that looks like this:

Search History in Chrome Local Storage

Meanwhile, Safari’s local storage will contain a different search history:

Search History in Safari Local Storage

Two different search histories, one for each browser.

Using the Search History

It’s interesting to know that search history maintained in your web browser’s local storage. However, it might be even more interesting to know how to access and use that history. Fortunately, accessing and using the Console search history is pretty straightforward. In fact, and assuming that Show search history is enabled, all you have to do is click the mouse anywhere in the Search profiles field. In turn, you’ll see a dropdown list showing your last four Console searches:

Using the Search History

If you want to rerun one of these searches all you have to do is click the appropriate query. For example, here we’ve reloaded the query displayName = “Bob*“:

Using the Search History

All you have to for now is click Search and wait for the results to come rolling in.

Search history also responds to everything you type in the Search profiles field. As we just saw, when you first click in the Search profiles your search history appears, without you having to do anything else:

Filtering the Search History

Note. What if you don’t like that behavior? Well, you can always disable Show search history; that prevents the search history from being displayed each time you click the Search profiles field. Of course, that also prevents the search history from being displayed, period.


If you want to, you can click one of your queries and have it. Alternatively, you might try this: while the search history displayed, type the letter c. When you do that, the search history is filtered to show only the saved searches (and saved filters) that include the letter c somewhere in the query text (and/or the saved filter name):

Filtering the Search History

Type the letter r (giving you the string cr), and the search history is filtered again, now showing only searches that have a cr somewhere in the query text:

Filtering the Search History

And what happens if you type the letter a? In that case, the search history disappears altogether:

Filtering the Search History

Why? Because none of the search history entries (and none of the saved filters) have the letter combination cra anywhere in their query text (or, as we mentioned before, the filter name).

As noted, filtering is done on characters that appear anywhere in the query text. For example, let’s clear the Search profiles field and type the letter b:

Filtering the Search History

As you can see, the history is filtered to a single item: the one search query that contains the letter b. And this happens even though the b in email = b* comes near the end of the query text. The target text does not have to come at the beginning of a query.

If you want to get rid of all the searches currently in the search history, simply bring up the search history list and then click Clear recent searches:

Clearing the Search History

That clears the search history without touching any filters you might have saved:

A Cleared Search History

Saving Filters

Ah, yes: what about saved filters? To explain what a saved filter is, let’s start by creating a simple little filter of our own:

Saving a Search Filter

Important. In this example, we used Guided Search to create and save our filter. However, you don’t have to go this route. If you prefer, you can type your query in the Search profiles field, then follow the instructions we’re about to give you for saving a filter.


Let’s assume that this is a useful filter, one that we want to reuse over and over again. Because of that, we can save the filter by completing the following procedure:

  1. Click the Search History and Saved Filters icon to display the pop-up menu.
  2. In the menu, click Save new filter:
    Saving a Search Filter
  3. In the Create new saved search dialog box, enter a name for the filter in the Filter Name field:
    Saving a Search Filter
  4. Click Save.

The new filter will now be available under Saved Filters:

Saving a Search Filter

Note that filter names must be unique: you can only have one filter named Non-US Residents. If you attempt to reuse a filter name, you’ll be asked to either save the new filter under a different name or to rewrite the existing version of the filter:

Overwriting a Search Filter

Unlike the search history, filters are stored centrally: that means that filters are available regardless of the computer/browser you are currently using. For example, suppose you save a filter using the Safari browser on Computer A:

Saving a Search Filter

If you later log on from Computer 2, using the Chrome web browser, that saved filter will be available to you:

Saving a Search Filter

Filters are also saved on a per-user basis: a filter that you saved will not be available to any other agent (not even an administrator). And filters are saved separately for each entity type. For example, suppose you have two entity types: user and employees. If you create a filter (Last Login Date) for the user entity type, you can save and re-use that filter any time you’re working with that entity type. However, if you switch to the employees entity type, the Last Login Date filter will not be available. If you want to use the same filter on multiple entity types, you’ll need to re-create that filter for each type.

Deleting a Saved Filter

Filters can be deleted at any time by completing the following procedure:

  1. Click the Search profiles field to display the search history/saved filters list.
  2. In the list, click the name of the filter than you want to delete. The filter is displayed in the Guided Search pane:
    Saving a Search Filter
  3. Click the Searches and Filters icon and then click Delete selected filter:
    Saving a Search Filter
  4. In the Are you sure you want to delete this saved filter? message box, click Delete:
    Deleting a Search Filter

As long as we’re on the subject, you might have noticed that the Guided Search section includes a trash can icon. In turn, you might have thought, “I bet that’s how you delete a saved filter.” As it turns out, however, the trash can icon doesn’t delete filters; instead, it deletes individual clauses from a filter. For example, suppose we have a filter with two clauses, one clause for the created attribute and the other for the primaryAddress.country attribute:

Deleting a Filter Clause

If you click the trash can icon next to the primaryAddress.country clause, that clause is deleted:

Deleting a Filter Clause

However, the filter itself remains, and the remaining trash can icon is now disabled. Why? Because we only have one clause left in our filter, and you can’t have a filter that doesn’t have at least one clause.

Modifying or Renaming a Filter

If you want to modify a saved filter, there are two ways to do that. For either approach, start by loading the filter (click the Search profiles field, then click the appropriate filter name). From there, you can do one of two things. For one, you can complete this procedure:

  1. Click Show Filters, make any required changes, then click the icon and click Update selected filter:
    Modifying a Search Filter
  2. In the Update saved search dialog box, click Save:
    Modifying a Search Filter

Alternatively, you can:

  1. Load the filter and then immediately click Update selected filter.
  2. Manually update the query shown in the Update saved search dialog box.
  3. Click Save.

Either way, the filter will be modified.

You can also use the latter approach to rename an existing filter. For example, suppose you have a filter named Filter 1, and you want to change that filter name to US Residents. To do that:

  1. Click the Show profiles field and then, from the Saved Filters section, click Filter 1:
    Renaming a Search Filter
  2. Click the Search History and Filters icon, and then click Update selected filter:
    Modifying a Search Filter
  3. In the Update saved search dialog box, type US Residents in the Filter Name field:
    Renaming a Search Filter
  4. Click Save.

If you look in the saved filters list, you’ll see that Filter 1 has been renamed US Residents.

Scroll ↓