Use SAP Document Management service (DMS), Integration Option to Store Document Files

Blogs for DMS series:

• Use SAP Document Management service (DMS), Integration Option to Store Document Files
• Use SAP Document Management service (DMS), Application Option to Store Document Files

Introduction of DMS

SAP Document Management Service is a content management solution on the Cloud Foundry environment of SAP BTP.

You can consume the SAP Document Management Service in different ways:

• SAP Document Management, integration option lets you build document management capabilities for your business applications. Features of Document Management, integration option

• SAP Document Management, application option is a standalone, ready-to-use web application that provides document management capabilities for your enterprise content. Features of Document Management, application option

• SAP Document Management, repository option lets you securely store and manage your documents. Features of Document Management service, repository option

Document Management, repository option isn’t an independent offering. You can use it for storage purposes along with Document Management, integration option or Document Management, application option.

You can purchase Document Management, integration option or application option, for storage purposes, you can either connect to your own storage or use Document Management, repository option.

Your own storage should be CMIS-compliant, on-premise, or cloud repository.

Thus, you can consume the DMS by the following combination:

• Document Management, integration option + your own storage

• Document Management, integration option + Document Management, repository option

• Document Management, application option + your own storage

• Document Management, application option + Document Management, repository option

Usage of Document Management, repository option

Usage of Document Management, repository option is defined as internal method. The Document Management Service, Repository Option can’t be used as standalone. It must be used with one of two options: Document Management Service, Application Option or Document Management Service, Integration Option.

As it’s a commercial entitlement, no tiles appear in the cloud cockpit’s. You should assign the entitlements of the Document Management, repository option to the same subaccount where Document Management, integration option or Document Management, application option instance is created.

In the global account, assign the entitlement to your subaccount:

Usage of Document Management, integration option

Step 1: Create Instance

Create an instance of Document Management Service, Integration Option:

Step 2: Create Service Key

Create a service key for the instance:

You can identity some informations in the service key, which are necessary in the following steps:

• ecmservice-url: endpoints:ecmservice:url

• uaa-url: uaa:url

• uaa-clientid: uaa:clientid

• uaa-clientsecret: uaa:clientsecret

Step 3: Connect to Document Management, Repository Option

Connect your instance of Document Management, integration option to Document Management, repository option for file storage using REST APIs, for example:

URL: <ecmservice-url>/rest/v2/repositories/

HTTP Method: POST

UAA URL: <uaa-url>/oauth/token

UAA clientid: <uaa-clientid>

UAA clientsecret: <uaa-clientsecret>

Body:

{
  "repository": {
    "displayName": "TIA_REPOSITORY_INTEGRATION_OPTION",
    "description": "Demo for the integration option.",
    "repositoryType": "internal",
    "isVersionEnabled":"true",
    "isVirusScanEnabled":"true",
    "skipVirusScanForLargeFile": "false",
    "hashAlgorithms":"SHA-256",
    "isContentBridgeEnabled": "true",
    "externalId": "TIA_REPOSITORY_INTEGRATION_OPTION"
  }
}

Response:

{
    "cmisRepositoryId": "9884357...ed3c26",
    "createdTime": "...",
    "description": "Demo for the integration option.",
    "externalId": "TIA_REPOSITORY_INTEGRATION_OPTION",
    "id": "7fd4cc24-65...cac4b60b6",
    "lastUpdatedTime": "...",
    "name": "TIA_REPOSITORY_INTEGRATION_OPTION",
    "repositoryCategory": "Instant",
    "repositoryParams": [
        {
            "paramName": "isVersionEnabled",
            "paramValue": true
        },
        {
            "paramName": "isVirusScanEnabled",
            "paramValue": true
        },
        {
            "paramName": "hashAlgorithms",
            "paramValue": "SHA-256"
        },
        {
            "paramName": "isContentBridgeEnabled",
            "paramValue": true
        },
        {
            "paramName": "skipVirusScanForLargeFile",
            "paramValue": false
        }
    ],
    "repositorySubType": "SAP Document Management Service",
    "repositoryType": "internal"
}

For more information, see SAP API Business Hub.

Step 4: Determine Repository RepositoryId and rootFolderId

In order to consume the reuse UI in an SAP Fiori application in the next step, you need to determine the repositoryId and rootFolderId for your repository. You can get the repository details using Restful API, for example:

URL: <ecmservice-url>/browser

HTTP Method: GET

UAA URL: <uaa-url>/oauth/token

UAA clientid: <uaa-clientid>

UAA clientsecret: <uaa-clientsecret>

Response:

{
    "TIA_REPOSITORY_INTEGRATION_OPTION": {
        "repositoryId": "TIA_REPOSITORY_INTEGRATION_OPTION",
        "repositoryName": "TIA_REPOSITORY_INTEGRATION_OPTION",
        "repositoryDescription": "Demo for the integration option.",
        "vendorName": "SAP AG",
        "productName": "SAP Document Management Service",
        "productVersion": "1.0",
        "rootFolderId": "9884357000431e0176ed3c26",
        ...
        "repositoryUrl": "https://api-di.sdm.cn40.apps.platform.sapcloud.cn/browser/TIA_REPOSITORY_INTEGRATION_OPTION",
        "rootFolderUrl": "https://api-di.sdm.cn40.apps.platform.sapcloud.cn/browser/TIA_REPOSITORY_INTEGRATION_OPTION/root",
        "cmisRepositoryId": "9884357000431e0176ed3c26",
        "repositoryCategory": "Instant",
        "externalId": "TIA_REPOSITORY_INTEGRATION_OPTION",
        "connectionType": "service"
    }
}

Step 5: Consume Reuse UI in an SAP Fiori Application

Embed the reusable UI component in your SAP Fiori application to display a list of documents from a repository and add document management capabilities. Thus, in order to consume the reusable UI, you should have a basic MTA Fiori Application.

In this post, we will use SAP Business Application Studio to develop a MTA Fiori Application.

1. Create a MTA Fiori Application in SAP Business Application Studio

For example, in the terminal of the Business Application Studio, execute yo fiori-project, and select the target running environment Cloud Foundry, select the template SAPUI5 Application, enter a project name, e.g. documentmanagement, select your HTML5 application runtime Standalone Approuter, etc., according to your own requirements.

Then, a MTA Fiori project would be created:

2. Integrate with DMS

In the mta.yaml, under resources section, add the following part:

- name: dms-instance
  type: org.cloudfoundry.managed-service
  parameters:
    service: sdm
    service-plan: standard

In the mta.yaml, modify modules/name=documentmanagement-approuter/requires with the following part, where <ecmservice-url> can be found by following the previous step:

  - name: dms-instance
    properties: 
      destinations: "[{\"name\": \"sdibackend\", \"url\": \"<ecmservice-url>\", \"forwardAuthToken\": true}]"

For example:

modules:
- name: documentmanagement-approuter
  type: approuter.nodejs
  path: documentmanagement-approuter
  requires:
  - name: documentmanagement_html_repo_runtime
  - name: dms-instance
    properties: 
      destinations: "[{\"name\": \"sdibackend\", \"url\": \"https://api-di.sdm.cn40.apps.platform.sapcloud.cn/\", \"forwardAuthToken\": true}]"
  parameters:
    disk-quota: 256M
    memory: 256M

In the manifest.json of the UI5 webapp, add component usage. Where, the repositoryId and rootFolderId can be found by following the previous step.

{
    ...
    "sap.ui5": {
        "componentUsages": {
            "documentTable": {
                "name": "com.sap.ecm.reuse.documentTable",
                "settings": {
                    "repositoryId": "<repositoryId>",
                    "objectId": "<rootFolderId>"
                }
            }
        },
        "resourceRoots": {
            "com.sap.ecm.reuse.documentTable": "./../comsapecmreuse.comsapecmreusedocumentTable/"
        },
        ...
    }
}

Add the component to your application, in any view, by defining a ComponentContainer and its usage.

<mvc:View controllerName="ns.HTML5Module.controller.View1" xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc" displayBlock="true" xmlns="sap.m">
  <Shell id="shell">
    <App id="app">
      <pages>
        <Page id="page" title="Document Management Admin UI">
          <content>
            <core:ComponentContainer usage="documentTable" height="100%" async="false" manifest="true"/>
          </content>
        </Page>
      </pages>
    </App>
  </Shell>
</mvc:View>

Edit the xs-app.json file in the UI5 module of your SAP Fiori application. To route the API calls to Document Management Service, Integration Option’s server, add one more route to /api.

{
    "welcomeFile": "/index.html",
    "authenticationMethod": "none",
    "logout": {
        "logoutEndpoint": "/do/logout"
    },
    "routes": [
        {
            "source": "^/api/(.*)$",
            "target": "$1",
            "authenticationType": "xsuaa",
            "service": "com.sap.ecm.reuse",
            "endpoint": "ecmservice"
        },
        {
            "source": "^(.*)$",
            "target": "$1",
            "service": "html5-apps-repo-rt",
            "authenticationType": "xsuaa"
        }
    ]
}

Update the xs-app.json file in the approuter app, and replace the placeholder with your own names:

{
    "welcomeFile": "/<namespace-name><html5-module-name>/index.html",
    "authenticationMethod": "none",
    "routes": []
}

For example:

{
    "welcomeFile": "/nsHTML5Module/index.html",
    "authenticationMethod": "none",
    "routes": []
}

For more details, please read: Consume Reuse UI for Document Management Service

3. Buid and Deploy to SAP BTP

Right click on the mta.yaml file and select Build MTA project.

Later right click on the file inside mta_archives folder and select Deploy MTA Archieve (Make sure you’ve logged into your SAP BTP account).

Step 6: Configure User Access

Make sure that the roles SDM_User and SDM_Admin is included into the role collection dedicated for DMS, and ensure the role collection has been assigned to yourself.

Step 7: Access your Fiori Application

You can get your own deployed application URL through Cockpit or CF CLI command, for example: https://cn40-enable…management-approuter.enablement.cn40.apps.platform.sapcloud.cn/

The Reuse UI in the SAP Fiori Application looks like:

Then you can upload or download documents directly in this UI page.

Step 8: Upload or Download Files Using APIs

Document Management Service provides integration option with API capabilities. With Document Management Service integration option, users can onboard repository, upload or download files and other supported actions via APIs. The APIs of Document Management Service follow standard CMIS call. For more details on CMIS specification, please read CMIS specification official documentation: https://docs.oasis-open.org/cmis/CMIS/v1.1/CMIS-v1.1.html.

1. Upload files with API:

URL: <ecmservice-url>/browser/<repository-id>/root/

HTTP Method: POST

UAA URL: <uaa-url>/oauth/token

UAA clientid: <uaa-clientid>

UAA clientsecret: <uaa-clientsecret>

2. Get the objectId of the file with API, where the folder-id represents the objectId of the folder where the file located in:

URL: <ecmservice-url>/browser/<repository-id>/root?cmisselector=children&&objectId=<folder-id>

HTTP Method: GET

UAA URL: <uaa-url>/oauth/token

UAA clientid: <uaa-clientid>

UAA clientsecret: <uaa-clientsecret>

3. Download the file with API:

URL: <ecmservice-url>/browser/<repository-id>/root?objectId=<object-id>&cmisSelector=content&download=attachment&filename=<file-name>

HTTP Method: GET

UAA URL: <uaa-url>/oauth/token

UAA clientid: <uaa-clientid>

UAA clientsecret: <uaa-clientsecret>

References

Help Portal – SAP Document Management Service