We've been regularly pushing improvements to the Context Service SDK. The current base version is 1.0.5 and the current extension version (auto-upgrade from the cloud) is 1.0.6. We recommend that you update your SDK to the latest base version of 1.0.5 because it resolves a threading issue in 1.0.4 and provides much better performance. It is available from the DevNet downloads link on the Context Service page.
The recent updates provide much improved search/lookup capabilities in Context Service. This blog post details the new method of doing lookups on objects and provides examples on many of the common operations.
You use the search() method of ContextServiceClient() to do a lookup on any of the base objects (Pod, Customer, Request). The most common search criteria is a list of key/value pairs with the key corresponding to a field name. However, special search keys are also supported for searching object meta-data (See Special Search Keys below).
For PII and Encrypted fields, the search only returns case-sensitive exact-matches; as the search is done on a hashed version of the data for security purposes. Note that white space is trimmed from the ends of any searches.
For unencrypted fields, case-insensitive search in English is supported. Note that for search purposes, non-alphanumeric characters in unencrypted fields are treated as white space and are not indexed. So, for example, searching for http://example.com results in a search for http example com. With the exception of letter case, searches must be exact match and partial matches are not supported. For example. A search for "Quick Brown Fox" will not match a field containing "Quick Brown" because "Fox" is missing from the field.
Searches take a Map of keys/values as the search term argument. Searches are done at the field-level for data elements and require that you provide the name for the field that you are searching as the key. For "OR" queries you may want to use the same key for a particular field, for example, when you want to search for PODs that have three particular tags. The key is always "tags", but the values are different. In that case use a MultivaluedMapImpl() Map to allow for multiple identical keys in the same map.
You use an AND or an OR modifier on the search. This is used when combining multiple search terms. search() returns a List of the objects that match your search criteria. For example, if you search in the Customer class, then a list of type Customer is returned.
// Searching by field values
Map<String, String> searchParams = new TreeMap<String, String>(){{
put("Context_City", "Boston");
}};
List<Customer> custResult = contextServiceClient.search(Customer.class, searchParams, OR);
System.out.println("Search by Context_City found : " + custResult.size() + " Matches");
Special Search Keys
There are several special search keys you can use beyond the normal key/value lookups on fields. You can lookup based on one or a combination of any of the following special keys in addition to field keys:
- id: The ID of the object.
- customerId: the Customer ID. Only valid when searching PODs.
- requestId: the Request ID. Only valid when searching PODs.
- mediaType: the Media Type of the POD.
- state: the POD State. Only valid when searching PODs.
- contributors.username: any contributor username associated with a POD
- contributors.id: any contributor ID associated with a POD
- newContributor.username: the last contributor username associated with a POD
- newContributor.id: the last contributor ID associated with a POD
- tags: PODs containing this tag.
- startDate:a time for the earliest "last updated" date to return (defaults to the last 24 hours). Entries are returned from startDate to "now".
- maxEntries: the maximum number of results to return (defaults to 50, minimum is 1 and maximum is 200)
Note that 'startDate' and 'maxEntries' are always AND'ed in the query, even if you specify OR as the operation to use for the lookup.
Looking Up Customers based on a Field
//Lookup Customers
Map<String, String> lookupParams = new TreeMap<String, String>(){{
put("Context_Home_Phone ", "555-555-5555");
}};
List<Customer> custList1 = contextServiceClient.search(Customer.class, lookupParams, AND);
for (Customer custItem : custList1) {
System.out.println(custItem.getCustomerId());
}
POD Lookups on Customer ID
This example shows how to do a POD lookup based on the ID of a Customer object.
// Lookup PODs by customerId including optional startDate and maxEntires
Map<String, String> podLookup = new TreeMap<String, String>(){{
put("customerId", customerId);
}};
List<Pod> podsByCustomer = contextServiceClient.search(Pod.class, podLookup, OR);
System.out.println("Pods associated with Customer " + customerId + ':');
for(Pod pod : podsByCustomer ) {
// print the POD Id and Request ID
System.out.println("POD ID: " + pod.getPodId().toString());
System.out.println(" Request ID: "+ pod.getRequestId().toString());
}
POD Lookups on POD ID
This example shows how to do a POD lookup based on a list of POD IDs.
// Lookup PODs by POD ID
Map<String, String> podLookup = new TreeMap<String, String>(){{
put("id", podIdA);
put("id", podIdB);
put("id", podIdC);
put("id", podIdD);
put("id", podIdE);
}};
List<Pod> podsByID = contextServiceClient.search(Pod.class, podLookup, AND);
System.out.println("PODs found with Given IDs");
for(Pod pod : podsByID ) {
// print the POD Id and Request ID
System.out.println("MATCHED POD ID: " + pod.getPodId().toString());
}
POD Lookups on State with Max Entries and Start Date
This example shows how to do a POD lookup based on POD state.
// Set the search time to be within the last 60 minutes
long testMinutes = new Date().getTime() - 1000 * 60;
Date testDate = new Date(testMinutes);
final String searchStartTime = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").format(testDate);
// lookup PODs by state
Map<String, String> podLookupState = new TreeMap<String, String>(){{
put("state", PodState.ASSIGNED.toString());
put("startDate", searchStartTime);
put("maxEntries", "3");
}};
List<Pod> podsByLookupState = contextServiceClient.search(Pod.class, podLookupState, AND);
System.out.println("\n\n *** Results of Lookup on STATE - " + podsByLookupState.size() + " results: ");
for(Pod pod : podsByLookupState ) {
// print the POD Id
System.out.println(" ** FOUND POD ID: " + pod.getPodId().toString());
System.out.println(" ** State: " + pod.getState().toString());
}
POD Lookups on Last Contributor
This example shows how to do a POD lookup based on the last contributor to create/modify the POD.
String contributorUsername = "f4d64bb5-7cbf-4832-b6434-a1464ac1cf5be";
Map<String, String> podLookupLContributor = new TreeMap<String, String>(){{
put("newContributor.username", contributorUsername);
}};
List<Pod> podsByLookupLContrib = contextServiceClient.search(Pod.class, podLookupLContributor, AND);
System.out.println("\n\n *** Results of Lookup on Last Contributor - " + podsByLookupLContrib.size() + " results: ");
for(Pod pod : podsByLookupLContrib ) {
// print the POD Id
System.out.println(" ** FOUND POD ID: " + pod.getPodId().toString());
System.out.println(" ** Contributors: " + pod.getContributors().toString());
}
POD Lookups on Any Contributor
This example shows how to do a POD lookup based on any contributor who created/modified the POD.
String contributorUsername = "f4d64bb5-7cbf-4832-b6434-a1464ac1cf5be";
Map<String, String> podLookupContributor = new TreeMap<String, String>(){{
put("contributor.username", contributorUsername);
}};
List<Pod> podsByLookupAnyContrib = contextServiceClient.search(Pod.class, podLookupContributor, AND);
System.out.println("\n\n *** Results of Lookup on Last Contributor - " + podsByLookupAnyContrib.size() + " results: ");
for(Pod pod : podsByLookupAnyContrib ) {
// print the POD Id
System.out.println(" ** FOUND POD ID: " + pod.getPodId().toString());
System.out.println(" ** Contributors: " + pod.getContributors().toString());
}
POD Lookups on Tag
This example shows how to do a POD lookup based on Tag.
// lookup PODs by multiple tags
MultivaluedMap fieldsSearch = new MultivaluedMapImpl();
fieldsSearch.add("tag", "My Tag");
fieldsSearch.add("tag", "My Other Tag");
List<Pod> podsByTag = contextServiceClient.search(Pod.class, podsByTagSearch, AND);
System.out.println("\n\n *** Results of Lookup on Tag - " + podsByTag.size() + " results: ");
for(Pod pod : podsByTag ) {
// print the POD Id
System.out.println(" ** FOUND POD ID: " + pod.getPodId().toString());
System.out.println(" ** TAGs: " + pod.getTags().toString());
}
