Business Technology Platform offers a lot of exciting and innovative services which have the potential to expedite digitalization and enable SAP customers to onboard the cloud journey. BTP and S/4HANA combination is a marriage made in heaven and with proper knowledge it gives the possibility to build a robust enterprise application landscape which can enhance productivity and give a “Wow!” feeling to business users.
This blog is more of a hands on experience which I am sure will help a lot of people working on Document Management Service on BTP. I know there are a lot of blogs and content available on SAP Community on this topic, but I can’t resist the temptation to share my learnings 🙂
I will cover the following topics:
- Connect BTP DMS with S/4HANA on-premise.
- Setup CMIS workbench to see the repositories created using DMS-Integration option and files attached from S/4HANA
- Create repositories in BTP DMS using DMS integration option APIs
- Use BTP DMS repository to store SAP GOS Attachments (Generic Object Service) and Business Document attachments (Archivelink)
- Use BTP DMS repositories for documents and tables archived using transaction SARA
- View documents attached in SAP Business Objects e.g. from VA02, CV01N etc. in DMS repository using CMIS workbench.
Brief summary of what is Document Management Service on BTP?
In simple terms DMS on BTP is a cloud based offering to manage business documents and attachments. It provides an efficient and cost effective solution to manage the large number of documents that can be attached to SAP business objects like Purchase Orders, Sales Order, DIR and DRW documents etc. in S/4HANA.
There are 3 variants of DMS on BTP:
- Document Management Service- Application Option: This is a Software-as-a-Service (SaaS) solution on BTP. It comes with its own UI which can help to create CMIS (Content Management Interoperability Services) compliant repositories and upload documents to the repositories. This can be launched from Subscriptions under “Instances and Subscription” link in the BTP Cockpit.
- Document Management Service- Integration Option: This is a service on BTP and provides a rich set of APIs to create a DMS repository or onboard any external CMIS compliant repository
- Document Management Service- Repository Option: This provides storage capabilities on BTP. The repositories are CMIS compliant.
I am assuming that the Global Administrator of your BTP has added the necessary entitlements and boosters for these 3 DMS variants and also created the subaccount where the DMS-Application option is available as a subscription and DMS-Integration option is added as a Service. Entitlements for DMS-Repository option should also be added by your BTP administrator to follow this blog. DMS-Repository option on BTP is optional and you can also use any external CMIS compliant repository.
Figure 1: BTP Cockpit- DMS Application Option and Integration Option in subaccount
Please generate the Service key for DMS-Integration Option which will have important configuration details we will need in the steps given in this blog below:
Figure 2: DMS Integration Service Key-Important Endpoints
1. Connect BTP DMS with S/4HANA on-premise:
Some important points to note which can save you a lot of time if you are exploring BTP DMS. It is not supported to connect S/4HANA with BTP DMS Application option. I could not find any SAP Note which clearly mentions this, but I guess many of us who would start to explore BTP DMS would first think of creating a repository on BTP DMS Application Option using the Manage repository app that comes with it and somehow integrate it with S/4HANA content repositories. Short answer to it is it will just not work.
In order to connect S/4HANA on prem with BTP DMS, we have to use BTP DMS-Integration Option and the APIs to perform different operations on the repositories. In this blog I will also be using BTP DMS-Repository Option for the actual storage where my repositories will be created using the available APIs.
1.1 Import BTP certificate in STRUST under SSL Client Standard or SSL Client Anonymous and this certificate list can be used when creating destinations in SM59
Figure 3: BTP Certificate from BTP Cockpit in browser
Figure 4: BTP Certificate imported in STRUST
1.2 Create RFC destination in S/4HANA on-prem system to connect to BTP DMS
In your S/4HANA system create a RFC destination of Type G in transaction SM59. In the Host name enter the value of “url” property (without https) of “ecmservice” from the DMS-Integration Option Service key from Figure 2
Figure 5: RFC Destination- Technical Settings
In the Logon_Security tab of the RFC destination select SSL Active and SSL certificate where we uploaded the BTP certificate
Figure 6: RFC Destination- Logon_Security tab
You may have to take help from Basis and network team to make sure the connection test from S/4HANA RFC destination to your BTP is successful. I had to provide proxy settings, but normally in client landscape it should work without proxy. You cannot proceed to the next steps until this RFC destination connection is working.
1.3 Create content repository in S/4HANA using transaction OAC0
In order to create content repository we need to provide RFC destination and OAUTH profile. Create the content repository in this step with the same name as the name of the repository we will create in BTP DMS in later step
Document Area should be Document Management System and Storage Type is CMIS Content Server.
Once content repository is created use the buttons highlighted in blue in screenshot below to “Send RFC Info” and “Check” connection test of this repository.
Figure 7: Create Content Repository in OAC0 in S/4HANA
For OAuth Profile (CMIS_SDM_CC):
First Create an OAuth 2.0 Client Profile in the AS ABAP of type HANA_CLOUD_PLATFORM as given in SAP Help.
Second go to transaction OA2C_CONFIG or to below URL and configure an OAuth 2.0 client
https://<HostName>:<Port>/sap/bc/webdynpro/sap/oa2c_config?sap-client=<nnn>
Here Client Id is from figure 2- DMS Integration Option Service Key
Figure 8: Create OAuth 2.0 Client using OA2C_CONFIG
1.4 Create storage category in transaction OACT in S/4HANA
Provide the content repository created in above step to create a new storage category
Figure 9: Create Storage Category in transaction OACT
1.5 Maintain mapping of Physical Document Class for all SAP Office documents with Storage Category
Got to transaction SKPR08 and for the class SOFFPHIO which is used by the system for all documents attached using Generic Object Service (GOS) maintain the mapping to the new Storage Category we created in transaction OACT
Figure 10: Map Physical Document Class used for GOS to Storage Category
We are now ready with the configuration we had to maintain in S/4HANA to integrate with DMS repository on BTP using the DMS-Integration Option.
In order to connect the dots and see how things are working and how our files are getting stored in actual repository in BTP DMS when we attach a file e.g. in VA02 or CV02N etc. we need to setup CMIS Workbench which provides the User Interface to see the files with timestamp when it was created etc.
2. Setup CMIS workbench to see the repositories created using DMS-Integration option and files attached from S/4HANA
This topic is very well covered in blog Utilizing CMIS Workbench together with BTP DMS
One useful tip to ensure that you are able to login into the CMIS workbench and connect to your BTP DMS repository is how to generate the access token to be entered in User Name
Figure 11: CMIS Workbench authentication screen
In this screen URL is the API endpoint from the DMS Integration service key in Figure 2. Copy the value of “url” parameter in property “ecmservice” from DMS Integration service key and add the suffix “/browser” to this endpoint.
Make sure to select radio button Browser for Binding and OAuth 2.0 for Authentication.
In field User Name enter the access token by opening this URL in a new tab in the same session where you have authenticated into your BTP Cockpit
URL to get access token: In figure 2- copy the value of parameter “url” from property “uaa”. It is just below the client secret parameter:
<value of parameter “url” from property “uaa”>/oauth/token?grant_type=client_credentials
Enter client id and client secret to authenticate in this URL:
Figure 12: URL Endpoint to get access token for CMIS Workbench
Copy the complete access_token value and enter in Username in the CMIS workbench authentication screen to load the repositories created using BTP DMS-Integration option
Figure 13: Access Token generated to be entered in Username in CMIS workbench to authenticate
Now you will be able to load the repositories and login to the one you select
Lets login to ZX repository, we will see the repository is currently empty.
Figure 14: Login to ZX repository
For every content repository we create it is mandatory to run report “CMIS_REPOSITORY_SETUP” in S/4HANA system to create the folder structure where SAP Business documents attached to business objects like Sales Order etc. will get stored. Open SE38 in S/4HANA system and run this report with parameter ZX for repository and RFC destination we created in step 1.2
Important to Note: This report should be run after onbaording the repository with the same name (e.g. ZX) using the DMS-Integration Option- Onboarding a Repository API which is described in the Section 3.
Figure 15: Input parameters for report CMIS_REPOSITORY_SETUP
Check the repository structure in CMIS workbench after running the report
Figure 16: Folder and subfolders created in repository ZX after running the report
3. Create repositories in BTP DMS using DMS integration option APIs
SAP API Business Hub can be used to try out the various APIs. For our scenario we have to use the APIs under SAP Document Management Service, Integration Option=>Administrative Options
While we can use Postman to execute these APIs, it is more convenient to add our BTP environment in the SAP API Business Hub in the Try Out Tab:
Figure 17: Add BTP environment for DMS Integration service in API Business Hub to try the APIs
The parameter values to add the BTP DMS Integration service environment can be found in the DMS-Integration Option Service key as shown in Figure 2 at the start of the blog.
Figure 18: How to Add environment in API Business Hub
Now lets run the API to Onboard a new repository with name ZP
Figure 19: Run API to onbaord a new repository ZP
If the environment is setup properly you will get a success message in the response body. Now run the report “CMIS_REPOSITORY_SETUP” as explained in Section 2 to create the folder structures in this repository.
Once you have also created the Content repository in S/4HANA in OAC0 and maintained the configurations in OACT, SKPR08 as explained in Section 1, this repository is ready to be used as a storage for documents attached using Generic Object Service (GOS) from business object like Sales Order (VA02) etc.
4. Use BTP DMS repository to store SAP GOS Attachments (Generic Object Service) and Business Document attachments (Archivelink)
We will use VA02 to understand how attachments GOS or Business documents are stored in the BTP DMS repository once all the configuration explained above is maintained.
Figure 20: Creating Attachments in VA02
Create Attachment uses SGOS
Save Business Document uses ArchiveLink
When we attach a document using Create Attachment it uses SAP Generic Object Service (GOS) to upload the attachment. SGOS attachments are stored in the content repository of the storage category mapped to class SOFFPHIO in SKPR08 e.g. in this blog I am using BTP DMS repository ZX. We can see the documents attached using GOS in the folder “/Knowledge Provider/SOFFPHIO” under the repository in CMIS Workbench.
Figure 21: Documents created under BTP DMS repository ZX through GOS attachments
For Business documents uploaded in VA02 the content repository created in OAC0 should have the Document Area “ArchiveLink”. The repository name can have only 2 characters.
Figure 22: Example of ArchiveLink repository created in OAC0 for storing Business Documents in BTP DMS repository
Maintain mapping in OAC3 for the Business Object, Document Type and Archive Link repository
Figure 23: Maintain mapping in OAC3
We can see the documents attached using “Save Business Document” option in VA02 in the folder “/Knowledge Provider/ArchiveLink” under the repository ZP in CMIS Workbench.
Figure 24: Business Documents stored under ArchiveLink folder in BTP DMS repository ZP
5. Use BTP DMS repositories for documents and tables archived using transaction SARA
Table and documents archived from transaction SARA for different Archiving Objects e.g. CV_DVS for Document Management, can also be stored in BTP DMS repository. Follow the steps below to maintain the BTP DMS Content repository for the archiving object
Go to Customizing->Technical Settings for the Archiving Object
Figure 25: Technical Settings for Archiving Object
Maintain Content Repository for the Archiving Object. Just type the content repository name if the F4 is not working for Content repositories in this screen.
Figure 26: Maintain Content Repository in Customizing
We can see the table or documents archived in the folder “/Knowledge Provider/ArchiveLink” under the repository ZP in CMIS Workbench.
6. View documents attached in CV02N in DMS repository using CMIS workbench.
When we check-in the attachment in CV02N we can select the Storage Category we created in transaction OACT to store them in the BTP DMS repository (e.g. ZX in this blog example)
Figure 27: Select storage category for BTP DMS created in OACT to check in documents into BTP DMS repo from CV02N
Documents attached in transaction CV01N / CV02N are stored in the folder “/Knowledge Provider/DMS_PCD1” under the repository ZX in CMIS Workbench.
Figure 28: Originals attached in CV02N transaction stored in folder DMS_PCD1 under repository ZX
It was a mammoth task to prepare this blog and I am happy I could complete it 🙂
Few other use cases for BTP DMS, and perhaps a topic for some future blog. Stay tuned!
- Integrate external repositories with S/4HANA using BTP DMS-Integration option.
- Consume documents uploaded in BTP DMS repository in 3rd party applications using the SAP Busines Object details (e.g. Sales Order Number) using APIs
- Use BTP DMS-Application Option for managing attachments created in custom Fiori apps running on BTP or on-premise.
