diff --git a/examples/sensitivity_label.pl b/examples/sensitivity_label.pl new file mode 100644 index 00000000..77894316 --- /dev/null +++ b/examples/sensitivity_label.pl @@ -0,0 +1,142 @@ +#!/usr/bin/perl + +############################################################################## +# +# An example of adding a Sensitivity Label to a Excel::Writer::XLSX workbook +# via document properties. +# +# Copyright 2000-2024, John McNamara, jmcnamara@cpan.org +# +# SPDX-License-Identifier: Artistic-1.0-Perl OR GPL-1.0-or-later +# + +# Sensitivity Labels are a property that can be added to an Office 365 +# document to indicate that it is compliant with a company's information +# protection policies. Sensitivity Labels have designations like +# "Confidential", "Internal use only", or "Public" depending on the policies +# implemented by the company. They are generally only enabled for enterprise +# versions of Office. +# +# See the following Microsoft documentation on how to [Apply sensitivity +# labels to your files and +# email](https://support.microsoft.com/en-us/office/apply-sensitivity-labels-to-your-files-and-email-2f96e7cd-d5a4-403b-8bd7-4cc636bae0f9). +# +# Sensitivity Labels are generally stored as custom document properties so +# they can be enabled using the Excel::Writer::XLSX `set_custom_property()` +# Workbook method. However, since the metadata differs from company to company +# you will need to extract some of the required metadata from sample files. +# +# The first step is to create a new file in Excel and set a non-encrypted +# sensitivity label. Then unzip the file by changing the extension from +# `.xlsx` to `.zip` or by using a command line utility like this: +# +# ```bash +# $ unzip myfile.xlsx -d myfile +# Archive: myfile.xlsx +# inflating: myfile/[Content_Types].xml +# inflating: myfile/docProps/app.xml +# inflating: myfile/docProps/custom.xml +# inflating: myfile/docProps/core.xml +# inflating: myfile/_rels/.rels +# inflating: myfile/xl/workbook.xml +# inflating: myfile/xl/worksheets/sheet1.xml +# inflating: myfile/xl/styles.xml +# inflating: myfile/xl/theme/theme1.xml +# inflating: myfile/xl/_rels/workbook.xml.rels +# ``` +# +# Then examine the `docProps/custom.xml` file from the unzipped xlsx file. The +# file doesn't contain newlines so it is best to view it in an editor that can +# handle XML or use a commandline utility like libxml’s [xmllint] to format +# the XML for clarity: +# +# [xmllint]: https://gnome.pages.gitlab.gnome.org/libxml2/xmllint.html +# +# ```xml +# $ xmllint --format myfile/docProps/custom.xml +# +# +# +# true +# +# +# 2024-01-01T12:00:00Z +# +# +# Privileged +# +# +# Confidential +# +# +# cb46c030-1825-4e81-a295-151c039dbf02 +# +# +# 88124cf5-1340-457d-90e1-0000a9427c99 +# +# +# 2 +# +# +# ``` +# +# The MSIP (Microsoft Information Protection) labels in the `name` attributes +# contain a GUID that is unique to each company. The "SiteId" field will also +# be unique to your company/location. The meaning of each of these fields is +# explained in the the following Microsoft document on [Microsoft Information +# Protection SDK - +# Metadata](https://learn.microsoft.com/en-us/information-protection/develop/concept-mip-metadata). +# +# Note, some sensitivity labels require that the document is encrypted. In +# order to extract the required metadata you will need to unencrypt the file +# which may remove the sensitivity label. In that case you may need to use a +# third party tool such as [msoffice-crypt]. +# +# [msoffice-crypt]: https://github.com/herumi/msoffice +# +# +# Once you have identified the necessary metadata you can add it to a new +# docuemnt as shown below. +# + +use strict; +use warnings; +use Excel::Writer::XLSX; + +my $workbook = Excel::Writer::XLSX->new( 'sensitivity_label.xlsx' ); +my $worksheet = $workbook->add_worksheet(); + +# Metadata extracted from a company specific file. +my $company_guid = "2096f6a2-d2f7-48be-b329-b73aaa526e5d"; +my $site_id = "cb46c030-1825-4e81-a295-151c039dbf02"; +my $action_id = "88124cf5-1340-457d-90e1-0000a9427c99"; + +# Add the document properties. Note that these should all be in text format. +$workbook->set_custom_property("MSIP_Label_${company_guid}_Enabled", 'true', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_SetDate", '2024-01-01T12:00:00Z', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_Method", 'Privileged', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_Name", 'Confidential', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_SiteId", $site_id, 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_ActionId", $action_id, 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_ContentBits", '2', 'text'); + + +$workbook->close(); + +__END__ diff --git a/sensitivity_label.xlsx b/sensitivity_label.xlsx new file mode 100644 index 00000000..a034a3b3 Binary files /dev/null and b/sensitivity_label.xlsx differ diff --git a/t/regression/properties06.t b/t/regression/properties06.t new file mode 100644 index 00000000..a97f4012 --- /dev/null +++ b/t/regression/properties06.t @@ -0,0 +1,80 @@ +############################################################################### +# +# Tests the output of Excel::Writer::XLSX against Excel generated files. +# +# Copyright 2000-2024, John McNamara, jmcnamara@cpan.org +# +# SPDX-License-Identifier: Artistic-1.0-Perl OR GPL-1.0-or-later +# + +use lib 't/lib'; +use TestFunctions qw(_compare_xlsx_files _is_deep_diff); +use strict; +use warnings; + +use Test::More tests => 1; + +############################################################################### +# +# Tests setup. +# +my $filename = 'properties06.xlsx'; +my $dir = 't/regression/'; +my $got_filename = $dir . "ewx_$filename"; +my $exp_filename = $dir . 'xlsx_files/' . $filename; + +my $ignore_members = []; +my $ignore_elements = {}; + + +############################################################################### +# +# Test the creation of a simple Excel::Writer::XLSX file. +# +use Excel::Writer::XLSX; + +my $workbook = Excel::Writer::XLSX->new( $got_filename ); +my $worksheet = $workbook->add_worksheet(); + +my $company_guid = "2096f6a2-d2f7-48be-b329-b73aaa526e5d"; +my $site_id = "cb46c030-1825-4e81-a295-151c039dbf02"; +my $action_id = "88124cf5-1340-457d-90e1-0000a9427c99"; + + +$workbook->set_custom_property("MSIP_Label_${company_guid}_Enabled", 'true', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_SetDate", '2024-01-01T12:00:00Z', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_Method", 'Privileged', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_Name", 'Confidential', 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_SiteId", $site_id, 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_ActionId", $action_id, 'text'); +$workbook->set_custom_property("MSIP_Label_${company_guid}_ContentBits", '2', 'text'); + +$workbook->close(); + + +############################################################################### +# +# Compare the generated and existing Excel files. +# + +my ( $got, $expected, $caption ) = _compare_xlsx_files( + + $got_filename, + $exp_filename, + $ignore_members, + $ignore_elements, +); + +_is_deep_diff( $got, $expected, $caption ); + + +############################################################################### +# +# Cleanup. +# +unlink $got_filename; + +__END__ + + + diff --git a/t/regression/xlsx_files/properties06.xlsx b/t/regression/xlsx_files/properties06.xlsx new file mode 100644 index 00000000..c36a7c9e Binary files /dev/null and b/t/regression/xlsx_files/properties06.xlsx differ