====== Attachment manager ======

{{tag> attachment}}

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 [[..:..:application_configuration:dev:backend#attachment_storage| 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 [[..:..:application_configuration:dev:backend#attachment_storage| configured]]. Default storage path is under **user home directory** (''System.getProperty("user.home")/idm_data'').

<note important>**Configure [[..:..:application_configuration:dev:backend#attachment_storage| 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.</note>

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 [[..:..:application_configuration:dev:backend#attachment_storage|time to live configuration]]).

Path to temporary files on file system has to be [[..:..:application_configuration:dev:backend#attachment_storage|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 [[..:..:application_configuration:dev:backend#attachment_storage|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)