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.
Display attachments specific to repository: Lists attachments contained in the repository that is configured with the CAP application.
Custom properties in attachments : Provides the capability to define custom properties for attachments in SDM.
Link as attachments: Provides the capability to support link or URL as attachments.

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. Configure the REPOSITORY_ID with the repository you want to use for deploying the application. Set the SDM instance name to match the SAP Document Management integration option instance you created in BTP and update this in the mta.yaml file under the srv module and the resources section values in the mta.yaml. Currently only non versioned repositories are supported.

Support for Custom Properties

Custom properties are supported via the usage of CMIS secondary type properties. Follow the below steps to add and use custom properties.

If the repository does not contain secondary types and properties, create CMIS secondary types and properties using the Create Secondary Type API. The property definition must contain the following section for the CAP plugin to process the property.

"mcm:miscellaneous": {        
   "isPartOfTable": "true"  
}

With this, the secondary type and properties definition will be as per the sample given below

{
   "id": "Working:DocumentInfo",
   "displayName": "Document Info",
   "baseId": "cmis:secondary",
   "parentId": "cmis:secondary",
   ...
   "propertyDefinitions": {
      "Working:DocumentInfoRecord": {
            "id": "Working:DocumentInfoRecord",
            "displayName": "Document Info Record",
            ...
            "mcm:miscellaneous": {     <-- Required section in the property definition
               "isPartOfTable": "true"
            }
      }
   }
}

Using secondary properties in CAP Application.
- Extend the Attachments aspect with the secondary properties in the previously created db/attachments.cds file.
- Annotate the secondary properties with @SDM.Attachments.AdditionalProperty.name.
- In this field set the name of the secondary property in SDM.
Refer the following example from a sample Incidents Management app:
```
extend Attachments with {
   customProperty : String
      @SDM.Attachments.AdditionalProperty: {
         name: 'Working:DocumentInfoRecordString'
      }  
      @(title: 'DocumentInfoRecordString');
}
```
Note

SDM supports secondary properties with data types String, Boolean, Decimal, Integer and DateTime.

Support for link type attachments

Note: Row-press is the new recommended approach for handling actions on attachment rows. With row-press enabled, the Attachments column will no longer appear as a separate action button. Instead, clicking on a row will automatically perform the appropriate action — opening a link or downloading a file, based on the attachment type.

This plugin provides the capability to create, open, rename and delete attachments of link type.

Steps to Enable Row-Press for Open Link

Add the openAttachment action to application's service definition

See this example from a sample incidents-management app.
```
action openAttachment() returns String;
```

Add a custom controller extension

In webapp/controller/custom.controller.js, copy and paste below content.

See this example from a sample incidents-management app.

sap.ui.define(
   [
   "sap/ui/core/mvc/ControllerExtension",
   "sap/m/library"
   ], 
   function (ControllerExtension,library) {
      "use strict";
 
      return ControllerExtension.extend("ns.incidents.controller.custom", {
         onRowPress: function(oContext) {
            this.base.editFlow
            .invokeAction("ProcessorService.openAttachment", {
               contexts: oContext.getParameter("bindingContext")
            })
            .then(function (res) {
               let odataurl = "";
               if(res.getObject().value == "None") {
                  const lastSlashIndex = res.oModel.getServiceUrl().lastIndexOf('/');
                  let str = res.oModel.getServiceUrl();
                  if (lastSlashIndex !== -1) {
                     str = str.substring(0, lastSlashIndex)  + str.substring(lastSlashIndex + 1);
                  }
                  odataurl = str+res.oBinding.oContext.sPath+"/content";
               } else {
                  odataurl = res.getObject().value;
               }
               library.URLHelper.redirect(odataurl, true);              
            });
         }
     });
   }
);

Replace ns.incidents in ControllerExtension.extend with the id in manifest.json file or id in component.js file. See this example.
Replace ProcessorService in invokeAction("ProcessorService.openAttachment") with the name of your service.

Add controlConfiguration for Row Press

In your sap.ui5.routing.targets section, under the relevant Object Page (e.g., IncidentsObjectPage), add or extend the controlConfiguration for the facet you want to enhance by copy and pasting below content. See this example.
```
"controlConfiguration": {
   "attachments/@com.sap.vocabularies.UI.v1.LineItem": {
      "tableSettings": {
         "type": "ResponsiveTable",
         "selectionMode": "Auto",
         "rowPress": ".extension.ns.incidents.controller.custom.onRowPress"
      }
   }
}
```
- Replace attachments with your entity’s facet name as needed.
- Replace ns.incidents in "rowPress": ".extension.ns.incidents.controller.custom.onRowPress" with the id in manifest.json file. Refer this example from a sample incidents-management app.
Register the Custom Controller Extension

In the root of your sap.ui5 section, add or extend the extends property to register your custom controller by copy and pasting below content. See this example.
```
"extends": {
   "extensions": {
      "sap.ui.controllerExtensions": {
         "sap.fe.templates.ObjectPage.ObjectPageController#ns.incidents::IncidentsObjectPage": {
            "controllerName": "ns.incidents.controller.custom"
         }
      }
   }
}
```
- Replace ns.incidents in "sap.fe.templates.ObjectPage.ObjectPageController#ns.incidents::IncidentsObjectPage" with the id in manifest.json file. Refer this example from a sample incidents-management app.
- Replace IncidentsObjectPage in "sap.fe.templates.ObjectPage.ObjectPageController#ns.incidents::IncidentsObjectPage" with id of the relevant Object Page (e.g., IncidentsObjectPage). Refer this example from a sample incidents-management app.
- Replace ns.incidents in "controllerName": "ns.incidents.controller.custom"with the id in manifest.json file. Refer this example from a sample incidents-management app.

Steps to Enable Create Link Feature in CAP Application

Note: Enabling row-press for open link (see steps above) is a prerequisite for link support.

Add the createLink action to application's service definition

See this example from a sample incidents-management app:

entity Incidents.attachments as projection on my.Incidents.attachments
actions {
   @(Common.SideEffects : {TargetEntities: ['']},)
   action createLink(
      in:many $self,
      @mandatory @Common.Label:'Name' name: String @UI.Placeholder: 'Enter a name for the link',
      @mandatory @assert.format:'^(https?:\/\/)(([a-zA-Z0-9\-]+\.)+[a-zA-Z]{2,}|localhost)(:\d{2,5})?(\/[^\s]*)?$'
      @Common.Label:'URL' url: String @UI.Placeholder: 'Example: https://www.example.com'
   );
}

Purpose: Enables users to create links with name and URL.
Validation: Ensures only valid HTTP(S) URLs are accepted.
UI Support: Provides labels and placeholders for better user experience.

UI Annotation Setup

To enable the creation of links, you need to add a new button to the attachments table toolbar. This button will appear as a menu button labeled "Create" on the toolbar of the attachments table. When clicked, it will display a menu with the "Link" option, allowing users to create a new link-type attachment.

Add the following annotation block to your app/<entity-folder>/<annotation-file>.cds file. See this example.

annotate service.Incidents.attachments with @UI: {
  HeaderInfo: {
        $Type         : 'UI.HeaderInfoType',
        TypeName      : '{i18n>Attachment}',
        TypeNamePlural: '{i18n>Attachments}',
  },
  LineItem  : [
    {Value: type, @HTML5.CssDefaults: {width: '10%'}},
    {Value: filename, @HTML5.CssDefaults: {width: '25%'}},
    {Value: content, @HTML5.CssDefaults: {width: '0%'}},
    {Value: createdAt, @HTML5.CssDefaults: {width: '20%'}},
    {Value: createdBy, @HTML5.CssDefaults: {width: '20%'}},
    {Value: note, @HTML5.CssDefaults: {width: '25%'}},
    {
      $Type  : 'UI.DataFieldForActionGroup',
      ID     : 'TableActionGroup',
      Label  : 'Create',
      ![@UI.Hidden]: {$edmJson: {$Eq: [ {$Path: 'IsActiveEntity'}, true ]}},
      Actions: [
        {
          $Type : 'UI.DataFieldForAction',
          Label : 'Link',
          Action: 'ProcessorService.createLink',
        }
      ]
    },
  ]
}
{
  url @readonly;
  note @(title: '{i18n>Note}');
  filename @(title: '{i18n>Filename}');
  modifiedAt @(odata.etag: null);
  content
      @Core.ContentDisposition: { Filename: filename, Type: 'inline' }
      @(title: '{i18n>Attachment}');
  folderId @UI.Hidden;
  mimeType @UI.Hidden;
  status @UI.Hidden;
  repositoryId @UI.Hidden;
}

Replace service.Incidents.attachments with the correct path for your entity and element (for example, my.YourEntity.yourElement) where you have defined composition of many Attachments.
Replace ProcessorService in Action: 'ProcessorService.createLink' with the name of your service.

Updating Tenant Databases for Link Feature

To support the Link feature, additional database columns are introduced. Upon re-deployment of your multitenant application, you may encounter "invalid column" errors if tenant database containers are not updated.

To resolve this, ensure the following task is added to the mta.yaml for the sidecar application.

tasks:
   -  name: upgrade-db
      command: cds-mtx upgrade '*'

This will automatically update tenant databases during deployment.

Support for Multitenancy

This plugin automates repository lifecycle management in a multi-tenant setup. On tenant subscription, it provisions a repository and stores its details, and on unsubscription, it securely cleans up the repository.

Refer the following example from a sample Incidents Management app which demonstrates how to onboard a new repository for a subscribing tenant.

Add the cds.xt.DeploymentService to the package.json file

"cds": {
"requires": {
    "cds.xt.DeploymentService": {
        "preset": "in-sidecar"
     }
  }
}

Add the @cap-js/sdm dependency to the mtx/sidecar/package.json
Add the external id of repository in properties of incidents-mtx-mtx in mta.yaml

Add SDMRepositoryConfig.js file in mtx/sidecar folder with the following content:

module.exports = {
    sdm: {
        repositoryConfig: {
        displayName: "SDM Repository",
        description: "Onboarded on tenant subscription",
        repositoryType: "internal",
        isVersionEnabled: "false",
        isVirusScanEnabled: "false",
        skipVirusScanForLargeFile: "true",
        hashAlgorithms: "SHA-256"
        }
    }
};

When the application is deployed as a SaaS application with above code, a repository is onboarded automatically when a tenant subscribes the SaaS application. The same repository is deleted when the tenant unsubscribes from the SaaS application. The necessary params for the Repository onboarding can be found in the documentation.

Deploying and testing the application

Log in to Cloud Foundry space:

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. The file is then 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.

Name		Name	Last commit message	Last commit date
Latest commit History 640 Commits
.github		.github
.reuse		.reuse
LICENSES		LICENSES
etc		etc
lib		lib
test		test
xmpl/db/content		xmpl/db/content
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PULL_REQUEST_TEMPLATE.md		PULL_REQUEST_TEMPLATE.md
README.md		README.md
cds-plugin.js		cds-plugin.js
eslint.config.mjs		eslint.config.mjs
index.cds		index.cds
jest-integration.config.js		jest-integration.config.js
jest.config.js		jest.config.js
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

CAP plugin for SAP Document Management Service

Key features

Table of Contents

Pre-Requisites

Setup

Using the released version

Using the development version

Use @cap-js/sdm plugin

Support for Custom Properties

Support for link type attachments

Steps to Enable Row-Press for Open Link

Steps to Enable Create Link Feature in CAP Application

UI Annotation Setup

Updating Tenant Databases for Link Feature

Support for Multitenancy

Deploying and testing the application

Running the unit tests

Known Restrictions

Support, Feedback, Contributing

Code of Conduct

Licensing

About

Uh oh!

Releases 13

Packages

Uh oh!

Contributors 9

Uh oh!

Languages

License

cap-js/sdm

Folders and files

Latest commit

History

Repository files navigation

CAP plugin for SAP Document Management Service

Key features

Table of Contents

Pre-Requisites

Setup

Using the released version

Using the development version

Use @cap-js/sdm plugin

Support for Custom Properties

Support for link type attachments

Steps to Enable Row-Press for Open Link

Steps to Enable Create Link Feature in CAP Application

UI Annotation Setup

Updating Tenant Databases for Link Feature

Support for Multitenancy

Deploying and testing the application

Running the unit tests

Known Restrictions

Support, Feedback, Contributing

Code of Conduct

Licensing

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Contributors 9

Uh oh!

Languages

Packages