Create a metadata template
Create a metadata template
To create a metadata template, pass a scope
, displayName
and an optional set
of fields
to the POST /metadata_templates/schema
API.
curl -i -X POST "https://api.box.com/2.0/metadata_templates/schema" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json" \
-d '{
"scope": "enterprise",
"displayName": "Customer",
"fields": [
{
"type": "string",
"key": "name",
"displayName": "Name",
"description": "The customer name",
"hidden": false
},
{
"type": "date",
"key": "last_contacted_at",
"displayName": "Last Contacted At",
"description": "When this customer was last contacted at",
"hidden": false
},
{
"type": "enum",
"key": "industry",
"displayName": "Industry",
"options": [
{"key": "Technology"},
{"key": "Healthcare"},
{"key": "Legal"}
]
},
{
"type": "multiSelect",
"key": "role",
"displayName": "Contact Role",
"options": [
{"key": "Developer"},
{"key": "Business Owner"},
{"key": "Marketing"},
{"key": "Legal"},
{"key": "Sales"}
]
}
]
}'
await client.metadataTemplates.createMetadataTemplate({
scope: 'enterprise',
displayName: templateKey,
templateKey: templateKey,
fields: [
{
type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField,
key: 'name',
displayName: 'name',
} satisfies CreateMetadataTemplateRequestBodyFieldsField,
{
type: 'float' as CreateMetadataTemplateRequestBodyFieldsTypeField,
key: 'age',
displayName: 'age',
} satisfies CreateMetadataTemplateRequestBodyFieldsField,
{
type: 'date' as CreateMetadataTemplateRequestBodyFieldsTypeField,
key: 'birthDate',
displayName: 'birthDate',
} satisfies CreateMetadataTemplateRequestBodyFieldsField,
{
type: 'enum' as CreateMetadataTemplateRequestBodyFieldsTypeField,
key: 'countryCode',
displayName: 'countryCode',
options: [
{
key: 'US',
} satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
{
key: 'CA',
} satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
],
} satisfies CreateMetadataTemplateRequestBodyFieldsField,
{
type: 'multiSelect' as CreateMetadataTemplateRequestBodyFieldsTypeField,
key: 'sports',
displayName: 'sports',
options: [
{
key: 'basketball',
} satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
{
key: 'football',
} satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
{
key: 'tennis',
} satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
],
} satisfies CreateMetadataTemplateRequestBodyFieldsField,
],
} satisfies CreateMetadataTemplateRequestBody);
client.metadata_templates.create_metadata_template(
"enterprise",
template_key,
template_key=template_key,
fields=[
CreateMetadataTemplateFields(
key="firstName",
display_name="First name",
description="Person first name",
type=CreateMetadataTemplateFieldsTypeField.STRING.value,
),
CreateMetadataTemplateFields(
key="lastName",
display_name="Last name",
description="Person last name",
type=CreateMetadataTemplateFieldsTypeField.STRING.value,
),
CreateMetadataTemplateFields(
key="dateOfBirth",
display_name="Birth date",
description="Person date of birth",
type=CreateMetadataTemplateFieldsTypeField.DATE.value,
),
CreateMetadataTemplateFields(
key="age",
display_name="Age",
description="Person age",
type=CreateMetadataTemplateFieldsTypeField.FLOAT.value,
),
CreateMetadataTemplateFields(
key="hobby",
display_name="Hobby",
description="Person hobby",
type=CreateMetadataTemplateFieldsTypeField.MULTISELECT.value,
),
],
)
await client.MetadataTemplates.CreateMetadataTemplateAsync(requestBody: new CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey) { TemplateKey = templateKey, Fields = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.String, key: "name", displayName: "name"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Float, key: "age", displayName: "age"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Date, key: "birthDate", displayName: "birthDate"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Enum, key: "countryCode", displayName: "countryCode") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "US"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "CA")}) },new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.MultiSelect, key: "sports", displayName: "sports") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "basketball"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "football"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "tennis")}) }}) });
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);
from boxsdk.object.metadata_template import MetadataField, MetadataFieldType
fields = [
MetadataField(MetadataFieldType.STRING, 'Name'),
MetadataField(MetadataFieldType.DATE, 'Birthday', 'bday'),
MetadataField(MetadataFieldType.ENUM, 'State', options=['CA', 'TX', 'NY'])
]
template = client.create_metadata_template('Employee Record', fields, hidden=True)
print(f'Metadata template ID {template.scope}/{template.templateKey} created!')
var templateParams = new BoxMetadataTemplate()
{
TemplateKey = "marketingCollateral",
DisplayName = "Marketing Collateral",
Scope = "enterprise",
Fields = new List<BoxMetadataTemplateField>()
{
new BoxMetadataTemplateField()
{
Type = "enum",
Key = "audience",
DisplayName = "Audience",
Options = new List<BoxMetadataTemplateFieldOption>()
{
new BoxMetadataTemplateFieldOption() { Key = "internal" },
new BoxMetadataTemplateFieldOption() { Key = "external" }
}
},
new BoxMetadataTemplateField()
{
Type = "string",
Key = "author",
DisplayName = "Author"
}
}
};
BoxMetadataTemplate template = await client.MetadataManager.CreateMetadataTemplate(templateParams);
// Create a new template, but hide it for now until it's ready for use
client.metadata.createTemplate(
'Vendor Contract',
[
{
type: 'date',
key: 'signed',
displayName: 'Date Signed'
},
{
type: 'string',
key: 'vendor',
displayName: 'Vendor'
},
{
type: 'enum',
key: 'fy',
displayName: 'Fiscal Year',
options: [
{key: 'FY17'},
{key: 'FY18'},
{key: 'FY19'}
]
}
],
{
hidden: true,
templateKey: 'vcontract',
copyInstanceOnItemCopy: false
}
)
.then(template => {
/* template -> {
id: '17f2d715-6acb-45f2-b96a-28b15efc9faa',
templateKey: 'vcontract',
scope: 'enterprise_12345',
displayName: 'Vendor Contract',
hidden: true,
copyInstanceOnItemCopy: false,
fields:
[ { type: 'date',
key: 'signed',
displayName: 'Date Signed',
hidden: false },
{ type: 'string',
key: 'vendor',
displayName: 'Vendor',
hidden: false },
{ type: 'enum',
key: 'fy',
displayName: 'Fiscal Year',
options:
[ { key: 'FY17' },
{ key: 'FY18' },
{ key: 'FY19' } ],
hidden: false } ] }
*/
});
var templateFields: [MetadataField] = []
templateFields.append(MetadataField(
type: "string",
key: "name",
displayName: "Full Name"
))
templateFields.append(MetadataField(
type: "date",
key: "birthday",
displayName: "Birthday"
))
templateFields.append(MetadataField(
type: "enum",
key: "department",
displayName: "Department",
options: [
["key": "HR"],
["key": "Sales"],
["key": "Marketing"],
]
))
client.metadata.createTemplate(
scope: "enterprise",
templateKey: "personnelRecord",
displayName: "Personnel Record",
hidden: false,
fields: templateFields
) { (result: Result<MetadataTemplate, BoxSDKError>) in
guard case let .success(template) = result {
print("Error creating metadata template")
return
}
print("Created metadata template with ID \(template.id)")
}
Template Fields
The fields
attribute represents the set of individual fields that a user can
fill in on a template. For example, a customer
template might have a name
field of type string
.
Template fields can be of string
, enum
, float
, date
, enum
or
multiSelect
type. Each field requires at least a type
, displayName
and key
.
{
"scope": "enterprise",
"displayName": "Customer",
"fields": [
{
"type": "string",
"key": "name",
"displayName": "Name"
}
]
}
The enum
and multiSelect
field types represent a dropdown list where a user
can select respectively one or many options from a list of items.
{
"scope": "enterprise",
"displayName": "Customer",
"fields": [
{
"type": "enum",
"key": "industry",
"displayName": "Industry",
"options": [
{"key": "Technology"},
{"key": "Healthcare"},
{"key": "Legal"}
]
}
]
}
Learn more about Metadata Template Fields
Template Keys
When a metadata template is created, a templateKey
is automatically generated
from the displayName
of the template unless a templateKey
is explicitly
provided. When creating the template key any spaces and irregular
characters in the name are removed, and the string is transformed to camel case.
For example, a metadata template that is named
Test Name (with-special_) Characters
will have a templateKey
of
testNameWithspecialCharacters
.
This template key is then used when making any API requests to get the template's information or assign it to an item.