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
- SAP Business Technology Platform Document Management Service, Integration option setup (Create a subaccount, space, service instance and key).
- 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
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
- URL: https://<< Oauth Token URL >>/oauth/token?grant_type=client_credentials
- Authentication: Client id and client secret from BTP DMS Service key
- Response body: JWT Token
- HTTP response code: 200
Repository Id
- URL: https://<< Oauth Token URL >>/oauth/token?grant_type=password&username=<<User email id>>&password=<<User password>>
- URL parameters: User email id and User password
- Authentication: Client id and client secret from BTP DMS Service key
- Response body: JWT Token
- HTTP response code: 200
Create Folder in DMS
DMS provides below API and supported parameters to create folders inside the repository
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/
- Repository Id: DMS repository Id
- Body parameters
- Response body: Folder object id
- 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
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
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root
- Repository Id: DMS repository Id
- Body parameters
- Response body: Folder ACL response
- 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
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
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
- Repository Id: DMS repository Id
- Folder name
- Body parameters
- 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
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
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/
- Repository Id: DMS repository Id
- Body parameters
- Response body: Document ACL response
- 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
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
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
- Repository Id: DMS repository Id
- Folder name
- Response body: Document object id
- 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
- URL: https://<<ECM Service URL>>/browser/<>/root/Test_AG1
- Repository Id: DMS repository Id
- Folder name
- Response body: New document object id
- 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
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
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
- Repository Id: DMS repository Id
- Folder name
- Response body: New document object id
- 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
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
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/Test_AG1
- Repository Id: DMS repository Id
- Folder name
- Body parameters
- 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.
- URL: https://<<ECM Service URL>>/browser/<<Repository Id>>/root/
- Repository Id: DMS repository Id
- Body parameters
- 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)