Excel.SensitivityLabel class
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.
Represents the sensitivity label on the workbook.
- Extends
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
Methods
| get |
Gets the current label information that exists on the workbook for the user. If there's no sensitivity label on the current workbook, an object with an |
| toJSON() | Overrides the JavaScript |
| try |
Tries to update to the provided sensitivity label on the workbook for the user. For ABAC-enabled labels, pass the desired attribute selections via |
Property Details
context
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.
The request context associated with the object. This connects the add-in's process to the Office host application's process.
context: RequestContext;
Property Value
Method Details
getCurrentOrNullObject()
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 the current label information that exists on the workbook for the user. If there's no sensitivity label on the current workbook, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.
getCurrentOrNullObject(): Excel.SensitivityLabelDetails;
Returns
The current SensitivityLabelDetails object.
Remarks
API set: ExcelApi BETA (PREVIEW ONLY)
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/98-preview-apis/manage-sensitivity-labels.yaml
// Get the sensitivity label currently applied to the workbook.
await Excel.run(async (context) => {
const workbook: Excel.Workbook = context.workbook;
const workbookLabel: Excel.SensitivityLabel = workbook.sensitivityLabel;
const currentLabel: Excel.SensitivityLabelDetails = workbookLabel.getCurrentOrNullObject();
currentLabel.load(
"color,id,isAbacAttributesRequired,isAbacEnabled,isEnabled,name,order,protectionType,siteId,tooltip"
);
await context.sync();
if (currentLabel.isNullObject) {
console.log("The workbook doesn't have a sensitivity label.");
return;
}
// Get ABAC values only when enabled for the label.
let abacAttributeValues: Excel.SensitivityLabelAbacAttributeValue[] = [];
if (currentLabel.isAbacEnabled) {
currentLabel.load("abacAttributeValues");
await context.sync();
abacAttributeValues = currentLabel.abacAttributeValues;
}
const attributeValues = abacAttributeValues.length
? abacAttributeValues
.map((attributeValue: Excel.SensitivityLabelAbacAttributeValue) =>
`${attributeValue.displayName} (ID: ${attributeValue.id}, ` +
`order: ${attributeValue.displayOrder}, active: ${attributeValue.isActive ? "Yes" : "No"})`)
.join(", ")
: "None";
let protectionDescription: string;
switch (currentLabel.protectionType) {
case Excel.SensitivityLabelProtectionType.adminDefined:
protectionDescription = "Defined by an administrator";
break;
case Excel.SensitivityLabelProtectionType.userDefined:
protectionDescription = "Defined by the user";
break;
case Excel.SensitivityLabelProtectionType.noProtection:
protectionDescription = "No protection";
break;
default:
protectionDescription = `Unknown (${currentLabel.protectionType})`;
break;
}
console.log(
`Current workbook sensitivity label:\n\n${currentLabel.name}\n` +
` ID: ${currentLabel.id}\n` +
` Site ID: ${currentLabel.siteId}\n` +
` Tooltip: ${currentLabel.tooltip}\n` +
` Color: ${currentLabel.color}\n` +
` Enabled: ${currentLabel.isEnabled ? "Yes" : "No"}\n` +
` Display order: ${currentLabel.order}\n` +
` ABAC enabled: ${currentLabel.isAbacEnabled ? "Yes" : "No"}\n` +
` ABAC attributes required: ${currentLabel.isAbacAttributesRequired ? "Yes" : "No"}\n` +
` ABAC attribute values: ${attributeValues}\n` +
` Protection type: ${protectionDescription}`
);
});
toJSON()
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.
Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Excel.SensitivityLabel object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.SensitivityLabelData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): {
[key: string]: string;
};
Returns
{ [key: string]: string; }
tryToUpdate(labelId, options)
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.
Tries to update to the provided sensitivity label on the workbook for the user. For ABAC-enabled labels, pass the desired attribute selections via options.abacAttributes.
tryToUpdate(labelId: string, options?: Excel.SensitivityLabelTryUpdateOptions): OfficeExtension.ClientResult<Excel.SensitivityLabelUpdateResult>;
Parameters
- labelId
-
string
The ID of the label to apply.
Optional. Additional inputs that influence the update, such as ABAC attribute selections for ABAC-enabled labels.
Returns
The SensitivityLabelUpdateResult object.
Remarks
API set: ExcelApi BETA (PREVIEW ONLY)
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 to the entire workbook.
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 workbook: Excel.Workbook = context.workbook;
const workbookLabel: Excel.SensitivityLabel = workbook.sensitivityLabel;
const updateResult: OfficeExtension.ClientResult<Excel.SensitivityLabelUpdateResult> =
workbookLabel.tryToUpdate(labelId);
await context.sync();
if (updateResult.value.status === Excel.SensitivityLabelUpdateStatus.success) {
console.log("Applied the sensitivity label to the workbook.");
} else {
console.error(`The sensitivity label wasn't applied. Status: ${updateResult.value.status}`);
}
});