Attachment ID

Hi sassafrass - good question. The short answer is that we do not currently recommend creating new media entities directly. Instead, create a Brandfolder media type, and then hook it up to a context where the Media Library or Entity Browser is used for selecting media items. That will give you a Brandfolder image browser interface and then automatically create media entities as needed.

More info:
There is a one-to-one relationship between each Brandfolder-sourced media entity and a Brandfolder Attachment (Attachments can be thought of like individual files attached to Assets). That field (field_brandfolder_attachment_id) is the source field for the media type, and stores the ID of the Brandfolder attachment associated with the Drupal entity. (There should only ever be one Drupal media entity of a given type with a given attachment ID). The field is not really intended to be user-facing at all, but Drupal will show it on the standard "add media" form, as you can see. On a related note, the "Brandfolder Image" field is meant to be read-only and not used for uploading images in Drupal. If you copy and paste a unique attachment ID from Brandfolder into that field and save the form (leaving the Brandfolder Image field empty), it will work, but it lacks safeguards. The better approach right now is to enable your Brandfolder Image-based media type in a context where Media Library or Entity Browser is used to select media entities. The Brandfolder browser in those contexts will let you search for any allowed Brandfolder asset and select an attachment. It will create new media entities as needed.

Relevant action items:

1. Update documentation to discourage use of the Content > Media > Add Media workflow
2. Add documentation for Entity Browser support
3. Prevent new BF media entities from being created with duplicate attachment IDs
4. Prevent the use of the Brandfolder Image field for uploading images
5. Improve the Brandfolder browser interface
6. Integrate the Brandfolder browser with the Add Media form and start supporting that as a valid workflow
7. Provide a mechanism for uploading new files within Drupal and creating Brandfolder assets/attachments according to various rules

Thanks for such a thoughtful and thorough explanation!!