Store Attachments

Imagine you're a poetry slam manager using a specialized application to organize events. Some events include catering, and you can upload a menu so guests can view catering options and prices in advance.

For storing attachments, the SAP Document Management Service is used. Access to storage in your CAP application is managed with the SAP cap-js/sdm plugin. Setting up attachments involves several components:

The Document Management Service, Repository option service with the build-runtime service plan operates in the SAP BTP provider subaccount and is used to securely store and manage attachments in a repository.
The Document Management Service, Integration option service with the build-runtime service plan operates in the SAP BTP provider subaccount and is used to build document management capabilities for business applications and connect to the SAP Document Management Service repository.
The @cap-js/sdm plugin offers seamless integration at the CAP level with the SAP Document Management Service. It supports a reuse UI to manage and store attachments in the SAP Document Management Service repository. This is achieved through an aspect called Attachments.

Bill of Materials

Entitlements

In addition to the entitlements listed for the multitenancy version, the table below shows the entitlements that are required in the different subaccounts to store attachments.

Subaccount	Entitlement Name	Service Technical Name	Service Plan	Type	Quantity
Provider
	Document Management Service, Integration option	sdm	build-runtime	Service	1
	Document Management Service, Repository option	sdm-repository	build-runtime	Service	1

Enhancing the Application Step by Step

To explore this feature with the Poetry Slam Manager, you have two options:

Clone the repository of the Partner Reference Application. Check out the main-multi-tenant branch and enhance the application step by step.
Alternatively, check out the main-multi-tenant-features branch where the feature is already included.

The following describes how to enhance the main-multi-tenant branch (option 1).

Application Enablement

Enhance the Poetry Slam Manager domain model. Add the Attachments aspect to the domain model. This provides a reuse component which handles the storage of attachments in the SAP Document Management Service repository. More details are described in the cap-js/sdm documentation on GitHub.
```
    using { Attachments } from '@cap-js/sdm';

    extend PoetrySlams with {
        attachments           : Composition of many Attachments;
    }
```
Add the required npm modules as dependencies to the package.json files of your project. Refer to the root package.json file and the mtx/sidecar/ package.json file of the sample application.
1. Open a terminal in the root folder of the project.
2. Run the following command to add the @cap-js/sdm package. It provides the attachment aspect to the data model to store attachments in the SAP Document Management repository.
```
npm add @cap-js/sdm
```
3. Open the root package.json file and add the cds.xt.DeploymentService to it. It manages the provisioning of the repository per subscription and stores its details. For unsubscriptions, it securely cleans up the repository.
```
    "cds": {
        "requires": {
            "cds.xt.DeploymentService": {
                "preset": "in-sidecar"
            }
        }
    }
```
4. In the terminal, navigate to the ./mtx/sidecar/ folder.
```
cd mtx/sidecar
```
5. Add the @cap-js/sdm package to the mtx module to enable the attachment plugin for multitenancy.
```
npm add @cap-js/sdm
```
6. Open the package.json in the ./mtx/sidecar/ folder and add the SAP Document Management Service, Integration option to the CDS requires section.
```
    "cds": {
        "requires": {
            "poetry-slams-sdm-integration": {
                "vcap": {
                    "label": "sdm"
                },
                "subscriptionDependency": {
                    "uaa": "xsappname"
                }
            }
        }
    }
```
In the ./mtx/sidecar/ folder create a file called SDMRepositoryConfig.js with the following configuration:
```
    module.exports = {
        sdm: {
            repositoryConfig: {
                displayName: 'PRA SDM Repository',
                description: 'Onboarded on tenant subscription',
                repositoryType: 'internal',
                isVersionEnabled: 'false',
                isVirusScanEnabled: 'true',
                skipVirusScanForLargeFile: 'false',
                hashAlgorithms: 'SHA-256'
            }
        }
    };
```
Note: This file serves as the SAP Document Management Service repository configuration and can be adjusted based on preference, as seen in Internal Repository on SAP Help Portal. To store attachments with the SAP Document Management Service, a tenant-specific repository is created when you subscribe to the SaaS application. It is deleted when you unsubscribe, based on the configuration in the SDMRepositoryConfig.js file. Once the repository is created upon subscription, you can't update the configuration by changing the file and redeploying it. You need to update it using the APIs provided on SAP Business Accelerator Hub.
Add the sample catering PDF file to the ./srv/poetryslam/sample_data/ folder. The PDF is used to test the upload of an attachment and includes event-specific catering options for guests.

Open the xs-security.json file in the root and create a new PoetrySlamDocumentManagementRoleCollection role collection with the SDM_User scope, required to manage attachments.

    "role-collections": [
        {
            "name": "PoetrySlamDocumentManagementRoleCollection",
            "description": "Manage attachments of Poetry Slams",
            "role-template-references": [
                "$XSSERVICENAME(poetry-slams-sdm-integration).SDM_User"
            ]
        }
    ]

Note: poetry-slams-sdm-integration is the resource name parameter of the SAP Document Management Service definition in the mta.yaml file that is added in a later step.

Enhance the OData action called createTestData in the Poetry Slams service implementation with the new method handleAttachmentTestData. This method adds the sample catering PDF file as an attachment to the first poetry slam.

Note: To add the PDF file to the first poetry slam, ensure that both the SAP Document Management Service and the Authorization and Trust Management (XSUAA) service are connected.
```
    const Attachments = require('../lib/attachments');

    this.on('createTestData', async (req) => {
    // ...
    try {
        // ...
        const attachments = new Attachments(req, db, poetrySlamIDs);
        await attachments.handleAttachmentTestData();
    } catch {
        // ...
    }
    });
```
Copy the ./srv/lib/attachments.js file to your project to implement the handleAttachmentTestData method.

(Optional) The next step moves the Attachments section, provided by the plugin, below the Visitors and Artists section on the poetry slams object page. It shows how a CDS aspect can be overwritten with custom configurations. If this step is skipped, the Attachments aspect is the last section on the object page by default.

8.1. Enhance the ./app/poetryslams/annotations.cds file. This file overwrites the default set annotations of the Attachments aspect.

 ```cds
     annotate service.PoetrySlams with @(
         UI                             : {
             Facets                         : [
                 {
                     $Type : 'UI.LineItem',
                     ID    : 'Attachments',
                     Label : '{i18n>Attachments}',
                     Target: '@UI.LineItem#Attachments',
                 }
             ]
         }
     );

     annotate service.PoetrySlams.attachments with @UI: {LineItem #Attachments: [
         {
             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%'}
         }
     ]};

     annotate service.PoetrySlams.attachments with {
         folderId     @UI.Hidden;
         mimeType     @UI.Hidden;
         status       @UI.Hidden;
         repositoryId @UI.Hidden;
     };
 ```

8.2. Take over the rest of the annotations from the Attachments aspect and add them to the /db/poetrySlamManagerModel.cds file.

 ```cds
     annotate PoetrySlams.attachments with {
         note       @(title: '{i18n>note}');
         filename   @(title: '{i18n>filename}');
         content    @(title: '{i18n>attachment}');
         url        @readonly;
         modifiedAt @(odata.etag: null);
         content    @Core.ContentDisposition: {
             Filename: filename,
             Type    : 'inline'
         };
     };
 ```

8.3. For translation of the Attachments section title, copy the attachment-specific web application texts.

8.4. Furthermore, add translation support for the Attachments table by copying the domain model-i18n files.

SAP BTP Configuration and Deployment

Open the SAP BTP cockpit of the provider subaccount and add the required entitlements:
1. SAP Document Management Service with the technical name sdm and build-runtime plan to securely store and manage attachments.
2. SAP Document Management Service with the technical name sdm-repository and build-runtime plan to connect to the SAP Document Management Service repository.

Add the SAP Document Management Service, Integration option as resource into the mta.yaml file.

    # Document Management Service, Integration Option
    - name: poetry-slams-sdm-integration
    type: org.cloudfoundry.managed-service
    parameters:
        service: sdm
        service-plan: build-runtime

Additionally, it is required as a dependency in the service and MTX module.

    # Service module
    # Defines the microservice or application that will be serviced.
    # Contract between the service and the used microservices, and the rest of the application. It specifies what is required from the environment, and what it provides to the environment.
    - name: poetry-slams-srv
      requires:
        ...
        - name: poetry-slams-sdm-integration

    # MTX module
    # Handles multitenancy
    - name: poetry-slams-mtx
      requires:
        ...
        - name: poetry-slams-sdm-integration

Furthermore, a repository ID needs to be provided in both the poetry-slams-srv and poetry-slams-mtx modules. The provided REPOSITORY_ID corresponds to the externalId parameter of the created repository. It serves as a unique name for the repository. You can see this in the mta.yaml file.

    # Service module
    # Defines the microservice or application that will be serviced.
    # Contract between the service and the used microservices, and the rest of the application. It specifies what is required from the environment, and what it provides to the environment.
    - name: poetry-slams-srv
      requires:
        ...
        - name: poetry-slams-sdm-integration
      properties:
        REPOSITORY_ID: PSM_REPO

    
    # MTX module
    # Handles multitenancy
    - name: poetry-slams-mtx
      requires:
        ...
        - name: poetry-slams-sdm-integration
      properties:
        REPOSITORY_ID: PSM_REPO

Run the command in your project root folder to install the required npm modules.
```
npm install
```
Build and deploy the application. As a result, the SAP Document Management Service, Integration option instance named poetry-slams-sdm-integration is created.

Note: For detailed instructions on how to deploy, refer to Deploy Your SAP BTP Multi-Tenant Application.

Testing

As of now it is only possible to test the SAP Document Management Service in a hybrid test setup as described in Hybrid Testing.

Unit Tests

Unit tests are available to test the generation of test data including an attached sample PDF file:

Copy the test/srv/lib/attachments.test.js file to your project. This file tests the Attachments class.
To run the automated SAP Cloud Application Programming Model tests, follow these steps:
1. Enter the following command in a terminal in SAP Business Application Studio to install all required node modules.
```
npm install
```
2. Enter the following command to run all tests. The result is shown afterwards.
```
npm run test
```

A Guided Tour to Explore the Attachments Feature

Now it's time to take you on a guided tour through the attachment feature of the Poetry Slam Manager:

Open the SAP BTP cockpit of the customer subaccount.
Navigate to Security - Role Collections.
Assign the PoetrySlamDocumentManagementRoleCollection role collection to your user to be able to manage attachments in the Poetry Slam Manager.
Open the Poetry Slams application.
To create sample data for mutable data, such as poetry slams, visitors, and visits, choose Generate Sample Data. As a result, a list with several poetry slams is shown.

Note: If you choose Generate Sample Data again, the sample data is set to the default values.
Test the upload of a new attachment file.
1. Select a poetry slam event to upload an attachment.
  
  Note: The first poetry slam event already has an attachment uploaded with the sample catering menu PDF file.
2. Edit the event and upload the provided sample catering menu PDF file.
3. Save the draft.
4. Click on the link of the newly added attachment. The PDF file opens and displays various catering options for the poetry slam event.

Remarks and Troubleshooting

If an upload of a large attachment fails because of low bandwidth and a timeout, you can increase the default CAP Node.js server timeout. To adjust the timeout of the built-in Node.js server, make the following changes:

Create a server.js file in the ./srv/ folder.
In the CAP listening event, the server timeout can be increased.

    const cds = require('@sap/cds'):
    // Listen to the 'listening' event to access the actual CAP HTTP server
    cds.once('listening', ({ server }) => {
        server. requestTimeout = 10 * 60 * 1000: // 10 minutes in ms
        console. log ("Node.js server timeout: ", server.requestTimeout);
    });
    module exports = cds. server;

The SAP Document Management Service does not yet provide API access to test the service using the service broker.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Store Attachments

Bill of Materials

Entitlements

Enhancing the Application Step by Step

Application Enablement

SAP BTP Configuration and Deployment

Testing

Unit Tests

A Guided Tour to Explore the Attachments Feature

Remarks and Troubleshooting

FilesExpand file tree

47-Multi-Tenancy-Features-Attachments.md

Latest commit

History

47-Multi-Tenancy-Features-Attachments.md

File metadata and controls

Store Attachments

Bill of Materials

Entitlements

Enhancing the Application Step by Step

Application Enablement

SAP BTP Configuration and Deployment

Testing

Unit Tests

A Guided Tour to Explore the Attachments Feature

Remarks and Troubleshooting