Merge branch 'develop' into changeLogSupport

Author: yashmeet29

.github/workflows/internalArticatory.yml

@@ -7,6 +7,10 @@ env:
 
 on:
   workflow_dispatch:
+    inputs:
+      deploy_branch:
+          description: 'Specify the branch foe which snapshot required'
+          required: true
 jobs:
   build-and-deploy-artifactory:
     runs-on: ubuntu-latest
@@ -15,6 +19,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.deploy_branch }}
 
       - name: Set up Java ${{ env.JAVA_VERSION }}
         uses: actions/setup-java@v4

README.md

@@ -20,6 +20,7 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei
 - Copy attachments: Provides the capability to copy attachments from one entity to another entity.
 - Link as attachments: Provides the capability to support link or URL as attachments.
 - Edit Link-type attachments: Provides the capability to update URL of link-type attachments.
+- Move attachments: Provides the capability to move attachments from one entity to another entity.
 - Localization of error messages and UI fields: Provides the capability to have the UI fields and error messages translated to the local language of the leading application.
 ## Table of Contents
 
@@ -33,6 +34,7 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei
 - [Support for Multiple attachment facets](#support-for-multiple-attachment-facets)
 - [Support for Technical user](#support-for-technical-user)
 - [Support for Copy attachments](#support-for-copy-attachments)
+- [Support for Move attachments](#support-for-move-attachments)
 - [Support for Link type attachments](#support-for-link-type-attachments)
 - [Support for Edit of Link type attachments](#support-for-edit-of-link-type-attachments)
 - [Support for Localization](#support-for-localization)
@@ -568,6 +570,143 @@ This plugin provides capability to copy attachments from one entity to another.
    }
    ```
 
+## Support for move attachments
+
+This plugin provides capability to move attachments from one entity to another entity. This capability will move attachments metadata on CAP as well as actual content on the SAP Document Management service repository. The move operation is performed in parallel for optimal performance and includes comprehensive error handling and rollback mechanisms.
+
+### Key Features
+
+- **Parallel Processing**: Move operations are executed in parallel using a thread pool for improved performance.
+- **Custom Properties Support**: Preserves and validates custom properties during the move.
+- **Automatic Rollback**: If database updates fail after a successful SDM move, the operation is automatically rolled back.
+- **Comprehensive Error Handling**: Returns detailed failure information for each attachment that fails to move.
+- **Folder Management**: Automatically creates target folders if they don't exist.
+
+### Usage Methods
+
+1. **A helper method to move attachments from one entity to another**
+   
+   The `AttachmentService` instance can be used to call `moveAttachments` method. This method expects an object of `MoveAttachmentInput` which requires the source folder ID, target entity's ID (`up__Id`), the `attachments facet name` and the `list of objectIds` corresponding to attachments that are to be moved.
+
+   Example usage:
+   ```java
+      String sourceFolderId = "source-folder-id";
+      String up__ID = "123";
+      List<String> objectIds = ["abc", "xyz"];
+      String facet = "AdminService.Books.attachments"
+      boolean isSystemUser = false;
+      
+      var moveEventInput = new MoveAttachmentInput(
+         sourceFolderId,
+         up__ID,
+         facet,
+         objectIds
+      );
+      
+      List<Map<String, String>> failedAttachments = 
+         attachmentService.moveAttachments(moveEventInput, isSystemUser);
+      
+      // Check for failures
+      if (!failedAttachments.isEmpty()) {
+         for (Map<String, String> failure : failedAttachments) {
+            String objectId = failure.get("objectId");
+            String reason = failure.get("failureReason");
+            // Handle failure
+         }
+      }
+   ```
+
+2. **OData API to move attachments from one entity to another**
+   
+   You can also use an OData API call to trigger the move operation.
+   `AttachmentsService` endpoint URL can be used with suffix `/<Service_name>.moveAttachments`. This request expects the following request body:
+   ```json
+   {
+      "sourceFolderId": "<source-folder-id>",
+      "up__ID": "<target-up-id>",
+      "facet": "<Service_Name>.<Entity_Name>.attachments",
+      "objectIds": ["abc", "xyz"]
+   }
+   ```
+
+   Example usage:
+   ```
+   HTTP Method: POST
+   Request URL:
+   <app_url>/odata/v4/<Service_Name>/<Entity_Name>(ID=<up__ID>,IsActiveEntity=false)/attachments/<Service_name>.moveAttachments
+   Request Body:
+   {
+      "sourceFolderId": "<source-folder-id>",
+      "up__ID": "<target-up-id>",
+      "facet": "AdminService.Books.attachments",
+      "objectIds": ["abc", "xyz"]
+   }
+   ```
+   
+   Note: The `facet` parameter should be the fully qualified name of the target attachment composition (e.g., `AdminService.Books.attachments`).
+
+### Optional Parameters
+
+When moving attachments, you can provide optional source facet information for proper cleanup:
+
+```java
+var moveEventInput = new MoveAttachmentInput(
+   sourceFolderId,
+   up__ID,
+   facet,
+   objectIds,
+   sourceFacet    // Optional: Full facet path, e.g., "AdminService.Authors.attachments"
+);
+```
+
+If `sourceFacet` is provided, the source entity metadata will be properly cleaned up after the move. If omitted, attachments are moved but source metadata cleanup is skipped.
+
+For OData API calls, you can include the optional `sourceFacet` parameter in the request body:
+```json
+{
+   "sourceFolderId": "<source-folder-id>",
+   "up__ID": "<target-up-id>",
+   "facet": "AdminService.Books.attachments",
+   "objectIds": ["abc", "xyz"],
+   "sourceFacet": "AdminService.Authors.attachments"
+}
+```
+
+### Response Format
+
+The move operation returns a list of failed attachments with detailed failure reasons:
+
+```json
+[
+   {
+      "objectId": "abc",
+      "failureReason": "Attachment abc already exists in Target entity"
+   },
+   {
+      "objectId": "xyz",
+      "failureReason": "Invalid custom properties: customProp1, customProp2. These properties are not supported in the target entity."
+   }
+]
+```
+
+### Common Failure Scenarios
+
+- **MaxCount Exceeded**: Target entity has reached its maximum allowed attachments.
+- **Invalid Custom Properties**: Attachment has custom properties not supported by the target entity.
+- **Permission Denied**: User lacks authorization to move the attachment.
+- **Duplicate File**: File with the same name already exists in the target folder.
+- **Database Update Failed**: Move succeeded in SDM but database update failed (automatic rollback occurs).
+- **Source Not Found**: Source attachment doesn't exist in SDM.
+
+### Best Practices
+
+1. **Always check the returned list of failed attachments** to inform users about partial failures.
+2. **Validate maxCount constraints** before initiating large move operations.
+3. **Ensure custom properties compatibility** between source and target entities.
+5. **Handle rollback scenarios gracefully** - rolled back attachments remain in the source folder.
+
+> **CRITICAL**: To preserve custom properties attached with attachments on UI, ensure these properties are defined in the target entity. If custom properties are not present in the target entity definition, they will be lost after the move and will not be visible on the UI.
+
 ## 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.

sdm/pom.xml

@@ -565,6 +565,9 @@
                         <exclude>
                             com/sap/cds/sdm/service/handler/AttachmentCopyEventContext.class
                         </exclude>
+                        <exclude>
+                            com/sap/cds/sdm/service/handler/AttachmentMoveEventContext.class
+                        </exclude>
                     </excludes>
                 </configuration>
                 <executions>

sdm/src/main/java/com/sap/cds/sdm/constants/SDMConstants.java

@@ -99,6 +99,20 @@ private SDMConstants() {
   public static final String ANNOTATION_IS_MEDIA_DATA = "_is_media_data";
   public static final String DRAFT_READONLY_CONTEXT = "DRAFT_READONLY_CONTEXT";
   public static final String FAILED_TO_COPY_ATTACHMENT = "Failed to copy attachment";
+
+  // Error messages for move operations
+  public static final String SDM_MOVE_OPERATION_FAILED = "SDM move operation failed";
+  public static final String VALIDATION_FAILED_PREFIX = "Validation failed: ";
+  public static final String VALIDATION_FAILED_DEFAULT_MESSAGE =
+      "Validation failed: Unable to process attachment properties or metadata";
+  public static final String INVALID_SECONDARY_PROPERTIES_PREFIX =
+      "Invalid secondary properties detected: ";
+  public static final String INVALID_SECONDARY_PROPERTIES_SUFFIX =
+      ". Attachment rolled back to source.";
+  public static final String FAILED_TO_MOVE_ATTACHMENT = "Failed to move attachment";
+  public static final String FAILED_TO_MOVE_ATTACHMENT_MSG = "SDM.Move.failedToMoveAttachmentError";
+  public static final String MOVE_OPERATION_PARTIAL_FAILURE =
+      "Move operation completed with some failures";
   public static final String FAILED_TO_FETCH_UP_ID = "Failed to fetch up_id";
   public static final String FAILED_TO_FETCH_FACET =
       "Invalid facet format, unable to extract required information.";

sdm/src/main/java/com/sap/cds/sdm/model/AttachmentMoveContext.java

@@ -0,0 +1,79 @@
+package com.sap.cds.sdm.model;
+
+import com.sap.cds.reflect.CdsEntity;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/** Helper class to hold attachment move context information. */
+public class AttachmentMoveContext {
+  private final String objectId;
+  private final MoveAttachmentsRequest request;
+  private final List<String> validSecondaryProperties;
+  private final Map<String, String> entityAnnotations;
+  private final CdsEntity targetEntity;
+  private final AttachmentProcessingResults processingResults;
+  private final List<Map<String, String>> failedAttachments;
+  private List<String> invalidProperties; // Mutable field to track validation failures
+
+  public AttachmentMoveContext(
+      String objectId,
+      MoveAttachmentsRequest request,
+      List<String> validSecondaryProperties,
+      Map<String, String> entityAnnotations,
+      CdsEntity targetEntity,
+      AttachmentProcessingResults processingResults,
+      List<Map<String, String>> failedAttachments) {
+    this.objectId = objectId;
+    this.request = request;
+    this.validSecondaryProperties = validSecondaryProperties;
+    this.entityAnnotations = entityAnnotations;
+    this.targetEntity = targetEntity;
+    this.processingResults = processingResults;
+    this.failedAttachments = failedAttachments;
+  }
+
+  public String getObjectId() {
+    return objectId;
+  }
+
+  public MoveAttachmentsRequest getRequest() {
+    return request;
+  }
+
+  public List<String> getValidSecondaryProperties() {
+    return validSecondaryProperties;
+  }
+
+  public Map<String, String> getEntityAnnotations() {
+    return entityAnnotations;
+  }
+
+  public CdsEntity getTargetEntity() {
+    return targetEntity;
+  }
+
+  public AttachmentProcessingResults getProcessingResults() {
+    return processingResults;
+  }
+
+  public List<Map<String, String>> getFailedAttachments() {
+    return Collections.unmodifiableList(failedAttachments);
+  }
+
+  public List<String> getInvalidProperties() {
+    return invalidProperties;
+  }
+
+  public void setInvalidProperties(List<String> invalidProperties) {
+    this.invalidProperties = invalidProperties;
+  }
+
+  /**
+   * Internal method for adding failed attachments during processing. For internal use only - do not
+   * expose to external callers.
+   */
+  public void addFailedAttachment(Map<String, String> failure) {
+    failedAttachments.add(failure);
+  }
+}

sdm/src/main/java/com/sap/cds/sdm/model/AttachmentProcessingResults.java

@@ -0,0 +1,31 @@
+package com.sap.cds.sdm.model;
+
+import java.util.List;
+
+/** Helper class to hold attachment processing results. */
+public class AttachmentProcessingResults {
+  private final List<String> successfulObjectIds;
+  private final List<List<String>> movedAttachmentsMetadata;
+  private final List<CmisDocument> populatedDocuments;
+
+  public AttachmentProcessingResults(
+      List<String> successfulObjectIds,
+      List<List<String>> movedAttachmentsMetadata,
+      List<CmisDocument> populatedDocuments) {
+    this.successfulObjectIds = successfulObjectIds;
+    this.movedAttachmentsMetadata = movedAttachmentsMetadata;
+    this.populatedDocuments = populatedDocuments;
+  }
+
+  public List<String> getSuccessfulObjectIds() {
+    return successfulObjectIds;
+  }
+
+  public List<List<String>> getMovedAttachmentsMetadata() {
+    return movedAttachmentsMetadata;
+  }
+
+  public List<CmisDocument> getPopulatedDocuments() {
+    return populatedDocuments;
+  }
+}

sdm/src/main/java/com/sap/cds/sdm/model/CmisDocument.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import java.io.InputStream;
+import java.util.Map;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -19,6 +20,7 @@ public class CmisDocument {
   private InputStream content;
   private String parentId;
   private String folderId;
+  private String sourceFolderId;
   private String repositoryId;
   private String status;
   private String mimeType;
@@ -28,4 +30,5 @@ public class CmisDocument {
   private String contentId;
   private String type;
   private String description;
+  private Map<String, Object> secondaryProperties;
 }

sdm/src/main/java/com/sap/cds/sdm/model/CopyAttachmentsResult.java

@@ -0,0 +1,24 @@
+package com.sap.cds.sdm.model;
+
+import java.util.List;
+import java.util.Map;
+
+/** Result class for copyAttachmentsToSDM method. */
+public class CopyAttachmentsResult {
+  private final List<Map<String, String>> attachmentsMetadata;
+  private final List<CmisDocument> populatedDocuments;
+
+  public CopyAttachmentsResult(
+      List<Map<String, String>> attachmentsMetadata, List<CmisDocument> populatedDocuments) {
+    this.attachmentsMetadata = attachmentsMetadata;
+    this.populatedDocuments = populatedDocuments;
+  }
+
+  public List<Map<String, String>> getAttachmentsMetadata() {
+    return attachmentsMetadata;
+  }
+
+  public List<CmisDocument> getPopulatedDocuments() {
+    return populatedDocuments;
+  }
+}