Make sure you view the Caveats page

I want to go through a short description of why the plugin works the way it does for the different versions, but first, the tldr version :
  • If you have a new CRM installation that you plan on using this on
  • OR you have an existing CRM installation, but you don't care about migrating existing binaries, just externalizing the new ones
  • OR you have an existing CRM installation (on premise), you want to migrate existing binaries AND you have direct access to the database AND you're willing to run SQL scripts directly on the database
    • Use version 4.1 plugin (v4.1 Setup), and to migrate, the 4.1 migration tool with manual sql scripts documented here : v4.1 Migration
  • If you have an existing CRM installation, you want to migrate existing binaries and you DON'T have direct database access (i.e. CRM online) or aren't willing to run scripts directly against the database, you have the following options :
  1. Use version 4.1, but you will have the following issue :
    1. When migrating annotations, the filesize field will be set to 3. File sizes will show up correctly in CRM, except when doing a query against the filesize. This will produce odd results. This query will also be quite slow as it will call azure once per item returned.
  2. Use version 2 (v2 Setup) and (Migration Tool), which has the following quirks :
    1. You either need to give users that access notes/attachments rights to be able to read the binary storage options entity (not a good idea), or you need to run the plugin steps under an account that has read rights on the entity. Using a different user will mess with your audit logging, but sometimes it's easy to live with that or not audited.
    2. Searching on note file sizes won't work correctly. The correct file sizes will be shown, but the query won't return correct results.
    3. Searching by filename will be altered, because the filename is stored with a prefix, so StartsWith operator won't work correctly.
  3. Use version 3.0, for which there is no built release, but you can use the code. Has the following quirks:
    1. The version 2 issues are fixed. However, for this to work, you need another entity in CRM to store the filesize. Users need full read/create/write access to this entity. If you look at the code, it's called "bso_attachmentextension", but you can call it whatever.
    2. If you don't have the above entity, v3.0 will still work, but you'll have the filesize query issues as above.

So, onto the why

  • CRM stores activity attachments in an entity called "ActivityMimeAttachment", but in the database the data goes into the "Attachment" table (Body field). It stores Note attachments as "Annotations", with the IsDocument set to true if there is a file attachment on a note (DocumentBody field). Both are stored as base64 strings.
  • It's possible to intercept both of the required entities' workflow steps (Create/Read/Delete).
  • When you attach to the create pre event, you can modify the DocumentBody (on annotation) field and store the data externally without CRM updating any other fields automatically. However, if you attach to the post create event (or update said entity afterwards), CRM recalculates the IsDocument and FileSize fields, and sets this regardless of what you provide.

Problems :
  • If you set the document body to null :
    • When a query hits your plugin, there will be no documentbody/body field to populate. If you just add it, it means ALL queries will retrieve all the external data... Bad idea.
    • If you try the migration, CRM sets the filesize to 0 and IsDocument to false. So even if you used the pre create event, after migration, all annotations/attachments have incorrect values in those fields.
    • I resorted to using a tiny base 64 string of 4 length (3 bytes binary length) in the body field to overcome the null issues. This means however that the filesize is set to 3 if you do a post create/ update on said entities.
  • V2 addressed getting the correct filesizes back, but that's slow and only works for the actual returned results, not the query(s) itself.
  • V3.0 addressed all issues, but the complexity just didn't seem worth it to me (I really hate having basically a "system" entity show up in advanced find. To be clear, you can use this version and as far as my testing went, it fixed all known issues. I just haven't produced a package for it, but the v3.0 migration tool works with it as well.
  • V3.1 and above also addressed the issues of v2, but I cut out the complexity required for v3.0. However, this means that the v3.1 Migration tool only COPIES annotation data externally, it does not MOVE the annotation data when doing a CRM -> EXTERNAL migration (actually, the tool now includes an option to force move annotations). You have to run sql script afterwards to clear out the binary data out of your CRM database (if you're so inclined). It also means that the v3.1 ONLY WORKS SYNCHRONOUSLY for annotations async for email attachments, i've removed async Create support (for annotations) in v3.1.
    • The filesize will always be incorrect for attachments (because attachments seems to only work in post-operation mode), but there's nowhere in the UI that you can search on that which I'm aware of, so should be fine.

Last edited Jun 15, 2016 at 11:14 PM by dawidpotgieter, version 29