Attachment Picker

Purpose of Attachment Picker :

The primary purpose of the Attachment Picker is to extend the default file attachment capability by allowing extensions to control how files are selected and uploaded. It enables integration with external storage systems, custom file processors, or internal validation logic before attaching files to a record. Unlike background widgets, this location is user-interactive and appears inside a controlled popup interface.

How It Works :

• The user clicks the 'Attach Files' option in a supported module.
• The user selects 'Attach from Extension'.
• A popup window is opened by the system.
• The extension registered under the attachment.picker location is rendered inside the popup body.
• The user selects or prepares files within the extension interface.
• When the user clicks Save, the ON_UPLOAD_ATTACHMENT event is triggered.
• The extension uploads the files using the provided SDK method.
• If the upload succeeds, files are attached to the record and the popup closes automatically.

Popup Behavior :

The Attachment Picker is displayed inside a system-controlled popup. The popup header, Save button, and Cancel button are managed by the platform. The extension only controls the content rendered inside the popup body. The Save action triggers a system event, and the extension must explicitly upload the selected files during this event.

Common Use Cases :

1. External Storage Integration

Extensions can allow users to select files from external systems instead of uploading from the local device.

Examples :

• Selecting files from a third-party cloud storage provider.
• Attaching documents stored in an external document management system.
• Fetching generated reports from an external service before attaching.

2. Custom File Validation

The Attachment Picker can validate files before they are attached to ensure compliance and security.

Examples:

• Restrict file types beyond default system validation.
• Prevent uploading files exceeding a custom size limit.
• Scan file metadata before allowing attachment.

3. File Transformation Before Upload

Files can be processed or modified before attaching them to the record.

Examples:

• Compressing images before upload.
• Generating a PDF dynamically and attaching it.
• Merging multiple files into a single document.

4. Automated File Generation

The extension can generate files dynamically based on record data and attach them automatically.

Examples:

• Generating invoices as PDF and attaching automatically.
• Creating compliance documents based on transaction data.
• Attaching system-generated audit reports.

Event Handling :

The Attachment Picker follows an event-driven model. When the user clicks the Save button inside the popup, the system triggers the ON_UPLOAD_ATTACHMENT event. The extension must handle this event and upload the selected files using the SDK method. If an error occurs, the extension can prevent the popup from closing by returning a prevent_save response.

When to Use Attachment Picker :

• You need custom file selection logic.
• Files must be fetched from external systems.
• Pre-upload validation or transformation is required.
• User interaction is necessary before attaching files.

When Not to Use Attachment Picker :

• File attachment does not require user interaction.
• Automation should occur without popup interaction.
• Logic needs to run silently in the background.

Summary

The Attachment Picker extends the standard file attachment mechanism by allowing extensions to provide controlled, customizable file upload experiences. It enables integration, validation, transformation, and automation while keeping the user in control through a structured popup interface.

• Provides interactive file selection.
• Supports custom validation and processing.
• Uses event-driven upload mechanism.
• Popup lifecycle is managed by the platform.

Events

Events

ON_UPLOAD_ATTACHMENT

This event is triggered when the user clicks the Save button in the attachment picker popup after selecting files to attach. Extensions must handle this event to upload the selected files using the SDK method. The event provides an opportunity to validate, process, or transform files before they are attached to the record.

Supported Locations :

attachment.picker

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
   App.instance.on('ON_UPLOAD_ATTACHMENT', async () => {
     try {
      const file = new File([
       new Blob(['Sample file content'])
      ], 'sample.txt', { type: 'text/plain' });

      await ZFAPPS.linkFiles({attachments: [file] });
     } catch (err) {
      return { prevent_save: true };
     }
   });
  })
}