CAP plugin for SAP Document Management Service

The @cap-js/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.
• Open attachment : Provides the capability to preview attachments.
• Delete attachment : Provides the capability to remove attachments.
• Rename attachment : Provides the capability to rename 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
• Setup
• Use @cap-js/sdm plugin
• Deploying and testing the application
• Running the unit tests
• Known Restrictions
• Support, Feedback, Contributing
• Code of Conduct
• Licensing

Pre-Requisites

• Node.JS 16 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.

Setup

In this guide, we use the Incidents Management reference sample app as the base application, to integrate SDM CAP plugin.

[!Note] To be able to use the Fiori uploadTable feature, you must ensure 1.121.0/ 1.122.0/ ^1.125.0 SAPUI5 version is updated in the application's index.html

Using the released version

If you want to use the released version of SDM CAP plugin follow the below steps:

1. Clone the incidents-app repository:

   git clone https://github.com/cap-js/incidents-app.git

2. Navigate to incidents-app root folder and checkout to the branch incidents-app-deploy:

   git checkout incidents-app-deploy

3. Install SDM CAP plugin by executing the following command:

   npm add @cap-js/sdm

Using the development version

If you want to use the version under development follow the below steps:

1. Clone the sdm repository:

   git clone https://github.com/cap-js/sdm.git

2. Open terminal, navigate to sdm root folder and generate tarball:

   npm pack

   This will generate a file with name cap-js-sdm-x.y.z.tgz

3. Clone the incidents-app repository:

   git clone https://github.com/cap-js/incidents-app.git

4. Navigate to incidents-app root folder and checkout to the branch incidents-app-deploy:

   git checkout incidents-app-deploy

5. Copy the path of .tgz file generated in step 2 and in terminal navigate to incidents-app root folder and execute:

   npm install <path-to-.tgz file>

Use @cap-js/sdm plugin

To use sdm plugin in incidents-app, create an element with an Attachments type. Following the best practice of separation of concerns, create a separate file db/attachments.cds and paste the below content in it:

using { sap.capire.incidents as my } from './schema';
using { Attachments } from '@cap-js/sdm';

extend my.Incidents with { attachments: Composition of many Attachments }

Create a SAP Document Management Integration Option Service instance and key. Using credentials from key onboard a repository and configure the onboarded repositoryId under cds.requires in package.json. Currently only non versioned repositories are supported.

"sdm": {
   "settings": {
   "repositoryId": "<repository-Id>"
   }
}

Deploying and testing the application

1. Log in to Cloud Foundry space:

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

2. Bind CAP application to SAP Document Management Integration Option. Check the following reference from mta.yaml of Incidents Management app

   modules:
      - name: incidents-srv
      type: nodejs
      path: gen/srv
      requires:
         - name: sdm-di-instance
     
   resources:
      - name: sdm-di-instance
      type: org.cloudfoundry.managed-service
      parameters:
         service: sdm
         service-plan: standard

3. Build the project by running following command from root folder of incidents-app.

   mbt build

   Above step will generate .mtar file inside mta_archives folder.

4. Deploy the application

   cf deploy mta_archives/*.mtar

5. Launch the application

   * Navigate to Html5Applications menu in BTP subaccount and open the application (nsincidents v1.0.0) in a browser.
   * Click on incident with title Solar panel broken.

6. The Attachments type has generated an out-of-the-box Attachments table (see highlighted box) at the bottom of the Object page:

7. Upload a file by going into Edit mode and either using the Upload button on the Attachments table or by drag/drop. Then click the Save button to have that file stored in SAP Document Management Integration Option. We demonstrate this by uploading the PDF file from xmpl/db/content/Solar Panel Report.pdf:

8. Open a file by clicking on the attachment. We demonstrate this by opening the previously uploaded PDF file: Solar Panel Report.pdf

9. Rename a file by going into Edit mode and setting a new name for the file in the filename field. Then click the Save button to have that file renamed in SAP Document Management Integration Option. We demonstrate this by renaming the previously uploaded PDF file: Solar Panel Report.pdf

10. Delete a file by going into Edit mode and selecting the file(s) and by using the Delete button on the Attachments table. Then click the Save button to have that file deleted from the resource (SAP Document Management Integration Option). We demonstrate this by deleting the previously uploaded PDF file: Solar Panel Report_2024.pdf

Running the unit tests

To run the unit tests:

npm run test

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.