CAP plugin for SAP Document Management Service

The project is currently in the development stage, where our team is actively working on building and refining its core components to ensure it meets all specified requirements and objectives.

The @cap-java/sdm package is cds-plugin that provides an easy CAP-level integration with SAP Document Management Service. This package supports handling of attachments(documents) by using an aspect Attachments in SAP Document Management Service.
This plugin can be consumed by the CAP application deployed on BTP to store their documents in the form of attachments in Document Management Repository.

Key features

• Create attachment : Provides the capability to upload new attachments.
• Virus scanning : Provides the capability to support virus scan for virus scan enabled repositories.
• Draft functionality : Provides the capability of working with draft attachments.

Table of Contents

• Pre-Requisites
• Deploying and testing the application
• Use @cap-java/sdm plugin
• Known Restrictions
• Support, Feedback, Contributing
• Code of Conduct
• Licensing

Pre-Requisites

• Java 17 or higher
• CAP Development Kit (npm install -g @sap/cds-dk)
• SAP Build WorkZone should be subscribed to view the HTML5Applications.
• MTAR builder (npm install -g mbt)
• Cloud Foundry CLI, Install cf-cli and run command cf install-plugin multiapps.

[!Note] cds-services

The behaviour of clicking attachment and opening it varies based on the version of cds-services used by the CAP application.

• For cds-services version >= 3.4.0, clicking on attachment will

  • open the file in new browser tab, if browser supports the file type.
  • download the file to the computer, if browser does not support the file type.

• For cds-services version < 3.4.0, clicking on attachment will download the file to the computer

A reference to adding this can be found here

Deploying and testing the application

1. Log in to Cloud Foundry space:

   cf login -a <CF-API> -o <ORG-NAME> -s <SPACE-NAME>

2. Create a SAP Document Management Integration Option Service instance and key. Bind your CAP application to this SDM instance. Add the details of this instance to the resources section in the mta.yaml of your CAP application. Refer the following example from a sample Bookshop app.

   modules:
      - name: bookshop-srv
      type: java
      path: srv
      requires:
         - name: sdm-di-instance
   
   resources:
      - name: sdm-di-instance
      type: org.cloudfoundry.managed-service
      parameters:
         service: sdm
         service-plan: standard
   

3. Using the created SDM instance's credentials from key onboard a repository. In mta.yaml, under properties of the srv module add the repository id. Refer the following example from a sample Bookshop app. Currently only non versioned repositories are supported.

   modules:
     - name: bookshop-srv
     type: java
     path: srv
     properties:
           REPOSITORY_ID: <REPO ID>
     requires:
        - name: sdm-di-instance
   

4. Add the following pom dependency in the srv folder

   <dependency>
      <groupId>com.sap.cds</groupId>
      <artifactId>sdm</artifactId>
      <version>1.0.0-SNAPSHOT</version>
   </dependency>

5. In the app/index.html file you will find this line

      <script id="sap-ui-bootstrap" src="https://sapui5.hana.ondemand.com/resources/sap-ui-core.js"

   Replace the src url with this instead

      "https://sapui5nightly.int.sap.eu2.hana.ondemand.com/resources/sap-ui-core.js"

6. Add the following facet in fiori-service.cds in the app folder

      {
         $Type : 'UI.ReferenceFacet',
         ID     : 'AttachmentsFacet',
         Label : '{i18n>attachments}',
         Target: 'attachments/@UI.LineItem'
      }

7. Build the project by running following command from root folder of your CAP application

   mbt build

   Above step will generate .mtar file inside mta_archives folder.

8. Deploy the application

   cf deploy mta_archives/*.mtar

9. Go to your BTP subaccount and launch your application.

10. The Attachments type will generate an out-of-the-box Attachments table.

Use @cap-java/sdm plugin

To use sdm plugin in your CAP application, create an element with an Attachments type. Following the best practice of separation of concerns, create a separate file srv/attachment-extension.cds and extend your entity with attachments. Refer the following example from a sample Bookshop app:

using {my.bookshop.Books } from '../db/books';
using {sap.attachments.Attachments} from`com.sap.cds/sdm`;
 
extend entity Books with {
    attachments : Composition of many Attachments;
}

Known Restrictions

• Repository : This plugin does not support the use of versioned repositories.
• File size : Attachments are limited to a maximum size of 100 MB.

Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2024 SAP SE or an SAP affiliate company and contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.