HPRM saved search

The HPRM saved search asset allows you to configure a set of HPRM search criteria in Matrix, storing and updating the results of the search on the system. These results are stored as data source record set shadow assets and can be used with other Matrix assets to provide additional HPRM functionalities.

An HPRM saved search should be created within a site with an assigned URL. HPRM saved search assets without a URL will not function correctly.

Once created, you can configure the settings of your HPRM saved search on its associated asset screens. These screens are similar to those for a standard page. They are described in the Asset screens documentation. This documentation will describe the Details screen, which is different for an HPRM saved search.

Details screen

The Details screen for the HPRM saved search allows you to configure the asset.

Read the Asset screens documentation for more information about the Status, Future status, Thumbnail, and Details sections

Connection setup

This section allows you to configure the connection to the HPRM system, creating the HPRM bridge for the saved search.

The fields available in this section are as follows:

Service URL

Enter the URL to the API of the HPRM system.

Username

Enter the username used to connect to the HPRM system.

Password

Enter the password used to connect to the HPRM system. This password must be Entered twice for validation purposes

Authentication method

Select the authentication method to use to connect to the HPRM system. The options available are:

HTTP basic

Uses basic HTTP authentication.

NTLM

Uses NTLM authentication.

Use a connector asset

This section allows you to select an HPRM connector with a configured connection to the HPRM system, creating the HPRM bridge for the saved search.

In the HPRM connector asset field, select a configured HPRM connector to use as the HPRM bridge for the saved search.

If an HPRM connector has been selected in the HPRM connector asset field, the Connection setup section fields have no effect and do not need to be completed.

Synchronize options

This section allows you to manage the results of the HPRM saved search.

The fields available in this section are as follows:

Download files

Select whether to enable the downloading of attachments of record sets. Attachments are the electronic documents of a record, such as a text file. If this option is set to Yes, the attached documents of the listed HPRM records will be available to download. By default, this field will be set to No.

File size download limit

Enter a size limit (in bytes) of attachments downloaded to Matrix on the HPRM saved search. By default, this option will be set to 4194304 bytes (4mb).

Synchronize timeout

Specify a time limit (in seconds) for the synchronization process of the HPRM connection. If this process exceeds this limit, the HPRM saved search will display a warning. By default, this option will be set to 7200 seconds.

Download timeout

Specify a time limit (in seconds) for the downloading of attachments on the HPRM connection. If the download process for an individual file exceeds this limit, the HPRM saved search will display a warning. By default, this option will be set to 3600 seconds.

Check update

This field allows you to check the record set results of the saved search for any new updates and synchronize them accordingly. The Check for updates button will check the results for updates, displaying the message '<#> out-of-date records' when updates are available. If this message is displayed, clicking the Synchronize now button will update the saved search results. Once this is done, the message 'Successfully synchronized' will be displayed. If no updates are available, the message 'No update is required' will be displayed when the Check for updates button is clicked.

Retrieve fields from server

This section allows you to request standard and additional metadata fields from the connected HPRM server. These fields can then be used in search queries for the HPRM saved search.

To retrieve these fields, then select Retrieve now; a message will be displayed totaling the number of standard and additional fields that have been retrieved, as shown in the figure. If no fields can be retrieved or the HPRM saved search is not connected to an HPRM server, the message 'Empty' will be displayed.

Fields that have been retrieved will now be available for selection in the search fields and result fields sections of the Details screen.

Search fields

This section allows you to configure search clauses on specific metadata fields of the records on the HPRM system. These queries are constructed in groups of search clauses that can be linked with different search logic to determine the search parameters.

To add a new group, select a search field in the -- Add search field -- list under the Add search field in a new group field. Once you have selected a field, select Save. A new group will be created, and additional fields will be available for configuring the query.

You can add additional metadata fields for selection to the -- Add search field -- list using the Retrieve now button. If no additional fields have been retrieved, this list will only display the default fields for the HPRM saved search. Read the Retrieve fields from server section in this documentation for more information.

To add additional search fields to a group:

  1. Select a field in the -- Add search field -- list located under that group in the Search fields table.

  2. Once you have selected a field, select Save.

The New search field will be created in the group.

These search clauses are configured using the settings in the Search fields table.

The fields available are as follows:

Group

The group that is being configured.

Name

The search field that is being configured.

Keyword

Enter a keyword to query the specified metadata field on records in the HPRM system. For example, if you are configuring the Titleword field, entering meeting as the keyword will search for records that contain meeting in their title. You can use wildcards in this field. For example, using * will match on any value for the specific field.

Delete (under search field)

To delete a search field, select the Delete box and select Save.

Group logic

Select the search logic to use for the search fields in a group. The options available are:

And

Select this option if all search field queries in the group must be met on the results of The HPRM saved search.

Or

Select this option if at least one of the search field queries in the group must be met on the results of the HPRM saved search.

For example, in the figure above, the And logic is used, meaning that only HPRM records that contain both meeting and agenda in their titles will be returned. If the Or logic was selected, records that contained at least one of the keywords would be returned as results.

Deleted (under group)

To delete a group, select the Delete box and select Save.

Global logic

Select the search logic to use for the groups. The options available are:

And

Select this option if all group queries must be met on the results of the HPRM saved search.

Or

Select this option if at least one of the group queries must be met on the results of the HPRM saved search.

Global logic is used solely on a global level; individual group logic will be maintained when using multiple groups. The figure below shows how the group and global logic work together within the HPRM saved search.
The group and global search logic

Result fields

This section allows you to select the metadata field information that will be returned on record results of the HPRM saved search.

Only metadata information returned on results can be used within Matrix. For example, if Record number is not selected in this section, you will not be able to use the %ds__recnumber% keyword replacement to call this information.

By default, the result fields listed in this section are:

  • Title

  • Record number

  • Record type

  • Document type

  • Creator

To add additional result fields to return in the search, select a field from the -- Add result field -- list and select Save.

You can add additional metadata fields for selection to the -- Add result field -- list using the Retrieve now button. If no additional fields have been retrieved, this list will only display the default fields for the HPRM saved search.

Read the Retrieve fields from server section in this documentation for more information.

In the Use local time field, select whether to convert returned date values stored in UTC (GMT) format to the local time zone of the system.

You can customize the output of these date formats using the date_format keyword modifier (for example, %Ds__reccreated^date_format:y% will print the full numeric representation of a year, in local time).

Read the Concepts documentation for more information.

Classification options

This section specifies an HPRM classification to which the saved search results are restricted. For example, you could restrict search results to only contain records that have the projects classification.

The fields available are as follows:

Classification

Enter the HPRM classification classification by which to restrict the saved search results. You can also include sub-classifications with these classifications (for example, RESEARCH - PROJECTS).

Include sub-classifications

Select whether to restrict the specified classification to return only top-level records or also to include the records of sub-classifications.

General search options

This section determines the general search options for the HPRM saved search.

In the general options and record type filter sections, define the search options using the following fields:

Search parent container

Enter the parent container to search in. For example, entering 09/1 into this field will only search the 09/1 container of the HPRM system.

Filetypes

Enter a file extension to limit the saved search results to that specific file type. For example, entering PDF into this field will only return HPRM records of the PDF file type.

Limit

Enter the maximum number of record set assets that will be listed as results of the saved search. For example, if 10 is entered into this field, only the first ten results will be listed. By default, 30 is entered into this field.

Search sort 1

Select a field as the first preference for sorting the saved search results. For example, if dateCreated is selected, the record set assets will be listed by their creation date. By default, none is selected in this field, meaning the assets will not be sorted.

Search sort 2

Select a value as the second preference for sorting the saved search results. This preference will be used for record set assets with the same value for the field selected in the Search sort 1 field. For example, if the Search sort 1 field was set to dateCreated, results in the saved search with the same creation date will be listed by the Search sort 2 field. By default, none is selected in this field, meaning these assets will not be sorted.

Search sort 3

Select a value as the third preference for sorting the saved search results. This will be used for record set assets with the same values for the fields selected in both the Search sort 1 and Search sort 2 fields. By default, none is selected in this field, meaning these assets will not be sorted.

Sort 1 descending

Select whether the results sorted by the field selected in the Search sort 1 field will be sorted by descending order. By default, this field is set to No.

Sort 2 descending

Select whether the results sorted by the field selected in the Search sort 2 field will be sorted by descending order. By default, this field is set to No.

Sort 3 descending

Select whether the results sorted by the field selected in the Search sort 3 field will be sorted by descending order. By default, this field is set to No.

Record type filter

Select record types from the add record type list to restrict retrieved records to specific types. For example, a saved search can be configured only to return document types or configured to return both document and folder types only.

Record set asset names

This section allows you to select how the record set results appear in the asset tree.

In the Record set asset names field, enter a string to use as the asset name for the record set results of the saved search. Keyword replacements can be used in this section. For example, if the keyword replacement is entered into this field, the record set assets will be named after their document type, such as TIF image. If this field is left blank, the record sets will be named Data source record set <assetID>.

For a list of available keyword replacements, refer to the Available keywords section below.

Available keywords

This section lists the available keyword replacements for record set assets of a saved search determined by the attributes of the record sets in the HPRM system. These keyword replacements can be used either in the record set asset names field or when listing the saved search results on an HPRM record listing.

These keyword replacements will differ depending on the available attributes of the HPRM system, and, as a result, they will only appear once an HPRM bridge has been established and committed in either the Connection setup or Use a connector asset sections. When an HPRM saved search is first created, the Available keywords field will read; 'No keywords available – this data source, as currently configured, does not have any record sets'.

Data source record set

HPRM records found as results of the saved search are displayed as data source record set assets under the HPRM saved search asset in the asset tree.

Read the Asset screens documentation for more information about the Status, Future status, Thumbnail, and Details sections.

User details

The section displays the details of the record set as configured in the record operations options. The URI and Version fields are standard fields in this section, as is the document_url field if the record set has an attachment. To display additional fields, they must be selected in the Fields field of the search default options. The User details section with user-defined fields is shown in the figure.

The user details section displaying the standard and user-defined fields
HPRM documents specified as data source assets in Matrix are updated and downloaded automatically by the update HPRM cron job. This job is set to run on a nightly basis by default but can be configured to run at different times on the Details screen of the job.