Feature dynamic SDM folder paths (Issue #244)

[Andreas-Meindl-msggroup]

Describe your changes

We changed the plugin to provide advanced folder management capabilities, allowing you to organize attachments in custom nested folder structures within the SDM repository. Instead of using the default entity-based folder structure, you can specify dynamic paths to organize attachments hierarchically based on your business logic.

Usage Examples

1. Basic Nested Folder Structure

Organize attachments by project and document type:

// Create attachment with custom path
await POST('/Incidents(ID=<incident-id>)/attachments', {
  filename: 'incident-report.pdf',
  sdmPath: 'incidents/2024/reports'
});

This creates the folder structure:

SDM Repository Root
└── incidents/
    └── 2024/
        └── reports/
            └── incident-report.pdf

2. Dynamic Path Based on Business Data

Generate paths dynamically based on entity properties:

// In a custom handler
srv.before('CREATE', 'Attachments', async (req) => {
  const incident = await SELECT.one.from(Incidents, req.data.up__ID);
  
  // Build path from incident properties
  const year = new Date(incident.createdAt).getFullYear();
  const priority = incident.priority || 'normal';
  
  req.data.sdmPath = `incidents/${year}/${priority}/${incident.customer.name}`;
});

Resulting structure:

incidents/
├── 2024/
│   ├── high/
│   │   └── CustomerA/
│   │       └── attachment.pdf
│   └── normal/
│       └── CustomerB/
│           └── attachment.pdf
└── 2025/
    └── high/
        └── CustomerC/
            └── attachment.pdf

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update (provided by Pull Request)

Checklist before requesting a review

• I have tested the functionality on my cloud environment.
• I have provided sufficient automated/ unit tests for the code.
• I have increased or maintained the test coverage.

Upload Screenshots/lists of the scenarios tested

• I have Uploaded Screenshots or added lists of the scenarios tested in description.
• getFolderIdByDynamicPath:
  • should return null on network error
  • should handle single folder path correctly
  • should handle nested folder paths correctly
  • should return null when folder does not exist
  • should return folderId when folder exists
• createNestedFolders
  • should create all folders when none exist
  • should throw error when folder creation fails and retry also fails
  • should handle race condition by retrying folder check on creation error
  • should use parent folder ID when creating nested folders
  • should filter out empty path segments
  • should handle single folder creation
  • should skip existing folders and only create missing ones
  • should create nested folders and return last folder ID