Context Service

Search for Objects (lookup)

Use contextServiceClient().search() to lookup objects. Search typically uses a list of key-value pairs where the key corresponds to a Context Service field name. Search is an exact word match and is case-insensitive in English.

type is a required search parameter if you search using ContextObject.

search() returns a list of objects that match your search criteria. Context Service automatically adds totalHits to the SearchParameters object after a search. totalHits is a key-value pair containing the number of results returned for the query. Use the AND or the OR query operator to combine multiple search terms. All search results are case-insensitive exact matches. White space is trimmed from the end of any search.

By default, all fields are searchable. To make a field non-searchable, set the searchable field property to false.

Search now enforces the key when you search for a key-value pair. For example, previously if you had two users, one with the first name Thomas and a second with the last name Thomas, search would return values for both keys. Search is now granular and searching for first_name:Thomas returns the records where only the first_name is Thomas.

Search for Customers Matching Multiple Fields

This example shows a basic customer search, using both first and last name fields. The search returns customer record that matches Jane in the first name field and Doe in the last name field. The function takes an initialized Context Service client as the input parameter.

java
Copy/**
 * Search for customer matching all specified fields.
 * 
 * @param contextServiceClient an initialized Context Service Client
 * @return List of customers matching the criteria
 */
public static List<ContextObject> searchForCustomerByFirstAndLastName (ContextServiceClient contextServiceClient) {
    SearchParameters params = new SearchParameters();
    params.add("Context_First_Name", "Jane");
    params.add("Context_Last_Name", "Doe");
    params.add("type", ContextObject.Types.CUSTOMER);
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.AND);

    for (ContextObject customer : result) {
        LOGGER.info("Found customer: " + customer.toString());
    }
    return result;
}

Special Search Keys

You can use special search keys to search for object metadata instead of the normal key-value lookups on fields. In addition to field keys, you can search based on one or a combination of any of the following special keys:

  • type—Search for a type of ContextObject. type is a required search parameter if you search using ContextObject.
  • id—Object ID.
  • customerId—Customer identifier.
  • parentId—Parent object identifier.
  • mediaType—Activity Media Type.
  • state—Object state. Valid when searching customers, requests, activities, or details.
  • contributors.username—Contributor Cisco Common Identity client UUID.
  • newContributor.username—Cisco Common Identity client UUID of the last contributor that updated an object.
  • contributors.uniqueId—Hashed unique contributor identifier.
  • notExists—Search for objects that do not contain the specified value or object property.
  • tags—Search for activities containing the specified tag.
  • maxEntries—Maximum number of results returned. The default value is 50, with a minimum value of 1 and a maximum value of 200. The maxEntries parameter always uses the AND query operator and ignores a specified OR operator.
  • sortedBy—Sorts the search results using the defined value. Possible values are lastUpdated, id, created, state, parentId, or customerId. The default value is lastUpdated.
  • sortOrder—Returns the search results in either ascending or descending order. Possible values are asc or desc. The default value is desc.
  • startIndex—Specifies where in the index to start searching from. Use startIndex to page through search results. Context Service returns search results beginning from the startIndex value. The default startIndex value is 0. You can use startIndex to view information when the total number of search results (totalHits) exceeds the maxEntries value. Searches that use startIndex to page through results will vary over time as the queried data changes.
  • startDate—Earliest possible time returned for the lastUpdated timestamp. The default startDate time is 24 hours. Entries are returned from startDate to "now". The startDate parameter always uses the AND query operator and ignores a specified OR operator.
  • endDate—Latest possible time returned for the lastUpdated timestamp. Search for objects updated between startDate and endDate. Using endDate alone returns objects updated before the current date.
  • query_string—Searches for all objects that contain the specified values, regardless of the key that corresponds to that value. query_string is a string containing space-delimited values. To search for values that contain whitespace, use quotes "" to wrap the value and escape the quotes. For example, use \“123 Main St\” to search for 123 Main St. The query_string parameter always the OR query operator and ignores a specified AND operator.
  • startCreatedDate—Search for objects created starting with the specified date. All entries created after the specified start date are returned.
  • endCreatedDate—Search for objects created ending with the specified date. All entries created up to the specified end date are returned.
  • summary—Specify if the search returns a summary. This is a boolean value and defaults to false. Set summary to true to return a list of objects containing only the object IDs. The number of matches is limited to a maximum of 100,000 entries.

Use the

RFC339Date class
to format dates when searching.

startDate and maxEntries always use the AND query modifier. Search ignores the OR query modifier if you use it with the startDate or maxEntries parameter.

Searching for an object immediately after it is created may not always work as expected. search() can take up to a minute to return results. If you need to look up information immediately after object creation, use get() instead.

Search for Activity Using Created Date

This example shows how to search for an activity by using the activity created date. The input takes a range of dates.

java
Copy// Logger
    private final static Logger LOGGER = LoggerFactory.getLogger(SearchEntities.class);
    private final static String DATE_STRING_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'";
/**
 * Search for PODs created within a specified date and time range.
 * 
 * @param contextServiceClient  an initialized Context Service Client
 * @param startTime return PODs that were created no earlier than this time
 * @param endTime return PODs that were created no later than this time
 * @return List of PODs that were created within the date/time range.
 */
public static List<ContextObject> searchForPodsByCreateDateRange (ContextServiceClient contextServiceClient, long startTime, long endTime) {
    // Convert times (msec) to Date/Time strings...
    String startDate = new RFC3339Date(startTime).toString();
    String endDate = new RFC3339Date(endTime).toString();

    SearchParameters params = new SearchParameters();
    params.add("startCreatedDate", startDate);
    params.add("endCreatedDate", endDate);
    params.add("type", ContextObject.Types.POD);
    // type is "special" and will be used to only match objects of that type, regardless of AND or OR
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.AND);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

Search for Customers based on a Field

This example shows how to search for customers by first name or last name.

java
Copy/**
 * Search for customer matching any of the specified fields.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @return List of customers matching the criteria
 */
public static List<ContextObject> searchForCustomerByFirstOrLastName (ContextServiceClient contextServiceClient) {
    SearchParameters params = new SearchParameters();
    params.add("Context_First_Name", "Jane");
    params.add("Context_Last_Name", "Doe");
    // NOTE: type is "special", so it won't just return all ContextObjects of this type when using OR
    params.add("type", ContextObject.Types.CUSTOMER);
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.OR);

    for (ContextObject customer : result) {
        LOGGER.info("Found customer: " + customer.toString());
    }
    return result;
}

Search for Activity Using ID

This example shows how to search for an activity using customer ID.

java
Copy/**
 * Search for Pod by CustomerID.
 * 
 * @param contextServiceClient an initialized Context Service Client
 * @param id the Customer ID
 * @return List of Pods associated with the Customer ID
 */
public static List<ContextObject> searchForPodByCustomerId (ContextServiceClient contextServiceClient, String id) {
    SearchParameters params = new SearchParameters();
    params.add("customerId", id);
    params.add("type", ContextObject.Types.POD);
    // Note that for a single parameter (type is "special"), it doesn't matter whether we use the AND or OR Operation.
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.OR);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

This example shows how to search for an activity using a list of pod Ids.

java
Copy/**
 * Search for Pod by List of Pod IDs.
 * 
 * @param contextServiceClient an initialized Context Service Client
 * @param idList the list of Pod IDs
 * @return List of Pods matching any of the IDs in the list
 */
public static List<ContextObject> searchForPodByListOfIds (ContextServiceClient contextServiceClient, List<String> idList) {
    SearchParameters params = new SearchParameters();
    params.addAll("id", idList);
    params.add("type", ContextObject.Types.POD);

    // For a list, make sure to use OR; since no Pod can match ALL of different IDs.
    // type is "special" and will be used to only match objects of that type, regardless of AND or OR
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.OR);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

Search for Activities Associated with a Request

This example shows how to search for all activities that contain a certain parentId value.

java
Copy/**
 * Search for Pod by Request ID.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @param id the Request ID
 * @return List of Pods associated with the Request ID
 */
public static List<ContextObject> searchForPodByRequestId (ContextServiceClient contextServiceClient, String id) {
    SearchParameters params = new SearchParameters();
    params.add("parentId", id);
    params.add("type", ContextObject.Types.POD);
    // Note that for a single parameter (type is "special"), it doesn't matter whether we use the AND or OR Operation.
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.OR);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

Search for Activities without an Associated Request

This example shows how to search for all activities that do not have a parentId value. Activities without a parentId value are not grouped with a request.

java
Copy/**
 * Search for Pods that do not have a parent Id value.
 *
 * @param contextServiceClient an initialized Context Service Client
 * @return a list of Pods matching the query
 */
public static List<ContextObject> searchForPodsByNullParentIdValue(ContextServiceClient contextServiceClient) {
    SearchParameters params = new SearchParameters();
    params.add("notExists", "parentId");
    params.add("type", ContextObject.Types.POD);
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.AND);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

Search for Activities Using Tags

This example shows how to search for all activities that contain either the tag sales or the tag marketing.

java
Copy/**
 * Returns list of PODs that any of the specified tags.  
 *
 * @param contextServiceClient an initialized Context Service Client
 * @return List of Pods that match at least one of the tags
 */
public static List<ContextObject> searchForPodsTaggedAsSalesOrMarketing (ContextServiceClient contextServiceClient) {
    SearchParameters params = new SearchParameters();
    params.add("tags", "sales");
    params.add("tags", "marketing");
    params.add("type", ContextObject.Types.POD);
    // type is "special" and will be used to only match objects of that type, regardless of AND or OR
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.OR);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

You can also search for all activities that contain all of your specified tags. This example shows how to search for all activities with the tags major, issue, and preferred-customer.

java
Copy/**
 * Returns list of PODs that match ALL specified tags.
 *
 * @param contextServiceClient  an initialized Context Service Client
 * @return List of Pods that match all of the tags
 */
public static List<ContextObject> searchForPodsTaggedAsMajorIssueForPreferredCustomer (ContextServiceClient contextServiceClient) {
    SearchParameters params = new SearchParameters();
    params.add("tags", "issue");
    params.add("tags", "major");
    params.add("tags", "preferred-customer");
    params.add("type", ContextObject.Types.POD);
    // type is "special" and will be used to only match objects of that type, regardless of AND or OR
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.AND);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

Search for Activity Using Query String

This example shows how to search for all activities the contain the value Ivanna.Buy@prospect.com, 222-222-2222, banana, or Ivanna Buy. The example uses quotes "" to wrap the phrase Ivanna Buy and escapes the quote characters.

java
Copy/**
 *  Search for PODs with a specified query_string parameter.
 * 
 *  @param contextServiceClient  an initialized ContextServiceClient
 *  @return a list of PODs found by the query_string sub queries
 */
public static List<ContextObject> searchForPodsByQueryString(ContextServiceClient contextServiceClient){
    SearchParameters params = new SearchParameters();
    params.add("query_string", "Ivanna.Buy@prospect.com 222-222-2222 banana \"Ivanna Buy\"");
    params.add("type", ContextObject.Types.POD);
    // type is "special" and will be used to only match objects of that type, regardless of AND or OR
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.AND);

    for (ContextObject pod: result){
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}

Complex Query Examples

You can combine multiple search parameters to build a complex query string. This example shows how to search for activities with a specified custom field, time range, and tag.

java
Copy/**
 * Build a complex query checking for a custom field, a time range, and a tag.
 * 
 * @param contextServiceClient  an initialized Context Service Client
 * @param startTime return PODs that were created no earlier than this time
 * @param endTime return PODs that were created no later than this time
 * @return a list of Pods matching the query
 */
public static List<ContextObject> searchForPodsByCustomFieldAndDateRangeAndTag(ContextServiceClient contextServiceClient, String customField, long startTime, long endTime) {
    // Convert times (msec) to Date/Time strings...
    String startDate = new RFC3339Date(startTime).toString();
    String endDate = new RFC3339Date(endTime).toString();

    SearchParameters params = new SearchParameters();
    params.add("startCreatedDate", startDate);
    params.add("endCreatedDate", endDate);
    params.add(FIELD_ONE, customField);
    params.add("tags", "cancellation");
    params.add("type", ContextObject.Types.POD);
    // type is "special" and will be used to only match objects of that type, regardless of AND or OR
    List<ContextObject> result = contextServiceClient.search(ContextObject.class, params, Operation.AND);

    for (ContextObject pod : result) {
        LOGGER.info("Found pod: " + pod.toString());
    }
    return result;
}
Next