Office.Diagnostics interface

Package:

outlook

Provides diagnostic information to an Outlook add-in.

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Starting with Mailbox requirement set 1.5, you can also use the Office.context.diagnostics property to get similar information.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-diagnostic-information.yaml

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

Properties

ews	Gets an object to identify whether Exchange Web Services (EWS) callback tokens are supported in an organization.
hostName	Gets a string that represents the type of Outlook client. The string can be one of the following values: Outlook, newOutlookWindows, OutlookWebApp, OutlookIOS, or OutlookAndroid.
hostVersion	Gets a string that represents the version of either the Outlook client or the Exchange Server (for example, "15.0.468.0"). If the mail add-in is running in Outlook on Windows (classic), on Mac, or on mobile devices, the hostVersion property returns the version of the Outlook client. In Outlook on the web and new Outlook on Windows, the property returns the version of the Exchange Server.
OWAView	Gets a string that represents the current view of Outlook on the web. The returned string can be one of the following values: OneColumn, TwoColumns, or ThreeColumns. If the application is not Outlook on the web, then accessing this property results in undefined. Outlook on the web has three views that correspond to the width of the screen and the window, and the number of columns that can be displayed: OneColumn, which is displayed when the screen is narrow. Outlook on the web uses this single-column layout on the entire screen of a smartphone. TwoColumns, which is displayed when the screen is wider. Outlook on the web uses this view on most tablets. ThreeColumns, which is displayed when the screen is wide. For example, Outlook on the web uses this view in a full screen window on a desktop computer.

Property Details

ews

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Gets an object to identify whether Exchange Web Services (EWS) callback tokens are supported in an organization.

ews: Ews;

Property Value

Office.Ews

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

• The ews property is available for preview in Outlook on the web and on Windows (new and classic (Version 2510, Build 19328.20000 and later)).

• Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication (NAA). Exchange user identity tokens are still supported for Exchange on-premises. For more information, see Nested app authentication FAQ.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/99-preview-apis/get-token-status.yaml

Office.context.mailbox.diagnostics.ews.getTokenStatusAsync({ isRest: false }, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.log(result.error.message);
    return;
  }
  const status = result.value;
  switch (status) {
    case Office.MailboxEnums.TokenStatus.Enabled:
      console.log("EWS callback tokens are enabled.");
      break;
    case Office.MailboxEnums.TokenStatus.Disabled:
      console.log("EWS callback tokens are disabled.");
      break;
    case Office.MailboxEnums.TokenStatus.Removed:
      console.log(
        "The organization has an Exchange Online environment. Legacy Exchange tokens are no longer supported.",
      );
      break;
  }
});

hostName

Gets a string that represents the type of Outlook client.

The string can be one of the following values: Outlook, newOutlookWindows, OutlookWebApp, OutlookIOS, or OutlookAndroid.

hostName: string;

Property Value

string

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: The Outlook value is returned for Outlook on Windows (classic) and on Mac. newOutlookWindows is returned for new Outlook on Windows.

hostVersion

Gets a string that represents the version of either the Outlook client or the Exchange Server (for example, "15.0.468.0").

If the mail add-in is running in Outlook on Windows (classic), on Mac, or on mobile devices, the hostVersion property returns the version of the Outlook client. In Outlook on the web and new Outlook on Windows, the property returns the version of the Exchange Server.

hostVersion: string;

Property Value

string

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

OWAView

Gets a string that represents the current view of Outlook on the web.

The returned string can be one of the following values: OneColumn, TwoColumns, or ThreeColumns.

If the application is not Outlook on the web, then accessing this property results in undefined.

Outlook on the web has three views that correspond to the width of the screen and the window, and the number of columns that can be displayed:

• OneColumn, which is displayed when the screen is narrow. Outlook on the web uses this single-column layout on the entire screen of a smartphone.

• TwoColumns, which is displayed when the screen is wider. Outlook on the web uses this view on most tablets.

• ThreeColumns, which is displayed when the screen is wide. For example, Outlook on the web uses this view in a full screen window on a desktop computer.

OWAView: MailboxEnums.OWAView | "OneColumn" | "TwoColumns" | "ThreeColumns";

Property Value

Office.MailboxEnums.OWAView | "OneColumn" | "TwoColumns" | "ThreeColumns"

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read