ALTER

ALTER Componenttypename component_name(
  attribute_name(attribute_value),

  ADD Subcomponenttypename subcomponent_name(
    attribute_name(attribute_value),
    attribute_name(attribute_value)
  ),
  MODIFY Subcomponenttypename subcomponent_name(
    attribute_name(attribute_value),
    attribute_name(attribute_value)
  ),
  
  RENAME Subcomponenttypename old_subcomponent_name TO new_subcomponent_name,
  DROP Subcomponenttypename subcomponent_name
);

The ALTER command modifies an MDL component in Vault.

If a component allows for subcomponents, you can ADD, MODIFY, or DROP the subcomponents as part of the same command. Take the example of a Documentstagegroup component with the following configuration, which we can retrieve with Vault API's Retrieve Component Record (MDL) endpoint.

RECREATE Documentstagegroup general_lc__c (
   label('General LC'),
   active(true),
   description(),
   document_lifecycle('Doclifecycle.general_lifecycle__c'),
   Documentstage draft__c(
      label('Draft'),
      active(true),
      description(),
      document_lifecycle_states_ref('Doclifecyclestate.draft__c',
         'Doclifecyclestate.planned__v'),
      order(1)
      ),
   Documentstage obsolete__c(
      label('Obsolete'),
      active(true),
      description(),
      document_lifecycle_states_ref('Doclifecyclestate.obsolete__c'),
      order(3)
      ),
   Documentstage review__c(
      label('Review'),
      active(true),
      description(),
      document_lifecycle_states_ref('Doclifecyclestate.in_review__c',
         'Doclifecyclestate.reviewed__c'),
      order(2)
      )
   );

Imagine you want to modify this component by:

Changing the value of the description attribute.
Removing the obsolete__c subcomponent.
Adding a new approved__c subcomponent.
Changing the name of another Documentstage from review__c to review_and_approval__c.
Modifying the multiselect document_lifecycle_states_ref attribute for the draft__c subcomponent by adding and removing states.

You can make each of these changes as a subcommand within the following ALTER command.

ALTER Documentstagegroup general_lc__c (

  # change the value of the description attribute on the Documentstagegroup component
  description('A general document lifecycle suitable for most purposes.'),
    
  # remove the obsolete__c Documentstage subcomponent
  DROP Documentstage obsolete__c,

  # add the approved__c Documentstage subcomponent
  ADD Documentstage approved__c(
    label('Approved'),
    active(true),
    description(),
    document_lifecycle_states_ref('Doclifecyclestate.approved__c'),
    order(3)
  ),
  
  # change the name of the review__c subcomponent to review_and_approval__c
  RENAME Documentstage review__c TO review_and_approval__c,
    
  # remove the planned__v lifecycle state from the draft__c subcomponent
  MODIFY Documentstage draft__c (
    document_lifecycle_states_ref DROP ('Doclifecyclestate.planned__v')
  ),

  # add the in_authoring__c lifecycle state to the draft__c subcomponent
  MODIFY Documentstage draft__c (
    document_lifecycle_states_ref ADD ('Doclifecyclestate.in_authoring__c')
  )
);

In addition to general MDL elements, ALTER commands can include the following:

Element	Description	Example
`ADD`/`DROP` Attribute Definition	The `ADD` or `DROP` attribute definition allows modification of attributes that allow multiple values by adding or removing value.	`document_lifecycle_states_ref ADD ('Doclifecyclestate.in_authoring__c')`
Subcommand	The action to execute within the `ALTER` command.	`MODIFY`

Multi-Value Attributes

Some components types allow you to set a list of values for certain attributes. Values should be separated by a comma (,) for example:

RECREATE Docfieldlayout general__c (
  label('General Section'),
  active(true),
  icon('VEEVA'),
  order(0),
  fields('Docfield.document_number__v',
    'Docfield.major_version_number__v',
    'Docfield.minor_version_number__v'
  )
);

These attributes will have multi_value set to true and a value set for ordered in the metadata for the component type. If ordered is set to true, then the order of items in the list has an impact on the behavior of the component.

When you add a value to a multi-value attribute using an ADD command within an ALTER command, Vault appends the new value to the end of the list. The example below appends Docfield.my_field__c to the end of the fields list from the example above.

ALTER Docfieldlayout general__c (
  fields ADD ('Docfield.my_field__c')
);