The com.sap.cds:cds-feature-attachments dependency is
a CAP Java plugin that provides out-of-the box attachments storage
and handling by using an aspect Attachments.
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.
The following version are the minimum versions for the usage of the plugin:
| Component | Minimum Version |
|---|---|
| CAP Java | 2.9.1 |
| UI5 | 1.121.0 |
At the moment the dependency is not available in the public maven repository. But it is planned to be available in the public maven repository.
Until then the dependency it only available SAP internally in the following SAP Artifactory: https://int.repositories.cloud.sap/ui/repos/tree/General/proxy-cap-java
If you have access to this repository and want to use the plugin you need to add this repository to the
maven settings.xml.
The usage of CAP Java plugins is described in
the CAP Java Documentation.
Following this documentation this plugin needs to be referenced in the pom.xml of a CAP Java project:
<dependency>
<groupId>com.sap.cds</groupId>
<artifactId>cds-feature-attachments</artifactId>
<version>${latest-version}</version>
</dependency>The latest version can be found in the changelog.
To be able to also use the cds models defined in this plugin the cds-maven-plugin needs to be used with the
resolve goal to make the cds models available in the project:
<plugin>
<groupId>com.sap.cds</groupId>
<artifactId>cds-maven-plugin</artifactId>
<version>${cds.services.version}</version>
<executions>
<execution>
<id>cds.resolve</id>
<goals>
<goal>resolve</goal>
</goals>
</execution>
</executions>
</plugin>If the cds models needs to be used in the db folder the cds-maven-plugin needs to be included also in the
db folder of the project.
This means the db folder needs to have a pom.xml with the cds-maven-plugin included and the cds-maven-plugin
needs to be run.
If the cds-maven-plugin is used correctly and executed the following lines should be visible in the build log:
[INFO] --- cds:2.8.1:resolve (cds.resolve) @ your-project-srv ---
[INFO] CdsResolveMojo: Copying models from com.sap.cds:cds-feature-attachments:<latest-version> (<project-folder>\target\classes)
After that the models can be used.
The cds models in include an aspect to add attachments to entities. It also includes annotations used by the FIORI UI to handle attachments.
To use the aspect the following code needs to be added to the entity definition:
using {sap.attachments.Attachments} from `com.sap.cds/cds-feature-attachments`;
entity Items : cuid {
...
attachments : Composition of many Attachments;
...
}The aspect Attachments shall be used directly for the composition.
It is important to use the correct from clause for the using statement.
Only if com.sap.cds/cds-feature-attachments is used and not concrete files of the feature are specified in the
from-statement also the annotations and other definitions are found and used.
In the model several fields are annotated with the @title annotation.
The texts of these fields needs to be included in the consumings project UI.
The following table gives an overview of the fields and the i18n codes:
| Field Name | i18n Code |
|---|---|
content |
attachment_content |
mimeType |
attachment_mimeType |
fileName |
attachment_fileName |
status |
attachment_status |
note |
attachment_note |
In addition to the field names also header information (@UI.HeaderInfo) are annotated:
| Header Info | i18n Code |
|---|---|
TypeName |
attachment |
TypeNamePlural |
attachments |
For the status of the attachment only the code value is stored at the moment. The status codes are:
UnscannedScanningCleanInfectedFailed
If a text for the status needs to be displayed on the UI the model needs to be enhanced with the texts. For this a new Statuses entity needs to be created like the following example:
entity Statuses @cds.autoexpose @readonly {
key code : StatusCode;
text : localized String(255);
}For this entity csv files can be included in the project structure with texts and translations, to show the translated texts on the UI.
With this a text can be added in example above like:
extend Attachments with {
statusText : Association to Statuses on statusText.code = $self.status;
}With this an annotation can be added to the attachments entity to have the status text displayed in the UI:
status @(
Common.Text: {
$value: ![statusText.text],
![@UI.TextArrangement]: #TextOnly
},
ValueList: {entity:'Statuses'},
sap.value.list: 'fixed-values'
);To enhance the UI with the attachments the following annotations are used for the UI.Facets annotations
in your app:
{
$Type : 'UI.ReferenceFacet',
ID : 'AttachmentsFacet',
Label : '{i18n>attachmentsAndLinks}',
Target : 'attachments/@UI.LineItem'
}A complete UI.Facets annotation could look like:
annotate service.Incidents with @(
UI.Facets : [
{
$Type : 'UI.CollectionFacet',
Label : '{i18n>Overview}',
ID : 'Overview',
Facets : [
{
$Type : 'UI.ReferenceFacet',
Label : '{i18n>GeneralInformation}',
ID : 'i18nGeneralInformation',
Target : '@UI.FieldGroup#i18nGeneralInformation',
},
{
$Type : 'UI.ReferenceFacet',
Label : '{i18n>Details}',
ID : 'i18nDetails',
Target : '@UI.FieldGroup#i18nDetails',
},],
},
{
$Type : 'UI.ReferenceFacet',
Label : 'Conversations',
ID : 'Conversations',
Target : 'conversations/@UI.LineItem#Conversations',
},
{
$Type : 'UI.ReferenceFacet',
ID : 'AttachmentsFacet',
Label : '{i18n>attachmentsAndLinks}',
Target : 'attachments/@UI.LineItem'
}
]
);In this plugin the persistent outbox is used to mark attachments as deleted. The enablement of the outbox is also included in the cds models of this plugin. In the capire documentation of the persistent outbox is it described how to overwrite the default outbox configuration.
If the default shall be used, nothing needs to be done.
This plugin checks for a binding to
the SAP Malware Scanning Service.
The concrete check if for a binding to a service with label malware-scanner.
The malware scanner is used in the default implementation of the technical service AttachmentService to scan
attachments.
If the default implementation of this service is overwritten, e.g. by using the plugin enhancement of the
SAP Document Management Service, then this overwriting plugin
is responsible for the malware scan and the plugin documentation needs to be checked for how the malware scan is done.
If the default implementation is used and the malware scanner is not available the attachments are marked as clean by setting the status of the attachment to:
Clean
Only attachments with the status Clean are accessible.
Attachments with all other status codes are not accessible.
If the malware scanner is available but during the request to the scanner an error occurs the status of the attachment is set to:
Failed
If attachments are uploaded but not scanned by a malware scanner (if a scanner is available) or are marked as infected the direct access of the attachment is not possible. In case users try to access the content of the attachment the following errors messages are displayed:
| Error Message | Error Message i18n Code |
|---|---|
| Attachment is not clean | not_clean |
| Attachment is not scanned, try again in a few minutes | not_scanned |
By adding the error message i18n code to the i18n.properties file the error message can be overwritten translated.
More information can be found in the capire documentation
for i18n.
The attachment service has an event RESTORE_ATTACHMENTS.
This event can be called with a timestamp to restore external stored attachments.
Documents which are marked as deleted can be restored.
The use case behind this feature is:
If backups of databases are restored the attachments stored in external storages also needs to be restored. To have a possibility to restore attachments which are marked as deleted a restore endpoint is available.
In the default implementation of the technical service AttachmentService this is not needed as the attachments are
stored directly in the database and are restored with the database.
If the default implementation is overwritten, e.g. by using the plugin enhancement of the SAP Document Management Service, then this overwriting plugin needs to handle the restore of attachments.
In such cases the restore endpoint can be used to restore attachments.
How long attachments are marked as deleted before they get deleted dependents on the configuration of the used storage.
There is no predefined endpoint for the restore action. To call the action of the service from outside the application a service could be defined like the following example:
service RestoreAttachments {
action restoreAttachments (restoreTimestamp: Timestamp);
}The action restoreAttachments could get in a timestamp from which the attachments need to be restored.
The action could be called with a POST request to the endpoint:
- OData v4:
/odata/v4/RestoreAttachments/restoreAttachments - OData v2:
/odata/v2/RestoreAttachments/restoreAttachments
With the body:
{
"restoreTimestamp": "2024-04-17T10:36:38.813491100Z"
}The action needs to be implemented and can call the attachment service as in the following example:
@ServiceName(RestoreAttachments_.CDS_NAME)
public class RestoreAttachmentsHandler implements EventHandler {
private final AttachmentService attachmentService;
public RestoreAttachmentsHandler(AttachmentService attachmentService) {
this.attachmentService = attachmentService;
}
@On(event = RestoreAttachmentsContext.CDS_NAME)
public void restoreAttachments(RestoreAttachmentsContext context) {
attachmentService.restoreAttachment(context.getRestoreTimestamp());
context.setCompleted();
}
}In the Spring Boot context the AttachmentService can be autowired in the handler.
To secure the endpoint security annotations can be used e.g. like the following example:
using {sap.attachments.Attachments} from `com.sap.cds/cds-feature-attachments`;
entity Items : cuid {
...
attachments : Composition of many Attachments;
...
}
annotate RestoreAttachments with @(requires: 'internal-user');Here the RestoreAttachments service is annotated with the requires annotation to secure the service.
Also, other annotations can be used to secure the service.
More information about the CAP Java security concept can be found in the CAP Java Documentation.