Create & publish a label

This page describes how to create and publish a label.

Create a label

To create a label, use the create method on the labels collection. Labels can optionally contain one or more Fields .

You also must specify:

• A LabelType .

• A label title through the property method.

• useAdminAccess is true to use the user's administrator credentials. The server verifies that the user is an admin with the "Manage Labels" privilege before allowing access.

This example creates a standard, admin label with a specified title and one SelectionOptions Field with 2 Choices .

  label_body 
 = 
 { 
 'label_type' 
 : 
 'ADMIN' 
 , 
 'properties' 
 : 
 { 
 'title' 
 : 
 ' TITLE 
' 
 }, 
 'fields' 
 : 
 [{ 
 'properties' 
 : 
 { 
 'display_name' 
 : 
 ' DISPLAY_NAME 
' 
 }, 
 'selection_options' 
 : 
 { 
 'list_options' 
 : 
 {}, 
 'choices' 
 : 
 [{ 
 'properties' 
 : 
 { 
 'display_name' 
 : 
 ' CHOICE_1 
' 
 } 
 }, 
 { 
 'properties' 
 : 
 { 
 'display_name' 
 : 
 ' CHOICE_2 
' 
 } 
 }] 
 } 
 }] 
 } 
 response 
 = 
 service 
 . 
 labels 
 () 
 . 
 create 
 ( 
 body 
 = 
 label_body 
 , 
 useAdminAccess 
 = 
 True 
 ) 
 . 
 execute 
 () 
 

  var 
  
 label 
  
 = 
  
 { 
 'label_type' 
 : 
  
 'ADMIN' 
 , 
 'properties' 
 : 
  
 { 
  
 'title' 
 : 
  
 ' TITLE 
' 
 }, 
 'fields' 
 : 
  
 [{ 
  
 'properties' 
 : 
  
 { 
  
 'display_name' 
 : 
  
 ' DISPLAY_NAME 
' 
  
 }, 
  
 'selection_options' 
 : 
  
 { 
  
 'list_options' 
 : 
  
 {}, 
  
 'choices' 
 : 
  
 [{ 
  
 'properties' 
 : 
  
 { 
  
 'display_name' 
 : 
  
 ' CHOICE_1 
' 
  
 } 
  
 }, 
  
 { 
  
 'properties' 
 : 
  
 { 
  
 'display_name' 
 : 
  
 ' CHOICE_2 
' 
  
 } 
  
 }] 
  
 } 
 }] 
 }; 
 service 
 . 
 labels 
 . 
 create 
 ({ 
  
 'resource' 
 : 
  
 label 
 , 
  
 'use_admin_access' 
 : 
  
 true 
 }, 
  
 ( 
 err 
 , 
  
 res 
 ) 
  
 = 
>  
 { 
 if 
  
 ( 
 err 
 ) 
  
 return 
  
 console 
 . 
 error 
 ( 
 'The API returned an error: ' 
  
 + 
  
 err 
 ); 
  
 console 
 . 
 log 
 ( 
 res 
 ); 
 }); 
 

The label is created in the UNPUBLISHED_DRAFT State . It must be PUBLISHED for use on files and to be visible to users. For more information, see Label lifecycle .

Label limits

The following limits apply when creating and applying labels:

• Standard labels—150
• Fields per label—10
• User-applied labels per file—5

Working with fields in labels

Publish a label

The Labels API lets you publish a draft label once it's complete.

To publish a label, use the publish method and specify:

• A Label resource that represents every label. It contains a resource Name and ID , which is a globally unique identifier for the label.

• useAdminAccess is true to use the user's administrator credentials. The server verifies that the user is an admin with the "Manage Labels" privilege before allowing access.

This example uses the ID to identify and publish the correct label.

  service 
 . 
 labels 
 () 
 . 
 publish 
 ( 
 name 
 = 
 'labels/ ID 
' 
 , 
 body 
 = 
 { 
 'use_admin_access' 
 : 
 True 
 }) 
 . 
 execute 
 () 
 

  service 
 . 
 labels 
 . 
 publish 
 ({ 
  
 'resource' 
 : 
  
 { 
  
 'use_admin_access' 
 : 
  
 true 
 }, 
 'name' 
 : 
  
 'labels/ ID 
' 
 }, 
  
 ( 
 err 
 , 
  
 res 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 err 
 ) 
  
 return 
  
 console 
 . 
 error 
 ( 
 'The API returned an error: ' 
  
 + 
  
 err 
 ); 
  
 console 
 . 
 log 
 ( 
 res 
 ); 
 }); 
 

Once the label is published, the label moves to the PUBLISHED State and the label's revision ID is incremented. The label is then visible to users and can be applied to files. For more information, see Label lifecycle .

Constraints when publishing labels

• Once published, a label cannot return to its original draft state. For more information, see Label lifecycle .

• Publishing a label creates a newly published revision. All previous draft revisions are deleted. Previously published revisions are kept but are subject to automated deletion as needed.

• Once published, some changes are no longer permitted. Generally, this means any change that invalidates or triggers new restrictions on existing metadata related to the label is rejected. For example, the following changes to a label aren't permitted after the label is published:

  • The label is directly deleted. (It must be disabled first, then deleted.)
  • The Field.FieldType is changed.
  • Updates to the Field validation options reject something previously accepted.
  • A reduction in maximum entries.