14.0:documentation:modules_rpt:dev:attachment_manager

Attachment manager

Attachments (~binary files) can be attached to an entity, which implements AttachableEntity interface. This entity is called attachment owner. Any owner can have more attachments. When owner is deleted, then all his attachments should be deleted too - override owner service delete method properly.

Attachments metadata are stored in database:

  • ownerType - AttachableEntity class - canonical name (e.g. eu.bcvsolutions.idm.rpt.entity.RptReport)
  • ownerId - AttachableEntity identifier (uuid)
  • contentId - binary file identifier (used as file name for DefaultAttachmentManager or "external" id into third party DMS)
  • contentPath - path to content (e.g. path on filesystem or url)
  • name - attachment name (e.g. notes.txt)
  • description - [optional] attachment description (e.g. My notes)
  • mimetype - content type (e.g. text/plain)
  • encoding - content encoding, its used mainly for text/plain contents (e.g. UTF-8).
  • filesize - content size in bytes
  • versionNumber - version number - int (e.g. 1, 2, 3, 4)
  • versionLabel - version label - string (e.g. 1.0, 2.0 , 2.1 , 3.0)
  • parent - [optional] the first attachment version identifier or null ⇒ is the first version
  • nextVersion - [optional] the next attachment version identifier or null ⇒ is the last version
  • attachmentType - [optional] - attachment type - can be used in search (e.g. draft, invoice)
  • ownerState - [optional] - sometimes is useful to attach file in some owner state, e.g. when owner has to be approved by workflow - can be used in search (e.g. approved, realized, rejected)

AttachmentManager features:

  • save attachment - when attachment is saved, then metadata are saved in database and binary file is stored in filesystem (by default).
  • save attachment version - attachments are versioned. Only major versions are supported now (e.g. 1.0, 2.0, 3.0). Attachment can be versioned automatically by attachment name (see saveAttachmentVersion method). When attachments are found, then last attachment version is returned only. Attachment versions can be found by attachment identifier separately.
  • update attachment metadata - e.g. binary data is unchanged, but new attachment description was added ⇒ creating new attachment version is not needed.
  • find attachments by owner, by identifier, by filter (comming soon)
  • find attachment versions by attachment identifier
  • delete attachments by owner, by identifier
  • create and purge temporary files - attachment manager is responsible for maintaining temporary files too. Old temporary files created by this managers are purged automatically (see temporary file time to live configuration).

Attachment binary data are stored on filesystem by default implementation (DefaultAttachmentManager). Different AttachmentManager can be added to store binary data in other document management system (DMS).

Default implementation

DefaultAttachmentManager stores binary files on file system. Path to storage on file system has to be configured. Default storage path is under user home directory (System.getProperty("user.home")/idm_data).

Configure storage path, where binary files will be saved. Otherwise will be storage created automatically under user home directory by default (System.getProperty("user.home")/idm_data) - it's not recommended to use this location in production. Warning about default storage location usage is written into logs, when attachment is saved.

When binary file is saved, then uuid content identifier (contentId) is generated and used as file name on filesystem with .bin extension. Content path in storage is prepared from actual date with pattern yyyy/MM/dd/uuid.bin. So content will be saved on path e.g. <storagePath>/2017/12/01/e963dd20-0a10-4052-8355-1425d021299a.bin.

Temporary files and attachments

Attachment manager is responsible for maintaining temporary files and temporary attachments. Temporary files are used e.g. by report renderers, when output data are created and downloaded. Temporary attachments are used for uploading new files into CzechIdM - e.g. for extended attributes with persistent type ATTACHMENT. Attachment is uploaded as temporary and when original form is submitted (owner's form), then the temporary attachment is moved under currently persisted owner (~renamed). When owner is deleted, all attachments are deleted too, but when owner's form is not submitted, then attachments remains marked as temporary.
Old temporary files and temporary attachments created by this manager are purged automatically (see temporary file time to live configuration).

Path to temporary files on file system has to be configured too (same as above). Default temp path is under storage path configured above (getStoragePath()/temp). When storage path above is configured, then this configuration can be leaved empty - folder /temp will be created automatically in storage path.

Configuration

All configuration properties are described in backend congifuration.

Future development

  • Add filter - find attachment by name, description, type … etc.
  • Attachment frontend agenda
  • Support authorization policies
  • Store binary data in DMS (e.g. Alfresco ECM or other DMS using CMIS), for fulltext search in binary data, replications, better cluster support, etc.
  • Save attachment templates e.g. by owner type only (ownerId is required now)