Retrieving and viewing the details of a DMS object

Released: JSON representation, HTML page

You can retrieve the details of a DMS object as a JSON representation or view the detail view for a DMS object. When retrieving the details as a JSON representation, you can enter a specific source from a source system to define which source properties and source categories are determined. If you do not specify a source, only the ID and the link relation for the DMS object will be returned. The Defining a source system chapter explains how to create a source.

To retrieve or display the details of a DMS object, you must perform the following steps:

  • Determining the URL for a repository

  • Determine the link relation for retrieving the details of a DMS object

  • Specifying response control parameters

  • Open the URL for the details of a DMS object

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 details of a DMS object

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 dmsobjectwithmapping link relation with placeholders for the values used to retrieve or view the details of the DMS object.

Response

{
        _links: {
                dmsobjectwithmapping: {
                        href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{dmsobjectid}{?sourceid}",
                        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 details of a DMS object:

Parameter

Description

dmsObjectId

Specifies the document ID of the DMS object for which you want to request or view the details.

sourceid

Defines the source to which the mapping used to retrieve the details of the DMS object belongs.

For information about providing a source system for mapping, see Defining a source system.

If you want to use the default source system, see Retrieving the default source system for a d.3 repository for more information.

Retrieve (JSON representation):

Only the source properties that are mapped to the d.3 properties are returned. If no source is specified, only the ID and the link relation for the DMS object will be returned.

View (HTML page):

You do not need to enter this parameter if you wish to view the details of a DMS object. The parameter will not be evaluated.

Opening the URL for the details of a DMS object (JSON representation)

Once you have created a URL, you can then retrieve the details of the DMS object as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123?sourceid=/myapp/sources/mysource
Accept: application/json

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

Response

{
  "_links": {
    "self": { 
                "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123"
     },
    "mainblobcontent": {
        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/main/c"
     },
     "editinoffice": {
           "href": "{ms-word:ofe|u|{+clientOrigin}/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/dav/D000000123%20(D000000123).DOCX}",
       "templated": true
     },
         "pdfblobcontent": {
       "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/p1/c"
     },
         "notes":{
           "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
         },
         "children":{
           "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm/?children_of=D000000123"
         },
         "versions":{
           "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/"
         }
  },
  "id": "D000000123",
  "sourceProperties": [
    {
      "key": "myprop1_ID",
      "value": "value of property 1"
    },
    {
      "key": "myprop2_ID",
      "value": "value of property 2 in row 2",
      "values": {                                                 
            "2": "value of property 2 in row 2",
        "4": "value of property 2 in row 4"
          }
    }
  ],
  "sourceCategories": ["mycategory2_ID"]
}

Property

Description

_links

Contains the link relations for the DMS object.

mainblobcontent: Relative download URL for the main document of the current version of the DMS object.

editinoffice: URL with placeholders for editing the document in Microsoft Office. You will only receive this URL if the administrator has activated the function for editing Microsoft Office documents. The URL is unavailable if you are working with Microsoft Office 365 in the cloud.

pdfblobcontent: Relative download URL for the generated (“dependent”) PDF document of the current version of the DMS object. You receive this URL only if a generated PDF document has been created for the DMS object.

notes: Relative URL for opening the notes of the DMS object. You will only receive this URL if any notes have already been saved for the DMS object.

children: Relative URL for the child DMS objects. You will only receive this URL if the DMS object has child items.

versions: Relative URL for retrieving and displaying the versions of a DMS object.

self: Self-link.

id

Specifies the document ID of the DMS object.

sourceProperties

Specifies the array with source properties that are available for the requested DMS object.

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

sourceCategories

Specifies the array with the IDs of the source categories that are possible for the requested DMS object.

The system will only return multiple categories if multiple source categories have been mapped to the d.3 category in which the requested DMS object 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.

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).

values

Specifies the values of the mapped d.3 property. Only returned if the d.3 property is a multi-value property.

values is an object comprised of name-value pairs (key value):

Name: Row number (starting with 1).

Value: Value of the property in the corresponding row.

displayValue

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

Opening the URL for the details of a DMS object (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 querying 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.

Example:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123
Accept: text/html