Today’s post covers the process of enabling Azure Attachment Management onto a Dynamics 365 for Customer Engagement environment. We’ll start with how to purchase/download it from the Microsoft Appsource website and then move into how to enable it to store attachments onto Azure and how to make the Attachment Management accessible for end-users on the entity forms. Let’s get started…
1. DOWNLOAD SOLUTION
As a system administrator, go to https://appsource.microsoft.com and search for “Attachment Management” by Microsoft Labs and click the correct option from the dropdown list. This will redirect to the download page. Ensure it is a solution created by Microsoft Labs, as this is the one that is required. Below is what should be displayed on the screen.
Note: Open the Microsoft Appsource website on the browser where the system admin is signed into Dynamics 365, as this will pick up all the CE instances within that organisation. (See screenshot below for more details.)
Now, select “Get it now” and a dialog permission box will pop up to ask the system admin to agree to provide basic information regarding the user’s account and agree to Microsoft’s Terms and Conditions. The page will then redirect to the installation page where the admin can select which instance they would like to add it to. Navigate to the dropdown field named “Organization to add the application to:” and select the Dynamics 365 CE instance this should go into.
Note: an admin can install this solution only into an instance to which they have system admin privileges.
Once the correct instance is selected, read and agree to the privacy and legal terms. After agreeing, the admin will be redirected to the Dynamics 365 Administration Center to provide a view of the installation progress. To check this, navigate to Applications in the menu bar.
2. AZURE CONFIGURATION
To store documents onto Azure, the admin will need to follow these steps to ensure all attachments and notes are being directed to store in Azure rather than Dynamics 365.
First, create a container within Azure Blob storage. This will be entered in the Dynamics 365 configuration so the system knows that any attachments will be stored within that container, which sits in Azure. Note: this can only be done if the organisation already has a resource group created within the portal.
Under Storage accounts within the Azure portal, click +Add and fill in the Storage account name in the new tab that opens. Leave every other option as is.
Once created, open the storage account and scroll down and open the Blobs service. Here, the admin will be able to create the containers that will contain the attachments uploaded via Dynamics 365. Recommended best practice is to create two global containers (which will be utilised in the Azure Attachment Storage Configuration page) and then create a container for each entity that will map attachments to Azure Blob Storage. The global containers that will be used for the configuration of the solution in Dynamics will also be the default container for any attachments that are not mapped to an entity.
Note: Create two (global) containers named “emailsattachmentcontainer” and “notesattachmentcontainer.” Set the “Public Access Level” of any other containers for their respective entities to “Blob,” as this will enable users to have a preview feature when hovering over the attachment link in Dynamics 365. Unless this is done, the preview feature will only display an error message.
3. DYNAMICS 365 CONFIGURATION
After a few minutes, the solution will now be installed in the Dynamics 365 environment. It can be verified in two places: first, from the site map where the admin will be able to see the “Azure Attachment Storage” module and second, via the solutions page where the solution will be displayed at the top of the list.
Under Azure Attachment Storage > Azure Blob Storage Setup, the admin will be able to configure how Dynamics will be communicating with Azure Blob Storage. This consists of Storage Account Name, Azure SAS Token, the notes and email attachments containers and an optional GUID field. Note: the GUID is inserted to restrict deletion of files from the Blob storage.
How to generate a SAS Token: First, click on the storage account that was created for this Dynamics 365 instance and then go to Shared access signature to add an Azure search which will bring up the SAS Token generation page.
Note: under Start and expiry date/time, set the date and time you want the SAS Token to expire. By default, it will expire after 24 hours.
Select the SAS token after it is generated.
Once copied, paste into the SAS Token field in the Azure Blob setup within Dynamics 365 and complete the other fields.
Once all fields are updated, click Confirm to save the changes. To confirm changes have been made, refresh the page and verify the message “Last modified by Admin Name” is at the bottom of the tab.
After configuring Azure Blob Storage set up within Dynamics 365, the admin will now have to enable the entities that will be using this add-on to upload documents and attachments. Under Azure Attachment Storage > Notes Attachment Entity Settings, tick all the boxes for every entity that requires the Azure Attachment functionality. Note: all entities will be displayed here using their schema names and not their display names.
After checking all entities that will have the Azure Attachment Management enabled, enter the container name in the CONTAINER NAME column. This will essentially map the entity to the container created in Azure and will store any attachments.
Note: if a container for an entity is not mapped, the global container will be the default destination of any attachments associated with that entity.
Now we can look at how to enable the functionality so end-users are able to upload multiple files onto the form using the web resources provided by the solution. These web resources are: msdyn_filesandattachments.html and msdyn_multiple_uploads.html.
Note: adding the web resources onto an entity form is not compulsory and will not hinder the upload of documents to Blob when done through the native notes creation via the social pane.
First, open the form for the entity that requires the attachment management functionality. Then, add a new tab to the form (1) and then select Web Resource (2) from the command bar of the form editor. Rename the Tab.
In the Add Web Resource dialog box, in the Web resource field, add the msdyn_multiple_uploads.html web resource. Tip: Search using the wild card key (*) before the first and last letter of the web resource. Give it a sensible name such as “DocumentUpload”.
Thereafter, configure the formatting by setting the number of rows to 13 and unchecking the display border option. Then click OK. Verify if the web resource is now on the form.
After creating the new tab for Multiple Uploads, repeat the same steps for the files and attachments tab. This tab will be where the user is able to access and download any files that have been uploaded against the record. For this, use the msdyn_filesandattachments.html web resource. The result should be as below.
Then save and publish and verify the tabs are now displayed on the entity form.
4. UNIT TESTING
As everything has now been published and is sitting in the environment, users can now go in and create notes and add attachments that will now sit in Azure Blob Storage. This section will cover where to verify if the functionality is working as expected.
First, open the entity where the Uploads and Attachments tabs are located. Drag and drop a file into the Uploads tab, create a note with it and add a description, then click Save. The attachments will now be displayed under the Attachments tab.
This will now be stored in the Azure Blob storage and the file name will be a concatenation of the GUID and the file name.
Note: if a user deletes a note in Dynamics 365, any related attachment with that note will also be deleted in Azure Blob storage.
5. EMAIL ATTACHMENTS
Above we have tested the attachments for notes within a Dynamics 365 record whereby the user will manually go and upload a document within the respective record. Email attachments are slightly different, as the attachments will come in via an email record. Therefore, the admin will enable attachment management for the Email entity in the NOTES ATTACHMENT SETTING ENTITY and then map the correct container to that entity (see image 1). Another point to note is that, if the email is tracked by Dynamics 365, then the attachment related to that email will also be displayed in the Azure Blob Storage and in the email’s Activity view (see image 4). If an email is tracked regarding a record that the user owns, then this will display in the Attachments tab of that specific record (see images 2 and 3). However, if the email is not “regarding” an actual record (which has attachment management enabled) then this will not be displayed under the Attachments tab in the email attachments list.
The same behaviour is also applicable when sending emails from Dynamics 365. When an email is sent with an attachment, then it is stored in the container mapped for email attachments (see image 5).
6. ADMIN TASKS
If the environment contains files that are being stored in the Dynamics 365 database, there are a couple of scenarios to consider:
- They could be from before the Azure Attachment Storage was implemented.
- It might be that Azure Blob Storage mapping from Dynamics 365 was done later that when the solution was first installed within Dynamics 365, and now there is a need to migrate them over to Azure Blob storage.
The admin can view how many files are currently sitting in the Dynamics 365 environment and how many files have been moved to the Azure Blob storage here: Azure Attachment Storage > Reports and Admin. To move the files over to Azure Blob storage, the admin will tick one or both checkboxes for Notes Attachments and Email Attachments and then click Move to Blob. If a special circumstance should occur in which the migration of the files to Blob should stop, the admin must click Stop Processing. Once the migration of the files has started, a message will be displayed at the bottom of the form to inform the admin of this. Refresh to see the update.
Note: ensure that mappings between the Notes and Email entities to the Blob Storage containers are configured before the migration.
Note: Dynamics 365 limits the movement of files to 140 attachments per fetch for maximum efficiency.
There are three entities that need to be configured to enable privileges for users to access the Attachment Management solution within Dynamics 365: Note, Azure Blob Storage Settings and NotesAttachmentEntitySetting.
First, the most basic security privileges that must be given to a user are read privileges on the Azure Blob Storage Settings and NotesAttachmentEntitySetting. This enables a user to see these two entities under the Azure Attachment Storage module on the sitemap, whereby they will be able to view the Azure Attachment Storage Configuration and the entities that have the solution enabled therein. For a user to have permission to upload, view, edit, and delete an attachment, the Note entity will have to be given full CRWD privileges.
Well, this was one of our longer blogposts, and if you made it this far, you’re now basically an expert on Azure Attachment Management! Let us know what you think.