Posted Feb 26 by Peng Qiu.
Updated Feb 26.

This is the last tutorial of Search Services Series in Documentum REST.

Last activity Feb 26 by Peng Qiu.
100 views. 0 comments.

Advanced Searches in Documentum REST Services (4): Search Templates

This is the last tutorial of Search Services Series in Documentum REST.

Overview

A saved search as we discussed in Part 3 is “fixed”. It means once a search is saved, the conditions in AQL like keywords, range or relative date, cannot be changed anymore. In many scenarios, users may want to change some pieces of attribute values or facets to customize the real time search. Search templates resource is introduced to bring this flexibility. You will learn how to create and execute a search template in this post.

Part 1. Advanced Searches in Documentum REST Services (1): AQL
Part 2. Advanced Searches in Documentum REST Services (2): Facets
Part 3. Advanced Searches in Documentum REST Services (3): Saved Searches
Part 4. Advanced Searches in Documentum REST Services (4): Search Templates

Here is a sample of a saved search, which has these conditions:

  • full-text keyword REST
  • object name starting with Doc
  • owner name is in the list [Administrator]
<!-- Saved Search Sample -->
<saved-search
    xmlns="http://identifiers.emc.com/vocab/documentum"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <properties>
        <object_name>A Saved Search Sample</object_name>
        <title>This will be a search template</title>
        <r_is_public>true</r_is_public>
    </properties> 
    <query-document>
        <search xmlns="http://identifiers.emc.com/vocab/documentum" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <types>
                <type>dm_document</type>
            </types>
            <expression-set operator="AND">
                <expressions>
                        <fulltext>REST</fulltext>
                    <property name="object_name" operator="BEGINS_WITH">Doc</property>
                    <property-list name="owner_name" operator="IN">
                        <values>
                            <value>Administrator</value>
                        </values>
                    </property-list>
                </expressions>
            </expression-set>
        </search>
    </query-document>
</saved-search>

What if users want to change the full-text term REST when executing it? This is actually what users can leverage search templates to do - substituting the term rest with any term like git or documentum during search execution, without changing the AQL on the server side.

Preliminary

Please refer to the Preliminary section in Advanced Searches in Documentum REST Services (1): AQL to prepare the environment.

Discover Search Template Resource

Since Documentum REST 7.3, Search Templates resource can be discovered in Repository resource with the link relation http://identifiers.emc.com/linkrel/search-templates.

<!-- Representation of Repository Resource -->
<?xml version="1.0" encoding="UTF-8"?>
<repository xmlns="http://identifiers.emc.com/vocab/documentum" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <id>2</id>
    <name>REPO1</name>
    ...
    <links>
        ...
        <link rel="http://identifiers.emc.com/linkrel/search-templates" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates"></link>
        ...
    </links>
</repository>

Create Search Template

Let's start with the below AQL. It's a normal AQL request except line 8. Please note at line 8, the fulltext expression has an attribute template=“true”. When this attribute is true, this expression is made as a template expression and its value can be externalized. In execution, users can specify a different fulltext term other than REST.

<!-- Template Enabled AQL -->
<search xmlns="http://identifiers.emc.com/vocab/documentum" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <types>
        <type>dm_document</type>
    </types>
    <expression-set operator="AND">
        <expressions>
            <fulltext template="true">REST</fulltext>
            <property name="object_name" operator="BEGINS_WITH">Doc</property>
            <property-list name="owner_name" operator="IN">
                <values>
                    <value>Administrator</value>
                </values>
            </property-list>
        </expressions>
    </expression-set>
</search>

A new search template is created by issuing the POST method to Search Templates resource.

POST /dctm-rest/repositories/REPO1/search-templates HTTP/1.1
Host: localhost:8080
Accept: application/xml
Content-Type: application/xml

<search-template
    xmlns="http://identifiers.emc.com/vocab/documentum"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <properties>
        <object_name>Search template sample</object_name>
        <subject>This is search template</subject>
        <r_is_public>true</r_is_public>
    </properties> 
    <query-document-template>
  ...
    </query-document-template>
</search-template>

——WebKitFormBoundary7MA4YWxkTrZu0gW–

Similar to a saved search, the properties for a search template are: object_name - search template name, subject - search template description and r_is_public - access control.

It's interesting to navigate into the response representation of search template. The representation has meta attributes, query document and an additional section - external-variables.

<?xml version="1.0" encoding="UTF-8"?>
<search-template xmlns="http://identifiers.emc.com/vocab/documentum" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="dmc_search_template" definition="http://localhost:8080/dctm-rest/repositories/REPO1/types/dmc_search_template">
    <properties>
        <object_name>Search template sample</object_name>
        <r_object_type>dmc_search_template</r_object_type>
        <subject>This is search template</subject>
        <r_creation_date>2019-02-12T08:10:47.000+00:00</r_creation_date>
        <r_modify_date>2019-02-12T08:10:47.000+00:00</r_modify_date>
        <owner_name>Administrator</owner_name>
        <r_is_public>true</r_is_public>
        <selected_sources>
            <item>REPO1</item>
        </selected_sources>
        <r_object_id>090000028000292a</r_object_id>
    </properties>
    <query-document-template><?xml version="1.0" encoding="UTF-8"?><... </query-document-template>
    <external-variables>
        <fulltext-variable>
            <id>/expression[0]</id>
            <expression-type>fulltext</expression-type>
            <data-type>string</data-type>
            <variable-value>REST</variable-value>
        </fulltext-variable>
    </external-variables>
    <links>
        <link rel="self" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates/090000028000292a"></link>
        <link rel="http://identifiers.emc.com/linkrel/delete" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates/090000028000292a"></link>
        <link rel="http://identifiers.emc.com/linkrel/search-execution" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates/090000028000292a/execution"></link>
    </links>
</search-template>

The templated fulltext expression has a corresponding external variable named fulltext-variable, which contains several elements.

  • id, xPath-like identity for each external variable
  • expression-type and date-type, their meanings are quite clear
  • variable-value, the original value of the condition in query document, which can work as default value if users don't specify one.

Shortcut to Create Search Template

Instead of creating search template from scratch, users can also convert a saved search into a search template. All expressions in the saved search will be templated.

At first, let's save a search following the Overview section. The POST request is submitted to Saved Searches resource and the request body is omitted below.

POST /dctm-rest/repositories/REPO1/saved-searches HTTP/1.1
Host: localhost:8080

The response will return a new saved search as below.

<?xml version="1.0" encoding="UTF-8"?>
<saved-search xmlns="http://identifiers.emc.com/vocab/documentum" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="dm_smart_list" definition="http://localhost:8080/dctm-rest/repositories/REPO1/types/dm_smart_list">
    <properties>
        <object_name>A Saved Search Sample</object_name>
        <title>This will be a search template</title>
        ...
    </properties>
    <query-document>...</query-document>
    <links>
        ...
        <link rel="http://identifiers.emc.com/linkrel/as-search-template" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates"></link>
    </links>
</saved-search>

Users can follow the href with link relation http://identifiers.emc.com/linkrel/as-search-template and make a POST request. The request body is a search template with an URL reference to an existing saved search through an attribute named search-reference. Since a saved search reference is specified, the query-document-template element is not needed.

POST /dctm-rest/repositories/REPO1/search-templates HTTP/1.1
Host: localhost:8080
Accept: application/xml
Content-Type: application/xml

<!-- Request Body -->
<search-template search-reference="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290c"
    xmlns="http://identifiers.emc.com/vocab/documentum"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <properties>
        <object_name>Shortcut Search template sample</object_name>
        <subject>This is a converted search template</subject>
        <r_is_public>true</r_is_public>
    </properties> 
</search-template>

——WebKitFormBoundary7MA4YWxkTrZu0gW–

You can see from the result that a number of external variables emerge in the element external-variables, which came from expressions of the original saved search.

<!-- Response Body -->
<?xml version="1.0" encoding="UTF-8"?>
<search-template xmlns="http://identifiers.emc.com/vocab/documentum" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="dmc_search_template" definition="http://localhost:8080/dctm-rest/repositories/REPO1/types/dmc_search_template">
    <properties>
        <object_name>Shortcut Search template sample</object_name>
        <r_object_type>dmc_search_template</r_object_type>
        <subject>This is a converted search template</subject>
        <r_creation_date>2019-02-12T08:57:34.000+00:00</r_creation_date>
        <r_modify_date>2019-02-12T08:57:34.000+00:00</r_modify_date>
        <owner_name>Administrator</owner_name>
        <r_is_public>true</r_is_public>
        <selected_sources>
            <item>REPO1</item>
        </selected_sources>
        <r_object_id>090000028000292b</r_object_id>
    </properties>
    <query-document-template>...</query-document-template>
    <external-variables>
        <fulltext-variable>
            <id>/expression[0]</id>
            <expression-type>fulltext</expression-type>
            <data-type>string</data-type>
            <variable-value>REST</variable-value>
        </fulltext-variable>
        <property-variable>
            <id>/expression[1]</id>
            <expression-type>property</expression-type>
            <property-name>object_name</property-name>
            <data-type>string</data-type>
            <operator>BEGINS_WITH</operator>
            <variable-value>Doc</variable-value>
        </property-variable>
        <property-list-variable>
            <id>/expression[2]</id>
            <expression-type>property-list</expression-type>
            <property-name>owner_name</property-name>
            <data-type>string</data-type>
            <operator>IN</operator>
            <variable-values>
                <item>Administrator</item>
            </variable-values>
        </property-list-variable>
    </external-variables>
    <links>
        <link rel="self" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates/090000028000292b"></link>
        <link rel="http://identifiers.emc.com/linkrel/delete" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates/090000028000292b"></link>
        <link rel="http://identifiers.emc.com/linkrel/search-execution" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates/090000028000292b/execution"></link>
    </links>
</search-template>

Execute Search Template

The last question we are going to answer is how to execute a search template. Before executing a search template, it is necessary to navigate the target template and get to know what variables are available. For our search template created in section Create Search Template, there is only one external variable for fulltext expression.

<!-- External Variables -->
<external-variables>
    <fulltext-variable>
        <id>/expression[0]</id>
        <expression-type>fulltext</expression-type>
        <data-type>string</data-type>
        <variable-value>REST</variable-value>
    </fulltext-variable>
</external-variables>

To execute a search template, users can specify the variable-value and issue a POST request to the href of link relation http://identifiers.emc.com/linkrel/search-execution.

POST /dctm-rest/repositories/REPO1/search-templates/090000028000292a/execution HTTP/1.1
Host: localhost:8080
Accept: application/xml

<!-- Request Body -->
<search-template>
  <external-variables>
      <fulltext-variable>
          <id>/expression[0]</id>
          <variable-value>git</variable-value>
      </fulltext-variable>
  </external-variables>
</search-template>

——WebKitFormBoundary7MA4YWxkTrZu0gW–

As to the request body, the id and variable-value of each external variable are mandatory. If no external variables are specified in the request body, the existing values saved in the template will work as default variable values.

This request should return no results as it searches the tutorials with another fulltext term “git”.

Conclusion

This tutorial is an introduction for search template resource. After learning from this article, you get to know:

  • It is a convenient way to construct new search criteria based on the existing search template.
  • Search templates are created with AQL.
  • Search template execution depends on new elements external-variable.
  • Saved searches can be converted to search templates.

Table of Contents

Your comment

To leave a comment, please sign in.