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 |
---|---|
| 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. |
| 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):
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):
|
| 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):
|
| 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. |
| Specifies the direction of the sort order.
In case the 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. |
| Specifies a full-text keyword. |
| Specifies which page of the result list is requested. If this parameter is not transferred, Page 1 will be requested. |
| 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:
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.
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.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 |
---|---|
| Contains the link relations for the item.
|
| Specifies the page number of the result list. |
| Specifies the array with search operation result items for the requested page. |
Structure of an item in the result list
Property | Description |
---|---|
| Contains the link relations for the item.
|
| Specifies the document ID of the item. |
| 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. |
| 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 |
---|---|
| Indicates the unique identifier of the source property. |
| Specifies the value of the mapped d.3 property. |
| Specifies the display value for the mapped d.3 property. Is returned only if the value ( |
| Specifies whether the mapped d.3 property is a multi-value property. If the d.3 property is a multi-value property, |
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