Skip to main content
Dynamics 365
·
9 min read

Extending the Outlook Add-in Experience in Microsoft Dynamics 365 Business Central and Microsoft Dynamics NAV

One of the showcase features of Dynamics 365 Business Central is the ability to use the product within Microsoft Outlook clients using Outlook add-ins. There are two add-ins that come out of the box with Dynamics 365 Business Central: The Contact Insights add-in and the Document View add-in.

From an email within Outlook, Contact Insights enables the user to go straight to the Contact, Customer, or Vendor Card that is associated to the sender or recipient of the email message. From there, information about the contact may be viewed or edited and documents may be created and sent directly in Outlook. Given an email that contains a document number within the body of the message, Document View enables the user to directly open that document within the context of the email message; from there, the document may be edited (if it is still a draft), posted, or emailed to the customer. Figure 1 shows the Contact Insights add-in opened inside of the Outlook web client.

That explains the default add-ins in a nutshell. But what happens if there is a scenario that is not supported by the default add-ins? That is exactly what this article is about – enabling new scenarios through new or modified Outlook add-ins for Business Central. To understand how to extend the existing Outlook add-ins or create new add-ins, we first need to understand how the Outlook add-ins work with Business Central. If you don’t care and just want to try creating an add-in yourself, feel free to skip to part two.

Also, the same steps apply to the Outlook add-in for Dynamics NAV, provided that your Dynamics NAV deployment uses either Azure Active Directory or NAVUserPassword as the authentication mechanism. For more information, see Credential Types for Dynamics NAV Users.

Part 1 – The Outlook add-in Architecture

In the simplest terms, an Outlook add-in is a frame that loads some web page. In our case, that web page happens to be the Dynamics 365 Business Central web site. There are three different pieces to the Business Central Outlook add-ins: the add-in manifest, the code that generates the manifest, and the code that handles the add-in session. The Outlook add-in manifest contains information about how to load the add-in. It tells Outlook what buttons should appear in the Outlook client, what text those buttons should contain, the images that should appear on those buttons, and, most importantly, what to do when those buttons are clicked. The code that generates the manifest is on the Business Central side. This code takes a manifest template (defined in a particular codeunit) and puts the correct strings, resource image links, and URLs in the manifest based on the system language and server configuration. This is an important point to understand – the manifest will look different depending on the tenant from which the manifest was generated and the language. The last component in this system is the actual code on the Business Central side that handles the incoming add-in session. This consists of a web page made specifically for the Outlook add-ins (OfficeAddin.aspx) as well as C/AL code that loads the correct page and record based on the incoming add-in context. The context contains information about the email from which the add-in loaded – such as: sender or recipient(s) of the message, the email subject, etc. This enables a custom experience depending on the contents of the email message.

Manifest File

Let’s dig into the manifest file first. You can take a look for yourself by jumping over to the Office Add-in Management page (Page 1610), selecting the “Contact Insights” row in the table, then clicking the “Download Add-in Manifest” action. This will prompt your browser to download the XML manifest file, which is what gets deployed to Exchange during the add-in setup step. There are two main pieces to the manifest file. The top portion is what describes the add-in itself. It contains information such as the name, description, and icon for the add-in. When you manage your add-ins in the Outlook portal, this is the information that will appear for the Contact Insights add-in.

The top portion of the manifest also contains the web address to load when a user launches the add-in from the horizontal pane. This is the single Business Central button right above the body of the email message that is shown in the first screenshot above, as opposed to the branded icons, which are add-in commands.

The add-in commands are defined in the VersionOverrides element. You can use this portion of the manifest to define different actions. In the Contact Insights add-in, we have a button that performs the default action as well as a menu button that contains several different actions for creating new documents for the contact in the email message. Each of the buttons in the Contact Insights add-in are links to the OfficeAddin.aspx page that specify a particular command as a query string that will get processed later by C/AL code. All of the strings related to the buttons as well as the URLs are defined at the bottom of the manifest file – within the Resources element. Figure 3 shows how the OfficeContext and Command query strings are specified in the button URL.

Manifest Generation

The Office Add-in Management page can be used to add new add-ins to the system that can later be deployed to a user’s mailbox or to the whole organization. To create a new add-in in the system, you must first write the manifest file for your new add-in. You can use either of the two default add-ins or the manifest in the example below as a reference. Just make sure to change the id of your new add-in. You’ll need to decide whether the manifest that you’ve built is deployable by itself or if the manifest needs to be customized at add-in deployment time based on the Business Central system settings. As an example of the latter, the Document View add-in manifest is generated at deployment time because the system puts information about the system’s number series into the manifest so that the add-in can recognize document numbers in emails. In most cases, however, the manifest could stand by itself.
Once the manifest is created, the add-in can be created in Business Central by clicking the “Upload Default Add-in Manifest” action in the ribbon of the Office Add-in Management page. This will create a new record in the table. Now, the system will pull the name, description, and version from the manifest and use those in the table. The “Manifest Codeunit” field is used to specify a codeunit that will make any deploy-time customizations to the manifest that you just uploaded. If that’s not necessary, it can be left as 0. At this time, the add-in could be deployed using the “Set up your Business Inbox in Outlook” wizard. For more information, see Using Business Central as your Business Inbox in Outlook.

Handling the add-in

Up to this point, we’ve only discussed the generation of the add-in, but nothing about what causes the correct Business Central pages to open once the add-in is launched. The whole flow can be described in these seven steps:

  1. Outlook loads the manifest for the add-in and loads the frame.
  2. The frame launches the URL specified in the manifest, which is the OfficeAddin.aspx page on the Business Central web server.
  3. OfficeAddin.aspx makes use of some of the Office JavaScript libraries to pull contextual information from the email item.
  4. This page then launches the Business Central client on page 1600 and passes the contextual information to the page as filters.
  5. Page 1600 wraps all the information it got into an “Office Add-in Context” temporary record.
  6. Page 1600 then passes this record to Codeunit 1630 (Office Management), which determines what to do based on the incoming context.
  7. The correct page is rendered in the client and shown to the end user.

I encourage you to look at the attached PowerPoint file to get a step-by-step diagram of this flow. If you would like to understand more about how this flow works and you have access to the code, I also encourage you to check out the code for the objects that are referenced.

Part 2 – Creating a new, custom add-in

Let’s walk through the end-to-end process of creating a new add-in. That means: writing the manifest, uploading the manifest into the system, writing the code to handle the add-in session, and deploying the add-in through the Business Central system.
In this example, we will be writing a new add-in that simply shows the company’s product list in Outlook. It will do this by launching the Item List page.

The Manifest

There are a few things we need for our new manifest: the add-in information (id, version, name, etc.), the icon url, and the url to point the add-in when the user launches it. All but the last one are straightforward. The actual URL to point the add-in is what is most important here. If this isn’t formatted properly, then the add-in will not work. Let’s look at how this add-in is formatted. See figure 4.

  1. This is the URL to your Business Central instance.
  2. The OfficeContext tells Business Central what add-in it needs to be concerned with. It is how BusinessCentral differentiates between the Contact Insights add-in, the Document View add-in, and any new add-ins you might create.
  3. This is the version of the add-in. It should be the same as the version at the top of the manifest file. Note: If these versions are not the same, your add-in will not load correctly.

Create the add-in in Business Central

Once your manifest looks correct, it’s time to upload the manifest into your Business Central instance. To do this, open the Office Add-in Management page and choose the Upload Default Add-in Manifest action. Browse to your manifest file on your machine and choose Open. Observe that a new row is inserted into the table that contains the same name, description, and version that was specified in the manifest file. For this demonstration, we will not be inserting any deploy-time settings into the manifest file, so we will leave the manifest codeunit as 0.

Handling the add-in request

We previously mentioned the Office Management codeunit (1630) and how it is responsible for deciding what to do inside of the add-in. There is a function inside of this codeunit called “GetHandlerCodeunit”, which looks at the HostType of the add-in (specified through the OfficeContext query string in the url – see Figure 4) and checks if that HostType is for one of the default add-ins.

It also has a publisher function that gets the codeunit number to run in the case that the host type doesn’t fit one of the default add-ins. We need to write a new codeunit that subscribes to this function and tells Office Management to run the new code we write. The codeunit that we write needs to have two things regarding this: first, the subscriber function that I just mentioned and second, logic in OnRun that does what we want, which in this case is show the Item List page. See figure 7 to see how to set the properties on the event subscriber in the new add-in handling codeunit.

We also need to add two more subscribers that will allow the add-in engine to get the Office Add-in record for our new add-in. Both of published functions are in codeunit 1652 – Office Add-in Management: GetManifestCodeunit and GetAddin. The resulting code should look something like figure 8. Containing the OnRun logic and the three event subscribers. Note that in figure 8 relies on two text constants:

  1. ProductListHostTypeTxt – This is the same value as the OfficeContext in the manifest, which in this case is “Outlook-ProductList”.
  2. AddinIdTxt – This is the Id of the add-in, which is the GUID that we generated and put in the add-in manifest. It is also the primary key of the Office add-in table.

All the pieces are now in place for our new Outlook add-in for Business Central. The only thing left to do is deploy it through the assisted set up wizard. Do that now and then launch your Outlook client. If you are using OWA (Outlook Web Access), you will need to do a hard refresh of the page so that the client can load your new add-in manifest that you just deployed. Now click on an email, and see that your new add-in is available in the email. You should be able to just click the Product List link to launch the addin and then see the Item list page.

Summary

This example was very simple, but you can use the same steps to do virtually anything you’d like with your custom add-in. In addition, you might have already figured out how you could change the default add-in functionality by changing the OfficeContext in some of the URLs in the manifest and then creating your own handler codeunit for the new functionality. There are essentially five steps that we took to create our own custom add-in:

  1. Create the manifest XML file for the new add-in that specifies an OfficeContext in the URLs.
  2. Upload the manifest in the Office add-in management page.
  3. Implement a new codeunit that will handle the add-in session for your specific OfficeContext.
    1. This codeunit must include the three event subscribers we talked about.
  4. Deploy the add-in to your mailbox.
  5. Launch it from your Outlook client.

Interesting C/AL Objects

PAG1600 – The entry point into Business Central from the add-in.

TAB1600 – The container for all the context-specific information that comes from Outlook.

COD1630 – The engine of the add-ins. All add-ins go through this codeunit when initialized, and all AL objects that need to access the add-in go through this codeunit.

COD1636 – This finds a contact/customer/vendor based on the email context and redirects to the appropriate card page.

COD1637 – This finds a referenced document number (Document View add-in) and opens the related page.

COD1642/1643 – These handle custom add-in manifest (XML) generation when deploying the add-in.

navteam

Related posts