Fields

Each document specification has three types of fields each exposing a way to search for the object being indexed.

  1. Identification Fields which are used to ensure that the document being indexed is unique and can be searched for by identifier.
  2. Required Fields hold the default search contents along with what will be displayed with search results.
  3. Custom Fields which are optional fields exposing alternative ways of searching for the object being indexed.

Fields are composed of a mix of text and one or more paths used to define a way to retrieve data from Clarify for the object being indexed.

Identification Fields

When updating the index, the indexing applications need to make sure that only one document per entity is indexed. This is important as it would not be very useful to have multiple search result for the same case.

The <identification/> node describes how to uniquely identify a Dovetail CRM entity in the index. During indexing three identifying index document fields are created: domain, id, and uri fields. Adding these standard identifying fields to each index document allow a single search index to contain many different types of entities while still be able to uniquely identify them in search results and during indexing.

Clarify Table Example

<identification displayName="solution" table="probdesc" idColumnName="id_number"/>

In this situation, the indexing applications know to create solution documents in the index that are identified by the id_number column on the probdesc table.

Search results matching solution documents will have the following identification fields:

Field Value Description
scheme dovetail Documents created for Dovetail CRM entities always have a scheme of dovetail.
domain solution The displayName of the specification.
id <'id_number' column value> Contains the value from the probdesc table's id_number column for the solution.

The contents of this field come from the database column name specified in the idColumnName attribute.

Note: The document specification must be configured so that documents generated are unique. You should make sure you specify an idColumnName for the object being indexed that is unique.
uri dovetail://solution/ To uniquely identify each document, the three identifying fields above are formatted into this single field.
Clarify View Example

<identification displayName="site" table="site_view" idColumnName="site_id"/>

In this situation, the indexing applications know to create site documents in the index that are identified by the site_id column on the site_view view.

Search results matching site documents will have the following identification fields:

Field Value Description
domain site The display name of the specification.
id <'site_id' column value> Contains the value from the site_view view's site_id column for the solution.

The contents of this field come from the database column name specified in the idColumnName attribute.

Note: The document specification must be configured so that documents generated are unique. You should make sure you specify an idColumnName for the object being indexed that is unique.
uri dovetail://site/ To uniquely identify each document, the three identifying fields above are formatted into this single field.

Note: When using a Clarify view as the base "table" of a document specification, required and custom field paths cannot traverse relations.

Required Fields

There are three required fields: title, summary, and contents.

Example Required Fields

Here are the required fields for the solution document specification:

<title xml:space="preserve"><path>title</path></title>
<summary xml:space="preserve"><path>description</path></summary>
<contents>
  <path>id_number</path>
  <path>title</path>
  <path>description</path>
  <path>probdesc2workaround:description</path>
</contents>
Search Result Fields

The title and summary fields will always be returned with search results. Depending on how you are displaying search results the formatting of the title and summary fields may be important. Notice the xml:space attribute which tells the XML parser to preserve the whitespace of the title and summary field specifications.

Content Field

The content field is very important as it is the default field used when searching your index. The contents field should contain all details about an entity that you wish to be searchable by default. The data indexed for the content field is not stored in your search index as it can get quite large and is not intended to be displayed to the search user.

Note: When using a Clarify view as the basis of a document specification, field paths cannot traverse relations.

Custom Fields

Custom fields are extra aspects of the entity you wish to be searchable. Custom field values are not returned with search results unless you request the search web service to do so.

<customField title="public">
  <path>public_ind</path>
</customField>

With this field in place, a search query can now filter out private solutions. Here is an example of a search for a solution using the public custom field:

>SeekerConsole.exe --search "domain:solution AND public:1"

The case specification shipped with Dovetail Seeker has a few more examples:

<customField title="part">
  <path>case_prt2part_info:part_info2part_num:part_number</path>
  <path>case_prt2part_info:part_info2part_num:description</path>
</customField>
<customField title="site">
  <path>case_reporter2site:name</path>
</customField>
<customField title="contact">
  <path>case_reporter2contact:first_name</path>
  <path>case_reporter2contact:last_name</path>
</customField>

These custom fields allow you to search for cases related to a particular part, reported by a site, or by a contact's name. Here is a more complex example that searches multiple fields:

>SeekerConsole.exe --search "(part:Seeker AND site:Dovetail) OR contact:Jones"

Note: When using a Clarify view as the basis of a document specification, field paths cannot traverse relations.

Storing Field Values

By default custom field values are stored in the index making them available when requested in search results. If custom search result values are not needed it is possible to reduce the size of your search index by turning off for your custom fields.

<customField title="site" isStored="false">
  <path>case_reporter2site:name</path>
</customField>

In this example the isStored attribute of the customField element is set to false. Telling the indexer that these field values should not be copied into the search index.

Tokenizing Field Values

By default custom field values are tokenized to best allow the indexer to do its work. This is usually the desired behavior. However when sorting search results by custom fields it is required that the custom field should not be tokenized.

This can be accomplished by setting the optional isTokenized attribute on the customField element to false.

<customField title="contactSortOrder" isTokenized="false" isStored="false">
  <path>case_reporter2contact:last_name</path> <path>case_reporter2contact:first_name</path>
</customField>

In this example a custom field is being added to be used for sorting search results by a contact last and then first name. Notice that this field is not stored in the index as its only reason for existence is for search result sorting.

Description and Tags Field Values

Like document specifications custom field specifications can have description and tags attributes used to describe and categorization of the custom field. This information is relayed to the search client when Document Specifications are retrieved.

<customField title="created" description="Date the case was created." tags="rangeable,date">
  <path>creation_time</path>
</customField>

The Description could be used by a dynamic search client to communicate to the user what this custom field is intended to search for. The Tags field could be used to create a taxonomy of search fields. In the example above we are tagging the field as a date and informing the client that range queries would work well with this field.

Paths

Paths are used within document fields to populate the search index with data about the Dovetail CRM entity being indexed. Paths start from a base table and walk across entity relations until they end up at a database column name.

Note: When using a Clarify view as the base table of a document specification, field paths can only be field names present on the base view.

All required and custom fields should contain one or more paths.

Path Examples

Below is an example of a path for a solution document specification.

<path>probdesc2workaround:description</path>

Notice that the path starts by traversing to a related workaround and resolving to the description field on the workaround table.

The following are legal paths that start from probdesc as the base table:

Path Description
title The title of the probdesc being indexed.
id_number The id_number of the probdesc being indexed.
probdesc2workaround:description The description of all the workarounds that are related to the probdesc being indexed.
probdesc2workaround:resolution2gbst_elm:title The title of the resolution of all the workarounds that are related to the probdesc being indexed.

Paths that expand to have more than one value (one to many relationships) will have all related values put into the field.

Paths Can Be Mixed With Text

It is perfectly fine to mix paths with text. Here is an example of the required field summary for a case document specification:

<summary xml:space="preserve">Case title: <path>title</path>
Owner: <path>case_owner2user:login_name</path>
</summary>

Notice the use of xml:space to preserve white space within the summary field. Without the xml:space attribute it is possible that any whitespace present could be ignored.

Multiple Paths

It is allowed and common to have many paths per specification. Below is an example search contents specification for a case:

<contents>
  <path>id_number</path>
  <path>title</path>
  <path>case_history</path>
</contents>

Notice how the content specification has multiple path elements each mapping to a field on the case table.

Note: If you are familiar with creating properties for rules in Dovetail RuleManager, you are likely familiar with paths.