Notes with single and multiple Attachments since version 10.3

In Sugar versions lower than 10.3 each note could contain only one single attachment which is described in the note record and which is uploaded to the upload directory ($sugar_config[‘upload_dir’]), the file name is the same as the id of the note record itself.

With version 10.3 multiple attachments were introduced which allow more than one attachment per note. All attachments are created as single notes with their own id, an attachment_flag set to true and a note_parent_id referencing the parent note.

Data migration from lower versions to 10.3 is not necessary because the one-to-one assignment is still valid. Notes can contain a direct attachment upload and additional referencing multiple attachments. 

Note in version <10.3 with and without attachment:

The attachment is defined by the file-fields of the note record.

With version 10.3 it is possible to define the attachment directly in the note record (legacy attachments) but also in a separate note record which references the enclosing note. To find that enclosing note a new field note_parent_id was introduced which contains the id of the enclosing note.

In the following image we have a note with a legacy attachment in the left column and a note with a new multiple attachment in the two right columns:

The note with legacy attachment contains all attachment information in the note record, the attachment_flag (new with 10.3) is set to true.

The note with one or more multiple attachments contains no data of the attachments, each attachment has its own note record with its own id and a note_parent_id referencing the enclosing note and the attachment_flag set  to true. The enclosing note has attachment_flag set to false.

The last example shows an enclosing note with legacy attachment and two additional multiple attachments:

REST upload

When uploading notes you must know how to change your REST calls to make use of the new feature.

Before version 10.3 you could upload only one file per note so you used the following REST calls to create a note with attachment:

1. Create note
   POST .../Notes
   with JSON arguments
   name,
   file_size,
   file_ext and
   filename
   :id: of the note is returned in the response.
   
   
2. If returned id is not null:
   Upload file
   POST .../Notes/:id:/file/filename
   with JSON arguments
   format,
   delete_if_fails.
   oauth_token and
   filename

With version 10.3 the upload first creates the enclosing note and then all the attachment notes can be created like this:

1. Create enclosing note
   POST .../Notes
   with JSON arguments
   name,
   file_size,
   file_ext and
   filename
   :id: of the note is returned in the response.
   
   
2. If  returned :id: is not null:
   Create attachment note
   with JSON arguments 
   name = filename,
   erased_fields = true,
   note_parent_id = :id:,
   attachment_flag = true
   :id: of the created attachment note is returned in the response, referenced in the following as :att-id:
   
   
3. If returned :att-id: is not null:
   Upload file
   POST .../Notes/:att-id:/file/filename
   with JSON arguments
   format,
   delete_if_fails.
   oauth_token and
   filename
   
   
4. Repeat step 2. and 3. for each additional attachment.

Deletion of attachments

When you delete a note with a legacy attachment, the attachment file is deleted from the upload directory.

When you delete a note with multiple attachments, the attachment files - which are handled as separate attachment notes - are not deleted, the note records remain in the system and the attachment files remain in the upload directory too.