Productivity is probably one of the most popular trends of recent years, and the Evernote solution is a prime example in this niche. Great news for Evernote users - now the opportunity to work with the solution in Outlook is also available, which will be discussed further.

I want to thank for the preparation of the article by Rodion Nasakin (Market Development Director Evernote in Russia and the CIS), as well as Actimind, an expert in plug-in development for various applications, including Microsoft Office applications.

In this article we want to talk about why Evernote needed to create an add-on for Outlook and share its development experience.

Why Evernote needed Outlook

Evernote service has become popular largely due to its versatility, allowing you to collect, synchronize and organize a variety of information. These can be text notes, handwritten sketches, scans, photos, articles copied from the Internet, task lists, voice recordings, and much more.



70% of users use Evernote in work and business, and it is obvious that a significant part of the necessary information comes to them by email. For Evernote, in turn, it is important that users can quickly collect all the information related to the working project in one place and work with it without leaving the application.

')

Therefore, in addition to a set of mobile and desktop applications, Evernote has several tools for working with incoming email. This, in particular, is copying chains of letters from Gmail with the Evernote Web Clipper plugin and sending it to a special Evernote address. And, of course, as soon as Office 365 added support for third-party add-ons (add-in), the service team thought about a special solution for such a prominent tool.



The development of Evernote for Outlook was assigned to the independent team Actimind , our compatriots from St. Petersburg. Previously, the guys had already worked on Evernote Web Clipper add-ons for browsers, so they had an idea about the Evernote API and the specifics of the service as a whole.



With Evernote for Outlook, users were able to copy a letter, correspondence in whole or in part to Evernote to their account, specifying the destination notebook and the necessary tags. Corporate notepads and tags for users of the Evernote Business solution are also supported.



By default, all files attached to emails are also saved to Evernote as attachments to a note. At the same time, printed and handwritten text in the attached images becomes searchable. You can send to Evernote and only a quote from the letter, highlighting the desired text.



The application works and "in the opposite direction" - you can quickly add notes from Evernote to the email created in Outlook to share them with colleagues.

How does the add-on for Outlook

An add-in or add-in (add-in) for Outlook is a manifest file, as well as one or more web pages. The manifest is an XML file that stores some information about the application, including the address from which Outlook will load the start page. Pages are directly responsible for the main logic and interface of the application. They will be opened in a secure frame on the Outlook website, and will be able to communicate with the service through a specially provided API.



Unlike classic add-ons for Outlook, new applications are launched only manually, in the context of one element. While the application is not running, it has no idea about the actions of the user. In addition, new applications can only work with letters and invitations. Support tasks, journal entries and calendar events in the online version of Outlook yet. But new applications are cross-platform and can work in any Outlook.com clients (Outlook 2013 or 2016, Outlook Online), including mobile ones.

Development environment

You can develop the add-in in any HTML + JS + CSS editor, but we would highlight two options.



First, Napa Office 365 Development Tools (www.napacloudapp.com), a cloud solution that is great for rapid prototyping.







Here you can quickly get acquainted with the main settings of the manifest and try out the JS API in action. Napa hosts the application files and automatically updates the manifest as it changes. When the online editor is no longer enough, the project can be exported, for example, to Visual Studio.



Visual Studio, starting with the 2012 version, supports the ability to develop add-ins for Office 365: it updates the manifest, raises IIS with files, and allows you to debug through IE. However, for the work you will need to install an additional component, which you can read more about here .



Other editors may have an embedded web server, but the manifest will most likely have to be downloaded and updated manually via the Outlook Manage add-ins menu item. However, this is not required so often.

Development process

The mithril + require.js bundle was chosen as the basis, the code was written mainly in CoffeeScript and Less. The assembly was carried out with the help of Grunt.

We took the exported file from Napa as the basis for the manifesto - it already has everything you need.

<?xml version="1.0" encoding="utf-8"?> <OfficeApp xsi:type="MailApp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"> <Id>e8df9484-022a-479e-8175-c08d2d540bdb</Id> ... <DisplayName DefaultValue="Evernote DEV"/> <IconUrl DefaultValue="https://localhost:44555/app/images/app-icon.png" /> ... <FormSettings> <Form xsi:type="ItemRead"> <DesktopSettings> <SourceLocation DefaultValue="https://localhost:44555/app/html/home-read.html" /> <RequestedHeight>350</RequestedHeight> </DesktopSettings> <TabletSettings> <SourceLocation DefaultValue="https://localhost:63342/app/html/home-read.html?mobile" /> <RequestedHeight>350</RequestedHeight> </TabletSettings> <PhoneSettings> <SourceLocation DefaultValue="https://localhost:44555/app/html/home-read.html?mobile" /> </PhoneSettings> </Form> <Form xsi:type="ItemEdit"> <DesktopSettings> <SourceLocation DefaultValue="https://localhost:44555/app/html/home-compose.html" /> </DesktopSettings> ... </Form> </FormSettings> <Permissions>ReadWriteMailbox</Permissions> ... </OfficeApp> 

The main parts of the manifest include the application ID, its name and description, as well as modes of operation and links. The Evernote application works in read mode (ItemRead) and in letter editing mode (ItemEdit), on desktops, tablets and mobile phones. If you wish, you can specify different links for each of these cases.



Since HTTPS is mandatory for all resources, a certificate is required. For the first time, a self-signed one will suffice for local development, but for a full-fledged verification, mobile clients will need a real one.



After adding the application manifest to your Outlook account, an application icon will appear above the email in read mode (or on the top panel in edit mode).



As mentioned above, all add-ins are launched manually, in the opening frame from above (or from the side, in edit mode) from the letter body. The corresponding page from the manifest will be loaded into it. The page should contain a link to office.js, which will create a global Office object and initialize it. All that remains is to put the application launch logic into Office.initialize.

  Office.initialize = (reason) => language = Office.context.displayLanguage context.init() 

After calling initialize, you can start using the JS API, for example, to get the interface language chosen by the user. By the way, good localization support is available, including manifest fields.







We used a scheme with several versions of the add-in — for development, for testing builds, and one stable for presentation. From the point of view of Outlook, these are different applications, each of them has its own manifest with a unique ID, and they refer to different places. This way you can develop and test without interfering with each other. In our case, the DEV-version manifest points to the path of the form "localhost: 44555", which is convenient for joint development. But if necessary, each developer can create his own version of the manifest for convenience or experiments.



As mentioned at the beginning, in the reading mode of the letter, the application should be able to save the current letter or the entire correspondence, as well as attachments of these letters.







When saving a letter, we also save all its attributes. In the JS API, getting them is very easy:

  item = Office.context.mailbox.item mail.subject = item.subject mail.sender = item.from.displayName + " ("+ item.from.emailAddress+")" 

With the body of the letter is more difficult, in reading mode it will not work. Fortunately, if the application has the ReadWriteMailbox access level, it is allowed to execute the makeEwsRequestAsync method, which allows you to execute a manually generated SOAP request to the service, though not any, but from a limited list. Using this method from the service, you can get some things that are not yet available through the JS API.

  Office.context.mailbox.makeEwsRequestAsync( @getItemUniqueBodyRequest(Office.context.mailbox.item.id), (asyncResult) -> @processMailSoap(asyncResult, callback)) 

getItemUniqueBodyRequest forms a SOAP request based on the letter identifier, processMailSoap parses the response sent. makeEwsRequestAsync, like many other potentially durable JS API methods, is asynchronous. The restriction applies to asynchronous methods - no more than three can be executed at the same time, besides, the maximum size of the returned result is limited to one megabyte.



In the same way, you can get a chain of letters, but with attachments any problems arise. The JS API does not provide direct access to attachment bodies. But there is a way to get them, for this you need to call the Office.context.mailbox.getCallbackTokenAsync function, get a short-term access token from it, and transfer it to the server along with a link to the Exchange service, which is located in Office.context.mailbox.ewsUrl. The server part has the ability to perform a limited set of SOAP requests to Exchange using a token, including receiving attachment data. The set of requests that the service can perform with the token is wider than the available client part with makeEwsRequestAsync, besides, the restriction of 1MB does not apply to it. But, unfortunately, the token is limited to access to one element, in the context of which the add-in was opened, even if ReadWriteMailbox permission is specified in its manifest, therefore it is not yet possible to save a chain of emails with attachments.



Users have the ability to set a notepad and Evernote tags to be used by default. To store these settings, the JS API provides an Office.context.roamingSettings object, which is synchronized for a specific add-in between all devices of this Outlook user. Values ​​are stored in JSON form.

  notebook = Office.context.roamingSettings.get(defaultNotebookSettingName) Office.context.roamingSettings.set(defaultTagsSettingName, ["tag1","tag2"]) Office.context.roamingSettings.saveAsync(callback) 

In the letter writing mode, the user can add a link to any of his notes. Recipients will be able to open the note in the browser, even if they are not users of Evernote.







Outlook JS API supports methods for inserting HTML fragments into the body. Along the way, we determine in what format the letter body is text and HTML, RTF as a letter format in Outlook 365 is not available.

  Office.context.mailbox.item.body.getTypeAsync (result) => if result.status == Office.AsyncResultStatus.Failed then return switch result.value when Office.MailboxEnums.BodyType.Html noteUrl = @getNoteShareUrl(note.guid, notebook, shareKey) imgSrc = @getNoteShareThmbUrl(note.guid, notebook, shareKey) html = @generateHtml(note, createdBy, noteUrl, imgSrc) Office.context.mailbox.item.body.setSelectedDataAsync(innerHtml, { coercionType: Office.MailboxEnums.BodyType.Html }) when Office.MailboxEnums.BodyType.Text noteUrl = remote.getNoteShareUrl(note.guid, notebook, shareKey) + "\n" Office.context.mailbox.item.body.setSelectedDataAsync(noteUrl, { coercionType: Office.MailboxEnums.BodyType.Text }) 

Attachments can be added to the letter if you have a direct link to them. Outlook will download and attach the file. But the ability to insert inline-elements is limited. The ContentID is not supported, and the base64 links Outlook filters. You can contrive and create an attachment, and then refer to it through the name, but this method is unreliable, besides the result will not appear immediately, but only after updating and saving the letter. It remains only to use absolute links to images. At the moment, the icon disappears if the user closes access to the note, due to the peculiarities of the operation of this mechanism in Evernote.

Difficulties

In general, Office JS API is fairly well documented , but of course it didn’t go without difficulties. Some points worthy of mention are listed below.



Almost immediately, we encountered the same-origin policy problem. It is good if you have the opportunity to immediately place the add-in files along with its server part, or you have access to the CORS settings . We had no such possibility during development. To save time, we developed in parallel with the preparation of the server part.



The easiest way to bypass the same-origin policy is Chrome, launched with the --disable-web-security flag. Similar opportunities exist for almost all major browsers, but to fully test and support mobile devices, we had to raise a small proxy server.



Debugging an application running in a desktop browser is not a problem. You have the choice of IDE and browser debugger. But debugging on mobile devices and in the desktop client can cause some difficulties, because the application is hidden inside the Outlook client. The most interesting thing is that the behavior of the application in the mobile client may differ from the behavior of the application opened in the online version of Outlook on the same device (most styles, of course, suffer). The internal log helps a little with output to the interface, but a full-fledged debugger in such circumstances is sometimes not enough, but the recent announcement of the release of Office UI Fabric - the debugger interface, according to the Office 365 development team, has to fill this gap.

Add-In Evernote for Outlook

However, in general, we managed to create a fairly functional and convenient solution at the level of Evernote Web Clipper extensions for browsers. So if your audience is actively working with Outlook, cross-platform and mobility is important to you, and also you are thinking about integration, we hope that our experience will be useful for you.