Skip to content

Latest commit

 

History

History
214 lines (163 loc) · 11 KB

metadata_template.md

File metadata and controls

214 lines (163 loc) · 11 KB

Metadata Templates

Metadata that belongs to a file is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields.

Create Metadata Template

The createMetadataTemplate(BoxAPIConnection api, String templateScope, String templateKey, String displayName, Boolean hidden, List<Field> fields) method will create a metadata template schema.

You can create custom metadata fields that will be associated with the metadata template.

MetadataTemplate.Field metadataField = new MetadataTemplate.Field();
metadataField.setType("string");
metadataField.setKey("text");
metadataField.setDisplayName("Text");

List<MetadataTemplate.Field> fields = new ArrayList<MetadataTemplate.Field>();
fields.add(metadataField);

MetadataTemplate template = MetadataTemplate.createMetadataTemplate(api, "enterprise", "CustomField", "Custom Field", false, fields);

final JsonObject jsonObject = new JsonObject();
jsonObject.add("text", "This is a test text");

Metadata metadata = new Metadata(jsonObject);
boxFile.createMetadata("CustomField", metadata);

Update Metadata Template

To update an existing metadata template, call the updateMetadataTemplate(BoxAPIConnection api, String scope, String template, List<FieldOperation> fieldOperations) method with the scope and key of the template, and the list of field operations to perform:

List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>();

String addCategoryFieldJSON = "{\"op\":\"addField\","\"data\":{"
    + "\"displayName\":\"Category\",\"key\":\"category\",\"hidden\":false,\"type\":\"string\"}}";
updates.add(new MetadataTemplate.FieldOperation(addCategoryFieldJSON));

String changeTemplateNameJSON = "{\"op\":\"editTemplate\",\"data\":{"
    + "\"displayName\":\"My Metadata\"}}";
updates.add(new MetadataTemplate.FieldOperation(changeTemplateNameJSON));

MetadataTemplate.updateMetadataTemplate(api, "enterprise", "myData", updates);

Get Metadata Template

Get by scope and template key

The getMetadataTemplate(BoxAPIConnection api) method will return information about default metadata schema. Also, getMetadataTemplate(BoxAPIConnection api, String templateKey) and getMetadataTemplate(BoxAPIConnection api, String templateKey, String templateScope, String... fields) can be used to set metadata template name, metadata scope and fields to retrieve.

MetadataTemplate template = MetadataTemplate.getMetadataTemplate(api, "templateName");

Get by ID

The static MetadataTemplate.getMetadataTemplateByID(BoxAPIConnection api, String templateID) method will return a specific metadata template.

MetadataTemplate template = MetadataTemplate.getMetadataTemplateByID(api, "37c0204b-3fe1-4a32-b9da-f28e88f4c4c6");

Get Enterprise Metadata Templates

Calling the static getEnterpriseMetadataTemplates(BoxAPIConnection api, String... fields) will return an iterable that will page through all metadata templates within a user's enterprise. Also, getEnterpriseMetadataTemplates(String templateScope, BoxAPIConnection api, String... fields) and getEnterpriseMetadataTemplates(String templateScope, int limit, BoxAPIConnection api, String... fields) can be used to set metadata scope, limit of items per single response.

Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates(api);
for (MetadataTemplate templateInfo : templates) {
    // Do something with the metadata template.
}

To return the metadata templates available to all enterprises pass in the global scope.

Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates('global', api);
for (MetadataTemplate templateInfo : templates) {
    // Do something with the metadata template.
}

Delete a Metadata Template

The deleteMetadataTemplate(BoxAPIConnection api, String scope, String template) method will remove a metadata template schema from an enterprise.

MetadataTemplate.deleteMetadataTemplate(api, "enterprise", "templateName");

Execute Metadata Query

There are two types of methods for executing a metadata query, methods without the fields parameter and with it. The methods without the fields parameters return a collection of BoxMetadataQueryItem objects. These methods have been deprecated. The methods with the fields parameters return a collection of BoxItem.Info objects. These methods are the preferred option. Examples of these two types are shown below.

The executeMetadataQuery(BoxAPIConnection api, String from, String query, JsonObject queryParameters, String ancestorFolderId, String indexName, JsonArray orderBy) method queries files and folders based on their metadata.

String from = "enterprise_341532.test";
String query = "testfield = :arg";
String ancestorFolderId = "0";
JsonObject queryParameters = new JsonObject().add("arg", "test");
JsonArray orderBy = new JsonArray();
JsonObject primaryOrderBy = new JsonObject().add("field_key", "primarySortKey").add("direction", "asc");
JsonObject secondaryOrderBy = new JsonObject().add("field_key", "secondarySortKey").add("direction",
    "asc");
orderBy.add(primaryOrderBy).add(secondaryOrderBy);

// NOTE: This method (without the fields parameter) is deprecated 
BoxResourceIterable<BoxMetadataQueryItem> results = MetadataTemplate.executeMetadataQuery(api, from, query, queryParameters, ancestorFolderId, null, orderBy);
for (BoxMetadataQueryItem r: results) {
  String customFieldValue = r.getMetadata().get("enterprise_341532").get(0).get("/customField");
  System.out.println(customFieldValue);
}

The executeMetadataQuery(BoxAPIConnection api, String from, String query, JsonObject queryParameters, String ancestorFolderId, String indexName, JsonArray orderBy, String ... fields) method queries files and folders based on their metadata and allows for fields to be passed in.

String from = "enterprise_341532.test";
String query = "testfield = :arg";
String ancestorFolderId = "0";
JsonObject queryParameters = new JsonObject().add("arg", "test");
JsonArray orderBy = new JsonArray();
JsonObject primaryOrderBy = new JsonObject().add("field_key", "primarySortKey").add("direction", "asc");
JsonObject secondaryOrderBy = new JsonObject().add("field_key", "secondarySortKey").add("direction",
    "asc");
orderBy.add(primaryOrderBy).add(secondaryOrderBy);

BoxResourceIterable<BoxItem.Info> results = MetadataTemplate.executeMetadataQuery(api, from, query, queryParameters, ancestorFolderId, null, orderBy, "id", "name", "metadata.enterprise_341532.test.customField");
for (BoxItem.Info itemInfo : results) {
    if (itemInfo instanceof BoxFile.Info) {
        BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
        // Do something with the file.

        // Example with metadata
        Metadata fileMetadata = fileInfo.getMetadata("test", "enterprise_341532");
        String customFieldValue = fileMetadata.getString("/customField");
        System.out.println(customFieldValue);

    } else if (itemInfo instanceof BoxFolder.Info) {
        BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo;
        // Do something with the folder.
    }
}