Search API

Dovetail Seeker exists to enable search against your Dovetail/Clarify CRM application. This API accepts GET or POST actions and executes searches against the index created by the indexing applications and returns results in JSON format.

Suggested Usages:
Simple Example

Request:

GET /seeker/search?query=test

Response:

{"SearchResults":[<elided for sake of brevity>],"TotalNumberOfResults":0,"RequestedNumberOfResults":10,"StartResultIndex":0, "SearchQuery":"test","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}

POST Example

Your application can use both GET and POST HTTP actions to execute search queries. The example below uses a JSON payload to transmit the query parameters. You could also use a regular web form POSTS (application/x-www-form-urlencoded).

Request:

POST /seeker/search

Headers:

Content-Type: application/json

Payload:

{ query: "test" }

Response:

{"SearchResults":[<elided for sake of brevity>],"TotalNumberOfResults":0,"RequestedNumberOfResults":10,"StartResultIndex":0, "SearchQuery":"test","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}

Pagination Example

It is common that search clients will wish to allow pagination of search results.

Request:

GET /seeker/search?query=VPN&resultCount=1&startResultIndex=2

Response:

{"SearchResults":[<elided for sake of brevity>],"TotalNumberOfResults":2,"RequestedNumberOfResults":1,"StartResultIndex":0, "SearchQuery":"VPN","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}

Result Sorting Example

Search results by default are sorted by relevancy. Sometimes that is not exactly what you want. It is possible to sort search results by a single custom field value.

Note: For a custom field to be sortable it's definition in the custom 
field document specification must have tokenization turned off.

Request:

GET /seeker/search?query=VPN&sortedByField=firstName&isSortedAscending=true

Response:

{"SearchResults":[<elided, yet sorted>],"TotalNumberOfResults":22,"RequestedNumberOfResults":10,"StartResultIndex":0,"SearchQuery":"Robert","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}

Return Custom Fields Example

Custom field values are normally not returned with search results. It may be desirable in some situations to have custom field values returned with search results. To accomplish this you simply include one or more returnCustomField parameters with the search request.

Request:

GET /seeker/search?query=domain:case+AND+blue&returnCustomField=site&returnCustomField=contact

Response:

{"SearchResults":...,"CustomFields":{"site":"Dovetail Software","contact":"James Miller"}}]...

Search service parameters for /search
Parameter Required Default Description
query yes n/a The search query
resultCount no 10 The number of results to return. Could also be considered the page size.
startResultIndex no 0 The index of the first search result to return. Used for pagination.
maximumSummaryLength no n/a The maximum number of characters allowed in the Summary field of any search result. The goal of this optional parameter is to allow the client to control the size of the payload before it is transmitted.
returnCustomField no n/a The custom fields in the search index are not normally returned with search results. Requests including this parameter will have all search results attempt to locate a field in the search index matching the parameter value.

Note: Multiple returnCustomField parameters can exist per request.
sortedByField no n/a Sort search results by this search index field.

Note: The field used for sorting cannot be Tokenized. You can control tokenization in the document specification.
isSortedAscending no false When search results are being sorted by a field. This optional parameter controls the sort order.
Search Results

The response returned by the Seeker web service is a collection of data encoded in JSON format. The search results themselves are wrapped in an envelope called Search Results Information which contains data about what was searched and what results are available.

An example search result:

{
  "SearchResults": [{
    "Score":0.5498657,
    "Domain":"solution",
    "Id":"2",
    "Title":"I can't connect to the VPN Server with my VPN Client",
    "Summary":"Users are unable to connect to WinRoute using the VPN client."
  }],
  "TotalNumberOfResults":2,
  "RequestedNumberOfResults":1,
  "StartResultIndex":0,
  "SearchQuery":"VPN",
  "Exception":null,
  "LastIndexUpdateTimestamp":
  "2008-10-02T11:16:23"
}
Search Results Information

The search service returns a wrapper around the search results containing information about what was searched and what details are available.

Property Description
Search Results An array of search result JSON objects.
TotalNumberOfResults The total number of search results that matched the search term.
RequestedNumberOfResults The number of results requested. This will match the resultCount request parameter.
StartResultIndex The index of the first search result returned. This will match the startResultIndex request parameter.
SearchQuery The search query. This will match the query request parameter.
Exception Only populated when something went wrong during the search process.
LastIndexUpdateTimestamp When the search index was last updated.
Search Results

Zero or more search results can be returned by a search ordered by diminishing relevance.

Property Example Description
Score .5498 A rating of how relevant the result is to the search term(s). A value between 0 and 1.
Domain solution The type of search result being returned.
Id 2 Identifier of the search result.
Title I can't connect to the VPN Server Title of the search result.
Summary Users are unable to connect to WinRoute using the VPN Client. A summary of the search result.

Search Query Syntax

Dovetail Seeker uses the excellent Lucene search engine library exposing your indexed data to simple or advanced queries. If you are familiar with the basic search engine query techniques you will feel right at home with querying Dovetail Seeker.

Simple Queries

The following is an example of a simple query:

Case 1234

Dovetail Seeker defaults to make search words exclusive. Only documents having the word Case and 1234 will be returned. This query is exactly the same as:

Case AND 1234

Changing this query to be inclusive, so that documents with Case or 1234 are returned, requires the use of the OR operator.

Case OR 1234

Note: The OR operator is case sensitive and needs to be capitalized.
Advanced Queries

For a detailed account of the capabilities of the Seeker's query syntax please refer to the Lucene documentation on Query Parser Syntax.