Administering Search Attributes and Features

Aptify provides robust search functionality that allows users to search for records within a particular service using several different query techniques and methods. Administrators can control the behavior of many search features including configuring full-text indexing for certain entities. This topic includes the following sub-topics that describe how administrator can configure search behavior in Aptify:

• Defining Which Fields To Search for Basic Finds
• Defining the Sort Order for Entity Find Results
• Enabling the FindRequiresFilter Attribute
• Setting the Find Search Type Attributes
• Setting the View and Find Suggested Value List Attributes
• Configuring Full Text Searches in Aptify

Defining Which Fields To Search for Basic Finds

By default, Aptify's Basic Find dialog searches for a record within a service based on the record's name (the first Is Name field in the entity's field sequence) or ID. Alternatively, Aptify allows an administrator to configure a different field or full text search to be used as the basic search items.

To support this functionality, Aptify includes the FindBasicSearchItemsToSearch attribute (which can be added to the Configuration > Attributes tab of any entity) to control which items (fields or full text indexes) are searched when using the Basic Find dialog. The value for this new attribute is an XML fragment and must be entered using the following syntax:

Syntax for ItemsToSearch Attribute

<ItemsToSearch>

<Item Name="Name1" FilterType= "FilterType1" Operator= "Operator1"/>

<Item Name="Name2" FilterType= "FilterType2" Operator= "Operator2"/>

</ItemsToSearch>

Within the ItemsToSearch element, any number of elements can be defined. The Item Name element has three defined attributes:

• Name: The name of the field or the display name of the Full Text Index Filter, depending on the value of FilterType. The value for this attribute must match a field or full text index filter in the entity. This is a required attribute.
• FilterType: The type of filter. This is a required attribute. The following options are available:
  • Field: The value in the Name attribute must match the name of an entity Field within the entity.
  • FullTextIndex: The value in the Name attribute must match the display name of a Full Text Index Filter defined on the entity. 
• Operator: Defines the operator to use in the search. The value of this attribute must match the English language (default) text for an Operator that is supported for the field or full text filter that is being searched. For numeric fields, the numeric operators (like =, < and >) can also be used. This is a required attribute. The available operators are dependent upon the value of the FilterType (field or full text index) and the type of field (text, numeric and bit).

The following operators are available for text fields and full text indexes. Note that not all operators are available for both text fields and full text indexes (see each operator below for details).

• Exactly Matches: Field value exactly matches the characters entered in the Find Basic dialog. This operator is available for text fields only.
• Contains: Field value contains the characters entered in the Find Basic dialog. The characters can appear anywhere in the field. This operator is available for both text fields and full text indexes.
• Contains (Full Text): This is the same as Contains operator, however, this operator is available for full text indexes only.
• Begins With: Field value begins with the characters entered in the Find Basic dialog. This operator available for text fields only.
• Ends With: Field value ends with these characters entered in the Value column. This operator available for text fields only.
• FreeText: The value of a record's field must contain something similar to the character or phrases entered in the Basic Find dialog. This operator is available for the full text filter type.

The following operators are available for numeric fields only:

• = or Equals: The value of a record's specified field must equal the value entered in the Find Basic dialog.
• > or Greater Than: The value of a record's specified field must be greater than the value entered in the Find Basic dialog.
• >= or Great Than Or Equals: The value of a record's specified field must be greater than or equal to the value entered in the Find Basic dialog.
• < or Less Than: The value of a record's specified field must be less than the value entered in the Find Basic dialog.
• <= or Less Than Or Equals: The value of a record's specified field must be less than or equal to the value entered in the Find Basic dialog.
• <> or Does Not Equal: The value of a record's specified field must not equal the value entered in the Find Basic dialog.
• != or Does Not Equal: The value of a record's specified field must not equal the value entered in the Find Basic dialog.

The following fields are available for bit fields only:

• Is True: Bit is set to 1.
• Is False: Bit is set to 0.

Example

For the Persons service, you could define the following two search items to search on when the Basic find dialog is launched from the Persons service. The first item searches the Country field of the Persons records and returns those that begin with the value entered in Basic Find dialog. The second item searches the full text index that is defined on the Persons entity to search address lines. If an address line contains the value entered in the Basic Find dialog, it will be returned.

Example

<ItemsToSearch>

<Item Name="Name" FilterType="Field" Operator="Begins With"/>

<Item Name="Status" FilterType="FullTextIndex" Operator="Contains" Value="Approved"/>

</ItemsToSearch>

Defining the Sort Order for Entity Find Results

By default, find results are sorted by the entity's ID field is ascending order. However, in some cases, sorting by ID may not be appropriate. For example, it may make more sense to sort Companies record by the name of the Company. Therefore, Aptify allows an administrator to modify the sort order of find results when applicable.

Concerning Sub-Type Entities

This attribute is not applicable to sub-type entities.

This behavior is controlled by the FindOrderBySQL field which can be added to the Configuration -> Attributes tab of any Entities record. An administrator can define an unlimited number of sort order levels for a particular entity by modifying the sort criteria with the FindOrderBySQL attribute using the steps below:

1. Open or create a view within the Entities service.
2. Open the entity that you want to configure.
3. Select the Configuration tab.
4. Select the Attributes sub-tab.
5. Click the New icon to create a new Entity Attributes record.
6. Enter FindOrderBySQL in the Name field.
7. In the Value field, define the sort criterion, separated by a comma, using the syntax below:
   • First Level Field Name to Sort By DIRECTION(ASC|DESC), Second Level Field Name to Sort By DIRECTION(ASC|DESC), etc. 
   1. In the example below, the FindOrderBySQL has been added to the Persons entity. With these settings, the results returned when running a search for records in the Persons service are first sorted in ascending order by Last Name record and then in descending order by Title.
       
8. Click OK and Save and Close the entity record.

Enabling the FindRequiresFilter Attribute

By default, a user can use the Find dialog without any search criteria to display all records within a service. However, the system's response time may be slower than expected if there are a large number of records in the service. To improve system performance, an administrator can require users to enter at least one search filter before processing a find request.

To prevent users from running Find queries without any search criteria, you need to add the FindRequiresFilter attribute to the entity's. When set to 1, a user must provide a search filter. When set to 0 (and invalid value or if the attribute is not found on the entity), a user does not need to provide a search filter.  

Follow these steps to require users to provide at least one search filter through the FindRequiresFilter attribute:

1. Open the entity you want to configure.
2. Select the Configuration tab.
3. Select the Attributes sub-tab.
4. Click the New icon to create a new Entity Attributes sub-type record.
   • Or open the existing record for the FindRequiresFilter, if one already exists.
5. Enter FindRequiresFilter in the Name field.
6. Enter 1 in the Value field.
7. Click OK and Save and Close the entity record.

After adding this attribute, Aptify displays the following message to users who attempt to run Find queries without specifying search criteria: The Find operation for the current entity requires at least one filter.

Recommendations for Requiring Filter Criteria

Aptify recommends that administrators enable this functionality for all entities that have a large number of records. This will prevent users from running queries that return an excessive number of results.

Setting the Find Search Type Attributes

In the Desktop client, Aptify provides two different types of Find dialogs that users can use to search for records within a particular service; a basic search dialog that limits the search criteria to the name or ID of a record and an advanced search dialog that allows users to define multiple filters on multiple fields within the service. By default, Aptify's basic Find dialog is opened when searching for records throughout the Aptify system. A user can access the advanced search option by clicking the link to the right of the search text field, however, there may be cases when having the advanced find dialog open by default is more appropriate. Therefore, Aptify allows an administrator to configure the find dialog that is opened when performing search operations on a global or per-entity basis.

Default Behavior of the Find Search Type Attribute

By default, the Aptify's basic Find dialog is used for all records within the system.

This behavior is controlled by the FindSearchTypeGlobalDefault attribute found on the Configuration > Attributes tab of the Entities entity.

• The possible values for this attribute are Basic (open the basic search dialog for all searches throughout the system, which is the default value) and Advanced (use the advanced search dialog for all searches within Aptify).
• If this attribute does not exist on the Entities entity (or has an invalid value), the basic find dialog will be displayed.

You can modify this attribute at the global level as necessary based on the system functionality desired. In addition, you can add the FindSearchType attribute to any entity to control which search dialog is opened when searching for records within a particular service.

• The possible values for this attribute are Basic (open the basic search dialog when performing searches for records within the particular service) and Advanced (use the advanced search dialog when performing searches for records within the particular service).

• If the FindSearchType attribute exists for an entity, then the find dialog specified within the attribute will be used. If an attribute does not exist for an entity (or has an invalid value), the global find dialog setting will be used.
   

See Using the Find Dialog for details about Aptify's Find dialogs.

Setting the View and Find Suggested Value List Attributes

When a user works with filters in the Find dialog and views, Aptify can automatically populate the filter's Value field with a suggested value list of the first 100 possible values that exist in the database. However, in some situations, this feature may not be valuable or decrease the performance of the system. Therefore, Aptify allows an administrator to configure this behavior on a global or per-entity basis. This behavior is controlled by two entity attributes for the Entities entity (found on the Configuration > Attributes tab):

Default Behavior of the View and Find Suggested Value List Attributes

By default, the Suggested Value list functionality is enabled for all view filters and disabled for all find filters.

• GlobalViewFiltersSuggestedValueLists: This attribute is set to On by default. It is a system-wide setting to control whether or not the Filter Control Value Drop Down Lists will be filled with up to 100 values pulled from the database. The possible values for this attribute are Off (do not retrieve suggested values), Per Entity (only retrieve suggested values when a particular Entity has the ViewFiltersSuggestedValueLists attribute defined with a value of On.), and On (always attempt to retrieve suggested values).
• GlobalFindSuggestedValuesLists: This attribute is a system-wide setting to control whether or not the Find Filters Drop Down Lists will be filled with up to 100 values pulled from the database. The possible values for this attribute are Off (do not retrieve suggested values), Per Entity (only retrieve suggested values when a particular Entity has the FindSuggestedValueLists attribute defined with a value of On.), and On (always attempt to retrieve suggested values). This attribute is set to Per Entity by default but no entities have a corresponding FindSuggestedValueLists attribute by default so it is effectively disabled.

You can modify these two global attributes as necessary based on the system functionality desired. In addition, when one or both of the attributes is set to Per Entity, you can add the following attributes to one or more entities to limit the locations where this functionality is available:

• ViewFiltersSuggestedValueLists: This is an entity-specific attribute you can add to any Entities record's Configuration > Attributes tab to turn on the Filter Control Value Drop Down list for views of that particular entity. When adding this attribute to an entity, set the value to On. Note that using this attribute assumes that GlobalViewFiltersSuggestedValueLists attribute is set to Per Entity.
• FindSuggestedValueLists: This is an entity-specific attribute you can add to any Entities record's Configuration > Attributes tab to turn on the Find Filters Value Drop Down list for Find dialog filter operations for that particular entity. When adding this attribute to an entity, set the value to On. Note that using this attribute assumes that GlobalFindSuggestedValuesLists attribute is set to Per Entity.

Configuring Full Text Searches in Aptify

Utilizing Microsoft's SQL Server®  full text query functionality, full text searches provide fast and flexible indexing for keyword queries of character-based data stored in the Aptify database. With this functionality, users can search for records that contain particular words and phrases or multiple forms of a word or phrase. Users can also use the full text search functionality to create powerful filter statements for views. These full text queries can even perform linguistic searches based on rules for a particular language.

In Aptify, full text searches utilize indexes to store information about keywords and their location within the database, specifically a given column within an entity. Full text indexing allows character-based data to be pre-processed for rapid searching at a later time. Indexes are logically grouped into catalogs and filters are added to entities within Aptify so that users can use the configured indexes to perform full text searches on particular services within Aptify. Before users can perform full text searches, an administrator must create and configure these items.

Follow the steps in the following sub-topics to configure full text searching within Aptify.

Full text search is an optional component of SQL server that can be included during the install of SQL server or after installation by using the SQL installation software. See Microsoft SQL Server Books Online for more information on installing and enabling full text indexing for the Aptify instance.

• Creating a Full Text Catalog
• Creating Full Text Indexes
• Configuring Full Text Indexes Filters
• About Performing Full Text Searches in Aptify

Creating a Full Text Catalog

Full text indexes are logically grouped together in full text catalogs. Each full text index must belong to a full text catalog. Follow the steps below to create a new Full Text Catalog record:

1. Open a new record from the Full Text Catalogs service.
2. Enter a Name for the catalog.
3. Select the name of the database instance where the catalog should reside in from the Database drop-down.
4. If this catalog is the default full text catalog, place a check mark in the Is Default check box.
5. If this catalog will include indexes that are based on a particular language that is accent sensitive, place a check mark in the Is Accent Sensitive check box.
   
   
6. Save the record.

Once the record is saved the following conditions are met:

•  The Name and Database fields on the General tab are disabled and cannot be modified.
• The Full Text Indexes and Attachments tabs are enabled.
  
  
  
  

Configuring Full Text Indexes Filters

Once a full text index has been configured, an administrator defines which services can utilize the full text indexes, which related fields to include and which fields to search within the index. For example, if an index has been created for the Addresses entity for address lines, an administrator could add a filter to the Persons entity so that users could full text search addresses within this entity. An administrator could further refine the search filter by only allowing the full text search to be performed on business addresses and address line 1.

1. Open or create a view within the Entities service.
2. Double-click the entity you want to configure.
3. Select the Configurations tab.
4. Select the Full Text Index Filters sub-tab.
5. Click the New icon to create a new Full Text Index Filters record.
6. Select the index from the Full Text Index Filter drop-down list.
7. Enter a Display Name.
   • This is the name that is displayed when using the Find dialog or filtering a view for the particular entity.
   • If you have more than one filter for a particular entity, the display name for each filter must be unique. 
8. Enter a culture string to use as the display name of the index filter in the Display Name Culture String field if you want to localize this filter.
9. Select the Description tab and enter a description for the search as desired.
   • This is the description that is displayed in the Description field when using the Find dialog or filtering a view for this entity. 
10. Select the Related Entity Fields tab.
11. Enter the list of related entity fields in which you want to be able to search, separated by commas.
    • For example, addresses are shared between multiple services in Aptify through the Addresses entity. In the Persons entity, AddressID, BillingAddressID and HomeAddressID fields are used to link Persons records to their business, billing and home addresses. Adding these related entity fields to this tab as shown below allows user to perform full text searches on these types of addresses.
      
       
12. Go to the Search Fields tab.
13. Enter the list of fields that you want users to be able to search within the index separated by commas.
    • For example, if you have created an index for the Addresses entity that indexes the address line fields (Line1, Line2, and Line3). You could limit searches to the first and second address lines only as shown below.
    • The default value is an asterisk *; which indicates all fields including in the index will be searched.
      
       
14. Click OK to close the record.
15. Add additional full text index filters as desired following the Steps 4 through 14 above.
    • Alternatively, you can click the OK and New to save the record and open a new Fields record in one step. 
16. Save and close the entity.

About Performing Full Text Searches in Aptify

Once full text indexing has been configured, users can perform full text queries against the Aptify database for entities configured to use full text indexes. Full text searches can be performed to find records within a particular service and can also be used to create filter statements for views.

• See Performing Full Text Searches from the Find Dialog for more information about performing full text searches with the Find dialog. 
• See Defining Full Text Based Filters for Views for more information about performing full text searches with views.