Retrieving and viewing the results of a search operation

Released: JSON representation, HTML page

When retrieving and viewing the results of a search operation, you can restrict the number of results displayed to you by specifying a particular source plus the associated source categories and source properties. You can also restrict your search results using a full-text search term. The Defining a source system chapter explains how to create a source for mapping.

To retrieve or display only the results of a search operation, you must perform the following steps:

  • Determining the URL for a repository

  • Determine the link relation for retrieving the results of a search operation

  • Specifying response control parameters

  • Open the URL for the results of a search operation

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determining the link relation for retrieving or viewing the results of a search operation

You open the URL for a repository as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

The JSON object for the repository contains the searchresultwithmapping link relation with placeholders for the values used to retrieve or view the results of the search operation.

Response

{
        _links: {
                searchresultwithmapping: {
                        href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm{?sourceid,sourceproperties,sourcecategories,sourcepropertysort,ascending,fulltext,page,pagesize}",
                        templated: true
                }
        },
        id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Specifying response control parameters

Use the following parameters to control the system response when retrieving or viewing the results of a search operation: You must encode the URL parameters (e.g. spaces in %20). The length of the encoded query parameter is limited to 2000 characters.

Parameter

Description

sourceid

Defines the source to which the mapping used to retrieve the results of the search operation belongs. Only the source properties and categories that have been mapped to d.3 properties and d.3 categories are used for the individual items in the result. If no source is specified, only the IDs and the link relations for the DMS object will be returned for the individual items in the result.

sourceproperties

Specifies the search restriction based on the properties of documents and dossiers from the perspective of the source. Species the ID of the mapped source properties in order to restrict a search procedure to certain criteria. The search procedure is executed based on the mapping.

Regular expressions specified by the administrator during mapping are ignored.

You must specify the search restrictions as a JSON object. You can define at least one value for each property.

Examples (not encoded):

  • sourceproperties={"myprop1_ID":["Test e-mail 1"]}: for a search for items with the d.3 property with the value "Test e-mail 1" that has been mapped to the source property with the ID "myprop1_ID".

  • sourceproperties={"myprop1_ID":["Test e-mail 1", "Test e-mail 2"]}: for a search for items with the d.3 property with the value "Test e-mail 1" or "Test e-mail 2" that has been mapped to the source property with the ID "myprop1_ID".

Restriction in relation to the definition of a search operation: You can also define multiple values for a parameter, provided that facets have been configured for the corresponding d.3 property. If no facets for viewing have been configured for the d.3 property, the last value is always adopted for the search operation.

You cannot use source properties, which are mapped to the common properties for comment fields (Comment 1 - 4), for the Search feature, since searching for individual comment fields in the d.3 repository is not supported.

You can also use several properties as search restrictions simultaneously.

Examples (not encoded):

  • sourceproperties={"myprop1_ID":["Test e-mail 1"],"myprop2_ID":["John Doe"]}: for a search for items with the d.3 property with the value "Test e-mail 1", that has been mapped to the source property with the ID "myprop1_ID" and the d.3 property with the value "John Doe" what has been mapped to the source property with the ID "myprop2_ID".

sourcecategories

Sets the categories used for searching items. You can define at least one category. Enter the ID of the source category, otherwise the search will be performed across all the categories in a d.3 repository.

Sets the source categories used for searching items. Enter the ID of the source category. The search procedure is executed based on the mapping.

You must specify the search restrictions as a JSON array. You can specify one or more source categories. If you do not specify a source category, the search will be performed across all the categories in a d.3 repository.

Examples (not encoded):

  • sourcecategories=["mycategory1_ID"]: for a search in the d.3 category that has been mapped to the source category with the ID "mycategory1_ID".

  • sourcecategories=["mycategory1_ID","mycategory2_ID"]: for a search in the d.3 categories that have been mapped to the source category with the ID "mycategory1_ID" or "mycategory2_ID".

sourcepropertysort

Specifies the ID of the mapped source property that is used to sort the result. If no sort property is specified, the default sort order using the Last modified sort criteria is applied.

ascending

Specifies the direction of the sort order.

  • ascending=true: results in an ascending sort order (from small to big (A-Z) and from old to young).

  • ascending=false: results in an descending sort order (from big to small (Z-A) and from young to old).

In case the ascending parameter is not explicitly specified, the ascending sort order is applied. This is not true for the default sort order: If the criteria Last modified is used for sorting and sort order is not specified, the sort order is descending.

In addition to this, dossiers are displayed prior to documents in the result list. Within documents and dossiers, the items are sorted by the specified sorting criterion.

fulltext

Specifies a full-text keyword.

page

Specifies which page of the result list is requested.

If this parameter is not transferred, Page 1 will be requested.

pagesize

Specifies how many items are displayed per page.

If this parameter is not transferred, 25 items per page will be requested.

Note

Specific values for the sourceproperties parameter related to the various options for restricting the result in a targeted way:

  1. Search for a numeric value or a money value:

    Specify the value without using a thousand separator. The decimal separator is the period (.). Example: For the value 1,000.20 EUR specify 1000.20.

  2. Search for a date and time:

    Specify the date in the format YYYY-MM-DD. Example: Enter 2014-12-05 for the date 12/05/2014 (MM/DD/YYYY).

    Time is specified in the format YYYY-MM-DDTHH:mm:ss+01:00. You must encode the plus character (+) with %2b. Example: 2015-02-18T23:59:59%2b01:00 for 02/18/2015 at 11:59 p.m. and 59 seconds in the time zone UTC+1 for standard time in Germany.

  3. Search for items that are located in a specific range:

    To search in a range, use a combination of the pipe and minus character (|-) as separators. Examples for a numeric field with the ID "231":

  • Values greater than or equal to 100: {"231":["100|-"]}

  • Values smaller than or equal to 100: {"231":["|-100"]}

  • Values between 100 and 200: {"231":["100|-200"]}

Opening the URL for the results of a search operation (JSON representation)

Once you have created a URL, you can then open the results of the search operation as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1_ID":["Test E-Mail 1"]}&sourcecategories=["mycategory1_ID"]&sourcepropertysort=myprop1_ID&ascending=true&fulltext=test&page=1&pagesize=50
Accept: application/json

The following JSON object will then be returned as a result:

Response

{
  "_links": {
    "next": {
      "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=2"
    },
    "self": {
      "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=1"
    }
  },
  "page": 1,
  "items": [
    {
      "_links": {
        "self": { "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123" },
                "previewReadonly": { href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/preview?isReadonly=true" }
      },
      "id": "D000000123",
      "sourceProperties": [
        {
          "key": "myprop1_ID",
          "value": "Test E-Mail 1",
          "isMultiValue": false
        },
        {
          "key": "myprop2_ID",
          "value": "Max Mustermann",
          "isMultiValue": true
        },
        "..."
      ],
      "sourceCategories": [ "mycategory1_ID" ]
    },
    "..."
  ]
}

Property

Description

_links

Contains the link relations for the item.

self: Self-link.

previewReadonly: Relative URL for retrieving the preview in read mode. Use the link relation when the preview is displayed in the inner supply (InnerSupply) of the operating concept.

next: Relative URL for opening the next page of the result list. Is only specified when there are more results to display.

prev: Relative URL for opening the previous page of the result list. Is only specified when there are previous results to display.

page

Specifies the page number of the result list.

items

Specifies the array with search operation result items for the requested page.

Structure of an item in the result list

Property

Description

_links

Contains the link relations for the item.

self: Self-link.

delete or deleteWithReason: If available, the item can be deleted with an HTTP DELETE request. For more information see Deleting the current version of a DMS object without user interaction.

update or updateWithContent: If available, the item can be updated with an HTTP PUT request. For more information see Storing a new version without user interaction.

id

Specifies the document ID of the item.

sourceProperties

Specifies the array with source properties that are available for the item.

If the same source property has been mapped to multiple d.3 properties that the item possesses, this source property will be returned multiple times with the respective values of the d.3 property.

Regular expressions specified by the administrator during mapping are ignored.

sourceCategories

Specifies the array with the IDs of the source categories that are available for the item.

The system will only return multiple categories if multiple source categories have been mapped to the d.3 category in which the item is located.

Structure of a source property

Property

Description

key

Indicates the unique identifier of the source property.

value

Specifies the value of the mapped d.3 property.

displayValue

Specifies the display value for the mapped d.3 property. Is returned only if the value (value) and display value (displayValue) are different.

isMultiValue

Specifies whether the mapped d.3 property is a multi-value property.

If the d.3 property is a multi-value property, value will return the first value or first input value of the property (depending on the d.3 repository configuration). To retrieve all multi-values, use the request for Retrieving the details of a DMS object.

Opening the URL for the results of a search operation (HTML page)

If you want to open the HTML view of the results, you must create the URL in the same way as described for retrieving the JSON representation. Enter the URL in the browser to view the HTML page. This HTML page contains the identifiers for the d.3 properties and d.3 categories.

Examples (not encoded):

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1_ID":["Test E-Mail 1"]}&sourcecategories=["mycategory1_ID"]&sourcepropertysort=myprop1_ID&ascending=true&fulltext=test&page=1&pagesize=50
Accept: text/html