SAP BTP, SAP API Business Hub

Explore SAP BTP DMS Rest APIs

webadmin
SAP S/4HANA Business Process Integration Certification Preparation Guide

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

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

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

Repository Id

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 repository

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 DMS

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 repository

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 id

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 repository

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 DMS

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 DMS

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 maintained

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 document

Document check out
  1. URL: https://<<ECM Service URL>>/browser/<>/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 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 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 restored

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