---
schema_version: "1"
id: 8bd3b64e751125f542f4493fe67338deeff93d7a42b9e3e8bb2459e2520067de
title: upsertMetadata()
collection: legacydeveloper
version: current
locale: en-us
portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/meta_upsertMetadata.md
canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_upsertMetadata.htm
source_site: developer.salesforce.com
content_type: documentation
content_hash: ca1c21520f5d40cf5c8cc2433dce30e9c825b7e4a688b43e356171c832d1a840
description: Creates or updates one or more metadata components in your organization synchronously.
---
# upsertMetadata()

Creates or updates one or more metadata components in your organization synchronously.

## Syntax

[UpsertResult](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_upsertResult.htm#meta_upsertResult "Contains information about the result of the associated upsertMetadata() call.")\[\] = metadataConnection.upsertMetadata([Metadata](https://developer.salesforce.com/docs/atlas.en-us.264.0.api_meta.meta/api_meta/metadata.htm)\[\] metadata);

## Usage

Use the upsertMetadata() call to create or update any component that extends [Metadata](https://developer.salesforce.com/docs/atlas.en-us.264.0.api_meta.meta/api_meta/metadata.htm). All components must be of the same type in the same call. For more details, see [Metadata Components and Types](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_objects_intro.htm "Metadata components are not based on sObjects, like objects in the API. Instead, they are based on metadata types, such as ApexClass and CustomObject, which extend Metadata, the base class for all metadata types. A component is an instance of a metadata type.").

If the specified components currently exist in your organization, the upsertMetadata() call updates them. Otherwise, upsertMetadata() creates these components. The fullname field matches the components. This call executes synchronously, which means that the call returns only after the operation is completed.

Starting in API version 34.0, this call supports the [AllOrNoneHeader](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_allornoneheader.htm "Indicates whether to roll back all metadata changes when some of the records in a call result in failures.") header. By default, if AllOrNoneHeader isn’t used in API version 34.0 and later, this call can save a partial set of records for records with no errors (equivalent to AllOrNoneHeader=false). In API version 33.0 and earlier, the default behavior is to only save all records when there are no failures in any record in the call (equivalent to AllOrNoneHeader=true).

## Version

Available in API version 31.0 and later.

## Permissions

Your client application must be logged in with the Modify Metadata Through Metadata API Functions or Modify All Data permission.

![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png)

#### Note

If a user requires access to metadata but not to data, enable the [Modify Metadata Through Metadata API Functions](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_metadata_perm.htm "To use Metadata API, a user must have these things.") permission. Otherwise, enable the Modify All Data permission.

## Required Fields

You must supply values for all the required fields in the component.

## Valid Field Values

You must supply values that are valid for the field’s data type, such as integers (not alphabetic characters) for integer fields. In your client application, follow the data formatting rules that are specified for your programming language and development tool. (Your development tool handles the appropriate mapping of data types in SOAP messages.)

## String Values

The API trims any leading and trailing white space when storing values in string fields. For example, if the value of a label field is entered as " MyObject ", the value is stored in the database as "MyObject".

## Basic Steps for Upserting Metadata Components

Use this process to upsert metadata components.

1. Create an array of [Metadata](https://developer.salesforce.com/docs/atlas.en-us.264.0.api_meta.meta/api_meta/metadata.htm) objects that correspond to the components that you want to create or update. All components must be of the same type.
2. Invoke upsertMetadata(), passing in the array of metadata components that you created in the previous step.
    
    The upsertMetadata() call returns an array of UpsertResult objects. Each returned UpsertResult corresponds to a component that you upserted and contains information about the upsert operation—whether the operation was successful, the name of the component that was upserted, a flag indicating whether the component was created, and any errors that were returned if the operation wasn’t successful.

## Sample Code—Java

public void upsertMetadataSample() {
    try {
        // Create custom object to upsert
        CustomObject co = new CustomObject();
        String name = "MyCustomObject";
        co.setFullName(name + "\_\_c");
        co.setDeploymentStatus(DeploymentStatus.Deployed);
        co.setDescription("Upserted by the Metadata API");
        co.setEnableActivities(true);
        co.setLabel(name + " Object");
        co.setPluralLabel(co.getLabel() + "s");
        co.setSharingModel(SharingModel.ReadWrite);

        CustomField nf = new CustomField();
        nf.setType(FieldType.Text);
        nf.setLabel("CustomField1");
        co.setNameField(nf);
        
        // Upsert the custom object
        UpsertResult\[\] results = metadataConnection
                .upsertMetadata(new Metadata\[\] { co });

        for (UpsertResult r : results) {
            if (r.isSuccess()) {
                System.out.println("Success!");
                if (r.isCreated()) {
                    System.out.println("Created component: "
                            + r.getFullName());
                } else {
                    System.out.println("Updated component: "
                            + r.getFullName());
                }
            } else {
                System.out
                .println("Errors were encountered while upserting "
                        + r.getFullName());
                for (Error e : r.getErrors()) {
                    System.out.println("Error message: " + e.getMessage());
                    System.out.println("Status code: " + e.getStatusCode());
                }
            }
        }
    } catch (ConnectionException ce) {
        ce.printStackTrace();
    }
}

## Arguments

### metadata

- **Type**: [Metadata](https://developer.salesforce.com/docs/atlas.en-us.264.0.api_meta.meta/api_meta/metadata.htm)\[\]
- **Description**: An array of one or more metadata components that you want to create or update.
    
    Limit: 10.
    
    You must submit arrays of only one type of component. For example, you can submit an array of 10 custom objects or 10 profiles, but not a mix of both types.

## Response

[UpsertResult](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_upsertResult.htm#meta_upsertResult "Contains information about the result of the associated upsertMetadata() call.")\[\]