Quantcast
Channel: Outlook dev blog
Viewing all 108 articles
Browse latest View live

Introducing add-in commands

0
0

Today we bring you the first in a two-part series of guest blog posts from Andrew Salamatov, a Senior Program Manager with our Outlook team. You can find the second part here. Enjoy!

Back at Build and Ignite, we announced a brand new feature, that we’re very excited about – Outlook add-ins (formerly called apps for Outlook) can now place buttons on the ribbon in Outlook! This simultaneously simplifies interacting with add-ins, as well as makes their presence more visible and engaging.

A new message window in Outlook showing multiple add-in buttons on the ribbon.

In a two-part series, we wanted to share our thinking behind why we invested in commands and how they work, as well as walk through a sample add-in with a command. This is the first post in the series.

What are add-in commands?

The idea behind commands came from your feedback! Users are demanding a fast, simple way to get to the actions they need most. Meanwhile, developers have been trying to make their add-ins stand out and feel native. As we thought about the various scenarios that were being built on the Outlook add-in platform, we arrived at three guiding principles.

First, add-ins must look and feel native to each Outlook client. Mobile Outlook is very different from desktop Outlook and Outlook.com. Yet users flow from one to the other throughout the day and expect the power of 3rd party add-ins to support them, wherever they are. On top of this, the clients differ in their UI and user interaction patterns, due to form factor limitations and use cases. The same UI entry point and experience will not work across all these clients. Instead, our platform must enable developers to integrate in a way that meets user expectation on each form factor.

Second, the platform must scale to support many add-ins. Whether a user wants to use 1 add-in or multiple, the entry points must scale. And this must be completely abstracted away from add-ins, so developers don’t have to focus on handling interoperability with other add-ins.

Third, the platform must be write once, run everywhere. It would be very expensive for developers to implement an add-in for desktop Outlook, then re-write it for Outlook.com and mobile. Add-ins would take years to develop and update with new functionality. Instead, the platform should provide developers with generic concepts and APIs, which may result in different UI or positioning across the different environments, but will behave the same way across all Outlook clients.

Applying these principles to scenarios where the user has to take an action on a message or appointment, it became obvious that the best experience would be to let add-ins place commands for users where users expect them. In desktop Outlook, this is of course the ribbon.

Command types

In this first release of commands, we support 3 different types:

A command which executes a function

A compose message window in Outlook with an add-in command button that executes a function, and a success message in the infobar.

This type of command is best suited for tasks which don’t require extra input beyond clicking a button. For example, "save to CRM", "create a new issue in service issue database from this email", "insert tracking pixel", "archive message", etc. It is important to communicate to the user whether or not this action was successful. This can be done via an infobar message, which is described in more detail in part 2 of the blog post.

A command which launches a task pane

The Yelp add-in in Outlook, which is an example of a command that opens a task pane.

 

The Evernote add-in, which is an example of a command that opens a task pane.

The task pane command is best used when the user needs to enter extra input or interact with UI. The task pane gives your app a place inside Outlook to display your own HTML/JavaScript-based UI.

A command which is a dropdown and shows a list of commands of either of the other two types

The Quick Insert command from the EmojiO sample, which is an example of a command that opens a drop-down menu.

The dropdown command is best suited for when a user needs to make a choice from a set of options. For example, "remind me if no one replies to this email in 1, 2, 3, … days", "assign classification", "archive for X days or months", "quick-order drinks, appetizers or heavy lunch for meeting". This command has an advantage over the task pane, in that the options appear natively and instantly to the user, and the user doesn’t need to wait for the task pane to load, or even move the mouse away. This should be used over a task pane anywhere, where the choice is simple and no additional input is necessary.

Now that you’ve had a taste for commands, stay tuned for our next post, which dives into how to build them!

-Andrew


Building add-ins with commands

0
0

Today we bring you the second in a two-part series of guest blog posts from Andrew Salamatov, a Senior Program Manager with our Outlook team. You can find the first part here. Enjoy!

Because of their advantages, we’re encouraging all developers building add-ins to use commands. In fact, soon we’ll start requiring add-ins submitted to the Office Store to use them for scenarios where it makes sense. In this post, I wanted to share the easiest way to get started building an add-in with commands.

To begin, we’ll need an Outlook 2016 client connected to an Office 365 account, a developer preview Outlook.com account, or an on-premises Exchange email account. As we announced back in April, this feature is new to Outlook 2016, which is shipping very soon (and other Outlook clients like mobile and web to follow soon!). For now, you can get your hands on an Outlook 2016 Preview client here. As for the email account, the easiest thing to do is to either use your existing Office 365 account or create one here.

Once you’ve installed the client, let’s get started building the add-in. In this blog post, I’ll show how to build an add-in with a simple button in a message compose form, which will translate selected text into Russian. The user flow will be very simple – user types in some text, clicks the button, and the text is replaced with its translation. As you know, add-ins consist of an XML manifest and html/javascript code. Let’s look at the manifest first.

The manifest

A quick aside on the manifest...

To support add-in commands, we had to introduce some changes to the existing manifest. To declare commands, developers use the existing 1.1 manifest, but must add a new section at the end called VersionOverrides. We introduced this section for backwards compatibility. Older clients, which do not support add-in commands will ignore this and activate the add-in according to the definition above this element. Newer clients will parse and use this section to run the add-in, ignoring activation rules above VersionOverrides. Because we still have users on older bits, your add-in must work the older way as well.

The concept behind VersionOverrides is that elements defined inside it override ones defined above. You can refer to this list for all the elements that can be overridden.

You’ll notice that we’ve changed the Host element to now contain extension points. Extension points are a new concept – the set of all extension points in a form factor define all the different ways that the add-in will integrate in that form factor. In the future, we will add new extension points as well as support for more form factors.

Ok, back to the translation add-in. The key part of the manifest is the Host element:

<Hosts>
  <Host xsi:type="MailHost">

    <DesktopFormFactor>
      <FunctionFile resid="functionFile" />

      <ExtensionPoint xsi:type="MessageComposeCommandSurface">
        <OfficeTab id="TabDefault">
          <Group id="translateGroup">
            <Label resid="groupLabel" />
            <Tooltip resid="groupTooltip" />

            <Control xsi:type="Button" id="translateButton">
              <Label resid="translateButtonLabel" />
              <Tooltip resid="translateButtonTooltip" />
              <Supertip>
                <Title resid="translateSuperTipTitle" />
                <Description resid="translateSuperTipDescription" />
              </Supertip>
              <Icon>
                <bt:Image size="16" resid="icon1_16x16" />
                <bt:Image size="32" resid="icon1_32x32" />
                <bt:Image size="80" resid="icon1_80x80" />
              </Icon>
              <Action xsi:type="ExecuteFunction">
                <FunctionName>translate</FunctionName>
              </Action>
            </Control>
          </Group>
        </OfficeTab>
      </ExtensionPoint>

    </DesktopFormFactor>
  </Host>
</Hosts>

You’ll notice here that we’ve declared an extension point MessageComposeCommandSurface, and in it we have defined controls. This generic name creates an abstraction, so developers have a single way to declare a button on a primary command surface and have it show up across Outlook desktop, Outlook.com and Outlook Web App (support for the latter two coming very soon). Take a look here to see which other extension points are supported currently.

The MessageComposeCommandSurface is made up of OfficeTab elements. These correspond to ribbon tabs in Outlook. Developers can declare one group on the home tab and/or one custom tab with up to ten groups (and six buttons per group). For the translate add-in, we’ll utilize the default Outlook tab (if you wish to create a custom tab, use the CustomTab element instead).

Next, take a look at the Control element. It’s a button, whose action is to execute a function. Most of the elements in it should be self-explanatory, but take a look here for complete documentation. What’s interesting about this button is its action. Rather than showing a task pane or a dropdown, Outlook will execute the specified function in a browser instance. Of course, that JavaScript function will have access to the entire Office.js API as well as all other JavaScript APIs. So, for example, if it needs to launch a pop-up browser window, it can do so using window.open(). This function must be defined in the HTML file specified by the FunctionFile element at the top of VersionOverrides (see full manifest in our Git repo linked at the bottom).

Finally, you’ll notice several resid attributes. We’ve made a slight change how strings are specified in the manifest with the VersionOverrides update. Since for some buttons, developers will want to reuse the same string, which might have many locale overrides, all strings and URLs are now defined once in separate section, and referenced via a resource id, or resid. This section is at the end of the manifest:

<Resources>
  <bt:Images>
    <bt:Image id="icon1_16x16" DefaultValue="https://ssl.microsofttranslator.com/static/222083/img/trans.png"/>
    <bt:Image id="icon1_32x32" DefaultValue="https://ssl.microsofttranslator.com/static/222083/img/trans.png"/>
    <bt:Image id="icon1_80x80" DefaultValue="https://ssl.microsofttranslator.com/static/222083/img/trans.png"/>
  </bt:Images>
  <bt:Urls>
    <bt:Url id="functionFile" DefaultValue="~remoteAppUrl/AppCompose/FunctionFile/Home.html"/>
  </bt:Urls>
  <bt:ShortStrings>
    <bt:String id="groupLabel" DefaultValue="Translator"/>
    <bt:String id="translateButtonLabel" DefaultValue="Translate"/>
    <bt:String id="translateSuperTipTitle" DefaultValue="Click this to translate text from English to Russian."/>
  </bt:ShortStrings>
  <bt:LongStrings>
    <bt:String id="groupTooltip" DefaultValue="Translate actions"/>
    <bt:String id="translateButtonTooltip" DefaultValue="Translates text from English to Russian."/>
    <bt:String id="translateSuperTipDescription" DefaultValue="Translates text from English to Russian."/>
  </bt:LongStrings>
</Resources>

The business logic

Now that we’ve written the manifest, we just need to hook up the logic to the button. Above, we defined the function which should be invoked when the button is clicked, and the file where the function is specified. As you’ll see in the complete sample solution, I broke out the logic into a separate JavaScript file, which is referenced by the HTML file. The main reason for this is to demonstrate that you can still have entirely separate js files, if you like. In the JavaScript file, you can see Office.initialize and the function translate. Office.initialize gets invoked as usual first. You can do any authentication that you need here. Once that returns, the specified function in the manifest will be invoked. In our case, that’s translate.

Important aside: The type of button we defined doesn’t show any UI natively, once pressed. This means that the user won’t know by default whether the click was successful, still processing or resulted in an error. The good news is that developers can use notification message APIs to convey progress and ultimately success or failure.

There are three types of notification messages:

  • Progress indicator
  • Informational message
  • Error

Developers should always show a success or error message, as otherwise users may not know if the operation fully succeeded, or just partially.

Informational messages can be permanent, meaning every time the user clicks on this message/appointment the message will be there (unless the user dismisses it), or temporary, meaning that it will be shown only once to the user. An example of a permanent message would be "This email is now tracked in CRM." While a temporary example would be "Translation succeeded". The latter is not important for the user to see if he or she ever comes back to this message in the future.

Error messages are always displayed to the user just once, and developers don’t control this.

When it comes to progress indicators, it’s up to the developer whether or not to show one. If the function will almost always execute very quickly and return a result, showing a progress indicator for a few milliseconds will result in a "flash" to the user, which they weren’t able to see anyway. So in these cases it doesn’t make sense to show a progress indicator. On the other hand, if the button will make a call to a web service, which is known to take a bit, then a progress indicator should definitely be shown.

Note that if for some reason it takes us more than 500 ms to launch the function (maybe it’s taking us a while to load the HTML/JS), we’ll display a default progress indicator anyway. If the developer then invokes a method to add a new notification message of any type, the current indicator will just be replaced.

There are APIs to replace messages, so that the UI is as smooth as possible. For all the details, go here.

Back to the translate function, which is where all of our logic happens (you’ll notice an event parameter passed – see documentation here and here). In this case, the service we’re using is pretty fast, so we won’t be adding a progress indicator. Instead, we’ll do the translation, and then set a success message (if we did show a progress indicator, we would call replace, instead of add here). The last step is to call event.completed(). This is critical, because it lets Outlook know that your function is done. Otherwise, there will be awkward UI that the user will see. The entire method looks like this:

 function translate(event) {
  Office.context.mailbox.item.getSelectedDataAsync("text", function (ar) {
    var requestUrl = generateRequestUrl(ar.value.data);

    $.ajax({
      url: requestUrl,
      jsonp: "callback",
      dataType: "jsonp",
      success: function (response) {
        var translatedText = response.text;
        var textToWrite = "";

        for (var i = 0; i < translatedText.length; i++)
          textToWrite += translatedText[i] + "<br/>";

        Office.context.mailbox.item.setSelectedDataAsync(textToWrite, { coercionType: "html" }, function (asyncResult) {
          Office.context.mailbox.item.notificationMessages.addAsync("success", {
            type: "informationalMessage",
            icon: "icon1_16x16",
            message: "Translated successfully",
            persistent: false
          });

          event.completed();
        });
      }
    });
  });
}

And that’s it! Now we can publish our code to a web server, install the manifest into a mailbox and try out the add-in. As always, check out Outlook Dev Center for more info. You can get help by posting a question on Stack Overflow, or on our MSDN forum.

You can find the full source code to the project on GitHub.

Enjoy!

-Andrew

Deprecating the REST API preview endpoint

0
0

As many of you know, the Outlook REST APIs moved from preview to general availability in October 2014. As part of this transition, we are shutting down the old preview endpoint https://outlook.office365.com/ews/odata on October 15th, 2015. You can continue to use the https://outlook.office.com/api/beta endpoint to check out our latest and greatest APIs. We require all apps & services using the https://outlook.office365.com/ews/odata endpoint to move to https://outlook.office.com/api/v1.0 endpoint by October 15th, 2015. This will also enable the apps to benefit from API enhancements being added continuously to https://outlook.office.com/api/beta and https://outlook.office.com/api/v1.0.

Where do I go to find more about it?

If you want to know more about what features are supported by the https://outlook.office.com/api/ endpoint, go to https://dev.outlook.com/, where you will find getting started materials and API references. Please check https://dev.outlook.com/ for any future updates. You can also post your questions on Stack Overflow with outlook-restapi tag.

Message Body property will filter unsafe HTML by default

0
0

As part of the Office 365 APIs, the Mail API lets you read, create, and send messages and manage folders in a user's mailbox in Office 365 or Exchange Online.

We are making a change in what is returned by default in the MessageBody property.

By default, we will strip any potentially unsafe HTML content from the Body of the Message or Post entity if the ContentType is HTML.

Here is an example of potentially unsafe HTML in the message body and below it you can see the filtered body.

Unfiltered HTML body

 "Body": { 
  "ContentType": "HTML",
  "Content": "<html><body><b>Bold</b><script>alert('Alert!');</script></body></html>"
}

Filtered HTML body

 "Body": {
  "ContentType": "HTML",
  "Content": "<html><body><b>Bold</b></body></html>"
}

If you require the un-filtered content, you can continue to get it by providing the following HTTP request header.

 Prefer: outlook.allow-unsafe-html

By default, if the Prefer header is not present, the API will return filtered HTML. The API will only return the unfiltered (and potentially unsafe) HTML if the header is present and set to outlook.allow-unsafe-html.

This change is being rolled out in our production service and will be widely deployed over the next few weeks.

If you have any questions please reach out to us on Stack Overflow using the outlook-restapi tag.

Outlook REST API changes to beta endpoint

0
0

We are making a few changes to the Office 365 REST APIs beta endpoint. The changes are being rolled out in pre-prod and production systems and will be widely deployed over the next few weeks.

User ID changed

The User entity's Id property will start returning a new format: {AAD User Id}@{AAD Tenant id} instead of the user's SMTP address.

 {
  ...
  @odata.id: "https://outlook.office365.com/api/beta/Users('9607a528-7230-43d2-bb04-b2e576eafba5@2dc87bd3-88ff-4b99-b7ba-618c973e93ea')",
  Id: "9607a528-7230-43d2-bb04-b2e576eafba5@2dc87bd3-88ff-4b99-b7ba-618c973e93ea"
  EmailAddress: "rohitag@contoso.com",
  DisplayName: "Rohit Nagarmal",
  Alias: "rohitag",
  ...
}

Note that we are also adding the EmailAddress property to User that contains the SMTP address that used to be in Id.

The request to find a user will continue to allow specifying an SMTP in addition to the new id format. So both of these requests are valid:

 GET https://outlook.office365.com/api/beta/users/rohitag@contoso.com

GET https://outlook.office365.com/api/beta/users/9607a528-7230-43d2-bb04-b2e576eafba5@2dc87bd3-88ff-4b99-b7ba-618c973e93ea

With this change, we have made the API more consistent with our Groups API where the ID always returned in the {AAD User Id}@{AAD Tenant id} format.

IsContactPhoto property removed

We have removed the IsContactPhoto property from the FileAttachment entity.

Hopefully this was something that you were not using anyways, but if you had your clients deserialize the FileAttachment object and were reading this property, you will have to update the code to remove references to it.

Name changes

We are making changes to entity names and property names to avoid naming conflict and confusion when we expose the Outlook entities in the Office 365 Unified API.

  • Folder entity renamed to MailFolder
  • Folders property on User entity renamed to MailFolders
  • DatetimeLastModfied renamed to LastModifiedDateTime
  • DateTimeCreated renamed to CreatedDateTime
  • DateTimeReceived renamed to ReceivedDateTime
  • DateTimeSent renamed to SentDateTime
  • DateTimeLastDelivered renamed to LastDeliveredDateTime

Please stay tuned, we are also making updates related to timezones and reminders in calendar events. We will have a separate post on these changes very soon.

Thanks,
Rohit

Outlook REST API changes to beta endpoint - Part II

0
0

I wanted to update you all on some more breaking changes that we are making to the Outlook REST API beta endpoint. These changes will be widely deployed over the next few weeks.

Reminders for events

The property Reminder will be removed from the Event entity, and two new properties ReminderMinutesBeforeStart and IsReminderOn will be added to the Event entity.

Example:

 {
  "ReminderMinutesBeforeStart": "15",
  "IsReminderOn": "true"
}

A new function ReminderView will also be added. This will return a list of reminders within the start and end times specified.

Example:

 .../api/Beta/me/ReminderView(startDateTime='2015-10-08T16:56:00',endDateTime='2015-10-12T00:56:00') 

In addition to this, two new actions Snooze and Dismiss will be enabled. These actions can be used to snooze a reminder or dismiss a reminder after it has been fired.

Example:

Snooze:

 .../api/Beta/me/Events('Id')/SnoozeReminder 

{
  "NewReminderTime": {
    "DateTime":"2015-10-13T08:30:00",
    "TimeZone":"Pacific Standard Time"
  }
}

Dismiss:

 .../api/Beta/me/Events('ID')/DismissReminder 

Timezone

Based on feedback we received on the existing timezone implementation, Start and End properties for Event entities will now be a complex type of:

 {
  DateTime
  Timezone
}

Timezone is mandatory for all create requests. It is also mandatory for update requests where start and end times are changed.

Example:

 "Start": {
  DateTime: "2015-09-25T16:00:00",
  TimeZone: "UTC"
}

Properties StartTimezone and EndTimezone will be removed from the Event entity and properties OriginalStartTimezone and OriginalEndTimezone will be added to the Event entity. OriginalStartTimezone and OriginalEndTimezone are meant to reflect what timezone was set when the event was created or updated.

In addition to this, a new preference header outlook.timezone will be supported for all GET requests. This header can be used to get the events in a timezone that is different from the one it was created in.

Example:

 Prefer: outlook.timezone = "Pacific Standard Time" 

Since a new type DateTime is being introduced, all "times" that are in any event related API will support the new DateTime format.

Examples:

Sort

 .../api/beta/me/Events?$orderby=Start/DateTime 

Filter

 //With outlook.timezone header as PST, time will be taken as PST 
.../api/beta/me/Events?$filter=Start/DateTime eq '2015-09-25T09:00:00'

//With no outlook.timezone header, time will be assumed as UTC
.../api/beta/me/Events?$filter=Start/DateTime eq '2015-09-25T16:00:00'

CalendarView/Instances

 .../api/beta/me/CalendarView?startDateTime=2015-09-25T16:00:00&endDateTime=2015-09-25T17:00:20
.../api/beta/me/CalendarView?startDateTime=2015-09-25T16:00:00-08:00&endDateTime=2015-09-25T17:00:20-08:00

Photos

We are renaming the UserPhoto property on User, GroupPhoto property on Group and ContactPhoto property on Contact to just Photo.

More extensive documentation on the new functionality is coming soon in our API reference documentation page. Please let us know if you have any questions, and visit http://dev.outlook.com for the latest news and updates.

Thanks,

Shreedevi

Outlook REST API changes to beta endpoint - Part III

0
0

Today we bring you a guest post from Abdelkader Bahgat, a Senior Program Manager with the Outlook team. Enjoy!

I wanted to update you all on some more breaking changes that we are making to the Outlook REST API beta endpoint. These changes impact Notifications and Webhooks. They are going to be deployed worldwide in phases over the next few weeks.

Since this deployment is going in phases, you may see up to two breaking changes for some of the APIs. In this blog, I’ll provide the final state of every change as well as its corresponding interim state (if applicable) during the phased rollout.

There are two type of changes; schema changes and functional changes. Refer to the notification reference documentation for the current schema and functional behavior. Below are the details of each one.

Schema changes

Schema changes apply to both subscription requests and notification payloads as follows. Also they apply to both https://outlook.office.com/api/beta and https://outlook.office365.com/api/beta endpoints.

Subscription request

The following subscription properties were updated as part of the breaking change. The table below shows the current property name, interim name and final name.

CurrentInterimFinal
ResourceURLresourceResource
CallbackURLnotificationURLNotificationURL
ClientStatecontextClientState
ExpirationTimesubscriptionExpirationDateTimeSubscriptionExpirationDateTime
ChangeTypechangeTypeChangeType

Subscription sample

Final version (changes highlighted)

 {
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/me/folders('Inbox')/messages",
  NotificationURL: "https://webhook.azurewebsites.net/api/send/rest_notify",
  ChangeType: "Created, Updated, Deleted",
  SubscriptionExpirationDateTime: "2015-10-24T18:40:00.0Z",
  ClientState: "Client information"
}

Interim version (changes highlighted)

 {   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  resource: "https://outlook.office.com/api/beta/me/folders('Inbox')/messages",
  notificationURL: "https://webhook.azurewebsites.net/api/send/rest_notify",
  changeType: "Created, Updated, Deleted",
  subscriptionExpirationDateTime: "2015-10-24T18:40:00.0Z",
  context: "Client information"
}

Notification payload

The following property was added to the notification body.

InterimFinal
resourceResource

The following notification properties were updated as part of the breaking change. The table below shows the current property name, interim name and final name.

Header

Current nameInterim nameFinal name
x-ClientStatex-contextClientState

Body

Current nameInterim nameFinal name
EntityresourceDataResourceData
SubscriptionExpirationTimesubscriptionExpirationDateTimeSubscriptionExpirationDateTime
SubscriptionId*subscriptionIdSubscriptionId
SequenceNumber*sequenceNumberSequenceNumber
ChangeType*changeTypeChangeType

* indicates lowerCamelCase type change in the interim version

Notification sample

Final version (changes highlighted)

ClientState: Client information
OData-Version: 4.0

{
  "value": [
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "Y3BENzI2MEMtODNDOS00OTgwLUI4MzYtRkU0RkJFQ0QwNDA0XzI0MjlFMDM3LTIyODAtNDI5QS05RTI5LTQ2ODJEMjUxNDFENg==",
      "SubscriptionExpirationDateTime": "2015-10-24T18:40:00Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Message",
        "@odata.id": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
        "@odata.etag": "W/\"CQAAABYAAADEtR7gR4I6QrDE5OwdwwziAAAAAAT1\"",
        "Id": "AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA=="
      }
    }
  ]
}

Interim version (changes highlighted)

x-context: Client information
OData-Version: 4.0

{
  "value": [
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "subscriptionId": "Y3BENzI2MEMtODNDOS00OTgwLUI4MzYtRkU0RkJFQ0QwNDA0XzI0MjlFMDM3LTIyODAtNDI5QS05RTI5LTQ2ODJEMjUxNDFENg==",
      "subscriptionExpirationDateTime": "2015-10-24T18:40:00Z",
      "sequenceNumber": 1,
      "changeType": "Created",
      "resource": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
      "resourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Message",
        "@odata.id": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
        "@odata.etag": "W/\"CQAAABYAAADEtR7gR4I6QrDE5OwdwwziAAAAAAT1\"",
        "Id": "AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA=="
      }
    }
  ]
}

Functional changes

There are four breaking functional changes in Beta. These changes are:

  1. Changes in Renew subscription API
  2. Addition of Notification URL validation
  3. Retiring Acknowledgement notification
  4. No ClientState in Subscription query response

Not all changes apply to the interim. Here is the functional change applicability matrix (final versus interim):

Functional changeInterimFinal
Changes in Renew subscription APIYesYes
Addition of Notification URL validationNoYes
Retiring Acknowledgement notificationNoYes
No ClientState in Subscription query responseYesYes

Changes in Renew subscription API

The renew subscription mechanism changed from POST to PATCH with payload like the following.

Final version

 {
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  SubscriptionExpirationDateTime: "2015-10-24T20:00:00.0Z"
}

Interim version

 {
    @odata.type:"#Microsoft.OutlookServices.PushSubscription",
    subscriptionExpirationDateTime: "2015-10-24T20:00:00.0Z"
}

Addition of Notification URL validation

Outlook REST APIs added validation for notification (callback) URL as part of creating a new subscription. Validation occurs as follows:

  1. Outlook service post the following to webhook service:

     POST https://<notificationUrl>?validationtoken=<TokenDefinedByService>

    ClientState: <Data sent in ClientState value in subscription request (if any)>
  2. Webhooks service must provide a 200 response with the validationtoken value in its body as type plain/text within 5 seconds. The validation token is a random string that should be discarded by the webhook after providing it in the response.

Retiring Acknowledgement notification

The notification URL validation process is replacing the acknowledgement notification.

No ClientState in Subscription query response

The ClientState (or context in interim state) property is not going to be sent back when a client queries for a specific subscription.

More extensive documentation on the new functionality is coming soon in our API reference documentation page. Please let us know if you have any questions, and visit http://dev.outlook.com for the latest news and updates.

Outlook REST API changes to beta endpoint - Part IV

0
0

I wanted to give an update on some more breaking changes that we are making to the Outlook REST API beta endpoint. These changes will be widely deployed over the next few weeks.

Scope of collections

We are making it consistent across the Outlook REST APIs to return all items of a given type from its top level collections. For example ../me/messages already returns all the messages of the user across all his mail folders, not just Inbox.

Similarly, we are making a change to the ../contacts, ../contactfolders and ../mailfolders endpoint.

  1. /Contacts endpoint will start returning all the contacts in the signed-in user’s mailbox. Prior to this change you would only see contacts from the default contacts folder of the user.
  2. /ContactFolders will return all ContactFolders in the signed-in user’s mailbox, irrespective of how deeply they are nested.
  3. /MailFolders will also start returning all MailFolders in the signed-in user’s mailbox. Prior to this change /MailFolders would return folders only from the root folder of the user.

Change to recurrence range

In the RecurrenceRange complex type (which is used in recurring meetings), we are changing the type for the StartDate and EndDate properties from DateTime to Date. There is also a new property in the Recurrence complex type, RecurrenceTimeZone, which reflects the timezone for StartDate and EndDate properties.

Old Recurrence

Recurrence: { 
Pattern: {
Type: "Daily",
Interval: 1,
Month: 0,
DayOfMonth:0,
FirstDayOfWeek: "Sunday",
Index: "First"
},
Range: {
Type: "EndDate",
StartDate: "2015-11-09T00:00:00Z",
EndDate: "2015-12-09T00:00:00Z",
NumberOfOccurrences: 0
}
}

New Recurrence

Recurrence: { 
Pattern: {
Type: "Daily",
Interval: 1,
Month: 0,
DayOfMonth:0,
FirstDayOfWeek: "Sunday",
Index: "First"
},
RecurrenceTimeZone: “Pacific Standard Time”,
Range: {
Type: "EndDate",
StartDate: "2015-11-09",
EndDate: "2015-12-09",
NumberOfOccurrences: 0
}
}

More extensive documentation on the new functionality is coming soon in our API reference documentation page. Please let us know if you have any questions, and visit http://dev.outlook.com for the latest news and updates.


Viewing all 108 articles
Browse latest View live




Latest Images