Attachment Field Configuration

The following documentation is for SuiteCRM Version 8.9.0+

Intro

Attachment fields allow you to associate uploaded files (such as documents or images) with your entities. These fields are managed by the media uploader system and support various storage backends.

Attachments Field Detail

How Attachment Fields Work

When a field is configured as type attachment, it enables file upload and management for that field. The system uses the configured storage backend to store and retrieve files, and links the uploaded file metadata to the entity record.

To use an attachment field, you must specify the storage_type in the field’s metadata configuration. This tells the system which storage backend to use for the uploaded files.

To understand how the media uploader and storage system works, please refer to the File Storage Configuration Reference.

It is also important to know the lifecycle of media objects to understand how files are managed in the system.

By default, the Attachment field type uses the private_documents storage type, as defined in the field metadata.

Configuration Example

To define an attachment field in your vardefs:

Minimal configuration:

'attachments' => [
    'name' => 'attachments',
    'vname' => 'LBL_ATTACHMENTS',
    'type' => 'attachment',
    'source' => 'non-db',
    'reportable' => false,
    'importable' => false,
    'metadata' => [
        'storage_type' => 'private-documents', // Required!
    ],
],

Full configuration with attachment specific options:

'attachments' => [
    'name' => 'attachments',
    'vname' => 'LBL_ATTACHMENTS',
    'type' => 'attachment',
    'source' => 'non-db',
    'reportable' => false,
    'importable' => false,
    'metadata' => [
        'storage_type' => 'private-documents', // Required!
        'upload_maxsize' => 10000000, // Optional, defaults to global config
        'breakpoint' => 1, // Optional
        'maxPerRow' => 3, // Optional
        'popoverMaxTextLength' => '200px', // Optional
        'popoverMinWidth' => '315px', // Optional
        'maxTextWidth' => '150px', // Optional
        'minWidth' => '185px', // Optional
    ],
],

Configuration Options

Option Description Required Default Value

Option	Description	Required	Default Value
`type`	Must be set to `attachment`	Yes	N/A
`storage_type`	The storage backend to use for this field. Must match a configured storage (e.g., `private-documents`, `public-images`). See the File Storage Configuration Reference.	Yes	`private-documents`
`upload_maxsize`	Maximum allowed file size in bytes.	No	Value from global configuration (`upload_maxsize`)
`breakpoint`	Number of attachments before a "Show More" link is displayed in the UI.	No	1
`maxPerRow`	Maximum number of attachments to display per row in the UI.	No	Dynamically calculated based on available space
`popoverMaxTextLength`	Maximum file name length in the popover before truncation.	No	200px
`popoverMinWidth`	Minimum width of each attachment inside the popover.	No	315px
`maxTextWidth`	Maximum file name length before truncation.	No	150px
`minWidth`	Minimum width of each attachment.	No	185px

type

Must be set to attachment

Yes

N/A

storage_type

The storage backend to use for this field. Must match a configured storage (e.g., private-documents, public-images). See the File Storage Configuration Reference.

Yes

private-documents

upload_maxsize

Maximum allowed file size in bytes.

Value from global configuration (upload_maxsize)

breakpoint

Number of attachments before a "Show More" link is displayed in the UI.

maxPerRow

Maximum number of attachments to display per row in the UI.

Dynamically calculated based on available space

popoverMaxTextLength

Maximum file name length in the popover before truncation.

200px

popoverMinWidth

Minimum width of each attachment inside the popover.

315px

maxTextWidth

Maximum file name length before truncation.

150px

minWidth

Minimum width of each attachment.

185px

Declaring Storage Types

The storage_type must correspond to a storage defined in your media configuration (see File Storage Configuration Reference). Example storage types include:

private-documents
archived-documents
private-images
public-images
public-documents

If you do not declare a valid storage_type, file uploads will not work for this field.