The highlight queries configuration file

Root element

<highlightQueryConfiguration>

<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>

Top-level elements

<settings>

As well as the highlight queries themselves, the configuration file enables control of some aspects of highlight query behavior that can affect the performance of the i2 Analyze server. The optional <settings> element supports the following child elements:

• <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.

<categoryDefinitions>

Optionally, you can control which users see a highlight query by putting it into one or more categories. A category specifies the user groups whose members can see the highlight queries it contains. To use categories, you define them at the top of the highlight queries configuration file, and then apply them to highlight query definitions.

When present, the <categoryDefinitions> element is a child of the <highlightQueryConfiguration> element:

<highlightQueryConfiguration ...>
  <settings>...</settings>
  <categoryDefinitions>
    ...
  </categoryDefinitions>
  ...
</highlightQueryConfiguration>

When the <categoryDefinitions> element is not present, all highlight queries are visible to all users who can see the types for which they're defined.

<highlightQueryGroups>

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>
  <categoryDefinitions>...</categoryDefinitions>
  <highlightQueryGroups>
     ...
  </highlightQueryGroups>
</highlightQueryConfiguration>

Category definition elements

<categoryDefinition>

The <categoryDefinitions> element can contain any number of <categoryDefinition> children, each of which must have a name and can have a list of "allowed" user groups.

  <categoryDefinitions>
    <categoryDefinition name="Finance">
      <allow>
        <userGroup name="Analyst"/>
        <userGroup name="Clerk"/>
      </allow>
    </categoryDefinition>
    ...
  </categoryDefinitions>

The name of each category definition must be unique; it's used later in the file to put highlight queries into categories. A category definition without a child <allow> element can still be used to categorize, but has no effect on the visibility of highlight queries.

<allow>

The single, optional <allow> element in each category definition specifies an OR'ed list of the user groups whose members can see the queries in the category. An empty <allow> element is equivalent to an absent one.

<userGroup>

The <userGroup> elements that form the list of allowed user groups have a single name attribute that must match the name of an i2 Analyze user group. This dependency is validated at server startup and when the live highlight queries configuration file is modified.

Highlight query elements

<highlightQueryGroup>

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>

<highlightQuery>

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.

<categories>

The optional <categories> child of a <highlightQuery> element is the mechanism through which you put highlight queries into categories. If the <categories> element is absent or empty, then the query is not in a category, and it is available to all users.

All <category> children of the <categories> element must have a name attribute whose value matches the name of an earlier <categoryDefinition>.

When the highlight queries configuration file is processed, the categories are OR'ed together. The resulting behavior is that a highlight query is visible to users who are in any of the groups that appear in the definitions of any of the categories in this list.

<description>

In the <description> child of a <highlightQuery> element, you can explain the behavior of the query to users. The contents of this element are displayed to users when they click the information icon ( i ) in a highlight pane heading. At a minimum, i2 recommends that you describe the relationship of the results to the subject record, and the order that you chose to present them in.

<path>

The <path> child of a <highlightQuery> element contains <segments> and <outputs> elements that together provide the logic for the query. Segments are responsible for the query structure, while outputs determine how users see the query results in highlight panes.

<sortBy>

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">
        <categories>
          <category name="Finance"/>
          ...
        </categories>
        <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

<segments>

<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>

<segment>

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.

<EntityType>/<LinkType>

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.

<direction>

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.

<conditions>

The <conditions> child of an entity type or link type element can contain any number of child elements that correspond to property types of the entity type or link type in question. For each property type, you can place a requirement on the values that matching records must have.

Note: At this version of i2 Analyze, highlight queries do not support conditions on property types with geospatial or multi-line string logical types.

<exportFields>

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>.

<propertyField>

The <propertyField> child of the <exportFields> element has three mandatory attributes:

• 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>

<countField>

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>.

<outputs>

After the <segments> in the path are the <outputs>, which control the values that users see with the query results in a highlight pane. The <outputs> element supports any number of child <field> elements, which have two attributes:

• 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.

Condition elements

<PropertyType>

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>

Note: Conditions are valid in every segment of a highlight query. Adding a condition to the entity type element in the final segment has the effect of directly filtering the results that a user sees.

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.