Introducing Metadata-Driven Retention

Apply metadata-based policies to meet business, legal and regulatory mandates around data retention.

Retention policies in Box can now be enabled for files with specific metadata templates or values.

Across different industries, legal and regulatory mandates require businesses to retain certain types of data for a specific period of time and dispose of that data in a certain way. FINRA and SEC17a-4, for example, require financial services firms to retain how their broker-dealer records are stored, maintained and deleted — and can result in hefty fines if organizations do not follow these mandates. Our Box Governance offering helps business easily meet these legal, regulatory and business policies for accessing, retaining and disposing their information with an easy-to-use solution.

Box Governance allows customers to configure automated policies, known as retention policies, to control the preservation and deletion schedules of their enterprise documents. Retention policies enable business to maintain certain types of content in Box for a specific period of time and to remove content from Box that is no longer relevant or in use after a specific period.

Today, we’re excited to introduce a new way for customers to manage their regulated data in the cloud with an expansion of our Box Governance offering to support metadata-driven retention polices, where retention policies can be applied to individual files based on custom metadata. This also enables customers to configure retention policies at the file level in addition to at the global and folder levels. In addition to bringing these new, expanded Box Governance capabilities to Box Admins via the Box Admin Console, we’re also making these capabilities available via the Box APIs and in our Java, Node, and .NET SDKs.

For example, let’s say a financial services firm offers a client portal where clients can access their financial documents and each client has their own set of folders in Box. Each client may have different types of insurance policies depending on their account and each policy is subject to a different retention schedule according to industry regulation. Using the new metadata-driven retention functionality, the firm can configure retention policies based on the type of insurance policy, rather than based on the file’s location in Box, which allows them to continue supporting a client-based folder structure while properly retaining the files and meeting industry regulatory requirements. The firm could assign a retention policy for any files where the metadata template “insurance policy type” exists or assign different retention policies for different types of insurance policies based on the specific type of insurance policy the client has, such as policy_type = auto or policy_type = home.

When using the API, you’d leverage the Retention Policy Assignment endpoint, which allows you to assign a retention policy object to an object in Box (like a file or folder). To do this, you’d set the assign_to parameter to assign the retention policy to a specific metadata template using the metadata template’s id. If the assign_to type is metadata_template, you can also add filter_fields allow you to configure retention policies based on specific metadata values in the template by providing the exact field and values required for that policy. Once the policy has started, any files that already have the specified metadata templates and/or key-value pairs will be retained per that policy.

Here’s an example of how to create a retention policy assignment based on a metadata template using cURL:

curl https://api.box.com/2.0/retention_policy_assignments \
-H “Authorization: Bearer ACCESS_TOKEN” \
-d ‘{“policy_id”: “32131”, “assign_to”: {“type”: “metadata_template”, “id”: “dbab3bd1–93ab-43d9-a31c-9b540b0a72ff”}}’ \
-X POST

If you wanted to create a retention policy assignment based on a specific metadata value in a template, you’d simply add filter_fields and specific which values you’d like to assign the policy for. Here’s how you’d accomplish using cURL:

curl https://api.box.com/2.0/retention_policy_assignments \
-H “Authorization: Bearer ACCESS_TOKEN” \
-d ‘{“policy_id”: “32131”, “assign_to”: {“type”: “metadata_template”, “id”: “dbab3bd1–93ab-43d9-a31c-9b540b0a72ff”}, “filter_fields”: { “field”: “c0753131-b592–4590–9c2d-ba67145fb784”, “value”: “fe6b46fd-a7e9–427f-b3d0-a0be0921372e”}}’ \
-X POST

Admins and Co-Admins who have the permission to manage policies can create any type of retention policy, including a metadata-driven retention policy. There are no special permissions required specifically for metadata-driven retention policies, as this is simply an addition to our existing retention capabilities. These policies can be created and assigned using the Box Admin Console or via the Box APIs. We have also added support for these new capabilities to our Node, Java and .NET SDKs.

The new metadata-driven retention functionality is available to any customer with Box Governance. If you are a Box Governance customer, you can dive deep into this new capability in our developer documentation. If you have any questions about using retention policies API or anything else, feel free to post in the Box Developer Forum or reach out to us on Twitter. If you don’t have a Box Developer account, you can create one here.

We can’t wait to see what you build!