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.

  • BTW, to allow a differentiation between enclosing notes and attachments it would be helpful to have the attachment_flag available in the Studio. Therefore a little vardef extension in the notes module can be written, e.g. in a file .../custom/Extension/modules/Notes/Ext/Vardefs/AttachmentFlag.php, containing the following content:

    <?php 
     $dictionary["Note"]["fields"]["attachment_flag"]["studio"] = true;
    

    Harald Kuske
    Principal Solution Architect – Professional Services, EMEA
    hkuske@sugarcrm.com
    SugarCRM Deutschland GmbH

  • Hi Harald,

    is there an easy way, apart from extending the module api to filter notes flagged as attachment? 

  • By default the attachment_flag is not part of the list view or search fields but you can add it in studio to list view, record view and search field list.

    Harald Kuske
    Principal Solution Architect – Professional Services, EMEA
    hkuske@sugarcrm.com
    SugarCRM Deutschland GmbH

  • Is there a way to have the list view filter by default on that field? I did some testing and added the field to the default filters this gave some strange results. I have a totl of 60k notes of which are 3 or 4 attachments. All other notes don't have the field set (null value in the database) and therefore when I add that field to the default filters it gives a total random number or records since the search query fails to find those fields which have null. 

  • Houuuu, you had the big luck that the attachment_flag was not set to 0 during upgrade. The column defaults to 0 in the database definition, so all new records should be correct.

    Then you have different possibilities:

    1) I created a calculation in Sugar_logic which set the value of the column attachment_flag to "equal($attachement_flag,true)". That works fine as long as you do not have too much unset records and it is dangerous because when you make a type it can happen that you reset all notes to attachment lessness.

    2) You could run an sql statement when you are hosted on premise setting all the null values to 0
    update notes set attachment_flag = 0 where attachment_flag is null

    3) You could define a temporary custom field, let's name it no_attachment_c which is calculated and which contains the exact opposite of attachment_flag by setting it to "not( equal($attachement_flag,true))" in studio. Then you can filter but again you have to recalculate all the existing records, but this time with no risk to destroy the original information

    Harald Kuske
    Principal Solution Architect – Professional Services, EMEA
    hkuske@sugarcrm.com
    SugarCRM Deutschland GmbH