IPWorks Cloud 2020 ActiveX Edition

Questions / Feedback?

ListMetadata Method

Lists the metadata items for a resource.

Syntax

boxcontrol.ListMetadata ResourceId, Scope, Schema

Remarks

This method lists the metadata items for the resource specified by ResourceId. If Scope and Schema are both empty, metadata items from all metadata containers associated with the resource are returned. Otherwise, only the items in the container specified by Scope and Schema are returned.

When non-empty, Scope and Schema must either be global and properties (respectively); or enterprise_<EnterpriseId> and the name of an existing metadata container within that scope on the specified resource.

Calling this method will fire the MetadataList event once for each metadata item, and will populate the Metadata* properties (clearing any previously-held items in the process).

Metadata Notes

Box's Metadata architecture consists of two entities: metadata items, and metadata containers (which Box calls "metadata templates").

A metadata item is just a name-value pair held by a metadata container. Its name may be up to 256 characters long, cannot begin with the $ character, and must be unique within the container.

A metadata container holds metadata items, and is associated with a single resource. All metadata containers must be created using a metadata container schema, which describes the possible metadata items the container may hold. Containers are uniquely identified (per-resource) by a schema path like /Scope/Schema (ergo, a resource cannot have multiple containers of the same schema).

Box provides a general-use schema, /global/properties, that functions as an unrestricted key-value store that will accept any metadata item. Enterprises can also create custom schemas, /enterprise_<EnterpriseId>/Schema, that only allow predefined metadata items (with specific data types) to be added.

See the following methods for more information: CreateMetadata, ListMetadata, UpdateMetadata, and DeleteMetadata.

Note that metadata is only usable on resources owned by paid Box accounts.

string resId = "f:09876";

// Create an instance of the default metadata container ("/global/properties") with a couple of metadata 
// items in it, and associate it with the specified resource. (Note that we're assuming that the given
// resource doesn't already have an instance of the default metadata container associated with it.)
box.Metadata.Add(new BoxMetadata() { Name = "num1", Value = "123", ModOp = BoxMetadataModOps.opAdd });
box.Metadata.Add(new BoxMetadata() { Name = "text1", Value = "abc", ModOp = BoxMetadataModOps.opAdd });

// All of the control's metadata-related methods all empty string to be passed to their Scope and Schema
// parameters, in which case "global" and "properties" will be used, respectively. (The exception is the
// ListMetadata() method, which interprets empty Scope and Schema values in a different way; refer to the
// ListMetadata() documentation for more information.)
box.CreateMetadata(resId, "", "");

// Some time later, imagine you wish to update the metadata items held by the default container on that
// resource. Always call ListMetadata() first so that control has the latest metadata loaded.
box.ListMetadata(resId, "global", "properties");

// Now that the control has the latest metadata items loaded for the default container on the given
// resource, we can modify what we wish to, setting the ModOp fields appropriately.
box.Metadata[0].Value = "456"; // Update the value of the "num1" item.
box.Metadata[0].ModOp = BoxMetadataModOps.opReplace;
box.Metadata[1].ModOp = BoxMetadataModOps.opRemove; // Remove the "text1" item.
// Add a new "text2" item.
box.Metadata.Add(new BoxMetadata() { Name = "text2", Value = "def", ModOp = BoxMetadataModOps.opAdd });

// Now commit the updates. Our example performs very simple updates, but you can build a very complex
// update scenario using some of the other ModOp values. Refer to the UpdateMetadata() documentation
// for more information.
box.UpdateMetadata(resId, "", "");

// Finally, this will remove the entire default metadata container from the given resource.
box.DeleteMetadata(resId, "", "");

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Cloud 2020 ActiveX Edition - Version 20.0 [Build 8265]