@cap-js/attachments v2.1.2

Attachments Plugin

The @cap-js/attachments package is a CDS plugin that provides out-of-the box asset storage and handling by using an aspect Attachments. It also provides a CAP-level, easy to use integration of the SAP Object Store.

Table of Contents

• Setup
• Use Attachments
• Test-drive Locally
• Using SAP Object Store
• Using SAP Malware Scanning service
• Multitenancy
• Contributing
• Code of Conduct
• Licensing

Setup

To enable attachments, simply add this self-configuring plugin package to your project:

 npm add @cap-js/attachments

In this guide, we use the Incidents Management reference sample app as the base application, to add Attachments type to the CDS model.

!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

Use Attachments

!Note To be able to use the plugin, make sure draft is enabled for the entity.

To use Attachments, simply add an element referring to the pre-defined Attachments type as follows:

using { Attachments } from '@cap-js/attachments';

entity Incidents {
  // ...
  attachments: Composition of many Attachments;
}

Test-drive Locally

With the steps above, we have successfully set up asset handling for our reference application. Let's see that in action. We can try out the scenarios where the attachments contents are stored locally in the database.

1. Start the server:

• Default scenario (In memory database):

  cds watch

2. Navigate to the object page of the incident Solar panel broken:

   Go to Object page for incident Solar panel broken

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

4. 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 that file in the dedicated resource (database, S3 bucket, etc.). We demonstrate this by uploading the PDF file from xmpl/db/content/Solar Panel Report.pdf:

5. 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 (database, S3 bucket, etc.). We demonstrate this by deleting the previously uploaded PDF file: Solar Panel Report.pdf

Using SAP Object Store

For using SAP Object Store, you must already have a SAP Object Store service instance with a bucket which you can access. To connect it, follow this setup.

1. Log in to Cloud Foundry:

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

2. To bind to the service continue with the steps below.

   In the project directory, you can generate a new file _.cdsrc-private.json by running:

   cds bind objectstore -2 <INSTANCE>:<SERVICE-KEY> --kind s3

Using SAP Malware Scanning Service

For using SAP Malware Scanning Service, you must already have a service instance which you can access.

1. To bind to the service continue with the steps below.

   cds bind malware-scanner -2 <INSTANCE>:<SERVICE-KEY>

By default, malware scanning is enabled for all profiles except development profile. You can configure malware scanning by setting:

"attachments": {
    "scan": true
}

Visibility control for Attachments UI Facet generation

By setting the @attachments.disable_facet property to true, developers can hide the plugin from the UI achieving visibility. This feature is particularly useful in scenarios where the visibility of the plugin needs to be dynamically controlled based on certain conditions.

Example Usage

entity Incidents {
  // ...
  @attachments.disable_facet
  attachments: Composition of many Attachments;
}

In this example, the @attachments.disable_facet is set to true, which means the plugin will be hidden by default.

Multitenancy

The plugin supports multitenancy scenarios, allowing both shared and tenant-specific object store instances.

!Note Starting from version 2.1.0, separate mode for object store instances is the default setting for multitenancy. Currently, only the S3-standard plan of the object store offering is supported.

For multitenant applications, make sure to include @cap-js/attachments in the dependencies of both the application-level and mtx/sidecar package.json files.

Shared Object Store Instance

!Note Ensure the shared object store instance is bound to the mtx application module before deployment.

To configure a shared object store instance, modify both the package.json files as follows:

"cds": {
    "requires": {
        "attachments": {
            "objectStore": {
                "kind": "shared"
            }
        }
    }
}

To ensure tenant identification when using a shared object store instance, the plugin prefixes attachment URLs with the tenant ID.

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.