PowerPoint.SensitivityLabelsCatalog 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.
Provides methods to check the status of the catalog of sensitivity labels in PowerPoint and retrieve all available sensitivity labels if the catalog is enabled.
- Extends
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| get |
Gets the host capabilities for sensitivity labels in PowerPoint. |
| get |
Methods
| get |
Gets the attribute-based access control (ABAC) attributes that are available to the current user. |
| get |
Gets sensitivity labels that are available to the current user. |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| new |
Create a new instance of the |
| toJSON() | Overrides the JavaScript |
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
getLabelingCapabilities
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 host capabilities for sensitivity labels in PowerPoint.
readonly getLabelingCapabilities: PowerPoint.LabelingCapability[];
Property Value
Remarks
getLabelingCapability
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.
readonly getLabelingCapability: PowerPoint.LabelingCapability | "NoLicense" | "LabelingDisabled" | "LabelingPolicyNotFound" | "LabelingEnabled" | "AttributeBasedAccessControlEnabled";
Property Value
PowerPoint.LabelingCapability | "NoLicense" | "LabelingDisabled" | "LabelingPolicyNotFound" | "LabelingEnabled" | "AttributeBasedAccessControlEnabled"
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/preview-apis/manage-sensitivity-labels.yaml
await PowerPoint.run(async (context) => {
// Check whether sensitivity labeling is available for the current user.
const labelCatalog: PowerPoint.SensitivityLabelsCatalog = context.sensitivityLabelsCatalog;
if (!labelCatalog) {
console.warn("The sensitivity label catalog isn't available.");
return;
}
labelCatalog.load("getLabelingCapability");
await context.sync();
switch (labelCatalog.getLabelingCapability) {
case PowerPoint.LabelingCapability.labelingEnabled:
console.log("Sensitivity labeling is enabled.");
break;
case PowerPoint.LabelingCapability.labelingDisabled:
console.log("Sensitivity labeling is disabled.");
break;
case PowerPoint.LabelingCapability.labelingPolicyNotFound:
console.log("No sensitivity labeling policy was found.");
break;
case PowerPoint.LabelingCapability.noLicense:
console.log("The current user doesn't have a valid sensitivity labeling license.");
break;
default:
console.log(`Unknown labeling capability: ${labelCatalog.getLabelingCapability}`);
break;
}
});
Method Details
getAttributes()
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 attribute-based access control (ABAC) attributes that are available to the current user.
getAttributes(): OfficeExtension.ClientResult<PowerPoint.SensitivityLabelAbacAttribute[]>;
Returns
Remarks
API set: PowerPointApi BETA (PREVIEW ONLY)
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/preview-apis/manage-sensitivity-labels.yaml
// Get available ABAC attributes and describe the kind of value each attribute accepts.
const container = document.getElementById("abac-attributes");
while (container.firstChild) {
container.removeChild(container.firstChild);
}
await PowerPoint.run(async (context) => {
const labelCatalog: PowerPoint.SensitivityLabelsCatalog = context.sensitivityLabelsCatalog;
if (!labelCatalog) {
console.warn("The sensitivity label catalog isn't available.");
return;
}
labelCatalog.load("getLabelingCapabilities");
await context.sync();
const capabilities: PowerPoint.LabelingCapability[] = labelCatalog.getLabelingCapabilities;
if (capabilities.indexOf(PowerPoint.LabelingCapability.attributeBasedAccessControlEnabled) === -1) {
console.warn("ABAC attributes aren't enabled or available for the current user.");
return;
}
const catalogAttributes: OfficeExtension.ClientResult<PowerPoint.SensitivityLabelAbacAttribute[]> =
labelCatalog.getAttributes();
await context.sync();
if (catalogAttributes.value.length === 0) {
console.log("No ABAC attributes are available in the sensitivity label catalog.");
return;
}
console.log("Available ABAC attributes:");
catalogAttributes.value.forEach((attribute: PowerPoint.SensitivityLabelAbacAttribute) => {
let dataTypeDescription: string;
switch (attribute.dataType) {
case PowerPoint.SensitivityLabelAbacAttributeDataType.booleanValue:
dataTypeDescription = "Boolean";
break;
case PowerPoint.SensitivityLabelAbacAttributeDataType.dateValue:
dataTypeDescription = "Date";
break;
case PowerPoint.SensitivityLabelAbacAttributeDataType.numberValue:
dataTypeDescription = "Number";
break;
case PowerPoint.SensitivityLabelAbacAttributeDataType.stringValue:
dataTypeDescription = "String";
break;
case PowerPoint.SensitivityLabelAbacAttributeDataType.unknown:
dataTypeDescription = "Unknown";
break;
default:
dataTypeDescription = `Unrecognized (${attribute.dataType})`;
break;
}
console.log(`ABAC attribute: ${attribute.displayName}`, {
dataType: attribute.dataType,
dataTypeDescription,
displayOrder: attribute.displayOrder,
isActive: attribute.isActive,
isMultiValued: attribute.isMultiValued,
values: attribute.values.map((attributeValue: PowerPoint.SensitivityLabelAbacAttributeValue) => ({
displayName: attributeValue.displayName,
displayOrder: attributeValue.displayOrder,
id: attributeValue.id,
isActive: attributeValue.isActive
}))
});
});
addAttributeOptions(catalogAttributes.value);
});
getLabels()
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 sensitivity labels that are available to the current user.
getLabels(): PowerPoint.SensitivityLabelDetailsCollection;
Returns
The current object.
Remarks
API set: PowerPointApi BETA (PREVIEW ONLY)
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/preview-apis/manage-sensitivity-labels.yaml
await PowerPoint.run(async (context) => {
const labelSelect = document.getElementById("label-id") as HTMLSelectElement;
labelSelect.options.length = 0;
const placeholder = document.createElement("option");
placeholder.textContent = "Select a label";
placeholder.value = "";
labelSelect.add(placeholder);
// Get the sensitivity labels that the organization published for the current user.
const labelCatalog: PowerPoint.SensitivityLabelsCatalog = context.sensitivityLabelsCatalog;
if (!labelCatalog) {
console.warn("The sensitivity label catalog isn't available.");
return;
}
const availableLabels: PowerPoint.SensitivityLabelDetailsCollection = labelCatalog.getLabels();
// Load the properties and sublabels for every label in the catalog.
availableLabels.load(
"items/color,items/id,items/isAbacAttributesRequired,items/isAbacEnabled,items/isEnabled," +
"items/name,items/order,items/protectionType,items/siteId,items/tooltip," +
"items/children/items/id,items/children/items/name,items/children/items/isEnabled"
);
await context.sync();
if (availableLabels.items.length === 0) {
console.log("No sensitivity labels are available for the current user.");
return;
}
// Display the loaded properties for each available label.
console.log("Available sensitivity labels:");
availableLabels.items.forEach((labelDetails: PowerPoint.SensitivityLabelDetails) => {
const childLabels = labelDetails.children && labelDetails.children.items.length
? labelDetails.children.items
.map((childLabel: PowerPoint.SensitivityLabelDetails) => `${childLabel.name} (${childLabel.id})`)
.join(", ")
: "None";
console.log(
`\n${labelDetails.name}\n` +
` ID: ${labelDetails.id}\n` +
` Site ID: ${labelDetails.siteId}\n` +
` Tooltip: ${labelDetails.tooltip}\n` +
` Color: ${labelDetails.color}\n` +
` Enabled: ${labelDetails.isEnabled ? "Yes" : "No"}\n` +
` Display order: ${labelDetails.order}\n` +
` ABAC enabled: ${labelDetails.isAbacEnabled ? "Yes" : "No"}\n` +
` ABAC attributes required: ${labelDetails.isAbacAttributesRequired ? "Yes" : "No"}\n` +
` Sublabels: ${childLabels}\n` +
` Protection type: ${labelDetails.protectionType}`
);
});
addLabelOptions(availableLabels);
});
load(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.
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: PowerPoint.Interfaces.SensitivityLabelsCatalogLoadOptions): PowerPoint.SensitivityLabelsCatalog;
Parameters
Provides options for which properties of the object to load.
Returns
load(propertyNames)
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.
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames?: string | string[]): PowerPoint.SensitivityLabelsCatalog;
Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
load(propertyNamesAndPaths)
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.
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): PowerPoint.SensitivityLabelsCatalog;
Parameters
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
newObject(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.
Create a new instance of the PowerPoint.SensitivityLabelsCatalog object.
static newObject(context: OfficeExtension.ClientRequestContext): PowerPoint.SensitivityLabelsCatalog;
Parameters
Returns
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 PowerPoint.SensitivityLabelsCatalog object is an API object, the toJSON method returns a plain JavaScript object (typed as PowerPoint.Interfaces.SensitivityLabelsCatalogData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): PowerPoint.Interfaces.SensitivityLabelsCatalogData;