Skip to Content
Technical Articles
Author's profile photo Aman Gupta

Explore SAP BTP DMS Rest APIs

Introduction

The Document Management Service helps you in the management of your business’s documents. It’s based on the OASIS (Organization for the Advancement of Structured Information Standards) industry standard CMIS (Content Management Interoperability Services) and includes features like versioning, hierarchies, access control, and document management

SAP Document Management Service on Business Technology Platform, is recently released by SAP and comes in two flavors

Document Management Service, Application Option, which is the standalone SaaS offering (ready-to-use web application that provides document management capabilities for your enterprise content)

Document Management Service, Integration Option lets you build document management capabilities for your business applications using the integration component(APIs) or the easy-to-use, reusable UI component

 

Please refer this link for the detailed introduction

 

Business Scenario

Recently, I have been working for an unique requirement where we need to replicate documents from different SAP SaaS applications(for ex: SAP SuccessFactors EC) to SAP BTP Document Management Service. As there is no native integration exists in between these two applications, we need to place a custom solution using SAP BTP Cloud Integration as an iPaaS.

The complete process of extracting the documents from SAP SaaS application and uploading it into SAP BTP DMS can be automated if using a middleware(for example SAP BTP Cloud Integration)

 

Pre-requisites

  1. SAP Business Technology Platform Document Management Service, Integration option setup (Create a subaccount, space, service instance and key). Please refer this link for the detailed steps
  2. Setup SAP BTP DMS repository

 

Scope of this document

The scope of this document covers the below scenarios

  • Generate a JSON Web Token
  • Create Folder in DMS
  • Access Control for Folder
  • Create document in DMS
  • Access Control for documents
  • How to do Version management(Check In & Check Out) for the documents
  • Deletion of a document
  • Deletion of a folder

We will use Postman client in this blog to explore and understand different SAP BTP DMS APIs call.

Generate a JSON Web Token

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA

DMS%20API%20calls

DMS API calls

We can generate two types of JWT from DMS Authorization server, depending upon the specific use case, admin or user specific JWT can be generated.

Admin JWTAdmin%20JWT

Admin JWT

  1. URL: https://<< Oauth Token URL >>/oauth/token?grant_type=client_credentials
  2. Authentication: Client id and client secret from BTP DMS Service key
  3. Response body: JWT Token
  4. HTTP response code: 200

 

User specific JWTUser%20specific%20JWT

User specific JWT

  1. URL: https://<< Oauth Token URL >>/oauth/token?grant_type=password&username=<<User email id>>&password=<<User password>>
  2. URL parameters: User email id and User password
  3. Authentication: Client id and client secret from BTP DMS Service key
  4. Response body: JWT Token
  5. HTTP response code: 200

 

Create Folder in DMS

DMS provides below API and supported parameters to create folders inside the repositoryFolder%20creation

Folder creation

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/
  2. Repository Id: DMS repository Id
  3. Body parameters
  4. Response body: Folder object id
  5. HTTP response code: 201
  • cmisaction: createFolder (In order to perform this particular operation in DMS repository, cmisaction in an HTTP POST must be createFolder)
  • propertyId[0]: cmisname
  • propertyValue[0]: Test_AG1 (folder name)
  • propertyId[1]: cmis:objectTypeId
  • propertyId[1]: cmis:folder
  • succinct: true (Acts as a query parameter)

 

Result in DMS application

Below is the created folder in DMSDMS%20folder

DMS folder

 

Access Control for Folder

Access control is very important to regulate the unauthorized access, DMS provides below API and supported parameters to assign Access control for folders inside the repositoryFolder%20ACL

Folder ACL

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root
  2. Repository Id: DMS repository Id
  3. Body parameters
  4. Response body: Folder ACL response
  5. HTTP response code: 201
  • cmisaction: applyACL
  • objectId: Folder objectId
  • ACLPropagation: propagate (this property will propagate the access for all tree structure inside the folder)
  • addACEPrincipal[0]: AmanGupta@test.com (user email id on which the access to be granted)
  • addACEPermission[0][0]: cmis:all (read or all access for the user)

 

Result in DMS application

Below is the assigned Folder ACL result with the user email idDMS%20folder%20ACL

DMS folder ACL

 

Create document in DMS

DMS repository supports many different types of document upload, DMS provides below API and supported parameters to create documents inside the repositoryDocument%20creation

Document creation

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
  2. Repository Id: DMS repository Id
  3. Folder name
  4. Body parameters
  5. HTTP response code: 201
  • cmisaction: createDocument (In order to perform this particular operation in DMS repository, cmisaction in an HTTP POST must be createDocument)
  • filename: AG.pdf
  • _charset: UTF-8
  • propertyId[0]: cmisname
  • propertyValue[0]: AG.pdf
  • propertyId[1]: cmis:objectTypeId
  • propertyId[1]: cmis:document
  • succinct: true (Acts as a query parameter)
  • includeAllowableActions: true (If true, then the Repository must return the available actions for each object in the result set)
  • media: file content(binary)

Result in DMS application

Below is the created document under the folder in DMSDMS%20document

DMS document

 

Access Control for documents

Access control is very important to regulate the unauthorized access, DMS provides below API and supported parameters to assign Access control for documents inside the folder

Document ACL

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/
  2. Repository Id: DMS repository Id
  3. Body parameters
  4. Response body: Document ACL response
  5. HTTP response code: 201
  • cmisaction: applyACL
  • objectId: Document objectId
  • addACEPrincipal[0]: AmanGupta@test.com (user email id for whom access to be granted)
  • addACEPermission[0][0]: cmis:all (read or all access for the user)

 

Result in DMS application

Below is the Access Control applied for the document in DMSDMS%20document%20ACL

DMS document ACL

 

Version management

Version management or version control allows the management of changes in requirements over time. It allows a complete retrace of all versions in each document, with the restore version capability.

Version management in SAP BTP DMS can be done by following the Check out and Check in procedure as stated below

Get object id

First of all, we need to get object id for the document where the versioning needs to be maintainedFolder%20object%20list

Folder object list

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
  2. Repository Id: DMS repository Id
  3. Folder name
  4. Response body: Document object id
  5. HTTP response code: 200

 

Document Check Out

Based on the unique object id retrieved in the last step, below DMS API call is needed to check out the documentCheck%20out%20document

Document check out

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
  2. Repository Id: DMS repository Id
  3. Folder name
  4. Response body: New document object id
  5. HTTP response code: 201
  • cmisaction: checkOut (In order to perform this particular operation in DMS repository, cmisaction in an HTTP POST must be checkOut)
  • objectId: Document object id
  • succinct: true (Acts as a query parameter)
  • includeAllowableActions: true (If true, then the Repository must return the available actions for each object in the result set)

 

Result in DMS application

Below is the result in DMS with document marked in check out state

DMS%20document%20check%20out

DMS document check out

 

Document Check In

Based on the new unique object id for the document check out retrieved in the last step, below DMS API call is needed to check in the document with the updated document content and comment for the new version

Document%20check%20in

Document check in

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
  2. Repository Id: DMS repository Id
  3. Folder name
  4. Response body: New document object id
  5. HTTP response code: 201
  • cmisaction: checkIn (In order to perform this particular operation in DMS repository, cmisaction in an HTTP POST must be checkIn)
  • objectId: Checked out document object id
  • filename: AG.pdf
  • _charset: UTF-8
  • succinct: true (Acts as a query parameter)
  • includeAllowableActions: true (If true, then the Repository must return the available actions for each object in the result set)
  • media: file content(binary)
  • checkInComment: Updated content in the file
  • major: false

 

Result in DMS application

Below is the result in DMS with document versioning after checking in, all the previous versions can still be downloaded and restoredDMS%20document%20versions

DMS document versions

 

Deletion of a document

In order to delete a document, DMS provides below API. It deletes the specified object and all of it’s properties present in a repository

Delete%20document

Delete document

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
  2. Repository Id: DMS repository Id
  3. Folder name
  4. Body parameters
  5. HTTP response code: 200
  • cmisaction: delete
  • objectId: Document objectId

 

Deletion of a folder

In order to delete a folder, DMS provides below API. It deletes the specified folder and all the descendant-objects of the folder. A repository may attempt to delete child- and descendant-objects of the specified folder in any order. Any child- or descendant-object that the repository cannot delete must persist in a valid state in the CMIS domain model.

Delete%20folder

Delete folder

  1. URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/
  2. Repository Id: DMS repository Id
  3. Body parameters
  4. HTTP response code: 200
  • cmisaction: deleteTree
  • objectId: Folder objectId
  • continueOnFailure: true (If true, then the repository should continue attempting to perform this operation even if deletion of a child- or descendant-object in the specified folder cannot be deleted)

 

There are many other APIs from BTP DMS which can be leveraged for a specific use case, please refer this to see the API catalog

 

The above content is from personal learning, comments and suggestions are welcome.

Happy document uploading!! 🙂

 

Important Links

SAP BTP DMS help page: https://help.sap.com/docs/DOCUMENT_MANAGEMENT

SAP BTP DMS CMIS REST APIs: https://api.sap.com/package/SAPDocumentManagementServiceIntegrationOptionCMISAPI/overview

SAP BTP DMS Discovery Center: https://discovery-center.cloud.sap/protected/index.html#/serviceCatalog/document-management-service-integration-option?licenseModel=cpea&tab=feature&region=all

 

Assigned Tags

      Be the first to leave a comment
      You must be Logged on to comment or reply to a post.