Create a metadata template

Guides Metadata Metadata templates Create a metadata template

Required Guides

GuideMetadata template scopes

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

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"}
          ]
        }
      ]
    }'

TypeScript Gen

await client.metadataTemplates.createMetadataTemplate({
  scope: 'enterprise',
  displayName: templateKey,
  templateKey: templateKey,
  fields: [
    {
      key: 'firstName',
      displayName: 'First name',
      description: 'Person first name',
      type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'lastName',
      displayName: 'Last name',
      description: 'Person last name',
      type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'dateOfBirth',
      displayName: 'Birth date',
      description: 'Person date of birth',
      type: 'date' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'age',
      displayName: 'Age',
      description: 'Person age',
      type: 'float' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'hobby',
      displayName: 'Hobby',
      description: 'Person hobby',
      type: 'multiSelect' as CreateMetadataTemplateRequestBodyFieldsTypeField,
      options: [
        {
          key: 'guitar',
        } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
        {
          key: 'books',
        } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
      ],
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
  ],
} satisfies CreateMetadataTemplateRequestBody);

Python Gen

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,
        ),
        CreateMetadataTemplateFields(
            key="lastName",
            display_name="Last name",
            description="Person last name",
            type=CreateMetadataTemplateFieldsTypeField.STRING,
        ),
        CreateMetadataTemplateFields(
            key="dateOfBirth",
            display_name="Birth date",
            description="Person date of birth",
            type=CreateMetadataTemplateFieldsTypeField.DATE,
        ),
        CreateMetadataTemplateFields(
            key="age",
            display_name="Age",
            description="Person age",
            type=CreateMetadataTemplateFieldsTypeField.FLOAT,
        ),
        CreateMetadataTemplateFields(
            key="hobby",
            display_name="Hobby",
            description="Person hobby",
            type=CreateMetadataTemplateFieldsTypeField.MULTISELECT,
            options=[
                CreateMetadataTemplateFieldsOptionsField(key="guitar"),
                CreateMetadataTemplateFieldsOptionsField(key="books"),
            ],
        ),
    ],
)

.NET Gen

await client.MetadataTemplates.CreateMetadataTemplateAsync(requestBody: new CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey) { TemplateKey = templateKey, Fields = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsField(key: "firstName", displayName: "First name", type: CreateMetadataTemplateRequestBodyFieldsTypeField.String) { Description = "Person first name" },new CreateMetadataTemplateRequestBodyFieldsField(key: "lastName", displayName: "Last name", type: CreateMetadataTemplateRequestBodyFieldsTypeField.String) { Description = "Person last name" },new CreateMetadataTemplateRequestBodyFieldsField(key: "dateOfBirth", displayName: "Birth date", type: CreateMetadataTemplateRequestBodyFieldsTypeField.Date) { Description = "Person date of birth" },new CreateMetadataTemplateRequestBodyFieldsField(key: "age", displayName: "Age", type: CreateMetadataTemplateRequestBodyFieldsTypeField.Float) { Description = "Person age" },new CreateMetadataTemplateRequestBodyFieldsField(key: "hobby", displayName: "Hobby", type: CreateMetadataTemplateRequestBodyFieldsTypeField.MultiSelect) { Description = "Person hobby", Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "guitar"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "books")}) }}) });

Swift Gen (Beta)

try await client.metadataTemplates.createMetadataTemplate(requestBody: CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey, templateKey: templateKey, fields: [CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.string, key: "testName", displayName: "testName")]))

Java

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);

Python

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!')

.NET

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);

Node

// 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 } ] }
		*/
	});

iOS

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)")
}

Metadata templates can only be created for the enterprise scope. Templates can not be created for the global scope.

Admin permissions required

Creating metadata templates is restricted to users with admin permission. This means that only admins, or co-admins who have been granted rights to Create and edit metadata templates for your company by the admin can use the web app or the API to manage templates.

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

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.

Create a metadata template

Required Guides

Create a metadata template

Admin permissions required

Template Fields

Template Keys

Related APIs

Related Guides