PowerPoint.SensitivityLabel class

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

Gets the current label information that exists on the presentation for the user. If there's no sensitivity label on the current presentation, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.

getCurrentOrNullObject(): PowerPoint.SensitivityLabelDetails;

Returns

The current SensitivityLabelDetails 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) => {
  // Get the sensitivity label currently applied to the presentation.
  const presentation: PowerPoint.Presentation = context.presentation;
  const presentationLabel: PowerPoint.SensitivityLabel = presentation.sensitivityLabel;

  const currentLabel: PowerPoint.SensitivityLabelDetails = presentationLabel.getCurrentOrNullObject();
  // Load the properties of the label currently applied to the presentation.
  currentLabel.load(
    "color,id,isAbacAttributesRequired,isAbacEnabled,isEnabled,name,order,protectionType,siteId,tooltip"
  );
  await context.sync();

  if (currentLabel.isNullObject) {
    console.log("The presentation doesn't have a sensitivity label.");
    return;
  }

  // Get ABAC values when enabled for the label.
  let abacAttributeValues: PowerPoint.SensitivityLabelAbacAttributeValue[] = [];
  if (currentLabel.isAbacEnabled) {
    currentLabel.load("abacAttributeValues");
    await context.sync();

    abacAttributeValues = currentLabel.abacAttributeValues;
  }

  // Display the loaded properties of the current label.
  const attributeValues = abacAttributeValues.length
    ? abacAttributeValues
        .map(
          (attributeValue: PowerPoint.SensitivityLabelAbacAttributeValue) =>
            `${attributeValue.displayName} (ID: ${attributeValue.id}, order: ${attributeValue.displayOrder}, active: ${attributeValue.isActive ? "Yes" : "No"})`
        )
        .join(", ")
    : "None";

  let protectionDescription: string;
  switch (currentLabel.protectionType) {
    case PowerPoint.SensitivityLabelProtectionType.adminDefined:
      protectionDescription = "Defined by an administrator";
      break;
    case PowerPoint.SensitivityLabelProtectionType.userDefined:
      protectionDescription = "Defined by the user";
      break;
    case PowerPoint.SensitivityLabelProtectionType.noProtection:
      protectionDescription = "No protection";
      break;
    default:
      protectionDescription = `Unknown (${currentLabel.protectionType})`;
      break;
  }

  console.log(
    `Current presentation 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}`
  );
});

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.SensitivityLabel object is an API object, the toJSON method returns a plain JavaScript object (typed as PowerPoint.Interfaces.SensitivityLabelData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): {
            [key: string]: string;
        };

Returns

Tries to update to the provided sensitivity label on the presentation for the user. For ABAC-enabled labels, pass the desired attribute selections via options.abacAttributes.

tryToUpdate(labelId: string, options?: PowerPoint.SensitivityLabelTryUpdateOptions): OfficeExtension.ClientResult<PowerPoint.SensitivityLabelUpdateResult>;

Parameters

Returns

The SensitivityLabelUpdateResult 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) => {
  // Apply the selected sensitivity label to the presentation.
  const labelId = (document.getElementById("label-id") as HTMLSelectElement).value;
  if (!labelId) {
    console.warn("Get the available labels, and then select a label to apply.");
    return;
  }

  const presentation: PowerPoint.Presentation = context.presentation;
  const presentationLabel: PowerPoint.SensitivityLabel = presentation.sensitivityLabel;

  const updateResult: OfficeExtension.ClientResult<PowerPoint.SensitivityLabelUpdateResult> =
    presentationLabel.tryToUpdate(labelId);
  await context.sync();

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