Adding an Existing Note to an Email as Attachment

Overview

There may be times when you want to reuse a file attached to one Note record as an attachment for an Email, similar to the ability in the Compose Email view to add an attachment using 'Sugar Document'.

Key Concepts

There are two key things to understand when implementing this functionality:

1. You can not relate an existing Note record to an Email record. This will throw an Exception in the API as intended. A note that is used as an attachment can only exist once and can not act as an attachment across multiple emails.
2. You can create a new Note record that uses an existing Note's attached file. Doing so essentially requires setting the upload_id field of the new Note record to the id of the existing Note you want to reuse the file from, and setting the file_source field of the new Note to 'Notes'. In addition to needing to set the upload_id, you must also set the filename and name field.

The following examples demonstrate how to do this in three different contexts: server-side (SugarBean/PHP), client-side (sidecar/Javascript), and purely through the API. But all three contexts follow the same essential steps:

1. Fetch the original Note record;
2. Create a new Note record, setting the necessary fields from the original Note record;
3. Link the new Note record to the Email record via the appropriate 'attachments' link.

PHP

This example would be done server-side using the SugarBean object, similar to how you might interact with the records in a custom Logic Hook or Scheduler job.

  $original_note_id = '4e226282-8158-11e8-a1b3-439fe19c087a';
$email_id = 'e3e058f4-7f11-11e8-ba11-fcdd97d61bbe';

// 1. Fetch Original Note:
$original_note = BeanFactory::retrieveBean('Notes', $original_note_id);

// 2.  Create a new note based on original note, setting upload_id, name, and filename:
$new_note = BeanFactory::newBean('Notes');
$new_note->upload_id = $original_note->getUploadId();
$new_note->file_source = 'Notes';
$new_note->filename = $original_note->filename;
$new_note->name = $original_note->filename;

// 3. Relate the new note to Email record using 'attachments' link:
$email = BeanFactory::retrieveBean('Emails', $email_id);
$email->load_relationship('attachments');
$email->attachments->add($email, $new_note);

Note that in most contexts, such as a Logic Hook or a custom endpoint, you will not need to call save() on either the $new_note or $email for $new_note to be related as an attachment to $email and for $new_note to save. The $new_note record will save as part of being linked to $email.

Javascript

The following example is totally standalone within Sidecar, demonstrating how to fetch the existing Note using app.data.createBean and bean.fetch(), create the new Note using app.data.createBean and setting the relevant fields, and then adding the new Note to the email records attachments_collection.

  var original_note_id = '4e226282-8158-11e8-a1b3-439fe19c087a';
var email_id = 'e3e058f4-7f11-11e8-ba11-fcdd97d61bbe';

// 1. Fetch Original Note:
var original_note = app.data.createBean('Notes');
original_note.set('id', original_note_id);
original_note.fetch();

// 2.  Create a new note based on original note, setting upload_id, name, and filename:

var new_note = app.data.createBean('Notes', {
	_link: 'attachments',
	upload_id: original_note.get('id'),
	file_source: 'Notes',
	filename: original_note.get('filename'),
	name: original_note.get('filename'),
	file_mime_type: original_note.get('file_mime_type'),
	file_size: original_note.get('file_size'),
	file_ext: original_note.get('file_ext'),
});

// 3.  Relate the new note to Email record using 'attachments_collection' link:

var email = app.data.createBean('Emails');
email.set('id', email_id);
email.fetch();

email.get('attachments_collection').add(new_note,{merge:true});
email.save();

Note: In the above example, the fields file_mime_type, file_size, and file_ext are also set. This is assuming a context where the customization is adding the attachments to the Compose Email view. Setting these fields makes the new attachments look correct to the user before saving the Email, but these fields are otherwise set automatically on save. If extending the actual compose view for emails, you also wouldn't fetch the email directly. This is added in this example purely for demonstration purposes.

REST API

The following section will outline how to related the attachment using the REST API using the /link/attachments/ endpoint for the Email record.

Fetch Original Note

To fetch the original note, send a GET request to rest/{REST VERSION}/Notes/{$original_note_id}. An example of the response is shown below :

  {
  "id": "4e226282-8158-11e8-a1b3-439fe19c087a",
  "name": "Note with Attachment",
  "date_entered": "2018-07-01T12:00:00-00:00",
  "description": "Send to special clients.",
  "file_mime_type": "application/pdf",
  "filename": "special_sales_doc.pdf",
  "_module": "Notes"
}

Create and Relate a Note

Create a JSON object based on the response (which we will treat as a JSON object named $original_note) like:

  {
	"upload_id": "$original_note.id",
	"file_source" : "Notes"
	"name" : "$original_note.filename",
	"filename" : "$original_note.filename",
}

Relate the Note to the Email record using the 'attachments' link. Next, send a POST request to rest/{REST VERSION}/Emails/{$email_id}/link/attachments/ with the JSON shown above as the request body.