Breaking news from around the world
Get the Bing + MSN extension
Now Available in Community - MBAS 2019 Presentation Videos
Catch the most popular sessions on demand and learn how Dynamics 365, Power BI, PowerApps, Microsoft Flow, and Excel are powering major transformations around the globe. | View Gallery
2019 release wave 2 Discover the latest updates to Dynamics 365Release overview guides and videos Release Plan | Early Access Availability
Ace your Dynamics 365 deployment with packaged services delivered by expert consultants. | Explore service offerings
Connect with the ISV success team on the latest roadmap, developer tool for AppSource certification, and ISV community engagements | ISV self-service portal
The FastTrack program is designed to help you accelerate your Dynamics 365 deployment with confidence.
FastTrack Program | Finance TechTalks | Customer Engagement TechTalks | Talent TechTalks | Upcoming TechTalks
One of the showcase features of Dynamics 365 Business Central is the ability to access Business Central functionality from your Outlook client, your Business Inbox in Outlook. You can look up contact and financial information from within the context of your email conversation or calendar meeting request, create documents such as invoices, and more. For additional detail on the add-in experience, see Using Business Central as your Business Inbox in Outlook.
One of the more common questions we get in relation to this functionality is, “Can I customize the Outlook add-in experience?”
Yes. Yes you can.
There are a couple of options for customizing or extending the Outlook add-in experience for Business Central:
Come back tomorrow for Part 2 of this series, where we’ll explore the option of customizing the existing add-in pages. In this blog post (Part 1), we’ll explore how to create a custom Outlook add-in that connects to your Business Central client.
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.
The Outlook add-in for Business Central uses the standard Outlook extensibility model to surface Business Central functionality. In the simplest terms, an Outlook add-in is a frame in Outlook that loads a web page. In our case, that web page happens to be the Business Central web site, which is rendered in a format designed for a streamlined Outlook experience.
There are three different pieces to the Outlook add-ins:
The Outlook add-in manifest contains information about how to load the add-in. It tells Outlook which buttons to display 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 people click the buttons. 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 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.
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, 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. This is the primary Business Central section of the ribbon you see in the desktop Outlook client, or the Business Central icon that displays in the Outlook Web App above the body of the email.
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 Contact Insights 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 base application 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. The figure below shows how the OfficeContext and Command query strings are specified in the button URL.
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 company’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.
After 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, which can be opened from the Assisted Setup page.
Up to this point, we’ve only discussed how to generate the add-in, but nothing about what causes the correct Business Central pages to open when the add-in is launched. The whole flow can be described in these seven steps:
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.
There are a few things we need for our new manifest, such as the add-in information (ID, version, name, and so on), the icon URL, and the URL to point the add-in to when the user launches it. All but the last of these are straightforward. The actual URL to point the add-in to 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 the figure below.
When your manifest looks correct, it’s time to upload it to Business Central. To do that:
Note that a new row is inserted in the table that contains the same name, description, and version that was specified in the manifest file. For this demonstration, we will not insert any deploy-time settings into the manifest file, so we will leave the manifest codeunit as 0.
We previously mentioned the Office Management codeunit (1630) and how it determines 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) and checks whether 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 codeunit. The following image shows how to set the properties for the subscriber. For more information on creating event subscribers in AL, see Subscribing to Events.
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 the published functions are in codeunit 1652 – Add-in Manifest Management: GetManifestCodeunit and GetAddin. The resulting code should look something like the figure below, which containing the page run logic and the three event subscribers.
Note that the code in the figure relies on two text values that are specific to the Product List add-in:
After you have created the extension, you just need to upload it to your tenant on the Extension Management page in Business Central.
All the pieces are now in place for the new Outlook add-in. The only thing left to do is deploy it through the Assisted Setup 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 the new add-in manifest you just deployed. Now click on an email, and see that your new add-in is available. You should be able to just click the Product Catalog action to launch the add-in and then see the Item List page.
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:
Have ideas for some cool Outlook add-ins for Business Central? Feel free to toss them out in the comments below.
Get a list of all posts in the Holiday count down series here: https://community.dynamics.com/business/b/financials/archive/2018/11/28/counting-down-to-the-holidays-with-daily-blogs
Thank you for this post.
When I'm using all the information on this post, I get a message in my custom add-in: "The Office host has not been initialized."
Do you have an idea what could have gone wrong?
@Peter-Paul, no, you don't necessarily need to deploy the add-in using the "Deploy All Add-ins" action. As long as the manifest is uploaded in the Office Add-in Management page, you can deploy the manifest to the Exchange mailboxes using whatever method works best for you.
Deploying the add-ins from the Office Add-in Management page uses administrator privileges to deploy the add-in to all mailboxes on the tenant. If you only want to deploy the add-ins to a few mailboxes, you can do that using the Set up your Business Inbox in Outlook wizard, which you can open from the Assisted Setup page.
If you do want to deploy the add-ins as an administrator to all mailboxes, there is currently a bug caused by deprecated Exchange endpoints that were being used to deploy the add-ins from the Office Add-in Management page, resulting in the error message you are seeing. Until we're able to find another method for automated deployment from Business Central, you have a couple of options of other options for administrative deployment:
1. Deploy the add-ins using the Office 365 admin center:
2. Deploy the add-ins using PowerShell cmdlets:
Do we have to run the "Deploy All Add-ins" command from the Office Add-in Management page to get this working? If so, why are we getting an error doing this (in BC CU2):
The application %1 did not install as expected. This might be caused by problems with the manifest file, problems connecting to the Exchange PowerShell server, or a version number that is not equal to or higher than the already installed application. You can download the manifest locally and then upload it to the Exchange Administration Center to determine the cause.
Where in the Exchange Administration Center can we upload this manually?
Business Applications communities