The highlight queries configuration file

<highlightQueryConfiguration> is the root element of the highlight query configuration file. In the examples, and in the automatically generated file, it references the highlight-queries-configuration.xsd file:

<highlightQueryConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="highlight-queries-configuration.xsd">
  ...
</highlightQueryConfiguration>

• <maxLinkResultsPerSegment> - The maximum number of link records that a single segment can match in the Information Store, which defaults to 50000.
• <maxSeedsPerSegment> - The maximum number of entity records that any segment except the last can match in the Information Store, which defaults to 1000.
• <maxResultsPerQuery> - The maximum number of entity records that the last segment can match in the Information Store, which defaults to 1000.
• <expireResultsInMinutes> - The length of time for which the server caches the results of a highlight query, which defaults to 30 minutes.

<highlightQueryConfiguration ...>
  <settings>
    <maxLinkResultsPerSegment>50000</maxLinkResultsPerSegment>
    ...
  </settings>
  ...
</highlightQueryConfiguration>

If any of the "max" limits is breached, the query in question returns no results and the user sees an error message. Other queries that do not breach the limits continue to run normally.

The only other element permitted as a direct child of <highlightQueryConfiguration> is <highlightQueryGroups>, which contains all the highlight queries for the deployment, grouped by the entity types of the subject records to which they apply.

<highlightQueryConfiguration ...>
  <settings>...</settings>
  <highlightQueryGroups>
     ...
  </highlightQueryGroups>
</highlightQueryConfiguration>

Each highlight query group contains the highlight queries for subject records of a particular type. The itemType attribute of the <highlightQueryGroup> element indicates which type the group is for. The valid values for the itemType attribute are defined in the XSD file; they are based on the display names of entity types in the Information Store schema.

  <highlightQueryGroups>
    <highlightQueryGroup itemType="Vehicle-I">
      ...
    </highlightQueryGroup>
    ...
  </highlightQueryGroups>

A <highlightQueryGroup> element can have multiple child <highlightQuery> elements. Each <highlightQuery> element defines a query to run against the Information Store, and controls some aspects of the highlight pane that displays the query results in the user interface.

The <highlightQuery> element supports the title attribute whose value is displayed as the title of the highlight pane. It also supports the automatic attribute that determines whether the query runs as soon as a user views the subject record. You can specify that users must run a time-consuming query manually (by clicking a button) by setting the value of this optional attribute to false.

The last permitted child of a <highlightQuery> element is <sortBy>. This optional (but important) element specifies how values that were discovered during execution of the query can change the results that users see. For example, depending on your investigation, you might sort a list of people who are associated with a vehicle by their family names or by their dates of association.

The <field> children of <sortBy> are processed in order of appearance. In each one, the id attribute contains the identifier of a field that was exported from the path. The order attribute determines whether results appear in ascending (ASC) or descending (DESC) order of the values of the identified field.

    <highlightQueryGroup itemType="Vehicle-I">
      <highlightQuery title="People with access" automatic="true">
        <description>People who have access to this vehicle,
          sorted by family name.</description>
        <path>...</path>
        <sortBy>
          <field id="familyName" order="ASC"/>
        </sortBy>
      </highlightQuery>
      ...
    </highlightQueryGroup>

<path> elements always have exactly two children: <segments> and <outputs>. <segments> always contains at least one <segment> element that defines a part of the query structure.

        <path>
          <segments>
            <segment>
              ...
            </segment>
            ...
          </segments>
          <outputs>
            ...
          </outputs>
        </path>

Each <segment> element also has exactly two children that specify the link and entity types that records must have in order to match this part of the query. Like the legal values for the itemType attribute of the <highlightQueryGroup> element, the names of these elements are not fixed but depend upon the Information Store schema for the deployment. Furthermore, the link type must be valid for the entity type that you specified in <highlightQueryGroup>, and the entity type must be valid for that link type. For example, a segment for people who have access to vehicles:

      <highlightQuery title="People with access">
        <path>
          <segments>
            <segment>
              <Access_To-I/>
              <Person-I/>
            </segment>
            ...

It is valid to use <AnyLinkType/> in place of a specific link type from the schema. It is also valid to use <AnyEntityType/> in place of a specific entity type, in any segment except the last one in the path.

The previous example contains a functionally complete segment definition. In a highlight query, the segment finds all the people in the Information Store that are connected to the inputs by 'Access To' links. If the segment is the first in the path, its single input is the subject record. Otherwise, its inputs are the records that the previous segment found.

The "entity type" and "link type" elements that make up a segment support three child elements, all of which are optional. To place further constraints on the records that the segment matches, you can add a <direction> or a <conditions> element. If you want to use some values from the records that you find at this stage of the query to provide context for the final results, you can add an <exportFields> element.

For link type elements only, you can constrain matching records according to whether their direction is towards or away from the entity record that forms the input to the segment. The <direction> child of a link type element always contains a single <value> child element whose text content is either INCOMING or OUTGOING.

A constraint of this type is often useful in scenarios such as telephone call analysis or financial investigations, where the direction of a link is key to determining its relevance.

You might want to export values from a segment of a highlight query for two reasons. First, to display those values to users alongside the results in the highlight pane for the query. Second, to use the values as criteria by which to sort the results of the query.

For a particular highlight query result, the values that you can export are the values of properties from the segments that contributed to that result. For example, imagine a query that finds bank account records that are connected through transaction links. You want to display the transaction dates from those links alongside the found accounts. In this example, every account is connected to the subject record through different links from every other account. If you export the date from the link type, each result sees a date value that comes from its particular links.

          <segments>
            <segment>
              <Access_To-I>
                <direction>...</direction>
                <conditions>...</conditions>
                <exportFields>
                  ...
                </exportFields>
              </Access_To-I>
              <Person-I/>
            </segment>
            ...

The <exportFields> element supports any number of two child element types: <propertyField> and <countField>.

• propertyType - The property type whose value you want to export from the segment. Valid values for this attribute depend on the current entity or link type and are defined in the XSD file. These values are based on the display names of property types in the Information Store schema.
• aggregatingFunction - For any particular result, it is possible for a segment to match multiple records. The aggregating function specifies what property value to use when that situation arises. Set the attribute value to MAX or MIN to select the highest or lowest property value from such a set. Alternatively, set the value to SUM to add the property values from all the matching records together.
• id - An identifier for the exported value that you can use to refer to it from elsewhere in the highlight query structure.

              <Access_To-I>
                <direction>...</direction>
                <conditions>...</conditions>
                <exportFields>
                  <propertyField id="typeOfUse" propertyType="type_of_use-P"
                    aggregatingFunction="MAX"/>
                  ...
                </exportFields>
              </Access_To-I>

As well as using <propertyField> to export the highest, lowest, or total value of a property from a set of records, you can use <countField> to export the number of records in that set. Returning to the example of linked accounts, it might be useful to tell users how many transactions took place between the subject and each result, or to sort the results by that number.

The <countField> element has a single mandatory attribute: id, which behaves exactly as it does in <propertyField>.

• id - The identifier of an export field, as previously specified in a <propertyField> or <countField> element.
• label - A value that the user interface uses as a column header for the field.

        <path>
          <segments>
            <segment>
              ...
            </segment>
            ...
          </segments>
          <outputs>
            <field id="typeOfUse" label="Type of use" />
            ...
          </outputs>
        </path>

Each highlight pane has space for up to two output fields. If you specify more than two <field> elements, users see them only when they click Show more in the highlight pane to display more result information.

Inside an <EntityType> or <LinkType> element, the <conditions> element can contain any number of child elements whose names are based on property types from the Information Store schema. The child elements restrict the records in the Information Store that match the current segment. The permitted contents of the condition depend on the logical type of the property type.

              <Access_To-I>
                <conditions>
                  <type_of_use-P>
                    ...
                  </type_of_use-P>
                  ...
                </conditions>
                ...
              </Access_To-I>

Some logical types - geospatial values, multiple-line strings, documents, pictures, and XML data - are not supported in highlight query conditions. According to the generated XSD file, property types with unsupported logical types are not valid children of <conditions> elements. For property types with supported logical types, this version of i2 Analyze supports conditions with four kinds of operators:

• For all valid property types, you can use <isSet> and <isNotSet> elements to specify that matching records must (or explicitly must not) have a value for the property with that type.

                  <conditions>
                    <type_of_use-P>
                      <isSet/>
                    </type_of_use-P>
                    ...
                  </conditions>

• For property types whose properties have string values, you can use <equalTo> and <notEqualTo> elements to specify that matching records must have a value for the property that exactly matches (or explicitly does not match) values that you provide.

                  <conditions>
                    <type_of_use-P>
                      <notEqualTo>
                        <value>Passenger</value>
                        ...
                      </notEqualTo>
                    </type_of_use-P>
                    ...
                  </conditions>

• For property types whose properties have numeric values, you can use <greaterThan>, <lessThan>, <greaterThanOrEqualTo>, and <lessThanOrEqualTo> elements to specify that matching records must have a property value with the specified relationship to a value that you provide.

                  <conditions>
                    ...
                    <transaction_value-P>
                      <greaterThan>
                        <value>50000</value>
                      </greaterThan>
                    </transaction_value-P>
                    ...
                  </conditions>

• For property types whose properties have date and time values, you can use an <inThePreceding> element to specify that matching records must have a value for the property that occurred within a certain period before the current date.

                  <conditions>
                    <type_of_use-P>
                      ...
                    </type_of_use-P>
                    <end_date_and_time-P>
                      <inThePreceding unit="WEEKS">
                        <value>6</value>
                      </inThePreceding>
                    </end_date_and_time-P>
                    ...
                  </conditions>

  In <inThePreceding> elements, the <value> must be an integer, while the unit attribute can be one of WEEKS, MONTHS, or YEARS.

If you specify multiple property types in the same <conditions> block, their effects are ANDed together. For example, if your conditions are "given name equal to 'John'" and "family name equal to 'Doe'", then only records for which both conditions are true appear in the results.

Conversely, if you use multiple operators against the same property type, their effects are ORed together. For example, you might decide that a property must either be not set or have one of a handful of values. However, you cannot use the same operator more than once, and you cannot use more than one of the numeric operators at the same time. Attempting to do either results in an invalid configuration file.