Posted Feb 25 by Peng Qiu.
Updated Feb 26.

This document introduces full-text search in Documentum REST Services.

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

Part I Full-text Search

The “search engine” of Documentum REST Services

From release 7.2, Documentum REST Services begin to support full-text search. Not only meta data, but also content are searchable with this service. You can discover the search resource under repository resource.

GET http://localhost:8080/dctm-rest/repositories/REPO1
Accept: application/json

The search resource under repository REPO1 looks like below. The link for search resource is a template containing many URL parameters.

{
    "id": 2,
    "name": "REPO1",
    ...
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/search",
            "hreftemplate": "http://localhost:8080/dctm-rest/repositories/REPO1/search{?collections,facet,include-total,inline,items-per-page,locations,object-type,page,q,sort,timezone,view}"
        }
    ]
}

What to Search in the Tutorial

Assuming there is a brand new repository, some data and content are populated for this tutorial.

  1. New cabinet Tutorial is created under repository REPO1.
  2. Document documentum is created under cabinet Tutorial and it has content documentum tutorial.
  3. Folders dfc and rest are created under cabinet Tutorial.
  4. Documents dfc tutorial and rest tutorial are created under folders dfc and rest respectively.

It looks like the structure as below.

enter image description here

Enter a Query

When you look at web page of search engine like google or bing, you can’t help to input the something in the search box. If you view the source of the page, you will probably find the search box has q as its name or id.

google website

In the google page above, you can see the magic character q standing for query. Search Resource of Documentum REST Services also has this q - a URL parameter. First let’s search the key word “tutorial”.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial

The GET request to this URL will return the search results containing “tutorial”. In fact, we can leverage simple search language to define more complicated search criteria.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=rest tutorial

Simple search language has implicit boolean operator “AND”. The URL above will search objects containing both “rest” and “tutorial”. What if you want to search the phase “rest tutorial”? Use double quotes.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=“rest tutorial”

Sometimes we has specific conditions for the objects to search. For example, we only care about the objects in our own folders, or some specified kinds of documents.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&locations=/Tutorial/rest&object-type=dm_document

Another two URL parameters locations and object-type are for such purpose. In the request above, it will only search key word “tutorial” of type dm_document in folder “/Tutorial/rest”.

Understanding Results

Defining search criteria in URL is quite straightforward, just like using a popular search engine. The search results are a bit sophisticated. There are two kinds of representation of search results: XML and JSON.

Search Results in XML

As the search results is a collection, its representation is an Atom feed, which is same as other collection type resources of Documentum REST Services, except there are some special elements in each Atom entry.

<?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/search</id>
    <title>Search results</title>
    <author>
        <name>Open Text Documentum</name>
    </author>
    <updated>2018-11-08T09:25:32.941+00:00</updated>
    ...
    <entry>
        ...
        <content type="application/xml" src="http://localhost:8080/dctm-rest/repositories/REPO1/objects/0900000280001429.xml"></content>
        <relevance:score xmlns:relevance="http://a9.com/-/opensearch/extensions/relevance/1.0/">1.0</relevance:score>
        <dm:terms xmlns:dm="http://identifiers.emc.com/vocab/documentum">
            <dm:term>Tutorial</dm:term>
            <dm:term>tutorial</dm:term>
        </dm:terms>
    </entry>
    ...
</feed>
Element score and terms

In the representation, an atom entry stands for a search result. And we can see the elements score and terms in each entry.

score is defined in open search specification. It means relative assessment of relevance for a particular search result with respect to the search query. terms is the matched terms of the search result.

Element content

Another element deserving attention is content. Element “content” indicates the details of real object contained in the search result entry.
By default, it has two attributes type and src. type is the content type of current representation; and src contains the link for the matched object. But the URL parameter inline will populate details in element “content”.

Search Results in JSON

The information in JSON representation search results is same as XML.

{
    "id": "http://localhost:8080/dctm-rest/repositories/REPO1/search",
    "title": "Search results",
    ...
    "entries": [
        {
            "id": "0900000280001429",
            ...
            "content": {
                "type": "application/vnd.emc.documentum+json",
                "src": "http://localhost:8080/dctm-rest/repositories/REPO1/objects/0900000280001429"
            },
            "score": "1.0",
            "terms": [
                "Tutorial",
                "tutorial"
            ]
        },
        ...
    ]
}

Pagination of Search Results

The size of search results for certain key word is probably big. It’s necessary to divide the results into several blocks and control the size of each block. We have two URL parameters to do this.

  • items-per-page, specifies the size of each page (block).
  • page, specifies which page to return.

Now that we may get part of the whole results set, how to tell how many results in all? There is another pagination URL parameter.

  • include-total, asks search service to retrieve the hit count.

With these new capabilities, a URL could looks like below.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&include-total=true&items-per-page=2&page=2

Other Customizations

The same results set may appear in different ways for different purposes.

Sort the Results

For example, we want the results show by lexical order of property object_name. The URL below will do this.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&sort=object_name ASC

Here “ASC” means ascending and “DESC” means descending.

Check the thumbnails

Sometimes, we prefer to check the thumbnail before requesting the whole object.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&thumbnail=true

  • thumbnail, returns the thumbnail link for each entry in the collection resource.

This URL will ask for thumbnail link in each search result. The thumbnail link has relation icon for each entry.

{
    "id": "http://localhost:8080/dctm-rest/repositories/REPO1/search",
    "title": "Search results",
    ...
    "entries": [
        ...
        {
            "id": "090000028000142a",
            "title": "Manage Users and Groups in Documentum REST Services.pdf",
            ...
            "links": [
                ...
                {
                    "rel": "icon",
                    "href": "object_type=dm_document&format=pdf&is_vdm=false&repository=2"
                }
            ],
            ...
        }
    ]
}

Customize Attributes in Results

Some users want to retrieve specified attributes in the search result entry instead of kicking off anther request to get the object. For example, it could be helpful if the content size or version number are displayed in the search results.

  • view, specifies the object properties to retrieve. This parameter works only when inline is set to true.

Below is a request which retrieving attributes “r_version_label” and “r_content_size”.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&view=r_version_label,r_content_size&inline=true

The search result will contains the additional attributes in element content.

{
    "id": "http://localhost:8080/dctm-rest/repositories/REPO1/search",
    "title": "Search results",
    ...
    "entries": [
        {
            "id": "0900000280001429",
            ...
            "content": {
                "name": "item",
                "type": "dm_document",
                "definition": "http://localhost:8080/dctm-rest/repositories/REPO1/types/dm_document",
                "properties": {
                    "r_version_label": [
                        "1.0",
                        "CURRENT"
                    ],
                    "r_content_size": 66639
                },
                ...
            },
            ...
        },
        ...
    ]
}

Part II Facet

For search, especially enterprise content search, well-organized search results are important, like invoices during last month, vacation plans of somebody…

Facet search is an approach to classify information.

Facet Search (Navigation)

The first Request for Facet

From Part I, we know how to send a request for full-text search, on which facet navigation is built.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&facet=r_object_type

A new URL parameter is introduced in the request.

  • facet, specifies the property to be used as facet.

In the request, the face of the cut and polished diamond is property r_object_type.

The data in your repository will match the categories in the facet results.

{
    "id": "http://localhost:8080/dctm-rest/repositories/REPO1/search",
    "title": "Search results",
    ...
    "facets": [
        {
            "facet-id": "facet_r_object_type",
            "facet-label": "Type",
            "facet-value": [
                {
                    "facet-id": "facet_r_object_type",
                    "facet-value-id": "dm_document",
                    "facet-value-count": 3,
                    "facet-value-constraint": "dm_document",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&facet=r_object_type&facet-value-constraints=dm_document"
                    }
                },
                {
                    "facet-id": "facet_r_object_type",
                    "facet-value-id": "dm_cabinet",
                    "facet-value-count": 1,
                    "facet-value-constraint": "dm_cabinet",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&facet=r_object_type&facet-value-constraints=dm_cabinet"
                    }
                }
            ]
        }
    ]
}

Dig the Facet Results and Navigate

The facet results are easy-understanding. In each facet, there are several elements of facet-value, which represents one classification against the faceted property. In the sample, there are two categories for object type: dm_document and dm_folder.

The facet-value element contains information like id, count and constraint. The most important element in the facet-value is the link, which is the entrance for each category.

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&facet=r_object_type&facet-value-constraints=dm_cabinet

Clicking the link above will navigate us to the dm_cabinet category. The combination of “facet=r_object_type” and “facet-value-constraints=dm_document” can be explained as r_object_type is dm_document.

  • facet-value-constraints, specifies a property constraint expression.

Customize facet Search

Since facet-value-constraints can define the conditions for a facet classification, we may leverage it to customize our own facet category.

For example, we just want to get the search results of either dm_document or dm_cabinet. Unfortunately, search resource of Documentum REST Services doesn’t return such category.

http://demo-server:8080/dctm-rest/repositories/acme01/search?q=tutorial&facet=r_object_type&facet-value-constraints=dm_document|dm_cabinet

In the request, we customize the value of parameter facet-value-constraints: dm_document|dm_cabinet. This is a boolean expression, which means dm_document or dm_cabinet.

  • |, OR
  • +, AND

What if the value of facet-value-constraints has two operators as the request below?

http://localhost:8080/dctm-rest/repositories/REPO1/search?q=tutorial&facet=r_object_type&facet-value-constraints=dm_document|dm_cabinet+dm_folder

The value here will be dm_document|(dm_cabinet+dm_folder). The two operators has same precedence, but the expression is calculated from right to left.

  • A+B|C means A+(B|C)
  • A|B+C means A|(B+C)

Table of Contents

Your comment

To leave a comment, please sign in.