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.

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:

Clone the incidents-app repository:

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

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

   git checkout incidents-app-deploy

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:

Clone the sdm repository:

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

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

Clone the incidents-app repository:

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

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

   git checkout incidents-app-deploy

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

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

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

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.
Deploy the application
```
cf deploy mta_archives/*.mtar
```

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.

The Attachments type has generated an out-of-the-box Attachments table (see highlighted box) at the bottom of the Object page:
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:
Open a file by clicking on the attachment. We demonstrate this by opening the previously uploaded PDF file: Solar Panel Report.pdf
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
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.

cap-js/sdm