1. Overview of the Document Uploader Element

The Document Uploader element is a drag-and-drop-enabled UI element that allows users to upload files to the DMS. Files are transferred to the backend using the chunked upload method. This ensures a more secure and stable upload process by sending large files in chunks.

With this element, users can add files via drag-and-drop or by selecting a file. File type validation is performed before upload, and a magic byte analysis is applied for security purposes. This ensures that only permitted and secure files are uploaded to the system.

The Document Uploader element can be used in scenarios requiring document management systems, application forms, support requests, onboarding flows, and folder-based file uploads.

The Document Uploader element is supported only in web applications.

1.1. Common Use Cases

The Document Uploader element is commonly used in the following scenarios:

• It can be used to collect documents or files from users. For example, identification documents, contracts, application documents, or additional files can be uploaded to the system using this element.
• It is preferred in structures requiring file uploads to a specific folder. It is particularly suitable for Document Management systems where the uploaded file needs to be associated with a target folder.
• It can be used to collect additional documents in form processes. It can serve as a file upload field in screens such as applications, onboarding, or support requests.
• It can be used in admin panels or content operations screens to allow editor or administrator users to upload documents to the system.
• It can be used in scenarios where multiple files need to be uploaded in a controlled, sequential manner.
• It offers an effective solution in scenarios where large files need to be transferred to the backend in parts rather than all at once.

2. Key Features

The Document Uploader element offers the following key features for file upload processes:

• A drag-and-drop area is located at the top. Within a dashed box, there is an “Inbox” icon, a main text (label), and a tooltip (hint). Users can drag and drop files into this area or click to select a file.
• When files are selected, a file list appears at the bottom. Each row includes a file icon, an editable file name field, file size, and a delete button.
• At the top of the list, the total number of files and an “Upload” button are displayed.
• When the upload begins, a progress bar is displayed for each file.
• For successful uploads, a green progress bar and a success message are shown; for failed uploads, a red progress bar, an error message, and a retry option are displayed.
• For unsupported file types, a yellow warning notification (toast) is shown to the user.

2.1. Element Settings (Properties)

When you select the DocumentUploader element, you can configure the upload behavior and the content displayed to the user via the Properties panel on the right.

The key settings for this element are as follows:

folderId: Specifies the ID of the target folder where uploaded files will be saved. It can be bound to the selectedFolderId binding of the Directory element. When this field is defined, all uploaded documents are created under the relevant folder.

documentId: This ID determines whether the upload will occur on an existing document or as a new document.

• If uploadMode = “newVersion”, this field is required and specifies the ID of the document to be updated.
• If uploadMode = “draft”:
  
  • If documentId is provided, a draft version is added to the existing document
  • If not provided, a new document is created as a draft
• Not used in uploadMode = “newDocument” mode

uploadMode: Determines the upload behavior.

• newDocument → Creates a new document (published) in the selected folder
• newVersion → Uploads a new version of the existing document (documentId is required)
• draft → Saves the document as a draft

maxFileSizeMb: Specifies the maximum allowed size for a single file in MB. Files exceeding this limit will not be uploaded, and a warning will be displayed to the user.

maxFileCount: Determines the maximum number of files that can be added to the upload queue at the same time. If the specified limit is exceeded, excess files are rejected.

chunkSizeMb: Determines the size of the chunks (in MB) into which files are split when sent to the backend. The default value is 10 MB. Used to ensure more stable uploads for large files.

Label: The main text displayed to the user in the drag-and-drop area. It is used to clearly explain the purpose of this area to the user.

Hint: A supplementary text that provides additional information to the user. Details such as supported file types, maximum size, or intended use can be displayed here.

autoClearSeconds: Ensures that successful uploads are automatically removed from the list after the specified time (in seconds).

maxVisibleEntries: Determines the maximum number of rows to be displayed in the file list at the same time. Additional entries are displayed via scrolling.

Language: Determines the interface language of the upload component.

2.2. Event Actions That Can Be Added to the Element

The DocumentUploader element provides events that can trigger actions based on user interactions. These events can be used to control the upload process and define additional workflows.

onUploadFinish: Triggered when the upload process for all files in the queue is complete (regardless of whether it was successful or failed). It is typically used for post-upload data refresh operations. For example, the GetDocumentTree action can be called via this event to update the Document tree.

onFileSelect: Triggered when one or more valid files are added to the upload queue. It can be used to capture the moment the user selects a file and perform related checks or provide notifications.

onUploadStart: Triggered when the user clicks the “Upload” button to start the upload process. It can be used in scenarios such as pre-upload preparation tasks, logging, or displaying notifications to the user.

2.3. Drag & Drop Support

The DocumentUploader element is built on the Ant Design Dragger component and offers the following features:

Multiple file selection: The `multiple` attribute works as expected. The user can drag and drop or select multiple files at the same time.

Accept filter: Allowed file extensions are automatically transferred to the `accept` HTML attribute. This ensures the browser displays only supported file types as selectable.

Client-side validation: The following checks are performed for each file before upload:

• Is the file extension among the supported file types defined in the system?
• Does the file size exceed the `maxFileSizeMb` limit?
• Do the first 16 bytes of the file contain content that poses a security risk?
  
  • (e.g., EXE/MZ, ELF, Shebang checks)
• Does the total number of files exceed the maxFileCount limit?

User notification in case of error: Toast notifications are displayed to the user for rejected files. Different messages are shown depending on the error cause:

• format (unsupported file type)
• security (security risk)
• size (file size limit)
• count (file count limit)

The displayed notifications automatically close after approximately 3.2 seconds.

2.4 Chunked Upload Process

The DocumentUploader element uses the chunked upload mechanism to ensure large files can be uploaded securely and reliably.

New document upload (uploadMode: “newDocument”)

The upload process consists of the following steps:

1. Init (Initialization): POST /documentmanagement/chunks/init. The file name, MIME type, target folder, total number of chunks, and size information are sent. The server returns an uploadId in response to this request.

2. Chunk Submission: POST /documentmanagement/chunks/{uploadId}/{chunkIndex} The file is split into chunks according to the specified chunk size, and each chunk is sent sequentially in application/octet-stream format. The progress bar is updated after each chunk.

3. Finalize (Completion): POST /documentmanagement/chunks/{uploadId}/finalize

After all chunks are sent, the server combines them, creates the document, and returns the documentId.

4. Error Handling: If an error occurs at any step of the upload process:

The upload session is cleared via the DELETE /documentmanagement/chunks/{uploadId} call.

Version upload (uploadMode: “newVersion” / “draft”)

Chunked upload is not used in these modes. The upload process is performed directly in a single step via the following endpoint:

PUT /documentmanagement/{documentId}/file

The file is sent in FormData format and saved as a version or draft of the existing document.

2.5. Supported File Types

The DocumentUploader element supports the following file categories:

• Office Files: docx, doc, xlsx, xls, pptx, ppt, odt, ods, odp, csv, rtf
• PDF / E-books: pdf, epub, fb2, djvu, xps
• Image Files: jpg, jpeg, png, gif, bmp, webp, svg, tiff, tif, ico, psd
• 3D Model Files: glb, gltf, obj, stl, 3ds, ply, dae, fbx, 3mf, ifc, step, stp, dwg, dxf
• Code / Text Files: js, ts, jsx, tsx, css, scss, py, java, cs, go, rs, cpp, c, h, sh, yaml, sql, json, xml, html, md, txt, log
• Archive Files: zip, rar, 7z, tar, gz, bz2, xz
• Diagram Files: vsdx, vsd, vdx, vssx, vstx, drawio
• Email Files: eml, msg

2.6. Operation Info Tags

Visual info tags are displayed on each upload row based on the operation performed. These tags clearly indicate the upload type to the user:

• New Document: Create a new document (uploadMode: “newDocument”)
• New Version: Add a new version to an existing document (uploadMode: ‘newVersion’)
• Draft: Upload the document as a draft (uploadMode: “draft”)

2.7. Clear Completed

After the upload is complete, a “Clear completed” button appears for successful uploads.

When this button is clicked, all successfully uploaded files are removed from the list.

If the autoClearSeconds property is defined, successful uploads are automatically cleared from the list after the specified time.

3. Document Uploader Element Use Case

Scenario: The user selects the “Contracts” folder in the left panel and uploads a new PDF document to this folder.

Flow

1. Folder Selection: When the user selects a folder via Directory:

Directory.onFolderSelect

1. SetValueOf(DocumentUploader.folderId, Directory.selectedFolderId)
2. → The selected folder is set as the upload destination

2. File Selection: The user drags and drops the file or selects it manually:

DocumentUploader.onFileSelect

→ Selected files are added to the upload queue

→ The user can edit the file name if necessary

3. Upload Start: When the user clicks the “Upload” button:

DocumentUploader.onUploadStart

→ The upload process begins

→ A progress bar is displayed for each file

4. Upload Completion: When all files have finished uploading:

DocumentUploader.onUploadFinish

1. GetDocumentTree → dsDocumentTree

→ The current document tree is retrieved from the backend

2. SetValueOf(Directory.options, dsDocumentTree)

→ The Directory is re-rendered and the new documents appear

3. ShowNotification(“Upload complete!”)

→ The result is communicated to the user

4. Best Practices

• Make sure to correctly map the folderId field. If it is incorrect or left blank, files will not be uploaded to the expected folder.
• Select the uploadMode setting appropriate for your scenario. Behaviors for creating new documents, adding versions, or uploading drafts differ.
• Set the `maxFileSizeMb` and `maxFileCount` values according to system capacity. Very high values may cause performance issues.
• Optimize the `chunkSizeMb` value for large file uploads. Smaller chunks provide more stable uploads but increase the number of requests.
• Fill in the `label` and `hint` fields clearly and concisely to provide proper guidance to the user.
• Manage post-upload data update operations via the onUploadFinish event. For example, refresh the directory tree using this event.

5. Limitations

• Unsupported file types cannot be uploaded. Files that fail file extension and content (magic byte) checks are rejected by the system.
• If the file size exceeds the `maxFileSizeMb` limit, the upload will not be performed.
• If the total number of files exceeds the `maxFileCount` limit, excess files will not be queued.
• Chunked upload is only used in the new document upload scenario (`uploadMode: “newDocument”`). Version and draft uploads are performed in a single operation.
• Errors occurring during the upload process are handled on a per-line basis. Failed files must be retried manually.
• The drag & drop area and the Upload button are inactive during design time.
• MIME type detection may not be accurate. It is determined based on information from the browser, the extension mapping, and the fallback mechanism.