Posted Feb 25 by Peng Qiu.
Updated Feb 26.

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

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

Overview

With the knowledge of AQL and facets, uses can execute real time search with sophisticated criteria. In a web application, a search criteria may be constructed from a complicated form. To make the same search criteria, users have to follow the same steps to prepare and submit the form carefully and repeatedly. Since Documentum REST 7.3, we introduce a new resource Saved Searches which help users to persist the search criteria to the server side, just like creating persistent objects in Content Server.

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

Preliminary

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

Discover Saved Searches Resource

Since release 7.3, the Repository Resource adds an additional link relation pointing to Saved Searches Resource.

<!-- 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/saved-searches" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches"></link>
        ...
    </links>
</repository>

Save a Search

Here is a sample of a saved search representation. There are three meta attributes defining search name (object_name), description (title) and access permission (r_is_public). The most important part is query-document, which contains an AQL statement. If the AQL contains special characters, we need to escape the characters or use a CDATA to save the AQL in the saved-search message.

<!-- Saved Search Representation -->
<saved-search
    xmlns="http://identifiers.emc.com/vocab/documentum"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <properties>
        <object_name>dave public</object_name>
        <title>this is saved search</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>
                    <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>
            <facet-definitions>
                <facet-definition id="id-1">
                    <attributes>
                        <attribute>keywords</attribute>
                    </attributes>
                </facet-definition>
            </facet-definitions>
        </search>
    </query-document>
</saved-search>

The POST request below is to create a new saved search. The request body contains the full representation of a saved search in XML.

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

<!--Request Body-->
<saved-search
xmlns="http://identifiers.emc.com/vocab/documentum"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<properties>
  <object_name>dave public</object_name>
  <title>this is saved search</title>
  <r_is_public>true</r_is_public>
</properties> 
<query-document>
      &amp;lt;search xmlns=&amp;quot;http://identifiers.emc.com/vocab/documentum&quot;
      ...
</query-document>
</saved-search>

——WebKitFormBoundary7MA4YWxkTrZu0gW–

If the search is saved successfully, the response will return HTTP status code 201 and the new saved search resource in the response body. The saved search resource supports regular get, update and deletion operations.

<?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>dave public</object_name>
        <title>this is saved search</title>
        <r_creation_date>2019-02-12T02:42:27.000+00:00</r_creation_date>
        <r_modify_date>2019-02-12T02:42:27.000+00:00</r_modify_date>
        <r_modifier>Administrator</r_modifier>
        <owner_name>Administrator</owner_name>
        <r_is_public>true</r_is_public>
        <selected_sources>
            <item>REPO1</item>
        </selected_sources>
        <has_results>false</has_results>
        <results_count>-1</results_count>
        <query_type>query_builder</query_type>
        <r_object_id>080000028000290a</r_object_id>
    </properties>
    <query-document>
        <?xml version="1.0" encoding="UTF-8"?><search...
    </query-document>
    <links>
        <link rel="self" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a"></link>
        <link rel="edit" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a"></link>
        <link rel="http://identifiers.emc.com/linkrel/delete" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a"></link>
        <link rel="http://identifiers.emc.com/linkrel/saved-search-results" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/results"></link>
        <link rel="http://identifiers.emc.com/linkrel/search-execution" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution"></link>
        <link rel="http://identifiers.emc.com/linkrel/as-search-template" href="http://localhost:8080/dctm-rest/repositories/REPO1/search-templates"></link>
    </links>
</saved-search>

Probably you have noticed that there are three new link relations in the saved search representation. Let's dig the first two and leave the third one to Advanced Searches in Documentum REST Services (4): Search Templates.

  • search-execution
  • saved-search-results
  • as-search-template

Execute Saved Search

A saved search has no values if it cannot be executed. As you can imagine, the link relation allows users to execute the saved search. The snippet below is the GET request to execute saved search.

GET /dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution HTTP/1.1
Host: localhost:8080
Accept: application/xml

You can still add additional URL parameters like items-per-page, include-total, page and inline on the execution URL to customize the search result. The search result for the saved search execution is exactly the same as a POST search service request with the same AQL.

<!-- Response Body(entries are omitted) -->
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <id>http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution</id>
    <title>Search results</title>
    ...
    <dm:facet xmlns:dm="http://identifiers.emc.com/vocab/documentum">
        <dm:facet-id>id-1</dm:facet-id>
        <dm:facet-label>Keywords</dm:facet-label>
        <dm:facet-value>
            <dm:facet-id>id-1</dm:facet-id>
            <dm:facet-value-id>extensibility</dm:facet-value-id>
            <dm:facet-value-count>3</dm:facet-value-count>
            <dm:facet-value-constraint>extensibility</dm:facet-value-constraint>
            <dm:link rel="search" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution?facet-id-constraints=id-1%3Dextensibility"></dm:link>
        </dm:facet-value>
        <dm:facet-value>
            <dm:facet-id>id-1</dm:facet-id>
            <dm:facet-value-id>client</dm:facet-value-id>
            <dm:facet-value-count>1</dm:facet-value-count>
            <dm:facet-value-constraint>client</dm:facet-value-constraint>
            <dm:link rel="search" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution?facet-id-constraints=id-1%3Dclient"></dm:link>
        </dm:facet-value>
        <dm:facet-value>
            <dm:facet-id>id-1</dm:facet-id>
            <dm:facet-value-id>search</dm:facet-value-id>
            <dm:facet-value-count>1</dm:facet-value-count>
            <dm:facet-value-constraint>search</dm:facet-value-constraint>
            <dm:link rel="search" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution?facet-id-constraints=id-1%3Dsearch"></dm:link>
        </dm:facet-value>
    </dm:facet>
</feed>

Navigate Facets

Navigating facets in Advanced Searches in Documentum REST Services (2): Facets tells that, to get facet results, users need to make a POST method with the original AQL to the facet URL. However, for a saved search resource, getting facet results is much simpler. Since the server saves the AQL and knows what it is, users don't need to submit the AQL again. A GET method will return the facet result to users.

GET /dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution?facet-id-constraints=id-1%3Dclient HTTP/1.1
Host: localhost:8080

By following the href with GET request, users can navigate facet results and there are only
one entry returned as expectation.

<!-- Response Body -->
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <id>http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution</id>
    <title>Search results</title>
    ...
    <entry>
        <id>0900000280002921</id>
        ...
    </entry>
    <dm:facet xmlns:dm="http://identifiers.emc.com/vocab/documentum">
        <dm:facet-id>id-1</dm:facet-id>
        <dm:facet-label>Keywords</dm:facet-label>
        <dm:facet-value>
            <dm:facet-id>id-1</dm:facet-id>
            <dm:facet-value-id>client</dm:facet-value-id>
            <dm:facet-value-count>1</dm:facet-value-count>
            <dm:facet-value-constraint>client</dm:facet-value-constraint>
            <dm:link rel="search" href="http://localhost:8080/dctm-rest/repositories/REPO1/saved-searches/080000028000290a/execution?facet-id-constraints=id-1%3Dclient"></dm:link>
        </dm:facet-value>
    </dm:facet>
</feed>

Saved Search Results

Users not only can execute the real time search on on a saved search, but also can save its search results on the server. When creating a saved search, the attribute has_results in the saved search request can be set to true, indicating to save the result. With this feature, users can get a snapshot of the search result from the REST services without querying to the xPlore index server, if stale results are affordable.

Enable or Refresh Saved Search Results

For a saved search resource that hasn't enabled saved search results option yet, users can turn on the saving by making a PUT method to the href of link relation.

PUT /dctm-rest/repositories/REPO1/saved-searches/080000028000290a/results HTTP/1.1
Host: localhost:8080
Accept: application/xml

The response is same as normal search execution, which is not shown here. Please note that facet results won't be saved.

Now we can get the saved search again and check the attributes has_results and results_count.

<!--Saved Search Representation with Results Enabled-->
<?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>dave public</object_name>
        ...
        <has_results>true</has_results>
        <results_count>5</results_count>
        ...
    </properties>
    ...
</saved-search>

Once the option is enabled, users can still keep the saved results updated by PUT to the href time to time.

Disable Saved Search Results

It's easy to disable this option. Below is a DELETE request to the href of link relation http://identifiers.emc.com/linkrel/saved-search-results, which disables saved search results.

DELETE /dctm-rest/repositories/REPO1/saved-searches/080000028000290a/results HTTP/1.1
Host: localhost:8080

After disabling the option, the attributes has_results and results_count become false and -1.

<!-- Saved Search Representation with Results Disabled -->
<?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>dave public</object_name>
        ...
        <has_results>false</has_results>
        <results_count>-1</results_count>
        ...
    </properties>
    ...
</saved-search>

Saved Search As Template

This topic is related to search template. Refer Advanced Searches in Documentum REST Services (4): Search Templates for the details.

Conclusion

After completing this tutorial, you get to know:

  • A saved search contains meta attributes and query document
  • Saving a new search is actually to create a persistent object with attributes and AQL.
  • Executing a saved search is similar to real time search executing with AQL, except that HTTP GET is used instead of POST
  • Saved results are not fresh data, but it can still be updated
  • Saved results can be disabled or enabled after saved search creation

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


Table of Contents

Your comment

To leave a comment, please sign in.