Edit

Excel.SensitivityLabelTryUpdateOptions interface

Package:
excel

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.

Provides options for SensitivityLabel.tryToUpdate.

Remarks

API set: ExcelApi BETA (PREVIEW ONLY)

Used by

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/98-preview-apis/manage-sensitivity-labels.yaml

// Apply the selected sensitivity label with the chosen ABAC attribute values.
await Excel.run(async (context) => {
    const labelId = (document.getElementById("label-id") as HTMLSelectElement).value;
    if (!labelId) {
        console.warn("Get available labels and select a label first.");
        return;
    }

    const attributeControls = document.getElementById("abac-attributes")
        .querySelectorAll<HTMLSelectElement>("select");
    if (attributeControls.length === 0) {
        console.warn("Get catalog attributes and select attribute values first.");
        return;
    }

    const labelCatalog: Excel.SensitivityLabelsCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available in this version of Excel.");
        return;
    }

    labelCatalog.load("getLabelingCapabilities");
    await context.sync();
    if (labelCatalog.getLabelingCapabilities.indexOf(Excel.LabelingCapability.attributeBasedAccessControlEnabled) === -1) {
        console.warn("ABAC attributes aren't enabled or available for the current user.");
        return;
    }

    // Refresh the catalog to validate selections against the current policy.
    const catalogAttributes: OfficeExtension.ClientResult<Excel.SensitivityLabelAbacAttribute[]> =
        labelCatalog.getAttributes();
    await context.sync();

    const selectedAttributes: Excel.SensitivityLabelAbacAttribute[] = [];
    for (const select of Array.from(attributeControls)) {
        const selectedIds = Array.from(select.selectedOptions)
            .map((option) => option.value).filter((id) => id !== "");
        if (selectedIds.length === 0) {
            continue;
        }

        const attribute: Excel.SensitivityLabelAbacAttribute | undefined =
            catalogAttributes.value.find((attribute) => attribute.displayName === select.name);
        if (!attribute || !attribute.isActive || (!attribute.isMultiValued && selectedIds.length > 1)) {
            console.warn("The attribute selections are no longer valid. Get catalog attributes and select values again.");
            return;
        }

        const selectedValues: Excel.SensitivityLabelAbacAttributeValue[] =
            attribute.values.filter((value) => value.isActive && selectedIds.indexOf(value.id) !== -1);
        if (selectedValues.length !== selectedIds.length) {
            console.warn("The attribute selections are no longer valid. Get catalog attributes and select values again.");
            return;
        }

        const selectedAttribute: Excel.SensitivityLabelAbacAttribute = {
            ...attribute,
            values: selectedValues
        };
        selectedAttributes.push(selectedAttribute);
    }

    if (selectedAttributes.length === 0) {
        console.warn("Select at least one ABAC attribute value first.");
        return;
    }

    const options: Excel.SensitivityLabelTryUpdateOptions = {
        abacAttributes: selectedAttributes
    };
    const workbook: Excel.Workbook = context.workbook;
    const workbookLabel: Excel.SensitivityLabel = workbook.sensitivityLabel;
    const updateResult: OfficeExtension.ClientResult<Excel.SensitivityLabelUpdateResult> =
        workbookLabel.tryToUpdate(labelId, options);
    await context.sync();

    if (updateResult.value.status === Excel.SensitivityLabelUpdateStatus.success) {
        console.log("Applied the sensitivity label and ABAC attributes to the workbook.");
    } else {
        console.error(`The sensitivity label wasn't applied. Status: ${updateResult.value.status}`);
    }
});

Properties

abacAttributes

If provided, specifies the attribute-based access control (ABAC) attributes to apply with the label. Must be omitted or empty for labels that are not ABAC-enabled; otherwise the update result has a status of SensitivityLabelUpdateStatus.abacAttributesNotAllowed. Required when the target label is ABAC-enabled and SensitivityLabelDetails.isAbacAttributesRequired is true.

Property Details

abacAttributes

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.

If provided, specifies the attribute-based access control (ABAC) attributes to apply with the label. Must be omitted or empty for labels that are not ABAC-enabled; otherwise the update result has a status of SensitivityLabelUpdateStatus.abacAttributesNotAllowed. Required when the target label is ABAC-enabled and SensitivityLabelDetails.isAbacAttributesRequired is true.

abacAttributes?: Excel.SensitivityLabelAbacAttribute[];

Property Value

Excel.SensitivityLabelAbacAttribute[]

Remarks

API set: ExcelApi BETA (PREVIEW ONLY)