Edit

Manage sensitivity labels in Office Add-ins

Workplace collaboration often extends beyond an organization to external partners. Sharing information outside an organization's network requires measures to prevent data loss and enforce compliance policies. Microsoft Purview Information Protection provides solutions for classifying and protecting sensitive information. Sensitivity labels apply this protection to data in Excel, Outlook, PowerPoint, and Word.

Use the Office JavaScript API to implement sensitivity label solutions in your Office Add-in projects and support the following scenarios.

  • Apply sensitivity labels to documents, messages, or appointments to comply with business and legal policies.
  • Restrict additional actions if a certain sensitivity label is applied, such as preventing users from adding external recipients to a message.
  • Classify data based on its sensitivity label to support auditing and reporting.

Note

In Excel, PowerPoint, and Word, the sensitivity label APIs are in preview. In Outlook, support for the sensitivity label feature was introduced in requirement set 1.13. For information about client support, see Supported clients and platforms.

Prerequisites

The sensitivity label feature requires a Microsoft 365 E5 subscription. Check whether you qualify for a Microsoft 365 E5 developer subscription through the Microsoft 365 Developer Program in the program FAQ. Otherwise, start a 1-month free trial or purchase a Microsoft 365 plan.

Supported clients and platforms

Sensitivity label API support varies by Office application and platform. Outlook support requires Exchange Online. The following table lists supported combinations.

Application Web Windows Mac
Excel Preview Preview Preview
Outlook Supported Supported
(new and classic (Version 2304 (Build 16327.20248) or later))		 Supported
(Version 16.77 (23081600) or later)
PowerPoint Preview Preview Preview
Word Preview Preview Preview

Configure sensitivity label support

Note

Preview APIs are subject to change and aren't intended for use in a production environment. We recommend that you try them out in test and development environments only. Don't use preview APIs in a production environment or within business-critical documents.

To use preview APIs:

The Excel, PowerPoint, and Word sensitivity label APIs follow a similar programming pattern. In each host, the request context provides access to the sensitivity label catalog, while the host-specific file object provides methods to get or update its label.

The following table lists the API members used to access the sensitivity label catalog and the label applied to a file in each Office host application.

Application Sensitivity label catalog Sensitivity label on the file
Excel context.sensitivityLabelsCatalog context.workbook.sensitivityLabel
PowerPoint context.sensitivityLabelsCatalog context.presentation.sensitivityLabel
Word context.sensitivityLabelsCatalog context.document.sensitivityLabel

The examples in the following sections use Word. To use Excel or PowerPoint, substitute the corresponding host namespace and file-level sensitivity label object.

Verify sensitivity labeling is available

Sensitivity labels and policies are configured by an organization's administrator through the Microsoft Purview compliance portal. For guidance on how to configure sensitivity labels in your tenant, see Create and configure sensitivity labels and their policies.

To determine whether sensitivity labeling is available to the current user, load getLabelingCapability (Excel, PowerPoint, Word) from the sensitivity label catalog.

await Word.run(async (context) => {
    // Access the sensitivity label catalog for the current user.
    const labelCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available.");
        return;
    }

    // Load the labeling capability status before reading it.
    labelCatalog.load("getLabelingCapability");
    await context.sync();

    // Display whether sensitivity labeling is enabled and available.
    console.log(`Sensitivity labeling capability: ${labelCatalog.getLabelingCapability}`);
});

Identify available sensitivity labels

To retrieve the labels published to the current user, call getLabels() (Excel, PowerPoint, Word) on the catalog.

The method returns a collection whose items and properties aren't available until you explicitly load them and call context.sync(). For guidance, see Load from a collection. Load items and the label properties your add-in needs. Available properties differ by host. For a complete list, see SensitivityLabelDetails (Excel, PowerPoint, Word).

await Word.run(async (context) => {
    // Access the sensitivity label catalog for the current user.
    const labelCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available.");
        return;
    }

    // Get the available labels and load the properties used by the add-in.
    const availableLabels = labelCatalog.getLabels();
    availableLabels.load("items/id,items/name,items/isEnabled");
    await context.sync();

    // Display the available labels.
    console.log("Available sensitivity labels:");
    availableLabels.items.forEach((label) => {
        console.log(`${label.name} (${label.id}) - ${label.isEnabled ? "Enabled" : "Disabled"}`);
    });
});

Get the sensitivity label

To retrieve the current label, if one is applied, call getCurrentOrNullObject() (Excel, PowerPoint, Word) on the file's sensitivity label object.

await Word.run(async (context) => {
    // Access the sensitivity label applied to the current document.
    const documentLabel = context.document.sensitivityLabel;

    // Get the current label, if one is applied, and load its ID and name.
    const currentLabel = documentLabel.getCurrentOrNullObject();
    currentLabel.load("id,name");
    await context.sync();

    // Display the current label or report that the document isn't labeled.
    if (currentLabel.isNullObject) {
        console.log("The document doesn't have a sensitivity label.");
    } else {
        console.log(`Current label: ${currentLabel.name} (${currentLabel.id})`);
    }
});

Set the sensitivity label

Before applying a label, call getLabels() (Excel, PowerPoint, Word) and select an enabled label or sublabel from the returned collection. The tryToUpdate() method (Excel, PowerPoint, Word) requires the selected label's ID as its parameter. Calling getLabels() first lets you retrieve this required ID and verify that the label is available to the current user. Check the returned SensitivityLabelUpdateResult (Excel, PowerPoint, Word) value to determine whether the update succeeded.

Note

A parent label that has sublabels can't be applied directly. Select one of its enabled sublabels instead.

async function setDocumentSensitivityLabel(labelId: string) {
    await Word.run(async (context) => {
        // Access the sensitivity label applied to the current document.
        const documentLabel = context.document.sensitivityLabel;

        // Apply the selected label.
        const updateResult = documentLabel.tryToUpdate(labelId);
        await context.sync();

        // Check whether the label update succeeded.
        if (updateResult.value === Word.SensitivityLabelUpdateResult.success) {
            console.log("Applied the sensitivity label to the document.");
        } else {
            console.error(`The sensitivity label wasn't applied. Result: ${updateResult.value}`);
        }
    });
}

Detect sensitivity label changes with the OnSensitivityLabelChanged event

Note

The OnSensitivityLabelChanged event is only available in Outlook.

Use the OnSensitivityLabelChanged event to run add-in logic when the sensitivity label changes on a message or appointment. For example, prevent users from downgrading the label of a mail item that contains certain attachments.

The OnSensitivityLabelChanged event uses event-based activation. For configuration, debugging, and deployment guidance, see Activate add-ins with events.

See also

  • Last updated on