upsertMetadata()

Syntax

1UpsertResult[] = metadataConnection.upsertMetadata(Metadata[] metadata);

Usage

Use the upsertMetadata() call to create or update any component that extends Metadata. All components must be of the same type in the same call. For more details, see Metadata Components and Types.

If the specified components already 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 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.

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

Sample Code—Java

1public void upsertMetadataSample() {
2    try {
3        // Create custom object to upsert
4        CustomObject co = new CustomObject();
5        String name = "MyCustomObject";
6        co.setFullName(name + "__c");
7        co.setDeploymentStatus(DeploymentStatus.Deployed);
8        co.setDescription("Upserted by the Metadata API");
9        co.setEnableActivities(true);
10        co.setLabel(name + " Object");
11        co.setPluralLabel(co.getLabel() + "s");
12        co.setSharingModel(SharingModel.ReadWrite);
13
14        CustomField nf = new CustomField();
15        nf.setType(FieldType.Text);
16        nf.setLabel("CustomField1");
17        co.setNameField(nf);
18        
19        // Upsert the custom object
20        UpsertResult[] results = metadataConnection
21                .upsertMetadata(new Metadata[] { co });
22
23        for (UpsertResult r : results) {
24            if (r.isSuccess()) {
25                System.out.println("Success!");
26                if (r.isCreated()) {
27                    System.out.println("Created component: "
28                            + r.getFullName());
29                } else {
30                    System.out.println("Updated component: "
31                            + r.getFullName());
32                }
33            } else {
34                System.out
35                .println("Errors were encountered while upserting "
36                        + r.getFullName());
37                for (Error e : r.getErrors()) {
38                    System.out.println("Error message: " + e.getMessage());
39                    System.out.println("Status code: " + e.getStatusCode());
40                }
41            }
42        }
43    } catch (ConnectionException ce) {
44        ce.printStackTrace();
45    }
46}

Arguments

Response

UpsertResult[]