API Tooling

Version 30.0: Spring ’14

Force.com Tooling API Developer's Guide

Note: Any unreleased services or features referenced in this or other press releases or public statements are not currently available and maynot be delivered on time or at all. Customers who purchase our services should make their purchase decisions based upon features that are

currently available.

Last updated: February 2, 2014

© Copyright 2000–2014 salesforce.com, inc. All rights reserved. Salesforce.com is a registered trademark of salesforce.com, inc., as are othernames and marks. Other marks appearing herein may be trademarks of their respective owners.

Table of Contents

GETTING STARTED.......................................................................................................................1

Chapter 1: Introducing Tooling API............................................................................................1When to Use Tooling API............................................................................................................................................1Using Tooling REST API............................................................................................................................................2Using Tooling SOAP API............................................................................................................................................4

REFERENCE...................................................................................................................................10

Chapter 2: Object Reference......................................................................................................10Tooling API Objects...................................................................................................................................................10ApexClass....................................................................................................................................................................12ApexClassMember......................................................................................................................................................13ApexCodeCoverage.....................................................................................................................................................15ApexCodeCoverageAggregate.....................................................................................................................................17ApexComponent.........................................................................................................................................................18ApexComponentMember............................................................................................................................................18ApexExecutionOverlayAction.....................................................................................................................................20ApexExecutionOverlayResult......................................................................................................................................22ApexLog......................................................................................................................................................................25ApexPage.....................................................................................................................................................................27ApexPageMember.......................................................................................................................................................27ApexResult..................................................................................................................................................................30ApexTrigger................................................................................................................................................................30ApexTriggerMember...................................................................................................................................................31ContainerAsyncRequest..............................................................................................................................................33CustomField................................................................................................................................................................35FieldHistoryRetentionJob...........................................................................................................................................38HeapDump..................................................................................................................................................................40MetadataContainer......................................................................................................................................................41SOQLResult...............................................................................................................................................................42StaticResource.............................................................................................................................................................43SymbolTable................................................................................................................................................................44TraceFlag.....................................................................................................................................................................46ValidationRule.............................................................................................................................................................52WorkflowRule.............................................................................................................................................................53

Index.................................................................................................................................................56

i

Table of Contents

GETTING STARTED

Chapter 1

Introducing Tooling API

Tooling API provides SOAP and REST interfaces that allow you to build custom development tools for Force.com applications.

For example, you can:

• Add features and functionality to your existing Force.com tools.

• Build dynamic modules for Force.com development into your enterprise integration tools.

• Build specialized development tools for a specific application or service.

Tooling API exposes objects used in developer tooling that you can access through REST or SOAP, and works just like theSalesforce REST API and SOAP API.

For detailed descriptions of Tooling API objects and the REST resources and SOAP calls that each object supports, seeTooling API Objects.

See Also:When to Use Tooling APIUsing Tooling REST APIUsing Tooling SOAP API

When to Use Tooling APIUse Tooling API to perform the following tasks:

• Manage working copies of Apex classes and triggers and Visualforce pages and components using the ApexClassMember,ApexTriggerMember, ApexPageMember, ApexComponentMember and MetadataContainer objects.

• Manage working copies of static resource files using the StaticResource object.

• Check for updates and errors in working copies of Apex classes and triggers and Visualforce pages and components, andcommit changes to your organization using the ContainerAsyncRequest object.

• Set heap dump markers using the ApexExecutionOverlayAction object.

• Overlay Apex code or SOQL statements on an Apex execution using the ApexExecutionOverlayAction object.

• Execute anonymous Apex.

• Set checkpoints to generate log files for yourself or for other users using the TraceFlag object.

• Access debug log and heap dump files using the ApexLog and ApexExecutionOverlayResult objects.

• Manage custom fields on custom objects using the CustomField object.

• Access code coverage results using the ApexCodeCoverage and ApexCodeCoverageAggregate objects.

• Manage validation rules and workflow rules using the ValidationRule and WorkflowRule objects.

1

Selecting the Right API for Your ApplicationTooling API provides both SOAP and REST interfaces.

• Use REST API bindings if you’re using a language that isn’t strongly typed, like JavaScript. See Using Tooling RESTAPI.

• Use SOAP API bindings if you’re using a strongly typed language like Java that generates Web service client code. SeeUsing Tooling SOAP API.

See Also:Using Tooling REST APIUsing Tooling SOAP API

Using Tooling REST APIUse REST API bindings if you’re using a language that isn’t strongly typed, like JavaScript. The REST Tooling API can beused just like the Force.com REST API; for details on usage, syntax, and authentication, see the Force.com REST API Developer'sGuide.

ResourcesThis section lists supported REST resources in Tooling API.

The base URI for each Tooling REST API resource is http://domain/services/data/vXX.X/tooling/ wheredomain is a Salesforce instance or a custom domain and vXX.X is the API version number. For example:http://na1.salesforce.com/services/data/v28.0/tooling/

Like the Force.com REST API, Tooling API uses the following resources.

DescriptionSupportedMethods

URI

Retrieves available code completions of the referenced type.Currently only supports Apex system method symbols(type=apex). Available from API version 28.0 or later.

GET/completions?type=

Executes Apex code anonymously. Available from API version29.0 or later.GET/executeAnonymous/?anonymousBody=<url

encoded body>

Executes a query against a Tooling API object and returnsdata that matches the specified criteria.

If the query results are too large, the response contains thefirst batch of results and a query identifier. The identifier canbe used in an additional request to retrieve the next batch.

GET/query/?q=

Lists the available Tooling API objects and their metadata.GET/sobjects/

Describes the individual metadata for the specified object orcreates a new record for a given object.

For example, use the GET method to retrieve the metadatafor the ApexExecutionOverlayAction object. Use the POSTmethod to create a new ApexExecutionOverlayAction object.

GET

POST

/sobjects/SObjectName/

2

Using Tooling REST APIIntroducing Tooling API

http://www.salesforce.com/us/developer/docs/api_rest/index.htm


DescriptionSupportedMethods

URI

Completely describes the individual metadata at all levels forthe specified object.

For example, use this resource to retrieve the fields, URLs,and child relationships for a Tooling API object.

GET/sobjects/SObjectName/describe/

Accesses records based on the specified object ID.

Use the GET method to retrieve records or fields, theDELETE method to delete records, and the PATCH methodto update records.

GET

PATCH

DELETE

/sobjects/SObjectName/id/

Retrieves a raw debug log by ID. Available from API version28.0 or later.GET/sobjects/ApexLog/id/Body/

ExamplesThe following examples use Apex to execute REST requests, but you can use any standard REST tool to access Tooling RESTAPI.

Note: Salesforce runs on multiple server instances. The examples in this guide use the na1 instance. The instanceyour organization uses might be different.

First, set up the connection to your org and the HTTP request type:

HttpRequest req = new HttpRequest();req.setHeader('Authorization', 'Bearer ' + UserInfo.getSessionID());req.setHeader('Content-Type', 'application/json');

At the end of each request (examples below), add the following code to send the request and retrieve the body of the response:

Http h = new Http();HttpResponse res = h.send(req);system.debug(res.getBody());

To get a description of all available objects in Tooling API:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/');req.setMethod('GET');

To get a description of a specific Tooling API object, for example TraceFlag:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/TraceFlag/');req.setMethod('GET');

To get a description of all the metadata for a specific Tooling API object, for example TraceFlag:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/TraceFlag/describe/');req.setMethod('GET');

To create a new Tooling API object, for example MetadataContainer:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/MetadataContainer/');

3

Using Tooling REST APIIntroducing Tooling API

req.setBody('{"Name":"TestContainer"}');req.setMethod('POST');

Tip: Use the ID from this call in the rest of the examples.

To retrieve a Tooling API object by ID, for example MetadataContainer:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/MetadataContainer/ + containerID + '/');req.setMethod('GET');

To update a Tooling API object by ID, for example MetadataContainer:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/MetadataContainer/ + containerID + '/');req.setBody('{"Name":"NewlyNamedContainer"}');req.setMethod('PATCH');

To query a Tooling API object by ID, for example MetadataContainer:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/query/?q=Select+id,Name+from+MetadataContainer+Where+ID=\'' + containerID + '\'');req.setMethod('GET');

Or to query an object within a MetadataContainer:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/query/?q=Select+id,Body,LastSyncDate,Metadata+from+ApexClassMember+Where+MetadataContainerID=\'+ containerID + '\'');req.setMethod('GET');

To check on the status of a deployment, using ContainerAsyncRequest:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/ContainerAsyncRequest/' + requestID + '/');req.setMethod('GET');

To execute anonymous Apex:

req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/executeAnonymous/?anonymousBody=System.debug('Test')%3B');req.setMethod('GET');

See Also:Tooling API ObjectsForce.com REST API Developer's Guide

Using Tooling SOAP APIUse SOAP API bindings if you’re using a strongly typed language like Java that generates Web service client code. ToolingSOAP API is used just like the Salesforce SOAP API. For details on usage, syntax, and authentication, see the SOAP APIDeveloper's Guide.

To access the Tooling API WSDL, from Setup, click Develop > API and click Generate Tooling WSDL.

4

Using Tooling SOAP APIIntroducing Tooling API


http://www.salesforce.com/us/developer/docs/api/index.htm


Like the Salesforce SOAP API, Tooling API uses the following calls.

DescriptionCall

Adds one or more new records to your organization’s data.create()

Deletes one or more records from your organization’s data.delete()

Lists the available Tooling API objects and their metadata.describeGlobal()

Describes metadata (field list and object properties) for the specified object or array of objects.

Call describeGlobal() to retrieve a list of all Tooling API objects for your organization,then iterate through the list and use describeSObjects() to obtain metadata about individualobjects.

describeSObjects()

Executes the specified block of Apex anonymously and returns the result.executeanonymous(stringapexcode)

Executes a query against a Tooling API object and returns data that matches the specifiedcriteria.

query()

Retrieves one or more records based on the specified IDs.retrieve()

Updates one or more existing records in your organization’s data.update()

Creates new records and updates existing records; uses a custom field to determine the presenceof existing records.

upsert()

ExamplesThese examples use Java, but you can use Tooling SOAP API in any language that supports Web services.

Use create() to compile Apex classes or triggers in Developer Edition or sandbox organizations. The first example belowuses ApexClass to compile a simple class with a single method called SayHello.

String classBody = "public class Messages {\n"+ "public string SayHello() {\n"+ " return 'Hello';\n" + "}\n"+ "}";

// create a new ApexClass object and set the bodyApexClass apexClass = new ApexClass();apexClass.Body = classBody;ApexClass[] classes = { apexClass };

// call create() to add the classSaveResult[] saveResults = sforce.create(classes);for (int i = 0; i < saveResults.Length; i++)

{if (saveResults[i].success)

{Console.WriteLine("Successfully created Class: " +saveResults[i].id);

}else

{Console.WriteLine("Error: could not create Class ");Console.WriteLine(" The error reported was: " +saveResults[i].errors[0].message + "\n");

}}

5


Use the IsCheckOnly parameter on ContainerAsyncRequest to indicate whether an asynchronous request should compilecode without making any changes to the organization (true) or compile and save the code (false).

The example below expands upon the first by modifying the SayHello() method to accept a person’s first and last name.This example uses MetadataContainer with ApexClassMember to retrieve and update the class, and ContainerAsyncRequestto compile and deploy the changes to the server. You can use the same method with ApexTriggerMember,ApexComponentMember, and ApexPageMember.

Note:

To test your code, modify the IsCheckOnly parameter in the code below, and log in to your org after a successfulexecution to verify the results.

• When IsCheckOnly = true, the SayHello() method should remain the same. (ApexClassMember containsthe compiled results, but the class on the server remains the same.)

• When IsCheckOnly = false, the SayHello() method should show the change to accept a person’s firstand last name.

String updatedClassBody = "public class Messages {\n"+ "public string SayHello(string fName, string lName) {\n"+ " return 'Hello ' + fName + ' ' + lName;\n" + "}\n"+ "}";

//create the metadata container objectMetadataContainer Container = new MetadataContainer();Container.Name = "SampleContainer";

MetadataContainer[] Containers = { Container };SaveResult[] containerResults = sforce.create(Containers);if (containerResults[0].success){

String containerId = containerResults[0].id;

//create the ApexClassMember objectApexClassMember classMember = new ApexClassMember();//pass in the class ID from the first exampleclassMember.ContentEntityId = classId;classMember.Body = updatedClassBody;//pass the ID of the container created in the first stepclassMember.MetadataContainerId = containerId;ApexClassMember[] classMembers = { classMember };

SaveResult[] MembersResults = sforce.create(classMembers);if (MembersResults[0].success){

//create the ContainerAsyncRequest objectContainerAsyncRequest request = new ContainerAsyncRequest();//if the code compiled successfully, save the updated class to the server//change to IsCheckOnly = true to compile without savingrequest.IsCheckOnly = false;request.MetadataContainerId = containerId;ContainerAsyncRequest[] requests = { request };SaveResult[] RequestResults = sforce.create(requests);if (RequestResults[0].success){

string requestId = RequestResults[0].id;

//poll the server until the process completesQueryResult queryResult = null;String soql = "SELECT Id, State, CompilerErrors, ErrorMsg FROM

ContainerAsyncRequest where id = '" + requestId + "'";queryResult = sforce.query(soql);if (queryResult.size > 0){ContainerAsyncRequest _request = (ContainerAsyncRequest)queryResult.records[0];

6


while (_request.State.ToLower() == "queued"){

//pause the process for 2 secondsThread.Sleep(2000);

//poll the server again for completionqueryResult = sforce.query(soql);_request = (ContainerAsyncRequest)queryResult.records[0];

}

//now process the resultswitch (_request.State){

case "Invalidated":break;

case "Completed"://class compiled successfully//see the next example on how to process the SymbolTable

break;

case "Failed":. . break;

case "Error":break;

case "Aborted":break;

}}else{

//no rows returned}

}else{

Console.WriteLine("Error: could not create ContainerAsyncRequest object");Console.WriteLine(" The error reported was: " +RequestResults[0].errors[0].message + "\n");

}}else{

Console.WriteLine("Error: could not create Class Member ");Console.WriteLine(" The error reported was: " +MembersResults[0].errors[0].message + "\n");

}}else{.. Console.WriteLine("Error: could not create MetadataContainer ");

Console.WriteLine(" The error reported was: " +containerResults[0].errors[0].message + "\n");

}}

Use a SymbolTable to access Apex class and trigger data in a structured format.

The example below queries the ApexClassMember object created in the previous example to obtain the SymbolTable of themodified class.

7


Note: The SOQL statement used depends on when the data is retrieved.

• To execute the query from within the example above, use the ID of the ContainerAsyncRequest. For example,SELECT Body, ContentEntityId, SymbolTable FROM ApexClassMember whereMetadataContainerId = '" + requestId + "'"

• Otherwise, use the ID of the modified class as shown below. For example, SELECT ContentEntityId,SymbolTable FROM ApexClassMember where ContentEntityId = '" + classId + "'"

//use the ID of the class from the previous stepstring classId = "01pA00000036itIIAQ";QueryResult queryResult = null;String soql = "SELECT ContentEntityId, SymbolTable FROM ApexClassMember where

ContentEntityId = '" + classId + "'";

queryResult = sforce.query(soql);if (queryResult.size > 0){

ApexClassMember apexClass = (ApexClassMember)queryResult.records[0];SymbolTable symbolTable = apexClass.SymbolTable;

foreach (Method _method in symbolTable.methods){

//here's the SayHello methodString _methodName = _method.name;

//is the method Global, Public or Private?String _methodVisibility = _method.visibility.ToString();

//get the method's return typestring _methodReturnType = _method.returnType;

//get the fName & lName parametersforeach (Parameter _parameter in _method.parameters){

string _paramName = _parameter.name;string _parmType = _parameter.type;

}}

}else{

//unable to locate class}

Use ApexExecutionOverlayAction to add checkpoints to your code for debugging.

This example adds a checkpoint to the class from the previous examples:

//use the ID of the class from the first example.string classId = "01pA00000036itIIAQ";

ApexExecutionOverlayAction action = new ApexExecutionOverlayAction();action.ExecutableEntityId = classId;action.Line = 3;action.LineSpecified = true;action.Iteration = 1;action.IterationSpecified = true;ApexExecutionOverlayAction[] actions = { action };

SaveResult[] actionResults = sforce.create(actions);if (actionResults[0].success){

// checkpoint created successfully}else

8


{Console.WriteLine("Error: could not create Checkpoint ");Console.WriteLine(" The error reported was: " +actionResults[0].errors[0].message + "\n");

}

See Also:Tooling API ObjectsSOAP API Developer's Guide

9



REFERENCE

Chapter 2

Object Reference

This section provides a list of Tooling API objects, their fields, and supported SOAP API calls and REST resources. Not allfields are listed for all objects.

To verify the complete list of fields for an object, see the Tooling API WSDL. To access the Tooling API WSDL, fromSetup, click Develop > API and click Generate Tooling WSDL.

Tooling API ObjectsTooling API includes the following objects:

DescriptionObject

Represents the saved copy of an Apex class. ApexClass uses the cachedversion of the class unless one is unavailable.

ApexClass

Represents the working copy of an Apex class for editing, saving or compilingin a MetadataContainer.

ApexClassMember

Represents code coverage test results for an Apex class or trigger.ApexCodeCoverage

Represents aggregate code coverage test results for an Apex class or trigger.ApexCodeCoverageAggregate

Represents the saved copy of aVisualforce component. ApexComponentuses the cached version of the class unless one is unavailable.

ApexComponent

Represents the working copy of a Visualforce component for editing, savingor compiling in a MetadataContainer.

ApexComponentMember

Specifies an Apex code snippet or SOQL query to execute at a specific lineof code in an Apex class or trigger and optionally generate a heap dump.

ApexExecutionOverlayAction

Represents the result from the Apex code snippet or SOQL query definedin the associated ApexExecutionOverlayAction, and the resulting heap dumpif one was returned.

ApexExecutionOverlayResult

Represents a debug log.ApexLog

Represents the saved copy of an Apex page. ApexPage uses the cached versionof the class unless one is unavailable.

ApexPage

Represents the working copy of a Visualforce page for editing, saving orcompiling in a MetadataContainer.

ApexPageMember

10

DescriptionObject

Represents the saved copy of an Apex page. ApexTrigger uses the cachedversion of the class unless one is unavailable.

ApexTrigger

Represents the working copy of an Apex trigger for editing, saving orcompiling in a MetadataContainer.

ApexTriggerMember

Allows you to compile and asynchronously deploy a MetadataContainerobject to your organization.

ContainerAsyncRequest

Represents a custom field on a custom object that stores data unique to yourorganization.

CustomField

Specifies the date range for the retention of field history data, beyond thestandard 18 months of data retention that Salesforce provides.

FieldHistoryRetentionJob

Manages working copies of ApexClassMember, ApexTriggerMember,ApexPageMember and ApexComponentMember objects, includingcollections of objects that should be deployed together.

MetadataContainer

Represents the working copy of a static resource file for editing or saving.Static resources allow you to upload content that you can reference ina Visualforce page, including images, stylesheets, JavaScript, and other files.

StaticResource

Represents a trace flag that triggers an Apex debug log at the specifiedlogging level.

TraceFlag

Represents a formula that is used for specifying when a criteria is met. Thisincludes both validation rules and workflow rules. Includes access to theassociated ValidationRule object in Salesforce Metadata API.

ValidationRule

Represents a workflow rule that is used to fire off a specific workflow actionwhen the specified criteria is met. Creation and modification of workflow

WorkflowRule

rules isn't supported. Includes access to the associated WorkflowRule objectin Salesforce Metadata API.

This section also provides details on the following complex types:

DescriptionObject

A complex type that represents the result of Apex code executed as part ofan ApexExecutionOverlayAction, returned in anApexExecutionOverlayResult.

ApexResult

A complex type that represents a heap dump in anApexExecutionOverlayResult.

HeapDump

A complex type that represents the result of a SOQL query in anApexExecutionOverlayResult.

SOQLResult

A complex type that represents all user-defined tokens in the Body of anApexClass, ApexClassMember, or ApexTriggerMember and their associatedline and column locations within the Body.

SymbolTable

The following Tooling API objects are used internally by the Developer Console.

11

Tooling API ObjectsObject Reference

• IDEPerspective

• IDEWorkspace

• User.WorkspaceId

See Also:Using Tooling REST APIUsing Tooling SOAP API

ApexClassRepresents the saved copy of an Apex class. ApexClass uses the cached version of the class unless one is unavailable.

Available from API version 28.0 or later.

To edit, save, or compile Apex classes, use ApexClassMember.

Supported SOAP API Callscreate(), delete(), describeSObjects(), query(), retrieve(), update(), upsert()

Supported REST API HTTP MethodsQuery, GET, POST, PATCH, DELETE

Fields

DetailsField Name

TypeSymbolTable

SymbolTable

PropertiesNillable

DescriptionA complex type that represents all user-defined tokens in the Body of anApexClass, ApexClassMember, or ApexTriggerMember and theirassociated line and column locations within the Body.

This field is null if the symbol table cannot be created.

UsageTo retrieve information about an Apex class, create an ApexClass object that references it. For example code, see Using ToolingSOAP API.

To edit, save, or compile Apex classes, use ApexClassMember.

Note: If there is not a cached version of SymbolTable, it will be compiled in the background and the query mighttake longer than expected. The SymbolTable returned from ApexClass does not contain references; to retrieve aSymbolTable with references, use ApexClassMember.

12

ApexClassObject Reference

ApexClassMemberRepresents the working copy of an Apex class for editing, saving or compiling in a MetadataContainer.



Fields

DetailsField Name

Typestring

Body

PropertiesCreate, Update

DescriptionThe data for the Apex class.

The Body field is the only field you can update() or PATCH.

Typestring

Content

PropertiesNone

DescriptionA string representation of ApexClassMetadata that lists the version, status,and packaged versions of the corresponding Apex class.

Typereference

ContentEntityId

PropertiesCreate, Filter, Group, Sort

DescriptionA reference to an Apex class.

There can be only one ContentEntityId per ApexClassMember,otherwise, an error is reported.

This field is required.

TypedateTime

LastSyncDate

13

ApexClassMemberObject Reference

DetailsField Name

PropertiesFilter, Sort

DescriptionThe date and time that this ApexClassMember Body was replicated fromthe underlying Apex class.

When you deploy a MetadataContainer, this value is compared with theLastModifiedDate of the underlying Apex class. If LastSyncDateis older than LastModifiedDate, the deployment fails with an error.

TypeApexClassMetadata

Metadata

PropertiesNone

DescriptionAn object that describes the version, status, and packaged versions of thecorresponding Apex class.

Typereference

MetadataContainerId


DescriptionA reference to a MetadataContainer or ContainerAsyncRequest object.

As part of a successful deployment, this field is reset from the ID of thedeployed MetadataContainer to the ID of the correspondingContainerAsyncRequest object.


TypeSymbolTable

SymbolTable

PropertiesNillable


This field is null if the symbol table cannot be created. A symbol tablecannot be created if the content referenced by the ContentEntityIdfield doesn’t use a symbol table, or if compiler errors for the last deploymentof the MetadataContainer in the MetadataContainerId field preventeda symbol table from being created.

14

ApexClassMemberObject Reference

UsageTo edit, save, or compile an Apex class, create an ApexClassMember object that references it.

Note: Once an ApexClassMember is successfully deployed in a MetadataContainer, the MetadataContainerIdis changed to the ID of the ContainerAsyncRequest, and the ApexClassMember can’t be modified or reused.

Apex classes are often dependent on each other for functionality. For example, a method in one class can call a method inanother class. If source file A is dependent on modified source file B and you try to save and compile source file A beforeyou’ve saved the changes to source file B, the compiler will throw an error. To successfully save and compile a group of relatedsource files, put the corresponding ApexClassMember and ApexTriggerMember objects in a single MetadataContainer object.

Each ApexClassMember object can only refer to a single MetadataContainer object. Multiple ApexClassMember objects canrefer to the same MetadataContainer object.

ApexCodeCoverageRepresents code coverage test results for an Apex class or trigger.

Available in Tooling API version 29.0 and later.

Supported CallsdescribeSObjects(), query(), retrieve()

Fields

DetailsField

Typestring

ApexClassorTriggerId

PropertiesFilter, Group, Sort

DescriptionThe ID of the class or trigger under test.

Typestring

ApexTestClassId


DescriptionThe ID of the test class.

Typeint

NumLinesCovered


DescriptionThe number of covered lines.

15

ApexCodeCoverageObject Reference

DetailsField

Typeint

NumLinesUncovered


DescriptionThe number of uncovered lines.

Typecomplexvalue

Coverage

PropertiesNone

DescriptionTwo lists of integers. The first is the covered lines, and the second is the list ofuncovered lines. If a lines is missing from both lists, the line is not executable anddoes not require coverage.

Coverage includes the following fields:• coveredLines

• namespace

• uncoveredLines

UsageTo query for code coverage, specify an Apex class, test class, or both. The returned JSON or XML object will contain twolists of integers: one for covered and one for uncovered lines.

The following example SOQL query retrieves code coverage results for a specific class or trigger covered by a specific test class:

SELECT CoverageFROM CodeCoverageWHERE ApexClassOrTrigger = ‘01pD000000066GR’AND ApexTestClass = ‘01pD000000064pu’

For per-class code coverage, the query would be:

SELECT CoverageFROM CodeCoverageWHERE ApexClassOrTrigger = ‘01pD000000066GR’

Note: In this case, multiple rows may be returned, since there may be multiple test classes that cover the same testclass.

As noted above, Coverage is returned as two lists of integers. The first is the covered lines, and the second is the list ofuncovered lines. If a line is missing from both lists, the line is not executable and does not require coverage. For example, ifthe covered lines are 2, 9, and 11, and uncovered lines are 3, 4, 5, and 6; the result would be: {2,9,11},{3,4,5,6}. Themissing lines (1, 7, 8 and 10) are not executable.

16

ApexCodeCoverageObject Reference

Code coverage percentage is a simple calculation of the number of covered lines divided by the sum of the number of coveredlines and the number of uncovered lines. For example, to calculate code coverage percentage in SOAP:

ApexCodeCoverage acc = null; //Query for an ApexCodeCoverage objectCoverage coverage = acc.coverage;int[] covered = coverage.coveredLines;int[] uncovered = coverage.uncoveredLines;int percent = covered.length / (covered.length + uncovered.length);System.out.println("Total class coverage is " + percent + "%.");

ApexCodeCoverageAggregateRepresents aggregate code coverage test results for an Apex class or trigger.


Supported CallsdescribeSObjects(), query(), retrieve()

Fields

DetailsField

Typestring

ApexClassorTriggerId


DescriptionThe ID of the class or trigger under test.

Typeint

NumLinesCovered


DescriptionThe number of covered lines.

Typeint

NumLinesUncovered


DescriptionThe number of uncovered lines.

Typecomplexvalue

Coverage

17

ApexCodeCoverageAggregateObject Reference

DetailsField

PropertiesNone

DescriptionTwo lists of integers. The first is the covered lines, and the second is the list ofuncovered lines. If a lines is missing from both lists, the line is not executable anddoes not require coverage.

Coverage includes the following fields:• coveredLines

• namespace

• uncoveredLines

UsageTo query for aggregate code coverage, specify an Apex test class. The returned JSON or XML object will contain two lists ofintegers: one for covered and one for uncovered lines. For examples, see ApexCodeCoverage.

ApexComponentRepresents the saved copy of aVisualforce component. ApexComponent uses the cached version of the class unless one isunavailable.


To edit, save, or compile Visualforce components, use ApexComponentMember.



UsageTo retrieve information about a Visualforce component, create an ApexComponent object that references it. For examplecode, see Using Tooling SOAP API.

To edit, save, or compile Visualforce components, use ApexComponentMember.

ApexComponentMemberRepresents the working copy of a Visualforce component for editing, saving or compiling in a MetadataContainer.



18

ApexComponentObject Reference

Fields

DetailsField Name

Typestring

Body


DescriptionThe data for the Visualforce component.


Typestring

Content

PropertiesNone

DescriptionA string representation of ApexComponentMetadata that lists the version,status, and packaged versions of the corresponding Visualforce component.

Typereference

ContentEntityId


DescriptionA reference to a Visualforce component.

There can be only one ContentEntityId per ApexComponentMember,otherwise, an error is reported.


TypedateTime

LastSyncDate


DescriptionThe date that this ApexComponentMember Body was replicated fromthe underlying entity.

When you deploy a MetadataContainer, this value is compared with theLastModifiedDate of the underlying Visualforce component. IfLastSyncDate is older than LastModifiedDate, the deployment failswith an error.

TypeApexComponentMetadata

Metadata

19

ApexComponentMemberObject Reference

DetailsField Name

PropertiesNone

DescriptionAn object that describes the version, status, and packaged versions of thecorresponding Visualforce component.

Typereference

MetadataContainerId





UsageTo edit, save, or compile a Visualforce component, create an ApexComponentMember object that references it. To create anew Visualforce component, use the Force.com REST API or the Metadata API.

Note: Once an ApexComponentMember is successfully deployed in a MetadataContainer, theMetadataContainerId is changed to the ID of the ContainerAsyncRequest, and the ApexComponentMembercan’t be modified or reused.

Visualforce pages and components are often dependent on each other for functionality. To successfully save and compile agroup of related source files, put the corresponding ApexComponentMember and ApexPageMember objects in a singleMetadataContainer object.

Each ApexComponentMember object can only refer to a single MetadataContainer object. Multiple ApexComponentMemberobjects can refer to the same MetadataContainer object.

See Also:Force.com REST API Developer's GuideMetadata API Developer's Guide

ApexExecutionOverlayActionSpecifies an Apex code snippet or SOQL query to execute at a specific line of code in an Apex class or trigger and optionallygenerate a heap dump.

Supported SOAP Callscreate(), delete(), describeSObjects(), query(), retrieve(), update(), upsert()

20

ApexExecutionOverlayActionObject Reference


http://www.salesforce.com/us/developer/docs/api_meta/index.htm

Supported REST HTTP MethodsQuery, GET, POST, PATCH, DELETE

Fields

DetailsField Name

Typestring

ActionScript

PropertiesCreate, Nillable, Update

DescriptionThe Apex code or SOQL query to run when execution reaches the linein the Apex class or trigger at the specified iteration. Results will beincluded in the heap dump file.

Typepicklist

ActionScriptType

PropertiesCreate, Filter, Group, Restricted picklist, Sort, Update

DescriptionIndicates whether the ActionScript is written in Apex or SOQL. Validvalues are:• None

• Apex

• SOQL


Typereference

ExecutableEntityId

PropertiesCreate, Filter, Group, Sort,

DescriptionThe ID of the Apex class or trigger being executed. This field is required.

TypedateTime

ExpirationDate

PropertiesCreate, Filter, Sort, Update

DescriptionThe expiration date of the overlay action. This field is required.

Typeboolean

IsDumpingHeap

21

ApexExecutionOverlayActionObject Reference

DetailsField Name

PropertiesCreate, Defaulted on create, Filter, Group, Sort, Update

DescriptionIndicates whether a heap dump is generated (true) or not (false). Toexecute the ActionScript without generating a heap dump, set thisfield to false.


Typeint

Iteration

PropertiesCreate, Filter, Group, Sort, Update

DescriptionThe number of times the specified line should execute before the heapdump is generated. This field is required.

Typeint

Line


DescriptionThe line number of the heap dump marker. This field is required.

Typereference

ScopeId


DescriptionThe user who executed the action. This field is required.

UsageWhen you are troubleshooting a runtime issue, you often want to find out more about the state of a variable or the state ofthe database, or create a specific condition to test your code. Use ApexExecutionOverlayAction to overlay a diagnostic outputon an Apex class or trigger without compromising production code.

ApexExecutionOverlayResultRepresents the result from the Apex code snippet or SOQL query defined in the associated ApexExecutionOverlayAction,and the resulting heap dump if one was returned.


22

ApexExecutionOverlayResultObject Reference

Supported SOAP Callsquery(), retrieve(), delete()

Supported REST HTTP MethodsQuery, GET, DELETE

Fields

DetailsField Name

Typestring

ActionScript

PropertiesNillable

DescriptionThe Apex code or SOQL query that was run.

Typepicklist

ActionScriptType

PropertiesFilter, Group, Sort, Nillable

DescriptionIndicates whether the ActionScript is written in Apex or SOQL. Validvalues are:• None

• Apex

• SOQL

TypeApexResult

ApexResult

PropertiesNillable

DescriptionA complex type that represents the result of Apex code executed as partof an ApexExecutionOverlayAction, returned in anApexExecutionOverlayResult.

TypedateTime

ExpirationDate


DescriptionThe expiration date of the overlay action.

23


DetailsField Name

TypeHeapDump

HeapDump

PropertiesNillable

DescriptionA complex type that represents a heap dump in anApexExecutionOverlayResult.

Typeboolean

IsDumpingHeap

PropertiesDefaulted on create, Filter, Group, Sort

DescriptionIndicates whether a heap dump was generated (true) or not (false).

Typeint

Iteration


DescriptionThe number of times the specified line should execute before the heapdump is generated. This field is required.

Typeint

Line


DescriptionThe line number of the checkpoint.

TypeSOQLResult

SOQLResult

PropertiesNillable

DescriptionA complex type that represents the result of a SOQL query in anApexExecutionOverlayResult.

Typereference

UserId

24


DetailsField Name

PropertiesFilter, Group, Sort,

DescriptionThe user who executed the action.

UsageWhen you are troubleshooting a runtime issue, you often want to find out more about the state of a variable or the state ofthe database, or create a specific condition to test your code. Use ApexExecutionOverlayAction to overlay a diagnostic outputon an Apex class or trigger without compromising production code, and use ApexExecutionOverlayResult to navigate theresults.

ApexLogRepresents a debug log.

To retrieve a raw log by ID, use the REST resource: /sobjects/ApexLog/id/Body/. (Available from API version 28.0or later.)

Supported SOAP Callsdelete(), describeSObjects(), query(), retrieve()

Supported REST HTTP MethodsQuery, GET, DELETE

Fields

DetailsField

Typetextarea

Application


DescriptionThis value depends on the client type that triggered the log or heap dump.• For API clients, this value is the client ID.• For browser clients, this value is Browser.


Typeint

DurationMilliseconds


DescriptionThe duration of the transaction in milliseconds. This field is required.

25

ApexLogObject Reference

DetailsField

Typepicklist

Location

PropertiesFilter, Group, Sort, Nillable, Restricted picklist

DescriptionSpecifies the location of the origin of the log or heap dump. Values are:• Monitoring — Generated as part of debug log monitoring and visible to all

administrators. These types of logs are maintained until the user or the systemoverwrites them.

• SystemLog — Generated as part of system log monitoring and visible only toyou. These types of logs are only maintained for 60 minutes or until the userclears them.

• Preserved — A system log that is maintained longer than 60 minutes. Usedfor internal support.

Typeint

LogLength


DescriptionLength of the log or heap dump in bytes. This field is required.

Typereference

LogUserId


DescriptionID of the user whose actions triggered the debug log or heap dump.

Typestring

Operation


DescriptionName of the operation that triggered the debug log or heap dump, such as APEXSOAP,Apex Sharing Recalculation, and so on. This field is required.

Typestring

Request


26

ApexLogObject Reference

DetailsField

DescriptionRequest type. Values are:• API — Request came from an API.• Application — Request came from the Salesforce user interface.


TypedateTime

StartTime


DescriptionStart time of the transaction. This field is required.

Typestring

Status


DescriptionStatus of the transaction. This value is either Success, or the text of an unhandledApex exception. This field is required.

ApexPageRepresents the saved copy of an Apex page. ApexPage uses the cached version of the class unless one is unavailable.


To edit, save, or compile Apex pages, use ApexPageMember.



UsageTo retrieve information about an Apex page, create an ApexPage object that references it. For example code, see Using ToolingSOAP API.

To edit, save, or compile Apex pages, use ApexPageMember.

ApexPageMemberRepresents the working copy of a Visualforce page for editing, saving or compiling in a MetadataContainer.

27

ApexPageObject Reference



Fields

DetailsField Name

Typestring

Body


DescriptionThe data for the Visualforce page.


Typestring

Content

PropertiesNone

DescriptionA string representation of ApexPageMetadata that lists the version, status,and packaged versions of the corresponding Visualforce page.

Typereference

ContentEntityId


DescriptionA reference to a Visualforce page.

There can be only one ContentEntityId per ApexPageMember,otherwise, an error is reported.


TypedateTime

LastSyncDate


DescriptionThe date that this ApexPageMember Body was replicated from theunderlying entity.

28

ApexPageMemberObject Reference

DetailsField Name

When you deploy a MetadataContainer, this value is compared with theLastModifiedDate of the underlying Visualforce page. IfLastSyncDate is older than LastModifiedDate, the deployment failswith an error.

TypeApexPageMetadata

Metadata

PropertiesNone

DescriptionAn object that describes the version, status, and packaged versions of thecorresponding Visualforce page.

Typereference

MetadataContainerId





UsageTo edit, save, or compile a Visualforce page, create an ApexPageMember object that references it. To create a new Visualforcepage, use the Force.com REST API or the Metadata API.

Note: Once an ApexPageMember is successfully deployed in a MetadataContainer, the MetadataContainerIdis changed to the ID of the ContainerAsyncRequest, and the ApexPageMember can’t be modified or reused.

Visualforce pages and components are often dependent on each other for functionality. To successfully save and compile agroup of related source files, put the corresponding ApexPageMember and ApexComponentMember objects in a singleMetadataContainer object. Use ContainerAsyncRequest to send the MetadataContainer to the application server.

Each ApexPageMember object can only refer to a single MetadataContainer object. Multiple ApexPageMember objects canrefer to the same MetadataContainer object.


29

ApexPageMemberObject Reference



ApexResultA complex type that represents the result of Apex code executed as part of an ApexExecutionOverlayAction, returned in anApexExecutionOverlayResult.


Fields

DetailsField

Typestring

apexError

DescriptionThe error text returned if the execution was unsuccessful.

TypeExecuteAnonymousResult

apexExecutionResult

DescriptionThe structured result returned from a successful execution.

ExecuteAnonymousResult includes the following fields:• column

• compileProblem

• compiled

• exceptionMessage

• exceptionStackTrace

• line

• success

Note: ExecuteAnonymousResult is outside the current execution context;it does not provide access to variables in the heap.

UsageOverlay Apex on checkpoints to capture structured debugging information.

ApexTriggerRepresents the saved copy of an Apex page. ApexTrigger uses the cached version of the class unless one is unavailable.


To edit, save, or compile Apex triggers, use ApexTriggerMember.


30

ApexResultObject Reference


UsageTo retrieve information about an Apex trigger, create an ApexTrigger object that references it. For example code, see UsingTooling SOAP API.

To edit, save, or compile Apex triggers, use ApexTriggerMember.

ApexTriggerMemberRepresents the working copy of an Apex trigger for editing, saving or compiling in a MetadataContainer.



Fields

DetailsField Name

Typestring

Body


DescriptionThe data for the Apex trigger.


Typestring

Content

PropertiesNone

DescriptionA string representation of ApexTriggerMetadata that lists the version,status, and packaged versions of the corresponding Apex trigger.

Typereference

ContentEntityId


DescriptionA reference to an Apex trigger.

31

ApexTriggerMemberObject Reference

DetailsField Name

There can be only one ContentEntityId per ApexTriggerMember,otherwise, an error is reported.


TypedateTime

LastSyncDate


DescriptionThe date that this ApexTriggerMember Body was replicated from theunderlying entity.

When you deploy a MetadataContainer, this value is compared with theLastModifiedDate of the underlying Apex trigger. If LastSyncDateis older than LastModifiedDate, the deployment fails with an error.

TypeApexTriggerMetadata

Metadata

PropertiesNone

DescriptionAn object that describes the version, status, and packaged versions of thecorresponding Apex trigger.

Typereference

MetadataContainerId





TypeSymbolTable

SymbolTable

PropertiesNillable


32

ApexTriggerMemberObject Reference

DetailsField Name

This field is null if the symbol table cannot be created. A symbol tablecannot be created if the content referenced by the ContentEntityIdfield doesn’t use a symbol table, or if compiler errors for the last deploymentof the MetadataContainer in the MetadataContainerId field preventeda symbol table from being created.

UsageTo edit, save, or compile an Apex trigger, create an ApexTriggerMember object that references it. To create a new trigger,use the Force.com REST API or the Metadata API.

Note: Once an ApexTriggerMember is successfully deployed in a MetadataContainer, the MetadataContainerIdis changed to the ID of the ContainerAsyncRequest, and the ApexTriggerMember can’t be modified or reused.

Apex triggers and classes are often dependent on each other for functionality. For example, a method in one class can call amethod in another class. If source file A is dependent on modified source file B and you try to save and compile source file Abefore you’ve saved the changes to source file B, the compiler will throw an error. To successfully save and compile a groupof related source files, put the corresponding ApexTriggerMember and ApexClassMember objects in a single MetadataContainerobject. Use ContainerAsyncRequest to send the MetadataContainer to the application server.

Each ApexTriggerMember object can only refer to a single MetadataContainer object. Multiple ApexTriggerMember objectscan refer to the same MetadataContainer object.


ContainerAsyncRequestAllows you to compile and asynchronously deploy a MetadataContainer object to your organization.

Supported SOAP API Callscreate(), describeSObjects(), query(), retrieve()

Supported REST API HTTP MethodsQuery, GET, POST

Fields

DetailsField Name

Typetextarea

CompilerErrors

PropertiesNillable

DescriptionErrors reported by the compiler during an asynchronous request.

33

ContainerAsyncRequestObject Reference



DetailsField Name

Typetextarea

ErrorMsg

PropertiesNillable

DescriptionErrors reported during an asynchronous request.

Typeboolean

IsCheckOnly

PropertiesCreate, Defaulted on create, Filter, Group, Sort

DescriptionIndicates whether the asynchronous request compiles the code withoutmaking any changes to the organization (true) or compiles and saves thecode (false).


Note: You can compile without saving but you can’t save withoutcompiling.

Typeboolean

IsRunTests

PropertiesNone

DescriptionReserved for future use.

Typereference

MetadataContainerId


DescriptionThe ID of a MetadataContainer object.

Specify a MetadataContainerId or aMetadataContainerMemberId, but not both.

Typereference

MetadataContainerMemberId

PropertiesCreate, Filter, Group, Nillable, Sort

34

ContainerAsyncRequestObject Reference

DetailsField Name

DescriptionThe ID of an ApexClassMember, ApexTriggerMember,ApexPageMember or ApexComponentMember object.

Specify a MetadataContainerId or aMetadataContainerMemberId, but not both.

Typepicklist

State

PropertiesFilter, Group, Restricted picklist, Sort

DescriptionThe state of the request. Valid values are:• Queued—the job is in the queue.• Invalidated—Salesforce cancelled the job because the results might

not be valid. This state occurs if someone changes the containermembers while IsCheckOnly=true, or if a newer compile requestis added to the queue.

• Completed—the compilation or deployment finished. TheSymbolTable fields for the specified object(s) were successfullyupdated. If IsCheckOnly is false, the Body for each object wassaved and the MetadataContainerId field for each object was resetfrom the ID of the deployed MetadataContainer to the ID of thecorresponding ContainerAsyncRequest object.

• Failed—the compilation or deployment failed for the reasons statedin the CompilerError field.

• Error—an unexpected error occurred. The messages in the ErrorMsgfield can be provided to Salesforce support if the issue persists.

• Aborted—use this value to delete a queued deployment.


UsageWhen you deploy a ContainerAsyncRequest, you must specify whether to save the compiled entities:

• To compile entities without saving, set the request to IsCheckOnly=true. This option is only supported if aMetadataContainerMember is specified. A single MetadataContainerMemberId can’t be compiled without saving.

• To compile and save entities to your organization, set the request to IsCheckOnly=false.

If the compile succeeds, the SymbolTable field is updated on each object in the specified MetadataContainer. If the save orcompile fails and a SymbolTable field cannot be updated, the field is cleared. If there is an outstanding save request, allupdates, inserts, and deployments fail.

To terminate a queued deployment, set the State field to Aborted.

CustomFieldRepresents a custom field on a custom object that stores data unique to your organization. Includes access to the associatedCustomField object in Salesforce Metadata API.

35

CustomFieldObject Reference


Supported SOAP Callscreate(), query(), retrieve(), update(), upsert()

Supported REST HTTP MethodsQuery, GET, POST, PATCH

Fields

DetailsField Name

Typestring

DeveloperName


DescriptionThe developer’s internal name for the custom field (for example “CF_c”).

Typestring

FullName

PropertiesGroup, Nillable

DescriptionThe full name of the custom field.

TypeCustomFieldMetadata

Metadata

PropertiesCreate, Update, Nillable

DescriptionCustomFieldMetadata includes the following fields:• caseSensitive

• customDataType

• defaultValue

• deleteConstraint

• deprecated

• description

• displayFormat

• displayLocationInDecimal

• escapeMarkup

• externalDeveloperName

• externalId

• formula

• formulaTreatBlanksAs

36


DetailsField Name

• inlineHelpText

• isFilteringDisabled

• isNameField

• isSortingDisabled

• label

• length

• maskChar

• maskType

• picklist

• populateExistingRows

• precision

• readOnlyProxy

• referenceTo

• relationshipLabel

• relationshipName

• relationshipOrder

• reparentableMasterDetai

• required

• restrictedAdminField

• scale

• startingNumber

• stripMarkup

• summarizedField

• summaryFilterItems

• summaryForeignKey

• summaryOperation

• trackFeedHistory

• trackHistory

• type

• unique

• visibleLines

• writeRequiresMasterRead

Typestring

NamespacePrefix


DescriptionThe namespace of the custom field. A custom field can be in an extensionnamespace different than the object.

Typepicklist

TableEnumOrId


37


DetailsField Name

DescriptionThe enum (for example, Account) or ID of the object this field is on.

FieldHistoryRetentionJobSpecifies the date range for the retention of field history data, beyond the standard 18 months of data retention that Salesforceprovides. The specified retention period cannot be less than 18 months.


Note: The FieldHistoryRetentionJob object is currently available through a limited pilot program. Contact yoursalesforce.com representative to see if your organization qualifies.

Supported SOAP API Callscreate(), describeSObjects(), query(), retrieve()

Supported REST API HTTP MethodsGET, POST

Fields

DetailsField Name

Typereference

CreatedById

PropertiesDefault on create, Filter, Group, Sort

DescriptionThe user ID of the user who created the field history retention job.

TypedateTime

CreatedDate

PropertiesDefault on create, Filter, Sort

DescriptionThe date the record was saved.

Typeint

DurationSeconds

PropertiesFilter, Group, Nillable, Sort

38

FieldHistoryRetentionJobObject Reference

DetailsField Name

DescriptionHow many seconds the field history retention job took to complete (eithersuccessfully or with failures).

Typepicklist

FieldHistoryType

PropertiesCreate, Filter, Group, Nillable, Restricted picklist, Sort

DescriptionThe standard Salesforce object type containing the field history you wantto retain. Valid values are:• Account

• Contact

• Leads

• Opportunity

Typeint

NumberOfRowsRetained

PropertiesFilter, Group, Nillable, Sort

DescriptionThe number of field history rows a field history retention job has retained.

TypedateTime

RetainOlderThanDate

PropertiesCreate, Filter, Sort

DescriptionThe date and time before which all field history data will be retained.

TypedateTime

StartDate

PropertiesFilter, Nillable, Sort

DescriptionThe start date of the field history retention job.

Typepicklist

Status

PropertiesFilter, Group, Nillable, Restricted picklist, Sort

39

FieldHistoryRetentionJobObject Reference

DetailsField Name

DescriptionProvides the status of the field history retention job. Valid values are:• Scheduled

• Running

• Succeeded

• Failed

HeapDumpA complex type that represents a heap dump in an ApexExecutionOverlayResult.


Fields

DetailsField

Typestring

className

DescriptionThe name of the Apex class or trigger.

Typearray of TypeExtent

extents

DescriptionTypeExtent includes the following fields:• collectionType

• count

• definition (array of AttributeDefinition)• extent (array of HeapAddress)• totalSize

• typeName

TypedateTime

heapDumpDate

DescriptionThe date and time that the heap dump was captured.

Typestring

namespace

DescriptionThe namespace of the Apex class or trigger. Null if there is no namespace.

40

HeapDumpObject Reference

UsageUse heap dumps to capture structured debugging information.

MetadataContainerManages working copies of ApexClassMember, ApexTriggerMember, ApexPageMember and ApexComponentMemberobjects, including collections of objects that should be deployed together.



Fields

DetailsField Name

Typestring

Name


DescriptionThe name of the MetadataContainer. If a container with the same namealready exists, an error is reported on create() or POST.


UsageUse a MetadataContainer as a package for your tool’s workspace. As a user works in the tool, update the ApexClassMember,ApexTriggerMember, ApexPageMember and ApexComponentMember objects in the MetadataContainer and use aContainerAsyncRequest object to save and deploy changes to the current organization.

A MetadataContainer can be reused, but container members can’t.

• When a ContainerAsyncRequest completes successfully, the MetadataContainerId field on all container members ischanged from the ID of the MetadataContainer to the ID of the ContainerAsyncRequest. At this point, container memberscan no longer be modified or deployed, and can’t be queried via the MetadataContainer; you have to query theContainerAsyncRequest to see what was deployed.

• If the deployment fails, container members remain on the MetadataContainer and can still be modified until they aresuccessfully deployed on another ContainerAsyncRequest. The MetadataContainerId field on the completed (faileddeployment) ContainerAsyncRequest is set to the ID of the MetadataContainer, so you can have multiple completedContainerAsyncRequests on a single MetadataContainer.

41

MetadataContainerObject Reference

Note: Deleting a MetadataContainer deletes all objects that reference it.

See Also:Metadata API Developer's Guide

SOQLResultA complex type that represents the result of a SOQL query in an ApexExecutionOverlayResult.


Fields

DetailsField

Typestring

queryError

DescriptionThe error text returned if the execution was unsuccessful.

TypeQueryResultMetadata

queryMetadata

DescriptionThe structured result returned from a successful execution.

QueryResultMetadata includes the following fields:• columnMetadata

• entityName

• groupBy

• idSelected

• keyPrefix

Typearray of MapValue

queryResult

Description

MapValue contains an array of MapEntry, which contains the following fields:• keyDisplayValue

• value (reference to StateValue)

UsageOverlay SOQL on checkpoints to capture structured debugging information.

42

SOQLResultObject Reference


StaticResourceRepresents the working copy of a static resource file for editing or saving. Static resources allow you to upload content thatyou can reference in a Visualforce page, including images, stylesheets, JavaScript, and other files.




Fields

DetailsField Name

Typestring

Name


DescriptionThe static resource name. The name can only contain characters, letters,and the underscore (_) character, must start with a letter, and cannot endwith an underscore or contain two consecutive underscore characters

Typestring

Body


DescriptionThe data for the static resource file.

Typestring

ContentType


DescriptionRequired. The content type of the file, for example text/plain.

Typestring

CacheControl


43

StaticResourceObject Reference

DetailsField Name

Description

Required. Indicates whether the static resource is marked with a publiccaching tag so that a third-party delivery client can cache the content. The valid values are:

• Private

• Public

UsageTo create, edit, or save a static resource file, create a StaticResource object that references it.

SymbolTableA complex type that represents all user-defined tokens in the Body of an ApexClass, ApexClassMember, or ApexTriggerMemberand their associated line and column locations within the Body.

Fields

DetailsField

Typearray of Constructor

constructors

DescriptionContains the position, scope and signature of constructors for the Apex class. Apextriggers don't have constructors.

Constructor includes the following fields:• location

• modifiers

• name

• references

• visibility (scope: Global, Public or Private)• parameters

Typearray of ExternalReference

externalReferences

DescriptionContains the name, namespace, and external class, method and variable referencesfor the Apex class or trigger. These references can be used for symbol highlightingor code navigation.

ExternalReference includes the following fields:• methods

• modifiers

• name

• namespace

• references

44

SymbolTableObject Reference

DetailsField

• variables

Typearray of SymbolTable

innerClasses

DescriptionContains a symbol table for each inner class of the Apex class or trigger.

Typearray of String

interfaces

DescriptionContains a set of strings for each interface with the namespace and name, for example:['System.Batchable', 'MyNamespace.MyInterface'].

Typearray of Method

methods

DescriptionContains the position, name, scope, signature, and return type of available Apexmethods.

Method includes the following fields:• location

• modifiers

• name

• references

• visibility (scope: Global, Public or Private)• parameters

• returnType

Typestring

name

DescriptionThe name of the Apex class or trigger.

Typestring

namespace

DescriptionThe namespace of the Apex class or trigger. Null if there is no namespace.

Typearray of VisibilitySymbol

properties

DescriptionContains the position, name, scope, and references of properties for the Apex classor trigger.

45

SymbolTableObject Reference

DetailsField

VisibilitySymbol includes the following fields:• location

• modifiers

• name

• references

• visibility (scope: Global, Public or Private)

Typearray of Symbol

tableDeclaration

DescriptionContains the position, name, and references of the Apex class or trigger.

Symbol includes the following fields:• location

• modifiers

• name

• references

Typearray of Symbol

variables

DescriptionContains the position, name and references of related variables.

Symbol includes the following fields:• location

• modifiers

• name

• references

UsageUse symbol tables instead of building a parser or compiler. Symbol tables allow you to do symbol highlighting, code navigation,code completion, symbol searches, and more.

A symbol table cannot be created if the content referenced by the ContentEntityId field doesn’t use a symbol table, or ifcompiler errors for the last deployment of the MetadataContainer in the MetadataContainerId field prevented a symboltable from being created.

TraceFlagRepresents a trace flag that triggers an Apex debug log at the specified logging level.



46

TraceFlagObject Reference

Fields

DetailsField Name

Typepicklist

ApexCode


DescriptionThe log category level for Apex code. Includes information about Apexcode and can include information such as log messages generated by datamanipulation language (DML) statements, inline SOQL or SOSL queries,the start and completion of any triggers, the start and completion of anytest method, and so on. The following are valid values.• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error


Typepicklist

ApexProfiling


DescriptionThe log category level for profiling information. Includes cumulativeprofiling information, such as the limits for your namespace, the numberof emails sent, and so on. The following are valid values.• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error


Typepicklist

Callout


47


DetailsField Name

DescriptionThe log category level for callouts. Includes the request-response XMLthat the server is sending and receiving from an external Web service. Thisis useful when debugging issues related to SOAP API calls. The followingare valid values.• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error


Typepicklist

Database


DescriptionThe log category for database activity. Includes information about databaseactivity, including every DML statement or inline SOQL or SOSL query.The following are valid values.• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error


TypedateTime

ExpirationDate

PropertiesCreate, Filter, Sort, Update

DescriptionThe date and time that the trace flag expires. This field is required.

Typereference

ScopeId

PropertiesCreate, Filter, Group, Nillable, Sort, Update

48


DetailsField Name

DescriptionA reference to a user. This field is used with the TracedEntityID field.• When ScopeId=user the actions of the user/entity specified by

TracedEntityID (user, Apex class or Apex trigger) are traced to thesystem log at the described level. System logs are visible only to you.Use this scope for class-level filtering. If there are both user andentity-level flags, the user flags take precedence until a method froma class with an entity trace flag is entered. When the method returns,the user trace flags are restored.

• When ScopeId=emptyid the user’s actions are traced to theorganization’s debug log at the described level. Debug logs are visibleto all administrators. This option is only available if TracedEntityIDreferences a user (not an Apex class or Apex trigger). The variableemptyid can be the value 0000000000000000 or null.

The scope defined here is reflected in the ApexLog Location field.

Typepicklist

System


DescriptionThe log category level for calls to all system methods, such as theSystem.debug method. The following are valid values.• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error


Typereference

TracedEntityId


DescriptionA reference to the following:• Apex class• Apex trigger• User

This field is used with the ScopeId field. This field is required.

49


DetailsField Name

Typepicklist

Validation


DescriptionThe log category level for validation rules. Includes information aboutvalidation rules, such as the name of the rule, whether the rule evaluatedtrue or false, and so on. The following are valid values.• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error


Typepicklist

Visualforce


DescriptionThe log category level for Visualforce. Includes information aboutVisualforce events, including serialization and deserialization of the viewstate or the evaluation of a formula field in a Visualforce page. Thefollowing are valid values.• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error


Typepicklist

Workflow


DescriptionThe log category level for workflow rules. Includes information forworkflow rules, such as the rule name, the actions taken, and so on. Thisfield is required. The following are valid values.

50


DetailsField Name

• Finest

• Finer

• Fine

• Debug

• Info

• Warn

• Error

UsageTo diagnose a functional issue or a performance problem, use the TraceFlag object to set up logging for yourself or for anotheruser. The following options are available:

• To set up a log for a specific user, set ScopeId to null and TracedEntityId to the ID of the user. This option can onlybe configured for a user, not an Apex class or Apex trigger.

• To configure logging levels for system logs (visible only to you), set ScopeId to user and TracedEntityId to the IDof the logged-in user.

• To set up a system log (visible only to you) for a specific Apex class or trigger, set ScopeId to user and TracedEntityIdto the ID of the Apex class or trigger.

The example below creates a new trace flag and attaches it to an end user.

//create a new TraceFlag objectTraceFlag traceFlag = new TraceFlag();traceFlag.ApexCode = "Finest";traceFlag.ApexProfiling = "Finest";traceFlag.Callout = "Info";traceFlag.Database = "Finest";traceFlag.System = "Debug";traceFlag.Validation = "Info";traceFlag.Visualforce = "Info";traceFlag.Workflow = "Info";

//set an expiration datetraceFlag.ExpirationDate = myTimestamp;//set the ID of the user to monitortraceFlag.TracedEntityId = "005A0000000i93O";

//call the create methodTraceFlag[] traceFlags = { traceFlag };SaveResult[] traceResults = sforce.create(traceFlags);for (int i = 0; i < traceResults.Length; i++){

if (traceResults[i].success){

Console.WriteLine("Successfully created trace flag: " +traceResults[i].id);

}else{

Console.WriteLine("Error: could not create trace flag ");Console.WriteLine(" The error reported was: " +traceResults[i].errors[0].message + "\n");

}}

51


ValidationRuleRepresents a formula that is used for specifying when a criteria is met. This includes both validation rules and workflow rules.Includes access to the associated ValidationRule object in Salesforce Metadata API.


Supported SOAP Callscreate(), query(), retrieve(), update(), upsert()

Supported REST HTTP MethodsQuery, GET, POST, PATCH

Fields

DetailsField Name

Typestring

FullName

PropertiesGroup, Nillable.

DescriptionThe Metadata API full name.

Typeid

Id

PropertiesFilter, Group, Sort.

DescriptionThe ID of a specific validation rule.

Typedatetime

LastModifiedDate

PropertiesFilter, Sort.

DescriptionLast modified date.

TypeValidationRuleMetadata

Metadata

PropertiesCreate, Nillable, Update.

DescriptionValidation rule metadata.

52

ValidationRuleObject Reference

DetailsField Name

Typestring

NamespacePrefix

PropertiesFilter, Group, Nillable, Sort.

DescriptionThe namespace prefix.

Typepicklist

TableEnumOrId



Typestring

ValidationName

PropertiesCreate, Filter, Group, Sort, Update.

DescriptionThe enum name or ID of entity this rule is associated with.

WorkflowRuleRepresents a workflow rule that is used to fire off a specific workflow action when the specified criteria is met. Creation andmodification of workflow rules isn't supported. Includes access to the associated WorkflowRule object in Salesforce MetadataAPI.


Supported SOAP Callscreate(), query(), retrieve()

Supported REST HTTP MethodsQuery, GET

Fields

DetailsField Name

Typestring

FullName

53

WorkflowRuleObject Reference

DetailsField Name

PropertiesGroup, Nillable.

DescriptionThe Metadata API full name.

Typeid

Id


DescriptionThe ID of a specific workflow rule.

Typedatetime

LastModifiedDate

PropertiesFilter, Sort.

DescriptionLast modified date.

TypeWorkflowRuleMetadata

Metadata

PropertiesNillable.

DescriptionWorkflow rule metadata.

Typestring

Name

PropertiesCreate, Filter, Group, Sort.

DescriptionThe enum name or ID of entity this rule is associated with.

Typestring

NamespacePrefix

PropertiesFilter, Group, Nillable, Sort.

DescriptionThe namespace prefix.

54


DetailsField Name

Typepicklist

TableEnumOrId



55


Index

A

ApexDebugging 20, 22, 25, 46Deploying 33, 41Editing 12–13, 27, 30–31Saving 12, 27, 30Saving and compiling 13, 31, 33, 41Viewing code coverage 15, 17

ApexClass object 12ApexClassMember object 13ApexCodeCoverage object 15ApexCodeCoverageAggregate object 17ApexComponent object 18ApexComponentMember object 18ApexExecutionOverlayAction object 20ApexExecutionOverlayResult object 22ApexLog object 25ApexPage object 27ApexPageMember object 27ApexResult object 30ApexTrigger object 30ApexTriggerMember object 31

C

Checkpoint 30, 40, 42ContainerAsyncRequest object 33CSS

Editing 43CustomField object 35

D

Debugging 25, 46Debugging Apex 20, 22Deploying Apex 33, 41Deploying Visualforce 33, 41Developer Console 1

E

Editing Apex 12–13, 27, 30–31Editing Visualforce 18, 27

F

FieldHistoryRetentionJob object 38

G

Generating heap dumps 20, 22, 25

H

Heap dump 40Heap dumps 20, 22, 25HeapDump object 40

J

JavaScriptEditing 43

L

Log 30, 40, 42Logging 25, 46

M

MetadataContainer object 41

O

ObjectsApexClass 12ApexClassMember 13ApexCodeCoverage 15ApexCodeCoverageAggregate 17ApexComponent 18ApexComponentMember 18ApexExecutionOverlayAction 20ApexExecutionOverlayResult 22ApexLog 25ApexPage 27ApexPageMember 27ApexResult 30ApexTrigger 30ApexTriggerMember 31ContainerAsyncRequest 33CustomField 35FieldHistoryRetentionJob 38HeapDump 40MetadataContainer 41SOQLResult 42StaticResource 43SymbolTable 44TraceFlag 46ValidationRule 52WorkflowRule 53

Overview 1

R

REST API 2

56

Index

S

Saving and compiling Apex 13, 31, 33, 41Saving and compiling Visualforce 18, 27, 33, 41Selecting the right API 2SOAP API 4SOQLResult object 42Standard objects 10StaticResource object 43Symbol tables 44SymbolTable object 44

T

Tasks 1TraceFlag object 46

V

ValidationRule object 52Visualforce

Deploying 33, 41Editing 18, 27Saving and compiling 18, 27, 33, 41

W

WorkflowRule object 53

X

XMLEditing 43

57

Index

Documents

API Tooling