This call retrieves the metadata that describes your organization. This information includes Apex classes and triggers, custom objects, custom fields on standard objects, tab sets that define an app, and many other metadata types.

Syntax

DescribeMetadataResult = metadataConnection.describeMetadata( double apiVersion);

Arguments

Name

apiVersion

Type

double

Description

The API version for which you want metadata; for example, 41.0.

Permissions

Your client application must be logged in with the “Modify All Data” permission.

Sample Code—Java public void describeMetadata() { try { double apiVersion = 21.0;

// Assuming that the SOAP binding has already been established.

DescribeMetadataResult res = metadataConnection.describeMetadata(apiVersion);

StringBuffer sb = new StringBuffer(); if (res != null && res.getMetadataObjects().length > 0) { for (DescribeMetadataObject obj : res.getMetadataObjects()) { sb.append( "***************************************************\n" ); sb.append( "XMLName: " + obj.getXmlName() + "\n" ); sb.append( "DirName: " + obj.getDirectoryName() + "\n" ); sb.append( "Suffix: " + obj.getSuffix() + "\n" );

Utility Calls describeValueType()

} sb.append( "***************************************************\n" );

}

} else { sb.append( "Failed to obtain metadata types." );

} catch (ConnectionException ce) { ce.printStackTrace();

}

System.out.println(sb.toString());

Response

DescribeMetadataResult

When to Use

describeMetadata()

and

describeValueType()

Use the describeMetadata()

call to get high-level information about all the metadata types that are available for your organization, such as type names and file suffixes. Use the describeValueType()

call to get granular information about a specific metadata type, such as fields contained within the type.

describeValueType()

Retrieves the metadata describing a given metadata type (value type).

describeValueType()

accepts a namespace and a type name, and returns a

DescribeValueTypeResult

object. This call is available in API version 33.0 and later.

Syntax

DescribeValueTypeResult = connection.describeValueType( "{ namespace } type_name ");

Example

Describe Apex class metadata in the Metadata namespace:

DescribeValueTypeResult = metadataConnection.describeValueType( "{http://soap.sforce.com/2006/04/metadata}ApexClass" );

Describe Apex class metadata in the Tooling namespace:

DescribeValueTypeResult = toolingConnection.describeValueType( "{urn:metadata.tooling.soap.sforce.com}ApexClass" );

Utility Calls

Arguments

Name

type

Type

string describeValueType()

Description

The name of the metadata type for which you want metadata; for example,

ApexClass

Include the namespace.

Permissions

Your client application must be logged in with the “Modify All Data” permission.

Sample Code—Java

The following example describes several metadata types by specifying the Metadata namespace. Each metadata type is described using the helper method, doDescribe()

, which calls the describeValueType()

Metadata API call. The sample retrieves information from the returned

DescribeValueTypeResult

: a property, the parent field (if any), and the fields. Next, the sample iterates through the fields and outputs information about each field.

public void describeValueType() throws ConnectionException { doDescribe( "{http://soap.sforce.com/2006/04/metadata}CustomObject" ); doDescribe( "{http://soap.sforce.com/2006/04/metadata}CustomField" ); doDescribe( "{http://soap.sforce.com/2006/04/metadata}EmailTemplate" );

} public void doDescribe(String type) throws ConnectionException {

DescribeValueTypeResult result = metadataConnection.describeValueType(type);

StringBuffer sb = new StringBuffer(); sb.append( "Describing " + type + " ...\n" ); if (result.getApiCreatable() == true) { sb.append( "Is API creatable.\n" );

} else { sb.append( "Is not API creatable.\n" );

}

ValueTypeField parentField = result.getParentField(); if (parentField != null) { sb.append( "** Parent type fields **\n" ); if (parentField.getIsForeignKey()) { sb.append( "This field is a foreign key.\n" ); for (String fkDomain : parentField.getForeignKeyDomain()) { sb.append( "Foreign key domain: " + fkDomain + "\n" );

}

} sb.append( "** Value type fields **\n" ); for (ValueTypeField field : result.getValueTypeFields()) { sb.append( "***************************************************\n" ); sb.append( "Name: " + field.getName() + "\n" );

Utility Calls describeValueType() sb.append( "SoapType: " + field.getSoapType() + "\n" ); if (field.getIsForeignKey()) { sb.append( "This field is a foreign key.\n" ); for (String fkDomain : field.getForeignKeyDomain()) { sb.append( "Foreign key domain: " + fkDomain + "\n" );

}

} sb.append( "***************************************************\n" );

}

System.out.println(sb.toString());

}

To run the previous example with the Tooling WSDL, replace the namespace with the Tooling namespace in the helper function call as follows. Also, use the Tooling connection instead of the Metadata connection to make the describeValueType()

call.

doDescribe( "{urn:metadata.tooling.soap.sforce.com}CustomObject" ); doDescribe( "{urn:metadata.tooling.soap.sforce.com}CustomField" ); doDescribe( "{urn:metadata.tooling.soap.sforce.com}EmailTemplate" );

After you run the sample, the output looks similar to the following.

Describing {http://soap.sforce.com/2006/04/metadata}CustomObject ...

Is API creatable.

** Value type fields **

***************************************************

Name: actionOverrides

SoapType: ActionOverride

***************************************************

Name: allowInChatterGroups

SoapType: boolean

***************************************************

Name: articleTypeChannelDisplay

SoapType: ArticleTypeChannelDisplay

***************************************************

Name: businessProcesses

SoapType: BusinessProcess

***************************************************

Name: compactLayoutAssignment

SoapType: string

***************************************************

Name: compactLayouts

SoapType: CompactLayout

***************************************************

Name: customHelp

SoapType: string

This field is a foreign key.

Foreign key domain: ApexPage

Foreign key domain: Scontrol

Utility Calls listMetadata()

***************************************************

Describing {http://soap.sforce.com/2006/04/metadata}CustomField ...

Is API creatable.

** Parent type fields **

This field is a foreign key.

Foreign key domain: CustomObject

** Value type fields **

***************************************************

Name: caseSensitive

SoapType: boolean

***************************************************

Name: customDataType

SoapType: string

***************************************************

Name: defaultValue

SoapType: string

***************************************************

Response

DescribeValueTypeResult

listMetadata()

This call retrieves property information about metadata components in your organization. Data is returned for the components that match the criteria specified in the queries

parameter. The queries

array can contain up to three ListMetadataQuery

queries for each call. This call supports every metadata type: both top-level, such as

CustomObject and

ApexClass , and child types, such as

CustomField

and RecordType .

Syntax

FileProperties

[] = metadataConnection.listMetadata( ListMetadataQuery [] queries,

double asOfVersion);

Usage

This call is useful when you want to identify individual components in package.xml

for a

retrieve()

call or if you want a high-level view of particular metadata types in your organization. For example, you could use this call to return a list of names of all the

CustomObject

or Layout

components in your organization, and use this information to make a subsequent

retrieve()

call to return a subset of these components. For more information about working with package.xml

, see

Deploying and Retrieving Metadata

on page 15.

Utility Calls listMetadata()

Note:

This is a synchronous call so the results are returned in one call. This differs from asynchronous calls, such as retrieve()

where at least one subsequent call is needed to get the results.

Permissions

Your client application must be logged in with the “Modify All Data” permission.

Sample Code—Java

The sample code below lists information about your custom objects. The code assumes that the SOAP binding has already been established.

public void listMetadata() { try {

ListMetadataQuery query = new ListMetadataQuery(); query.setType( "CustomObject" );

//query.setFolder(null); double asOfVersion = 41.0;

// Assuming that the SOAP binding has already been established.

FileProperties[] lmr = metadataConnection.listMetadata( new ListMetadataQuery[] {query}, asOfVersion); if (lmr != null) { for (FileProperties n : lmr) {

System.out.println( "Component fullName: " + n.getFullName());

System.out.println( "Component type: " + n.getType());

}

} catch (ConnectionException ce) { ce.printStackTrace();

}

Arguments

Name

queries asOfVersion

Type Description

ListMetadataQuery

[] A list of objects that specify which components you are interested in.

double The API version for the metadata listing request. If you don't specify a value in this field, it defaults to the API version specified when you logged in. This field allows you to override the default and set another API version so that, for example, you could list the metadata for a metadata type that was added in a later version than the API version specified when you logged in. This field is available in API version 18.0 and later.

Response

FileProperties

Utility Calls ListMetadataQuery

ListMetadataQuery

The ListMetadataQuery parameter specified in a

listMetadata()

call consists of the following properties:

Name

folder type

Type

string string

Description