Understand DMS API – Free Postman Collection!!

[Dan_Wroblewski]

In my videos introducing the Document Management Service, I received some comments asking for the Postman Collection I used to show how the API works.

So I decided to release Postman collection, and write a short blog post to explain how the APIs work.

You can see all my DMS videos in the DMS playlist - more to come soon: https://www.youtube.com/watch?v=hLrCoHPwqT4&list=PL6RpkC85SLQCsKSvIOqMzFKW30B4TKXh-

 

How the APIs Work

There's 2 API Sets

The APIs are described on the SAP Business Accelerator Hub, but lo and behold, there are 2 separate sets of APIs:

• CMIS Compliant – API Reference: Most of the APIs for working with content are compliant with CMIS, an industry standard for APIs that call content management systems. 
   
• SAP REST API – API Reference: These have more to do with creating a repo and administrative tasks.

Objects

The contents of the repo are objects, which contain CMIS-defined properties. Some of the more notable properties:

• cmis:objectId: Unique ID for that object
• cmis:objectTypeId: Indicates the type of object, generally document (cmis:document) or folder (cmis:folder)
• cmis:name: Name for that object
• cmis:parentIds: Object ID of the folders that contain this object
• ... you can also get the owner, creation date, modified date, version, mime type of document type and more. DMS has complex capabilities, like version or encryption, and those are beyond the scope of this blog post.

"properties": {
	"cmis:objectId": {
		"id": "cmis:objectId",
		"localName": "cmis:objectId",
		"displayName": "cmis:objectId",
		"queryName": "cmis:objectId",
		"type": "id",
		"cardinality": "single",
		"value": "DzX04u_1PD5uNT2IfcmNzztROjky-92pHkAK1-SoE5U"
	},
	"cmis:name": {
		"id": "cmis:name",
		"localName": "cmis:name",
		"displayName": "cmis:name",
		"queryName": "cmis:name",
		"type": "string",
		"cardinality": "single",
		"value": "invoice_id-1731489392337-28"
	},
	"cmis:objectTypeId": {
		"id": "cmis:objectTypeId",
		"localName": "cmis:objectTypeId",
		"displayName": "cmis:objectTypeId",
		"queryName": "cmis:objectTypeId",
		"type": "id",
		"cardinality": "single",
		"value": "cmis:folder"
	}
}

Note that the property names start with cmis. When working with the properties, you need to use this namespace. This affects how you write some of the URLs (such as the query call) as well as selecting properties in the formula editor of SAP Build Apps (see below).

SAP Build Apps Formula Editor

Since the property names have a colon in them (:), you will need to use an alternate form for specifying those fields in the formula editor of SAP Build Apps.

For example, if you use the standard format, the formula editor will give an error:

Instead, you need to put such properties inside parentheses:

Queries

All but one of the calls are standard REST calls, and similar to many other REST APIs. But there is a query call, that lets you write SQL-esque statements to retrieve objects. 

For example, if I want to retrieve all of the documents for a folder with a specific ID, and return only the name property, I could use the following URL: 

https://{{endpoint}}/browser/{{repo}}?cmisSelector=query&
q=SELECT cmis:name FROM cmis:folder WHERE
cmis:objectId='DzX04u_1PD5uNT2IfcmNzztROjky-92pHkAK1-SoE5U'

To get the full OASIS documentation on writing queries, see their documentation.

 

Postman Collection

You can download the collection here: https://github.com/sap-tutorials/sap-build-apps/blob/main/projects/dms/DMS_CMIS.postman_collection.j...

NOTE:

• Some of the requests in the collection contain example objectIDs or file names, which of course will not work on your tenants. So you will have to change those.

Create Environment

In order to use the requests, you will need to set up an environment that supplies some of the authentication information. What I did is set up an environment for every different tenant I had that included DMS.

In the environment, you'll need to fill in the following properties:

clientid
clientsecret
endpoint
authenticationurl
repo

The first 4 you will get from the service key of your DMS Integration Option service.

The service key will look something like this:

On the second, authentication url property at the bottom, you'll have to append oauh/token to the value.

The repo property you get when you run the API for all your repos:

Get Token

The authentication for all the requests is set up to be done in the parent node, the top of the collection, DMS CMIS.

All you have to do is scroll down and click Get New Access Token.

If all goes well, you should get a success message.

Then click Use Token.

Occasionally, I find that the authentication doesn't work and I get an unauthorized message because there is a cookie that is not being overwritten. So for that request, I clear the cookie. But this doesn't happen very often.

Click Cookies (you may have to click twice), and then delete the cookie.