Salesforce.com API AppExchange Web Services Developer’s Guide

perform text searches across your organization’s information ( search call)

, and retrieve calls)

•

•

create, update, and delete data ( create

, update ,

upsert , and

delete calls)

• perform administrative tasks, such as retrieving user information (

call), changing passwords (

setPassword and

( getServerTimestamp call)

calls), and getting the system time

Page 1

AppExchange API

• replicate data locally (

and

obtain and navigate metadata about your organization’s data ( describeGlobal ,

calls)

•

calls)

For each operation, client applications submit a synchronous request to the AppExchange Web service, await the Web service’s response, and process the results. The AppExchange Web service commits any changed data automatically. For detailed information about supported Web

service operations, see API Calls

on page 31 and API Utility Calls on page 125.

AppExchange Objects and the API

You can use the API to perform query, insert, update, and delete operations on Salesforce data via the AppExchange objects. Objects are programmatic representations of your organization’s

Salesforce data. Object properties represent fields in those data entities, and client applications set or retrieve data values via these properties. For example, accounts are represented by an

Account object, and an Account object has fields that represent the account name, phone

number, shipping address, and so on. For detailed information about AppExchange objects, see

API Objects on page 132.

Supported Salesforce Editions

To use the API, your organization must use Enterprise Edition or Unlimited Edition. If you are an existing Salesforce customer and want to upgrade to either Enterprise or Unlimited Edition, contact your account representative.

To develop Web service client applications, it is strongly recommended that you use Salesforce

Developer Edition. Developer Edition provides access to all of the features available with

Enterprise Edition—it is constrained only by the number of users and the amount of storage space. Developer Edition provides a development context that allows you to build and test your solutions without impacting your organization’s live data. Developer Edition accounts are available for free at http://www.salesforce.com/developer .

Standards Compliance

The API is implemented to comply with the following specifications:

Standard Name

Simple Object Access Protocol

(SOAP) 1.1

Web Service Description

Language (WSDL) 1.1

WS-I Basic Profile 1.1

Website

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ http://www.w3.org/TR/2001/NOTE-wsdl-20010315 http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-

24.html

Development Platforms

The API works with modern SOAP development environments, including, but not limited to,

Visual Studio .NET 2003, and Apache Axis. In this document, we provide examples in Java and

C# (.NET). The Java examples are based on Apache Axis 1.3 and JDK 5.0 (Java 2 Platform

Standard Edition Development Kit 5.0). For more information about Apache Axis 1.3, go to http:/

/ws.apache.org/axis/ . To see a complete list of compatible development platforms and more sample code, go to http://www.salesforce.com/developer .

Page 2

AppExchange API

Note

Development platforms vary in their SOAP implementations. Implementation differences in certain development platforms might prevent access to some or all of the features in the API. If you are using Visual Studio for .NET development, we recommend that you use Visual Studio

2003 or higher.

Go to the Developer Web Site For More Information

The Salesforce.com Developer Web site provides a full suite of developer toolkits, sample code, sample SOAP messages, community-based support, and other resources to help you with your development projects. Be sure to visit http://www.salesforce.com/developer and sign up for a free Developer Edition account.

W

HAT

’

S

N

EW IN

V

ERSION

7.0

This topic describes what’s new in the API version 7.0.

Release Note

On the Salesforce.com Developer Web site, visit http://www.salesforce.com/developer/technotes.jsp?tn=TN-17 for a summary of new and changed features in this release of the API.

API Support Policy

It is recommended that your client applications use the most recent version of the AppExchange

WSDL file. When a new version is released, you should follow the steps in this section to:

•

Regenerate the WSDL file (see Step 2: Generate or Obtain the Web Service WSDL on page 4)

•

Import it into your environment (see Step 3: Import the WSDL File Into Your Development

Platform on page 5)

Salesforce strives to make backwards compatibility easy when using the AppExchange platform.

Existing programs written with earlier versions of the API will continue to work unmodified.

Programs that compile and run with “Version N” of the AppExchange WSDL file can generally be recompiled and run with the AppExchange “Version N+1” WSDL file without modification. To prevent writing new programs with API functions that have been scheduled for removal (see below), some functions might not appear in the “Version N+1” WSDL file. The “Version N+1”

WSDL file will likely contain new functionality not found in “Version N”.

In order to mature and improve the quality and performance of the AppExchange Web service,

API functions that are no longer practical or useful may be scheduled for removal. Functions will generally be supported for a minimum of three years (usually longer) from the date of first release. Advanced notice of API removal will be given at least one year before the API is actually removed. Notification will be given to organizations using these APIs again roughly six months before removal and again roughly three months before removal. Notification will be sent via email to all administrators, posted on the Sforce message boards, and published in the Sforce newsletter.

Page 3

AppExchange API

Q

UICK

S

TART

This topic tells you what you need to start using the API in your development environment. It includes the following steps:

•

Step 1: Obtain a Salesforce Developer Edition Account

•

Step 2: Generate or Obtain the Web Service WSDL

•

Step 3: Import the WSDL File Into Your Development Platform

•

Step 4: Walk Through the Sample Code

Note

Before you begin building client applications, you need to install your development platform according to its product documentation. In addition, you should read

Basic Concepts on page 20.

Step 1: Obtain a Salesforce Developer Edition Account

If you are not already a member of the Sforce developer community, go to http:// www.salesforce.com/developer and follow the instructions for signing up for a Developer Edition account. Even if you already have an Enterprise Edition or Unlimited Edition account, it is strongly recommended that you use Developer Edition for developing, staging, and testing your solutions against sample data to protect your organization’s live data. This is especially true for applications that will be inserting, updating, or deleting data (as opposed to simply reading data).

Step 2: Generate or Obtain the Web Service WSDL

To access the AppExchange Web service, you need a Web Service Description Language (WSDL) file. The WSDL file defines the Web service that is available to you. Your development platform uses this WSDL to generate an API to access the AppExchange Web service it defines. You can either obtain the WSDL file from your organization’s Salesforce administrator or you can generate it yourself if you have access WSDL download page in the Salesforce user interface. For more information about WSDL, see http://www.w3.org/TR/wsdl .

WSDL Files for Web Services

There are two AppExchange Web services for which you can obtain WSDL files for API access:

• AppExchange Enterprise Web services API (enterprise WSDL)—This API is for most enterprise users who are developing client applications for their organization. The enterprise

WSDL file is a strongly typed representation of your organization’s data. It provides information about your schema, data types, and fields to your development environment, allowing for a tighter integration between it and the AppExchange Web service. This WSDL changes if custom fields or custom objects are added to, renamed, or removed from, your organization’s Salesforce configuration.

• AppExchange Partner Web services API (Partner WSDL)—This API is for salesforce.com partners who are developing client applications for multiple organizations. As a loosely typed representation of the Salesforce object model, this API can be used to access data within any organization. It is more flexible, although not as easy to use, as its enterprise counterpart.

For more information, see

Using the Partner WSDL on page 277.

Generating the WSDL File for Your Organization

Administrators, and users with the “Modify All Data” permission, can download the Web Services

Description Language (WSDL) file to integrate and extend Salesforce using the API. The WSDL file is dynamically generated based on which type of WSDL file (enterprise or partner) you download. The generated WSDL defines all of the API calls, objects (including standard and custom objects), and fields that are available for API access for your organization.

Page 4

AppExchange API

To generate the WSDL file for your organization:

1. Log in to your Enterprise, Unlimited, or Developer Edition Salesforce account. You must log in as an administrator or as a user who has the “Modify All Data” permission.

2. Click Setup | Integrate | AppExchange API.

3. Click the appropriate link to download the enterprise WSDL (if you are a Salesforce customer) or partner WSDL.

Your browser opens the WSDL file.

4. Save the WSDL file to your local file system.

Note

For the enterprise WSDL file, if new custom fields or objects are added to, renamed, or removed from your organization’s information, you need to regenerate the WSDL file in order to access them.

Step 3: Import the WSDL File Into Your Development Platform

Once you have the WSDL file, you need to import it into your development platform so that your development environment can generate the necessary objects for use in building client Web service applications in that environment. This section provides sample instructions for Apache

Axis and Microsoft Visual Studio. For instructions about other development platforms, see your platform’s product documentation.

Note

The process for importing WSDL files is identical for the enterprise and partner WSDL files.

Instructions for Java Environments (Apache Axis)

Java environments access the API through Java objects that serve as proxies for their serverside counterparts. Before using the API, you must first generate these objects from your organization’s WSDL file.

Each SOAP client has its own tool for this process. For Apache Axis, you use the WSDL2Java utility. For more information about using WSDL2Java, see the following URL: http://ws.apache.org/axis/java/reference.html

Note

Before you run WSDL2Java, you must have Axis installed on your system and all of its component JAR files must be referenced in your classpath.

The basic syntax for WSDL2Java is: java –classpath pathToFirstJAR/FirstJARFilename;pathToSecondJAR/SecondJARFilename org.apache.axis.wsdl.WSDL2Java pathToWsdl/WsdlFilename

For AppExchange WSDL files, the -a switch is recommended to configure WSDL2Java.

The following sample command uses the -a switch: java –classpath pathToFirstJAR/FirstJARFilename;pathToSecondJAR/SecondJARFilename org.apache.axis.wsdl.WSDL2Java -a pathToWsdl/WsdlFilename

This command will generate a set of folders and Java source code files in the same directory in which it was run. After these files are compiled, they can be included in your Java programs for use in creating client applications.

For most Java development environments, you can use Wizard-based tools for this process instead of the command line. For more information about using WSDL2Java with AppExchange, visit the message boards at http://www.salesforce.com/developer/boards.jsp

Instructions for Microsoft Visual Studio

Visual Studio languages access the API through objects that serve as proxies for their serverside counterparts. Before using the API, you must first generate these objects from your organization's WSDL file.

Page 5

AppExchange API

Visual Studio provides two approaches for importing your WSDL file and generating an XML Web service client: an IDE-based approach and a command line approach.

Note

Before you begin, the first step is to create a new application or open an existing application in

Visual Studio. In addition, you need to have generated the WSDL file, as described in Generating the WSDL File for Your Organization on page 4.

An XML Web service client is any component or application that references and uses an XML Web service. This does not necessarily need to be a client-based application. In fact, in many cases, your XML Web service clients might be other Web applications, such as Web Forms or even other

XML Web services. When accessing XML Web services in managed code, a proxy class and the .NET Framework handle all of the infrastructure coding.

To access an XML Web service from managed code:

1. Add a Web reference to your project for the XML Web service that you want to access.

The Web reference creates a proxy class with methods that serve as proxies for each exposed method of the XML Web service.

2. Add the namespace for the Web reference.

3. Create an instance of the proxy class and then access the methods of that class as you would the methods of any other class.

To add a Web reference:

1. On the Project menu, choose Add Web Reference.

2. In the URL box of the Add Web Reference dialog box, type the URL to obtain the service description of the XML Web service you want to access, such as: file:///c:\WSDLFiles\enterprise.wsdl

3. Click the Go button to retrieve information about the XML Web service.

4. In the Web reference name box, rename the Web reference to sforce, which is the namespace you will use for this Web reference.

5. Click Add Reference to add a Web reference for the target XML Web service. For more information, see the topic “Adding and Removing Web References” in the Visual Studio documentation.

6. Visual Studio retrieves the service description and generates a proxy class to interface between your application and the XML Web service.

Note

If you are using Visual Basic .Net and the enterprise WSDL, you will need to modify the generated Web service client to overcome a bug in Visual Studio's client generation utility. The

API exposes two objects (

Case and

described in Sample Code Walkthrough on page 7.

) whose names conflict with Visual Basic keywords.

When the classes that represent these objects are created, Visual Studio wraps the class names with brackets ([Case] and [Event]). This is the method by which you can re-use keywords.

Unfortunately, in the definition of the SObject class, Visual Studio does not wrap these to class references in the System.Xml.Serialization.XmlIncludeAttribute that are part of the

SObject

definition. To work around this problem in Visual Studio, you need to edit the

XmlIncludeAttribute

settings for Case and Event as shown below. This does not apply to C# and only applies when using the enterprise version of the WSDL.

System.Xml.Serialization.XmlIncludeAttribute(GetType([Event])), _

System.Xml.Serialization.XmlIncludeAttribute(GetType([Case])), _

Step 4: Walk Through the Sample Code

Once you have imported your WSDL file, you can begin building client applications that use the

API. The fastest way is to learn by example—start by walking through the code example

Page 6

AppExchange API

S

AMPLE

C

ODE

W

ALKTHROUGH

This topic walks through the following code samples that use the API:

•

Java Sample Code

•

C# Sample Code

Java Sample Code

This section walks through a sample Java client application that uses the Apache Axis SOAP client. The purpose of this sample application is to show the required steps for logging into the login server and to demonstrate the invocation and subsequent handling of several API calls.

This sample application performs the following main tasks:

1. Prompts the user for their Salesforce user name and password.

2. Calls

to log in to the single login server and, if the login succeeds:

•

Sets the returned sessionID into the session header, which is required for session

authentication on subsequent API calls.

• Resets the AppExchange Web service endpoint to the returned

serverUrl , which is the

target of subsequent API calls.

All client applications that access the API must complete the tasks in this step before attempting any subsequent API calls.

3. Calls

describeGlobal to retrieve a list of all available objects for the organization’s data.

4. Calls

to retrieve metadata (field list and object properties) for a specified object.

5. Calls

, passing a simple query string ("select FirstName, LastName from

Contact"

), and iterating through the returned

(a java.net.URL), which is the endpoint of the Web service. For the login call, the parameter

In the following sample code, the API calls and other significant code is identified in a bold font.

In addition, note the error handling code that follows each API call.

Note

The sample client application begins by importing the necessary packages and objects.

package com.doc.samples; import java.io.BufferedReader; import java.io.IOException; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.sforce.soap.enterprise.DescribeGlobalResult; import com.sforce.soap.enterprise.DescribeSObjectResult; import com.sforce.soap.enterprise.Field; import com.sforce.soap.enterprise.FieldType; import com.sforce.soap.enterprise.LoginResult; import com.sforce.soap.enterprise.PicklistEntry; import com.sforce.soap.enterprise.QueryResult; import com.sforce.soap.enterprise.SforceServiceLocator; import com.sforce.soap.enterprise.SoapBindingStub; import com.sforce.soap.enterprise.QueryOptions; import com.sforce.soap.enterprise.SessionHeader; import com.sforce.soap.enterprise.fault.ExceptionCode; import com.sforce.soap.enterprise.fault.LoginFault; import com.sforce.soap.enterprise.sobject.Contact;

/**

*

* Title: Login Sample

*

*

Page 7

AppExchange API

* Description: Console application illustrating login, session management, server redirection,

* and

*

*

*

*

* Company: salesforce.com

*

* @version 7.0

*/ public class Samples {

private SoapBindingStub binding;

private LoginResult loginResult = null;

private String userName = "";

private String password = "";

static BufferedReader rdr = new BufferedReader(new java.io.InputStreamReader(System.in));

public Samples() {

}

public static void main(String[] args) {

Samples samples1 = new Samples();

samples1.run();

}

// Helper function for retrieving user input from the console

String getUserInput(String prompt) {

System.out.print (prompt);

try {

return rdr.readLine();

}

catch (IOException ex) {

return null;

}

/**

* The login function is used to obtain a token from Salesforce. AppExchange

* for 2 hours.

private boolean login() {

userName = getUserInput("Enter user name: ");

password = getUserInput("Enter password: ");

Note

The sample client application retrieves the user’s login credentials.

// Helper function for retrieving user input from the console

String getUserInput(String prompt) {

print(prompt, false);

try {

return rdr.readLine();

}

catch (IOException ex) {

return null;

Page 8

AppExchange API

}

/** The login function is used to obtain a token from Salesforce.

* This token must be passed to all other calls to provide

* authentication and is valid for 2 hours.

private boolean login() {

userName = getUserInput("Enter user name: ");

password = getUserInput("Enter password: ");

Note

Next, the sample client application initializes the binding stub. This is our main interface to the

Web service through which all calls are made. The getSoap method takes an optional parameter

always starts with http(s)://www.salesforce.com. After logging in, the sample client application changes the endpoint to the one specified in the returned

using the URL returned from the LoginResult .

object.

try {

System.out.println("LOGGING IN NOW....");

loginResult = binding.login(userName, password);

} catch (LoginFault ex) {

// The LoginFault derives from AxisFault

ExceptionCode exCode = ex.getExceptionCode();

if (exCode == ExceptionCode.FUNCTIONALITY_NOT_ENABLED ||

exCode==ExceptionCode.INVALID_CLIENT ||

exCode==ExceptionCode.INVALID_LOGIN ||

exCode==ExceptionCode.LOGIN_DURING_RESTRICTED_DOMAIN ||

exCode==ExceptionCode.LOGIN_DURING_RESTRICTED_TIME ||

exCode==ExceptionCode.ORG_LOCKED ||

exCode==ExceptionCode.PASSWORD_LOCKOUT ||

exCode==ExceptionCode.SERVER_UNAVAILABLE ||

exCode==ExceptionCode.TRIAL_EXPIRED ||

exCode==ExceptionCode.UNSUPPORTED_CLIENT){

System.out.println("Please make sure that you have a valid user id and password.");

} else {

// Write the fault code to the console

System.out.println(ex.getExceptionCode());

// Write the fault message to the console

System.out.println("An unexpected error has occurred." + ex.getMessage());

}

return false;

} catch (RemoteException ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

return false;

}

// Check if the password has expired if (loginResult.isPasswordExpired()) {

System.out.println("An error has occurred. Your password has expired.");

return false;

}

Page 9

AppExchange API

Note

Once the client application has logged in successfully, it will use the results of the

call to reset the endpoint of the service to the virtual server instance that is servicing your organization.

To do this, the client application sets the ENDPOINT_ADDRESS_PROPERTY of the binding object

binding._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_PROPERTY, loginResult.getServerUrl());

Note

The sample client application now has an instance of the SoapBindingStub that is pointing to the correct endpoint. Next, the sample client application sets a persistent SOAP header (to be included on all subsequent calls that are made with the SoapBindingStub) that contains the valid sessionId for our login credentials. To do this, the sample client application creates a new

_SessionHeader

object and set its sessionId property to the sessionId property from the

user (see Factors that Affect Data Access on page 32). This call should not be made more than

object.

// Create a new session header object and add the session id

// from the login reutrn object

SessionHeader sh = new SessionHeader();

sh.setSessionId(loginResult.getSessionId());

Note

Next, the sample client application calls the setHeader method of the SoapBindingStub to add the header to all subsequent method calls. This header will persist until the SoapBindingStub is destroyed or until the header is explicitly removed. The “SessionHeader” parameter is the name of the header to be added.

// set the session header for subsequent call authentication

binding.setHeader(new

SforceServiceLocator().getServiceName().getNamespaceURI(), "SessionHeader", sh);

// return true to indicate that we are logged in, pointed

// at the right url and have our security token in place.

return true;

}

Note

To determine the objects that are available to the logged in user, the sample client application executes a

describeGlobal

call, which returns all of the objects that are visible to the logged in

once per session, as the data returned from the call likely does not change frequently. The

DescribeGlobalResult is simply echoed to the console.

private void describeGlobalSample() {

try

{

DescribeGlobalResult describeGlobalResult = null;

describeGlobalResult = binding.describeGlobal();

String[] types = describeGlobalResult.getTypes();

for (int i=0;i<types.length;i++)

System.out.println(types[i]);

getUserInput("\nDescribe global was successful.\n\nHit the enter key to continue....");

}

catch (Exception ex)

{

System.out.println("\nFailed to return types, error message was: \n" + ex.getMessage());

getUserInput("\nHit return to continue...");

}

Page 10

AppExchange API

}

Note

The following code segment illustrates the type of metadata information that can be obtained for each object available to the user. The sample client application executes a

describeSObject

call

on a given object and then echoes the returned metadata information to the console. Object metadata information includes permissions, field types and lengths, and available values for picklist fields and types for referenceTo fields.

private void describeSample() {

String objectToDescribe = getUserInput("\nType the name of the object to describe (try Account): ");

try {

DescribeSObjectResult descSObjectRslt = null;

descSObjectRslt= binding.describeSObject(objectToDescribe);

if (!(descSObjectRslt == null)) {

// Report object level information

Field[] fields=descSObjectRslt.getFields();

String objectName=descSObjectRslt.getName();

boolean isActivateable=descSObjectRslt.isActivateable();

boolean isCreateable=descSObjectRslt.isCreateable();

boolean isCustom=descSObjectRslt.isCustom();

boolean isDeleteable=descSObjectRslt.isDeletable();

boolean isQueryable=descSObjectRslt.isQueryable();

boolean isReplicateable=descSObjectRslt.isReplicateable();

boolean isRetrieveable = descSObjectRslt.isRetrieveable();

boolean isSearchable = descSObjectRslt.isSearchable();

boolean isUndeleteable = descSObjectRslt.isUndeletable();

boolean isUpdateable = descSObjectRslt.isUpdateable();

System.out.println("Metadata for " + objectToDescribe + " object:\n");

System.out.println("Object name = " + objectName);

System.out.println("Number of fields = " + fields.length);

System.out.println("Object can be activated = " + isActivateable);

System.out.println("Can create rows of data = " + isCreateable);

System.out.println("Object is custom object = " + isCustom);

System.out.println("Can delete rows of data = " + isDeleteable);

System.out.println("Can query for rows of data = " + isQueryable);

System.out.println("Object used in replication = " + isReplicateable);

System.out.println("Can retrieve object = " + isRetrieveable);

System.out.println("Can search object = " + isSearchable);

System.out.println("Can un-delete = " + isUndeleteable);

System.out.println("Can update = " + isUpdateable);

System.out.println("\nField metadata for " + objectToDescribe

+ " object:\n");

// Report information about each field

if (!(fields == null)) {

for (int i=0;i<fields.length;i++) {

Field field = fields[i];

int byteLength = field.getByteLength();

int digits = field.getDigits();

String label = field.getLabel();

int length = field.getLength();

String name = field.getName();

PicklistEntry[] picklistValues = field.getPicklistValues();

int precision = field.getPrecision();

String[] referenceTos = field.getReferenceTo();

int scale = field.getScale();

FieldType fieldType = field.getType();

boolean IsCalculated = field.isCalculated();

boolean IsCreateable = field.isCreateable();

Page 11

AppExchange API

boolean IsCustom = field.isCustom();

boolean IsDefaultedOnCreate = field.isDefaultedOnCreate();

boolean IsFilterable = field.isFilterable();

boolean IsNameField = field.isNameField();

boolean IsNillable = field.isNillable();

boolean IsRestrictedPicklist=field.isRestrictedPicklist();

boolean IsUpdateable = field.isUpdateable();

System.out.println("************* New Field ***************");

System.out.println("Name = " + name);

System.out.println("Label = " + label);

System.out.println("Length = " + length);

System.out.println("Bytelength = " + byteLength);

System.out.println("Digits = " + digits);

System.out.println("Precision = " + precision);

System.out.println("Scale = " + scale);

System.out.println("Field type = " + fieldType);

// field properties

System.out.println("Custom field = " + IsCustom);

System.out.println("Name field = " + IsNameField);

System.out.println("Can set field value on Create = " + IsCreateable);

System.out.println("Can set field value on Update = " + IsUpdateable);

System.out.println("Can be used to filter results = " + IsFilterable);

System.out.println("Field value can be empty = " + IsNillable);

System.out.println("Field value is defaulted on Create

= " + IsDefaultedOnCreate);

System.out.println("Field value is calculated = " + IsCalculated);

System.out.println("Field value is a restricted picklist

= " + IsRestrictedPicklist);

if (picklistValues != null) {

System.out.println("Picklist values = ");

for (int j=0;j<picklistValues.length;j++) {

if (picklistValues[j].getLabel() != null)

System.out.print(" item: " + picklistValues[j].getLabel());

else

System.out.print(" item: " + picklistValues[j].getValue());

System.out.print(", value = " + picklistValues[j].getValue());

System.out.println(", is default = " + picklistValues[j].isDefaultValue());

}

if (referenceTos != null) {

System.out.println("Field references the following objects:");

for (int j=0;j<referenceTos.length;j++)

System.out.println(" " + referenceTos[j]);

}

System.out.println("\n");

}

getUserInput("\nDescribe " + objectToDescribe

+ " was successful.\n\nHit the enter key to conutinue....");

}

} catch (Exception ex) {

System.out.println("\nFailed to get " + objectToDescribe

+ " description, error message was: \n" + ex.getMessage());

getUserInput("\nHit return to continue...");

}

Page 12

AppExchange API

Note

The sample client application executes a query by invoking the

query call, passing a simple query

string ("select FirstName, LastName from Contact"), and iterating through the returned

QueryResult .

(1/2 new AXIS 1.3 code) private void describeSample() {

String objectToDescribe = getUserInput("\nType the name of the object to

describe (try Account): ");

try {

DescribeSObjectResult descSObjectRslt = null; descSObjectRslt= binding.describeSObject(objectToDescribe); if (!(descSObjectRslt == null)) {

// Report object level information

Field[] fields=descSObjectRslt.getFields();

String objectName=descSObjectRslt.getName();

boolean isActivateable=descSObjectRslt.isActivateable();

boolean isCreateable=descSObjectRslt.isCreateable();

boolean isCustom=descSObjectRslt.isCustom();

boolean isDeleteable=descSObjectRslt.isDeletable();

boolean isQueryable=descSObjectRslt.isQueryable();

boolean isReplicateable=descSObjectRslt.isReplicateable();

boolean isRetrieveable = descSObjectRslt.isRetrieveable();

boolean isSearchable = descSObjectRslt.isSearchable();

boolean isUndeleteable = descSObjectRslt.isUndeletable();

boolean isUpdateable = descSObjectRslt.isUpdateable();

System.out.println("Metadata for " + objectToDescribe + " object:\n");

System.out.println("Object name = " + objectName);

System.out.println("Number of fields = " + fields.length);

System.out.println("Object can be activated = " + isActivateable);

System.out.println("Can create rows of data = " + isCreateable);

System.out.println("Object is custom object = " + isCustom);

System.out.println("Can delete rows of data = " + isDeleteable);

System.out.println("Can query for rows of data = " + isQueryable);

System.out.println("Object used in replication = " + isReplicateable);

System.out.println("Can retrieve object = " + isRetrieveable);

System.out.println("Can search object = " + isSearchable);

System.out.println("Can un-delete = " + isUndeleteable);

System.out.println("Can update = " + isUpdateable);

System.out.println("\nField metadata for " + objectToDescribe + " object:\n");

// Report information about each field

if (!(fields == null)) {

for (int i=0;i<fields.length;i++) {

Field field = fields[i];

int byteLength = field.getByteLength();

int digits = field.getDigits();

String label = field.getLabel();

int length = field.getLength();

String name = field.getName();

PicklistEntry[] picklistValues = field.getPicklistValues();

int precision = field.getPrecision();

String[] referenceTos = field.getReferenceTo();

int scale = field.getScale();

FieldType fieldType = field.getType();

boolean IsCalculated = field.isCalculated();

boolean IsCreateable = field.isCreateable();

boolean IsCustom = field.isCustom();

boolean IsDefaultedOnCreate = field.isDefaultedOnCreate();

boolean IsFilterable = field.isFilterable();

boolean IsNameField = field.isNameField();

boolean IsNillable = field.isNillable();

Page 13

AppExchange API

boolean IsRestrictedPicklist=field.isRestrictedPicklist();

boolean IsUpdateable = field.isUpdateable();

System.out.println("************* New Field ***************");

System.out.println("Name = " + name);

System.out.println("Label = " + label);

System.out.println("Length = " + length);

System.out.println("Bytelength = " + byteLength);

System.out.println("Digits = " + digits);

System.out.println("Precision = " + precision);

System.out.println("Scale = " + scale);

System.out.println("Field type = " + fieldType);

// field properties

System.out.println("Custom field = " + IsCustom);

System.out.println("Name field = " + IsNameField);

System.out.println("Can set field value on Create = " + IsCreateable);

System.out.println("Can set field value on Update = " + IsUpdateable);

System.out.println("Can be used to filter results = " + IsFilterable);

System.out.println("Field value can be empty = " + IsNillable);

System.out.println("Field value is defaulted on Create = " +

IsDefaultedOnCreate);

System.out.println("Field value is calculated = " + IsCalculated);

System.out.println("Field value is a restricted picklist = " +

IsRestrictedPicklist); private void querySample() {

QueryResult qr = null;

QueryOptions qo = new QueryOptions();

qo.setBatchSize(new Integer(250));

binding.setHeader(new

SforceServiceLocator().getServiceName().getNamespaceURI(), "QueryOptions", qo);

try {

qr = binding.query("select FirstName, LastName from Contact");

boolean done = false;

if (qr.getSize() > 0){

System.out.println("Logged in user can see "

+ qr.getRecords().length + " contact records.");

while (!done) {

for (int i=0;i<qr.getRecords().length;i++) {

Contact con = (Contact)qr.getRecords(i);

String fName = con.getFirstName();

String lName = con.getLastName();

if (fName == null)

System.out.println("Contact " + (i + 1) + ": " + lName);

else

System.out.println("Contact " + (i + 1) + ": " + fName + " " + lName);

}

if (qr.isDone()) {

done = true;

} else {

qr = binding.queryMore(qr.getQueryLocator());

}

else {

System.out.println("No records found.");

}

System.out.println("\nQuery succesfully executed.");

getUserInput("\nHit return to continue...");

}

catch (RemoteException ex) {

Page 14

AppExchange API

System.out.println("\nFailed to execute query succesfully,

error message was: \n" + ex.getMessage());

getUserInput("\nHit return to continue...");

}

C# Sample Code

This section walks through a sample C# client application. The purpose of this sample application is to show the required steps for logging in and to demonstrate the invocation and subsequent handling of several API calls.

This sample application performs the following main tasks:

1. Prompts the user for their Salesforce user name and password.

2. Calls

to log in to the single login server and, if the login succeeds:

•

Sets the returned sessionID into the session header, which is required for session

authentication on subsequent API calls.

• Resets the AppExchange Web service endpoint to the returned

serverUrl , which is the

the target of subsequent API calls.

All client applications that access the API must complete the tasks in this step before attempting any subsequent API calls.

3. Calls

describeGlobal to retrieve a list of all available objects for the organization’s data.

4. Calls

to retrieve metadata (field list and object properties) for a specified object.

5. Calls

, passing a simple query string ("select FirstName, LastName from

Contact"

), and iterating through the returned

For the login call, the initial endpoint is always http(s)//www.salesforce.com. Once the client application has logged in successfully, however, a client application uses the results of the login

In the following sample code, API calls and other significant code is identified in a bold font. In addition, note the error handling code that follows each API call.

The following code begins the sample C# client application.

using System; namespace Walkthrough

{

class WalkthroughSample

{

private sforce.SforceService binding;

static private WalkthroughSample walkthroughSample;

[STAThread]

static void Main(string[] args)

{

walkthroughSample = new WalkthroughSample();

walkthroughSample.run();

}

public void run()

{

//Call the login function

if ( login() )

{

//Do a describe global

describeGlobal();

//describe an account object

describeSObject("account");

//retrieve some data using query

Page 15

AppExchange API

querySample();

}

The login() method retrieves the user’s login credentials, instantiates a binding stub (which is the main interface to the web service through which all calls are made), and invokes the

call.

call to reset the endpoint of the service to the virtual server instance that is servicing your organization. After logging in successfully, the sample client application:

• Instantiates a persistent SOAP header and sets its sessionId value to the session ID returned in the

LoginResult (loginResult.sessionId). This SOAP header is included on all

subsequent calls that are made with the binding.

• Changes the Web services endpoint (binding.URL) to the URL specified in the returned

invokes a describeGlobal call, which returns all of the objects that are visible to the logged in

object (loginResult.serverUrl).

private bool login()

{

//Get the user name and password from the console

Console.Write("Username: ");

string username = Console.ReadLine();

Console.Write("Password: ");

string password = Console.ReadLine();

//create a new instance of the web service proxy class

binding = new sforce.SforceService();

try

{

//execute the login placing the results

//in a LoginResult object

sforce.LoginResult loginResult = binding.login(username, password);

//set the session id header for subsequent calls

binding.SessionHeaderValue = new sforce.SessionHeader();

binding.SessionHeaderValue.sessionId = loginResult.sessionId;

//reset the endpoint url to that returned from login

binding.Url = loginResult.serverUrl;

return true;

}

catch (Exception ex)

{

//Login failed, report message then return false

Console.WriteLine("Login failed with message: " + ex.Message);

return false;

}

Note

The describeGlobal method determines the objects that are available to the logged in user. It

user (see Factors that Affect Data Access on page 32). This call should not be made more than

once per session, as the data returned from the call likely does not change frequently. The

DescribeGlobalResult is simply echoed to the console.

private void describeGlobal()

{

//The describe global will return an array of object names that

Page 16

AppExchange API

//are available to the logged in user

sforce.DescribeGlobalResult dgr = binding.describeGlobal();

Console.WriteLine("\nDescribe Global Results:\n");

//Loop through the array echoing the object names to the console

for (int i=0;i<dgr.types.Length;i++)

{

Console.WriteLine(dgr.types[i]);

}

Console.WriteLine("\n\nHit enter to continue...");

Console.ReadLine();

}

Note

The describeSObject method illustrates the type of metadata information that can be obtained for each object available to the user. The sample client application executes a

The querySample() method executes a query by invoking the query call, passing a simple query

call on a given object and then echoes the returned metadata information to the console. Object metadata information includes permissions, field types and lengths, and available values for picklist fields and types for referenceTo fields.

private void describeSObject(string objectType)

{

//Call the describeSObject passing in the object type name

sforce.DescribeSObjectResult dsr =

binding.describeSObject(objectType);

//The first properites we will echo are on the object itself

//First we will output some Descriptive info on the object

Console.WriteLine("\n\nObject Name: " + dsr.name);

if (dsr.custom) Console.WriteLine("Custom Object");

if (dsr.label != null) Console.WriteLine("Label: " + dsr.label);

//now the permissions on the object

if (dsr.activateable) Console.WriteLine("Activateable");

if (dsr.createable) Console.WriteLine("Createable");

if (dsr.deletable) Console.WriteLine("Deleteable");

if (dsr.queryable) Console.WriteLine("Queryable");

if (dsr.replicateable) Console.WriteLine("Replicateable");

if (dsr.retrieveable) Console.WriteLine("Retrieveable");

if (dsr.searchable) Console.WriteLine("Searchable");

if (dsr.undeletable) Console.WriteLine("Undeleteable");

if (dsr.updateable) Console.WriteLine("Updateable");

//Now we will retrieve meta-data about each of the fields

for (int i=0;i<dsr.fields.Length;i++)

{

//Create field object for readability

sforce.Field field = dsr.fields[i];

//Echo some useful information

Console.WriteLine("Field name: " + field.name);

Console.WriteLine("\tField Label: " + field.label);

//This next property indicates that this

//field is searched when using

//the name search group in SOSL

if (field.nameField)

Console.WriteLine("\tThis is a name field.");

if (field.restrictedPicklist)

Console.WriteLine("This is a RESTRICTED picklist field.");

Page 17

AppExchange API

Console.WriteLine("\tType is: " + field.type.ToString());

if (field.length > 0)

Console.WriteLine("\tLength: " + field.length);

if (field.scale > 0)

Console.WriteLine("\tScale: " + field.scale);

if (field.precision > 0)

Console.WriteLine("\tPrecision: " + field.precision);

if (field.digits > 0)

Console.WriteLine("\tDigits: " + field.digits);

if (field.custom)

Console.WriteLine("\tThis is a custom field.");

//Output the permission on this field.

if (field.nillable) Console.WriteLine("\tCan be nulled.");

if (field.createable) Console.WriteLine("\tCreateable");

if (field.filterable) Console.WriteLine("\tFilterable");

if (field.updateable) Console.WriteLine("\tUpdateable");

//If this is a picklist field, we will show the values

if (field.type.Equals(sforce.fieldType.picklist))

{

Console.WriteLine("\tPicklist Values");

for (int j=0;j<field.picklistValues.Length;j++)

Console.WriteLine("\t\t" + field.picklistValues[j].value);

}

//If this is a foreign key field (reference),

//we will show the values

if (field.type.Equals(sforce.fieldType.reference))

{

Console.WriteLine("\tCan reference these objects:");

for (int j=0;j<field.referenceTo.Length;j++)

Console.WriteLine("\t\t" + field.referenceTo[j]);

}

Console.WriteLine("");

}

Console.WriteLine("\n\nHit enter to continue...");

Console.ReadLine();

}

Note

string ("select FirstName, LastName from Contact"), and iterating through the returned

QueryResult .

private void querySample()

{

//The results will be placed in qr

sforce.QueryResult qr = null;

//We are going to increase our return batch size to 250 items

//Setting is a recommendation only, different batch sizes may

//be returned depending on data, to keep performance optimized.

binding.QueryOptionsValue = new sforce.QueryOptions();

binding.QueryOptionsValue.batchSize = 250;

binding.QueryOptionsValue.batchSizeSpecified = true;

try

Page 18

AppExchange API

{

qr = binding.query("select FirstName, LastName from Contact");

bool done = false;

if (qr.size > 0)

{

Console.WriteLine("Logged in user can see "

+ qr.records.Length + " contact records.");

while (!done)

{

Console.WriteLine("");

for (int i=0;i<qr.records.Length;i++)

{

sforce.Contact con = (sforce.Contact)qr.records[i];

string fName = con.FirstName;

string lName = con.LastName;

if (fName == null)

Console.WriteLine("Contact " + (i + 1) + ": " + lName);

else

Console.WriteLine("Contact " + (i + 1) + ": " + fName

+ " " + lName);

}

if (qr.done)

{

done = true;

}

else

{

qr = binding.queryMore(qr.queryLocator);

}

else

{

Console.WriteLine("No records found.");

}

catch (Exception ex)

{

Console.WriteLine("\nFailed to execute query succesfully, error message was: \n" + ex.Message);

}

Console.WriteLine("\n\nHit enter to exit...");

Console.ReadLine();

}

Page 19

AppExchange API

HAPTER

B a s i c C o n c e p t s

This topic provides high-level introductions to the basic concepts you need to understand before building client applications that use the API. It includes the following topics:

•

Overview of API Calls

•

Overview of Objects

•

Security and the API

•

Error Handling in the API

•

Internationalization and Character Sets

•

XML Compliance

•

Multiple Instance Support

•

Primitive Data Types

•

Opportunity Forecast Override Business Rules

O

VERVIEW OF

API C

ALLS

All API calls are synchronous requests made to the AppExchange Web service. Any changes to

your Salesforce data are committed automatically. For more information, see API Calls on page 31, including the following topics:

•

Using API Calls on page 31

•

Sforce Object Query Language (SOQL) on page 38

•

Sforce Object Search Language (SOSL) on page 44

•

Data Replication on page 51

•

List of API Calls on page 53

O

VERVIEW OF

O

BJECTS

In the API, objects are data entities that represent your organization’s information. Object

properties represent fields in those data entities, and client applications set or retrieve data values via these properties.

For more information, see

API Objects on page 132, including the following topics:

•

Key Concepts of API Objects on page 132

•

List of Standard Objects on page 141

•

Individual objects, beginning with Account on page 145

Page 20

AppExchange API

S

ECURITY AND THE

API

Client applications that access your organization’s Salesforce data are subject to the same security protections that are used in the Salesforce user interface.

User Authentication

Client applications must log in using valid credentials for an organization. authenticates these credentials and, if valid, provides the client application with:

• a sessionID that must be set into the session header so that all subsequent calls to the Web service are authenticated

• a URL for the client application’s Web service requests

Profile Configuration

Permissions to access data and invoke API calls are governed by the profile of the user who is currently logged in. An organization’s Salesforce administrator controls the availability of various functions and views by configuring profiles and assigning users to them. In the Salesforce user interface, go to Setup | Manage Users | Profiles to create, edit, or delete profiles. Client applications can query or update only those objects and fields to which they have access via the profile of the logged-in user.

Note

The Web services WSDL files return all available objects and fields for an organization.

Sharing

In the Salesforce user interface, the concept of sharing refers to the act of granting access to a user or group to view and/or edit a record owned by another user, if the default organization access levels do not otherwise permit such access. All API calls respect the sharing model. For more information about sharing, see the Salesforce online help.

Note

In the API, you can create and update objects such as AccountShare and

OpportunityShare

that define sharing entries for records.

Implicit Restrictions for Objects and Fields

Certain objects can be created or deleted only in the Salesforce user interface. Other objects are read-only—client applications cannot

create ,

, or

fields within some objects can be specified on create

such objects. Similarly, certain

but not on update

. Other fields are read-

only—client applications cannot specify field values in create or

update calls. For more

information, see the respective object descriptions in API Objects on page 132.

E

RROR

H

ANDLING IN THE

API

The API calls return error data that your client application can use to identify and resolve runtime errors. If an error occurs during the invocation of most API calls, then the Web service throws an exception and returns an

ApiFault with an associated ExceptionCode

. If the error occurs during

the invocation of a create

, update , or

call, the Web service returns an Error

Error Handling for Session Expiration

When you sign on via the

call, a new client session begins and a corresponding unique session ID is generated. Sessions automatically expire after the amount of time specified in the

Security Controls setup area of the Salesforce application (default two hours). When your session expires, the exception code INVALID_SESSION_ID is returned in an ApiFault. If this happens, you must invoke the

call again.

Page 21

AppExchange API

More About Error Handling

For more information about errors, see the following topics:

•

ApiFault on page 35

•

List of APIFault Types on page 38

•

ExceptionCode on page 35

•

Error on page 37

I

NTERNATIONALIZATION AND

C

HARACTER

S

ETS

The Web service supports either full Unicode characters or ISO-8859-1 characters. The character set for your organization depends on the Salesforce instance your organization uses. If your organization logs into ssl.salesforce.com, then your encoding is ISO-8859-1. All other instances

use UTF-8. You can determine the character set for your organization by calling describeGlobal

and inspecting the encoding value returned in the DescribeGlobalResult .

If your organization uses ISO-8859-1 encoding, then all data sent to the AppExchange Web service must be encoded in ISO-8859-1. Characters outside the valid ISO-8859-1 range might be truncated or cause an error.

Note

The Web service response is encoded in the character set used by your organization (UTF-8 or

ISO-8859-1). Either way, the encoded data is usually handled for you by the SOAP client.

XML C

OMPLIANCE

The API is based on XML, which requires all documents to be well formed. Part of that requirement is that certain Unicode characters are not allowed in an XML document, even in an escaped form, and that others must be encoded according to their location. Normally this is handled for you by any standard SOAP or XML client. Clients must be able to parse any normal

XML escape sequence, and must not pass up invalid XML characters.

Some characters, as mentioned, are illegal even if they are escaped. The illegal characters include the Unicode surrogate blocks and a few other Unicode characters. All are seldom-used control characters that are usually not important in any data, and tend to cause problems with many programs. Although they are not allowed in XML documents, they are allowed in HTML documents and may be present in Salesforce data. The illegal characters will be stripped from any API response.

The following characters are illegal:

0xFFFE

0xFFFF

Control characters 0x0 - 0x19

(Not including 0x9, 0xA, 0xD, tab, newline, and carriage return)

0xD800 - 0xDFFF

For UTF-8 encoding, Salesforce supports only the basic UCS-2 plane and does not support any of the extended UCS-4 characters. UCS-4 support is extremely rare in any system. UCS-2 is the set that Java and Windows NT support. For more information about XML characters and character sets, see: www.w3.org/TR/REC-xml#charsets

Page 22

AppExchange API

M

ULTIPLE

I

NSTANCE

S

UPPORT

Salesforce Instances

The API provides access to all servers, including:

• US/North America 0

• US/North America 1

• EMEA/Europe

• AP/Japan

The different sets of servers are referred to as instances.

Note

An organization is not guaranteed to be on a particular instance, just because that organization is located in a particular region, although that is generally true. Also, additional instances may be added in the future.

The SOAP implementation of the API also provides a single login server. You can log in to any organization via a single entry point, without having to hard-code the instance for your organization. To access an organization via the API, you must first authenticate the session by

sending a login request to the login server at the following URL:

https://www.salesforce.com/services/Soap/c/7.0

The insecure version of the URL is also supported: http://www.salesforce.com/services/Soap/c/7.0

All subsequent calls to the server during the session should be made to the URL returned in the

response, which points to the server instance for your organization.

Salesforce Sandbox

Enterprise Edition customers have access to the Salesforce Sandbox, which is a testing environment that offers a full or partial copy of your organization’s live production data. For more information about Salesforce Sandbox, please visit the Successforce website or contact

Customer Support.

To access your organization’s Salesforce Sandbox via the API, use the following URLs to make login requests:

• https://test.salesforce.com/services/Soap/c/7.0 (Enterprise WSDL)

• https://test.salesforce.com/services/Soap/u/7.0 (Partner WSDL)

Page 23

AppExchange API

P

RIMITIVE

D

ATA

T

YPES

The API uses the following primitive data types:

Value

base64Binary boolean date dateTime double

Description

Base 64-encoded binary data. Fields of this type are used for storing

binary files in Attachment s,

Document s, and

Scontrol objects. In these

objects, the Body or Binary field contains the (base64 encoded) data, while the BodyLength field defines the length of the data in the Body or

Binary

field. In the Document

object, you can specify a URL to the document instead of storing the document directly in the record.

Boolean fields have one of these values: True (or 1), or False (or 0).

Date data. Fields of this type contain date values, such as ActivityDate in the

values (timestamps), such as ActivityDateTime in the Event

object. Unlike dateTime fields, date fields contain no time value—the time portion of a date field is not relevant and is always set to midnight in the GMT/UTC time zone.

Date/time values (timestamps). Fields of this type handle date/time

object or the CreatedDate, LastModifiedDate, or SystemModstamp in many objects. Regular dateTime fields are full timestamps with a precision of one second. They are always transferred in the GMT/UTC time zone.

In your client application, you might need to translate the timestamp to or from a local time zone.

Development tools differ in the way that they handle time data. Some development tools report the local time, while others report only the

GMT time. To determine how your development tool handles time values, refer to its documentation.

Note that the Event object has a DurationInMinutes field that specifies

the number of minutes for an event. Even though this is a temporal value, it is an integer type—not a dateTime type.

Double values. Fields of this type can contain fractional portions (digits to the right of the decimal place), such as ConversionRate in

CurrencyType .

In the API, all non-integer values (such as

Currency Field Type

and

Percent Field Type ) contain values of type double.

Some restrictions may be applied to double values:

•

scale :

maximum number of digits to the right of the decimal place.

•

precision

Total number of digits, including those to the left and the right of the decimal place

The maximum number of digits to the left of the decimal place is equal

precision

minus

scale

. In the online application, precision is defined

differently—it is the maximum number of digits allowed to the left of the decimal place.

Page 24

AppExchange API

Value

int string

Description

Fields of this type contain numbers with no fractional portion (digits to the right of a decimal place), such as the NumberOfEmployees in an

Contact object, the FirstName field is 40 characters, the

. For integer fields, the digits field specifies the maximum number of digits that an integer can have.

Character strings. Fields that are of datatype string contain text and some have length restrictions depending on the data being stored. For example, in the

LastName

field is 80 characters, the MailingStreet is 255 characters.

These data types are used in the SOAP messages that are exchanged between your client application and the AppExchange Web service. When writing your client application, follow the data typing rules defined for your programming language and development environment. Your development tool handles the mapping of typed data in your programming language with these

SOAP data types.

The primitive data types are:

• specified in the World Wide Web Consortium’s publication XML Schema Part 2: Datatypes at the following URL: http://www.w3.org/TR/xmlschema-2/

• enumerated in the SOAPType field of the

of the DescribeSObjectResult .

type, which is described in the fields property

Primitive types are used as a standardized way to define, send, receive, and interpret basic data types in the SOAP messages exchanged between client applications and the AppExchange Web service. In addition, primitive data types are interpreted in a Salesforce-specific way, which is useful for display formatting and for numeric conversion (adding values of different currencies).

For example, Salesforce chooses to interpret a double value passed via SOAP as a double in a number of possible ways, depending on the field definition. If the field type for that data is currency, Salesforce handles the display of the data by prepending it with a currency symbol and inserting a decimal for precision. Similarly, if the field type is percent, Salesforce handles the display of the data by appending a percent sign (%). Regardless of the field type, however, the value is sent in the SOAP message as a double.

The API also uses datatypes we have defined in the WSDLs, called field types. For more

information, see Field Types

on page 133, and for more information about the WSDLs, see WSDL

Files for Web Services on page 4.

O

PPORTUNITY

F

ORECAST

O

VERRIDE

B

USINESS

R

ULES

If you have Customizable Forecasting enabled for your organization, and have set up users and roles in the Forecast Hierarchy, you can use two objects to retrieve opportunity forecast override information:

• OpportunityOverride

• LineitemOverride

These read-only objects keep an up-to-date record of the current values related to forecasts, whether those values are inherited from the opportunity itself or reflect an opportunity forecast override. Inherited values are stored in these objects, separate from the Opportunity object, to improve performance.

If an override record exists (whether or not a particular value is overriden), the Amount,

Quantity, Forecast Period, Forecast Category values (and Unit Price on LineitemOverride values) stored in these objects will be used to compute the forecast for the OwnerId specified in the record. These objects represent the user's view of the Opportunity or OpportunityLineitem with regard to forecasting, and may reflect overridden values from an opportunity owner or Forecast

User below the specified user in the Forecast Hierarchy. If an override record does not exist, then the values stored in the Opportunity or OpportunityLineItem record are used, and no override information appears to the user.

Page 25

AppExchange API

In the Forecast Hierarchy, one user at each non-leaf level is designated as the Forecast User.

The Forecast User sees the Opportunity Forecast Related List on the Opportunity Detail page when they view an opportunity owned by a subordinate user (if that user has the Allow

Forecasting permission). A Forecast User's forecasts include contributions from those same subordinates. Other users in the same role as a Forecast User just see their own opportunities reflected in their forecasts.

Note

As you read this section, remember that we will be discussing both Forecast Users and opportunity owners. When we describe traversals from a user and travelling along the Forecast

Hierarchy, it is always in order unless otherwise specified. For more information about Forecast

Users and the Forecast Hierarchy, see the online help.

OpportunityOverride Lifecycle

OpportunityOverride records are created, updated, or deleted only under certain conditions, and only for relevant users.

Note

Because LineitemOverride records always have a parent record in the OpportunityOverride object with the same OpportunityId and OwnerId, this document explains the lifecycle of the

OpportunityOverride records first, then explains any additional behaviors relevant only to

LineitemOverride records.

Creating Opportunity Overrides

Forecast Users above the opportunity owner in the Forecast Hierarchy can override a forecastrelated value (Amount, Quantity, Forecast Period and Forecast Category) by editing the

Opportunity Forecasts related list in an opportunity owned by a subordinate user. Also, the opportunity owner can change opportunity forecast-related values (e.g. Forecast Category,

Stage, Amount, Close Date,) in an opportunity that he or she owns. (Forecast Category has additional rules governing it, see Special Case: Forecast Category on page 2 for more information.)

When a user sets the first override for a particular Opportunity record, OpportunityOverride records are created and appropriate values are written for the opportunity owner and every

Forecast User above the opportunity owner in the Forecast Hierarchy. The values stored in each user's record depend on their location in the hierarchy-- users below the user that made an override will have the opportunity object values, everyone else will have the overridden values, plus the opportunity values for anything not overridden.

When subsequent override values are set, the new values are written to the override records of the user who set the override and other Forecast Users above in the Forecast Hierarchy, until an existing override value is reached.

Quantity can only be overridden in the UI if Quantity Forecasting is enabled on the Forecast

Settings page, and Amount can only be overridden if Revenue Forecasting is enabled.

Note

Any changes that an opportunity owner can make on the Opportunity Forecast edit page are applied to the Opportunity record as well as the relevant OpportunityOverride records.

Updating Opportunity Values and Opportunity Override Values

Whenever an opportunity forecast-related value is updated on the Opportunity record itself, the corresponding records in the OpportunityOverride object for the opportunity owner and Forecast

Users above the owner in the Forecast Hierarchy are updated, until the first override value is encountered. Note that the opportunity owner can't override anything except Forecast Category, but they can edit Close Date and Stage on the Opportunity Forecast edit page, in addition to

Forecast Category. All three fields correspond to the Opportunity record, and the result is the

Page 26

AppExchange API same whether they make the changes on the Opportunity Forecast edit page or the Opportunity edit page.

Changes to the following Opportunity fields also affect records in the OpportunityOverride:

• Close Date affects Forecast PeriodId if the new Close Date falls into a different Forecast

Period than the old Close Date. In this case, the OpportunityOverride PeriodId is updated on the opportunity override record of the opportunity owner, and all Forecast Users above the owner in the Forecast Hierarchy, until the first overriden Period is encountered.

• Currency ISO Code changes always cause an update to the opportunity owner's

OpportunityOverride object. No other object is updated unless Amount changes, which is often the case.

• If Territory Management is enabled, Territory changes on the Opportunity affect

OpportunityOverride records. An Opportunity owner's opportunity overrides are updated with the new Territory, and OpportunityOverride records are inserted or updated for Forecast

Users above the opportunity owner in the Forecast Hierarchy. OpportunityOverride records are also deleted for any Forecast User whose Territory (stored on the override record) is no longer above the opportunity owner in the new opportunity Territory. That is, even if the opportunity owner remains a subordinate of a Forecast User before and after the update, if they roll up into a different territory, that Forecast User loses the overrides for the old territory and new records are created for the new territory.

• When an opportunity is set to Closed/Won, the Amount/Quantity and Period Inherited flags are set to True and the corresponding values are updated to match the opportunity, if they are different. The Forecast Category inherited flag is also set to true and the category itself set to Closed, unless it has been overridden to Omitted. Omitted is the only valid Forecast

Category override for a Closed/Won opportunity.

• When an opportunity is set to Closed/Lost, the Amount/Quantity and Period Inherited flags are set to True, and the corresponding values are updated to match the opportunity, if they are different, and the Forecast Category Inherited flag is set to True and the category itself is set to Omitted if the current value is anything other than Omitted.

Deleting Opportunity Overrides

Opportunity override records are not deleted unless one of these triggering events occurs:

• An opportunity is deleted

• A change is made in the Forecast Hierarchy, such that a particular OpportunityOverride owner is no longer above the opportunity owner or is no longer the Forecast User in the relevant role or territory.

• An opportunity is transferred to a new owner or territory, individually or as part of an account transfer.

• The “Allow Forecasting” permission is removed from a user.

When an opportunity is transferred to a new owner, an override record for the new owner is added as needed, and override objects are deleted for all users that are not Forecast Users above the new owner in the Forecast Hierarchy, possibly including the previous opportunity owner. Also, override objects are updated or inserted as necessary for all Forecast Users above the new owner in the Forecast Hierarchy. Restrictions on opportunity owners are strictly enforced during a transfer. If the new owner was in the Forecast Hierarchy of the previous owner, and had made overrides that are no longer valid as the opportunity owner, such as an Amount override, then the corresponding inherited flag is set to True and the value is refreshed from the opportunity.

Special Case: Forecast Category

An additional rule applies to Forecast Category values: If you set the Forecast Category in a new opportunity that isn't the default forecast category for the stage selected, or update an existing

Forecast Category on an opportunity, then OpportunityOverride records are created for relevant users as described above. Since only opportunity owners can update the Forecast Category on an opportunity record directly, this scenario is treated as a Forecast Category override by the opportunity owner (the Forecast Category Inherited flag on that user's override record is False).

Page 27

AppExchange API

LineitemOverride Object Lifecycle

Additional rules apply to line item overrides, as explained in the rest of this section.

Creating Line Item Overrides

The full set of LineitemOverride records for each OpportunityOverride record is always created to mirror the line item records that exist for the Opportunity record. Whether a user makes an override at the opportunity level or line item level, or even just edits Forecast Category on the

Opportunity Edit (only opportunity owners can do this), the end result is the same in terms of the

Opportunity and LineitemOverride records that are created.

Updating Line Item Overrides

All information from “Updating Opportunity Values and Opportunity Override Values” on page 1 applies to updating LineitemOverride records, with these changes:

• Forecast Category overrides at the opportunity level are cascaded down into child

LineitemOverride records, if the Forecast Category has not been overridden for a particular line item by that user or a subordinate user. That is, when a user establishes an opportunitylevel Forecast Category override, any line item-level Forecast Category overrides by a subordinate Forecast User will take precedence when updating line item Forecast Category values for this user and any superiors. The converse is not true. Forecast Category on an

OpportunityOverride record is never updated in response to a Forecast Category override on a LineitemOverride record by any user. When a user sets a Forecast Category override at the line item level, the override value is written to the LineitemOverride records of the user who set the override and other Forecast Users above that user in the Forecast Hierarchy, until an existing override value is reached.

• Opportunity line item values for Unit Price, Total Price and Quantity, if changed, are saved on the LineitemOverride records for the opportunity owner and above in the Forecast Hierarchy, until the first overriden value is encountered for the field. Quantity can only be overridden in the UI if Quantity Forecasting is enabled on the Forecast Settings page, and Unit Price and

Total Price can only be overridden if Revenue Forecasting is enabled.

When Quantity or Unit Price are overridden, the Total Price is computed and written to the relevant LineitemOverride record. When Total Price is overridden, but not Unit Price, the Unit

Price is computed and written to the relevant LineitemOverride records. If both are overridden, no computation occurs. The computation applies to the LineItemOverride record that contains the override value and related LineitemOverride records that inherit the overridden value. That is, for a given LineitemOverride record, we compute Total Price or

Unit Price according to the above rules, if an override is made on the current record or if the record inherited an override made by a subordinate Forecast User.

Note that if you have selected the value Schedule Date in the Setup | Customize |

Forecasts | Forecast Settings | Forecast Date picklist, you cannot override these values:

• If forecasting by Revenue, or Revenue and Quantity, and the OpportunityLineItem record has a Revenue schedule, you cannot override Unit Price and Total Price.

• If forecasting by Quantity, or Revenue and Quantity, and the OpportunityLineitem records have Quantity schedules, you cannot override Quantity.

Deleting Line Item Overrides

Whenever a line item is deleted, LineitemOverride records relating to that line item are deleted for all users, similar to opportunities. Also, opportunity transfers and Forecast Hierarchy changes affect line item overrides the same way they affect opportunity overrides. That is, if an

OpportunityOverride record is deleted, all the child LineitemOverride records, matching on

OpportunityId and OwnerId, are also deleted.

Page 28

AppExchange API

HAPTER

U s a g e G u i d e l i n e s

This topic describes usage guidelines and best practices for developers using the API. It contains the following sections:

•

Content Type Requirement

•

Request Metering

•

Compression

•

HTTP Persistent Connections

•

HTTP Chunking

C

ONTENT

T

YPE

R

EQUIREMENT

In the API version 7.0 and later, all requests must contain a correct content type, for example:

Content-Type: text/xml; charset=utf-8

. Earlier versions of the API do not enforce this requirement.

R

EQUEST

M

ETERING

To maintain optimum performance and ensure that the API is available to all of our customers, salesforce.com balances transaction loads by limiting the number of API requests (or calls) that any one customer organization may execute concurrently or within any 24-hour period. The limits are based on edition type, as specified in the following table:

Edition Types

Developer Edition

• Enterprise Edition

• Professional Edition

(with API access enabled)

Unlimited Edition

Limits

5,000 calls per organization per 24-hour period, or

5 concurrent calls at any one time

1,000 calls per license per 24-hour period, or

1,000,000 calls per organization per 24-hour period, whichever is lowest

5,000 calls per license per 24-hour period, or

5,000,000 calls per organization per 24-hour period, whichever is lowest

When an organization exceeds any limit, the organization may be temporarily blocked from making additional calls until the end of the relevant 24-hour period.

C

OMPRESSION

The API allows the use of compression on the request and the response, using the standards defined by the HTTP 1.1 specification. This is automatically supported by some SOAP/WSDL clients, and can be manually added to others. Visit http://www.salesforce.com/developer/ projects_toolkits.jsp

for more information on particular clients.

Compression is not used unless the client specifically indicates that it supports compression. For better performance, we suggest that clients accept and support compression as defined by the

HTTP 1.1 specification.

Page 29

AppExchange API

To indicate that the client supports compression, you should include the HTTP header “Accept-

Encoding: gzip, deflate” or a similar heading. The API compresses the response if the client properly specifies this header. The response includes the header “Content-Encoding: deflate” or

“Content-Encoding: gzip,” as appropriate. You can also compress any request by including a

“Content-Encoding: deflate” or “gzip” header.

Most clients are partially constrained by their network connection, even on a corporate LAN.

The API allows the use of compression to improve performance. Almost all clients can benefit from response compression, and many clients may benefit from compression of requests as well.

The API supports deflate and gzip compression according the HTTP 1.1 specification.

Response Compression

The API can optionally compress responses. Responses are compressed only if the client sends an Accept-Encoding header with either gzip or deflate compression specified. The API is not required to compress the response even if you have specified Accept-Encoding, but it normally does. If the API compresses the response, it also specifies a Content-Encoding header with the name of the compression algorithm used, either gzip or deflate.

Request Compression

Clients can also compress requests. The API decompresses any requests before processing. The client must send up a Content-Encoding HTTP header with the name of the appropriate compression algorithm. For more information, see:

• Content-Encoding at: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11

• Accept-Encoding at: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3

• Content Codings at: www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.5

Note

Details about how to implement request SOAP compression in Java with Apache Axis can be found in Tech Notes on the Salesforce.com Developer Web site: http://www.salesforce.com/ developer/tech-notes.jsp?tn=TN-14 h.

HTTP P

ERSISTENT

C

ONNECTIONS

Most clients achieve better performance if they use HTTP 1.1 persistent connection to reuse the socket connection for multiple requests. Persistent connections are normally handled by your

SOAP/WSDL client automatically. For more details, see the HTTP 1.1 specification at: http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.1

HTTP C

HUNKING

Clients that use HTTP 1.1 may receive chunked responses. Chunking is normally handled by your

SOAP/WSDL client automatically.

Page 30

AppExchange API

HAPTER

A P I C a l l s

This topic describes the API calls that your client applications can invoke to retrieve and change your organization’s information. It contains the following sections:

•

Using API Calls

•

Sforce Object Query Language (SOQL)

•

Sforce Object Search Language (SOSL)

•

Data Replication

•

List of API Calls

The rest of this topic describes most of the API calls in detail. Some of the API calls are described in

API Utility Calls on page 125.

U

SING

API C

ALLS

This section includes the following topics:

•

About API Calls

•

Characteristics of API Calls

•

Factors that Affect Data Access

•

Typical API Call Sequence

•

Start By Logging In to the Login Server

•

Core Data Objects Used in API Calls

About API Calls

API calls represent specific operations that your client applications can invoke at runtime to perform certain tasks. For example, you can: query your organization’s data; add, update, and delete information; obtain metadata about your organization’s data; and run utilities to perform administration tasks. For detailed information about API utility calls, see

API Utility Calls on page 125.

Characteristics of API Calls

All API calls are:

• Service Requests and Responses—Your client application prepares and submits a service request to the AppExchange Web service, the AppExchange Web service processes the request and returns a response, and the client application handles the response.

• Synchronous—Once the API call is invoked, your client application waits until it receives a response from the service. Asynchronous calls are not supported.

• Committed automatically—Every operation that writes to a Salesforce object is committed

automatically. This is analogous to the AUTOCOMMMIT setting in SQL. For create

update ,

and delete calls that attempt to write to multiple records in an object, the write operation for

each record is treated as a separate transaction. For example, if a client application attempts to create two new accounts, they’re created using mutually exclusive insert operations that succeed or fail individually, not as a group.

Page 31

AppExchange API

Factors that Affect Data Access

When using the API, the following factors affect access to your organization’s data:

• Depending on which WSDL you are using:

• Enterprise WSDL: The generated enterprise.wsdl file contains all of the objects that are available to your organization. A client application can access, via the API, objects that are defined in the enterprise.wsdl file that you are using.

• Partner WSDL: When using the generated Partner WSDL file, a client application can access objects that are returned in the

describeGlobal call.

For more information, see Generating the WSDL File for Your Organization on page 4.

• Some objects may not appear in the WSDL because you must first contact Salesforce and

request access, for example CategoryData on page 172. These objects are noted in the

“Usage” section for each object.

• Whether your configured permissions allow access to the data. Your client application logs in as a user to the AppExchange Web service. The profile associated with the logged-in user grants or denies access to specific objects and fields in your organization.

For certain objects, the user profile is configured with one of the following permissions:

• Read—Users can only view objects of this type.

• Create—Users can read and create objects of this type.

• Edit—Users can read and update objects of this type.

• Delete—Users can read, edit, and delete objects of this type.

These permissions apply to the following objects:

. Other objects

(such as

AccountTeamMember ) follow sharing on the associated permission-assigned object

(such as the Account

record). Similarly, a Partner

depends on the permissions in the associated

Account .

User permissions do not affect field-level security or sharing. If field-level security specifies that a field is hidden, users with “Read” on that object can view only those fields that are not hidden on the record. In addition, users with “Read” on an object can view only those records that sharing settings allow. The one exception is the “Edit Read Only Fields” permission, which gives users the ability to edit fields marked as read only via field-level security.

The API respects object-level and field-level security configured in the Salesforce user interface. You can access objects and fields only if the security settings in the logged-in user’s profile permit such access. For example, fields that are not visible to a given user are not returned in a

call. For more information, see Security and the

or describeSObjects

API on page 21.

• Whether the sharing model of the logged-in user allows access to the data. For most API calls, data that is outside of the logged-in user’s sharing model is not returned. Users are granted the most permissive access that is available to them, either through organizationwide defaults or manual record sharing.

• Whether your organization uses territory management to control user access to accounts, cases, and opportunities. Territory management is available in Enterprise, Unlimited, and

Developer Edition organizations. For more information, see the Salesforce online help.

• Whether a given object is configured to be accessible via certain API calls. For example, to

create an object via the create

call, its object must be configured as createable (createable is True) . To determine what operations are allowed on a given object, your client application can invoke the

call on the object and inspect the following properties in the

call), updateable ( update call), deletable

: creatable ( create

( delete

call), queryable ( query call), retrievable (

call), searchable (

call), and replicatable (

ID values in reference fields (see Reference Field Type on page 135) are validated in

and getDeleted

calls).

Page 32

AppExchange API

• Whether a particular change would compromise the referential integrity of your organization’s Salesforce data. For example:

•

update calls. For information on IDs, see

and

If a client application delete

•

s an object instance, then its children are automatically

deleted as part of the call if the ChildRelationshipcascadeDelete

property for that child has a value of “True.” For example, if a client application deletes an

any associated OpportunityLineItem records are also deleted. However, if an

, then

OpportunityLineItem is not deletable or is currently being used, then the

call on the parent

will fail. Use DescribeSObjectResult

to view the ChildRelationship

value if you want to be sure what will be deleted.

There are certain exceptions which prevent the execution of a cascadeDelete . For example, you cannot delete an account if it has associated cases, if it has related opportunities that are owned by other users, or if associated contacts are enabled for the

Self-Service portal. In addition, if you attempt to delete an account that has closed/won opportunities owned by you or has active contracts, then the delete request for that record will fail.

• Whether a given field in an object can be updated or not. For example, read-only fields

cannot be changed in create or

update calls.

• Whether a given feature is used by your organization. For example, the RecordTypeId field will appear in your WSDL file only if at least one record type is configured for your organization in the Salesforce user interface.

• Rules for custom objects—such as fields that are configured in the Salesforce user interface to be required (not null) or unique—are not implicitly enforced via the API.

• Ownership changes to one object instance do not automatically cascade to other object instances. For example, if ownership changes for a given

, ownership does not then automatically change for any

Account —each ownership change

associated with that

must be made separately and explicitly by the client application.

• Certain features that are configurable in the Salesforce user interface are not accessible or implicitly enforced via the API. For example:

• Page layouts can specify whether a given field is required, but the API does not enforce such layout-specific field restrictions or validations in

create and

Before invoking any other calls, a client application must first invoke the login

calls. It is up to the client application to enforce any such constraints, if applicable.

• Record types can control which picklist values can be chosen in a given record and which which page layouts users with different profiles can see. However, such rules that are configured and enforced in the Salesforce user interface are not enforced in the API. For example, the AppExchange Web service will not validate whether the value in a picklist field is allowed per any record type restrictions associated with the profile of the logged in user. Similarly, the AppExchange Web service will not prevent a client application from adding data to a particular field simply because that field does not appear in a layout associated with the profile of the logged in user.

If any such constraints are required, it is up to business logic in the client application to enforce them explicitly.

Typical API Call Sequence

For each call, your client application typically:

1. Prepares the request by defining request parameters, if applicable.

2. Invokes the call, which passes the request with its parameters to the AppExchange Web service for processing.

3. Receives the response (synchronously) from the AppExchange Web service.

4. Handles the response, either by processing the returned data (for a successful invocation) or by handling the error (for a failed invocation).

Page 33

AppExchange API

Start By Logging In to the Login Server

call to establish a session with the login server, set the returned server URL as the target server for subsequent

API requests, and set the returned session ID in the SOAP header to provide server authorization

for subsequent API requests. For more information, see login on page 101 and

Sample Code

Walkthrough on page 7.

After logging in, you can accomplish a variety of tasks:

•

Querying Data:

•

Search & Retrieval:

, search

•

Modifying Data:

•

•

Data Replication:

For a list of supported API calls, see List of API Calls on page 53.

•

Utilities:

Core Data Objects Used in API Calls

Many calls in the API use the following data objects:

• ID See

standard objects, see List of Standard Objects on page 141.

•

•

•

•

sObject

An sObject represents an object, such as an individual

Account or

Campaign . For a list of

An sObject has the following properties:

Name fieldsToNull

Type

string[]

Description

Array of one or more field names whose value you want to explicitly set to null. Used only with the

upsert call. Ensures that, for this

sObject

, the value in the specified fields will be set to null.

You can specify only those fields that you can update and that are nillable. For example, specifying an ID field or required field results in a run-time error.

Unique ID for this individual object. For the

exception and returns an ApiFault with an associated ExceptionCode and error message text. If

call, this value is null. For all other API calls, this value must be specified.

Page 34

AppExchange API

ApiFault

If an error occurs during the invocation of a call, the AppExchange Web service throws an

an error occurs during a create, update, or delete call, it results in an Error

. For more

information, see Error Handling in the API

on page 21. Also, see List of APIFault Types on page 38. An ApiFault has the following properties:

Name exceptionCode exceptionMessage

Type

ExceptionCode

string

Description

Exception code.

Error message text.

ExceptionCode

An ExceptionCode contains information about an

ApiFault that occurred during a call. For more

information, see Error Handling in the API

on page 21. Also, see List of APIFault Types on page 38.

The following list of ExceptionCode values is defined in your WSDL file:

ExceptionCode

API_CURRENTLY_DISABLED

API_DISABLED_FOR_ORG

EMAIL_TO_CASE_LIMIT_EXCEEDED

EMAIL_TO_CASE_NOT_ENABLED

EXCEEDED_ID_LIMIT

EXCEEDED_LEAD_CONVERT_LIMIT

EXCEEDED_MAX_SIZE_REQUEST

EXCEEDED_MAX_TYPES_LIMIT

EXCEEDED_QUOTA

FUNCTIONALITY_NOT_ENABLED

IMAGE_TOO_LARGE

INACTIVE_OWNER_OR_USER

INSUFFICIENT_ACCESS

INVALID_ASSIGNMENT_RULE

INVALID_BATCH_SIZE

INVALID_CLIENT

Description

Because of a system problem, API functionality is temporarily unavailable.

The API has not been enabled for the organization.

Contact salesforce.com to enable API access.

The daily converted email limit for the Email-to-Case feature has been exceeded.

The Email-to-Case feature has not been enabled.

Too many IDs were requested in a

Too many IDs were sent to a convertLead

call.

call.

The size of the message sent to the AppExchange Web service exceeded 50 MB.

The number of object types to describe is too large.

The size limit for organization data storage was exceeded during a

AssignmentRuleHeader value was specified.

call.

Functionality has been temporarily disabled. Other calls may continue to work.

The image exceeds the allowed size parameters.

The user or record owner is not active.

The user does not have sufficient access to perform the operation.

An invalid

The query options have an invalid batch size value.

The client is invalid.

Page 35

AppExchange API

ExceptionCode

INVALID_CROSS_REFERENCE_KEY

INVALID_FIELD

INVALID_ID_FIELD

INVALID_LOGIN

INVALID_NEW_PASSWORD

Description

An invalid foreign key cannot be set on a field.

The specified field name is invalid.

The specified ID is correctly formatted, but is not valid, for example, it is an ID of the wrong type, or the object it identifies no longer exists.

The

credentials are not valid.

The new password does not conform with the password policies of the organization.

INVALID_OPERATION

INVALID_OPERATION_WITH_EXPIRED

_PASSWORD

Due to password expiration, a valid password must be

set using setPassword

before the call can be invoked.

INVALID_QUERY_FILTER_OPERATOR

An invalid operator was used in the query filter clause,

at least for that field.

INVALID_QUERY_LOCATOR

INVALID_QUERY_SCOPE

An invalid queryLocator parameter was specified in a

Sforce Object Search Language (SOSL) on page 44.

call.

The specified search scope is invalid.

INVALID_REPLICATION_DATE

INVALID_SEARCH

INVALID_SEARCH_SCOPE

INVALID_SESSION_ID

INVALID_SOAP_HEADER

INVALID_SSO_GATEWAY_URL

INVALID_TYPE

The date for replication is out of the allowed range, such as before the organization was created.

The

call has invalid syntax or grammar. See

The specified search scope is invalid.

The specified sessionID is invalid or has expired. Log in again to start a new session.

There is an error in the SOAP header. If you are migrating from an earlier version of the API, be advised that the SaveOptions header cannot be used with API

version 5.5 or later. Use AssignmentRuleHeader

instead.

The URL provided to configure the Single Sign-On gateway was not a valid URL.

The specified

sObject type is invalid.

INVALID_TYPE_FOR_OPERATION

The specified

sObject type is invalid for the specified

operation.

LOGIN_DURING_RESTRICTED_DOMAIN

The user is not allowed to log in from this IP address.

LOGIN_DURING_RESTRICTED_TIME

The user is not allowed to log in during this time period.

MALFORMED_ID

An invalid ID string was specified. For information about

IDs, see

Sforce Object Query Language (SOQL) on page 38.

MALFORMED_QUERY

MALFORMED_SEARCH

An invalid query string was specified. For example, the query string was longer than 10,000 characters.

An invalid search string was specified. For example, the search string was longer than 10,000 characters.

Page 36

AppExchange API

ExceptionCode

MISSING_ARGUMENT

OPERATION_TOO_LARGE

ORG_LOCKED

PASSWORD_LOCKOUT

QUERY_TIMEOUT

QUERY_TOO_COMPLICATED

REQUEST_LIMIT_EXCEEDED

SERVER_UNAVAILABLE

SSO_SERVICE_DOWN

TRIAL_EXPIRED

UNKNOWN_EXCEPTION

UNSUPPORTED_API_VERSION

UNSUPPORTED_CLIENT

Description

A required argument is missing.

The query exceeds the size limit.

The organization has been locked. You must contact salesforce.com to unlock the organization.

The user has exceeded the allowed number of login attempts. The user must contact his or her administrator to regain login access.

The query has timed out. For more information, see

SOQL query is either selecting too many fields or there are too many filter conditions. Try reducing the number of formula fields referenced in the query.

Exceeded either the concurrent request limit or the request rate limit for your organization. For details, see

Request Metering on page 29.

A server that is necessary for this call is currently unavailable. Other types of requests might still work.

The service was unavailable, and an authentication call to the organization’s specified Single Sign-On server failed.

The trial period for the organization has expired. A representative from the organization must contact salesforce.com to re-enable the organization.

The system encountered an internal error. Please report this problem to salesforce.com.

The file represents an unsupported version of the API.

This version of the client is no longer supported.

Error

An Error contains information about an error that occurred during an API create

update , or

call. For more information, see Error Handling in the API on page 21. An Error has the

following properties:

Name

StatusCode message fields

Type

StatusCode string string[]

Description

A code that characterizes the error.

Error message text.

Reserved for future use.

Page 37

AppExchange API

List of APIFault Types

The following table lists the ApiFault types that the AppExchange Web service returns if an error

occurs when processing a service request.

Fault Description

ApiQueryFault

LoginFault

InvalidSObjectFault

Indicates the row and column numbers where the problem occurred.

Error occurred during the

call.

call.

InvalidFieldFault

Invalid field in a

Problem in the

passed in a

call.

MalformedQueryFault

InvalidQueryLocatorFault

Problem in the queryLocator passed in a

queryMore call.

MalformedSearchFault

Problem in the

searchString

passed in a search call.

InvalidIdFault

Specified ID was invalid in a setPassword

the queryString parameter in the query

call.

UnexpectedErrorFault

Unexpected error occurred. The error is not associated with any other

ApiFault .

S

FORCE

O

BJECT

Q

UERY

L

ANGUAGE

(SOQL)

Use the Sforce Object Query Language (SOQL) to construct simple but powerful query strings for

call. Similar to the SELECT command in SQL, SOQL

allows you to specify the source object (such as Account ), a list of fields to retrieve, and

conditions for selecting rows in the source object. This topic includes:

•

SOQL Syntax

•

conditionExpression Syntax

•

fieldExpression Syntax

•

Logical Operators

•

Changing the Batch Size in Queries

•

Querying Multi-Select Picklists

•

Filtering on Boolean Fields

Note

SOQL does not support all advanced features of the SQL SELECT command. For example, you cannot use SOQL to perform join operations, use wildcards in field lists, use calculation expressions, or specify an ORDER BY clause to sort rows in the result set.

Page 38

AppExchange API

SOQL Syntax

SOQL uses the following syntax: select fieldList from objectType [where conditionExpression] where:

Syntax

fieldList

Description

Specifies a list of one or more fields, separated by commas, that you want to retrieve from the specified object.

objectType

You must specify valid field names and must have read-level permissions to each specified field. The fieldList defines the ordering of fields in the query results.

Specifies the type of object that you want to

to that object. For a list of valid objects, see List of Standard Objects on page 141.

You must specify a valid object and must have read-level permissions

conditionExpression

Determines which rows in the specified object to retrieve. If unspecified, the

query retrieves all rows in the object.

See

conditionExpression Syntax on page 39 for the appropriate

syntax.

NOTE

SOQL statements cannot exceed 10,000 characters. For SOQL statements that exceed this

maximum length, the Web service returns an ExceptionCode of

MALFORMED_QUERY ; no result rows are returned.

conditionExpression Syntax

The conditionExpression uses the following syntax:

fieldExpression [logicalOperator fieldExpression2][logicalOperator

fieldExpression3]...

• You can use parentheses to define the order in which fieldExpressions are evaluated. For example, the following expression is True if fieldExpression1 is True and either

fieldExpression2

or fieldExpression3 are True.

fieldExpression1

AND (fieldExpression2 OR fieldExpression3)

• However, the following expression is True if either fieldExpression3 is True or both

fieldExpression1

and fieldExpression2 are True.

(fieldExpression1

AND fieldExpression2) OR fieldExpression3

• Client applications must specify parentheses when nesting operators. However, multiple operators of the same type do not need to be nested.

See fieldExpression Syntax on page 40 for the syntax of fieldExpressions. See

Logical

Operators on page 42 for the valid logical operators.

Page 39

AppExchange API

fieldExpression Syntax

A fieldExpression uses the following syntax:

fieldName

comparisonOperator value where:

Syntax

fieldName comparisonOperator value

Description

The name of a field in the specified object. Use of single or double quotes around the name will result in an error. You must have at least read-level permissions to the field. It can be any field—it does not need to be a field in the fieldList.

See

Comparison Operators on page 40 for a list of valid operators.

A value, enclosed in single quotes (double quotes result in an error), used to compare with the value in fieldName. You must supply a value whose data type matches the field type of the specified field.

You must supply a native value—other field names or calculations are not permitted.

For date values, use the formatting listed in Date Formats on page 41.

Comparison Operators

The following table lists the comparisonOperator values that are used in fieldExpression syntax. Note that comparisons on strings are case-insensitive.

Operator Name

Description

Equals

Not equals

Less than

Expression is True if the value in the specified fieldName equals the specified value in the expression. String comparisons using the equals operator are case-insensitive.

Expression is True if the value in the specified fieldName does not equal the specified value.

Expression is True if the value in the specified fieldName is less than the specified value.

Less or equal

Greater than

Expression is True if the value in the specified fieldName is less than, or equals, the specified value.

Expression is True if the value in the specified fieldName is greater than the specified value.

Greater or equal

Expression is True if the value in the specified fieldName is greater than or equal to the specified value.

Page 40

AppExchange API

Operator Name

like Like includes excludes

Description

Expression is True if the value in the specified fieldName matches the characters of the text string in the specified

value

The like operator in SOQL is similar to the same operator in SQL; it provides a mechanism for matching partial text strings and includes support for wildcards.

• The % and _ wildcards are supported for the like operator.

• The % wildcard matches zero or more characters.

• The _ wildcard matches exactly one character.

• The text string in the specified value must be enclosed in single quotes.

• The like operator is supported for string fields only (see

string on page 25).

• The like operator performs a case-insensitive match, unlike the case-sensitive matching in SQL.

• The like operator in SOQL does not currently support escaping of special characters such as % or _. The \

(backslash) character should not be used.

select AccountId, FirstName, lastname from Contact where lastname like ‘%appl_%’ matches Appleton, Apple, Bapple, but not Appl.

Applies only to multi-select picklists. See Querying Multi-

Select Picklists on page 43.

Date Formats

A fieldExpression uses the following date formats:

Use

Date only

Date, time, and time zone offset

Format Syntax

YYYY-MM-DD

• YYYY-MM-DDThh:mm:ss+hh:mm

• YYYY-MM-DDThh:mm:ss-hh:mm

• YYYY-MM-DDThh:mm:ssZ

Example

1999-01-01

• 1999-01-01T23:01:01+01:00

• 1999-01-01T23:01:01-08:00

• 1999-01-01T23:01:01Z

The zone offset is always from UTC. For more information, see:

• http://www.w3.org/TR/xmlschema-2/#isoformats

• http://www.w3.org/TR/NOTE-datetime

Note

For a fieldExpression that uses date formats, the date is not enclosed in single quotes. No quotes should be used around the date. For example: select Id from Account where CreatedDate > 2005-10-08T15:00:00Z

Page 41

AppExchange API

Logical Operators

The following table lists the logicalOperator values that are used in fieldExpression syntax:

Operator Syntax

and

fieldExpressionX

and fieldExpressionY or not

fieldExpressionX

or fieldExpressionY not fieldExpressionX

Description

True if both fieldExpressionX and fieldExpressionY are True.

True if either fieldExpressionX or fieldExpressionY is True.

True if fieldExpressionX is False.

Changing the Batch Size in Queries

By default, the number of rows returned in the query result object (batch size) returned in a

portion of the SOAP header before invoking the query call.

or queryMore

call is set to 500. Client applications can change this setting by specifying the batch size in the

QueryOptions

The maximum batch size is 2,000 records, however the maximum is automatically reduced if you select large text fields or standard objects like Account. In such cases, the actual batch size may be reduced by a factor of two per large text field or standard object selected. If you select many fields, the maximum will also be reduced to maintain performance. Similarly, even if a batch size of 200 is selected, if the API determines that its more efficient to return more than 200, it will.

There is no guarantee that the requested batch size will be the actual batch size. This is done to maximize performance.

Note

The batch size will be no more than 200 if the SOQL statement selects two or more custom fields of type long text. This is to prevent large SOAP messages from being returned.

The following sample Java (Axis) code demonstrates setting the batch size to two hundred and fifty (250) records.

QueryOptions qo = new QueryOptions(); qo.setBatchSize(new Integer(250)); binding.setHeader(new SforceServiceLocator().getServiceName().getNamespaceURI(),

"QueryOptions", qo);

The following sample C# (.NET) code demonstrates setting the batch size to two hundred and fifty (250) records.

binding.QueryOptionsValue = new QueryOptions(); binding.QueryOptionsValue.batchSize = 250; binding.QueryOptionsValue.batchSizeSpecified = true;

Page 42

AppExchange API

Querying Multi-Select Picklists

Client applications use a specific syntax for querying multi-select picklists (in which multiple items can be selected).

Supported Operators

The following operators are supported for querying multi-select picklists:

Operator

!= includes excludes

Description

Equals the specified string.

Does not equal the specified string.

Includes (contains) the specified string.

Excludes (does not contain) the specified string.

Semicolon Character

A semicolon is used as a special character to specify AND. For example, the following notation:

'AAA;BBB' means 'AAA' and 'BBB'. Specifying AND is used for multiselect picklists, for cases when two or more items must be selected.

Examples

In the following example SOQL notation:

MSP1__c = 'AAA;BBB' the query filters on values in the MSP1__c field that are equal to AAA and BBB selected (exact match).

In the following example SOQL notation:

MSP1__c includes ('AAA;BBB', 'CCC') the query filters on values in the MSP1__c field that contains either of these values:

•

AAA

and BBB selected

•

CCC

selected.

A match will result on any field value that contains 'AAA' and 'BBB' or any field that contains

'CCC'. For example, the following will be matched:

• matches with 'AAA;BBB':

'AAA;BBB'

'AAA;BBB;DDD'

• matches with 'CCC':

'CCC'

'CCC;EEE'

'AAA;CCC'

'BBB;CCC'

Page 43

AppExchange API

Filtering on Boolean Fields

To filter on a Boolean field, use the following syntax: where BooleanField = TRUE where BooleanField = FALSE

S

FORCE

O

BJECT

S

EARCH

L

ANGUAGE

(SOSL)

Use the Sforce Object Search Language (SOSL) to construct simple but powerful text searches

for the search call. This topic describes SOSL syntax and usage:

•

About SOSL

•

Designing Efficient Text Searches

•

Testing Searches in the Salesforce Interface

•

Search Scope

•

SOSL Syntax

•

FIND {SearchQuery}

•

Single Words and Phrases

•

•

•

•

•

•

Valid SearchGroup Settings

•

Example IN Clauses

•

RETURNING FieldSpec

•

Syntax

•

Example RETURNING Clauses

•

LIMIT n

•

Example Text Searches

•

Text Searches in Different Languages

About SOSL

SOSL allows you to specify the text expression, the scope of fields to search, the list of objects and fields to retrieve, and the maximum number of objects to return. You pass the entire SOSL

expression in the searchString

parameter of the

call.

Like the

Sforce Object Query Language (SOQL)

, SOSL allows you programmatically search your organization’s Salesforce data for specific information. You can search all objects—including custom objects—to which you have access. The AppExchange Web service executes the search within the specified scope and returns to you only the information that is available to you based on the user permissions under which your application has logged in.

Designing Efficient Text Searches

When designing text searches, make sure that your text searches are designed with efficiency and performance in mind. A text search should be sufficiently comprehensive to gather all the information you need but also properly focused to search only where you want to look. SOSL syntax allows you to define the search scope, both in the types of columns to search (IN clause) and the objects to search (RETURNING clause). For examples, see the discussions of

SearchGroup on page 48 and

RETURNING FieldSpec on page 49.

Page 44

AppExchange API

Testing Searches in the Salesforce Interface

Before coding your text search programmatically, you can test your text search syntax using the sidebar Search or Advanced Search features in Salesforce interface. Programmatic searches are most similar (but not identical) to the Advanced Search feature—programmatic searches are more exacting, requiring you to structure your searches carefully, while the Advanced Search feature is prestructured and is more forgiving to the end user.

Search Scope

The

call searches most objects (including custom objects) and text fields to which you have access. It does not search the following objects and fields:

• Any objects (such as picklists) that are defined as not searchable (searchable is False). To determine whether a given object is searchable, your application can invoke the

describeSObjects call on the object and inspect the searchable property in the

DescribeSObjectResult .

•

Number, date, checkbox, or textarea fields. To search for such information, use the query

call instead.

•

Attachment

objects associated with certain objects, such as Account

, Contact , or

objects.

Note

The

call does not provide specialized search features such as synonym matching or stop words.

SOSL Syntax

SOSL uses the following syntax:

FIND {SearchQuery}

[ IN SearchGroup

]

[ RETURNING FieldSpec ]

[ LIMIT n ]

where:

Syntax Description

FIND {SearchQuery}

IN SearchGroup

Required. Specifies the text (words or phrases) to search for. The

SearchQuery must be delimited with curly braces.

Optional. Scope of fields to search. One of the following values:

• ALL FIELDS

• NAME FIELDS

• EMAIL FIELDS

• PHONE FIELDS

If unspecified, then the default is ALL FIELDS.

Note: You specify the list of objects to search in the RETURNING

FieldSpec

clause.

RETURNING FieldSpec

Optional. Information to return in the search result. List of one or more objects and, within each object, list of one or more fields. If unspecified, then the search results contain the IDs of all objects found. For information on IDs, see

maximum length, the AppExchange Web service returns an ExceptionCode of

LIMIT n

Optional. Maximum number of rows to return. If unspecified, then the default is the logical maximum limit of 200 rows.

Page 45

AppExchange API

Note

SOSL statements cannot exceed 10,000 characters. For SOSL statements that exceed this

MALFORMED_SEARCH ; no result rows are returned.

FIND {SearchQuery}

The required FIND clause allows you to specify the word or phrase to search for. A search query includes the literal text (single word or a phrase surrounded by double quotes) to search for and,

optionally, Wildcards

, and logical and grouping (parentheses) Operators

. Searches are evaluated from left to right and are conducted in Unicode (UTF-8) encoding. Text searches are caseinsensitive. For example, searching for Customer, customer, or CUSTOMER all return the same results.

Note that special types of text expressions (such as macros, functions, or regular expressions) that are evaluated at run time are not allowed in the FIND clause.

Note

The SearchQuery must be delimited with curly braces. This is needed to unambiguously distinguish the search expression from other clauses in the text search.

Single Words and Phrases

A SearchQuery contains two types of text:

• Single Word—A single word, such as test or hello. Words in the SearchQuery are delimited by spaces, punctuation, and changes from letters to digits (and vice-versa). Words are always case insensitive. In Chinese, Japanese, and Korean (CJK), words are also delimited by pairs of CJK-type characters.

• Phrase—A collection of words and spaces surrounded by double quotes such as “john smith”

. Multiple words can be combined together with logical and grouping Operators

to form a more complex query. Certain keywords (AND, OR, and AND NOT) must be surrounded in double quotes if you want to search for those words.

Wildcards

You can specify the following wildcard characters to match text patterns in your search:

Wildcard

Description

Use an asterisk (*) to match one or more characters at the middle or end of your search term. Do not use the asterisk at the beginning of a search term.

If you are searching for a literal asterisk in a word or phrase, then escape the asterisk (precede it with the \ character).

For example, a search for john* finds items that start with variations on the term john, such as, johnson or johnny. A search for ma* finds items with mary

or marty.

Use a question mark (?) to match one character at the middle or end of your search term. Do not use the question mark wildcard at the beginning of a search term.

For example, a search for jo?n finds items with the word john or joan.

When using wildcards, consider the following issues:

• The more focused your wildcard search, the faster the search results are returned, and the more likely the results will reflect your intention. For example, to search for all occurrences of the word prospect (or prospects, the plural form), it is more efficient to specify prospect*

in the search string than to specify a less restrictive wildcard search (such as prosp*

) that could return extraneous matches (such as prosperity).

Page 46

AppExchange API

• Tailor your searches to find all variations of a word. For example, to find property and properties

, you would specify propert*.

• Punctuation is indexed. To find * or ? inside a phrase, you must enclose your search string in quotation marks and you must escape the special character. For example, “where are you\?”

finds the phrase where are you?. The escape character (\) is required in order for this search to work correctly.

Operators

You can use the following special operators to focus your text search.

Operator

" "

Logical

Operators

AND

AND NOT

Description

Use quotation marks around search terms to find an exact phrase match.

This can be especially useful when searching for text with punctuation. For example, "acme.com" finds items that contain the exact text acme.com. A search for "monday meeting" finds items that contain the exact phrase monday meeting

Note that logical operators are case-insensitive. For example, specifying AND, and

, or And returns the same results.

Finds items that match all of the search terms. For example, john AND smith finds items with both the word john and the word smith. If an operator is not specified, then this is the default operator.

Finds items with at least one of the search terms. For example, john OR smith

finds items with either john or smith, or both words.

Finds items that do not contain the search term. For example, john AND NOT smith

finds items that have the word john but not the word smith.

Grouping

Operators

( ) Use parentheses around search terms in conjunction with logical operators to focus your search. For example, you can search for:

•

("Bob" and "Jones") OR ("Sally" and "Smith")

—searches for either

Bob Jones or Sally Smith.

•

("Bob") and ("Jones" OR "Thomas") and Sally Smith

—searches for

Bob Jones or Bob Thomas and Sally Smith.

Reserved Characters

The following characters are reserved for current and future use:

& | ! ( ) { } [ ] ^ " ~ * ? : \ ' + -

In the current version, the following special characters are used:

* ? ( ) "

Reserved characters, if specified in a text search, must be escaped (preceded by the backslash \ character) in order to be properly interpreted. This is true even if the SearchQuery is enclosed in double quotes. An error occurs if you do not precede reserved characters with a backslash. For example, to search for the following text:

(1+1):2 you must escape the reserved characters in the following manner:

$1\+1$\:2

Page 47

AppExchange API

Example FIND Clauses

Type of Search

Single term

Single phrase

Term OR Term

Term AND Term

Term AND Phrase

Term OR Phrase

Complex query using Term/

Phrase using AND/OR

Example(s)

Find {MyProspect}

Find {[email protected]}

Find {find}

Find {in}

Find {returning}

Find {limit}

Find {John Smith}

Find {MyProspect OR MyCompany}

Find {MyProspect AND MyCompany}

Find {MyProspect AND "John Smith"}

Find {MyProspect OR "John Smith"}

Find {MyProspect AND "John Smith" OR MyCompany}

Complex query using Term/

Phrase using AND NOT

Wildcard Search

Escape sequences

Invalid/Incomplete phrase

Find {MyProspect AND ("John Smith" OR MyCompany)}

Find {MyProspect AND NOT MyCompany}

Find {My*}

Find {Why not\?}

Find {"John Smith}

IN SearchGroup

The optional IN clause allows you to define the types of fields to search. You can specify one of the following values (note that numeric fields are not searchable). If unspecified, the default behavior is to search all text fields in searchable objects.

Valid SearchGroup Settings

Scope

ALL FIELDS

NAME FIELDS

Description

Search all searchable fields. If the IN clause is unspecified, then this is the default setting.

Search only name fields. In custom objects, fields that are defined as “Name Field” are searched. In standard and custom objects, name fields have the nameField property set to True (see the

array of the fields parameter of the DescribeSObjectResult for

more information).

Page 48

AppExchange API

Scope

PHONE FIELDS

EMAIL FIELDS

Description

Search only phone number fields.

Search only email fields.

While the IN clause is optional, it is recommended that you specify the search scope unless you need to search all fields. For example, if you’re searching only for an email address, you should specify IN EMAIL FIELDS in order to design the most efficient search.

Example IN Clauses

Search Type

No search group

ALL FIELDS

EMAIL FIELDS

PHONE FIELDS

NAME FIELDS

Invalid searches

Example(s)

Find {MyProspect}

Find {MyProspect} in ALL FIELDS

Find {[email protected]} in EMAIL FIELDS

Find {MyProspect} in PHONE FIELDS

Find {MyProspect} in NAME FIELDS

Find {MyProspect} in SIDEBAR FIELDS

Find {MyProspect} in Accounts

RETURNING FieldSpec

The optional RETURNING clause allows you to specify the information that is returned in the text search result. If unspecified, then the default behavior is to return the IDs of all available objects

found (up to the maximum LIMIT n

specified in the LIMIT clause). Use the RETURNING clause to restrict the results data that is returned from the

call. For information on IDs, see ID

Object to return. If specified, then the search call returns the IDs of all

Syntax

RETURNING ObjectTypeName[(FieldList)][, ObjectTypeName[(FieldList)], ...

where:

Name

ObjectTypeName

FieldList

Description

found objects matching the specified object. Must be a valid sObject

type. You can specify multiple objects, separated by commas. Objects

not specified in the RETURNING clause are not returned by the search

call. For information on IDs, see ID Fields on page 136.

Optional list of one or more fields to return for a given object, separated by commas. If you specify one or more fields, then—in addition to the

IDs—the fields are also returned for all found objects. You do not need to specify ID fields, as they are always returned. For information on IDs,

see ID Fields on page 136.

Note

The RETURNING clause affects what data is returned, not what data is searched. The IN clause affects what data is searched.

Page 49

AppExchange API

Example RETURNING Clauses

Search Type

No Field Spec

One sObject, no fields

Multiple sObject s,

no fields

One sObject , one or

more fields

Example(s)

Find {MyProspect}

Find {MyProspect} RETURNING Contact

Find {MyProspect} RETURNING Contact, Lead

Find {MyProspect} RETURNING Contact(id)

Find {MyProspect} RETURNING Contact(FirstName, LastName)

Custom sObject

Find {MyProspect} RETURNING Account(name, id)

Find {MyProspect} RETURNING CustomObject_c

Multiple sObject s,

one or more fields

Multiple sObject s,

mixed number of fields

Unsearchable

Find {MyProspect} RETURNING CustomObject_c(id)

Find {MyProspect} RETURNING CustomObject_c(id, CustomField_c)

Find {MyProspect} RETURNING Contact(FirstName, LastName),

Account(name, id)

Find {MyProspect} RETURNING Contact(FirstName, LastName),

Account, Lead(FirstName)

Find {MyProspect} RETURNING RecordType(id)

Find {MyProspect} RETURNING Pricebook

Invalid

sObject s

Find {MyProspect} RETURNING FooBar

Invalid sObject field Find {MyProspect} RETURNING Contact(fooBar)

LIMIT n

The optional LIMIT clause allows you to specify the maximum number of rows returned in the text query. If unspecified, then the default is 200, which is the highest allowable value.

Example Text Searches

Look for joe anywhere in the system. Return the IDs of the records where joe is found.

Find {joe}

Look for the name Joe Smith anywhere in the system, in a case insensitive way. Return the ids of the records where Joe Smith is found.

Find {Joe Smith}

Look for the name Joe Smith in the name field of a lead, return the ID field of the records.

Find {Joe Smith}

In All Fields

Returning lead

Page 50

AppExchange API

Look for the name Joe Smith in the name field of a lead and return the name and phone number.

Find {Joe Smith}

In All Fields

Returning lead(name, phone)

Look for the name Joe Smith or Joe Smythe in the name field of a lead or contact and return the name and phone number. If an opportunity is called Joe Smith, the opportunity should not be returned.

Find {"Joe Smith" OR "Joe Smythe"}

In All Fields

Returning lead(name, phone), contact(name, phone)

Wildcards:

Find {Joe Sm*}

Find {Joe Sm?th*}

Delimiting "and" and "or" as literals when used alone:

Find {"and" or "or"}

Find {"joe and mary"}

Find {in}

Find {returning}

Find {find}

Escaping special characters & | ! ( ) { } [ ] ^ " ~ * ? : \ '

Find {right brace \}}

Find {asterisk \*}

Find {question \?}

Find {single quote \'}

Find {double quote \"}

Text Searches in Different Languages

In Chinese, Japanese, and Korean (CJK), words are delimited by pairs of CJK-type characters.

D

ATA

R

EPLICATION

The API supports data replication, which allows you to store and maintain a local, separate copy of your organization’s pertinent Salesforce data for specialized uses, such as data warehousing, data mining, custom reporting, analytics, integration with other applications, and so on. Data replication provides you with local control and the ability to run large or ad hoc analytical queries across the entire data set without transmitting all that data across the network.

API Calls for Data Replication

The API supports data replication with the following API calls:

API Call

since the last replication request, as described in Checking for Structural Changes in the

Description

Retrieves the list of objects that have been updated (added or changed) during the specified timespan for the specified object.

Retrieves the list of objects that have been deleted during the specified timespan for the specified object.

Page 51

AppExchange API

Client applications can invoke these API calls to determine which objects in your organization’s data have been updated or deleted during a given time period. These API calls return a set of IDs for objects that have been updated (added or changed) or deleted, as well as the timestamp

(GMT—not local—timezone) indicating when they were last updated or deleted. It is the responsibility of the client application to process these results and to incorporate the required changes into the local copy of the data.

Scope of Data Replication

This feature provides a mechanism that targets data replication (one-way copying of data). It does not provide data synchronization (two-way copying of data) or data mirroring capabilities.

Data Replication Steps

A client application typically proceeds along the following basic steps for each object that it replicates:

1. Optionally, the client application determines whether the structure of the object has changed

Object on page 53.

2. Call

getUpdated , passing in the object and timespan for which to retrieve data.

Note that

getUpdated retrieves the IDs for data to which the logged in user has access. Data

that is outside of the user’s sharing model is not returned. The AppExchange Web service returns the ID of every changed object that is visible to you, regardless of what change

occurred in the object. For information on IDs, see ID Fields on page 136.

3. Pass in all IDs in an array. For each ID element in the array, call

to obtain the latest information you want from the associated object. The client application must then take the appropriate action on the local data, such as inserting new rows or updating existing ones with the latest information.

4. Call

, passing in the object and timespan for which to retrieve data. Like

getDeleted retrieves the IDs for data to which the logged in user has access.

Data that is outside of the user’s sharing model is not returned. The AppExchange Web service returns the ID of every changed object that is visible to you, regardless of what change occurred in the object. For information on IDs, see

5. Iterate through the returned array of IDs. Your client application must then take the appropriate action on the local data to remove (or flag as deleted) the deleted objects. If your client application cannot match rows in the local data using the retrieved object ID, then the local data rows either were deleted or were never created, in which case there is nothing to do.

6. Optionally, the client application saves the request timespans for future reference.

Object-Specific Requirements for Data Replication

The API objects have the following requirements for data replication:

• The

and getDeleted

calls filter the results so that the client application receives

IDs for only those created or updated objects to which the logged in user has access. For information on IDs, see

Factors that Affect Data Access on page 32.

• Your client application can replicate any objects to which it has sufficient permissions.

For example, to replicate all data for your organization, your client application must be logged in with “View All Data” access rights to the specified object. For more information, see

• The objects must be within your sharing rules.

• The object must be configured to be replicateable (replicateable is True). To determine whether a given object is replicateable, your application can invoke the

call on the object and inspect the replicateable property in the

Page 52

AppExchange API

Polling for Changes

Client applications typically poll for changed data periodically. Polling involves the following considerations:

• The polling frequency depends on business requirements for how quickly changes in your organization’s Salesforce data need to be reflected in the local copy. Some client applications might poll just once a day to retrieve changes, while other client applications might poll every five minutes to achieve near real-time redundant mirroring of the Salesforce data.

• The AppExchange Web service truncates the seconds portion of dateTime values. For example, if a client application submits a timespan between 12:30:15 (GMT) and 12:35:15

(GMT), then the AppExchange Web service retrieves information about items that have changed between 12:30:00 (GMT) and 12:35:00 (GMT), inclusive.

Note: Development tools differ in the way that they handle time data. Some development tools report the local time, while others report only the GMT time. To determine how your development tool handles time values, refer to its documentation.

• We recommend polling no more frequently than every five minutes. The AppExchange Web service has built in controls to prevent errant applications from invoking the data replication

API calls too frequently.

• Client applications should save the timespan used in previous data replication API calls so that the application knows the last time period for which data replication was successfully completed.

• To ensure data integrity on the local copy of the data, a client application needs to capture all of the relevant changes during polling—even if it requires processing data redundantly to ensure that there are no gaps. Your client application can contain business logic to skip processing objects that have already been integrated into your local data.

• Gaps can also occur if the client application somehow fails to poll the data as expected (for example, due to a hardware crash or network connection failure). Your client application can contain business logic that determines the last successful replication and polls for the next consecutive timespan.

• If for any reason the local data is compromised, your client application might also provide business logic for rebuilding the local data from scratch.

Checking for Structural Changes in the Object

In the API, data replication focuses on changes made to the records of objects. It does not determine whether changes have been made to the structure of objects (for example, fields added to—or removed from—a custom object). It is the responsibility of the client application to check whether the structure of a given object has changed since the last update. Before replicating data, client applications can call

the data returned in the DescribeSObjectResult with the data returned and saved from previous

on the object, and then compare

describeSObjects invocations.

L

IST OF

API C

ALLS

The following table lists supported calls in the API in alphabetical order, and provides a brief description for each. Click a call name to see syntax, usage, and more information for that call.

Note:

For a list of API utility calls, see API Utility Calls on page 125.

Call

Description

, or (optionally) an

Page 53

AppExchange API

Call

Description

Adds one or more new individual objects to your organization’s data.

Deletes one or more individual objects from your organization’s data.

Retrieves a list of available objects for your organization’s data.

Retrieves metadata about page layouts for the specified object type.

Retrieves metadata (field list and object properties) for the specified object type. Superseded by

see ID Fields on page 136.

An array-based version of describeSObject.

Describes the “apps” and tabs that have been configured for the user.

Retrieves the IDs of individual objects of the specified object that have been deleted since the specified time. For information on IDs,

Retrieves the IDs of individual objects of the specified object that have been updated since the specified time. For information on IDs,

see ID Fields on page 136.

Logs in to the login server and starts a client session.

Executes a query against the specified object and returns data that matches the specified criteria.

Retrieves the next batch of objects from a query.

Retrieves one or more objects based on the specified object IDs.

Executes a text search in your organization’s data.

Updates one or more existing objects in your organization’s data.

Creates new objects and updates existing objects; matches on a custom field to determine the presence of existing objects.

convertLead

Converts a

Lead into an

, or (optionally) an Opportunity

Syntax

LeadConvertResult [] = sfdc.convertLead(leadConverts LeadConvert[]);

Usage

Use

convertLead to convert a

Lead into an

and Contact , as well as (optionally) an

as applicable, any associated Account ,

. To convert a Lead

, your client application must be logged in with “Convert Leads” permission and “Edit” permission on Leads, as well as sufficient permissions to create or update,

, and

The convertLead call provides an easy way to convert the information in a qualified lead to a new

or updated account, contact, and opportunity. Your organization can set its own guidelines for

Page 54

AppExchange API determining when a lead is qualified, but typically, a lead can be converted as soon as it becomes a real opportunity that you want to forecast.

If data is merged into existing account and contact objects, then only empty fields in the target object are overwritten—existing data (including IDs) are not overwritten. The only exception to this is if your client application sets overwriteLeadSource to True, in which case the

LeadSource

field in the target Contact

object will be overwritten with the contents of the

LeadSource

field in the source

Lead object.

Rules and Guidelines

When converting leads, consider the following rules and guidelines:

Field Mappings.

The system automatically maps standard lead fields to standard account, contact, and opportunity fields. For custom lead fields, your Salesforce administrator can specify how they map to custom account, contact, and opportunity fields.

Record Types.

If the organization uses record types, the default record type of the new owner is assigned to records created during lead conversion. For more information about record types, see the Salesforce online help.

Picklist Values.

The system assigns the default picklist values for the account, contact, and opportunity when mapping any standard lead picklist fields that are blank. If your organization uses record types, blank values are replaced with the default picklist values of the new record owner.

Basic Steps for Converting Leads

Converting leads involves the following basic steps:

1. The client application determines the IDs of any lead(s) to be converted.

2. Optionally, the client application determines the IDs of any account(s) to merge the lead into. The client application can use SOSL or SOQL to search for accounts that match the lead name, as in the following example, select id, name from account where name='CompanyNameOfLeadBeingMerged'

3. Optionally, the client application determines the IDs of contact(s) to merge the lead into. The client application can use SOSL or SOQL to search for contacts that match the lead contact name, as in the following example.

select id, name from contact where firstName='FirstName' and lastName='LastName' and accountId = '001…'

4. Optionally, the client application determines whether opportunities should be created from the leads.

5. The client application queries the LeadSource table to obtain all of the possible converted status options (select … from LeadStatus where IsConverted='1'), and then selects a value for the Converted Status.

6. The client application calls

convertLead .

7. The client application iterates through the returned result(s) and examine each

LeadConvertResult

object to determine whether conversion succeeded for each lead.

8. (Optional) As a best practice, the client application creates tasks in which the WhoId is the

ContactId

and (if an opportunity is created), the WhatId is the OpportunityId.

9. (Optional) When converting leads owned by a queue, the owner must be specified. This is because accounts and contacts cannot be owned by a queue. Even if you are specifying an existing account or contact, you must still specify an owner.

Page 55

AppExchange API

Sample Code—Java private Boolean convertLead (String leadId, String contactId, String accountId, boolean overWriteLeadSource, boolean doNotCreateOpportunity, String opportunityName, String convertedStatus, boolean sendEmailToOwner)

{

LeadConvert leadConvert = new LeadConvert();

leadConvert.setLeadId(leadId);

leadConvert.setContactId(contactId);

leadConvert.setAccountId(accountId);

leadConvert.setOverwriteLeadSource(overWriteLeadSource);

leadConvert.setDoNotCreateOpportunity(doNotCreateOpportunity);

leadConvert.setOpportunityName(opportunityName);

leadConvert.setConvertedStatus(convertedStatus);

leadConvert.setSendNotificationEmail(sendEmailToOwner);

LeadConvertResult[] lcr = null;

try {

lcr = binding.convertLead(new LeadConvert[] {leadConvert});

for (int i=0; i<lcr.length; i++) {

if (lcr[i].isSuccess()) {

System.out.println("Conversion succeeded.\n");

LeadConvertResult result = lcr[i];

System.out.println("The new contact id is: " + result.getContactId());

} else {

System.out.println("The conversion failed because: " + lcr[i].getErrors(0).getMessage());

}

} catch (UnexpectedErrorFault e) {

System.out.println("Unexpected error encountered:\n\n" + e.getExceptionMessage());

return Boolean.FALSE;

} catch (RemoteException e) {

System.out.println("Remote exception encountered:\n\n" + e.getMessage());

return Boolean.FALSE;

}

return Boolean.TRUE;

}

Sample Code—C# private bool convertLead(string leadId, string contactId,

string accountId, bool overWriteLeadSource,

bool doNotCreateOpportunity, string opportunityName,

string convertedStatus, bool sendEmailToOwner)

{

sforce.LeadConvert leadConvert = new sforce.LeadConvert();

leadConvert.leadId = leadId;

leadConvert.contactId = contactId;

leadConvert.accountId = accountId;

leadConvert.overwriteLeadSource = overWriteLeadSource;

leadConvert.doNotCreateOpportunity = doNotCreateOpportunity;

leadConvert.opportunityName = opportunityName;

leadConvert.convertedStatus = convertedStatus;

leadConvert.sendNotificationEmail = sendEmailToOwner;

Page 56

AppExchange API

sforce.LeadConvertResult[] lcr = null;

try

{

lcr = binding.convertLead(new sforce.LeadConvert[] {leadConvert});

for (int i=0;i<lcr.Length;i++)

if (lcr[i].success)

{

Console.WriteLine("Conversion succeeded.\n");

sforce.LeadConvertResult result = lcr[i];

Console.WriteLine("The new contact id is: " + result.contactId);

}

else

{

Console.WriteLine("The conversion failed because: " + lcr[i].errors[0].message);

}

catch (Exception e)

{

Console.WriteLine("Unexpected error encountered:\n\n" + e.Message);

return false;

}

return true;

}

Page 57

AppExchange API

Arguments

The

convertLead call accepts an array of LeadConvert objects (100 maximum). A LeadConvert

object contains the following properties.

Name accountId contactId convertedStatus

Type

doNotCreateOpportunity

boolean

leadId

string

Description

ID of the

Account into which the lead will be merged.

Required only when updating an existing account.

If no accountID is specified, then the AppExchange

Web service creates a new Account. To create a new

Account, the client application must be logged in with sufficient access rights.

To merge a Lead into an existing Account, the client application must be logged in with read/write access to the specified Account. The account name and other existing data are not overwritten.

Contact into which the lead will be merged

ID of the

(this contact must be associated with the specified

accountId

, and an accountId must be specified).

Required only when updating an existing contact.

If no contactID is specified, then the AppExchange

Web service creates a new Contact that is implicitly

associated with the Account

. To create a new

Contact, the client application must be logged in with sufficient access rights.

To merge a Lead into an existing Contact, the client application must be logged in with read/write access to the specified Contact. The contact name and other existing data are not overwritten (unless

overwriteLeadSource

is set to True, in which case only the LeadSource field is overwritten).

Valid

value for a converted Lead.

Required. To obtain the list of possible values, the client application queries the

Specifies whether to create an Opportunity during

object, as in:

Select Id, MasterLabel from LeadStatus where

IsConverted=true

lead conversion (False, the default) or not (True). Set this flag to True only if you do not want to create an

Opportunity from the lead. An opportunity is created by default.

ID of the

to convert. Required. For information on IDs, see

IDs, see ID Fields on page 136.

Page 58

AppExchange API

Name opportunityName overwriteLeadSource ownerId

Type

string boolean

sendNotificationEmail

boolean

Description

Name of the Opportunity to create. If no name is specified, then this value defaults to the company name of the lead. The maximum length of this field is

80 characters. If doNotCreateOpportunity argument is True, then no Opportunity is created and this field must be left blank; otherwise, an error is returned.

Specifies whether to overwrite the LeadSource field

on the target Contact

object with the contents of the

LeadSource

field in the source

Lead object (True), or

not (False, the default). To set this field to True, the client application must specify a contactId for the target Contact object.

Specifies the ID of the person to own any newly created Account, Contact, and Opportunity. If the client application does not specify this value, then the owner of the new entities will be the owner of the

Lead. Not applicable when merging with existing objects—if an ownerId is specified, the AppExchange

Web service does not overwrite the ownerId field in an existing Account or Contact. For information on

Specifies whether to send a notification email to the owner specified in the ownerId (True) or not (False, the default).

Response

LeadConvertResult

[]

Fault

UnexpectedErrorFault

See Also

convertLead call returns an array of LeadConvertResult objects. Each element in the

Sample SOAP Messages - convertLead

Page 59

AppExchange API

LeadConvertResult

The

LeadConvertResult

array corresponds to the LeadConvert[] array passed as the leadConverts

parameter in the convertLead call. For example, the object returned in the first index in the

LeadConvertResult

array matches the object specified in the first index of the LeadConvert[] array. A LeadConvertResult object has the following properties:

Name accountId contactId success errors

Type

leadId

opportunityId

boolean

Description

ID of the new

ID of the new Contact (if a new contact was specified) or

(if a new account was specified) or the ID of the account specified when

convertLead

was invoked.

the ID of the contact specified when

convertLead was

invoked. For information on IDs, see

ID of the converted Lead

. For information on IDs, see

ID of the new

, if one was created when

convertLead

was invoked. For information on IDs, see

convertLead call succeeded (True)

Indicates whether the

or not (False) for this object.

If an error occurred during the create

call, an array of

objects providing the error code and description.

Page 60

AppExchange API

create

Adds one or more new individual objects to your organization’s data.

Syntax

[] = sfdc.create( sObject

[] sObjects);

Usage

Use

to add one or more individual objects, such as an Account

Contact , to your

organization’s information. The create

call is analogous to the INSERT statement in SQL.

Rules and Guidelines

When creating objects, consider the following rules and guidelines:

Permissions.

Your client application must be logged in with sufficient access rights to create individual objects within the specified object. For more information, see

Factors that Affect Data

Access on page 32.

Special Handling.

Certain objects—and certain fields within those objects—require special handling or permissions. For example, you might also need permissions to access this object’s parent object. Before you attempt to

a particular object, be sure to read its description in

API Objects on page 132.

Createable Fields.

Certain objects cannot be created via the API. To create an object via the

call, its object must be configured as createable (createable is True). To determine whether a given object can be created, your client application can invoke the

call on the object and inspect its createable property.

Automatically Maintained Fields.

The AppExchange Web service generates unique values for ID fields automatically. For

, you cannot explicitly specify an ID value in the sObject

The

[]

object contains the ID of each object that was successfully created. For information on IDs, see

supply a value. For more information, see Required Fields on page 137.

The AppExchange Web service populates certain fields automatically, such as CreatedDate,

CreatedById

, LastModifiedDate, LastModifiedById, and SystemModstamp. You cannot explicitly specify these values.

Required Fields.

For required fields that do not have a preconfigured default value, you must

Default Values.

For some objects, certain fields have a default value, such as OwnerID. If you do not specify a value for such fields, the AppExchange Web service populates these fields with the default value. For example, if you do not override the OwnerID, then the AppExchange Web service populates this field with the user ID associated with the user under which your client application is logged in.

• For required fields that do not have a preconfigured default value, you must supply a value.

• For all other fields in the object, if you do not explicitly specify a value, then its value is null.

Referential Integrity.

Your client application must conform to the rules of referential integrity.

For example, if you are creating an object that is the child of a parent object, you must supply the foreign key information that links the child to the parent. For example, when creating a

CaseComment

, you must supply the valid caseID for the parent

, and that parent Case must exist in the database.

Valid Data 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 specified for your programming language and development tool (your development tool will handle the appropriate mapping of data types in SOAP messages).

Page 61

AppExchange API

String Values.

When storing values in string fields, the AppExchange Web service trims any leading and trailing whitespace. For example, if the value of a name field is entered as

" ABC Company "

, then the value is stored in the database as "ABC Company".

Assignment Rules.

When creating new

Lead objects, your client application can set

options in the

AssignmentRuleHeader to have the case or lead automatically assigned to one or

more users based on assignment rules configured in the Salesforce user interface. For more

information, see Case on page 164 or

create call. If a create request exceeds 200 objects, then the entire operation

Maximum Number of Objects Created.

Your client application can add up to 200 individual objects in a single

fails.

Basic Steps for Creating Objects

Creating objects involves the following basic steps:

1. Instantiate one or more individual objects from the session. For each object, populate its fields with the data that you want to add.

2. Construct an sObject []

array and populate that array with the objects that you want to create. All objects must be of the same type.

3. Call

, passing in the sObject []

array.

4. Process the results in the

[]

object to verify whether the objects have been successfully created.

Sample Code—Java public Boolean createAccountSample()

{

// Create two account objects

Account account1 = new Account();

Account account2 = new Account();

// Set some fields on the account object

// Name field (required) not being set on account1,

// so this record should fail during create.

account1.setAccountNumber("002DF99ELK9");

account1.setBillingCity("Wichita");

account1.setBillingCountry("US");

account1.setBillingState("KA");

account1.setBillingStreet("4322 Haystack Boulevard");

account1.setBillingPostalCode("87901");

// Set some fields on the account2 object

account2.setName("Golden Straw");

account2.setAccountNumber("003DF99ELK9");

account2.setBillingCity("Oakland");

account2.setBillingCountry("US");

account2.setBillingState("CA");

account2.setBillingStreet("666 Raiders Boulevard");

account2.setBillingPostalCode("97502");

// Create an array of SObjects to hold the accounts

SObject[] sObjects = new SObject[2];

// Add the accounts to the SObject array

sObjects[0] = account1;

sObjects[1] = account2;

// Invoke the create call

Page 62

AppExchange API

try {

SaveResult[] saveResults = binding.create(sObjects);

// Handle the results

for (int i=0; i<saveResults.length; i++) {

// Determine whether create succeeded or had errors

if (saveResults[i].isSuccess()) {

// No errors, so we will retrieve the id created for this index

System.out.println(saveResults[i].getId());

}

else {

// Handle the errors

...

}

} catch (InvalidSObjectFault e) {

System.out.println("Invalid object exception encountered:\n\n" + e.getMessage());

return Boolean.FALSE;

} catch (UnexpectedErrorFault e) {

System.out.println("Unexpected error exception encountered:\n\n" + e.getMessage());

return Boolean.FALSE;

} catch (InvalidIdFault e) {

System.out.println("Invalid Id exception encountered:\n\n" + e.getMessage());

return Boolean.FALSE;

} catch (RemoteException e) {

System.out.println("Remote exception encountered:\n\n" + e.getMessage());

return Boolean.FALSE;

}

return Boolean.TRUE;

}

Sample Code—C# private void createAccount()

{

// Create an account object to send to the service

Account account = new Account();

// Set several properties

account.Name = "Koka Kola";

account.Website = "www.kokakola.com";

// Add the account to an array of SObjects

sObject[] records = new sObject[] {account};

// Invoke the create call, passing in the account properties

// and saving the results in a SaveResult object

SaveResult[] saveResults = binding.create(records);

// Access the new ID

String newID = saveResults[0].id;

}

Page 63

AppExchange API

Arguments

Name sObjects

Type

Array of one or more s (up to 200) to create

Description

Response

[]

Faults

InvalidSObjectFault

UnexpectedErrorFault

See Also

upsert on page 121

create call returns an array of SaveResult objects. Each element in the SaveResult array

Sample SOAP Messages - create

SaveResult

The

corresponds to the

sObject [] array passed as the

sObjects

parameter in the create call. For

example, the object returned in the first index in the SaveResult array matches the object

specified in the first index of the sObject

[] array. A SaveResult object has the following properties:

Name id success errors

Type

boolean

Indicates whether the create call succeeded (True) or

Description

ID of the sObject

that you attempted to

create . If this

field contains a value, then the object was created successfully. If this field is empty, then the object was not created and the AppExchange Web service returned error information instead.

not (False) for this object.

If an error occurred during the create

call, an array of

objects providing the error code and description.

Page 64

AppExchange API

delete

Deletes one or more individual objects from your organization’s data.

Syntax

DeleteResult

[] = sfdc.delete(ID[] ids);

Usage

Use

your organization’s data. The delete call is analogous to the DELETE statement in SQL.

to delete one or more existing objects, such as individual accounts or contacts, in

Rules and Guidelines

When deleting objects, consider the following rules and guidelines:

• Your client application must be logged in with sufficient access rights to delete individual objects within the specified object. For more information, see

Factors that Affect Data Access on page 32.

• In addition, you might also need permission to access this object’s parent object. For special

access requirements, see the object’s description in API Objects on page 132.

•

To ensure referential integrity, the delete call supports cascading deletions. If you delete a

parent object, you delete its children automatically, as long as each child object can be

deleted. For example, if you delete a Case , the API automatically deletes any

CaseComment ,

CaseHistory , and

CaseSolution objects associated with that case. However, if a

CaseComment

is not deletable or is currently being used, then the delete call on the parent

Case will fail.

•

Certain objects cannot be deleted via the API. To delete an object via the delete call, its

object must be configured as deletable (deletable is True). To determine whether a given object can be deleted, your client application can invoke the

1. Determine the ID of each object that you want to delete. For example, you might call query

call on the object and inspect its deletable property.

Basic Steps for Deleting Objects

Deleting objects involves the following basic steps:

to retrieve a set of records that you want to delete based on specific criteria.

2. Construct an ID[] array and populate it with the IDs of each object that you want to delete.

You can specify the IDs of different objects. For example, you could specify the ID for an

individual Account

and an individual

Contact in the same array.For information on IDs, see

3. Call

4. Process the results in the

, passing in the ID.[] array.

DeleteResult

[]

object to verify whether the objects have been successfully deleted.

Sample Code—Java public Boolean deleteSample() {

// Create an array of Strings to hold the IDs of the records to delete and add

IDs to the array

String[] ids = new String[] { "001x00000000JerAAE", "001x00000000JesAAE" };

// Invoke the delete call

try {

DeleteResult[] deleteResults = binding.delete(ids);

// Process the results

Page 65

AppExchange API

for (int i=0;i<deleteResults.length;i++) {

DeleteResult deleteResult = deleteResults[i];

// Determine whether delete succeeded or had errors

if (deleteResult.isSuccess()) {

// Get the id of the deleted record

deleteResult.getId();

}

else {

// Handle the errors

Error[] errors = deleteResult.getErrors();

...

}

} catch (UnexpectedErrorFault e) {

System.out.println("Unexpected error encountered:\n\n" + e.getExceptionMessage());

return Boolean.FALSE;

} catch (RemoteException e) {

System.out.println("Remote exception encountered:\n\n" + e.getMessage());

return Boolean.FALSE;

}

return Boolean.TRUE;

}

Sample Code—C# private void deleteAccount()

{

// Delete call takes a string array of Ids as parameter

String[] IDs = new Sring[] {""};

// Invoke the delete call, saving the result in a DeleteResult object

DeleteResult[] deleteResults = binding.delete(IDs);

// Determine whether the delete call succeeded or failed

if (deleteResults[0].success)

{

// Delete operation succeeded

System.Diagnostics.Trace.WriteLine("Deleted: " + deleteResults[0].id);

}

else

{

// Delete operation failed

System.Diagnostics.Trace.WriteLine("Couldn't delete because: " + deleteResults[0].errors[0].message);

}

Arguments

Name ids

Type

ID []

Description

Array of one or more IDs associated with the objects to delete. In version 7.0 and later, you can pass a maximum of 200 object IDs to the

call. In version

6.0 and earlier, the limit is 2,000.

Page 66

AppExchange API

Response

DeleteResult []

Faults

InvalidSObjectFault

UnexpectedErrorFault

See Also

Sample SOAP Messages - delete

DeleteResult

The

array corresponds to the ID[] array passed as the ids

call returns an array of DeleteResult objects. Each element in the DeleteResult

parameter in the

call. For example, the object returned in the first index in the DeleteResult array matches the object specified in the first index of the ID[] array.

A DeleteResult object has the following properties:

Name id success errors

Type

boolean

Description

ID of an

that you attempted to delete. For information on IDs, see

Indicates whether the delete call succeeded (True) or

not (False) for this object.

If an error occurred during the delete call, an array of

DescribeGlobalResult = sfdc.describeGlobal();

objects providing the error information.

Page 67

AppExchange API

describeGlobal

Retrieves a list of available objects for your organization’s data.

Syntax

Usage

Use

describeGlobal to obtain the list of available objects for your organization. You can then

iterate through this list and use

describeSObjects to obtain metadata about individual objects.

Your client application must be logged in with sufficient access rights to retrieve metadata about

your organization’s data. For more information, see Factors that Affect Data Access on page 32.

Sample Code—Java private void describeGlobalSample() {

try

{

DescribeGlobalResult describeGlobalResult = null;

describeGlobalResult = binding.describeGlobal();

String[] types = describeGlobalResult.getTypes();

for (int i=0;i<types.length;i++)

System.out.println(types[i]);

getUserInput("\nDescribe global was successful.\n\nHit the enter key to continue....");

}

catch (Exception ex)

{

System.out.println("\nFailed to return types, error message was: \n" + ex.getMessage());

getUserInput("\nHit return to continue...");

}

Sample Code—C# private void globalDescribe()

{

// Invoke describeGlobal call and save results in DescribeGlobalResult object

DescribeGlobalResult dgr = binding.describeGlobal();

// Iterate through the results

for (int i=0;i<dgr.types.Length;i++)

{

// The dgr.types[i] object is a string

System.Diagnostics.Trace.WriteLine(dgr.types[i]);

}

binding.describeSObject

}

Arguments

None.

Page 68

AppExchange API

Response

DescribeGlobalResult

Fault

UnexpectedErrorFault

See Also

describeSObjects on page 80

describeGlobal call returns a DescribeGlobalResult object, which has the following

Sample SOAP Messages - describeGlobal

DescribeGlobalResult

The

properties.

Name encoding maxBatchSize types

Type

string int string[]

Description

Specifies how an organization’s data is encoded, such as

UTF-8

or ISO-8859-1.

Maximum number of records allowed in a create ,

you pass to describeSObjects .

, or delete call.

List of available objects for your organization. You iterate through this list to retrieve the object string that

Retrieves metadata about page layouts for the specified object type.

Page 69

AppExchange API

describeLayout

Syntax

DescribeLayoutResult = sfdc.describeLayout(string sObjectType);

Usage

Use describeLayout

to retrieve information about the layout (presentation of data to users) for a

given object type. The describeLayout

call returns metadata about a given page layout, including layouts for edit and display-only views and record type mappings. Note that field-level security and layout editability affects which fields appear in a layout.

Users typically have one layout per object type assigned in their user profiles. In Enterprise and

Unlimited Editions, users can have multiple layouts, associated with multiple record types,

defined in their user profile. The describeLayout call returns metadata for multiple layouts, if

applicable.

Note

The

describeLayout call is an advanced API call that is typically used only by partners who have

written custom page rendering code for generating output on a specialized device (for example, on PDAs) and need to examine the layout details of an object before rendering the page output.

Basic Steps for Describing Layouts

Describing layouts involves the following basic steps:

1. To display a detail page, a client application first gets the recordTypeId from the record, then it finds the layoutId associated with that recordTypeId (through

recordTypeMapping

), and finally it uses that layout information to render the page.

2. To display an edit page, a client application first determines whether more than one record type is available and, if so, presents the user with a choice. Once a record type has been chosen, then the client application uses the layout information to render the page. It uses

the picklist values from the RecordTypeMapping to display valid picklist values for picklist

fields.

3. A client application uses describeSObjects to get the labels for layout, using the

value field

on DescribeLayoutComponent

to perform a lookup on the

when the

LayoutComponent

is of type field.

Sample Code—Java private void describeLayoutSample() {

try {

String objectToDescribe = getUserInput("Enter an object name: ");

DescribeLayoutResult dlr = binding.describeLayout(objectToDescribe);

System.out.println("There are " + dlr.getLayouts().length +

" layouts for the " + objectToDescribe + " object.");

for (int i=0;i<dlr.getLayouts().length;i++){

DescribeLayout layout = dlr.getLayouts(i);

System.out.println(" There are " +

layout.getDetailLayoutSections().length + " detail layout sections");

for (int j=0;j<layout.getDetailLayoutSections().length;j++){

DescribeLayoutSection dls = layout.getDetailLayoutSections(j);

System.out.println(new Integer(j).toString() +

" This section has a heading of " + dls.getHeading());

if (layout.getEditLayoutSections() != null) {

System.out.println(" There are " +

layout.getEditLayoutSections().length + " edit layout sections");

Page 70

AppExchange API

}

for (int k=0;k<layout.getEditLayoutSections().length;k++){

DescribeLayoutSection els = layout.getEditLayoutSections(k);

System.out.println(new Integer(k).toString() +

" This section has a heading of " + els.getHeading());

System.out.println("This section has " +

els.getLayoutRows().length + " layout rows.");

for (int l=0;l<els.getLayoutRows().length;l++){

DescribeLayoutRow lr = els.getLayoutRows(l);

System.out.println(" This row has " + lr.getNumItems() + " items.");

for (int h=0;h<lr.getLayoutItems().length;h++){

DescribeLayoutItem li = lr.getLayoutItems(h);

if (li.getLayoutComponents() != null) {

System.out.println(" " +

new Integer(h).toString() +

" " + li.getLayoutComponents(0).getValue());

}

if (dlr.getRecordTypeMappings() != null)

System.out.println("There are " +

dlr.getRecordTypeMappings().length + " record type mappings for the " +

objectToDescribe + " object");

else

System.out.println("There are no record type mappings for the " +

objectToDescribe + " object.");

} catch (Exception e) {

System.out.println("An exceptions was caught: " + e.getMessage());

getUserInput("Press enter to continue...");

}

Sample Code—C# private void describeLayoutSample()

{

try

{

Console.Write("Enter the name of an object to describe the layout of: ");

string objectToDescribe = Console.ReadLine();

sforce.DescribeLayoutResult dlr = binding.describeLayout(objectToDescribe);

Console.WriteLine("There are " + dlr.layouts.Length + " layouts for the " +

objectToDescribe + " object.");

for (int i=0;i<dlr.layouts.Length;i++)

{

sforce.DescribeLayout layout = dlr.layouts[i];

Console.WriteLine(" There are " + layout.detailLayoutSections.Length +

" detail layout sections");

for (int j=0;j<layout.detailLayoutSections.Length;j++)

{

sforce.DescribeLayoutSection dls = layout.detailLayoutSections[j];

Console.WriteLine(j + " This section has a heading of " +

dls.heading);

}

if (layout.editLayoutSections != null)

Page 71

AppExchange API

Arguments

{

Console.WriteLine(" There are " + layout.editLayoutSections.Length

+ " edit layout sections");

for (int j=0;j<layout.editLayoutSections.Length;j++)

{

sforce.DescribeLayoutSection els = layout.editLayoutSections[j];

Console.WriteLine(j + " This section has a heading of " +

els.heading);

Console.WriteLine("This section has " + els.layoutRows.Length +

" layout rows.");

for (int k=0;k<els.layoutRows.Length;k++)

{

sforce.DescribeLayoutRow lr = els.layoutRows[k];

Console.WriteLine(" This row has " + lr.numItems +

" items.");

for (int h=0;h<lr.layoutItems.Length;h++)

{

sforce.DescribeLayoutItem li = lr.layoutItems[h];

if (li.layoutComponents != null)

Console.WriteLine(" " + h + " " +

li.layoutComponents[0].value);

}

if (dlr.recordTypeMappings != null)

Console.WriteLine("There are " + dlr.recordTypeMappings.Length +

" record type mappings for the " + objectToDescribe + " object");

else

Console.WriteLine("There are no record type mappings for the " +

objectToDescribe + " object.");

}

catch (Exception e)

{

Console.WriteLine("An exceptions was caught: " + e.Message);

}

Name sObjectType

Type

string

Description

The specified value must be a valid object for your organization. For a complete list of objects, see

List of

Standard Objects .

Response

DescribeLayoutResult

Faults

InvalidSObjectFault

UnexpectedErrorFault

Page 72

AppExchange API

See Also

The describeLayout call returns a DescribeLayoutResult object containing top-level record type

Sample SOAP Messages - describeLayout

DescribeLayoutResult

information about the passed-in sObjectType, as well as a mapping of record types to layouts.

Your client application can traverse this object to retrieve detailed metadata about the layout.

Name Type Description layouts

DescribeLayout []

Layout(s) associated with the specified

sObjectType

. A user profile typically has only one associated layout per object type.

However, a user profile might have multiple layouts associated with multiple record types.

recordTypeMappings

RecordTypeMapping

[] Record type mapping(s) available for the user.

A user profile may have multiple record types.

All record types are returned—not just those available to the calling user. This allows the client application to display a layout appropriate for a given user profile. For example, suppose User A owns a record, and this record has recordType X set. If User B tries to view this record, then the client application can display the record using the layout associated with this recordType for User

B’s profile (even if the record type is not a available for the user).

DescribeLayout

Represents a specific layout for the specified sObjectType. Each DescribeLayout is referenced by its unique layout ID and consists of two types of views (represented in this object as arrays of

DescribeLayoutSection s):

• Detail view—Read-only display of the object. In a detail layout, certain pieces of

information (such as address details) might be aggregated into a single DescribeLayoutItem

• Edit view—Editable display of the object. In an edit layout, individual pieces of information

(such as an address) will be broken up into separate fields.

An individual DescribeLayout consists of the following fields:

Name Type Description detailLayoutSections

DescribeLayoutSection []

Layout section(s) for the detail view.

editLayoutSections

DescribeLayoutSection []

Layout section(s) for the edit view.

Unique ID of this Layout. For information

DescribeLayout and consists of one or more columns and one or more

Page 73

AppExchange API

DescribeLayoutSection

Represents a section of a

rows (an array of DescribeLayoutRow s).

Name columns heading layoutRows rows useCollapsibleSection useHeading

Type

int string

DescribeLayoutRow []

int boolean boolean

Description

Number of columns in this

Heading text (label) for this

Array of one or more

DescribeLayoutRow s.

Number of rows in this

Indicates whether this

DescribeLayoutSection . A DescribeLayoutRow consists of one or more

is a collapsible section, also known as a “twistie”

(True), or not (False).

Indicates whether to use the heading

(True) or not (False).

DescribeLayoutRow

Represents a row in a

DescribeLayoutItem

s. For each DescribeLayoutRow, a

DescribeLayoutItem refers either to a specific field or to an “empty” DescribeLayoutItem

DescribeLayoutItem that contains no

DescribeLayoutComponent s). An empty DescribeLayoutItem can be returned when a given

DescribeLayoutRow is sparse (for example, containing more fields on the right column than on

the left column). Where there are gaps in the layout, an empty DescribeLayoutItem

is returned as a placeholder.

Name layoutItems numItems

Type

DescribeLayoutItem

[] int

Description

Refers to either a specific field or to an

“empty” LayoutItem (a LayoutItem that contains no

DescribeLayoutComponent s).

Number of layoutItems. This information is redundant but, due to a bug in a popular SOAP toolkit, was required to avoid serialization problems.

Page 74

AppExchange API

DescribeLayoutItem

Represents an individual item in a DescribeLayoutRow

. A DescribeLayoutItem consists of a set of components (

DescribeLayoutComponent

), each of which is either a field or a separator. For most fields on a layout, there is only one component per layout item. However, in a display-only view, the DescribeLayoutItem might be a composite of the individual fields (for example, an address can consist of street, city, state, country, and postal code data). On the corresponding edit view, each component of the address field would be split up into separate DescribeLayoutItems.

Name editable label layoutComponents placeholder required

Type Description

boolean Indicates whether this

DescribeLayoutItem can be edited

(True) or not (False).

string Label text for this DescribeLayoutItem.

DescribeLayoutComponent [] DescribeLayoutComponent (s) for this

DescribeLayoutItem.

boolean Indicates whether this

DescribeLayoutItem is a placeholder

(True) or not (False). If True, then this

DescribeLayoutItem is blank.

boolean Indicates whether this

DescribeLayoutItem is required (True) or not (False). This is useful to know if, for example, you wanted to render required fields in a contrasting color

(such as red).

DescribeLayoutComponent

Represents the smallest unit in a layout—a field or a separator. To reference a field for display, a

client application uses the following notation to reference a field in the describeSObjects call:

LayoutComponent.fieldName

Name tabOrder type value

Type Description

int Indicates the tab order for the item in the row.

layoutComponentType Type of DescribeLayoutComponent. One of the following values:

•

Field

—Field name. A mapping to the name field on

the DescribeSObjectResult .

•

Separator

—Separator character, such as a semicolon

(:) or slash (/).

string Value of this DescribeLayoutComponent.

Page 75

AppExchange API

RecordTypeMapping

Represents a single record type mapping in the recordTypeMappings field in a

DescribeLayoutResult object. This object is a map of valid

recordTypeId s to layoutId s. For displaying a detail view, a client application uses this mapping to determine which layout is associated with the record type on the record. For displaying an edit view, a client application uses this mapping to determine which layout to use (and possibly to allow the user to choose between multiple record types); it will also determine the set of available picklist values.

Name available layoutId name recordTypeId picklistsForRecordType

Type

boolean

defaultRecordTypeMapping

boolean

string

PicklistForRecordType []

Description

Indicates whether this record type mapping is available (True) or not

(False). Availability is used to display a list of available record types to the user when they are creating a new record.

Indicates whether this is the default record type mapping

(True) or not (False).

ID of the layout associated with this record type mapping. For

Name of this record type mapping.

ID of the record type to map. For

Represents a single record type picklist in a RecordTypeMapping

Record type picklist(s) mapped to the recordTypeId.

PicklistForRecordType

. The picklistName matches up with the name

field in the DescribeSObjectResult , and the PicklistForRecordTypes are the set of

acceptable values for the recordType.

Name picklistName picklistValues

Type Description

string Name of the picklist.

PickListEntry

[] Set of picklist values associated with the

recordTypeId

in the

RecordTypeMapping

Page 76

AppExchange API

describeSObject

Describes metadata (field list and object properties) for the specified object.

Note

describeSObjects supersedes this call. We encourage you to use describeSObjects

instead of this call.

Syntax

DescribeSObjectResult = sfdc.describeSObject(string sObjectType);

Usage

Use

to obtain metadata for a given object. You can first call describeGlobal to

retrieve a list of all objects for your organization, then iterate through the list and use

describeSObject to obtain metadata about individual objects.

Your client application must be logged in with sufficient access rights to retrieve metadata about

your organization’s data. For more information, see Factors that Affect Data Access on page 32.

Sample Code—Java public void describeSample()

{

try {

// Invoke describeSObject and save results in DescribeSObjectResult

DescribeSObjectResult describeSObjectResult = binding.describeSObject("Account");

// Determine whether the describeSObject call succeededi

if (! (describeSObjectResult == null)) {

// Retrieve fields from the results

Field[] fields = describeSObjectResult.getFields();

// Get the name of the object

String objectName = describeSObjectResult.getName();

// Get some flags

boolean isActivateable = describeSObjectResult.isActivateable();

// Many other values are accessible

if (! (fields == null)) {

// Iterate through the fields to get properties for each field

for (int i = 0; i < fields.length; i++) {

Field field = fields[i];

int byteLength = field.getByteLength();

int digits = field.getDigits();

String label = field.getLabel();

int length = field.getLength();

String name = field.getName();

PicklistEntry[] picklistValues = field.getPicklistValues();

int precision = field.getPrecision();

String[] referenceTos = field.getReferenceTo();

int scale = field.getScale();

FieldType fieldType = field.getType();

boolean fieldIsCreateable = field.isCreateable();

// Determine whether there are picklist values

if (picklistValues != null) {

System.out.println("Picklist values = ");

for (int j = 0; j < picklistValues.length; j++) {

if (picklistValues[j].getLabel() != null) {

Page 77

AppExchange API

System.out.println(" Item: " + picklistValues[j].getLabel());

}

// Determine whether this field refers to another object

if (referenceTos != null) {

System.out.println("Field references the following objects:");

for (int j = 0; j < referenceTos.length; j++) {

System.out.println(" " + referenceTos[j]);

}

} catch (Exception ex) {

System.out.println("\nFailed to get Account description, error message was:

\n" + ex.getMessage());

}

getUserInput("Press enter to continue...");

}

Sample Code—C# private void sObjectDescribe()

{

// Invoke describeSObject and save results in DescribeSObjectResult

DescribeSObjectResult dsr = binding.describeSObject("Account");

// Get value that indicates whether we can create a record

bool canCreate = dsr.createable;

// Get a field and save its name

String fldName = dsr.fields[0].name;

}

Arguments

Name sObjectType

Type

string

Description

Object. The specified value must be a valid object for

your organization. For a complete list of objects, see List of Standard Objects

Response

describeSObjects on page 80

Faults

InvalidSObjectFault

UnexpectedErrorFault

Page 78

AppExchange API

See Also

describeGlobal on page 68

Sample SOAP Messages - describeSObject

DescribeSObjectResult

Both the

call and the

object. (The describeSObject

call return a DescribeSObjectResult

call has been deprecated.) See DescribeSObjectResult in the

describeSObjects

section for details.

Page 79

AppExchange API

describeSObjects

An array-based version of describeSObject ; describes metadata (field list and object properties)

for the specified object or array of objects.

Note

Use this call instead of

DescribeSObjectResult [] = sfdc.describeSObjects(string sObjectType [] );

Syntax

Usage

Use describeSObjects

to obtain metadata for a given object or array of objects. You can first call

describeGlobal to retrieve a list of all objects for your organization, then iterate through the list

and use describeSObjects to obtain metadata about individual objects. The describeSObjects

call is limited to a maximum of 100 objects.

Your client application must be logged in with sufficient access rights to retrieve metadata about

your organization’s data. For more information, see Factors that Affect Data Access on page 32.

Sample Code—Java private void describeSObjectsSample()

{

try {

DescribeSObjectResult[] describeSObjectResults =

binding.describeSObjects(new String[] {"account", "contact", "lead"});

for (int x=0;x<describeSObjectResults.length;x++)

{

DescribeSObjectResult describeSObjectResult = describeSObjectResults[x];

// Retrieve fields from the results

Field[] fields = describeSObjectResult.getFields();

// Get the name of the object

String objectName = describeSObjectResult.getName();

// Get some flags

boolean isActivateable = describeSObjectResult.isActivateable();

System.out.println("Object name: " + objectName);

// Many other values are accessible

if (fields != null)

{

// Iterate through the fields to get properties for each field

for (int i = 0; i < fields.length; i++)

{

Field field = fields[i];

int byteLength = field.getByteLength();

int digits = field.getDigits();

String label = field.getLabel();

int length = field.getLength();

String name = field.getName();

PicklistEntry[] picklistValues = field.getPicklistValues();

int precision = field.getPrecision();

String[] referenceTos = field.getReferenceTo();

int scale = field.getScale();

FieldType fieldType = field.getType();

boolean fieldIsCreateable = field.isCreateable();

System.out.println("Field name: " + name);

Page 80

AppExchange API

// Determine whether there are picklist values

if (picklistValues != null && picklistValues[0] != null)

{

System.out.println("Picklist values = ");

for (int j = 0; j < picklistValues.length; j++)

{

if (picklistValues[j].getLabel() != null)

{

System.out.println(" Item: " +

picklistValues[j].getLabel());

}

// Determine whether this field refers to another object

if (referenceTos != null && referenceTos[0] != null)

{

System.out.println("Field references the following objects:");

for (int j = 0; j < referenceTos.length; j++)

{

System.out.println(" " + referenceTos[j]);

}

} catch (Exception ex) {

System.out.println("\nFailed to get object descriptions, error message was:

\n" + ex.getMessage());

}

Sample Code—C# private void describeSObjectsSample()

{

sforce.DescribeSObjectResult[] describeSObjectResults = binding.describeSObjects(new string[] {"account", "contact", "lead"});

for (int x=0;x<describeSObjectResults.Length;x++)

{

sforce.DescribeSObjectResult describeSObjectResult = describeSObjectResults[x];

// Retrieve fields from the results

sforce.Field[] fields = describeSObjectResult.fields;

// Get the name of the object

String objectName = describeSObjectResult.name;

// Get some flags

bool isActivateable = describeSObjectResult.activateable;

// Many other values are accessible

if (fields != null)

{

// Iterate through the fields to get properties for each field

for (int i = 0; i < fields.Length; i++)

{

sforce.Field field = fields[i];

int byteLength = field.byteLength;

int digits = field.digits;

string label = field.label;

int length = field.length;

Page 81

AppExchange API

string name = field.name;

sforce.PicklistEntry[] picklistValues = field.picklistValues;

int precision = field.precision;

string[] referenceTos = field.referenceTo;

int scale = field.scale;

sforce.fieldType fieldType = field.type;

bool fieldIsCreateable = field.createable;

// Determine whether there are picklist values

if (picklistValues != null && picklistValues[0] != null)

{

Console.WriteLine("Picklist values = ");

for (int j = 0; j < picklistValues.Length; j++)

{

if (picklistValues[j].label != null)

{

Console.WriteLine(" Item: " +

picklistValues[j].label);

}

// Determine whether this field refers to another object

if (referenceTos != null && referenceTos[0] != null)

{

Console.WriteLine("Field references the following objects:");

for (int j = 0; j < referenceTos.Length; j++)

{

Console.WriteLine(" " + referenceTos[j]);

}

Arguments

The

your organization. For a complete list of objects, see List of Standard Objects

call takes in an array of sObjects.

Name sObjectType

Type

string

Description

Object. The specified value must be a valid object for

Response

describeSObject on page 77

Faults

InvalidSObjectFault

UnexpectedErrorFault

Page 82

AppExchange API

See Also

describeGlobal on page 68

DescribeSObjectResult

The

Indicates whether the object can be created via the

call returns a DescribeSObjectResult object, which has the following properties. Note that, while the Boolean properties indicate whether certain API calls can be used for an object, other factors (such as security settings in the user’s personal profile) also affect whether such operations can be performed on the object.

Name activateable

ChildRelationships createable custom deletable fields keyPrefix label labelPlural layoutable name queryable replicateable retrieveable

Type Description

boolean boolean

Reserved for future use.

ChildRelationship

[] An array of ChildRelationship, which is the name of the sObject that has a foreign key to the sObject being described.

or not (False).

create call (True)

boolean boolean

Field []

string string string boolean string boolean boolean boolean

Indicates whether the object is a custom object (True) or not (False).

Indicates whether the object can be deleted via the delete call (True)

or not (False).

Array of fields associated with the object. The mechanism for retrieving information from this list varies among development tools.

Three character code prefix in the object ID. Object IDs are prefixed with three character codes that specify the type of the object (for

example, Account

objects have a prefix of "001" and

objects have a prefix of "006". The

describeLayout call (True)

call returns a value for objects that have a stable prefix. For object types that do not have a stable or predictable prefix, this field is blank. Therefore, client applications that rely on these codes should use this way of determining object types to ensure forward compatibility.

Label text for a renamed tab (for example, "Patient" in a medical vertical) in the user interface, if applicable, or the object name, if not.

Label text for an object that represents the plural version of an object name, for example, “Accounts.”

Indicates whether the object supports the

or not (False).

Name of the object. This is the same string that was passed in as the sObjectType parameter.

Indicates whether the object can be queried via the query call (True)

or not (False).

Indicates whether the object can be replicated via the getUpdated and

getDeleted calls (True) or not (False).

Indicates whether the object can be retrieved via the retrieve call

(True) or not (False).

Page 83

AppExchange API

Name searchable undeletable updateable urlDetail urlEdit urlNew

Type

boolean boolean boolean string string string

Description

Indicates whether the object can be searched via the search call

(True) or not (False).

Reserved for future use.

Indicates whether the object can be updated via the update call (True)

or not (False).

URL to the view details screen (read-only) for this object. Compare with urlEdit, which is read-write.

Client applications can use this URL to redirect to, or access, the standard Salesforce user interface for standard and custom objects.

To provide flexibility and allow for future enhancements, returned urlDetail

values are dynamic. To ensure that client applications are forward compatible, it is recommended that they use this capability where possible. Note that, for objects for which a stable URL API is not available, this field is returned empty.

URL to the edit screen for this object. For example, the urlEdit field for the Account object returns https://na1.salesforce.com/{ID}/ e

. Substituting the {ID} field for the current object ID will return the

Salesforce Web interface's edit page for that object specific account.

Compare with urlDetail, which is read-only.

Client applications can use this URL to redirect to, or access, the standard Salesforce user interface for standard and custom objects.

To provide flexibility and allow for future enhancements, returned urlDetail

URL to the new/create screen for this object type. Client applications can use this URL to redirect to, or access, the standard Salesforce user interface for standard and custom objects. To provide flexibility and allow for future enhancements, returned urlNew values are dynamic. To ensure that client applications are forward compatible, it is recommended that they use this capability where possible. Note that, for objects for which a stable URL API is not available, this field is returned empty.

ChildRelationship

The name of the sObject that has a foreign key to the sObject being described.

Name cascadeDelete

Type

boolean

childSObject

string

field

string

Description

Indicates whether the child object is deleted when the parent object is deleted (True) or not (False).

The name of the object on which there is a foreign key back to the parent sObject.

The name of the field that has a foreign key back to the parent sObject.

Page 84

AppExchange API

Field

In the DescribeSObjectResult , the fields property contains an array of Field objects. Each field

represents a field in an API object. The array contains only the fields that the user can view, as defined by the user's field-level security settings.

Name autonumber byteLength calculated controllerName

int boolean string

createable

boolean

custom defaultedOnCreate

boolean boolean

dependentPicklist

boolean

digits filterable htmlFormatted label

Type

boolean int boolean boolean string

Description

Indicates whether this field is an autonumber field (True) or not (False).

Analogous to a SQL IDENTITY type, autonumber fields are read only, noncreateable text fields with a maximum length of 30 characters.

Autonumber fields are read-only fields used to provide a unique ID that is independent of the internal object ID (such as a purchase order number or invoice number). Autonumber fields are configured entirely in the

Salesforce user interface. The API provides access to this attribute so that client applications can determine whether a given field is an autonumber field.

For variable-length fields (including binary fields), the maximum size of the field, in bytes.

Indicates whether the field is a custom formula field (True) or not (False).

Note that custom formula fields are always read-only.

The name of the field that controls the values of this picklist. It only applies if type is picklist or multipicklist and dependentPicklist is true. See About Dependent Picklists .

The mapping of controlling field to dependent field is stored in the

validFor

attribute of each PicklistEntry for this picklist. See validFor .

Indicates whether the field can be created (True) or not (False). If True,

then this field value can be set in a create call.

Indicates whether the field is a custom field (True) or not (False).

Indicates whether this field is defaulted when created (True) or not

(False). If True, then Salesforce implicitly assigns a value for this field when the object is created, even if a value for this field is not passed in on the

create call. For example, in the

Opportunity object, the Probability

field has this attribute because its value is derived from the Stage field.

Similarly, the Owner has this attribute on most objects because its value is derived from the current user (if the Owner field is not specified).

Indicates whether a picklist is a dependent picklist (True) where available values depend on the chosen values from a controlling field, or not

(False). See About Dependent Picklists .

For fields of type integer. Maximum number of digits. The AppExchange

Web service returns an error if an integer value exceeds the number of digits.

Indicates whether the field is filterable (True) or not (False). If True, then

this field can be specified in the WHERE clause of a query string in a query

call.

Indicates whether a field such as a hyperlink custom formula field has been formatted for HTML and should not be encoded for display in HTML

(True) or not (False). Also indicates whether a field is a custom formula field has an IMAGE text function.

Text label that is displayed next to the field in the Salesforce user interface. This label can be localized.

Page 85

AppExchange API

Name length name nameField nillable picklistValues precision soapType type updateable

Type

int string boolean boolean

PickListEntry []

int

referenceTo

string[]

restrictedPicklist

boolean

scale

int

SOAPType

FieldType

boolean

Description

For string fields, the maximum size of the field in Unicode characters (not bytes).

Field name used in API calls, such as create

, delete

, and query .

Indicates whether this field is a name field (True) or not (False). Used to identify the name field for standard objects (such as AccountName for an

Account object) and custom objects. Limited to one per entity, except

where FirstName and LastName fields are used (such as in the Contact

object).

Indicates whether the field is nillable (True) or not (False). A nillable field can have empty content. A non-nillable field must have a value in order for the object to be created or saved.

Provides the list of valid values for the picklist. Specified only if restrictedPicklist

is True.

For fields of type double. Maximum number of digits that can be stored, including all numbers to the left and to the right of the decimal point (but excluding the decimal point character).

For fields that refer to other objects, this array indicates the objects of the referenced objects.

Indicates whether the field is a restricted picklist (True) or not (False).

For fields of type double. Number of digits to the right of the decimal point. The AppExchange Web service silently truncates any extra digits to the right of the decimal point, but it returns a fault response if the number has too many digits to the left of the decimal point.

See SOAPType for a list of allowable values.

See FieldType

for a list of allowable values.

Indicates whether the field is updateable (True) or not (False). If True,

then this field value can be set in a update

call.

FieldType

In the Field object associated with the DescribeSObjectResult , the type field can contain one of

the following strings. For more information about field types, see

Field Types on page 133.

type Field Value

string boolean int double date dateTime base64

What the Field Object Contains

String values.

Boolean (True / False) values.

Integer values.

Double values.

Date values.

Date and time values.

Base64-encoded arbitrary binary data (of type base64Binary). Used for

Attachment ,

Document , and

Scontrol objects.

Page 86

AppExchange API

type Field Value

ID reference currency textarea percent phone url email combobox picklist multipicklist anyType

What the Field Object Contains

Primary key field for the object. For information on IDs, see ID Fields on page 136

Cross-references to a different object. Analogous to a foreign key field in

SQL.

Currency values.

String that is displayed as a multi-line text field.

Percentage values.

Phone numbers. Values can include alphabetic characters. Client applications are responsible for phone number formatting.

URL values. Client applications should commonly display these as hyperlinks.

Email addresses.

Comboboxes, which provide a set of enumerated values and allow the user to specify a value not in the list.

Single-select picklists, which provide a set of enumerated values from which only one value can be selected.

Multi-select picklists, which provide a set of enumerated values from which multiple values can be selected.

Values can be any of these types: string, picklist, boolean, int, double

, percent, ID, date, dateTime, url, or email.

SOAPType

The

DescribeSObjectResult returns the fields property, which contains an array of fields whose

value provides information about the object being described. One of those fields, soapType, contains one of the following string values. All of the values preceded by xsd: are XML schema primitive data types. For more information about the XML schema primitive data types, see the

World Wide Web Consortium’s publication XML Schema Part 2: Datatypes at the following URL: http://www.w3.org/TR/xmlschema-2/ .

Value Description tns:ID

Unique ID associated with an sObject

. For information on IDs, see

xsd:anyType

Can be ID, Boolean, double, integer, string, date, or dateTime.

xsd:base64Binary

Base 64-encoded binary data.

xsd:boolean xsd:date xsd:dateTime xsd:double xsd:int xsd:string

Boolean (True / False) values.

Date values.

Date/time values.

Double values.

Integer values.

Character strings.

Page 87

AppExchange API

PickListEntry

In the Field object associated with the

Picklist Field Type on page 135.

, the picklistValues field contains an array of PickListEntry properties. Each PickListEntry can contain any one of the following string values. For more information, see

Name active validFor defaultValue label value

Type

boolean byte[] boolean

Description

Indicates whether this item must be displayed (True) or not (False) in the drop-down list for the picklist field in the user interface.

A set of bits where each bit indicates a controlling value for which this PickListEntry is valid. See About

Dependent Picklists .

Indicates whether this item is the default item (True) in the picklist or not (False). Only one item in a picklist is designated as the default.

Display name of this item in the picklist.

Value of this item in the picklist.

string string

About Dependent Picklists

A dependent picklist works in conjunction with a controlling field to filter its values. The value chosen in the controlling field affects the values available in the dependent picklist.

A dependent picklist can be any custom picklist or multi-select picklist field that displays available values based on the value selected in its corresponding controlling field. A controlling field can be any standard or custom picklist (with at least one and less than 200 values) or checkbox field whose values control the available values in one or more corresponding dependent fields.

In the following example, the controlling picklist Beverage has two values, which relate to the values of the dependent picklist Beverage Variety:

Beverage

Coffee

Tea

Beverage Variety

Decaffeinated

Regular

Chamomile

Earl Grey

English Breakfast

For each PickListEntry that represents a value in a dependent picklist, the validFor attribute contains a set of bits. Each bit indicates a controlling field value for which the PickListEntry is valid. Read the bits from left to right.

For more information on dependent picklists, see the “About Dependent Fields” topic in the

Salesforce online help.

Sample Code for Dependent Picklists

// helper class to decode a "validFor" bitset class Bitset {

byte[] data;

public Bitset(byte[] data) {

Page 88

AppExchange API

this.data = data == null?new byte[0]:data;

}

public boolean testBit(int n) {

return (data[n>>3] & (0x80 >> n % 8)) != 0;

}

public int size() {

return data.length * 8;

}

...

DescribeSObjectResult describeSObjectResult = getClient().describeSObject("Case");

Field[] fields = describeSObjectResult.getFields();

// create a map of all fields for later lookup Map fieldMap = new HashMap(); for(int i=0;i<fields.length;i++) {

fieldMap.put(fields[i].getName(),fields[i]);

} for(int i=0;i<fields.length;i++) {

// check whether this is a dependent picklist

if(Boolean.TRUE.equals(fields[i].getDependentPicklist())) {

// get the controller by name

Field controller = (Field)fieldMap.get(fields[i].getControllerName());

System.out.println("Field '"+fields[i].getLabel()+"' depends on

'"+controller.getLabel()+"'");

PicklistEntry[] picklistValues = fields[i].getPicklistValues();

for(int j = 0;j<picklistValues.length;j++) {

// for each PicklistEntry: list all controlling values for which it is valid

System.out.println("Item: '"+picklistValues[j].getLabel()+"' is valid for:");

Bitset validFor = new Bitset(picklistValues[j].getValidFor());

if("picklist".equals(controller.getType().getValue())) {

// if the controller is a picklist, list all

// controlling values for which this entry is valid

for(int k = 0;k<validFor.size();k++) {

if(validFor.testBit(k)) {

// if bit k is set, this entry is valid for the

// for the controlling entry at index k

System.out.println(" "+controller.getPicklistValues()[k].getLabel());

}

} else if("boolean".equals(controller.getType().getValue())) {

// the controller is a checkbox

// if bit 1 is set this entry is valid if the controller is checked

if(validFor.testBit(1)) {

System.out.println(" checked");

}

// if bit 0 is set this entry is valid if the controller is not checked

if(validFor.testBit(0)) {

System.out.println(" unchecked");

}

Page 89

AppExchange API

describeTabs

The describeTabs call returns information about the standard apps and custom apps, if any, available for the user who sends the call, including the list of tabs defined for each app.

Syntax

DescribeTabSetResult [] = sfdc.describeTabs();

Usage

Use the

describeTabs call to obtain information about the standard apps or custom apps that are

configured for the user. The describeTabs call returns the minimum required metadata that can be used to render standard and custom apps in another user interface. Typically this call is used by partner applications to render Salesforce data in another user interface.

In the Salesforce user interface, users have access to standard apps (and may also have access to custom apps) as listed in the AppExchange app menu at the top of the page. Selecting a standard app or custom app in the UI allows the user to switch between the listed apps at any time.

For each app, the call returns the app name, the URL of the logo, whether or not it is the currently selected application for the user, and details about the tabs displayed for that app.

For each tab, the call returns the tab name, the primary

sObject that is displayed on the tab,

whether it is a custom tab, and the URL for viewing that tab. Note that the “All Tabs” tab is never included in the list of tabs.

Sample Code—Java private void describeTabSet ()

{

try {

DescribeTabSetResult[] dtsrs = binding.describeTabs();

System.out.println("There are " + new Integer(dtsrs.length).toString() + " tabsets defined.");

for (int i=0;i<dtsrs.length;i++) {

System.out.println("Tabset " + new Integer(i + 1).toString() + ":");

DescribeTabSetResult dtsr = dtsrs[i];

String tabSetLabel = dtsr.getLabel();

String logoUrl = dtsr.getLogoUrl();

boolean isSelected = dtsr.isSelected();

DescribeTab[] tabs = dtsr.getTabs();

System.out.println("Label is " + tabSetLabel + " logo url is " + logoUrl +

", there are " + new Integer(tabs.length) + " tabs defined in this set. This tab is selected: " + isSelected);

for (int j=0;j<tabs.length;j++) {

DescribeTab tab = tabs[j];

String tabLabel = tab.getLabel();

String objectName = tab.getSobjectName();

String tabUrl = tab.getUrl();

System.out.println("\tTab " + new Integer(j + 1) + ": \n\t\tLabel = " +

tabLabel + "\n\t\tObject details on tab: " + objectName + "\n\t\t" +

"Url to tab: " + tabUrl);

}

} catch (Exception ex) {

System.out.println("\nFailed to describe tabs, error message was: \n" + ex.getMessage());

Page 90

AppExchange API

}

Sample Code—C# sforce.DescribeTabSetResult[] dtsrs = binding.describeTabs();

Console.WriteLine("There are " + dtsrs.Length.ToString() + " tabsets defined."); for (int i=0;i<dtsrs.Length;i++)

{

Console.WriteLine("Tabset " + (i + 1).ToString() + ":");

sforce.DescribeTabSetResult dtsr = dtsrs[i];

String tabSetLabel = dtsr.label;

String logoUrl = dtsr.logoUrl;

bool isSelected = dtsr.selected;

DescribeTab[] tabs = dtsr.tabs;

Console.WriteLine("Label is " + tabSetLabel + " logo url is " + logoUrl + ", there are " + tabs.Length.ToString() + " tabs defined in this set.");

for (int j=0;j<tabs.Length;j++)

{

sforce.DescribeTab tab = tabs[j];

String tabLabel = tab.label;

String objectName = tab.sobjectName;

String tabUrl = tab.url;

Console.WriteLine("\tTab " + (j + 1).ToString() + ": \n\t\tLabel = " + tabLabel +

"\n\t\tObject details on tab: " + objectName + "\n\t\t" +

"Url to tab: " + tabUrl);

}

Arguments

None.

Response

DescribeTabSetResult ,

DescribeTab

See Also

describeTabs call returns a DescribeTabSetResult object, which has the following

DescribeTabSetResult

The

properties:

Name

label logoUrl

Type

string string

Description

The display label for this standard or custom app.

A fully qualified URL to the logo image associated with the standard or custom app.

Page 91

AppExchange API

Name

selected tabs

Type

boolean

DescribeTab

Description

If True, then this standard or custom app is the user’s currently selected app.

An array of tabs that are displayed for the specified standard app or custom app.

DescribeTab

The describeTabs

call returns a DescribeTabSetResult

object, of which

DescribeTab

is a property:

Name

custom label sobjectName url

Type

boolean string string string

Description

True if this is a custom tab, False if this is a standard tab.

The display label for this tab.

The name of the

sObject that is primarily displayed on

this tab (for tabs that display a particular SObject). For a

list of objects, see List of Standard Objects

A fully qualified URL for viewing this tab.

Page 92

AppExchange API

getDeleted

Retrieves the list of individual objects that have been deleted within the given timespan for the specified object.

Syntax

GetDeletedResult

= sfdc.getDeleted(string sObjectType dateTime startDate dateTime

EndDate);

Usage

Use

been deleted from your organization’s data within the specified timespan. The getDeleted call

for data replication applications to retrieve a list of object instances that have

retrieves a GetDeletedResult object that contains an array of DeletedRecord objects containing

the ID of each deleted object and the date/time (GMT timezone) on which it was deleted. Be sure

to read Data Replication on page 51 before using

in your client applications. (For information on IDs, see

ID Fields on page 136.)

The

Polling for Changes on page 53.

call respects the user’s sharing model.

Rules and Guidelines

When replicating deleted objects, consider the following rules and guidelines:

• The specified startDate must chronologically precede the specified endDate value. The specified startDate cannot be the same value as, or later than, the specified endDate value.

Otherwise, the AppExchange Web service returns an INVALID_REPLICATION_DATE error.

• Results are returned for no more than 30 days previous to the day the call is executed.

• Client applications typically poll for changed data periodically. For important polling considerations, see

•

Certain objects cannot be replicated via the API. To replicate an object via the getDeleted

call, its object must be configured as replicateable (replicateable is True). To determine whether a given object can be replicated, your client application can invoke the

describeSObjects call on the object and inspect its replicateable property.

• Development tools differ in the way that they handle time data. Some development tools report the local time, while others report only the GMT time. To determine how your development tool handles time values, refer to its documentation.

Basic Steps for Replicating Deleted Objects

Replicating objects involves the following basic steps for each object that you want to replicate:

1. Optionally, the client application determines whether the structure of the object has changed

since the last replication request, as described in Checking for Structural Changes in the

Object on page 53.

2. Call

There are record limits on the result

, passing in the object and timespan for which to retrieve data.

3. In the

DeleteResult

object, iterate through the returned array of DeletedRecord objects containing the ID of each deleted object and the date/time (GMT timezone) on which it was deleted.

4. Your client application must then take the appropriate action on the local data to remove (or flag as deleted) the deleted objects.

5. Optionally, the client application saves the request timespan for future reference.

A client application likely performs other tasks associated with data replication operations. For example, if an opportunity were to become closed, a client application might run a new revenue report. Similarly, if a task were completed, the process might log this somehow in another system.

Page 93

AppExchange API

Sample Code—Java private void getDeletedSample() {

try {

// You can use the timestamp from the service for a known point in time

Calendar serverTime = binding.getServerTimestamp().getTimestamp();

// Create a start time value for the call

GregorianCalendar startTime = (GregorianCalendar) serverTime.clone();

// Create an end time value for the call

GregorianCalendar endTime = (GregorianCalendar) serverTime;

// Subtract 5 mins from the server time so that we have a valid time frame.

// You can use just about any timespan you want, 5 minutes is arbitrary

endTime.add(GregorianCalendar.MINUTE, -5);

System.out.println("Checking deletes at: " + startTime.getTime().toString());

GetDeletedResult gdr = binding.getDeleted("Contact", startTime, endTime);

// Check the number of records contained in the results, if more that 0,

// then something was deleted in the 5 minute span

if (gdr.getDeletedRecords() != null && gdr.getDeletedRecords().length > 0) {

for (int i=0;i<gdr.getDeletedRecords().length;i++) {

System.out.println(gdr.getDeletedRecords(i).getId() + " was deleted on " + gdr.getDeletedRecords(i).getDeletedDate().getTime().toString());

}

} else {

System.out.println("No deletions from contacts in the last 5 minutes.");

}

} catch (Exception ex) {

System.out.println("\nException caught, error message was: \n" + ex.getMessage());

}

Sample Code—C# private void getDeletedSample()

{

DateTime endTime = binding.getServerTimestamp().timestamp;

DateTime startTime = endTime.Subtract(new System.TimeSpan(0, 0, 5, 0, 0));

sforce.GetDeletedResult gdr = binding.getDeleted("Contact", startTime, endTime);

if (gdr.deletedRecords.Length > 0)

{

for (int i=0;i<gdr.deletedRecords.Length;i++)

{

Console.WriteLine(gdr.deletedRecords[i].id + " was deleted on " + gdr.deletedRecords[i].deletedDate.ToString());

}

else

{

Console.WriteLine("No deleted contacts between " + startTime.ToString() +

" and " + endTime.ToString() );

}

Page 94

AppExchange API

Arguments

Name sObjectType startDate endDate

Type

string dateTime dateTime

Description

Object. The specified value must be a valid object for your organization. See

sObject .

Starting date/time (GMT—not local—timezone) of the timespan for which to retrieve the data. The

AppExchange Web service ignores the seconds portion of the specified dateTime value (for example, 12:30:15 is interpreted as 12:30:00 GMT).

Ending date/time (GMT—not local—timezone) of the timespan for which to retrieve the data. The

AppExchange Web service ignores the seconds portion of the specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 GMT).

Limits

GetDeletedResult

•

If your getDeleted

call returns more than 600,000 records and the user is a system administrator, an exception EXCEEDED_ID_LIMIT is returned.

•

If your getDeleted

call returns more than 20,000 records and the user is not a system administrator, an exception OPERATION_TOO_LARGE is returned. Note that this error is returned when more than 20,000 records across the organization have been deleted, not just the records viewable by the user.

You can correct the error by choosing start and end dates that are closer together.

Response

GetDeletedResult

Faults

InvalidSObjectFault

UnexpectedErrorFault

See Also

getUpdated

Data Replication on page 51

The getDeleted call returns a GetDeletedResult object that contains an array of DeletedRecord

Sample SOAP Messages - getDeleted

GetDeletedResult

objects. Each element in the DeletedRecord array corresponds to an object that was deleted within the given timespan. Each DeletedRecord object has the following properties:

Page 95

AppExchange API

Name id modifiedDate

Type

dateTime

Description

ID of an

getUpdated for data replication applications to retrieve a set of IDs for objects of the

that has been deleted.

Date/time (GMT—not local—timezone) on which this object was deleted.

Page 96

AppExchange API

getUpdated

Retrieves the list of individual objects that have been updated (added or changed) within the given timespan for the specified object.

Syntax

GetUpdatedResult

[] = sfdc.getUpdated(string sObjectType dateTime startDate dateTime EndDate);

Usage

Use

specified object that have been created or updated within the specified timespan. The

call retrieves an array of

GetUpdatedResult

objects containing the ID of each

created or updated object and the date/time (GMT timezone) on which it was created or updated, respectively. Be sure to read

Data Replication on page 51 before using

getUpdated call retrieves the IDs only for objects to which the logged in user has access.

in your client application.

Note

The

For example, data that is outside of the user’s sharing model is not returned.

Rules and Guidelines

When replicating created and updated objects, consider the following rules and guidelines:

• The specified startDate must chronologically precede the specified endDate value. The specified startDate cannot be the same value as, or later than, the specified endDate value.

Otherwise, the AppExchange Web service returns an INVALID_REPLICATION_DATE error.

• Results are returned for no more than 30 days previous to the day the call is executed.

• Client applications typically poll for changed data periodically. For important polling considerations, see

Polling for Changes on page 53.

• Your client application can replicate any objects to which it has sufficient permissions. For example, to replicate all data for your organization, your client application must be logged in with “View All Data” access rights to the specified object. Similarly, the objects must be

within your sharing rules. For more information, see Factors that Affect Data Access on page 32.

•

Certain objects cannot be replicated via the API. To replicate an object via the getUpdated

call, its object must be configured as replicateable (replicateable is True). To determine whether a given object can be replicated, your client application can invoke the

describeSObjects call on the object and inspect its replicateable property.

• Certain objects cannot be deleted, such as

objects.

However, if instances of these objects are no longer visible in the Salesforce user interface, then they might have been rendered inactive so that only users with administrative access can see them. To determine whether a missing object instance has been made inactive, your client application can call

getUpdated and check the object’s active flag.

Basic Steps for Replicating Updated Objects

Replicating objects involves the following basic steps for each object that you want to replicate:

1. Optionally, the client application determines whether the structure of the object has changed

since the last replication request, as described in Checking for Structural Changes in the

Object on page 53.

Page 97

AppExchange API

2. Call

getUpdated , passing in the object and timespan for which to retrieve data.

3. Iterate through the returned array of IDs. For each ID element in the array, call retrieve to

obtain the latest information you want from the associated object. Your client application must then take the appropriate action on the local data, such as inserting new rows or updating existing ones with the latest information.

4. Optionally, the client application saves the request timestamp for future reference.

Sample Code—Java private void getUpdatedSample() {

try {

// You can use the server timestamp as known point in time

Calendar serverTime = binding.getServerTimestamp().getTimestamp();

// Create a start time value for the call

GregorianCalendar startTime = (GregorianCalendar) serverTime.clone();

// Create an end time value for the call

GregorianCalendar endTime = (GregorianCalendar) serverTime;

// subtract 5 mins from the server time so

// that we have a valid time frame, you can use just

// about any timespan you want, 5 minutes is arbitrary

startTime.add(GregorianCalendar.MINUTE, -5);

System.out.println("Checking updates at: " + startTime.getTime().toString());

GetUpdatedResult ur = binding.getUpdated("Account", startTime, endTime);

// Check the length of the returned array of IDs

// to detect if you got any hits

if (ur.getIds() != null && ur.getIds().length > 0) {

for (int i=0;i<ur.getIds().length;i++) {

System.out.println(ur.getIds(i) + " was updated between " + startTime.getTime().toString() + " and " + endTime.getTime().toString());

}

} else {

System.out.println("No updates to accounts in the last 5 minutes.");

}

} catch (Exception ex) {

System.out.println("\nException caught, error message was: \n" + ex.getMessage());

}

Sample Code—C# private void getUpdatedSample()

{

DateTime endTime = binding.getServerTimestamp().timestamp;

DateTime startTime = endTime.Subtract(new System.TimeSpan(0, 0, 5, 0, 0));

sforce.GetUpdatedResult gur = binding.getUpdated("Account", startTime, endTime);

if (gur.ids.Length > 0)

{

for (int i=0;i<gur.ids.Length;i++)

{

Page 98

AppExchange API

Arguments

Console.WriteLine(gur.ids[i] + " was updated between " + startTime.ToString() + " and " + endTime.ToString());

}

else

{

Console.WriteLine("No updates to accounts between " + startTime.ToString()

+ " and " + endTime.ToString() );

}

Name sObjectType startDate endDate

Type

string dateTime dateTime

Description

Object. The specified value must be a valid object for your organization. For a list of standard objects, see

List of Standard Objects

Starting date/time (GMT—not local—timezone) of the timespan for which to retrieve the data. The

AppExchange Web service ignores the seconds portion of the specified dateTime value (for example, 12:30:15 is interpreted as 12:30:00 GMT).

Ending date/time (GMT—not local—timezone) of the timespan for which to retrieve the data. The

AppExchange Web service ignores the seconds portion of the specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 GMT).

Important:

There is a 600,000 record limit on the result

GetUpdatedResult []

. If your

Data Replication on page 51

call returns more than 600,000 records, an exception EXCEEDED_ID_LIMIT is returned. You can correct the error by choosing start and end dates that are closer together.

Response

GetUpdatedResult

[]

Faults

InvalidSObjectFault

UnexpectedErrorFault

See Also

getDeleted

getUpdated call returns an array of GetUpdatedResult objects. Each element in the

Sample SOAP Messages - getUpdated

Page 99

AppExchange API

GetUpdatedResult

The

GetUpdatedResult

array corresponds to an object that was inserted or updated within the given timespan. A GetUpdatedResult object has the following properties:

Name id

Type

Description

ID of an

that has been updated.

Page 100

AppExchange API

login

Logs in to the login server and starts a client session.

Syntax

= sfdc.login(string username, string password);

Usage

Use the

call to log in to the login server and start a client session. A client application must log in and obtain a session ID and server URL before making any other API calls.

When a client application invokes the

call, it passes in a user name and password. Upon invocation, the AppExchange Web service authenticates the login and returns the session ID for the session, the user ID associated with the logged in user name, and an URL that points to the

AppExchange Web service to use in all subsequent API calls.

After logging in, a client application needs to:

• set the session ID in the SOAP header so that the AppExchange Web service can validate subsequent requests for this session

• specify the server URL as the target for subsequent service requests

Development tools differ in the way you specify session headers and server URLs. For more information, see the documentation for your particular development tool.

Client applications do not need to explicitly log out to end the session. Sessions expire automatically after a predetermined length of time, which can be configured at Setup | Security

Controls. The default is 120 minutes (two hours).

If you will be repeatedly logging in and your organization’s password policy forces users to change their passwords every certain number of days, you should enable the “Password Never

Expires” option on your profile.

Sample Code—Java private boolean login() {

LoginResult loginResult = null;

SoapBindingStub sfdc = null;

try {

// Create binding object

sfdc = (SoapBindingStub) new SforceServiceLocator().getSoap();

// login

loginResult = sfdc.login("username", "password");

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

return false;

}

System.out.println("Login was successful.");

// Reset the SOAP endpoint to the returned server URL

sfdc._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_PROPERTY, loginResult.getServerUrl());

// Create a new session header object

// add the session ID returned from the login

SessionHeader sh = new SessionHeader();

sh.setSessionId(loginResult.getSessionId());

// Set the session header for subsequent call authentication

Page 101

AppExchange API

sfdc.setHeader(new SforceServiceLocator().getServiceName().getNamespaceURI(),

"SessionHeader", sh);

// get user info

try {

GetUserInfoResult userInfo = sfdc.getUserInfo();

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

return false;

}

return true;

}

Sample Code—C# private void login()

{

// Create service object

SforceService sfdc = new SforceService();

// Invoke the login call and save results in LoginResult

LoginResult lr = sfdc.login("username","password");

// Reset the SOAP endpoint to the returned server URL

sfdc.Url = lr.serverUrl;

// Create a new session header object

// Add the session ID returned from the login

sfdc.SessionHeaderValue = new SessionHeader();

sfdc.SessionHeaderValue.sessionId = lr.sessionId;

sfdc.GetUserInfoResult userInfo = lr.userInfo;

}

Arguments

Name username password

Type

string string

Response

Faults

LoginFault

UnexpectedErrorFault

See Also

GetUserInfoResult User information fields. For a list of these fields, see GetUserInfoResult

Sample SOAP Messages - login

Description

Page 102

AppExchange API

LoginResult

The

call returns a LoginResult object, which has the following properties:

Name Type Description passwordExpired serverUrl sessionID userID userInfo

boolean string string

Indicates whether the password used during the login attempt is expired

(True) or not (False). If the password has expired, then the AppExchange

Web service returns a valid sessionId, but the only allowable operation is

the setPassword

call.

URL of the Web service that will process subsequent API calls. Your client application needs to set the end point.

Unique ID associated with this session. Your client application needs to set this value in the session header.

ID of the user associated with the specified username and password.

Page 103

AppExchange API

query

Executes a query against the specified object and returns data that matches the specified criteria.

Syntax

Use the query call to retrieve data from an object. When a client application invokes the query

= sfdc.query(string queryString);

Usage

call, it passes in a query expression that specifies the object to query, the fields to retrieve, and any conditions that determine whether a given object qualifies. For an extensive discussion

about the syntax and rules used for queries, see Sforce Object Query Language (SOQL) on page 38.

Upon invocation, the Web service executes the query against the specified object, caches the results of the query on the Web service, and returns a query response object to the client application. The client application can then use methods on the query response object to iterate through rows in the query response and retrieve information.

Your client application must be logged in with sufficient access rights to query individual objects within the specified object and to query the fields in the specified field list. For more information, see

Factors that Affect Data Access on page 32.

Certain objects cannot be queried via the API. To query an object via the

queried, your client application can invoke the describeSObjects call on the object and inspect its

call, its object must be configured as queryable (queryable is True). To determine whether an object can be

queryable

property.

Suggestion: If you use the Enterprise WSDL, you should not use describe to populate a select list. For example, if a system administrator adds a field to the WSDL after you consume it, the

describe

will pull down the field but your toolkit won’t know how to serialize it, and your integration may fail.

The query response object contains up to 500 rows of data by default. If the query results

exceed 500 rows, then the client application uses the

queryMore

call and a server-side cursor to

retrieve additional rows in 500-row chunks. You can increase the default size up to 2,000 in the

QueryOptions header, as described in Changing the Batch Size in Queries on page 42.

Queries that take longer than two minutes to process will be timed out. For timed out queries,

the AppExchange Web service returns an ExceptionCode

of QUERY_TIMEOUT . If a timeout occurs, refactor your query to return or scan a smaller amount of data.

When querying for fields of type Base64 (see base64Binary on page 24), the query response

object returns only one record at a time. You cannot alter this by changing the batch size of the

query call.

Note

For multi-currency organizations, special handling is required when querying currency fields containing values in different currencies. For example, if a client application is querying

PricebookEntry objects based on values in the UnitPrice field, and if the UnitPrice amounts

are expressed in different currencies, then the query logic must handle this case correctly. For example, if the query is trying to retrieve the product codes of all products with a unit price greater than or equal to $10USD. the query expression might look something like this: select Product2Id,ProductCode,UnitPrice from PricebookEntry where (UnitPrice >= 10 and CurrencyIsoCode="USD") or (UnitPrice >= 5.47 and CurrencyIsoCode="GBP") or (UnitPrice >= 8.19 and CurrencyIsoCode="EUR")

Page 104

AppExchange API

Sample Code—Java private void querySample() {

QueryResult qr = null;

QueryOptions qo = new QueryOptions();

qo.setBatchSize(new Integer(250));

binding.setHeader(new

SforceServiceLocator().getServiceName().getNamespaceURI(), "QueryOptions", qo);

try {

qr = binding.query("select FirstName, LastName from Contact");

boolean done = false;

if (qr.getSize() > 0){

System.out.println("Logged in user can see " + qr.getRecords().length + " contact records.");

while (!done) {

for (int i=0;i<qr.getRecords().length;i++) {

Contact con = (Contact)qr.getRecords(i);

String fName = con.getFirstName();

String lName = con.getLastName();

if (fName == null)

System.out.println("Contact " + (i + 1) + ": " + lName);

else

System.out.println("Contact " + (i + 1) + ": " + fName + " " + lName);

}

if (qr.isDone()) {

done = true;

} else {

qr = binding.queryMore(qr.getQueryLocator());

}

else {

System.out.println("No records found.");

}

System.out.println("\nQuery succesfully executed.");

}

catch (RemoteException ex) {

System.out.println("\nFailed to execute query succesfully, error message was:

\n" + ex.getMessage());

}

Sample Code—C# private void contactQuery()

{

// Set the query options (Optional; default batch size is 2000)

binding.QueryOptionsValue = new QueryOptions();

binding.QueryOptionsValue.batchSize = 500;

binding.QueryOptionsValue.batchSizeSpecified = true;

// Invoke the query call and save the result in a QueryResult

QueryResult qr = binding.query("select FirstName, LastName from contact where

MailingPostalCode = '94062'");

// Get the returned records

sObject[] records = qr.records;

Page 105

AppExchange API

Arguments

// Determine whether some records where returned

if (records.Length > 0)

{

bool done = false; // Use this for loop control

while (done == false) // Or while(!done)

{

for (int i=0; i<records.Length; i++)

{

Contact contact = (Contact)records[i];

System.Diagnostics.Trace.WriteLine(contact.FirstName + " " + contact.LastName);

}

// Update the loop control

done = qr.done;

// Determine whether we need to retrieve another batch of result records

if (done == false)

{

qr = binding.queryMore(qr.queryLocator);

records = qr.records;

}

else

{

done = qr.done;

}

else

{

System.Diagnostics.Trace.WriteLine("no records matched criteria");

}

Name queryString

Type

string

Description

Query string that specifies the object to query, the fields to return, and any conditions for including a specific

object in the query. For more information, see Sforce

Object Query Language (SOQL) on page 38.

Response

Sforce Object Query Language (SOQL) on page 38

Faults

MalformedQueryFault

InvalidSObjectFault

InvalidFieldFault

UnexpectedErrorFault

Page 106

AppExchange API

See Also

queryMore on page 108

Changing the Batch Size in Queries on page 42

Sample SOAP Messages - query

QueryResult

The

queryMore for retrieving subsequent sets of

call returns a QueryResult object, which has the following properties:

Name queryLocator done records size

Type Description

QueryLocator

String. Used in

objects from the query results, if applicable. boolean

the query results (False) using queryMore

int

[]

Represents a server-side cursor. Note that a Salesforce account can have up to five (5) query cursors open at a time.

Indicates whether additional rows need to be retrieved from

, or not (True).

Your client application can use this value as a loop condition while iterating through the query results.

Array of

sObject s representing individual objects of the

specified object and containing data defined in the field list

specified in the queryString .

Total number of rows retrieved in the query. Your client application can use this value to determine whether the query retrieved any rows (size > 0) or not (size = 0).

QueryLocator

In the

object returned by the query

call, the queryLocator field contains a

QueryLocator

object that you will use in a subsequent queryMore

call. Note that:

• You use a given QueryLocator only once. Each time you pass it in a

queryMore call, the Web

service returns a new QueryLocator in the

•

QueryLocator

objects expire automatically after 15 minutes of inactivity.

A QueryLocator represents a server-side cursor. A Salesforce account can have up to five (5) query cursors open at a time. If five QueryLocator cursors are opened when a client application attempts open a new one, then the oldest of the five cursors is released.

Page 107

AppExchange API

queryMore

Retrieves the next batch of objects from a

Syntax

QueryLocator QueryLocator);

= sfdc.queryMore(

Usage

Sample Code—Java

See the

Sample Code—Java for the

call.

Sample Code—C#

See the

Sample Code—C# for the

more than 500) in the result set. The query call retrieves the first 500 records and creates a

call.

Arguments

You use queryMore

to process query

calls that retrieve a large number of records (by default,

server-side cursor that is represented in the queryLocator object. The queryMore

call processes subsequent records in up to 500-record chunks, resets the server-side cursor, and returns a

newly generated QueryLocator

. To iterate through records in the result set, you generally call

True). You can change the maximum number of records returned to up to 2,000. See Changing the Batch Size in Queries on page 42 for more information.

repeatedly until all records in the result set have been processed (the Done flag is

Name queryLocator

Type

QueryLocator

Description

Represents the server-side cursor that tracks the current processing location in the query result set.

Response

Faults

InvalidQueryLocatorFault

UnexpectedErrorFault

See Also

query on page 104

Changing the Batch Size in Queries on page 42

Sample SOAP Messages - queryMore

Page 108

AppExchange API

QueryResult

The

queryMore call returns a QueryResult object, which has the following properties:

Name queryLocator done records size

Type Description

QueryLocator

String. Used in subsequent

queryMore calls for retrieving

sets of objects from the query results, if applicable.

boolean Indicates whether additional rows need to be retrieved from the query results (False) using another

queryMore call, or

not (True). Your client application can use this value as a loop condition while iterating through the query results.

sObject s representing individual objects of the

Array of

specified object and containing data defined in the field list

specified in the queryString .

int Total number of rows retrieved in the query. Your client application can use this value to determine whether the query retrieved any rows (size > 0) or not (size = 0).

QueryLocator

In the

object returned by the queryMore

call, the queryLocator field contains a

QueryLocator

object that you will use in subsequent queryMore

calls. Note that:

• You use a given QueryLocator only once. Each time you pass it in a

queryMore call, the Web

service returns a new QueryLocator in the

sObject [] result = sfdc.retrieve(string fieldList, string sObjectType, ID ids[]);

•

QueryLocator

objects expire automatically after 15 minutes of inactivity.

Page 109

AppExchange API

retrieve

Retrieves one or more objects based on the specified object IDs.

Syntax

Usage

Use the retrieve call to retrieve individual records from an object. The client application passes the list of fields to retrieve, the object, and an array of object IDs to retrieve. The retrieve call

does not return records that have been deleted.

In general, you use

retrieve when you know in advance the IDs of the records to retrieve. Use

query instead to obtain records when you do not know the IDs or when you want to specify other

selection criteria.

Client applications can use

to obtain a set of Opportunity records, iterate through the returned Opportunity

to perform a client-side join. For example, a client application

can run a query

records, obtain the accountId for each Opportunity, and then call retrieve to obtain

information for those accountIds.

Certain objects cannot be retrieved via the API. To retrieve an object via the

call, its object must be configured as retrieveable (retrieveable is True). To determine whether an object can be retrieved, your client application can invoke the

information, see Factors that Affect Data Access on page 32.

call on the object and inspect its retrievable property.

Your client application must be logged in with sufficient access rights to retrieve individual objects within the specified object and to retrieve the fields in the specified field list. For more

Sample Code—Java private void retrieveSample() {

try {

// Invoke the retrieve call and save results in an array of SObjects

SObject[] sObjects = binding.retrieve("Id, AccountNumber, Name, Website",

"Account", new String[] {"001x0000002kuk1AAA", "001x0000002khE0AAI"});

// Verify that some objects were returned.

// Even though we began with valid object Ids,

// someone else might have deleted them in the meantime.

if (sObjects != null) {

// Loop through the array and print out some properties

for (int i=0;i<sObjects.length;i++) {

// Cast the SObject into an Account object

Account retrievedAccount = (Account)sObjects[i];

System.out.println("Account: " + retrievedAccount.getId());

System.out.println(" AccountNumber = " + retrievedAccount.getAccountNumber());

System.out.println(" Name = " + retrievedAccount.getName());

System.out.println(" Website = " + retrievedAccount.getWebsite());

}

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

}

Page 110

AppExchange API

Sample Code—C# private void retrieve()

{

// Invoke retrieve call and save results in an array of SObjects

sObject[] records = binding.retrieve("FirstName, LastName", "Contact", new

String[] {"", ""});

// Iterate through the results

for (int i=0;i<records.Length;i++)

{

Contact contact = (Contact)records[i];

// Get the contact properties

System.Diagnostics.Trace.WriteLine("Name is: " + contact.FirstName + " " + contact.LastName);

}

Arguments

Name fieldList from ids

Type

string string

ID []

Description

List of one or more fields in the specified object, separated by commas. You must specify valid field names and must have read-level permissions to each specified field. The fieldList defines the ordering of fields in the result

Because using the wildcard might return a very large result set that could slow client application performance, use it only when necessary.

Object from which to retrieve data. The specified value must be a valid object for your organization. For a

complete list of objects, see List of Standard Objects on page 141.

Array of one or more IDs of the objects to retrieve. You can pass a maximum of 2000 object IDs to the

call. For information on IDs, see ID Fields on page 136.

Response

Name result

Type

Array of one or more sObject

Description

s representing individual

objects of the specified object. The number of sObject

s returned in the array matches the number of object IDs passed into the

retrieve call. If you do not have access

to an object or if a passed ID is invalid, the array returns null

for that object. For information on IDs, see ID

Page 111

AppExchange API

Faults

InvalidSObjectFault

InvalidFieldFault

UnexpectedErrorFault

See Also

search to search for objects based on a search string. The search call supports searching

Sample SOAP Messages - retrieve

Page 112

AppExchange API

search

Executes a text search in your organization’s data.

Syntax

SearchResult

= sdfc.search(String searchString);

Usage

Use

custom object. For an extensive discussion about the syntax and rules used for text searches, see

Sforce Object Search Language (SOSL) on page 44.

Certain objects cannot be searched via the API, such as

Attachment

objects. To search an object

via the search call, its object must be configured as searchable (searchable is True). To

determine whether an object can be searched, your client application can invoke the

describeSObjects call on the object and inspect its searchable property.

Sample Code—Java private void searchSample() {

SearchResult sr = null;

try {

// This search will look for a particular phone number in Contacts,

// Leads and Accounts returning similar information for Contact

// and Leads and just the name and phone number for the Accounts

sr = binding.search("find {4159017000} " +

"in phone fields " +

"returning " +

"contact(id, phone, firstname, lastname), " + "lead(id, phone, firstname, lastname), " +

"account(id, phone, name)");

// Put the results into an array of SearchRecords

SearchRecord[] records = sr.getSearchRecords();

// Check the length of the returned array of records to see

// if the search found anything

if (records != null && records.length > 0) {

// We are going to use vectors to hold the results

Vector contacts = new Vector();

Vector leads = new Vector();

Vector accounts = new Vector();

// We will go throught the results and determine what type

// of object we found by using instanceof and add each record

// to the correct vectory

for (int i=0;i<records.length;i++){

SObject record = records[i].getRecord();

if (record instanceof Contact) {

contacts.add(record);

} else if (record instanceof Lead){

leads.add(record);

} else if (record instanceof Account) {

accounts.add(record);

}

// we now have our results sorted into buckets of specific types

// so we can report our findings

if (contacts.size() > 0) {

Page 113

AppExchange API

System.out.println("Found " + new Integer(contacts.size()).toString() + " contacts:");

for (int i=0;i<contacts.size();i++){

Contact c = (Contact) contacts.get(i);

System.out.println(c.getFirstName() + " " + c.getLastName() + " - " + c.getPhone());

}

if (leads.size() > 0) {

System.out.println("Found " + new Integer(leads.size()).toString() + " leads:");

for (int i=0;i<leads.size();i++){

Lead l = (Lead) leads.get(i);

System.out.println(l.getFirstName() + " " + l.getLastName() + " - " + l.getPhone());

}

if (accounts.size() > 0) {

System.out.println("Found " + new Integer(accounts.size()).toString() + " accounts:");

for (int i=0;i<accounts.size();i++){

Account a = (Account) accounts.get(i);

System.out.println(a.getName() + " - " + a.getPhone());

}

} else {

System.out.println("No records were found for the search.");

}

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

}

Sample Code—C# private void searchSample()

{

sr = binding.search("find {4159017000} " +

"in phone fields returning " +

"contact(id, phone, firstname, lastname), " +

"lead(id, phone, firstname, lastname), " +

"account(id, phone, name)");

sforce.SearchRecord[] records = sr.searchRecords;

System.Collections.ArrayList contacts = new System.Collections.ArrayList();

System.Collections.ArrayList leads = new System.Collections.ArrayList();

System.Collections.ArrayList accounts = new System.Collections.ArrayList();

if (records.Length > 0)

{

for (int i=0;i<records.Length;i++)

{

sforce.sObject record = records[i].record;

if (record.GetType() == typeof(sforce.Contact))

{

contacts.Add(record);

}

Page 114

AppExchange API

Arguments

else if (record.GetType() == typeof(sforce.Lead))

{

leads.Add(record);

}

else if (record.GetType() == typeof(sforce.Account) )

{

accounts.Add(record);

}

System.Diagnostics.Trace.WriteLine("out");

}

if (contacts.Count > 0)

{

Console.WriteLine("Found " + contacts.Count + " contacts:");

for (int i=0;i<contacts.Count;i++)

{

sforce.Contact c = (sforce.Contact) contacts[i];

Console.WriteLine(c.FirstName + " " + c.LastName + " - " + c.Phone);

}

if (leads.Count > 0)

{

Console.WriteLine("Found " + leads.Count + " leads:");

for (int i=0;i<leads.Count;i++)

{

sforce.Lead l = (sforce.Lead) leads[i];

Console.WriteLine(l.FirstName + " " + l.LastName + " - " + l.Phone);

}

if (accounts.Count > 0)

{

Console.WriteLine("Found " + accounts.Count + " accounts:");

for (int i=0;i<accounts.Count;i++)

{

sforce.Account a = (sforce.Account) accounts[i];

Console.WriteLine(a.Name + " - " + a.Phone);

}

else

{

Console.WriteLine("No records were found for the search.");

}

Name searchString

Type

string

Description

Search string that specifies the text expression to search for, the scope of fields to search, the list of objects and fields to retrieve, and the maximum number of objects to return. For more information, see

Sforce Object

Search Language (SOSL) on page 44.

Page 115

AppExchange API

Response

SearchResult

Fault

MalformedSearchFault

See Also

Sample SOAP Messages - search

SearchResult

The

call returns a SearchResult object, which has the following properties:

Name searchRecords

Type Description

SearchRecord[] Array of SearchRecord objects, each of which contains an

sObject .

Page 116

AppExchange API

update

Updates one or more existing objects in your organization’s data.

Syntax

[] = sfdc.update( sObject

[] sObjects);

Usage

Use

your organization’s data. The update

to update one or more existing objects, such as individual accounts or contacts, in

call is analogous to the UPDATE statement in SQL.

Rules and Guidelines

When updating objects, consider the following rules and guidelines:

Permissions.

Your client application must be logged in with sufficient access rights to update

individual objects (as well as individual fields inside that object) within the specified object. For

more information, see Factors that Affect Data Access on page 32.

Special Handling.

Certain objects—and certain fields within those objects—require special handling or permissions. For example, you might also need permissions to access this object’s

parent object. Before you attempt to update a particular object, be sure to read its description in

API Objects on page 132.

Updateable Objects.

Certain objects cannot be updated via the API. To update an object via

the update

call, its object must be configured as updateable (updateable is True). To determine

whether an object can be updated, your client application can invoke the describeSObjects

call on the object and inspect its updateable property.

Required Fields.

When updating required fields, you must supply a value—you cannot set the value to null. For more information, see

Required Fields on page 137.

ID Fields.

Fields whose names contain “Id” are either that object’s primary key (see ID Fields

on page 136) or a foreign key (see Reference Field Type on page 135). Client applications cannot

update primary keys, but they can update foreign keys. For example, a client application can update the OwnerId of an

Account , because OwnerID is a foreign key that refers to the user who

owns the account record. Use describeSObjects to confirm whether the field can be updated.

Automatically Updated Fields.

The AppExchange Web service updates certain fields automatically, such as LastModifiedDate, LastModifiedById, and SystemModstamp. You

cannot explicitly specify these values in your update

call.

Resetting Values to null.

To reset a field value to null, you add the field name to the fieldsToNull

array in the sObject . You cannot set required fields (nillable is False) to null.

Valid Field Values.

String Values.

When storing values in string fields, the AppExchange Web service trims any leading and trailing white space. For example, if the value of a name field is entered as

" ABC Company "

, then the value is stored in the database as "ABC Company".

Assignment Rules.

When updating

Lead objects, your client application can set

AssignmentRuleHeader options to have the case or lead automatically assigned to one or more

users based on assignment rules configured in the Salesforce user interface. For more

information, see Case on page 164 or

update call. If an update request exceeds 200 objects, then the

Page 117

AppExchange API

Maximum Number of Objects Created.

Your client application can change up to 200 individual objects in a single

entire operation fails.

Basic Steps for Updating Objects

Updating objects involves the following basic steps:

1. Determine the ID of each object that you want to update . For example, you might call

to retrieve a set of objects (with their IDs), based on specific criteria, that you would want to update. If you know the ID of the object that you want to update, you can call

instead. For information on IDs, see

3. Construct an sObject []

2. For each object, populate its fields with the data that you want to update.

array and populate that array with the objects that you want to update. All objects must be of the same object.

4. Call

, passing in the

5. Process the results in the

[]

array.

[]

object to verify whether the objects have been successfully updated.

Sample Code—Java public void updateAccountSample() {

// Create an array of SObjects to send to the update method

Account[] updates = new Account[2];

// This account could also be from the results of a retrieve or query call

Account updateAccount = new Account();

updateAccount.setId("001x0000002kuk2AAA");

updateAccount.setShippingPostalCode("94105");

updates[0] = updateAccount;

Account updateAccount2 = new Account();

updateAccount2.setId("001x0000002kuk1AAA");

updateAccount2.setWebsite("www.website.com");

updates[1] = updateAccount2;

// Invoke the update call and save the results

try {

SaveResult[] saveResults = binding.update(updates);

}

catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

getUserInput ("\nUpdate failed. Press return to continue...");

return;

}

getUserInput ("\nUpdate done. Press return to continue...");

}

Sample Code—C# private void update()

{

// You would typically retrieve an SObject, modify its properties,

// and then send the objects up in an array. For this sample,

// we create a new contact object to update by setting

// the id to a valid contact id

Contact contact = new Contact();

contact.Id = ""; // This should be a valid ID

contact.MailingCity = "new city";

Page 118

AppExchange API

Arguments

contact.MailingPostalCode = "98776";

// Invoke the update call, saving the results in SaveResult

SaveResult[] sr = binding.update(new sObject[]{contact});

// The SaveResult should never be empty

for (int i=0;i<sr.Length;i++)

{

// Determine whether the row update succeeded

if (sr[i].success)

{

// Get the ID of the updated row

System.Diagnostics.Trace.WriteLine(sr[i].id);

}

else

{

// Iterate through the errors

Error[] errors = sr[i].errors;

for (int j=0;j<errors.Length;j++)

{

System.Diagnostics.Trace.WriteLine(errors[j].message);

}

Name sObjects

Type

Description

Array of one or more objects (maximum of 200) to update.

Response

[]

Faults

InvalidSObjectFault

UnexpectedErrorFault

See Also

Sample SOAP Messages - update

SaveResult

The

sObject [] array passed as the

call returns an array of SaveResult objects. Each element in the SaveResult array corresponds to the

sObjects

parameter in the update

call. For example, the object returned in the first index in the SaveResult array matches the object

specified in the first index of the sObject

[] array.

A SaveResult object has the following properties:

Page 119

AppExchange API

Name id

Type

success errors

boolean

Description

ID of an

Indicates whether the update

that you successfully updated. If this field contains a value, then the object was updated successfully. If this field is empty, then the object was not updated and the AppExchange Web service returned error information instead.

call succeeded (True) or not (False) for this object.

If an error occurred during the update call, an array of

objects providing the error code and description.

Page 120

AppExchange API

upsert

Creates new objects and updates existing objects; uses a custom field to determine the presence of existing objects. In most cases, we recommend that you use upsert instead of

UpsertResult[] = sfdc.upsert(String externalIdFieldName, sObject

because upsert is idempotent. Available in version 7.0 and later.

Syntax

[] sObjects);

Usage

The term upsert is a merging of the words insert and update. The upsert call is available for objects that can be updated by the

External ID Attribute on Custom Fields on page 140. For

call and can take custom fields.

The upsert call uses an indexed custom field called an external ID to determine whether to create a new object or update an existing object. (For more information about custom fields designated as external ID fields, see

more information about adding custom fields to objects, see the “Adding Fields” topic in the online help.)

Your client application must have the permission “Modify All Data” to execute this call.

Upsert uses the external ID to determine whether it should create a new object or update an existing one:

• If the external ID is not matched, then a new object is created.

• If the external ID is matched once, then the existing object is updated.

• If the external ID is matched multiple times, then an error is reported.

• When batch updating multiple objects where the external ID is the same for two or more objects in your batch call, those records will be marked as errors in the

UpsertResult . The

objects will be neither created or updated.

Using this call can dramatically reduce how many calls you need to make, particularly when:

• You are integrating your organization’s Salesforce data with ERP (enterprise resource planning) systems such as accounting and manufacturing.

• You are importing data and want to prevent the creation of duplicate objects.

Be advised that matching by external ID is case-insensitive. That is, “ABC123” is matched with

“abc123.” Before performing an operation, review your external IDs for any values that would be matched if case was not considered. If such values exist, you may want to modify them to make them unique.

Sample Code—Java public void upsertAccountSample()

{

// Create an array of SObjects to send to the upsert method

SObject[] upserts = new Account[2];

// This account is assumed to be existing.

// Could be from the results of a retrieve or query call.

Account upsertAccount = new Account();

upsertAccount.setWebsite("http://www.website.com");

// A custom field "External_Id" is used for "External ID" on Upsert

upsertAccount.setExternal_Id__c("1111111111");

upserts[0] = upsertAccount;

// This account is meant to be new

Account upsertAccount2 = new Account();

upsertAccount2 = new Account();

upsertAccount2.setName("My Company, Inc");

Page 121

AppExchange API

upsertAccount2.setExternal_Id__c("2222222222");

upserts[1] = upsertAccount2;

try {

// Invoke the upsert call and save the results.

// Use External_Id custom field for matching records

UpsertResult[] upsertResults = binding.upsert("External_Id__c", upserts);

for (UpsertResult result : upsertResults) {

if (result.isSuccess()) {

System.out.println("\nUpsert succeeded.");

System.out.println((result.isInserted() ? "Insert" : "Update") + " was performed.");

System.out.println("The Account id: " + result.getIds(0).toString());

} else {

System.out.println("The Upsert failed because: " + result.getErrors(0).getMessage());

}

} catch (RemoteException ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

}

getUserInput("\nPress the RETURN key to continue...");

}

Sample Code—C# private void upsertSample()

{

if (!loggedIn) {

if (!login())return;

}

//First, create a contact using the upsert call. The contact must have a

//custom field that is designated as an external id in this case it's called

//ExternalId__c sforce.Contact[] contact = new Contact[1]; contact[0] = new sforce.Contact(); contact[0].LastName = "External_Id"; contact[0].FirstName = "Test"; contact[0].ExternalId__c = "01010101"; sforce.UpsertResult ur = binding.upsert("ExternalId__c", contact)[0]; if (ur.success)

{ //Check out the created flag

Console.WriteLine("Value of created flag is: " + ur.created);

} else

{ //Report an error

Console.WriteLine("Error: \n" + ur.errors[0].message); return;

}

//Now, we can call the upsert again changing a value.

contact[0].FirstName = "Joe"; contact[0].LastName = "Sampson";

Page 122

AppExchange API

Arguments ur = binding.upsert("ExternalId__c", contact)[0]; if (ur.success)

{ //Check out the create flag, should be false now

Console.WriteLine("Value of created flag is: " + ur.created);

} else

{ //Report an error

Console.WriteLine("Error: \n" + ur.errors[0].message); return;

}

Name

ExternalIDFieldName

Type

string

sObjects

information, see External ID Attribute on

Description

Contains the name of the field designated as an external ID field for this object. For more

Custom Fields on page 140.

Array of one or more objects (maximum of

200) to create or update.

Response

UpsertResult

[]

Faults

InvalidSObjectFault

UnexpectedErrorFault

See Also

create on page 61

update on page 117

UpsertResult

The upsert call returns an array of UpsertResult objects. Each element in the UpsertResult array corresponds to the

[] array passed as the sObjects

parameter in the

upsert call. For

example, the object returned in the first index in the UpsertResult array matches the object

specified in the first index of the sObject

[] array.

An UpsertResult object has the following properties:

Page 123

AppExchange API

Name ids

Type

isCreated success errors

boolean boolean

Error

Description

If the call succeeded, the field contains the ID of the record that was either updated or created. If there was an error, the field is null. For more information, see

List of API Calls on page 53.

Indicates whether the record was created (True) or updated (False).

Indicates whether the call succeeded (True) or not

(False) for this object.

If an error occurred during the call, an

Error object

providing the error code and description is returned.

Page 124

AppExchange API

HAPTER

A P I U t i l i t y C a l l s

This topic describes API calls that your client applications can invoke to obtain the system timestamp, user information, and change user passwords. For a complete list of all API calls, see

The following table lists the API utility calls described in this topic:

Task / Call

Description

Retrieves the current system timestamp from the Web service.

Retrieves personal information for the user associated with the current session.

Changes a user’s password to a system-generated value.

Sets the specified user’s password to the specified value.

getServerTimestamp

Retrieves the current system timestamp (GMT) from the Web service.

Syntax dateTime timestamp = sfdc.getServerTimestamp();

Usage

Use

getServerTimestamp

to obtain the current system timestamp from the Web service. You might do this if, for example, you need to use the exact timestamp for timing or data synchronization purposes. When you

getServerTimestamp call was executed.

an object, the Web service uses the system timestamp to update the CreatedDate and LastModifiedDate fields, respectively, in the object.

The getServerTimestamp

call always returns the timestamp in GMT. However, your local system might automatically display the results in your local time based on your time zone settings.

Note

Development tools differ in the way that they handle time data. Some development tools report the local time, while others report only the GMT time. To determine how your development tool handles time values, refer to its documentation.

Sample Code—Java public void getServerTimestampSample() {

// Invoke the getServerTimestamp call and save the results

try {

Calendar serverTime = binding.getServerTimestamp().getTimestamp();

System.out.println("Server time is: " + serverTime.getTime().toString());

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

Page 125

AppExchange API

}

Sample Code—C# private void getServerTimeStamp()

{

// Invoke the getServerTimeStamp call and save the results

GetServerTimestampResult ts = binding.getServerTimestamp();

// Write the server timestamp to the diagnostics window

System.Diagnostics.Trace.WriteLine(ts.timestamp.ToUniversalTime);

}

Arguments

None.

Response

Name

timestamp

Type dateTime

Description

System timestamp of the Web service when the

Fault

See Also

GetUserInfoResult result = sfdc.getUserInfo();

Sample SOAP Messages - getServerTimestamp

getUserInfo

Retrieves personal information for the user associated with the current session.

Syntax

Usage

Use

The getUserInfo call applies only to the user name under which your client application has logged

to obtain personal information about the currently logged in user. This convenience API call retrieves and aggregates common profile information that your client application can use for display purposes, performing currency calculations, and so on.

in. To retrieve additional personal information not found in the

GetUserInfoResult

object, you can

call retrieve

on the User

object and pass in the

userID

returned by this call. To retrieve personal

information about other users, you could call retrieve (if you know their user ID) or

on the

User object.

Page 126

AppExchange API

Sample Code—Java public void getUserInfoSample() {

GetUserInfoResult getUserInfoResult = null;

try {

// Invoke the getUserInfo call

getUserInfoResult = binding.getUserInfo();

// Display the returned user information

System.out.println("User's currency symbol: " + getUserInfoResult.getCurrencySymbol());

System.out.println("User's organization name: " + getUserInfoResult.getOrganizationName());

System.out.println("User's default currency code: " + getUserInfoResult.getUserDefaultCurrencyIsoCode());

System.out.println("User's email: " + getUserInfoResult.getUserEmail());

System.out.println("User's full name: " + getUserInfoResult.getUserFullName());

System.out.println("User's user id: " + getUserInfoResult.getUserId());

System.out.println("User's language: " + getUserInfoResult.getUserLanguage());

System.out.println("User's locale: " + getUserInfoResult.getUserLocale());

System.out.println("User's timezone: " + getUserInfoResult.getUserTimeZone());

System.out.println("User's org is multi currency: " + getUserInfoResult.isOrganizationMultiCurrency());

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

}

Sample Code—C# private void getUserInfo()

{

// Invoke getUserInfo call and save the results in getUserInfoResult

GetUserInfoResult ui = binding.getUserInfo();

// Get some of the user information

String orgName = ui.organizationName;

String userFullName = ui.userFullName;

}

Arguments

None.

Response

GetUserInfoResult

Fault

See Also

Sample SOAP Messages - getUserInfo

Page 127

AppExchange API

GetUserInfoResult

The

Setup | Customize | User Interface. See User

call returns a GetUserInfoResult object, which has the following properties:

Name

accessibilityMode currencySymbol organizationId organizationMultiCurrency

boolean

organizationName userDefaultCurrencyIsoCode

string string

userEmail userFullName userID userLanguage userLocale userTimeZone userUiSkin

string string

string string string string

Type boolean string

Description

Available in API version 7.0 and later. Indicates whether user interface modifications for the visually impaired are on (True) or off (False).

The modifications facilitate the use of screen readers such as JAWS.

Currency symbol to use for displaying currency values. Applicable only when

organizationMultiCurrency

is False.

Organization ID. Allows third-party tools to uniquely identify individual organizations in

Salesforce, which is useful for retrieving billing or organization-wide setup information.

Indicates whether the user’s organization uses multiple currencies (True) or not (False).

Name of the user’s organization or company.

Default currency ISO code. Applicable only when

organizationMultiCurrency

is True.

When the logged in user creates any objects that have a currency ISO code, the Web service uses this currency ISO code if it is not explicitly specified in the

create call.

User’s email address.

User’s full name.

User ID.

User’s language.

User’s locale (language and country).

User’s time zone.

Available in API version 7.0 and later. Returns the value Theme2 if the user is using the newer user interface theme of the online application, labeled “Salesforce.” Returns Theme1 if the user is using the older user interface theme, labeled

“Salesforce Classic.” In the online application, this look and feel setting is configurable at

Interface Themes

Page 128

AppExchange API

resetPassword

Changes a user’s password to a system-generated value.

Syntax string password = sfdc.resetPassword(ID userID);

Usage

Use resetPassword

to request that the AppExchange Web service change the password of a User

SelfServiceUser

, and return the system-generated password string. Use setPassword

instead if you want to set the password to a specific value.

Your client application must be logged in with sufficient access rights to change the password for

the specified user. For more information, see Factors that Affect Data Access on page 32.

SelfServiceUser whose password you

Sample Code—Java public void resetPasswordSample() {

// Specify the user ID of the password to reset

String idToReset = "005x0000000fFLnAAM";

// Invoke the resetPasswordResult call

try {

ResetPasswordResult resetPasswordResult = binding.resetPassword(idToReset);

// Display the new server-generated password

System.out.println(resetPasswordResult.getPassword());

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

}

Sample Code—C# private void resetPassword()

{

// Invoke resetPassword call and save results in ResetPasswordResult

ResetPasswordResult rpr = binding.resetPassword("userID");

// Get the generated password

System.Diagnostics.Trace.WriteLine(rpr.password);

}

Arguments

Name

userID

Type Description

ID of the User or

want to reset. For information on IDs, see ID Fields on page 136.

Page 129

AppExchange API

Response

Name

password

string

Type Description

New password generated by the AppExchange Web service.

Fault

InvalidIdFault

See Also

setPassword

setPassword to change the password of a

Sample SOAP Messages - resetPassword

setPassword

Sets the specified user’s password to the specified value.

Syntax

SetPasswordResult setPasswordResult = sfdc.setPassword(ID userID string password);

Usage

Use

User or

SelfServiceUser

to a value that you specify. For example, a client application might prompt a user to specify a different password,

and then invoke setPassword

to change the user’s login password. Use resetPassword

instead if you want to reset the password with an AppExchange Web service-generated value.

Your client application must be logged in with sufficient access rights to change the password for

the specified user. For more information, see Factors that Affect Data Access on page 32.

Sample Code—Java

(new AXIS 1.3 code) public void setPasswordSample() {

// Specify the userID and new password

String idToReset = "005x0000000fFLnAAM";

String newPassword = "password";

try {

// Invoke the setPassword call

SetPasswordResult setPasswordResult = binding.setPassword(idToReset, newPassword);

// If the call fails, an exception is raised; otherwise, the return is empty.

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

}

Page 130

AppExchange API

}

Sample Code—C# private void setPassword()

{

// Invoke setPassword call; returns nothing if successful

binding.setPassword("userid", "newpassword");

}

Arguments

Name

userID

Type

password

string

Response

None.

Fault

InvalidIdFault

resetPassword on page 129

See Also

SelfServiceUser whose password you

Sample SOAP Messages - setPassword

Description

ID of the User or

want to reset. For information on IDs, see ID Fields on page 136.

New password to use for the specified user.

Page 131

AppExchange API

HAPTER

A P I O b j e c t s

This topic describes the objects defined in the API. It contains the following sections:

•

Key Concepts of API Objects

•

List of Standard Objects

K

EY

C

ONCEPTS OF

API O

BJECTS

This section includes the following topics:

•

•

•

•

•

•

•

Relationships Among Objects

•

Custom Objects and Custom Fields

•

Common Object Fields

About API Objects

In the API, objects are data entities that represent your organization’s information. For example, the

an object (such as a specific account that is represented by an Account

object represents accounts—companies and organizations involved with your business, such as customers, partners, and competitors. To describe a particular occurrence of

object), this document uses the term object instance. An object instance is analogous to a row in a database table.

Access to Objects

While this topic describes all of the objects available in the API, your applications work with only the objects that you are authorized to access. Programmatic access to objects is determined by the objects that are defined in your enterprise WSDL file, your organization configuration, your security access (which is configured by your organization’s system administrator in your personal

profile), and your data sharing model. For more information, see Factors that Affect Data Access on page 32.

Page 132

AppExchange API

Field Types

In addition to the primitive datatypes explained in Primitive Data Types on page 24, the API

defines the following datatypes for object fields:

Field Type anyType calculated combobox currency email

ID multipicklist percent phone picklist reference textarea url

What the Field Contains

Polymorphic data type that returns string, date, number, or Boolean data depending on the kind of field involved. See AnyType Field Type on page 134.

Fields that are defined by a formula. See Calculated Field Type on page 134.

A combobox, which includes a set of enumerated values and allows the user

to specify a value not in the list. See Combobox Field Type on page 134.

Currency values. See Currency Field Type on page 134.

Email addresses. See Email Field Type on page 134.

Primary key field for the object. See ID Field Type on page 134.

Note that most Web services tools, including .NET and Axis 1.2 and greater, map the ID simple type defined in the API WSDL (Enterprise or Partner) to a string. However, other tools, including Axis v1.1, generate a specific ID class to represent the ID simple type. Please consult your web services toolkit documentation for more information.

Multi-select picklists, which include a set of enumerated values from which multiple values can be selected. See

Multi-Select Picklist Field Type on page 135.

Percentage values. See

Percent Field Type on page 135.

Phone numbers. Values can include alphabetic characters. Client applications are responsible for phone number formatting. See

Phone Field

Type on page 135.

Picklists, which include a set of enumerated values from which one value

can be selected. See Picklist Field Type on page 135.

Cross-references to a different object. Analogous to a foreign key field in

SQL. See

Reference Field Type on page 135.

String that is displayed as a multi-line text field. See

Textarea Field Type on page 136.

URL values. Client applications should commonly display these as hyperlinks. See

URL Field Type on page 136.

These field types extend the primitive data types, which are described in Primitive Data Types on page 24. While many of these field types follow common data typing conventions that are made

explicit in their metadata, certain field types have unique characteristics that you need to understand before using them in your client application.

These field types apply to both standard and custom fields. They are enumerated in the type field of the

type, which is described in the fields property of the

restrictions. These restrictions are enforced when you create

Page 133

AppExchange API

Note

Some numeric fields have precision and scale limits. In addition, certain text fields have length

update objects. However, the

API may return data that does not meet these restrictions.

AnyType Field Type

The anyType field type is dynamic and returns string, date, number, or boolean data depending on the kind of field involved. For example, the element in the SOAP message has an xsi:type="xsd:string"

attribute if the field is of type string. Most SOAP toolkits will automatically deserialize this element into the correct native type.

Calculated Field Type

Calculated fields are read-only fields in the API. These are fields defined by a formula, which is an algorithm that derives its value from other fields, expressions, or values. You can filter on these fields in SOQL, but you should not replicate these fields. The length of text calculated fields is 1300 characters or less—anything longer will be truncated.

Calculated fields are called formula fields in the Salesforce user interface. For more information, search the online help for “formula fields.”

Combobox Field Type

A combobox is a picklist that also allows users to type a value that is not already specified in the list. A combobox is defined as a string value.

Currency Field Type

Currency fields contain currency values, such as the ExpectedRevenue field in a Campaign , and

are defined as type

double .

For organizations that have the multi-currency option enabled, the CurrencyIsoCode field is defined for any object that can have currency fields. The CurrencyIsoCode field and currency fields are linked in a special way. On any specific record, the CurrencyIsoCode field defines the currency of that record, and thus, the values of all currency fields on that record will be expressed in that currency.

For most cases, clients do not need to consider the linking of the CurrencyIsoCode field and the currency fields on an object. However, clients may need to consider the following:

• The CurrencyIsoCode field exists only for those organizations that have enabled multicurrency support.

• When displaying the currency values in a user interface, it is preferred to prepend each currency value with its CurrencyIsoCode value and a space separator.

• The CurrencyIsoCode field is a restricted picklist field. The set of allowable values, defined in the

CurrencyType

object, can vary from organization to organization. Attempting to set it to a value that is not defined for an organization causes the operation to be rejected.

• If you update the CurrencyIsoCode field on an object, it implicitly converts all currency values on that object to the new currency code, using the conversion rates that are defined for that organization in the Salesforce user interface. If you specify currency values in that

same update call, the new currency values you specify are interpreted in the new

CurrencyIsoCode

field value, without conversion.

To perform currency conversions, client applications can look up the CurrencyIsoCode in the

CurrencyType object.

Email Field Type

Email fields contain email addresses. Client applications are responsible for specifying valid and properly formatted email addresses in

create and

See ID Fields on page 136.

calls.

ID Field Type

Page 134

AppExchange API

Multi-Select Picklist Field Type

Multi-select picklist fields contain a list of one or more items from which a user can choose multiple items. One of the items can be configured as the default item. Selections are maintained as a string containing a series of attributes delimited by semi-colons. For example, a query might return the values of a multi-value picklist as “first value; second value; third value”.) For information on querying multi-select picklists, see

Querying Multi-Select Picklists on page 43.

Percent Field Type

Percent fields contain percent values. Percent fields are defined as type double .

Phone Field Type

Phone fields contain phone numbers, which can include alphabetic characters. Client applications are responsible for phone number formatting.

Picklist Field Type

Picklist fields contain a list of one or more items from which a user chooses a single item. One of the items can be configured as the default item.

In the

object associated with the

for advisory (unrestricted) picklist fields on create

, the restrictedPicklist field defines whether the field is a restricted picklist or not. The API does not enforce the list of values

update . When inserting an unrestricted

picklist field that does not have a PickListEntry , the system creates an “inactive” picklist value.

This value can be promoted to an “active” picklist value by adding the picklist value in the

Salesforce user interface.

When creating new, inactive picklists, the API checks to see if there is a match. This check is case-insensitive.

In the Field

object associated with the DescribeSObjectResult

, the PicklistValues field contains an array of items (PickListEntry objects). Each

PickListEntry

defines the item’s label, value, and whether it is the default item in the picklist (a picklist has no more than one default value).

Enumerated fields support localization of the labels to the language of the user. For example, for

the ForecastCategory field on an Opportunity

, the value “Omitted” may be translated to various languages. The enumerated field values are fixed and do not change with a user’s language.

However, each value may have a specified “label” field that provides the localized label for that

value. You must always use the value when inserting or updating a field. The query call always

returns the value, not the label. The corresponding label for a value in the DescribeSObjectResult

should be used when displaying the value to the user in any user interface.

The API supports the retrieval of the certain picklists in the following objects:

, and

TaskStatus . Each object represents a value in the respective picklist. These picklist entries

always specify some other piece of information, such as whether the status is converted, and so

on. Your client application can invoke the query

call on any of these objects (such as

CaseStatus )

to retrieve the set of values in the picklist, and then use that information while processing other

objects (such as Case s) to determine more information about those objects (such as a given

case). These objects are read-only via the API. To modify items in picklists, you must use the

Salesforce user interface.

Reference Field Type

A reference field contains an Id value that points to a unique record (usually the parent record) on another object. This is analogous to the concept of a foreign key in relational databases. The name of a reference field ends, by convention, with the letters Id (such as CaseId or

OpportunityId

). For example, in the OpportunityCompetitor

object, the OpportunityId field is a reference field that points to the

identifies an Opportunity

object. It contains an Id value that uniquely

record.

In some cases, an object can refer to another object of its same type. For example, an

can have a parent link that points to another

Page 135

AppExchange API

The Event and

Task

objects both have WhoId and WhatId cross-reference ID fields. Each of these cross-reference fields can point to one of several other objects. The WhoId field can point to a

, and the WhatId field can point to an Account

or Lead

, Opportunity ,

Campaign , or

In addition, if the WhoId field refers to a Lead

, then the WhatId field must be empty.

You can describe and query each cross-referenced object. When you query a cross-reference ID field, it returns an object ID of the appropriate type. You can then query that ID to get additional information about the object, using the ID in the id field for that query.

The cross-reference ID field value is either:

• a valid record in your organization, or

• an empty value, which indicates an empty reference

The cross-reference ID field value, if non-null, is guaranteed to be an object in your organization. However, it is not guaranteed that you can query that object. Users with the “View

All Data” permission can always query that object. Other users may be restricted from viewing or editing the referenced object.

When specifying a value for a cross-reference ID field in a create or

update call, the value must

be a valid value of type ID, and the user must have appropriate access to that object. The exact requirements vary from field to field.

Textarea Field Type

Textarea fields contain text that can be longer than 4000 bytes. Unlike string fields, textarea fields cannot be specified in the WHERE clause of a

queryString

of a

call. To filter records on this field, you must do so while processing records in the

restriction, its filterable field in the Field type (described in the fields property of the

. For fields with this

DescribeSObjectResult ) is False.

URL Field Type

URL fields contain URLs. Client applications are responsible for specifying valid and properly

formatted URLs in create

and update calls.

ID Fields

With rare exceptions, all objects in the API have a field of type id that is named “Id” and contains a unique identifier for each record in the object. It is analogous a primary key in relational databases. When you

create a new record, the Web service generates an ID value for

the record, ensuring that it is properly formatted and unique within your organization’s data. You cannot use the

retrieve via the describeSObjects

call on “Id” fields. Because the ID value stays constant over the lifetime of the record, you can refer to the record by its ID in subsequent API calls. Also, the ID value contains a three-character code that identifies the object type, which client applications can

call.

In addition, certain objects, including custom objects, have one or more fields of type reference that contain the ID value for a related record. These fields have names that end in the suffix “-

Id”, for example, OwnerId in the Account object. OwnerId contains the ID of the user who owns that account. Unlike the field named “Id,” reference fields are analogous to foreign keys and can

be changed via the update

call. For more information, see Reference Field Type on page 135.

Some API calls, such as retrieve

and delete , accept an array of IDs as parameters—each array

element uniquely identifies the row to retrieve or delete. Similarly, the

array of sObject s—each sObject contains an Id field that uniquely identifies the sObject

call accepts an

ID values can be 15 or 18 characters long. The API and the Salesforce user interface accept both types of ID values, although the API always returns an 18-character ID. An 18-character ID adds additional encoding information about the case of the first 15 digits. At some point in the future, all IDs will be 18-character IDs. In the interim, if you need to store IDs, we recommend that you store 15-character IDs. However, if you must store IDs in all lowercase (this is not recommended), an 18-character ID will ensure uniqueness.

Page 136

AppExchange API

To convert an 18-character ID to a 15-character ID, truncate the final three digits. If you need information on the algorithm used to convert 15-character IDs to 18-character IDs, please contact Customer Support.

Note

Most Web services tools, including .NET and Axis 1.2 and greater, map the ID simple type defined in the API WSDL (Enterprise or Partner) to a string. However, other tools, including Axis v1.1, generate a specific ID class to represent the ID simple type. Please consult your web services toolkit documentation for more information.

System Fields

The following fields are read-only fields commonly found in objects. The Web service updates these fields automatically.

However, if you are migrating data into Salesforce from an external system, it is possible to explicitly set the CreatedById, CreatedDate, LastModifiedById, and LastModifiedDate fields.

For more information, contact Customer Support.

Field

Type

Description

Globally unique string that identifies a particular record. For

ID of the

who created this object. Read-only.

CreatedById

CreatedDate

Date and time when this object was created. Read-only.

LastModifiedById

ID of the

who last updated this object. Read-only.

LastModifiedDate

Date and time when this object was last modified by a user.

Read-only.

SystemModstamp

Date and time when this record was last modified by a user or by a workflow process (such as a trigger). Read-only.

Required Fields

Required fields must have a non-null value. This rule affects the

create call, Salesforce automatically populates the data

and update calls:

• When a client application invokes the

for certain required fields (such as system fields and the object ID fields). Similarly, if a required field has a default value (its defaultedOnCreate attribute is set to True, as

described in Field on page 85, then Salesforce implicitly assigns a value for this field when

the object is created, even if a value for this field is not explicitly passed in on the create

call.

For all other required fields, such as Id fields that are analogous to foreign keys in SQL (see

Reference Field Type on page 135), a client application must explicitly assign a value when

the object is created (it cannot be null).

• When a client application invokes the

update call, a required field cannot be set to null.

Many required fields cannot be changed in an update call.

For more information about the special handling of required fields for particular objects, see the documentation for such objects later in this topic.

Page 137

AppExchange API

Relationships Among Objects

Certain objects, including custom objects, have the following kinds of relationships with other objects:

• Master-Detail (1:1)—When a record in the master object is deleted, the related records in the detail object are also deleted. The security settings for the master record also control the detail record. The lookup field is the field linking the two objects. You cannot create a master-detail relationship to users or leads.

• Lookup (1:n)—This type of relationship has no effect on deletion or security, and the lookup field is not required. When you define a lookup relationship for a custom object, data from the custom object can appear as a custom related list on page layouts for the other object.

These relationships are already defined for standard objects. For custom objects, configure these relationships in the Salesforce user interface. For detailed information, see the Salesforce user interface online help.

Custom Objects and Custom Fields

In the Salesforce user interface, you can extend your organization’s Salesforce data by defining custom objects. For certain custom objects, you can also use the Salesforce user interface to define custom fields on those objects. Although client applications cannot define new custom objects or new custom fields on custom objects, they can insert new records for existing custom objects.

Custom Objects

Custom objects are custom Salesforce tables that allow you to store information unique to your organization. For custom objects, the custom flag—a Boolean field in the

DescribeSObjectResult —is True. Client applications cannot

create custom objects via the API.

However, client applications with sufficient permissions can invoke API calls on custom objects.

Custom Fields

Salesforce administrators can define custom fields for standard or custom objects in their organization using the Saleforce user interface. During creation, the custom flag—a Boolean field in the

Relationships Among Objects on page 138. For example, cascading deletes are supported in

object—is set to True. Client applications cannot define custom fields via the API.

Usually, client applications do not need to know whether a field is a standard field or a custom field.

The following objects support custom fields:

•

•

•

•

•

•

•

•

•

•

•

•

•

•

Note that all numeric custom fields are handled as type

double .

Page 138

AppExchange API

Master-Detail

Lookup

Naming Conventions for Custom Objects and Custom Fields

Custom objects and custom fields have an associated name field that is defined by your

Salesforce administrator. Custom objects must have unique names within your organization, and custom fields must have unique names within the same object.

In the API, the names of custom objects and custom fields are identified by a suffix of two underscores immediately followed by a lowercase “c” character. For example, a custom object labeled “Issue” in the Salesforce user interface is seen as Issue__c in that organization’s WSDL.

Similarly, a custom field labeled “Hire Date” in the Salesforce user interface is seen as

Hire_Date__c

in that organization’s WSDL.

In order for a custom object record to appear in the Salesforce user interface, its name field must be populated. If you use the API to create a custom object record that does not have a name, then the ID of that record will be used as its name.

Relationships Among Custom Objects

Custom objects relate to other objects and behave just like standard objects, as described in

custom objects in a Master-Detail relationship.

The following objects can parent custom objects. An object with an asterisk next to it cannot participate in a Master-Detail relationship.

•

•

•

•

•

•

(*)

•

•

Product

(*)

•

or integration, or when using the upsert

•

User (*)

The following table summarizes whether a standard object can be:

• The master in a master-detail relationship with a custom object. Master-detail relationships involve cascading deletes and sharing rules that are controlled by the parent.

• The lookup in a lookup relationship on a custom object. In other words, whether a custom object can have a lookup to the standard object.

• Extended with custom fields.

Standard Object

Custom Fields

Page 139

AppExchange API

Standard Object

Master-Detail

Lookup

Custom Fields

External ID Attribute on Custom Fields

In the Salesforce user interface, you can identify one custom field on an object as being an external ID field. The field type must be text, number, or email field. An external ID contains record IDs from a system outside of Salesforce. You can match against this field during importing

call. Also, external ID fields are indexed, so selective filters on them should run quickly.

Common Object Fields

With few exceptions, the following fields are found on all objects:

OwnerID Fields

Objects have an ownerID field that is an reference to the user who owns that object. Ownership is an important concept that affects the security model and has other implications throughout the system. Any user can query the owner field for any record they can access. However, setting the ownerID field has the following limitations:

• For most users and most objects, the ownerID field cannot be set directly upon insert. It is implicitly set to the current user when inserting an object.

•

When creating or updating a Case

or Lead

, a client application (that is logged in with

sufficient permissions to transfer a record) can set the ownerID field to any valid User

in the organization or to any valid queue of the appropriate type in the organization.

• Updating the ownerID field via the API changes only the owner of that record. The change of ownership does not cascade to associated records as it does when you transfer record ownership in the application.

• Updating the ownerID field on an account deletes the existing sharing information and reapplies the default sharing model and autoshare rules.

RecordTypeId Fields.

Record types are used to offer different business processes and subsets of picklist values to different

s based on their Profile settings.

Record types are configured in the Salesforce user interface. The

object is read-only in the API. A client application can retrieve the list of valid record type IDs for a given object by calling

on the RecordType object.

The RecordTypeId field can contain the ID of the RecordType that is associated with a standard

or custom object. Client applications can set this field in create

or update calls. If specified in a

update call, the record type ID must refer to a valid record type for that object.

Note

The RecordTypeId field will appear in your WSDL file only if at least one record type is configured for your organization in the Salesforce user interface.

For more information about ID fields, see ID Fields on page 136.

CurrencyIsoCode.

For organizations that have multi-currency enabled, the CurrencyIsoCode field contains the string representation of the currency ISO code associated with currency values in the object. Note that the

User object also has a DefaultCurrencyIsoCode field, which is the

default currency for that user. For example, a user in France could have a

DefaultCurrencyIsoCode

set to Euros, and that would be their default currency in the

application. However, the User object could have currency custom fields stored in a different

currency.

Page 140

AppExchange API

L

IST OF

S

TANDARD

O

BJECTS

The API provides access to the following standard objects:

Object Description

The role that a given Contact

An individual account, which is an organization involved with your business (such as customers, competitors, and partners).

plays on an

A partner relationship between two specific Account

objects.

A sharing entry on an

who is a member of an

AccountTerritoryAssignmentRule

team.

A rule that assigns accounts to territories.

AccountTerritoryAssignmentRuleItem

A field-specific criteria row for an

AccountTerritoryAssignmentRule .

Approval

An approval request for a Contract

Asset

An asset (such as product previously sold and installed) owned by an

An assignment rule associated with a Case or

Lead .

A file that a

has uploaded and attached to a parent object.

A business process.

A marketing campaign, such as a direct mail promotion, webinar, or trade show.

The association between a

Campaign and either a

A case, which is a customer issue such as a customer’s feedback, problem, or question.

A comment that provides additional information about

the associated Case .

Historical information about changes that have been made to the associated

A sharing entry on a Case .

The association between a particular Case and a

particular

The status of a

A tree of Solution categories.

, such as New, On hold, In Process, and so on.

A logical grouping of

Solution records.

Page 141

AppExchange API

Object

OpportunityCompetitor

OpportunityContactRole

Description

A contact, which is an individual associated with your

Account s.

A contract (a business agreement) associated with an

Account .

The role that a given Contact

plays on a Contract .

The status of a

Contract , such as Draft, In Approval,

Activated, Terminated, or Expired.

The currencies used by an organization for which the multi-currency feature is enabled.

A logical segment of your organization’s data.

A file that a user has uploaded. Unlike Attachment

objects, Documents are not attached to a parent object.

An email message

Historical information about field value changes for an object. Available in API version 7.0 and later.

A calendar appointment event.

A person ( User ,

to attend an Event , or a scheduled resource (such as a

, or Lead

) who has been invited

conference room) associated with the event.

Fiscal year settings.

A repository for a Document

MailMergeTemplate

, email template, or report. Only one type of item can be contained in a particular Folder.

A set of

A lead, which is a prospect or potential Opportunity .

that is a member of a public group.

A sharing entry on a Lead

The status of a

A note, which is text associated with an Attachment ,

, such as Open, Qualified, or

Converted.

Customizable forecast data for an opportunity line item.

A mail merge template (a Microsoft Word document) used for performing mail merges for your organization.

Contact ,

Contract ,

A competitor on an Opportunity

, or custom object.

An opportunity, which is a sale or pending deal.

The association between an Opportunity and a

, with a specified Role name applied to the contact.

Page 142

AppExchange API

Object

OpportunityHistory

OpportunityLineItemSchedule

OpportunityTeamMember

QuantityForecastHistory

RevenueForecast

RevenueForecastHistory

Description

The history of an

An opportunity line item, which is a member of the list of

s associated with an

, along with other information about those products on that opportunity.

Information about the quantity, revenue distribution, and delivery dates for a particular

Customizable forecast data for an opportunity.

A partner relationship between an

Account and an

A sharing entry on an

Opportunity in the sales pipeline, such

The stage of an

as New Lead, Negotiating, Pending, Closed, and so on.

An individual

on the sales team of a particular

The association between two particular Accounts or between a particular

Opportunity and an

A role for an account

Partner

, such as consultant, supplier, and so on.

A fiscal period.

A price book that contains the list of

Product s that your

organization sells.

A price book that contains the list of

Product2 s that

your organization sells.

A product entry (an association between a

Product2 ) in a pricebook.

and

A product that your organization sells. A product is

member of the list of items in a Pricebook .

A product that your organization sells. A product is

member of the list of items in a Pricebook2

A profile, which defines a set of permissions to perform different operations, such as querying, adding, updating, or deleting information.

A quantity-based customizable forecast.

Historical information about a quantity-based customizable forecast.

A record type.

A revenue-based customizable forecast.

Historical information about a revenue-based customizable forecast.

Page 143

AppExchange API

Object

Account

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Usage

Use

convertLead call. For more information, see convertLead

objects to query and manage accounts in your organization. Client applications can

s associated with an account via the API.

Client applications can also create or update Account objects by converting a

Lead via the

See Also

Represents an individual account, which is an organization involved with your business (such as customers, competitors, and partners).

AccountShare on page 148

AccountTeamMember on page 150

Page 145

AppExchange API

AccountContactRole

Represents the role that a given

plays on an

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountId

ContactId

IsPrimary

Role

Field Type

Description

ID of the

. For information on IDs, see ID

ID of the Contact associated with this account. For

Specifies whether this Contact

plays the primary role on this

Name of the role played by the Contact

(True) or not (False). Note that each account has only one primary contact role.

on this

Use the AccountContactRole

, such as Decision Maker, Approver,

Buyer, and so on. Must be unique—there cannot be multiple records in which the AccountId,

ContactId

, and Role values are identical.

Different contacts can play the same role on the same account. A contact can play different roles on the same account.

Usage

object to define the role that a given Contact plays on a given

Account within the context of a specific

See Also

Account on page 145

Contact on page 174

A partner relationship between two specific Account objects.

Page 146

AppExchange API

AccountPartner

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountFromId

AccountToId

IsPrimary

Role

Field Type

ID of the main Account in the partner relationship.

Description

For information on IDs, see

Account in the partner relationship.

ID of the partner

Indicates whether the

AccountPartner

is the main account’s primary partner (True) or not (False).

The UserRole

that the partner Account

has on the

main Account . For example, “Consultant” or

“Distributor.”

Usage

AccountPartner

is a read-only object.

See Also

Partner on page 227

OpportunityPartner on page 221

Represents a sharing entry on an Account .

Page 147

AppExchange API

AccountShare

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountAccessLevel

AccountId

CaseAccessLevel

OpportunityAccessLevel

Field

Type

Description

picklist reference

ID of the

Account associated with this sharing entry. This field cannot be

updated. For information on IDs, see ID Fields on page 136.

Level of access that the User

or Group has to cases associated with the

Account. One of the following values:

• Private -

can view or edit the Case .

cannot access the Case .

• Read Only -

can only view the

• Read/Write -

This field must be set to an access level that is at least equal to the organization’s default caseAccessLevel.

This field cannot be updated via the API if the AccountAccessLevel field is set to “All.”

Using the API, you cannot update this field for the associated Account owner. You must update the Account owner’s caseAccessLevel via the

Salesforce user interface.

can view or edit the Account

Group has to the

Account . One of the

following values:

• Owner -

cannot access the

• Read Only -

can only view the

• Read/Write -

•

All - User

Group can view, edit,

, and share the Account

with other

. This value is not valid for

calls.

This field must be set to an access level that is at least equal to the organization’s default

access level. In addition, either this field, the OpportunityAccessLevel field, or the CaseAccessLevel field must be set higher than the organization’s default access level.

Group has to opportunities associated

with the

Account . One of the following values:

• Private -

cannot access the associated opportunities.

• Read Only -

or Group

can only view the associated opportunities.

• Read/Write -

Using the API, you cannot update this field for the associated Account

can view or edit the associated opportunities.

This field must be set to an access level that is at least equal to the organization’s default opportunityAccessLevel.

This field cannot be updated via the API if the AccountAccessLevel field is set to “All.”

owner. You must update the

Account owner’s opportunityAccessLevel via

the Salesforce user interface.

Page 148

AppExchange API

Field

RowCause

UserOrGroupId

Field

Type

Description

Manual Sharing - The User or

Reason that this sharing entry exists. Read-only. Values may include:

•

has access because a User

with

“All” access manually shared the

with them.

• Owner - The

is the owner of the Account or is in a Role above the

Account owner in the role hierarchy.

•

Sales Team—The User

Group has team access (is an

AccountTeamMember

•

Sharing Rule—The User or

has access via an

sharing rule.

that has been given access to the

Accounts owned by other users. For more information, see Sharing on page 21.

. This field cannot be updated.

Usage

The AccountShare object allows you to determine which users and groups can view and/or edit

If you attempt to insert an AccountShare that matches an existing AccountShare record, the

OpportunityShare on page 222

call updates any modified fields and returns the existing record.

See Also

Account on page 145

CaseShare on page 169

LeadShare on page 200

Represents a User who is a member of an

Page 149

AppExchange API

AccountTeamMember

team.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountId

TeamMemberRole

UserId

Field

Type

Description

ID of the Account to which this user is a team

member. Must be a valid Account ID. Required.

For information on IDs, see

Role associated with this team member. One of the valid team member roles defined for your organization. Required.

ID of the User who is a member of this account

team. Must be a valid User ID. Required.

Usage

Use the AccountTeamMember object to manage members of a particular

rule are assigned. For information on IDs, see ID

and to specify roles for those users on that account. This object is available only for Enterprise and Unlimited

Edition users who have enabled the account team preference.

Page 150

AppExchange API

AccountTerritoryAssignmentRule

An account assignment rule that assigns accounts to territories based on account fields. Only available if territory management has been enabled for your organization. For more information, see the “What is Territory Management?” topic in the online help.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

BooleanFilter

IsActive

IsInherited

Name

TerritoryId

Field Type

Description

Advanced filter conditions that were specified for the rule in the online application. For example, “(1 AND

2) OR 3."

Indicates whether the rule is active (True) or inactive

(False). Active rules run automatically when new accounts are created and existing accounts are edited. The exception is when the

IsExcludedFromRealign

field on Account is “True,” which prevents account assignment rules from evaluating that account.

Indicates whether the rule is an inherited rule (True) or a local rule (False). An inherited rule also acts upon territories below it in the territory hierarchy. A local rule is created at the immediate territory and only impacts the immediate territory.

A name for the rule that can have up to 80 characters.

ID of the territory where accounts that satisfy this

UserTerritory on page 267

Usage

A territory will not have any accounts (with the exception of manually assigned accounts) unless at least one account assignment rule is active for the territory.

Territory on page 260

AccountTerritoryAssignmentRule . Only available if territory

Page 151

AppExchange API

AccountTerritoryAssignmentRuleItem

A row of selection criteria for an

management has been enabled for your organization. For more information, see the “What is

Territory Management?” topic in the online help.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Operation

RuleID

SortOrder

Value

Field Type

picklist picklist reference

int string

Description

The standard or custom account field to use as a criteria.

The criteria to apply, such as “equals” or “starts with”.

ID of the associated

AccountTerritoryAssignmentRule .

The order in which this row is evaluated compared to

other AccountTerritoryAssignmentRuleItem objects

for the given AccountTerritoryAssignmentRule

The field value(s) to evaluate, such as “94105” if the

Field

is “Billing Zip/Postal Code.”

Usage

• Both standard and custom account fields can be used as criteria for account assignment rules.

• A territory will not have any accounts (with the exception of manually assigned accounts) unless at least one account assignment rule is active for the territory.

Territory on page 260

UserTerritory on page 267

Represents an approval request for a Contract .

Page 152

AppExchange API

Approval

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

ApproveComment

OwnerId

ParentId

RequestComment

Status

Field

Type

Description

Text entered by the user when they approved or rejected this approval request. Required. Can have up to 4,000 characters.

ID of the User being asked to approve or reject the

approval request. Must be a valid User ID.

Required. For information on IDs, see ID Fields on page 136.

ID of the Contract associated with this approval

request. Must be a valid contract ID. Required.

Text entered by the

who created the approval request. Optional. This field cannot be updated after the Approval has been created. Can have up to 4,000 characters.

request is created ( create

Status of this approval request. One of the following picklist values:

•

Pending

—Specified only when the Approval

call)

•

Approved

—Specified only when the Approval request is approved (

call)

•

Rejected

—Specified when the Approval request is rejected (

( create call) and immediately rejected for

call) or when it is created

archival/historical purposes.

Usage

The Approval object allows client applications to programmatically handle approval requests for a

Contract . Initially, to request a Contract approval, a client application might create a new

Approval request object, specifying the ContractId, OwnerId (user approving or rejecting the request), Status (Pending), and (optionally) RequestComment fields. Note that when a client

application creates the first approval request, if the value of the Contract status field is Draft,

then the status is automatically changed to InApproval (see

ContractStatus on page 178 for

more information).

A client application might subsequently update an existing Approval request, specifying the

Status

(Approved or Rejected) and an ApproveComment (required); the RequestComment field cannot be updated. Updating an Approval record (either to approve or reject) requires the client application to be logged in with “Approve Contract” permission. To update an Approval request,

Page 153

AppExchange API its Status must be Pending—a client application cannot update an Approval that has already

been Approved or Rejected. To re-submit an Approval request for a given Contract

, a client application must create a new, separate Approval object and repeat the approval process.

Once a Contract has been approved (not rejected), the AppExchange Web service automatically updates the Contract’s lastApprovedDate field. The AppExchange Web service does not update its status field (which remains InApproval). To activate an approved Contract, it must be activated explicitly. Client applications can activate a Contract by setting the value in its Status field to Activated, or users can activate a contract using the Salesforce user interface.

Contract can have multiple approval requests in various states (Pending, Approved, and

Rejected). In addition, one User can have multiple approval requests associated with the same

Contract .

Client applications cannot explicitly delete

Approval objects. Approval objects are deleted

automatically if the parent Contract is deleted.

Page 154

AppExchange API

Asset

Represents an asset such, as product previously sold and installed, owned by an Account

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Type

Description

AccountId

ContactId

Description

InstallDate

IsCompetitorProduct

Name

ID of the Account associated with this Asset. Must be a

valid Account ID. Required if ContactId is not

specified. For information on IDs, see ID Fields on page 136.

Contact associated with this asset. Must be a

ID of the

valid Contact ID that has an Account parent (but does not need to match the asset’s AccountId). Required if

AccountId

is not specified.

Description of this asset.

Date on which this asset was installed.

Indicates whether this Asset represents a product sold by a competitor (True) or not (False).

Name of the asset. Required.

Price

Product2Id

PurchaseDate

Quantity

SerialNumber

Status

UsageEndDate

Price paid for this asset.

ID of the Product2

associated with this asset. Must be a valid Product2 ID. Optional.

Date on which this asset was purchased.

Quantity purchased or installed.

Serial number for this asset.

Customizable picklist of values. The default picklist includes the following values:

• Purchased

• Shipped

• Installed

• Registered

• Obsolete

Date when usage for this asset ends / expires.

Usage

Page 155

AppExchange API

Use the

Asset

object to track assets previously sold into customer accounts. With asset tracking, a client application can quickly determine which products were previously sold and/or are currently installed at a specific account.

For example, your organization might want to renewal and up-sell opportunities on products sold in the past. Similarly, your organization might want to track competitive products that exist in a customer environment that could potentially be replaced or swapped out.

Asset tracking is also useful for product support, providing detailed information to assist with product-specific support issues. For example, the PurchaseDate or SerialNumber could indicate whether a given product has certain maintenance requirements, including product recalls.

Similarly, the UsageEndDate might indicate when the asset was removed from service or when a license or warranty expires.

If an application creates a new Asset, it must minimally specify its Name and either an

accountId

, contactId, or both.

Page 156

AppExchange API

AssignmentRule

Represents an assignment rule associated with a

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Active

Name

RuleType

Field

Type

Before creating or updating a new Case

Description

Indicates whether this assignment rule is active

(True) or not (False).

Name of this assignment rule.

Type of assignment rule—caseAssignment or leadAssignment

Usage

or Lead

, a client application can query (by name) the

AssignmentRule to obtain the ID of the assignment rule to use, and then assigned that Id to the

assignmentRuleId

field of the

AssignmentRuleHeader . For more information, see

AssignmentRuleHeader on page 287.

Note that the AssignmentRule

object is a read-only object. Assignment rules are created, configured, and deleted in the Salesforce user interface.

Page 157

AppExchange API

Attachment

Represents a file that a

User has uploaded and attached to a parent object.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Body

BodyLength

IsPrivate

Name

ParentId

Field Type Description

base64Binary

Encoded file data.

Size of the file (in bytes).

Indicates whether the Attachment is viewable only by the owner and administrators. If the private field is set to True for an Attachment, the Attachment can be viewed only by the Attachment owner and administrators. During a

call, it is possible to mark an Attachment as “private” even if you are not the Attachment owner. This can result in a situation in which you can no longer access the

Attachment that you just inserted or updated.

Name of the attached file.

ID of the parent object of the Attachment. The following objects are supported as parents of Attachments:

•

•

•

•

•

•

•

•

All of the Attachment fields are accessible in the describeSObjects

and query

calls. Using the

call, you can insert the Name, ParentId, Body, Private, and OwnerId fields. For modifying

Attachments, the

You can access all of the Attachment fields in a query call. However, you cannot receive the Body field for multiple Attachments in a single query call. If your query returns the Body field, your

call gives you access to change the Name, Body, Private, and OwnerId fields.

client application must ensure that only one row with one Attachment is returned; otherwise, an error occurs. A more effective approach is to return IDs (but not Attachments in the Body field)

from a query

call and then pass them into

calls that return the Body field.

Page 158

AppExchange API

Usage

The API sends and receives the binary file attachment data encoded as a base64Binary data type. Prior to

, client applications must encode the binary attachment data as base64.

Upon receiving a response, client applications must decode the base64 data to binary (this conversion is usually handled for you by the SOAP client).

The create

call restricts Attachments to a maximum size of 5MB. For a file attached to a

Solution ,

the limit is 1.5MB. The maximum email attachment size is 3MB.

The API supports attachments on email in

, and

calls. The query call does

not return attachments parented by emails, unless the user performing the query has the

“Modify All Data” permission.

Note

The

call does not search Attachment

objects during text searches.

See Also

Note on page 205

Page 159

AppExchange API

BusinessProcess

Represents a business process.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Description

IsActive

Name

Field

Type

Use the BusinessProcess object to offer different subsets of picklist values to different users for

Description

Description of this business process. Up to 255 characters.

Indicates whether this BusinessProcess can be presented to users in the Salesforce user interface (True) or not (False) when creating a new record type or changing the business process of an existing record type.

Name of this business process. Up to 80 characters.

Usage

the Lead Status, Case Status, and Opportunity Stage fields (see the

objects, respectively). Similar to a RecordType , a BusinessProcess

, CaseStatus

, and

OpportunityStage

identifies the type of a row in a Case ,

Lead , or

Opportunity and implies a subset of picklist values

for these three fields. The values for the remaining picklist fields are driven off of RecordType

Page 160

AppExchange API

Campaign

Represents and tracks a marketing campaign, such as a direct mail promotion, webinar, or trade show.

Supported Calls

Fields

The Campaign statistics fields are read-only (as in the Salesforce user interface). You cannot update the statistics via the API. For a complete list of fields in this object, see the WSDL file for your organization and the Salesforce online help.

Usage

Client applications can

s associated with a campaign via the API.

The Campaign object is defined only for those organizations that have the Marketing feature enabled and valid Marketing licenses. In addition, it is accessible only to those users that are enabled as Marketing Users. If the organization does not have the Marketing feature or valid

Marketing licenses, the Campaign object does not appear in the describeGlobal

call, and you cannot use

CampaignMember s. You will commonly need to update campaigns with CampaignMember . See CampaignMember on page 162.

with the Campaign object.

Note

The main constituents of campaigns are

Page 161

AppExchange API

CampaignMember

Represents the association between a Campaign

and either a

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CampaignId

ContactId

FirstRespondedDate

HasResponded

LeadId

Status

Field

Type

Description

associated. For information on IDs, see ID Fields on page 136.

ID of the

Campaign to which this

Lead or

Contact is

ID of the

who is associated with a Campaign

date boolean

Indicates the date on which the campaign member was first given a responded status.

Indicates whether the campaign member has responded to the campaign (True) or not (False).

ID of the

who is associated with a

you cannot use describeSObjects or

Controls the Responded flag on a CampaignMember. You cannot directly set the Responded flag, as it is readonly, but you can set it indirectly by setting the Status field in a create or update call. Each predefined Status field value implies a Responded flag value. Each time you update the Status field, you implicitly update the

Responded

flag on the CampaignMember.

In the Salesforce user interface, Marketing Users can define the valid CampaignMember status values for the

Status

picklist. They can choose one status as the default CampaignMember status. For each Status field value, they can also select which values should be counted as “Responded,” meaning that the Responded flag will be set to True for those Status values.

Usage

Each CampaignMember record has a unique ID. Each individual CampaignMember record must contain either a ContactId or a LeadId, but cannot contain both. Any attempt to create a single

CampaignMember with both a contactId and a LeadId will result in a successful insert but only the ContactId will be inserted. However, you can create separate CampaignMember records on a

Campaign —one for the

Lead and one for the

Contact .

The CampaignMember object is defined only for those organizations that have the Marketing feature and valid Marketing licenses. In addition, the object is accessible only to those users that are enabled as Marketing Users. If the organization does not have the Marketing feature or valid

Marketing licenses, the CampaignMember object does not appear in the

describeGlobal call, and

You can indirectly update CampaignMember records by sending a create

with the CampaignMember object.

Page 162

AppExchange API

Inserting, Updating, and Deleting Campaign Members

request. A

create call

for CampaignMembers is interpreted as an auto-insert-or-update call. The API automatically determines whether a CampaignMember exists with the specified

Id and Contact

Id or

Id. If the CampaignMember does not exist for the given Contact Id or

Id, then a

is performed. If the CampaignMember already exists, the call is interpreted as an

and the Status field and Responded flag on the existing record are updated. Thus, you cannot create duplicate CampaignMember records, because any attempt to create a duplicate record simply updates the existing record.

During a

value specified in the call is a valid CampaignMember status for the given Campaign

call, the AppExchange Web service verifies whether the Status field

. If the specified Status value is a valid CampaignMember status, the AppExchange Web service assigns that value to the CampaignMember Status field and updates the Responded flag with the associated value. If the specified Status value is not a valid CampaignMember status, the API assigns the default CampaignMember status to the Status field and updates the Responded flag with the associated value. However, if the given

does not have a default

CampaignMember status, the API assigns the value specified in the call to the Status field, and the Responded flag is set to False.

Page 163

AppExchange API

Case

Represents a case, which is a customer issue such as a customer’s feedback, problem, or question.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CaseNumber

ClosedDate

ClosedOnCreate

ContactId

Description

IsClosed

IsEscalated

IsVisibleInCss

Origin

OwnerId

Priority

Reason

Field

Type

Description

The date and time when the case was closed.

only and is automatically set upon create . It cannot be set

Indicates whether the case was closed at the same time that it was created (True) or not (False). This flag is read-

to True unless the IsClosed flag is also True.

Contact . For information on IDs, see

ID of the associated

A text description of the case. Can have up to 32,000 characters.

Indicates whether the case is closed (True) or open

(False). This field is controlled by the Status field; it cannot be set directly.

use a case, or whether you can query ,

Assigned automatically when each case is inserted. It cannot be set directly, and it cannot be modified after the

Case is created.

Indicates whether the case has been escalated (True) or not. A case's escalated state does not affect how you can

, or delete it.

However, you cannot set the IsEscalated flag via the

API. For more information on case escalation, see the online help.

Indicates whether the case can be viewed in the Customer

Self-Service Portal (True) or not (False).

The source of the case, such as “Email,” “Phone,” or

“Web.”

ID of the case owner.

The importance or urgency of the case, such as “High,”

“Medium,” or “Low.”

The reason why the case was created, such as

“Instructions not clear,” or “User didn’t attend training.”

Page 164

AppExchange API

Field

Status

Subject

SuppliedCompany

SuppliedEmail

SuppliedName

SuppliedPhone

Type

Field

Type

object to manage cases for your organization. Client applications can create

Description

The status of the case, such as “New,” “Closed,” or

“Escalated.” This field directly controls the IsClosed flag.

Each predefined Status value implies an IsClosed flag value. For more information, see

CaseStatus .

The subject of the case. Can have up to 255 characters.

The company name that was entered when the case was created. Cannot be updated after the case has been created.

The email address that was entered when the case was created. Cannot be updated after the case has been created.

The name that was entered when the case was created.

Cannot be updated after the case has been created.

The phone number that was entered when the case was created. Cannot be updated after the case has been created.

The type of case, such as “Feature Request” or “Question.”

Usage

Use the Case

s associated with a case via the API.

When you

assigned to one or more User s based on assignment rules that have been configured in the

a case, your client application can have the case automatically

Salesforce user interface. To use this feature, your client application needs to set either of the following options (but not both) in the

AssignmentRuleHeader used in the

call:

Field assignmentRuleId useDefaultRule

Field

Type

Description

assignment rule, you query the AssignmentRule

ID of the assignment rule to use. Can be an inactive assignment rule. If unspecified and

useDefaultRule

is True, then the default assignment rule is used. To find the ID for a given

object (specifying RuleType=”caseAssignment”),

iterate through the returned AssignmentRule

objects, find the one you want to use, retrieve its

ID, and then specify its ID in this field in the

AssignmentRuleHeader

Lead (which is similar to

Specifies whether to use the default rule for rulebased assignment (True) or not (False). The default rule is assigned by users in the Salesforce user interface.

For a code example that shows setting the

AssignmentRuleHeader

for a

setting the

AssignmentRuleHeader for a

), see

Represents a comment that provides additional information about the associated Case .

Page 165

AppExchange API

Page 166

AppExchange API

CaseComment

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CommentBody

IsPublished

ParentId

Field

Type

Description

Text of the CaseComment. The maximum size of the comment body is 4000 bytes.

Indicates whether the CaseComment is visible to customers in the Self-Service portal (True) or not (False).

This is the only field that can be updated via the API. All of the other case CaseComment cannot be updated.

ID of the parent

of the CaseComment. For information on

IDs, see

particular Case . All users have access to create and view

Usage

In the Salesforce user interface, comments are generally entered by users working on a

CaseComment s in the Salesforce user

interface and when using the API. In both the Salesforce user interface and via the API,

CaseComment

s cannot be modified after insertion, except to update the Published field. You cannot delete

CaseComment s by any means.

Page 167

AppExchange API

CaseHistory

Superseded by

EntityHistory

. Represents historical information about changes that have been

made to the associated Case

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CaseId

Field

OldValue

NewValue

Field

Type

Description

ID of the Case associated with the CaseHistory entry. For

information on IDs, see

Name of the case field that was modified, or a special value to indicate some other modification to the case. The possible values, in addition to the case field names, are:

• ownerAssignment - The owner of the case was changed.

• ownerAccepted - A User took ownership of a case from a queue.

• ownerEscalated - The owner of the case was changed due to case escalation.

• external - A User made the case visible to customers in the

Customer Self-Service Portal.

Previous value of the modified case field.

New value of the modified case field.

Usage

The CaseHistory object is always read-only in Salesforce. Case history entries are indirectly created by modifying a case via the Salesforce user interface or the API.

Two rows are added to CaseHistory when foreign key fields change. One row contains the foreign key entity names that display in the online application. For example, “Jane Doe” is recorded as the name of a Contact. The other row contains the actual foreign key ID that is only returned to and visible from the API.

Page 168

AppExchange API

CaseShare

Represents a sharing entry on a

Supported Calls

Fields

For a complete list of fields in this object type, see the WSDL file for your organization.

Field

CaseAccessLevel

CaseId

RowCause

UserOrGroupId

Field

Type

Description

Group has to the

can view or edit the Case .

. One of the following values:

• Owner -

cannot access the

• Read Only -

can only view the

• Read/Write -

•

All - User

Group can view, edit,

, and share the Case with

other Users. This value is not valid for

calls.

This field must be set to an access level that is higher than the organization’s default access level for cases.

ID of the Case associated with this sharing entry. This field cannot be

updated. For information on IDs, see ID Fields on page 136.

or Group has access because a User with “All”

Reason that this sharing entry exists. Read-only. Values may include:

•

Manual - The User

access manually shared the

is the owner of the Case or is in a Role above the

with them.

•

Owner - The User

Case owner in the role hierarchy.

• ImplicitChild -

has access to the Case on the

associated with this Case

•

Rule - The User or

Group has access via a

Case sharing rule.

Group that has been given access to the

ID of the User

Case s owned by other users. For more information, see

. This field cannot be updated.

Usage

The CaseShare object allows you to determine which users and groups can view and/or edit

Sharing on page 21.

If you attempt to insert a CaseShare that matches an existing CaseShare record, the

AccountShare on page 148

call updates any modified fields and returns the existing record.

See Also

OpportunityShare on page 222

LeadShare on page 200

Page 169

AppExchange API

CaseSolution

Represents the association between a particular

and a particular

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CaseId

SolutionId

Field

Type

Description

associated with the Solution . For information on

ID of the Case

IDs, see

ID of the Solution associated with the case.

Usage

You cannot update CaseSolutions via the API. If you attempt to insert a CaseSolution that

matches an existing CaseSolution record, the create

call simply returns the existing record.

Page 170

AppExchange API

CaseStatus

Represents the status of a Case

, such as New, On Hold, In Process, and so on.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsClosed

IsDefault

MasterLabel

SortOrder

Field Type

closed Case (True) or not (False). Multiple case status values can represent a closed Case .

Description

Indicates whether this case status value represents a

Indicates whether this is the default case status value

(True) or not (False) in the picklist.

Master label for this case status value. This display value is the internal label that does not get translated.

Number used to sort this value in the case status picklist. These numbers are not guaranteed to be sequential, as some previous case status values might have been deleted.

Usage

The

CaseStatus object represents a value in the case status picklist. The case status picklist

provides additional information about the status of a

represents an open or closed case. Your client application can invoke the query call on the

, such as whether a given status value

CaseStatus object to retrieve the set of values in the case status picklist, and then use that

information while processing Case objects to determine more information about a given case.

For example, the application could test whether a given case is open or closed based on its

Status

value and the value of the IsClosed property in the associated CaseStatus object.

The CaseStatus object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on CaseStatus objects.

Page 171

AppExchange API

CategoryData

Represents a logical grouping of Solution

records.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Usage

CategoryData

allows you to assign one or more categories to a Solution

. It is an intermediate

data table with two foreign keys that defines the relationship between a CategoryNode and a

the other foreign key, RelatedEntityID, refers to a Solution

record.

CategoryData

has two foreign keys:

• the first foreign key, CategoryNodeID, refers to the ID of a

CategoryNode

•

ID.

This is a many-to-many relationship, so there can be multiple rows returned with a particular

CategoryNode ID—a

CategoryNode on page 173

can be associated with multiple categories.

Note

Access to this object must be requested from Salesforce.

See Also

Page 172

AppExchange API

CategoryNode

Represents a tree of

categories.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

SortAlphabetically

Field Type Description

Controls the sort order of child CategoryNode

objects.

If this field is True, then the SortOrder column of direct children will be ignored.

Usage

CategoryNode defines a category of solutions. In the Salesforce user interface, you can edit

category definitions at Setup | Customize | Solution | Solution Categories.

Note

Attempting to delete a CategoryNode that has children (referred by CategoryNode.Parent), or is referred to elsewhere, will cause a failure.

See Also

CategoryData on page 172

Represents a contact, which is an individual associated with your Account

Page 173

AppExchange API

Contact

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Usage

Use the Contact object to manage individuals who are associated with Account s in your

organization. Client applications can create

s associated with a contact via the API.

Client applications can also create or update Contact objects by converting a

Lead via the

convertLead call. For more information, see convertLead

Page 174

AppExchange API

Contract

Represents a contract (a business agreement) associated with an

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountId

ActivatedById

ActivatedDate

CompanySignedDate

CompanySignedId

ContractNumber

ContractTerm

CustomerSignedDate

CustomerSignedId

EndDate

OwnerExpirationNotice

StartDate

Status

Field Type

Description

ID of the

associated with this contract.

ID of the

who activated this contract.

Date/time when this contract was activated.

Date on which this contract was signed by your organization.

ID of the

who signed this contract.

Number of this contract.

Number of months that this contract is valid.

Date on which the customer signed this contract.

ID of the

who signed this contract.

Calculated end date of this contract. Read-only.

This value is calculated by adding the

ContractTerm

to the StartDate.

Number of days ahead of the contract end date

(15, 30, 45, 60, 90, and 120). Used to notify the owner in advance that the contract is ending.

Start date for this contract.

Status for the contract.

Usage

The

object represents a business agreement. Client applications can

create ,

retrieve contracts via the API.

query , and

The Status field specifies the current state of a contract. Status strings (defined in the

ContractStatus

object) represent its current state (Draft, InApproval, or Activated).

Client applications must initially create

a Contract in a non-Activated state. Client applications can subsequently activate a Contract by calling

update call when activating the Contract.

and setting the value in its Status field to

Activated

; however, the Status field is the only field that the client application can set in the

Once a Contract has been activated, your client application cannot change its status; however, prior to activation, your client application can change the status from Draft to InApproval via

Page 175

AppExchange API the API. Also, your client application can

contracts whose status is Draft or InApproval but not when a contract is Activated.

Client applications can

s associated with a contract via the API.

Page 176

AppExchange API

ContractContactRole

Represents the role that a given

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

ContactId

ContractId

IsPrimary

Role

Field Type

Description

ID of the

associated with this Contract

ID of the

. For information on IDs, see ID

Specifies whether this Contact

plays the primary role on this

Name of the role played by the Contact

(True) or not (False). Note that each contract has only one primary contact role.

on this

Use the ContractContactRole

, such as Decision Maker, Approver,

Buyer, and so on. Must be unique—there cannot be multiple records in which the ContractId,

ContactId

, and Role values are identical.

Different contacts can play the same role on the same contract. A contact can play different roles on the same contract.

Usage

object to define the role that a given Contact plays on a given

Contract within the context of a specific

See Also

Contact on page 174

Contract on page 175

Represents the status of a Contract

Page 177

AppExchange API

ContractStatus

, such as Draft, InApproval, Activated, Terminated, or

Expired.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsDefault

MasterLabel

SortOrder

StatusCode

Field Type

ContractStatus object represents a value in the contract status picklist. The contract status

Description

Indicates whether this is the default contract status value (True) or not (False) in the picklist.

Master label for this contract status value. This display value is the internal label that does not get translated.

Number used to sort this value in the contract status picklist. These numbers are not guaranteed to be sequential, as some previous contract status values might have been deleted.

Code indicating the status of a contract. One of the following values:

• Draft

• InApproval

• Activated

Two other values (Terminated and Expired) are defined but are not available for use via the API.

Usage

The

picklist provides additional information about the status of a

, such as its current state

(Draft, InApproval, or Activated). Your client application can invoke the

call on the

ContractStatus object to retrieve the set of values in the contract status picklist, and then use that information while processing

objects to determine more information about a given contract. For example, the application could test whether a given contract is activated based on its Status value and the value of the StatusCode property in the associated ContractStatus object.

The ContractStatus object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on ContractStatus objects.

Page 178

AppExchange API

CurrencyType

Represents the currencies used by an organization for which the multi-currency feature is enabled.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

ConversionRate

DecimalPlaces

IsActive

IsCorporate

IsoCode

Field

Type

Description

Conversion rate of this currency type against the corporate currency.

For this currency, specifies the number of digits to the right of the decimal point, such as zero (0) for

JPY or 2 for USD. Required.

Indicates whether this currency type is active

(True) or not (False). Inactive currency types do not appear in picklists in the Salesforce user interface.

Indicates whether this currency type is the corporate currency (True) or not (False). Required.

All other currency conversion rates are applied against this corporate currency. If a currency is already defined as the corporate currency in the

Salesforce user interface, it cannot be unset.

When a non-corporate currency is set to a corporate currency, the system will reconfigure all conversion rates based on the new corporate currency.

ISO code of the currency. Required. Must be one of the valid alphabetic, three-letter currency ISO code defined by the ISO 4217 standard, such as

USD, GBP, or JPY. Must be unique within your organization.

Usage

For multi-currency organizations only, use the

CurrencyType object to define the currencies that

your organization uses. This object is not available in single-currency organizations.

Your client application cannot

CurrencyType object. In addition, you need “Customize

Application” permission to edit a CurrencyType.

Page 179

AppExchange API

Division

A logical segment of your organization's data. For example, if your company is organized into different business units, you could create a division for each business unit, such as “North

America,” “Healthcare,” or “Consulting.”

Supported Calls

Fields

For a complete list of fields on this object, see the Enterprise WSDL file for your Division-enabled

organization. (For more information about the Web Service WSDLs, see WSDL Files for Web

Services on page 4).

Field

IsActive

IsGlobalDivision

Name

SortOrder

Field Type

Represents a file that a user has uploaded. Unlike Attachment objects, Documents are not

Description

Indicates whether the division is active (True) or not

(False).

Indicates whether the division is your organization’s global default division (True) or not (False).

A descriptive name for the division, up to 80 characters.

The order in which this division name appears in the

Division picklist field when creating or editing users in the Salesforce user interface.

Usage

To discover whether divisions have been enabled for an organization, inspect the User object for the DefaultDivision field--if it is present, then divisions have been enabled. The values available for that field are the global division ID for the organization, created when divisions are first enabled, and any other division IDs that have been created. The division ID associated with a user is populated in the objects owned or created by the user.

You can use the division ID to make searches, reports, and list views run more quickly and return more relevant results if an organization has very large data sets. For more information, see the Salesforce online help, in the Fields description for the object.

For more information about how divisions are used, see the topic “Overview of Divisions” in the

Salesforce online help.

Note

The User object has a Division field that is unrelated to the Division object. The Division field is a standard text field similar to Company or Department that has no special properties. Do not confuse it with the DefaultDivision field, which does relate to the Division object.

Page 180

AppExchange API

Document

attached to a parent object.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AuthorID

Field Type

Body

BodyLength

Description

FolderId

Name

Type

URL

Description

ID of the

who is responsible for the Document. For

ID of the Folder that contains the Document. See Folder on page 192.

Encoded file data. If specified, then do not specify an URL.

Size of the file (in bytes).

Text description of the Document.

Name of the Document.

File type of the Document. In general, the values match the file extension for the type of Document (such as pdf or jpg

.).

URL reference to the file (instead of storing it in the database). If specified, do not specify the Body /

BodyLength.

Usage

You must have the “Edit” permission on Documents and the appropriate access to the

Folder that contains a document in order to create or update a Document in that Folder .

When calling create

update for a document, a client application can specify a value in either

the Body or URL fields—but not both.

Encoded Data

The API sends and receives the binary file data encoded as a base64Binary data type. Prior to

, clients must encode the binary file data as base64. Upon receiving an API response, clients must decode the base64 data to binary (this conversion is usually handled for you by the

SOAP client).

Maximum Document Size

The

create and

received. For information on IDs, see ID Fields on page 136.

calls restrict documents to a maximum size of 5MB.

Page 181

AppExchange API

Page 182

AppExchange API

EmailMessage

An email message.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

ActivityId

BccAddress

CcAddress

FromAddress

FromName

HasAttachment

Headers

HtmlBody

Incoming

MessageDate

ParentId

Status

Subject

TextBody

ToAddress

Field Type

Description

ID of the activity that is associated with the email.

Usually represents an open task that is created for the case owner when a new unread email message is

The addresses that were sent a blind carbon copy of the email.

The addresses that were sent a carbon copy of the email.

The address that originated the email.

The sender’s name.

Indicates whether the email was sent with an attachment (True) or not (False).

The Internet message headers of the incoming email. Used for debugging and tracing purposes.

Does not apply to outgoing emails.

The body of the email in HTML format.

Indicates whether the email was received (True) or sent (False).

The date the email was created.

ID of the

to which the email is associated.

Read only. The status of the email. For example,

“New,” “Unread,” “Replied,” “Sent.”

The subject line of the email.

The body of the email, in plain text format.

The address of the email’s recipient.

Page 183

AppExchange API

Usage

This object is specific to the Email-to-Case feature, which allows emails sent to one of your company’s email addresses to automatically create a new case in Salesforce. See the online help for more information.

See Also

picklist anyType anyType reference picklist

Page 184

AppExchange API

EntityHistory

Represents historical information about an object’s changed field values. Supersedes

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

FieldName

NewValue

OldValue

ParentID

ParentSobjectType

Data Type

Description

ID of the standard or custom field. For information on IDs, see

In API version 7.0 and later, EntityHistory works with Case ,

New value of the modified field.

Previous value of the modified field.

ID of the object that contains the field.

The kind of object that contains the field.

Usage

Contract , and

Solution objects:

• The EntityHistory object is always read-only in the online application.

• When a field is modified, EntityHistory records both the old and new field values.

There are exceptions to this behavior for certain fields such as long text areas and multiselect picklists. These fields appear in EntityHistory to indicate that the field was changed, but the old and new values are not recorded.

• Two rows are added to EntityHistory when foreign key fields change. One row contains the foreign key entity names that display in the online application. For example, “Jane Doe” is recorded as the name of a Contact. The other row contains the actual foreign key ID that is only returned to and visible from the API.

• Up to a total of twenty standard and/or custom fields can be tracked for a given object.

• In the online application, you can specify which fields are tracked or not tracked at any time.

See the online help for more information.

• As soon as tracking is turned on for a field, all changes in value are recorded in the database.

• Turning off tracking for a field stops further changes from being recorded, but the history data is not deleted.

• Be advised that deleting a custom field also permanently deletes the history data for that custom field.

See Also

Contract on page 175

Account . For information on

Page 185

AppExchange API

Event

Represents a calendar appointment event.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountId

ActivityDate

ActivityDateTime

Description

Division

DurationInMinutes

IsAllDayEvent

IsChild

Field Type

Description

ID of the related

IDs, see

If the Event IsAllDayEvent flag is set to True

(indicating that it is an all day Event), then the Event due date information is contained in the ActivityDate field. This field is a date field with a timestamp that is always set to midnight in the GMT/UTC time zone. The timestamp is not relevant, and you should not attempt to alter it to account for any time zone differences.

If the Event IsAllDayEvent flag is set to

False (indicating that it is not an all day

Event), then the Event due date information is contained in the ActivityDateTime field.

This field is a regular Date/Time field with a relevant time portion. The time portion is always transferred in the GMT/UTC time zone. You need to translate the time portion to or from a local time zone for the user or the application, as appropriate.

Text description of the event. Can have up to

32,000 characters.

The name of the related division.

The event length, in minutes. Note that even though this represents a temporal value, it is an integer type—not a dateTime type.

Indicates whether the ActivityDate field

(True) or the ActivityDateTime field (False) is used to define the date and/or time of the event.

Indicates whether the event is a child of another event (True) or not (False). This field is not editable.

Page 186

AppExchange API

Field

IsGroupEvent

IsPrivate

IsRecurrence

Location

OwnerId

RecurrenceActivityId

RecurrenceDayOfMonth

RecurrenceDayOfWeekMask

RecurrenceEndDateOnly

RecurrenceInstance

RecurrenceInterval

Field Type

Description

Indicates whether the event is a group event with multiple attendees (True) or not (False).

This field is not editable.

Indicates whether users other than the creator of this event can (False) or cannot

(True) see the event details when viewing the event user's calendar. However, users with the “View All Data” or “Modify All Data” permission can see private events in reports and searches, or when viewing other users' calendars. Private events cannot be associated with opportunities, accounts, cases, campaigns, contracts, leads, or contacts.

Indicates whether the event is scheduled to repeat itself (True) or only occurs once

(False). This is a read only field on update, but not on create. If IsRecurrence is True, then RecurrenceStartDateTime,

RecurrenceEndDateOnly

, RecurrenceType, and any recurrence fields associated with the given recurrence type must be populated.

See Recurring Events .

The location of the event.

ID of the user who owns the event.

Read-only. Not required on create. ID of the main record of the recurring event.

Subsequent occurrences have the same

RecurrenceActivityID

The day of the month on which the event repeats.

The day or days of the week on which the event repeats. This field contains a bitmask.

For each day of the week, the values are as follows:

• Sunday = 1

• Monday = 2

• Tuesday = 4

• Wednesday = 8

• Thursday = 16

• Friday = 32

• Saturday = 64

Multiple days are represented as the sum of their numerical values. For example, Tuesday and Thursday = 4 + 16 = 20.

The last date on which the event repeats.

The frequency of the recurring event. For example, “2nd” or “3rd.”

The interval between recurring events.

Page 187

AppExchange API

Field

RecurrenceMonthOfYear

RecurrenceStartDateTime

RecurrenceTimeZoneSidKey

RecurrenceType

ShowAs

Subject

Type

WhatId

WhoId

Field Type

picklist picklist picklist combobox picklist reference reference

Description

The month of the year on which the event repeats.

The date and time when the recurring event begins. Must be a date and time before

RecurrenceEndDateOnly

The time zone associated with the recurring event. For example, “GMT-8:00” for Pacific

Standard Time.

Indicates how often the event repeats. For example, daily, weekly, or every Nth month

(where “Nth” is defined in

RecurrenceInstance

Indicates how this event appears when another user views the calendar: busy, out of office, or free time.

The subject line of the event, such as “Call,”

“Email,” or “Meeting.”

The type of event, such as “Call,” “Email,” or

“Meeting.”

ID of a related

, or custom object.

ID of a related

Lead . If the WhoId

refers to a lead, then the WhatId field must be empty.

Usage

Use

deemed too large. In such cases, OPERATION_TOO_LARGE is returned. If you receive the

s to manage calendar appointments.

Queries on events will be denied before they time out if they involve amounts of data that are

OPERATION_TOO_LARGE

error message, refactor your query to return or scan a smaller amount of data.

When querying for events with a specific due date, you must filter on both the

ActivityDateTime

and ActivityDate fields. For example to find all events with a due date of

February 14, 2003, you need two filters:

• One filter with the ActivityDate field equal to midnight GMT on February 14, 2003.

• One filter with the ActivityDateTime field greater than or equal to midnight on February 14,

2003 in the user’s local time zone AND less than or equal to midnight on February 15, 2003 in the user’s local time zone.

Recurring Events

• Recurring events are available in version 7.0 and later.

• After an event is created, it cannot be changed from recurring to nonrecurring or vice versa.

• If IsRecurrence is True, then RecurrenceStartDateTime, RecurrenceEndDateOnly,

RecurrenceType

, and any properties associated with the given recurrence type (see the following table) must be populated.

Page 188

AppExchange API

The following table describes the usage of recurrence fields. Each recurrence type must have all of its properties set. All unused properties must be set to null.

RecurrenceType Value

RecursDaily

RecursEveryWeekday

RecursMonthly

RecursMonthlyNth

RecursWeekly

RecursYearly

RecursYearlyNth

Properties

RecurrenceInterval

RecurrenceDayOfWeekMask

RecurrenceInterval

RecurrenceDayOfMonth

RecurrenceInterval

RecurrenceInstance

RecurrenceDayOfWeekMask

RecurrenceInterval

RecurrenceDayOfWeekMask

RecurrenceDayOfMonth

RecurrenceMonthOfYear

RecurrenceInstance

RecurrenceDayOfWeekMask

RecurrenceMonthOfYear

Example Pattern

Every second day

Every weekday - cannot be

Saturday or Sunday

Every second month, on the third day of the month

Every second month, on the last

Friday of the month

Every three weeks on

Wednesday and Friday

Every March on the twentysixth day of the month

The first Saturday in every

October

Archived Activities

Older events and Task s are archived according to the criteria listed below. In the Salesforce user

interface, users can view archived activities only in the Printable View or by clicking View All on the Activity History related list or by doing an advanced search. However, in the API, archived activities are not accessible.

Activities are archived according to the following criteria:

• Events with an ActivityDateTime or ActivityDate value greater than or equal to 365 days old

• Tasks with a Closed flag value of True and an ActivityDate value greater than or equal to

365 days old

• Tasks with a Closed flag value of True, a blank ActivityDate field, and a create date greater than or equal to 365 days ago

If you use the API to insert activities that meet these criteria, the activities will be archived during the next run of the archival background process.

Page 189

AppExchange API

EventAttendee

Represents a person ( User ,

) who has been invited to attend an Event , or a

, or Lead

scheduled resource (such as a conference room) associated with the event.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AttendeeId

EventId

RespondedDate

Response

Status

Field

Type

Description

ID of the person ( User ,

been invited to attend the Event , or the scheduled resource associated with this Event . For

, or Lead ) who has

information on IDs, see

ID of the Event

Date and time when the attendee (invitee) responded.

Optional text that the attendee entered when responding to the event request.

query the EventAttendee object for a given event, iterate through the list, examine

Attendee status. One of the following values:

•

New

—Invitee has received the invitation but has not yet responded.

•

Declined

—Invitee has declined to attend the event.

•

Accepted

—Invitee has accepted the invitation to attend the event.

•

Deleted

—The invitation has been deleted.

•

Uninvited

—Reserved for future use.

•

Maybe

—Reserved for future use.

Usage

The EventAttendee object is a read-only object that provides information about who has been invited to attend a particular event and their response to that invitation. A client application can, for example,

the status, and send email notifications to every person who accepted the invitation.

To determine all the events that a particular person is attending during a given time period (for

example, next week), a client application could query the Event

object for a given date range, iterate through the results and, for each event, query the EventAttendee object and determine whether the particular person (attendeeId) has accepted an invitation to that event.

Page 190

AppExchange API

FiscalYearSettings

Settings to define a custom or standard fiscal year for your organization. FiscalYearSetting objects have a parent-child relationship with

Period

objects.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsStandardYear

Name

PeriodId

PeriodLabelScheme

PeriodPrefix

QuarterLabelScheme

QuarterPrefix

WeekLabelScheme

YearType

Field Type

reference picklist picklist picklist picklist picklist picklist

Description

Indicates whether the fiscal year is a standard calendar year (True) or a custom fiscal year (False).

A name for the fiscal year. Can have up to 80 characters.

ID of the associated fiscal period. For information on

IDs, see ID Fields on page 136.

The numbering scheme used for fiscal periods.

The prefix of fiscal periods. For example, if “P” is the prefix, then the first period is “P1.”

The numbering scheme used for fiscal quarters.

The prefix of fiscal quarters. For example, if “Q” is the prefix, then the fourth quarter would be “Q4.”

The numbering scheme used for weeks.

Indicates one of two types of fiscal years, Standard or Custom. Standard denotes the standard

Gregorian calendar, while Custom means a fiscal year with a custom structure.

Usage

This is a read-only object. For information on setting up custom or standard fiscal years, see the

Salesforce online help.

See Also

Period on page 230

MailMergeTemplate , email template, or report. Only

Page 191

AppExchange API

Folder

Represents a repository for a

Document ,

one type of item can be contained in a particular Folder.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccessType

IsReadOnly

Name

Type

Field

Type

Description

Indicates who can access the Folder. Available values include:

• Hidden—Folder is hidden from everyone.

• Public—Folder is accessible by all users.

•

Shared—Folder is accessible only by User s in a particular

UserRole . The API does not allow you to view,

insert, or update which group or Role the Folder is shared with.

Indicates whether this Folder is read-only (True) or editable

(False).

Name of the Folder.

Type of objects contained in the Folder. The Type field cannot be updated. Available values include:

• Document

• Email template

• Report

Usage

You must have the “Modify All Data” permission to create, update, or delete document folders, email template folders, or report folders. To query Folders, no special permissions are needed.

Page 192

AppExchange API

Group

Represents a set of User s.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Email

Name

RelatedId

Type

Field

Type

Description

Email address for a group of type Case. Applies only for a case queue.

Name of the Group.

For Groups of type “Role,” the ID of the associated

UserRole . Read-only.

Type of the Group. One of the following values:

• Regular—Standard public Group. When you

Role—Public Group that includes all of the User s in a

Group, its type must be Regular.

•

particular

UserRole .

• RoleAndSubordinates—Public Group that includes all of

the User

in a particular

UserRole and all of the

User s in

UserRole s below that UserRole .

• Organization—Public Group that includes all of the

s in the organization. This Group is read-only.

• Case—Public group of people that comprise a queue that can own a

• Lead —Public group of people that comprise a queue that can own a

Lead .

Usage

Groups can be deleted. Any

GroupMember on page 194

can access the Group object—no special permissions are needed.

Only public Groups are accessible via the API. Personal Groups are not available.

See Also

Group that is a members of a public group.

Page 193

AppExchange API

GroupMember

Represents a User or

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

GroupId

UserOrGroupId

Field

Type

Description

ID of the

. For information on IDs, see ID Fields on page 136.

ID of the

User or

A GroupMember record exists for every User

that is a direct member of the group.

Usage

GroupMembers cannot be updated. Any user can access the GroupMember object—no special permissions are needed.

Group who is a direct member of a public group

whose Type field is set to “Regular”. Users who are indirect members of “Regular” public groups are not listed as group members. A User can be an indirect member of a group if he or

she is in a UserRole

above the direct group member in the hierarchy, or if he or she is a member of a group that is included as a subgroup in that group.

If you attempt to insert a GroupMember that matches an existing GroupMember record, the

call simply returns the existing record.

See Also

Group on page 193

Represents a lead, which is a prospect or potential Opportunity

Page 194

AppExchange API

Lead

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Type

Description

Annual Revenue

City

Annual revenue for the company of the lead.

City for the address of the lead.

Company of the lead.

Company

ConvertedAccountId

ConvertedContactId

Object reference ID that points to the Account into

which the Lead

has been converted. For information

Object reference ID that points to the Contact into

which the Lead

has been converted.

Date on which this Lead was converted.

ConvertedDate

ConvertedOpportunityId

Object reference ID that points to the Opportunity

into which the

Lead has been converted.

Country

Description

Email

Fax

FirstName

Industry

IsConverted

IsUnreadByOwner

Country for the address of the lead.

Description of the lead.

Email address for the lead.

Fax number for the lead.

First name of the lead.

Industry the lead works in.

Indicates whether the Lead

has been converted

(True) or not (False).

If true, lead has been assigned, but not yet viewed.

See Unread Leads on page 196 for more information.

LastName

LeadSource

MobilePhone

NumberOfEmployees

OwnerId

picklist phone

Last name of the lead.

Source from which the lead was obtained.

Mobile phone number for the lead.

Number of employees at the lead’s company.

the API by the LeadStatus object. See

User ID of the owner of the lead.

Page 195

AppExchange API

Field

Phone

PostalCode

Rating

Salutation

State

Status

Field

Type

Description

Phone number for the lead.

Postal code for the address of the lead.

Rating of the lead.

Salutation for the lead.

State for the address of the lead.

Status code for this converted lead. Status codes are defined in the lead status picklist and represented in

Lead Status

Picklist on page 196 for more information.

Street number and name for the address of the lead.

Title for the lead, for example CFO or CEO.

Website for the lead.

Street

Title

Website

url

Converted Leads

Leads have a special state to indicate that they have been converted into an

Account ,

Opportunity . Your client application can convert leads via the

, and

convertLead call. Users can

also convert Leads through the Salesforce user interface. Once a Lead has been converted, it is read-only. You cannot

picklist, a client application can invoke the query

a converted Lead. However, you can query converted

Leads using the query

call.

Leads have several fields that indicate their converted status. These special fields are read-only via the API. You cannot set these fields directly; they are set when converting the Lead in the

Salesforce user interface. The fields are:

•

ConvertedAccountId

•

ConvertedContactId

•

ConvertedDate

•

ConvertedOpportunityId

•

IsConverted

•

Status

Unread Leads

Leads have a special state to indicate that they have not been viewed or edited by the lead owner. In the Salesforce user interface, this is helpful for users to know which leads have been assigned to them but which they have not touched yet. The

IsUnreadByOwner

field is True if the lead owner has not yet viewed or edited the lead, and False if the lead owner has viewed or edited the lead at least once.

Lead Status Picklist

Each

Status

value corresponds to either a converted or unconverted status in the lead status picklist, as defined in the Salesforce user interface. To obtain the lead status values in the

call on the LeadStatus object.

You cannot convert a lead via the API by changing the Status field to one of the “converted” lead status values. When you convert qualified leads into an account, contact, and opportunity, you can select one of the “converted” status types to assign to the lead. Leads with a “converted” status type are no longer available in the Leads tab, although you can include them in reports.

Page 196

AppExchange API

Usage

To update

or call convertLead

, your client application must be logged in with the “Edit” permission on Leads.

When you

create ,

upsert a lead, your client application can have the lead

, or

automatically assigned to one or more

AssignmentRuleHeader used in the

s based on assignment rules that have been configured in the Salesforce user interface.

To use this feature, your client application needs to set either of the following options (but not both) in the

call:

Field assignmentRuleId useDefaultRule

Field

Type

Description

query the AssignmentRule object (specifying

ID of the assignment rule to use. Can be an inactive assignment rule. If unspecified and

useDefaultRule

is True, then the default assignment rule is used.

To find the ID for a given assignment rule, you

RuleType="leadAssignment"

), iterate through the

returned AssignmentRule objects, find the one you

want to use, retrieve its ID, and then specify its ID in this field in the

AssignmentRuleHeader .

Specifies whether to use the default rule for rulebased assignment (True) or not (False). The default rule is assigned by users in the Salesforce user interface.

The following code example shows how to automatically assign a newly created lead.

package com.sforce; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.sforce.soap.enterprise.LoginResult; import com.sforce.soap.enterprise.QueryResult; import com.sforce.soap.enterprise.SaveResult; import com.sforce.soap.enterprise.SforceServiceLocator; import com.sforce.soap.enterprise.SoapBindingStub; import com.sforce.soap.enterprise._AssignmentRuleHeader; import com.sforce.soap.enterprise._SessionHeader; import com.sforce.soap.enterprise.fault.LoginFault; import com.sforce.soap.enterprise.fault.UnexpectedErrorFault; import com.sforce.soap.enterprise.sobject.Lead; import com.sforce.soap.enterprise.sobject.SObject; public class LeadAssignment {

static LeadAssignment _leadAssignment;

public static void main(String[] args) {

_leadAssignment = new LeadAssignment();

try {

_leadAssignment.CreateLead();

Page 197

AppExchange API

} catch (Exception e) {

e.printStackTrace();

}

public void CreateLead() throws UnexpectedErrorFault, LoginFault,

RemoteException {

//Create the proxy binding and login

SoapBindingStub binding = (SoapBindingStub) new

SforceServiceLocator().getSoap();

LoginResult lr = binding.login("[email protected]", "secret");

//Reset the binding to use the endpoint returned from login

binding._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_POINT, loginResult.getServerUrl());

//Create the session id header, and add it to the proxy binding

_SessionHeader sh = new _SessionHeader();

sh.setSessionId(lr.getSessionId());

binding.setHeader(new

SforceServiceLocator().getServiceName().getNamespaceURI(), "SessionHeader", sh);

//Create a new case and assign various properties

Lead lead = new Lead();

lead.setFirstName("Joe");

lead.setLastName("Smith");

lead.setCompany("ABC Corporation");

lead.setLeadSource("API");

//The lead assignment rule will assign any new leads that

//have "API" as the LeadSource to a particular user

//Create the assignment rule header and add it to the proxy binding

_AssignmentRuleHeader arh = new _AssignmentRuleHeader();

//In this sample we will look for a particular rule and if found

//use the id for the lead assignment. If it is not found we will

//instruct the call to use the current default rule. You cannot use

//both of these values together.

QueryResult qr = binding.query("Select Id From AssignmentRule where Name =

'Mass Mail Campaign' and RuleType = 'leadAssignment'");

if (qr.getSize() == 0) {

arh.setUseDefaultRule(new Boolean(true));

} else {

arh.setAssignmentRuleId(qr.getRecords(0).getId());

}

binding.setHeader(new

SforceServiceLocator().getServiceName().getNamespaceURI(),

"AssignmentRuleHeader", arh);

// Every operation that results in a new or updated case, will

// use the specified rule until the header is removed from the

// proxy binding.

SaveResult[] sr = binding.create(new SObject[] {lead});

for (int i=0;i<sr.length;i++) {

if (sr[i].isSuccess())

System.out.println("Successfully creaeted lead with id of: " + sr[i].getId().getValue() + ".");

else

Page 198

AppExchange API

System.out.println("Error creating lead: " + sr[i].getErrors(0).getMessage());

}

// This call effectively removes the header, the next lead will

// be assigned to the default lead owner. Remember to add the

// session header back in.

binding.clearHeaders();

binding.setHeader(new

SforceServiceLocator().getServiceName().getNamespaceURI(),

"SessionHeader", sh);

}

Page 199

AppExchange API

LeadShare

Represents a sharing entry on a

Supported Calls

Fields

For a complete list of fields in this object type, see the WSDL file for your organization.

Field

CaseAccessLevel

CaseId

RowCause

UserOrGroupId

Field

Type

Description

can view or edit the Lead

Group has to the

Lead . One of the

following values:

• Owner -

cannot access the

• Read Only -

can only view the

• Read/Write -

•

All - User

Group can view, edit,

, and share the Lead

with other

s. This value is not valid for

calls.

This field must be set to an access level that is higher than the organization’s default access level for leads.

updated. For information on IDs, see ID Fields on page 136.

ID of the Lead

associated with this sharing entry. This field cannot be

Manual Sharing - The User or

Reason that this sharing entry exists. Read-only. Values may include:

•

Group has access because a User with

“All” access manually shared the

Lead with them.

•

Owner - The User

is the owner of the Lead

or is in a Role above the

Case owner in the role hierarchy.

• ImplicitChild -

has access to the Lead

on the

associated with this Lead .

•

Sharing Rule - The User or

has access via a Lead

sharing rule.

ID of the

that has been given access to the Lead

. This field cannot be updated.

Usage

The LeadShare object allows you to determine which users and groups can view and/or edit

Leads owned by other users. For more information, see Sharing on page 21.

If you attempt to insert a LeadShare that matches an existing LeadShare record, the create

call updates any modified fields and returns the existing record.

See Also

AccountShare on page 148

OpportunityShare on page 222

CaseShare on page 169

Represents the status of a Lead , such as Open, Qualified, or Converted.

Page 200

AppExchange API

LeadStatus

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsConverted

IsDefault

MasterLabel

SortOrder

Field Type

Description

Indicates whether this lead status value represents a converted lead (True) or not (False). Multiple lead status values can represent a converted lead. For more information, see

convertLead on page 54.

Indicates whether this is the default lead status value

(True) or not (False) in the picklist.

Master label for this lead status value. This display value is the internal label that does not get translated.

Number used to sort this value in the lead status picklist.

These numbers are not guaranteed to be sequential, as some previous lead status values might have been deleted.

Usage

The

object represents a value in the lead status picklist (see Lead Status Picklist on page 196). The lead status picklist provides additional information about the status of a

Lead ,

such as whether a given status value represents a converted

Lead . Your client application can

invoke the

Lead objects to determine more

call on the LeadStatus object to retrieve the set of values in the lead status picklist, and then use that information while processing

information about a given lead. For example, the application could test whether a given lead is converted based on its Status value and the value of the IsConverted property in the associated LeadStatus object.

The LeadStatus object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on LeadStatus objects.

Page 201

AppExchange API

LineitemOverride

A forecast override of a line item on an Opportunity

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AmountInherited

ForecastCategoryInherited

OpportunityId

OpportunityLineItemId

OverrideAmount

Field Type

OverrideForecastCategory

reference reference currency

OverrideQuantity

OverrideUnitPrice

OwnerId

QuantityInherited

TerritoryId

UnitPriceInherited

Description

Indicates whether the overridden amount rolls up through the forecast hierarchy (True), or was overridden by the LineitemOverride owner

(False).

Indicates whether the overridden forecast category rolls up through the forecast hierarchy (True), or was overridden by the

LineitemOverride owner (False).

ID of the associated

. For

ID of the associated

OpportunityOverride on page 219

The total monetary amount of the line item, possibly overridden.

The forecast category of the line item, possibly overridden.

The quantity of the line item, possibly overridden.

The monetary amount of the unit price, possibly overridden.

ID of the LineitemOverride owner.

Indicates whether the overridden quantity rolls up through the forecast hierarchy (True), or was overridden by the LineitemOverride owner

(False).

ID of the forecast owner’s

UserRole or

Territory .

Indicates whether the overridden unit price rolls up through the forecast hierarchy (True), or was overridden by the LineitemOverride owner (False).

Page 202

AppExchange API

Usage

This is read-only object specific to customizable forecasting. It has a child-parent relationship

with OpportunityOverride

See Also

application can specify the Body field in the create

Page 203

AppExchange API

MailMergeTemplate

Represents a mail merge template (a Microsoft Word document) used for performing mail merges for your organization.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Body

BodyLength

Description

Filename

LastUsedDate

Name

Field Type Description

base64Binary

Microsoft Word document to use as a mail merge template. Up to 5MB. Due to limitations with

Microsoft Word mail merge templates, your client

call but not in the

call.

Length of the Microsoft Word document.

Text description of this mail merge template. Up to 255 characters.

Use the MailMergeTemplate object to manage mail merge templates for your organization. All

Filename of the Microsoft Word document that was uploaded as a mail merge template. Up to

255 characters in length.

Date and time when this MailMergeTemplate was last used.

Name of this mail merge template.

Usage

users can view a MailMergeTemplate, but you need the “Customize Application” permission to modify it.

Page 204

AppExchange API

Note

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

IsPrivate flag

The IsPrivate flag on a note is a Boolean field that influences the access rights for that note. If the note is marked private, only the note owner or a User with the “Modify All Data” permission can view the note or query it via the API. Because of this, you can create an unusual situation for a regular user that does not have the “Modify All Data” permission. If a regular user sets the

IsPrivate

flag to True on a note that they do not own, then they can no longer query ,

, or

Product2 , or custom object.

that note.

Usage

Represents a note, which is text associated with an

Use the Note object to manage notes for an Attachment

, Contact ,

Opportunity , or a

custom object.

Page 205

AppExchange API

Opportunity

Represents an opportunity, which is a sale or pending deal.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountId

Amount

CampaignId

CloseDate

CurrencyIsoCode

Description

ExpectedRevenue

Field

Type

Description

Id of the account associated with this opportunity

Estimated total sale amount. For opportunities with products, the amount is the sum of the related products. Any attempt to update this field, if the Opportunity has products, will be ignored. The update call will not be rejected, and other fields will be updated as specified, but the

Amount will be unchanged.

is defined only for those organizations that have

s enabled as a feature. The

must have read access rights to the cross-referenced

object in order to

that campaign into the CampaignId field on the

Opportunity.

picklist textarea currency

The date when the Opportunity is expected to close.

Exists only for multi-currency organizations. If your organization does not have multi-currency enabled, this field is not accessible.

If the organization has multi-currency and a

Pricebook2 is specified on the Opportunity (i.e.,

the Pricebook2Id field is not blank), then the value of this field must match the value of the

objects that are associated with any opportunity line items it has.

Text description of the Opportunity. Up to 32,000 characters.

A read-only field that is equal to the product of the Opportunity Amount field and the

Probability

. You cannot directly set the

ExpectedRevenue

field, but you can indirectly set it by setting the Amount or Probability fields.

Page 206

AppExchange API

Field

ForecastCategory

HasOpportunityLineItem

IsClosed

IsWon

LeadSource

Name

NextStep

Field

Type

Description

A restricted picklist field. It is implied, but not directly controlled, by the StageName field. You can override this field to a different value than is implied by the StageName.

The values of the ForecastCategory field are fixed enumerated values. The field labels are localized to the language of the user performing the operation, if localized versions of those labels are available for that language in the

Salesforce user interface.

Read-only field that indicates whether the

Opportunity has associated line items. A value of

True means that Opportunity line items have been created for the Opportunity.

An Opportunity can have Opportunity line items only if the Opportunity has a price book. The opportunity line items must correspond to

Pricebook2 . However, you can

objects that are listed in the

Opportunity's

insert Opportunity line items on an Opportunity

that does not have an associated Pricebook2

For the first Opportunity line item that you insert

on an Opportunity without a Pricebook2 , the API

automatically sets the Pricebook2Id field, if the

Opportunity line item corresponds to a

Pricebook2 is not active or the CurrencyIsoCode

in an active Pricebook2

that has a CurrencyIsoCode field that matches the

CurrencyIsoCode

field of the Opportunity. If the

fields do not match, then the Web service returns an error.

You cannot

update the Pricebook2Id or

PricebookId

fields if opportunity line items exist on the

Opportunity . You must

the line items before attempting to update the

PricebookId

field

Directly controlled by StageName. You can query and filter on this field, but you cannot directly

set it in a create ,

upsert

, or

request. It can only be set via StageName.

Directly controlled by StageName. You can query and filter on this field, but you cannot directly

set it in a create ,

upsert

, or

request. It can only be set via StageName.

The source of the Opportunity, such as

Advertisement or Trade Show.

A name for the Opportunity. Can have up to 80 characters.

Description of next task in closing opportunity.

Up to 255 characters are allowed in this field.

Page 207

AppExchange API

Field

OwnerId

Pricebook2Id

PricebookId

Probability

StageName

TotalOpportunityQuantity

Type

Field

Type

Description

User who has been assigned to work

ID of the

this Opportunity.

ID of a related Pricebook2

object. The

Pricebook2Id

field indicates which

applies to this specific Opportunity. The

Pricebook2Id

field is defined only for those organizations that have Products enabled as a feature.

You can specify values for only one field

(Pricebook2Id or PricebookId)—not both fields. For this reason, both fields are declared nillable

Deprecated as of version 3.0 and is provided for backward compatibility only. Unless you need to continue referring to a

Pricebook

object for this

Opportunity in an existing client application, use the Pricebook2Id field instead, specifying the

ID of the

Pricebook2 object.

percent

Percentage of estimated confidence in closing the opportunity. It is implied, but not directly controlled, by the StageName field. You can override this field to a different value than what is implied by the StageName.

Current stage of the Opportunity. The

StageName

field controls several other fields on an Opportunity. Each of the fields can be directly set or implied by changing the StageName field.

In addition, the StageName field is a picklist, so it has additional members in the returned

to indicate how it affects the other fields. To obtain the stage name values in the picklist, a client application can invoke the

call on the OpportunityStage

object. If the StageName is updated, then the

ForecastCategory

is automatically updated based on the stage-category mapping.

The number of items included in an Opportunity.

Used in quantity-based forecasting.

The type of opportunity. For example, Existing

Business or New Business.

Usage

Use the Opportunity

object to manage information about a sale or pending deal. To update

Opportunity , your client application needs “Edit” permission on Opportunities. Client applications

, and

Attachment s associated with an opportunity via the API.

For a visual diagram of the relationships between

Schedule Objects on page 274.

and other objects, see

Product and

Client applications can also create or update Opportunity objects by converting a

Lead via the

convertLead call.

Page 208

AppExchange API

See Also

OpportunityCompetitor on page 210

OpportunityHistory on page 212

OpportunityLineItem on page 213

OpportunityLineItemSchedule on page 216

Page 209

AppExchange API

OpportunityCompetitor

Represents a competitor on an

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CompetitorName

OpportunityID

Strengths

Weaknesses

Field

Type

Description

combobox

Name of the competitor.

ID of the associated

. For information

Description of the competitor’s strengths. Can have up to 1,000 characters.

Use the OpportunityCompetitor

Description of the competitor’s weaknesses. Can have up to 1,000 characters.

Usage

object to manage competitors on an Opportunity

, associating multiple competitors on a opportunity and specifying the strengths and weaknesses of each competitor.

See Also

Opportunity on page 206

Represents the association between an Opportunity and a

Page 210

AppExchange API

OpportunityContactRole

, with a specified

UserRole

name applied to the contact.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

ContactId

OpportunityId

Field

Type

Description

ID of an associated Contact

. The API applies user access rights to the associated

Opportunity for an

OpportunityContactRole, but not to the associated

Contact . As such, the API may return rows from

an OpportunityContactRole query that include

ContactId

values for contacts to which the user does not have sufficient access rights. It may also return ContactId values for contacts that have been deleted. In either case, the client must

perform

a query on the contact table for that

ContactId value to determine whether the

is accessible to the user and has not been deleted.

ID of an associated Opportunity

. The

OpportunityId

field of an

OpportunityContactRole is non-nullable, and it cannot be updated. You must provide a value for

the OpportunityId on create

. You cannot change it after it has been inserted.

Usage

OpportunityContactRoles appear in the Salesforce user interface on the Opportunity detail page.

Like most other objects, OpportunityContactRole records have their own unique ID that you use when updating or deleting an OpportunityContactRole.

You can create multiple relationships between the same Opportunity and a

Contact . This action is

not recommended, but the application does not prohibit it.

Page 211

AppExchange API

OpportunityHistory

Represents the history of an Opportunity .

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Amount

CloseDate

ExpectedRevenue

ForecastCategory

OpportunityId

Probability

StageName

Field

Type

Description

double date

currency picklist

Estimated total sale amount.

Date when the opportunity is expected to close.

Calculated revenue based on the Amount and

Probability

fields.

Category that determines the column in which an opportunity is totaled in a forecast.

ID of the associated

. For information

percent

Percentage of estimated confidence in closing the opportunity.

Name of the current stage of the opportunity (for example, Prospect or Proposal).

Usage

The OpportunityHistory object represents the history of a change to any of the major fields

(listed above) of an

. To obtain information about how fast a particular opportunity is progressing,

all of the OpportunityHistory objects associated with a given Opportunity .

The OpportunityHistory object is read-only. The system generates a new OpportunityHistory object whenever a user or client application changes the value of any of the above fields; the then-current values of all of these major fields are saved in the newly-generated object.

Note that the OpportunityHistory object is automatically deleted if its parent Opportunity

is deleted.

See Also

Opportunity on page 206

Product2 s associated with

Page 212

AppExchange API

OpportunityLineItem

Represents an opportunity line item, which is a member of the list of

an Opportunity

, along with other information about those products on that opportunity.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CurrencyIsoCode

Description

HasRevenueSchedule

HasQuantitySchedule

ListPrice

OpportunityId

Field

Type

Description

Pricebook2 is specified on the parent

Exists only for multi-currency organizations. If your organization does not have the multicurrency enabled, the CurrencyIsoCode field is not accessible.

If the organization has multi-currency enabled, and a

Opportunity (i.e., the

Pricebook2Id

field is not blank on the Opportunity referenced by this object’s

OpportunityId

), then the value of this field must match the value of the

CurrencyIsoCode

field on the PricebookEntry

object that is associated with this object.

Text description of the opportunity line item. Can have up to 255 characters.

Read-only. Indicates whether a revenue schedule has been created for the OpportunityLineItem

(True) or not (False).

If the OpportunityLineItem has a revenue schedule, the Quantity and TotalPrice fields cannot be updated. In addition, the Quantity field cannot be updated if the OpportunityLineItem has a quantity schedule. The API ignores any attempt

to update these fields. The update

call will not be rejected but the updated values will be ignored.

Read-only. Indicates whether a quantity schedule has been created for the OpportunityLineItem

(True) or not (False).

Corresponds to the UnitPrice on the

that is associated with this line item, which can be in the standard pricebook or a custom pricebook. A client application can use this information to show whether the unit price (or sales price) of the line item differs from the pricebook entry list price.

ID of the associated

. For information

Page 213

AppExchange API

Field

PriceBookEntryId

ProductId

Quantity

TotalPrice

UnitPrice

Field

Type

Description

ID of the associated

. Exists only for those organizations that have Products enabled as a feature. You can specify values for only either PricebookEntryId or ProductId, but not both. For this reason, both fields are declared nillable.

continue referring to a Product

ID of the associated

Product

. This field has been deprecated as of version 3.0 and is only provided for backward compatibility. Unless you need to

object for this

OpportunityLineItem in an existing client application, use the PricebookEntryId field instead, specifying the ID of the

object.

In a given update call, you can change either the

Read-only if the OpportunityLineItem has a quantity schedule, a revenue schedule, or both a quantity and a revenue schedule.

currency currency

This field is deprecated but exists in order to provide backward compatibility. It represents the total price of the OpportunityLineItem.

TotalPrice

or the UnitPrice, but not both at the same time. This field is nillable, but you cannot se both TotalPrice and UnitPrice to null in the same

update call.

To insert the TotalPrice for an

OpportunityLineItem via the API (given only a unit price and the quantity), calculate the TotalPrice field as the unit price multiplied by the quantity.

The TotalPrice field is read-only if the

OpportunityLineItem has a revenue schedule. If the OpportunityLineItem does not have a schedule or only has quantity schedule, the

TotalPrice

field can be updated.

The unit price for the OpportunityLineItem. In the

Salesforce user interface, the unit price is calculated by dividing the total price of the

OpportunityLineItem by the quantity listed for that line item.

Usage

can have OpportunityLineItems only if the opportunity has a Pricebook2

. An

OpportunityLineItem must correspond to a Product2

that is listed in the opportunity's

Pricebook2 . For information about inserting OpportunityLineItems for an Opportunity that does not have an associated Pricebook2

or any existing line items, see

Effects on Opportunities on page 215.

The OpportunityLineItem object is defined only for those organizations that have Products enabled as a feature. If the organization does not have the Products feature, the

OpportunityLineItem object does not appear in the describeGlobal call, and you cannot use

describeSObjects or

query with the OpportunityLineItem object.

Page 214

AppExchange API

For a visual diagram of the relationships between

Product and Schedule Objects on page 274.

and other objects, see

Note:

If multi-currency option has been enabled, the CurrencyIsoCode field will be present. It cannot be modified, and is always set to the value of the CurrencyIsoCode of the parent

For more information about CurrencyIsoCode fields, see Currency Field Type on page 134.

Permissions

The user must have the “Edit” permissions on Opportunity records in order to

Inserting an OpportunityLineItem increments the Opportunity Amount value by the

opportunity line items on an opportunity.

Effects on Opportunities

Opportunities that have associated OpportunityLineItems are affected in the following ways:

•

TotalPrice

of the OpportunityLineItem. Additionally, inserting an OpportunityLineItem increments the Expected Amount on the opportunity by the TotalPrice times the opportunity Probability.

• The opportunity Amount becomes a read-only field when the opportunity has line items. The

API ignores any attempt to update this field on an opportunity with line items. The

call will not be rejected, but the updated value will be ignored.

• You cannot update the PricebookId field or the CurrencyIsoCode field on the opportunity if line items exist. The API rejects any attempt to update these fields on an opportunity with line items.

• When you

an OpportunityLineItem, the API verifies that the line item corresponds to a

Pricebook2 that is associated with the opportunity. If the opportunity does not have an associated Pricebook2

in the

, the Web service automatically sets the pricebook on the opportunity if the line item corresponds to a

in an active

, and if the PricebookEntry has a CurrencyIsoCode field that matches the

CurrencyIsoCode

field of the opportunity. If the Pricebook2

is not active or the

CurrencyIsoCode

fields do not match, the AppExchange Web service returns an error.

• The opportunity HasLineItem field is set to True when an OpportunityLineItem is inserted for that opportunity.

particular OpportunityLineItem .

Page 215

AppExchange API

OpportunityLineItemSchedule

Represents information about the quantity, revenue distribution, and delivery dates for a

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Description

OpportunityLineItemId

Quantity

Revenue

ScheduleDate

Type

Field

Type

Description

schedule. See Allowed Quantity and Revenue Field

Text description of the opportunity line item schedule. Can have up to 255 characters.

ID of the associated

The total number of units to be scheduled in a quantity schedule. See

Allowed Quantity and

Revenue Field Values

for more information.

The total price to be scheduled in a revenue

Values for more information.

The date the associated OpportunityLineItem is to

be scheduled for an event: delivery, shipping, or any other date you wish to track.

The type of the schedule. Required when inserting an OpportunityLineItemSchedule. Valid values

include Quantity, Revenue, or Both. See Allowed

Type Field Values

for more information.

Allowed Type Field Values

The allowed Type values for a particular OpportunityLineItemSchedule depend on the productlevel schedule preferences and whether the line item has any existing schedules. The following criteria must be met:

• The

Product2 on which the

OpportunityLineItem is based must have the appropriate

RevenueScheduleEnabled

and/or QuantityScheduleEnabled flags set to True.

• When you

create a schedule for a line item that does not have any existing schedules, you

can specify any valid value.

Page 216

AppExchange API

•

If you create a schedule for a line item that already has existing schedules, the new schedule

must be consistent with the existing schedules. The following matrix outlines the allowable values:

Value of

HasRevenueSchedule on line item

false false true true

Value of

HasQuantitySchedule on line item

false true false true

Allowable Type Values

Revenue, Quantity, Both

Quantity

Revenue

Both

Allowed Quantity and Revenue Field Values

The allowable Quantity and Revenue field values depend on the value of the Type field:

Type Value

Revenue

Quantity

Both

Allowable Quantity Value

Null

Non-null

Allowable Revenue Value

Non-null

Null

Non-null

The Quantity and Revenue fields have the following restrictions in the update call.

• For a schedule of Type “Quantity,” you cannot update a null Revenue value to non-null.

Likewise for a schedule of Type “Revenue,” you cannot update a null Quantity value to nonnull.

• You cannot null out the Quantity field for a schedule of Type “Quantity.” Likewise you cannot null out the Revenue field for a schedule of Type “Revenue.”

• You cannot null out either the Revenue or Quantity fields for a schedule of type “Both.”

Usage

Two types of OpportunityLineItemSchedules are supported:

• Quantity schedules

• Revenue schedules

The user must have edit access rights on the

describeGlobal call, and you cannot use

in order to create

update line item

schedules on that opportunity.

Applies Only If Products and Schedules Are Enabled

The OpportunityLineItemSchedule object is defined only for those organizations that have the

Products and Schedules features enabled. If the organization does not have the Products and

Schedules features, the OpportunityLineItemSchedule object does not appear in the

field on the OpportunityLineItem by the line item schedule Revenue amount.

query with the

OpportunityLineItemSchedule object.

Page 217

AppExchange API

Effects on Opportunities and Opportunity Line Items

OpportunityLineItemSchedules affect opportunities and opportunity line items in the following ways:

• Inserting an OpportunityLineItemSchedule of Type “Revenue” or “Quantity” increments the

TotalPrice

Inserting an OpportunityLineItemSchedule of Type “Quantity” or “Both” increments the

Quantity

field on the

OpportunityLineItem by the line item schedule Quantity amount.

• The

call also affects the original opportunity as follows: 1) the Opportunity Amount is

incremented the by OpportunityLineItemSchedule revenue amount; and 2) the Opportunity

Expected Amount

is incremented by the line item schedule amount multiplied by the

Opportunity Probability.

• Deleting an OpportunityLineItemSchedule has a similar effect on the related

OpportunityLineItem and

Opportunity . Deleting a schedule decrements the

OpportunityLineItem TotalPrice by the deleted line item schedule amount. The opportunity

Amount

is also decremented by the line item schedule amount, and the Opportunity

Expected Amount

is reduced by the line item schedule amount multiplied by the Opportunity

Probability

Deleting an Opportunity Line Item Schedule

Deleting the last remaining schedule will set the corresponding HasQuantitySchedule and/or

HasRevenueSchedule

flags to False on the parent line item.

See Also

OpportunityLineItem on page 213

Product2 on page 238

delete on page 65

Page 218

AppExchange API

OpportunityOverride

A forecast override of an

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AmountInherited

ForecastCategoryInherited

OpportunityId

OutOfDate

OverrideAmount

OverrideComment

OverrideForecastCategory

OverridePeriodId

OverrideQuantity

OwnerId

Field Type

Description

Indicates whether the overridden amount rolls up through the forecast hierarchy (True), or was overridden by the OpportunityOverride owner (False).

Indicates whether the overridden forecast category rolls up through the forecast hierarchy (True) or was overridden by the

OpportunityOverride owner (False).

ID of the associated

. For

True if a subordinate user's

OpportunityOverride, or the opportunity itself, has been updated since this override was last updated, such that an overridden value on this override may be obsolete. For example, a subordinate user has more recently overridden the same period, category, or amount field.

The total monetary amount of the opportunity, possibly overridden.

The comment entered on the opportunity forecast edit page. Can have up to 255 characters.

The forecast category of the opportunity, possibly overridden.

ID of the associated fiscal

Period , possibly

overridden. If you are using custom fiscal years and the period falls after your custom fiscal year has ended, then the override is not returned. For information on custom fiscal years, see the Salesforce online help.

The quantity of the opportunity, possibly overridden.

ID of the OpportunityOverride owner.

Page 219

AppExchange API

Field

PeriodInherited

QuantityInherited

TerritoryId

Field Type

LineitemOverride on page 202

Description

Indicates whether the overridden period rolls up through the forecast hierarchy (True) or was overridden by the OpportunityOverride owner (False).

Indicates whether the overridden quantity rolls up through the forecast hierarchy (True) or was overridden by the OpportunityOverride owner (False).

ID of the associated

Territory

if Territory

Management is enabled, otherwise the field is not available.

Usage

This is read-only object specific to customizable forecasting. It has a parent-child relationship

with LineitemOverride

See Also

Page 220

AppExchange API

OpportunityPartner

A partner relationship between an

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountToId

IsPrimary

OpportunityId

Role

Field Type

Account in the partner relationship.

reference picklist

Description

ID of the partner

For information on IDs, see

Opportunity that is in the partner

Indicates whether the account is the opportunity’s primary partner (True) or not (False).

ID of the

relationship.

The UserRole

that the

Account has on the

AccountPartner on page 147

. For example, “Reseller” or

“Manufacturer.”

Usage

OpportunityPartner

is a read-only object.

See Also

Partner on page 227

Represents a sharing entry on an Opportunity .

Page 221

AppExchange API

OpportunityShare

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

OpportunityAccessLevel

OpportunityId

RowCause

UserOrGroupId

Field

Type

Description

All—User or Group can view, edit, delete

Level of access that the User or Group has to the

Opportunity. Valid values include:

• None—User or Group cannot access the

Opportunity.

• Read—User or Group can only view the

Opportunity.

• Edit—User or Group can view or edit the

Opportunity.

•

, and share the Opportunity with other users. This

value is not valid for create

and

update calls.

This field must be set to an access level that is higher than the organization’s default access level for opportunities.

ID of the

associated with this sharing entry. This field cannot be updated. For information on IDs, see

Opportunity on the Account

Reason that this sharing entry exists. Read-only.

Valid values include:

• Owner—User is the owner of the Opportunity or

is in a UserRole

above the Opportunity owner in the role hierarchy.

• Manual—User or Group has access because a

User with “All” access manually shared the

Opportunity with them.

• Rule—User or Group has access via an

Opportunity sharing rule.

• ImplicitChild—User or Group has access to the

associated with this

OpportunityTeamMember on page 226 for

• Team—User has access to the Opportunity because she or he is on the sales team for the

Opportunity. The OpportunityTeamMember object for this Opportunity sets the access level.

See

more information.

edit opportunities owned by other users. For more information, see Sharing on page 21.

ID of the User

or Group

that has been given access to the Opportunity. This field cannot be updated.

Page 222

AppExchange API

Usage

The OpportunityShare object allows you to determine which users and groups can view and/or

If you attempt to create an OpportunityShare that matches an existing OpportunityShare record, the

create call updates any modified fields and returns the existing record.

See Also

Group on page 193

Key Concepts of API Objects

Page 223

AppExchange API

OpportunityStage

Represents the stage of an

in the sales pipeline, such as New Lead, Negotiating,

Pending, Closed, and so on.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field Field Type

DefaultProbability

percent

Description

ForecastCategory

IsActive

IsClosed

IsWon

MasterLabel

SortOrder

opportunity stage picklist provides additional information about the stage of a Opportunity , such

Description

The default percentage estimate of the confidence in closing a specific opportunity for this opportunity stage value.

Description of this opportunity stage value. Can have up to 255 characters.

The default forecast category for this opportunity stage value. The forecast category automatically determines how opportunities are tracked and totaled in a forecast.

Indicates whether this opportunity stage value is active

(True) or not (False). Inactive opportunity stage values are not available in the picklist and are retained for historical purposes only.

Indicates whether this opportunity stage value represents a closed opportunity (True) or not (False).

Multiple opportunity stage values can represent a closed opportunity.

Indicates whether this opportunity stage value represents a won opportunity (True) or not (False).

Multiple opportunity stage values can represent a won opportunity.

Master label for this opportunity stage value. This display value is the internal label that does not get translated. Can have up to 255 characters.

Number used to sort this value in the opportunity stage picklist. These numbers are not guaranteed to be sequential, as some previous opportunity stage values might have been deleted.

Usage

The

OpportunityStage

object represents a value in the opportunity stage picklist. The

as its probability or forecast category. Your client application can invoke the

use that information while processing Opportunity

call on the

OpportunityStage object to retrieve the set of values in the opportunity stage picklist, and then

Page 224

AppExchange API

objects to determine more information about a given opportunity. For example, the application could test whether a given opportunity is won or not based on its StageName value and the value of the IsWon property in the associated

OpportunityStage object.

The OpportunityStage object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on OpportunityStage objects.

Page 225

AppExchange API

OpportunityTeamMember

Represents an individual User

on the sales team of a particular Opportunity .

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

OpportunityId

UserId

TeamMemberRole

Field

Type

Description

ID of the

associated with this sales team. This field cannot be updated. For information on IDs, see

ID of the

who is a member of the

Opportunity’s sales team. This field cannot be updated.

OpportunityTeamMember record, the create

Role that the team member has on the Opportunity.

The valid values are set by the organization’s administrator in the Sales Team Roles picklist.

Usage

If you attempt to insert an OpportunityTeamMember that matches an existing

call updates any modified fields and returns the existing record.

In the Salesforce user interface, users can set up a sales team for the opportunities they own.

The sales team includes other users that are working on the Opportunity with them. The

OpportunityTeamMember object is available only in organizations that have enabled the team selling functionality.

See Also

UserTeamMember on page 266

Represents the association between two particular Account s or between a particular

Page 226

AppExchange API

Field

AccountFromId

AccountToId

IsPrimary

OpportunityId

Role

Partner

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Type

Description

Account in a partner relationship between

ID of the main

two accounts. Specifying this field when calling create

creates an Account Partner. If you specify the

OpportunityId

field, you cannot specify this field as well.

For information on IDs, see

ID of the Partner Account related to either an Opportunity or an Account. You must specify this field when creating an

Opportunity Partner or an Account Partner.

Valid for Opportunity Partners only.

Indicates that the Account is the primary Partner for the

Opportunity.Only one Account can be marked as “primary” for an Opportunity. If you set the Primary flag to 1 (True) upon insert of a new Opportunity Partner, any other existing primary partners for that Opportunity will automatically have their Primary flag set to 0 (False).

ID of the Opportunity in a partner relationship between an

calling create creates an Opportunity Partner. If you

and an Opportunity

. Specifying this field when

specify the AccountFromId field, you cannot specify this field as well.

UserRole that the Account has towards the related

Opportunity or Account (for example, Consultant or

Distributor).

Usage

All of the Partner fields are accessible in the describeSObjects

and

calls; see Fields on page 227. You must have the “View All Data” permission to access Partners via the API.

Each Account in the relationship is assigned a Role (such as “Consultant” or “Distributor”) designating that account’s role towards the related Account or Opportunity. A relationship between two Accounts is referred to as an Account Partner, and a relationship between an

Opportunity and an Account is referred to as an Opportunity Partner.

Using the

call, you can insert the OpportunityId or AccountFromId, AccountToId,

Primary

, and Role fields. You cannot

Partners via the API.

Page 227

AppExchange API

Using the

AccountPartner on page 147

call, you can insert the OpportunityId or AccountFromId, AccountToId,

Primary

, and Role fields. When creating a Partner object, you must specify either the

OpportunityId

field or the AccountFromId field. Specifying the OpportunityId field creates an

Opportunity Partner, and the AccountFromId field creates an Account Partner. You must always specify a value for the AccountToId field.

When you create an Account Partner—a relationship between two Accounts—the API automatically creates a reverse partner relationship between those two Accounts. For example, if you create an Account Partner with “Acme, Inc.” as the AccountFromId and “Acme Consulting” as the AccountToId, the API automatically creates a reverse partner with “Acme Consulting” as the AccountFromId and “Acme, Inc.” as the AccountToId. In the reverse partner, the value of the Role field is set to the designated reverse Role value associated with the value of the Role field in the original Account Partner. In the Salesforce user interface, system administrators can set up the valid Role values and their corresponding reverse Role values.

If you set the Primary flag to 1 (True) upon insert of a new Opportunity Partner, any other existing primary partners for that Opportunity will automatically have their Primary flag set to 0

(False).

See Also

OpportunityPartner on page 221

UserRole on page 265

PartnerRole on page 229

Page 228

AppExchange API

PartnerRole

Represents a role for an account

Partner

, such as consultant, supplier, and so on.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

MasterLabel

ReverseRole

SortOrder

Field Type

PartnerRole object represents a value in the partner role picklist. The partner role picklist

Description

Master label for this partner role value. This display value is the internal label that does not get translated.

Name of the reverse role that corresponds to this partner role. For example, if the role is “subcontractor,” then the reverse role might be “general contractor.” In the user interface, assigning a partner role to an account creates a reverse partner relationship so that both accounts list the other as a partner.

Number used to sort this value in the partner role picklist. These numbers are not guaranteed to be sequential, as some previous partner role values might have been deleted.

Usage

The

provides additional information about the role of a

Partner

, such as their corresponding reverse

role. Your client application can invoke the query call on the PartnerRole object to retrieve the

set of values in the partner role picklist, and then use that information while processing

PartnerRole objects to determine more information about a given partner role. For example, the

application could determine the reverse role of a given partner role based on its Role value and the value of the ReverseRole property in the associated PartnerRole object.

The PartnerRole object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on PartnerRole objects.

Page 229

AppExchange API

Period

A fiscal period.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

EndDate

IsForecastPeriod

Number

PeriodLabel

QuarterLabel

StartDate

Type

Data Type

Description

The last date of the fiscal period.

Indicates whether the period is associated with customizable forecasts (True) or not (False).

If the labeling scheme of your fiscal year's quarters or months is numbered, this field indicates the relative number of the row.

If the months in your fiscal year use custom names, then this field contains the appropriate name for rows of type Month.

If the quarters in your fiscal year use custom names, then this field contains the appropriate name for rows of type Quarter.

The first date of the fiscal period.

Indicates whether the period is of type Month,

Quarter, Week, or Year.

Usage

This is a read-only object that is related to FiscalYearSettings

See Also

FiscalYearSettings on page 191

Represents a price book that contains the list of Product s that your organization sells.

Page 230

AppExchange API

Pricebook

Note

The Pricebook object has been deprecated as of version 3.0 and is provided for backwards compatibility only. Unless you need to continue using the Pricebook object in an existing

application, use Pricebook2

instead.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Usage

Use the Pricebook object to query information about Pricebooks that have been configured for an

organization. The purpose of the Pricebook object is to allow you to obtain valid Pricebook object

IDs for use when querying or modifying

Product s through the API. See Product on page 236 for

more information.

The Pricebook object is defined only for those organizations that have Products enabled as a feature. If the organization does not have the Products feature, the Pricebook object does not

appear in the describeGlobal

call, and you cannot use

describeSObjects or

query with the

Pricebook object.

Products are the main constituents of Pricebooks. “Setting up a price book” via the API usually means loading products into those Pricebooks. Use this process to configure Pricebooks via the API:

1. Manually create the Pricebooks using the Salesforce user interface.

2. Query the Pricebook object to obtain the Pricebook IDs.

3. To load products into those Pricebooks, call create or

update using the API.

Page 231

AppExchange API

Pricebook2

Represents a price book that contains the list of products that your organization sells.

Note

In this release, price books are represented by

objects. The Pricebook object is no

longer recommended for use.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Description

IsActive

IsStandard

Name

Field Type

Description

Text description of this Pricebook2 object.

Indicates whether this Pricebook2 object is active (True) or not (False). Inactive Pricebook2 objects are hidden in many areas in the Salesforce user interface. You can change the IsActive flag on a Pricebook2 object as often as necessary.

Indicates whether this Pricebook2 object is the standard price book for the organization (True) or not (False).

Every organization has one standard price book—all other price books are custom price books.

Name of this Pricebook2 object. This field is read-only for the standard pricebook.

Usage

A price book is a list of products that your organization sells. Each organization has one standard price book that defines the standard or generic list price for each product or service that it sells.

In addition, an organization can have multiple custom price books that can be used for specialized purposes, such as a discount price book, price books for different channels or markets, price books for select accounts or opportunities, and so on. While your client

application can create ,

, and delete custom price books, your client application can only

update the standard price book. For some organizations, the standard price book might be the

only price needed, but if you need to set up further price books, you can reference the standard price book when setting up list prices in custom price books.

Use the Pricebook2 object to

information about standard and custom price books that have been configured for your organization. A common use of the Pricebook2 object is to allow your client application to obtain valid Pricebook2 object IDs for use when configuring

objects via the API. Your client application can query ,

create (custom, not

standard), update

, and

Pricebook object has been

Pricebook2 objects.

How PriceBook2, Product2, and PricebookEntry Objects Are Related

In the API:

• Price books are represented by

Pricebook2 objects (the

deprecated).

Page 232

AppExchange API

•

Products are represented by Product2 objects (the

Product

object has been deprecated).

•

Each price book contains zero or more entries (represented by PricebookEntry

objects) that specify the products that are associated with the price book. A price book entry defines the price for which you sell a product at a particular currency.

These objects are defined only for those organizations that have Products enabled as a feature.

If the organization does not have the Products feature enabled, the Pricebook2 object does not

appear in the describeGlobal

call, and you cannot access it via the API.

For a visual diagram of the relationships between Pricebook2

and other objects, see

Product and

Schedule Objects on page 274.

Setting Up a Price Book

The process of setting up a price book via the API usually means:

1. Initially loading product data from your organization into

Product2 objects (calling

for each product that you want to add).

2. For each

object, creating a PricebookEntry that links the

Product2 object to the

standard Pricebook2

. You need to define a standard price for a product at a given currency

(if you have multi-currency enabled), before defining a price for that product in the same currency in a custom pricebook.

3. Creating a custom

Pricebook2 .

4. Querying the Pricebook2 object to obtain the Pricebook2 IDs.

5. For each

object, creating a PricebookEntry for every

that you want to add, specifying unique properties for each

Product and Schedule Objects on page 274

(such as the UnitPrice and

CurrencyIsoCode

) as needed.

Page 233

AppExchange API

PricebookEntry

Represents a product entry (an association between a Pricebook2 and

) in a pricebook.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

CurrencyIsoCode

Field Type

(True) or not (False). Although you can never delete

IsActive

Name

Pricebook2Id

Product2Id

ProductCode

UnitPrice

UseStandardPrice

Description

Available only for organizations with the multi-currency feature enabled. Contains the ISO code for any currency allowed by the organization.

Indicates whether this PricebookEntry object is active

PricebookEntry objects, your client application can set the object’s IsActive flag to False. Inactive

PricebookEntry objects are hidden in many areas in the

Salesforce user interface. You can change the IsActive flag on a PricebookEntry object as often as necessary.

Name of this PricebookEntry object. This read-only field references the value in the Name field of the

create call. It cannot be

object.

ID of the Pricebook2

object with which this

PricebookEntry is associated. Required field. This field must be specified in the

changed in an update

call. For information on IDs, see

ID of the Product2 object with which this PricebookEntry

is associated. Required field. This field must be specified

in the create call. It cannot be changed in an

call.

of the associated Product2

Product code for this PricebookEntry object. This readonly field references the value in the ProductCode field

object.

Unit price for this PricebookEntry object. You can specify a UnitPrice only if UseStandardPrice is set to False.

Indicates whether this PricebookEntry object uses the

standard price defined in the standard Pricebook2 object

(True) or not (False). If set to True, then this field is read-only and it references the UnitPrice value in the associated

Product2 object. For PricebookEntry objects

associated with the standard Pricebook2

object,

UseStandardPrice

must be set to True.

Page 234

AppExchange API

Usage

Use the PricebookEntry object to define the association between your organization’s products

( Product2

object) and your organization’s standard price book or to other, custom-defined price books (

Pricebook2 objects). Using PricebookEntry objects allows you to configure the standard

price for a product in this price book or to override it with a custom value and, for multi-currency organizations, to specify different currencies as well.

When your client application calls

, it must specify the IDs of the associated Pricebook2

object and Product2 object. Once created, your client application cannot

update these IDs.

The PricebookEntry object is defined only for those organizations that have Products enabled as a feature. If the organization does not have the Products feature enabled, then the

PricebookEntry object does not appear in the

describeGlobal call, and you cannot access it via

the API.

For a visual diagram of the relationships between PricebookEntry

and other objects, see Product and Schedule Objects on page 274 and

How PriceBook2, Product2, and PricebookEntry Objects

Are Related on page 232.

Page 235

AppExchange API

Product

Represents a product that your organization sells. A product is member of the list of items in a

Pricebook

Note

The Product object has been deprecated as of version 3.0 and is provided for backwards compatibility only. Unless you need to continue using the Product object in an existing

application, use Product2

instead.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

PriceBookId Field

The PricebookId field indicates the

Pricebook

on which the Product is configured. When inserting Products, the PricebookId field must be set, and its value must be valid and non-

blank. You cannot update the PricebookId field during an update

call. You can query the

Pricebook object to obtain valid Pricebook object IDs for your organization after they have been

created using the Salesforce user interface.

IsActive Flag

The IsActive flag indicates whether a Product is active. Although you can never delete Products,

you can set a Product’s IsActive flag to False. Inactive Products are hidden in many areas in the

Salesforce user interface. You can change a Product’s IsActive flag as often as necessary.

Schedule

Enabled Flags

Default

Schedule

Fields

Schedule Fields

The Product object has several fields that are only used for schedules (a.k.a. annuities). Two types of schedules on Products are supported—quantity schedules and revenue schedules.

Schedules are available only for those organizations that have the Products and Schedules features enabled. If the organization does not have the Schedules feature, the schedule fields do

not appear in the DescribeSObjectResult

, and you cannot

s can have a schedule of that type. These flags can be set via a create

, or

update the fields.

When enabling the Schedules feature, organizations can decide whether to enable quantity schedules, revenue schedules, or both. In addition, you can use the API to control quantity and revenue scheduling at the product level via the RevenueScheduleEnabled and

QuantityScheduleEnabled

flags. A value of True for either flag indicates that the Product and

any OpportunityLineItem

uses the default schedule values to create an OpportunityLineItemSchedule

call.

The remaining Product schedule fields define default schedules for the object. The Web service

when an

OpportunityLineItem is created for the Product. The API ignores default schedules on a product

when a line item referencing it is created.

The following table lists the default schedule fields and their valid values.

Field

RevenueScheduleType

RevenueInstallmentPeriod

Valid Values

None, Divide, Repeat

None, Daily, Weekly, Monthly, Quarterly, Yearly

Page 236

AppExchange API

Field

NumberOfRevenueInstallments

QuantityScheduleType

QuantityInstallmentPeriod

NumberOfQuantityInstallments

Valid Values

An integer from 1 to 100

None, Divide, Repeat

None, Daily, Weekly, Monthly, Quarterly, Yearly

An integer from 1 to 100

When you attempt to set the schedule fields via a

The Product object allows you to query ,

call, the API applies crossfield integrity checks. The integrity requirements are:

• If the schedule type is set to “None,” then the installment period and number of installments must be null.

• If the schedule type is set to any value other than “None,” then the installment period and number of installments must be non-null.

Inserts or updates that fail these integrity checks are rejected with an error.

The RevenueScheduleType, RevenueInstallmentPeriod, QuantityScheduleType, and

QuantityInstallmentPeriod

fields are restricted picklist fields and are available only if the organization has the Schedules feature enabled.

Usage

, and update

(but not

Pricebook on page 231). Products can be queried, inserted, and updated via the API, but they

) Products on

Pricebooks. These operations constitute the main configuration necessary for Pricebooks (see

cannot be deleted through the API or any other means. See IsActive Flag on page 236 for more

information. Because Products can never be deleted, exercise caution when creating them.

The Product object is defined only for those organizations that have Products enabled as a feature. If the organization does not have the Products feature, the Product object does not appear in the

describeGlobal

call, and you cannot use describeSObjects

OpportunityLineItem on page 213

with the Product object.

See Also

OpportunityLineItemSchedule on page 216

Products are represented by Product2 objects. The Product object has been deprecated.

Page 237

AppExchange API

Product2

Represents a product that your organization sells.

Note

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Description

Family

IsActive

Name

ProductCode

Field Type

textarea picklist

describeSObjects and process the

Description

A text description of this Product2 record.

Name of the product family associated with this

Product2 object. Product families are configured as picklists in the Salesforce user interface. To obtain a list of valid values, your client application can call

DescribeSObjectResult for the values associated with the

Family

field.

Indicates whether this Product2 object is active (True) or not (False). Inactive Product2s are hidden in many areas in the Salesforce user interface. You can change the

IsActive

flag on a Product2 object as often as necessary.

Default name of this Product2 object.

Default product code for this Product2 object. The product code naming pattern is defined by your organization.

Schedule

Enabled Flags

Schedule Fields

The Product2 object has several fields that are only used for schedules (a.k.a. annuities).

The API supports two types of schedules on Product2 objects:

• quantity schedules

• revenue schedules

Schedules are available only for those organizations that have the Products and Schedules features enabled. If the organization does not have the Schedules feature, the schedule fields do

not appear in the DescribeSObjectResult

, and you cannot

OpportunityLineItem s can have a schedule of that type. These flags can be set via a

, or

update the fields.

CanUseRevenueSchedule

flags. A value of True for either flag indicates that the Product and any

values are used to create an OpportunityLineItemSchedule

update call.

Page 238

AppExchange API

Default

Schedule

Fields

The remaining Product2 schedule fields define default schedules for the object. Default schedule

when an OpportunityLineItem is

created for the Product.

The following table lists the default schedule fields and their valid values (all fields are also nillable).

Field

RevenueScheduleType

RevenueInstallmentPeriod

NumberOfRevenueInstallments

QuantityScheduleType

QuantityInstallmentPeriod

NumberOfQuantityInstallments

Valid Values

Divide, Repeat

Daily, Weekly, Monthly, Quarterly, Yearly

Integer between 1 to 150, inclusive.

Divide, Repeat

Daily, Weekly, Monthly, Quarterly, Yearly

Integer between 1 to 150, inclusive.

When you attempt to set the schedule fields via a

call, the API applies crossfield integrity checks. The integrity requirements are:

• If the schedule type is nil, then the installment period and number of installments must be nil.

• If the schedule type is set to any value, then the installment period and number of installments must be non-nil.

Any

update calls that fail these integrity checks are rejected with an error.

These default schedule fields, as well as CanUseQuantitySchedule and

CanUseRevenueSchedule

, are restricted picklist fields and are available only if the organization has the Schedules feature enabled:

Usage

Use Product2 objects to define the default product information for your organization. The

Product2 object is associated by reference with Pricebook2

objects via

objects.

The same product can be represented in different price books as price book entries. In fact, the same product can be represented multiple times (as separate

Use the Product2 object to query

objects) in the same price book with different prices and/or currencies. A Product can only have one price for a given currency within the same Pricebook. To be used in custom price books, all standard prices must be added as price book entries to the standard price book.

information about the products that have been configured for your organization. A common use of the Product2 object is to allow your client application to

obtain valid Product2 object IDs for use when configuring PricebookEntry objects via the API.

Your client application can

(custom, not standard), update

, create

, and

objects. You can also change the IsActive flag in create or

Pricebook2

update calls.

The Product2 object is defined only for those organizations that have Products enabled as a feature. If the organization does not have the Products feature, the Product2 object does not

appear in the describeGlobal

call, and you cannot use

describeSObjects or

query with the

Product object.

If you try to delete a product via the API but there is an opportunity that uses that product, the delete will not be successful. The workaround is to delete the product in the online user interface, which gives you an option to archive the product.

For a visual diagram of the relationships between

Schedule Objects on page 274 and

and other objects, see

Product and

How PriceBook2, Product2, and PricebookEntry Objects Are

Related on page 232.

Page 239

AppExchange API

Page 240

AppExchange API

Profile

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Usage

Use the Profile object to

query the set of currently configured user profiles in your organization.

Your client application can use Profile objects to obtain valid profile IDs for use when querying or modifying users through the API. Your client application can

, update , and

delete Profiles.

See Also

Represents a profile, which defines a set of permissions to perform different operations, such as querying, adding, updating, or deleting information.

Page 241

AppExchange API

QuantityForecast

A quantity-based forecast. The API also provides revenue-based forecasts (

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Closed

CommitComment

CommitOverride

DefaultRollupCommit

DefaultRollupUpside

InvalidationDate

ManagerChoiceCommit

Field Type

double double double dateTime

Description

A rollup of opportunities or opportunity line items that have closed in this period.

The comment entered when the owner edited his or her Commit total from the Adjusted Total link on the forecast edit page.

The owner's override of their own My Commit total.

The owner's standard Commit rollup, including their own opportunities and forecast-level overrides from subordinate users in the role hierarchy.

The owner's standard Best Case rollup, including their own opportunities and forecast-level overrides from subordinate users in the role hierarchy.

If not blank, indicates that the rollup numbers for

Forecast Override fields that represent calculated

(summarized) amounts may not be up to date.

The manager’s choice regarding the commit amount:

• DefaultRollup: Use the manager's default commit rollup for owner's forecast, which reflects the manager's opportunity forecast overrides.

• AcceptForecast (default selection): Accept the forecast owner's Adjusted Total commit amount, which may or may not be an override.

• ManagerManualOverride: Use the manager's manual override.

• OpportunityOnlyRollup: Use the opportunity rollup, including opportunity forecast overrides, but excluding any forecast-level (Adjusted Total) overrides.

Page 242

AppExchange API

Field Field Type

ManagerChoiceUpside

double double double double

ManagerClosed

ManagerCommitOverri de

ManagerDefaultRollu pCommit

ManagerDefaultRollu pUpside

ManagerId

ManagerOpportunityR ollupCommit

ManagerOpportunityR ollupUpside

ManagerPipeline

double double double

Description

The manager’s choice regarding the best case amount:

• DefaultRollup: Use the manager's default best case rollup for owner's forecast, which reflects the manager's opportunity forecast overrides.

• AcceptForecast (default selection): Accept the forecast owner's Adjusted Total best case amount, which may or may not be an override.

• ManagerManualOverride: Use the manager's manual override.

• OpportunityOnlyRollup: Use the opportunity rollup, including opportunity forecast overrides, but excluding any forecast-level (Adjusted Total) overrides.

The manager's closed total for the owner's forecast, including any opportunity or opportunity product overrides made by the manager.

The manager's manual override of the forecast owner's Commit total. Represents an option in the override pop-up window, which allows managers to choose how to roll up the forecast numbers of a direct report.

The manager's standard Commit rollup for the forecast owner. Represents an option in the override pop-up window, which allows managers to choose how to roll up the forecast numbers of a direct report.

The manager's standard Best Case rollup for the forecast owner. Represents an option in the override pop-up window, which allows managers to choose how to roll up the forecast numbers of a direct report.

ID of the direct manager of the user who owns this forecast. For information on IDs, see

The manager's view of the forecast owner's opportunity-level Commit rollup, ignoring all forecast overrides. Represents an option in the override pop-up window, which allows managers to choose how to roll up the forecast numbers of a direct report.

The manager's view of the forecast owner's opportunity-level Best Case rollup, ignoring all forecast overrides. Represents an option in the override pop-up window, which allows managers to choose how to roll up the forecast numbers of a direct report

The manager's pipeline total for the owner's forecast, including any opportunity or opportunity product overrides made by the manager.

Page 243

AppExchange API

Field

ManagerTerritoryId

ManagerUpsideOverri de

Field Type

double double double double

OpportunityRollupCl osed

OpportunityRollupCo mmit

OpportunityRollupPi peline

OpportunityRollupUp side

OwnerId

PeriodId

Pipeline

ProductFamily

Quota

TerritoryId

UpsideComment

UpsideOverride

Description

ID of the manager's UserRole

Territory

The manager's manual override of the forecast owner's Best Case total. Represents an option in the override pop-up window, which allows managers to choose how to roll up the forecast numbers of a direct report.

The owner's Closed total for his or her opportunities only.

The owner's Commit total for his or her opportunities only.

The owner's Pipeline total for his or her opportunities only.

The owner's Best Case total for his or her opportunities only.

ID of the

User who owns this forecast.

ID of the related Period

The total pipeline rollup from subordinates in the role hierarchy, including the owner's opportunities.

The value chosen in the Product Family picklist, which can be configured at Setup | Customize |

Products | Fields. This field is relevant if you have chosen “Use Product Families” as the Forecast Type at Setup | Customize | Forecast | Settings. If you are not forecasting by product family or if the forecast represents opportunities that are not associated with a product family, this field is blank.

The quota amount for the period.

ID of the forecast owner’s UserRole or

Territory .

The comment entered when the owner edited his or her Best Case total.

The owner's override of their My Best Case total.

Usage

This is read-only object specific to customizable forecasting.

Rollup fields always reflect opportunity and opportunity product overrides by the forecast owner or one of the forecast owner’s subordinates in the role hierarchy. In addition, the manager rollup fields include overrides by the forecast owner's direct manager in the role hierarchy.

Some of the rollup fields ignore forecast-level (Adjusted Total) overrides, but they never ignore opportunity forecast overrides that are visible to the owner or manager.

See Also

RevenueForecast on page 247

QuantityForecastHistory on page 245

Page 244

AppExchange API

QuantityForecastHistory

Historical information about a quantity-based forecasts that have been submitted (saved) in the

Salesforce user interface.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Closed

Commit

CommitComments

CommitOverridden

ForecastOverrideId

Pipeline

Quota

Upside

UpsideComments

UpsideOverridden

Field Type

Description

The closed amount of the forecast.

The commit amount of the forecast.

Comments about the commit value.

Indicates whether the commit value was overridden

(True) or not (False).

ID of the related forecast override. For information on IDs, see

QuantityForecast on page 242

The pipeline amount of the forecast.

The quota amount of the forecast.

The upside amount of the forecast.

Comments about the best case value.

Indicates whether the upside value was overridden

(True) or not (False).

Usage

This is a read-only object specific to customizable forecasting. When a user submits a quantitybased forecast in the Salesforce user interface, a row is added to this table. If the same forecast is ever resubmitted, additional rows are added. The CreatedDate of the history row reflects the day on which the forecast was submitted. For more information about customizable forecasts, see the online help.

See Also

RevenueForecastHistory on page 250

Page 245

AppExchange API

RecordType

Represents a record type.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

BusinessProcessId

Description

IsActive

Name

TableEnumOrIdName

SobjectType

Field

Type

Description

IDs, see ID Fields on page 136.

ID of an associated

BusinessProcess

. For information on

A text description of the RecordType. Can have up to 255 characters.

Indicates whether the RecordType is active (True) or not

(False). Only active RecordTypes can be used.

Name of the RecordType. Can have up to 80 characters.

(Replaced by SobjectType in version 7.0 and later.)

Object to which this RecordType applies. Valid values include “lead,” “contact,” “account,” and other objects that support RecordTypes. A particular RecordType can apply to only one type of object.

Available in version 7.0 and later. Object to which this

RecordType applies, including custom objects.

Usage

Use the

Profile . Your client application can invoke the

object to offer different

BusinessProcess

es and subsets of picklists values to different users based on their particular

describeSObjects and

query calls on RecordType objects. Record types are read-only in the API.

The following objects have a RecordTypeId field: Account

. Client applications can set this field in create or

can retrieve the list of valid record type IDs for a given object by calling query on the

calls on these objects, specifying a valid record type ID associated with these objects. A client application

object. For more information, see RecordTypeId Fields on page 140.

Record Type Objects on page 274

Page 246

AppExchange API

RevenueForecast

A revenue-based forecast. The API also provides quantity-based forecasts; see

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Closed

CommitComment

CommitOverride

currency picklist

CurrencyIsoCode

DefaultRollupCommit

DefaultRollupUpside

InvalidationDate

ManagerChoiceCommit

Field Type

Description

A rollup of opportunities or opportunity line items that have closed in this period.

The comment entered when the owner edited his or her Commit total from the Adjusted Total link on the forecast edit page.

The owner's override of their own My Commit total.

The currency code for monetary amounts.

The owner's standard Commit rollup, including their own opportunities and forecast-level overrides from subordinate users in the role hierarchy.

The owner's standard Best Case rollup, including their own opportunities and forecast-level overrides from subordinate users in the role hierarchy.

If not blank, indicates that the rollup numbers for

Forecast Override fields that represent calculated

(summarized) amounts may not be up to date.

The manager’s choice for the commit amount:

• DefaultRollup: Use the manager's default commit rollup for owner's forecast, which reflects the manager's opportunity forecast overrides.

• AcceptForecast (default selection): Accept the forecast owner's Adjusted Total commit amount, which may or may not be an override.

• ManagerManualOverride: Use the manager's manual override.

• OpportunityOnlyRollup: Use the opportunity rollup, including opportunity forecast overrides, but excluding any forecast-level (Adjusted Total) overrides.

Page 247

AppExchange API

Field Field Type

ManagerChoiceUpside

currency currency currency currency reference currency currency currency

ManagerClosed

ManagerCommitOverri de

ManagerDefaultRollu pCommit

ManagerDefaultRollu pUpside

ManagerId

ManagerOpportunityR ollupCommit

ManagerOpportunityR ollupUpside

ManagerPipeline

Description

The manager’s choice regarding the best case amount:

• DefaultRollup: Use the manager's default best case rollup for owner's forecast, which reflects the manager's opportunity forecast overrides.

• AcceptForecast (default selection): Accept the forecast owner's Adjusted Total best case amount, which may or may not be an override.

• ManagerManualOverride: Use the manager's manual override.

• OpportunityOnlyRollup: Use the opportunity rollup, including opportunity forecast overrides, but excluding any forecast-level (Adjusted Total) overrides.

The manager's closed total for the owner's forecast, including any opportunity or opportunity product overrides made by the manager.

ID of the direct manager of the user who owns this forecast. For information on IDs, see

currency currency currency currency reference reference currency picklist currency reference

The manager's pipeline total for the owner's forecast, including any opportunity or opportunity product overrides made by the manager.

Page 248

AppExchange API

Field

ManagerTerritoryId

ManagerUpsideOverri de

Field Type

reference currency

OpportunityRollupCl osed

OpportunityRollupCo mmit

OpportunityRollupPi peline

OpportunityRollupUp side

OwnerId

PeriodId

Pipeline

ProductFamily

Quota

TerritoryId

UpsideComment

UpsideOverride

ID of the manager's UserRole

Description

Territory

The owner's Closed total for his or her opportunities.

The owner's Commit total for his or her opportunities.

The owner's Pipeline total for his or her opportunities.

The owner's Best Case total for his or her opportunities.

ID of the

User who owns this forecast.

ID of the related Period

The total pipeline rollup from subordinates in the role hierarchy, including the owner's opportunities.

The value chosen in the Product Family picklist, configured at Setup | Customize | Products |

Fields. This field is relevant if you have chosen “Use

Product Families” as the Forecast Type at Setup |

Customize | Forecast | Settings. If you are not forecasting by product family or if the forecast represents opportunities that are not associated with a product family, then this field is blank.

The quota amount for the period.

ID of the forecast owner’s UserRole or

Territory .

The comment entered when the owner edited his or her Best Case total.

The owner's override of their My Best Case total.

Usage

This is a read-only object specific to customizable forecasting.

Rollup fields always reflect opportunity and opportunity product overrides by the forecast owner or one of the forecast owner’s subordinates in the role hierarchy. In addition, manager rollup fields include overrides by the forecast owner's direct manager in the role hierarchy.

Some of the rollup fields ignore forecast-level (Adjusted Total) overrides, but they never ignore opportunity forecast overrides that are visible to the owner or manager.

See Also

QuantityForecast on page 242

RevenueForecastHistory on page 250

Page 249

AppExchange API

RevenueForecastHistory

Historical information about revenue-based forecasts that have been submitted (saved) in the

Salesforce user interface.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Closed

Commit

CommitComments

CommitOverridden

CurrencyIsoCode

ForecastOverrideId

Pipeline

Quota

Upside

UpsideComments

UpsideOverridden

Field Type

currency currency

picklist reference currency currency currency

Description

The closed amount of the forecast.

The commit amount of the forecast.

Comments about the commit value.

Indicates whether the commit value was overridden

(True) or not (False).

The currency code for monetary amounts.

ID of the related forecast override. For information on IDs, see

QuantityForecastHistory on page 245

The pipeline amount of the forecast.

The quota amount of the forecast.

The best case amount of the forecast.

Comments about the upside value.

Indicates whether the upside value was overridden

(True) or not (False).

Usage

This is a read-only object specific to customizable forecasting. When a user submits a revenuebased forecast in the Salesforce user interface, a row is added to this table. If the same forecast is ever resubmitted, additional rows are added. The CreatedDate of the history row reflects the day on which the forecast was submitted. For more information about customizable forecasts, see the online help.

See Also

RevenueForecast on page 247

calls create , but not when calling

Page 250

AppExchange API

Scontrol

Represents a custom s-control, which is custom content that is hosted by the system but executed by client applications.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Binary

BodyLength

Description

Filename

HtmlWrapper

Name

Field Type Description

base64Binary

Binary content of this custom s-control, such as an ActiveX control or a Java archive. Up to 5 MB.

Can be specified when your client application

update .

int string string

The length of the custom s-control.

Text description of the custom s-control.

An uploaded object to display when the custom s-control is added to a custom link. Can be a

Java applet, an ActiveX control, or any other type of desired content.

permission is required to create or

HTML page that will be delivered when the user views this custom s-control. This HTML page can be the entire content of the custom s-control, or it can reference the binary. Up to 1,048,576 characters.

Name of this custom s-control.

Usage

Use custom s-control objects to manage custom content on the Web service that is executed by client applications. All users can view custom s-control objects, but the “Customize Application”

update custom s-control objects. Your organization must be

using Enterprise or Unlimited Edition and be enabled for custom s-controls.

Page 251

AppExchange API

Field

ContactID

Email

FirstName

IsActive

LanguageLocaleKey

LastLoginDate

LastName

LocaleSidKey

SelfServiceUser

You can use the API to manage Self-Service users. For details on how to implement Self-Service users, download the Self-Service Implementation Guide. There are also tip sheets and online help topics to explain how to use Self-Service. Click Help & Training in the Salesforce user interface to access these resources.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Type

Description

Required. All Self-Service users must be associated

with a Contact

. The contact’s email should match the SelfServiceUser email. The contact must have a value in the AccountID field or an error occurs.

for the Contact to which the SelfServiceUser is

Required. Make this the same as the email address

associated. Password resets and other system communication will be sent to this email address.

Required. This is a restricted picklist field. It is the primary language for the user. All on-screen text in the Self-Service portal is displayed in this language.

The date and time when the SelfServiceUser last logged in.

First name of the SelfServiceUser.

Indicates whether the SelfServiceUser is allowed to log in to the Self-Service portal (True) or not

(False). Note that there is no way to delete a

SelfServiceUser. They can only be marked as inactive.

Required. Last name of the SelfServiceUser.

Required. This is a restricted picklist field. The value of the Locale field affects the formatting and parsing of values, especially numeric values, in the

Self-Service portal. Locale field values are twoletter codes that indicate language and sometimes language and country. The codes are based on ISO standards.

Page 252

AppExchange API

Field

TimeZoneSidKey

SuperUser

Username

Field

Type

SelfServiceUser passwords using the setPassword

Description

Required. This is a restricted picklist field. The time zone of a SelfServiceUser affects the offset used when displaying or entering times in the Self-

Service portal.

Indicates whether the SelfServiceUser is a super user (True) or not (False).

Required. This contains the name that a

SelfServiceUser enters to log into the Self-Service portal. Username must be in the form of an email address. It must also be unique in your organization. If you try to create or update a

SelfServiceUser with a duplicate username, the operation is rejected and an error is returned.

Usage

A note about passwords: for security reasons, you cannot query SelfServiceUser passwords via the API or the Salesforce user interface. However, the API allows you to set and reset

and

A note about notification emails: SelfServiceUser

calls.

s created from the API do not cause a notification email to be sent. If you want to notify the user, you must send them an email after creating the user.

See Also

Contact on page 174

User on page 262

Page 253

AppExchange API

Solution

A detailed description of a customer issue and the resolution of that issue.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsPublished

IsPublishedInPublicKb

IsReviewed

OwnerId

RecordTypeId

SolutionName

SolutionNote

SolutionNumber

Status

Field

Type

Description

Indicates whether the Solution has been published.

A Solution’s published state does not affect how it can be used, or whether you can

delete it. For more information on publishing

, or

Solutions, see the online help.

Indicates whether the Solution has been published in the Public Knowledge Base (True) or not (False).

ID of the User who owns the Solution record. For

information on IDs, see

ID of the RecordType to which the Solution is

associated.

Required. If a client application creates a new

Solution and a value for this field is unspecified, then the Web service automatically specifies a hyphen (-), the default value for this field.

Indicates whether the Solution has been reviewed

(True) or not (False). This flag can only be set indirectly via the Status picklist. Each predefined

Status

value implies an IsReviewed flag value.

The details of the Solution record. Can have up to

32,000 characters.

An identifying number that is assigned automatically when a Solution is created. It cannot be set directly, and it cannot be modified after the

Solution is created.

picklist, a client application can invoke the query

The status of the Solution. Directly controls the

IsReviewed

flag. To obtain the status values in the

call on the SolutionStatus

object.

Usage

Use

Solution objects to manage your organization’s solution knowledge base. Client applications

, and

Attachment s associated with a solution via the API.

Page 254

AppExchange API

See Also

CategoryData on page 172

CategoryNode on page 173

Represents the status of a Solution , such as Draft, Reviewed, and so on.

Page 255

AppExchange API

SolutionStatus

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsDefault

IsReviewed

MasterLabel

SortOrder

Field Type

reviewed Solution (True) or not (False). Multiple solution status values can represent a reviewed Solution

Description

Indicates whether this is the default solution status value (True) or not (False) in the picklist. Only one value can be the default value.

Indicates whether this solution status value represents a

Master label for this solution status value. This display value is the internal label that does not get translated.

Number used to sort this value in the solution status picklist. These numbers are not guaranteed to be sequential, as some previous solution status values might have been deleted.

Usage

The

SolutionStatus

object represents a value in the solution status picklist. The solution status picklist provides additional information about the status of a

query call on the SolutionStatus object to retrieve the set of values in the solution status picklist,

, such as whether a given status value represents a reviewed or unreviewed solution. Your client application can invoke the

and then use that information while processing Solution objects to determine more information

about a given solution. For example, the application could test whether a given case has been reviewed or not based on its Status value and the value of the IsReviewed property in the associated SolutionStatus object.

The SolutionStatus object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on SolutionStatus objects. You

cannot create ,

, or delete a SolutionStatus object via the API.

See Also

Page 256

AppExchange API

Task

A business activity such as making a phone call or other “to-do” items. In the Salesforce user interface, Task and

reference picklist picklist combobox reference reference

records are collectively referred to as activities.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountId

ActivityDate

Description

IsClosed

OwnerId

Priority

Status

Subject

WhatId

WhoId

Field Type

Description

ID of the associated Account . For information on IDs,

see

ID of the User who owns the Task record. For

The due date of the task. This field has a timestamp that is always set to midnight in the GMT/UTC time zone. The timestamp is not relevant; do not attempt to alter it in order to accommodate time zone differences.

Text description of the task.

Indicates whether the task was completed (True) or not

(False). Is only set indirectly via the Status picklist.

Indicates the importance or urgency of a task, such as high, normal, or low.

The current status of the task, such as In Progress or

Completed. Each predefined Status field implies a value for the IsClosed flag. To obtain picklist values, a client

call on the TaskStatus

object.

The subject line of the task, such as “Call” or “Send

Quote.”

ID of a related

, or custom object.

ID of a related

Lead . If the WhoId refers to a

lead, then the WhatId field must be empty.

Usage

Archived Task

objects are not accessible via the API. See Archived Activities on page 189.

Page 257

AppExchange API

TaskPriority

Represents the importance or urgency of a Task

, such as High, Normal, or Low.

Supported API Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsDefault

IsHighPriority

MasterLabel

SortOrder

Field Type

TaskPriority object represents a value in the task priority picklist. The task priority picklist

Description

Indicates whether this is the default task priority value

(True) or not (False) in the picklist. Only one value in the picklist can be the default value.

Indicates whether this task priority value represents a high priority

Task

(True) or not (False). Multiple task priority values can represent a high-priority

Task .

Master label for this task priority value. Can have up to

255 characters. This display value is the internal label that does not get translated.

Number used to sort this value in the task priority picklist. These numbers are not guaranteed to be sequential, as some previous task priority values might have been deleted.

Usage

The

provides additional information about the importance of a

Task , such as whether a given priority

value represents a high priority. Your client application can invoke the

information while processing Task objects to determine more information about a given task. For

call on the

TaskPriority object to retrieve the set of values in the task priority picklist, and then use that

example, the application could test whether a given task is high priority based on its Priority value and the value of the IsHighPriority property in the associated TaskPriority object.

The TaskPriority object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on TaskPriority objects.

Page 258

AppExchange API

TaskStatus

Represents the status of a Task , such as Not started, Completed, or Closed.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsClosed

IsDefault

MasterLabel

SortOrder

Field Type

closed Task (True) or not (False). Multiple task status values can represent a closed Task .

Description

Indicates whether this task status value represents a

Indicates whether this is the default task status value

(True) or not (False) in the picklist.

Master label for this task status value. Can have up to

255 characters. This display value is the internal label that does not get translated.

Number used to sort this value in the task status picklist.

These numbers are not guaranteed to be sequential, as some previous task status values might have been deleted.

Usage

The

TaskStatus

object represents a value in the task status picklist. The task status picklist provides additional information about the status of a

Task , such as whether a given status value

represents an open or closed task. Your client application can invoke the query

call on the

TaskStatus object to retrieve the set of values in the task status picklist, and then use that

information while processing Task objects to determine more information about a given task. For

example, the application could test whether a given task is open or closed based on its Status value and the value of the IsClosed property in the associated TaskStatus object.

The TaskStatus object is read-only via the API. With sufficient permissions, your client

and describeSObjects calls on TaskStatus objects.

Page 259

AppExchange API

Territory

A flexible collection of accounts and users where the users have at least read access to the accounts, regardless of who owns the accounts. Only available if territory management has been enabled for your organization. For more information, see the “What is Territory Management?” topic in the online help.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

AccountAccessLevel

CaseAccessLevel

Description

ForecastUserId

Name

OpportunityAccessLe vel

ParentTerritoryID

RestrictOppTransfer

Field Type

Description

Account access level granted to users assigned to this territory.

Case access level granted to users assigned to this territory.

A description of the territory that is 1,000 characters or less.

ID of the “forecast user,” who is the user to whom forecasts from this territory’s child territories roll up.

For information on IDs, see

AccountTerritoryAssignmentRuleItem on page 152

A name for the territory that is 40 characters or less.

Opportunity access level granted to users assigned to this territory.

Territory immediately above this territory in the territory hierarchy.

Indicates whether the opportunities associated with this territory are kept within the bounds of this territory and this territory’s children when account assignment rules are run (True), or if opportunities associated with this territory can be assigned to other nodes of the territory hierarchy when account assignment rules are run (False).

Usage

Use the Territory

object to query

your organization’s territory hierarchy. Use it in your client application to obtain valid Territory IDs when querying or modifying objects associated with territories.

UserTerritory on page 267

Page 260

AppExchange API

string string string string

Page 261

AppExchange API

User

Represents a user in your organization.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Alias

City

CompanyName

Country

DefaultDivision

Department

Division

Email

EmailEncodingKey

EmployeeNumber

Fax

FirstName

ForecastEnabled

IsActive

LanguageLocaleKey

LastLoginDate

LastName

Field Type

Description

The user’s alias. For example, “jsmith.”

The city associated with the user.

The name of the user’s company.

The country associated with the user

The user’s default division. Only applicable if divisions are enabled for your organization. For more information, see the online help.

The company department associated with the user.

The user’s working division. Only applicable if divisions are enabled for your organization. For more information, see the online help.

The user’s email address.

The email encoding for the user, such as “ISO-8859-

1” or “UTF-8”.

The user’s employee number.

The user’s fax number.

The user’s first name.

Indicates whether the user is enabled as a forecast user (True) or not (False) in customizable forecasting. Forecast users see forecast rollups from users below them in the forecast hierarchy.

Indicates whether the user has access to log in

(True) or not (False). You can modify a User's active status from the Salesforce user interface or via the

API.

The user’s language, such as “French” or “Chinese

(Traditional).”

The date and time when the user last logged in.

The user’s last name.

Page 262

AppExchange API

Field

LocaleSidKey

MobilePhone

OfflinePdaTrialExpi rationDate

OfflineTrialExpirat ionDate

Phone

Postal Code

ProfileId

ReceivesAdminInfoEm ails

ReceiveInfoEmails

State

Street

TimeZoneSidKey

Title

Field Type

Description

The Locale field is a restricted picklist field. The value of the Locale field affects formatting and parsing of values, especially numeric values, in the user interface. It does not affect the API.

The Locale field values are named according to the language, and country if necessary, using two-letter

ISO codes. The set of names is based on the ISO standard. It can often be more convenient to manually set a User's Locale in the user interface, and then use that value for inserting or updating other Users via the API.

The user’s mobile or cellular phone number.

The date and time when the user’s Sales Anywhere trial expires. Sales Anywhere was formerly known as Offline PDA Edition.

The date and time when the user’s Offline Edition trial expires.

The user’s phone number.

The user’s postal or ZIP code.

ID of the user’s Profile . For information on IDs, see

Indicates whether the user receives emails for administrators from salesforce.com (True) or not

(False).

Indicates whether the user receives informational emails from salesforce.com (True) or not (False).

The state associated with the user.

The street address associated with the user.

The Timezone field is a restricted picklist field. A

User's time zone affects the offset used when displaying or entering times in the user interface.

However, the API does not use a User's time zone when querying or setting values.

The Timezone field values are named using region and key city, according to ISO standards. It can often be more convenient to manually set a User's time zone in the user interface, and then use that value for inserting or updating other Users via the

API.

The user’s business title, such as “Vice President.”

Page 263

AppExchange API

Field

Username

UserPermissionsAvan tgoUser

UserPermissionsMark etingUser

UserPermissionsOffl ineUser

UserPermissionsWire lssUser

UserRoleId

WirelessEmail

Field Type

boolean boolean boolean boolean

reference email

Description

The Username field contains the name that a User enters to log into the API or the Salesforce user interface. The Username must be in the form of an email address. It must also be unique across all

Salesforce instances. If you try to

ID of the user’s UserRole

update a

User with a duplicate Username, the operation is rejected.

Each inserted User also counts as a license in

Salesforce. Every organization has a maximum number of licenses. If you attempt to exceed the maximum number of licenses by inserting Users, the

create call is rejected.

Indicates whether the user is enabled to use the

Sales Anywhere product (True) or not (False).

Indicates whether the user is enabled to manage campaigns in the online application (True) or not

(False).

Indicates whether the user is enabled to use Offline

Edition (True) or not (False).

Indicates whether the user is enabled to use

Wireless Edition (True) or not (False).

The email address associated with the user’s wireless service.

Usage

Use the User object to query information about users and to provision and modify users in your organization. Unlike with other objects, the records in the User table represent actual users—not data owned by users.

All Users have access to use query or

with User objects. To create or

update a

User object, you must log in with “Manage Users” permission.

Disabling Users

You cannot delete Users in the Salesforce user interface or the API. To disable a User, deactivate

that User in the Salesforce user interface. Because Users can never be deleted, we recommend that you exercise caution when creating them.

Passwords

For security reasons, you cannot query Users' passwords via the API or the Salesforce user interface. However, the API allows you to set and “reset” Users’ passwords using the

setPassword and

getUserInfo on page 126

calls.

The password lockout status and the ability to reset a User's locked-out status is not available via the API. You must check and reset a User's password lockout status using the Salesforce user interface.

See Also

Page 264

AppExchange API

UserRole

Represents a user role in your organization.

Note

This object was called “Role” in previous versions of the API documentation.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Usage

Use the UserRole object to

All Users have access to invoke query

the set of currently configured user roles in your organization.

Use it in your client application to obtain valid UserRole IDs to use when querying or modifying a

User .

or describeSObjects with the UserRole object. If your client

application logs in with the “Modify All Data” permission, it can

Roles.

Page 265

AppExchange API

UserTeamMember

Represents a single User on the default sales team of another user.

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

OwnerId

UserId

OpportunityAccessLevel

TeamMemberRole

Field

Type

Description

ID of the User who owns the default sales team.

This field cannot be updated. For information on

IDs, see

ID of the User who is a member of the default

sales team. This field cannot be updated.

Level of access that the team member has to opportunities for which the User has added his or her default sales team. One of the following values:

• None—User cannot access the

• Read—User can only view the Opportunity.

• Edit—User can view or edit the Opportunity.

• All—User can view, edit,

, and share the

Opportunity with other Users. This value is not

valid for create

and update calls.

This field must be set to an access level that is higher than the organization’s default access level for opportunities.

create call updates any modified fields and returns the existing record.

Role that the team member has on opportunities for which the User has added his or her default sales team. The valid values are set by the organization’s administrator in the Sales Team

Roles picklist.

Usage

If you attempt to insert a UserTeamMember that matches an existing UserTeamMember record, the

Users can set up their default sales team to include the other Users that typically work with them on opportunities. The UserTeamMember object is available only in organizations that have enabled the team selling functionality.

See Also

OpportunityTeamMember on page 226

Page 266

AppExchange API

UserTerritory

An individual

who has been assigned to a Territory . Only available if territory management

has been enabled for your organization. For more information, see the “What is Territory

Management?” topic in the online help.

Supported Calls

Fields

For a complete list of fields on this object, see the WSDL file for your organization and the

Salesforce online help.

Field

IsActive

TerritoryID

UserId

Field Type

Territory to which the user has been

Description

Indicates whether the user is active in the given territory (True), or inactive in the given territory

(False). Users who are active in a territory were explicitly assigned to the territory and can have open opportunities, closed opportunities, or no opportunities associated with that territory. Users who are inactive in a territory were not explicitly assigned to the territory, but own an open or closed opportunity that is associated with the territory. For example, a user may have been transferred out of a territory, but still own opportunities in his or her old territory.

ID of the

assigned. For information on IDs, see

AccountTerritoryAssignmentRule on page 151

ID of the user.

Usage

Note that if a user is inactive in a territory and the opportunities they own that are associated with the territory are all closed, then the user is not returned.

See Also

Territory on page 260

AccountTerritoryAssignmentRuleItem on page 152

Represents a custom link to a URL or Scontrol .

Page 267

AppExchange API

WebLink

Supported Calls

Fields

For a complete list of fields in this object, see the WSDL file for your organization and the

Salesforce online help.

Field

Encoding Key

HasMenuBar

HasScrollbars

HasToolbar

Height

IsResizable

LinkType

Name

OpenType

PageEnumOrId

Field

Type

Description

Encoding of parameters on the URL link.

Indicates whether the popup window shows a menubar (True) or not (False).

Indicates whether the popup window shows scroll bars (True) or not (False).

Indicates whether the popup window shows browser toolbars (True) or not (False). Toolbars normally contain navigation buttons like Back,

Forward, and Print.

Height of the popup, in pixels.

Indicates whether users are allowed to resize the popup window (True) or not (False).

Type of link (Scontrol or URL).

Name to display on page.

How the custom link opens when clicked in a browser—NewWindow, Sidebar, or NoSidebar.

(Replaced in version 7.0 and later by

PageOrSobjectType

Page on which to display the custom link. One of the following values:

• AccountDetail

• CampaignDetail

• CaseDetail

• ContactDetail

• ContractDetail

• EventDetail

• LeadDetail

• OpportunityDetail

• Product2Detail

• SolutionDetail

• TaskDetail

• UserDetail

Page 268

AppExchange API

Field

PageOrSObjectType

Position

ScontrolId

ShowsLocation

ShowsStatus

Url

Field

Type

Description

picklist picklist

For standard objects, the name of the page on which to display the custom link. For custom objects, the name of the sobject.

Location on the screen where the popup should open—TopLeft, FullScreen, or None.

ID of the custom s-control object ( Scontrol ) to link

to. Can include Salesforce fields as tokens within the custom s-control object. For information on

IDs, see

Indicates whether the popup window shows the browser’s address bar containing the URL (True) or not (False).

Show the status bar at the bottom of the browser.

Document, Note, and Attachment Objects

URL of the page to link to. Can include Salesforce fields as tokens within the URL. Can have up to

4,000 characters.

Width of the popup, in pixels.

Width

Usage

Use the WebLink object to programmatically manage custom links, which allow client applications to integrate Salesforce data with external URLs, an organization’s intranet, or other back-end office systems. To create a custom link, the client application must be logged in with the “Customize Application” permission. A WebLink can point to:

• An external URL, such as www.google.com or your company's intranet.

• A custom s-control, such as a Java applet or Active-X control.

Custom links can include Salesforce fields as tokens within the URL or custom s-control.

Scontrol on page 251

Page 269

AppExchange API

HAPTER

D a t a M o d e l

This chapter provides entity relationship diagrams (ERDs) for standard Salesforce objects. It includes the following sections:

•

Sales Objects

•

Task and Event Objects

•

Support Objects

•

•

User and Profile Objects

•

Record Type Objects

•

Product and Schedule Objects

•

Sharing and Team Selling Objects

•

Customizable Forecasting Objects

Page 270

AppExchange API

S

ALES

O

BJECTS

Page 271

AppExchange API

T

ASK AND

E

VENT

O

BJECTS

S

UPPORT

O

BJECTS

Page 272

AppExchange API

D

OCUMENT

, N

OTE

,

AND

A

TTACHMENT

O

BJECTS

U

SER AND

P

ROFILE

O

BJECTS

Page 273

AppExchange API

R

ECORD

T

YPE

O

BJECTS

P

RODUCT AND

S

CHEDULE

O

BJECTS

Page 274

AppExchange API

S

HARING AND

T

EAM

S

ELLING

O

BJECTS

Page 275

AppExchange API

C

USTOMIZABLE

F

ORECASTING

O

BJECTS

Page 276

AppExchange API

HAPTER

U s i n g t h e P a r t n e r W S D L

This topic describes the partner WSDL:

•

Introducing the Partner WSDL

•

Objects, Fields, and Field Data and the Partner WSDL

•

Queries and the Partner WSDL

•

Namespaces in the Partner WSDL

•

User Interface Themes

•

Examples

I

NTRODUCING THE

P

ARTNER

WSDL

The API provides two WSDLs to choose from:

• Enterprise Web services WSDL—Used by enterprise developers to build client applications for a single Salesforce organization.

• Partner Web services WSDL—Used for client applications that are metadata driven and dynamic in nature. It is particularly—but not exclusively—useful to salesforce.com partners who are building client applications for multiple organizations. As a loosely typed representation of the Salesforce object model, it can be used to access data within any organization. It is more flexible, although not as easy to use, as its enterprise counterpart.

This topic introduces the partner Web services WSDL and describes how it differs from the enterprise Web services WSDL. In general, the enterprise Web services WSDL is more straightforward to use, while the partner Web services WSDL is more flexible and dynamically adaptable to different organizations, allowing you to write a single application that can be used for multiple users and multiple organizations.

Obtaining the Partner WSDL File

To use the Partner WSDL, download a copy of the file using either of the following methods:

• obtain it from your organization’s Salesforce administrator, or

• generate in the Setup | Integrate | AppExchange API area of the Salesforce user interface according to the instructions in

Step 2: Generate or Obtain the Web Service WSDL on page 4.

While the enterprise.wsdl file needs to be regenerated whenever custom fields or custom objects are added to an organization’s Salesforce information, the Partner WSDL file partner.wsdl

remains the same regardless of underlying changes in the organization’s

Salesforce data.

Page 277

AppExchange API

API Calls and the Partner WSDL

The Partner WSDL file defines exactly the same API calls found in the enterprise.wsdl file.

A client application using the Partner WSDL will likely use the following API calls to determine an organization’s metadata:

Task / Call

Description

Retrieves a list of available objects for your organization’s data.

Retrieves metadata about page layouts for the specified object type.

Describes metadata (field list and object properties) for the specified object.

Superseded by describeSObjects

Use describeSObject to obtain metadata for a given object. You can first call describeGlobal to retrieve a list of all objects for your organization, then iterate through the list and use describeSObject to obtain metadata about individual objects.

In the Salesforce user interface, users have access to standard apps (and may also have access to custom apps) as listed in the

AppExchange app menu at the top of the page. Selecting a standard app or custom app in the UI allows the user to switch between the listed apps at any time.

To explore an organization’s metadata, a client application can:

1. Call

describeGlobal to obtain a list of available objects.

2. In the returned

DescribeGlobalResult

, retrieve an array of sObject

s ( types field).

3. Iterate through each sObject

in the array, calling describeSObject to retrieve a list of fields

and other properties for the

in the returned DescribeSObjectResult .

O

BJECTS

, F

IELDS

,

AND

F

IELD

D

ATA AND THE

P

ARTNER

WSDL

While the enterprise.wsdl file defines all of the specific objects (such as Account

, Contact

, and

other objects described in API Objects on page 132) in a Salesforce organization, the Partner

WSDL file defines a single, generic object (

sObject ) that represents all of the objects. For a

particular object, its type is defined in the name field in the returned DescribeSObjectResult .

With the Partner WSDL, your client application code handles fields as arrays of name-value pairs that represent the field data. When referring to the names of individual fields, use the value in its name

field of the

type in the DescribeSObjectResult .

Languages vary in the way they handle name-value pairs and map typed values to the primitive

XML data types defined in SOAP messages. With the Enterprise WSDL, the mapping is handled implicitly. With the Partner WSDL, however, you need to manage values and data types when building client applications. When specifying the value of a particular field, be sure to use a value that is valid for the field (range, format, and data type). Make sure that you understand the mapping between data types in your programming language with XML primitive data types (one

of the values in the SOAPType field of the Field

type in the DescribeSObjectResult

Q

UERIES AND THE

P

ARTNER

WSDL

When using the

However, in the QueryResult

call with the Partner WSDL, consider the following guidelines:

• The

queryString

parameter is case-insensitive. The AppExchange Web service will accept field names in the fieldList using any combination of uppercase and lowercase letters.

, the case of field names (both predefined and custom fields)

Page 278

AppExchange API

will match exactly the value in the name field of the Field

type in the

QueryResult is determined by

It is recommended that you use the proper case when specifying fields in the fieldList.

• For the Partner Web services API, the ordering of fields in the

the field order in the fieldList, not the field order in the WSDL file.

• The fieldList cannot contain duplicate field names. For example:

• Invalid (returns an error): "select firstname, lastname, firstname from User"

• Valid: "select firstname, lastname from User"

•

The QueryResult

always contains all of the fields specified in the fieldList, even if some of the fields contain no data (null). Although SOAP allows you to omit fields that contain no values in the result set, the API always returns an array containing all fields.

N

AMESPACES IN THE

P

ARTNER

WSDL

In XML, every tag has a defined namespace. In the enterprise.wsdl, namespaces are handled implicitly. When using API calls with the Partner WSDL, however, you need to explicitly specify the correct namespaces for API calls, objects, and fields, and faults. This rule applies to predefined and custom objects and fields.

For

API Calls sObjects

Fields

Faults

Namespace

urn:partner.soap.sforce.com

urn:sobject.partner.soap.sforce.com

urn:fault.partner.soap.sforce.com

U

SER

I

NTERFACE

T

HEMES

Starting with the Winter ’06 release, the online application supports multiple user interface themes. Currently there are two user interface themes, “Salesforce” and “Salesforce Classic.”

The

GetUserInfoResult object, which includes the userUiSkin

call returns a

property. This property informs you of the user’s current user interface theme.

Stylesheets are available so partners can mimic the look and feel of the online application. For details, sample pages, and a style guide, go to http://www.salesforce.com/developer/technotes.jsp?tn=TN-16 .

E

XAMPLES

This section provides the following code samples in Java and C#:

•

•

•

•

Page 279

AppExchange API

Sample query Calls

The following Java and C# examples show using the query

call for the Partner WSDL.

Java Example

private void querySample() {

QueryResult qr = null;

QueryOptions qo = new QueryOptions();

qo.setBatchSize(new Integer(250));

binding.setHeader(new

SforceServiceLocator().getServiceName().getNamespaceURI(), "QueryOptions", qo);

try {

qr = binding.query("select Id, Website, Name from Account

where Name = 'Golden Straw'");

if (qr.getSize() != 0) {

SObject account = qr.getRecords()[0];

System.out.println("Retrieved " + new Integer(qr.getSize()).toString() +

" account(s) using Name = 'Golden Straw', ID = " +

account.getId() + ", website = " +

account.get_any()[1].getValue());

}

qr = binding.query("select FirstName, LastName, Id from Contact");

boolean bContinue = true;

int loopCount = 0;

while (bContinue) {

System.out.println("Results set " + new Integer(loopCount++).toString()

+ " - ");

// process the query results

for (int i = 0; i < qr.getRecords().length; i++) {

SObject con = qr.getRecords()[i];

org.apache.axis.message.MessageElement[] fields = con.get_any();

String fName = fields[0].getValue();

String lName = fields[1].getValue();

if (fName == null) {

System.out.println("Contact " + (i + 1) + ": " + lName);

}

else {

System.out.println("Contact " + (i + 1) + ": " + fName + " " + lName);

}

// handle the loop + 1 problem by checking to see if the most recent queryResult

if (qr.isDone()) {

bContinue = false;

}

else {

qr = binding.queryMore(qr.getQueryLocator());

}

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

return;

}

System.out.println("\nQuery sample done.");

}

Page 280

AppExchange API

C# Example

private void querySample()

{

QueryResult qr = null;

binding.QueryOptionsValue = new sforce.QueryOptions();

binding.QueryOptionsValue.batchSize = 250;

binding.QueryOptionsValue.batchSizeSpecified = true;

qr = binding.query("select FirstName, LastName from Contact");

bool bContinue = true;

int loopCounter = 0;

while (bContinue)

{

Console.WriteLine("\nResults Set " + Convert.ToString(loopCounter++) + " - ");

//process the query results

for (int i=0;i<qr.records.Length;i++)

{

sforce.sObject con = qr.records[i];

string fName = con.Any[0].InnerText;

string lName = con.Any[1].InnerText;

if (fName == null)

Console.WriteLine("Contact " + (i + 1) + ": " + lName);

else

Console.WriteLine("Contact " + (i + 1) + ": " + fName + " " + lName);

}

//handle the loop + 1 problem by checking to see if the most recent queryResult

if (qr.done)

bContinue = false;

else

qr = binding.queryMore(qr.queryLocator);

}

Console.WriteLine("\nQuery succesfully executed.");

Console.Write("\nHit return to continue...");

Console.ReadLine();

}

Sample search Call

The following Java and C# examples show using the search

call for the Partner API.

Java Example

private void searchSample()

{

SearchResult sr = null;

QueryResult qr = null;

try {

sr = binding.search("find {4159017000} in phone fields returning " +

" contact(id, phone, firstname, lastname), " +

" lead(id, phone, firstname, lastname), " +

" account(id, phone, name)");

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

return;

}

SearchRecord[] records = sr.getSearchRecords();

Page 281

AppExchange API

Vector contacts = new Vector();

Vector leads = new Vector();

Vector accounts = new Vector();

if (records != null && records.length > 0) {

for (int i=0;i<records.length;i++){

SObject record = records[i].getRecord();

if (record.getType().toLowerCase().equals("contact")) {

contacts.add(record);

} else if (record.getType().toLowerCase().equals("lead")){

leads.add(record);

} else if (record.getType().toLowerCase().equals("account")) {

accounts.add(record);

}

if (contacts.size() > 0) {

System.out.println("Found " + new Integer(contacts.size()).toString() +

" contacts:");

for (int i=0;i<contacts.size();i++){

SObject c = (SObject)contacts.get(i);

System.out.println(c.getId() + " - " +

c.get_any()[1].getValue() + " " +

c.get_any()[2].getValue() + " - " + c.get_any()[0].getValue());

}

if (leads.size() > 0) {

System.out.println("Found " + new Integer(leads.size()).toString() +

" leads:");

for (int i=0;i<leads.size();i++){

SObject l = (SObject) leads.get(i);

System.out.println(l.getId() + " - " +

l.get_any()[1].getValue() + " " +

l.get_any()[2].getValue() + " - " + l.get_any()[0].getValue());

}

if (accounts.size() > 0) {

System.out.println("Found " + new Integer(accounts.size()).toString() +

" accounts:");

for (int i=0;i<accounts.size();i++){

SObject a = (SObject) accounts.get(i);

System.out.println(a.getId() + " - " +

a.get_any()[1].getValue() + " " +

a.get_any()[2].getValue() + " - " + a.get_any()[0].getValue());

}

} else {

System.out.println("No records were found for the search.");

}

System.out.println("\nSearch sample done.");

}

C# Example

private void searchSample()

{

sforce.SearchResult sr = null;

sr = binding.search("find {4159017000} in phone fields returning " +

"contact(id, phone, firstname, lastname), " +

"lead(id, phone, firstname, lastname), " +

"account(id, phone, name)");

Page 282

AppExchange API

sforce.sObject[] records = sr.records;

System.Collections.ArrayList contacts = new System.Collections.ArrayList();

System.Collections.ArrayList leads = new System.Collections.ArrayList();

System.Collections.ArrayList accounts = new System.Collections.ArrayList();

if (sr.size > 0)

{

for (int i=0;i<records.Length;i++)

{

sforce.sObject record = records[i];

if (record.type.ToLower().Equals("contact"))

{

contacts.Add(record);

}

else if (record.type.ToLower().Equals("lead"))

{

leads.Add(record);

}

else if (record.type.ToLower().Equals("account") )

{

accounts.Add(record);

}

if (contacts.Count > 0)

{

Console.WriteLine("Found " + contacts.Count + " contacts:");

for (int i=0;i<contacts.Count;i++)

{

sforce.sObject c = (sforce.sObject)contacts[i];

Console.WriteLine(c.Any[2].InnerText + " " + c.Any[3].InnerText + " - " +

c.Any[1].InnerText);

}

if (leads.Count > 0)

{

Console.WriteLine("Found " + leads.Count + " leads:");

for (int i=0;i<leads.Count;i++)

{

sforce.sObject l = (sforce.sObject)leads[i];

Console.WriteLine(l.Any[2].InnerText + " " + l.Any[3].InnerText + " - " +

l.Any[1].InnerText);

}

if (accounts.Count > 0)

{

Console.WriteLine("Found " + accounts.Count + " accounts:");

for (int i=0;i<accounts.Count;i++)

{

sforce.sObject a = (sforce.sObject)accounts[i];

Console.WriteLine(a.Any[2].InnerText + " - " + a.Any[1].InnerText);

}

else

{

Console.WriteLine("No records were found for the search.");

}

Page 283

AppExchange API

Sample create Call

The following Java and C# examples show using the create

call for the Partner WSDL.

Java Example

private void createContactSample() {

SObject[] cons = new SObject[1];

MessageElement[] contact = new MessageElement[5];

contact[0] = new MessageElement(new QName("FirstName"),"Joe");

contact[1] = new MessageElement(new QName("LastName"),"Blow");

contact[2] = new MessageElement(new QName("Salutation"),"Mr.");

contact[3] = new MessageElement(new QName("Phone"),"999.999.9999");

contact[4] = new MessageElement(new QName("Title"),"Purchasing Director");

cons[0] = new SObject();

cons[0].setType("Contact");

cons[0].set_any(contact);

SaveResult[] sr = null;

try {

sr = binding.create(cons);

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

return;

}

for (int j = 0; j < sr.length; j++) {

if (sr[j].isSuccess()) {

System.out.println("A contact was created with an id of: "

+ sr[j].getId());

}

else {

// there were errors during the create call, go through the errors

// array and write them to the screen

for (int i = 0; i < sr[j].getErrors().length; i++) {

// get the next error

com.sforce.soap.partner.Error err = sr[j].getErrors()[i];

System.out.println("Errors were found on item " +

new Integer(j).toString());

System.out.println("Error code: " + err.getStatusCode().toString());

System.out.println("Error message: " + err.getMessage());

}

C# Example

private void createAccountSample()

sforce.sObject account;

sObject[] accs = new sObject[1];

account = new sforce.sObject();

System.Xml.XmlElement[] acct = new System.Xml.XmlElement[6];

System.Xml.XmlDocument doc = new System.Xml.XmlDocument();

acct[0] = doc.CreateElement("Industry"); acct[0].InnerText = "Farming";

acct[1] = doc.CreateElement("Name"); acct[1].InnerText = "Golden Straw";

acct[2] = doc.CreateElement("NumberOfEmployees"); acct[2].InnerText = "40";

Page 284

AppExchange API

acct[3] = doc.CreateElement("Ownership"); acct[3].InnerText = "Privately Held";

acct[4] = doc.CreateElement("Phone"); acct[4].InnerText = "666.666.6666";

acct[5] = doc.CreateElement("Website"); acct[5].InnerText = "www.oz.com";

account.type = "Account";

account.Any = acct;

accs[0] = account;

//create the object(s) by sending the array to the web service

SaveResult[] sr = binding.create(accs);

for (int j=0;j<sr.Length;j++)

{

if (sr[j].success)

{

Console.Write(System.Environment.NewLine + "An account was create with an id of: "

+ sr[j].id);

}

else

{

//there were errors during the create call, go through the errors

//array and write them to the screen

for (int i=0;i<sr[j].errors.Length;i++)

{

//get the next error

Error err = sr[j].errors[i];

Console.WriteLine("Errors were found on item " + j.ToString());

Console.WriteLine("Error code is: " + err.statusCode.ToString());

Console.WriteLine("Error message: " + err.message);

}

Sample update Call

The following Java and C# examples show using the update call for the Partner WSDL.

Java Example

private void updateAccountSample()

{

// create the account object to hold our changes

SObject updateAccount = new SObject();

updateAccount.setType("Account");

// need to have the id so that web service knows which account to update

updateAccount.setId("001x0000002kuk1AAA");

// set a new value for the name property

MessageElement[] ufields = new MessageElement[1];

ufields[0] = new MessageElement(new QName("Name"),"New Account from Update

Sample");

updateAccount.set_any(ufields);

// create one that will throw an error

SObject errorAccount = new SObject();

errorAccount.setType("Account");

errorAccount.setId("SLFKJLFKJ");

errorAccount.setFieldsToNull(new String[] {"Name"});

// call the update passing an array of object

try {

SaveResult[] saveResults = binding.update(new SObject[] {updateAccount,

Page 285

AppExchange API

errorAccount});

// loop through the results, checking for errors

for (int j = 0; j < saveResults.length; j++) {

System.out.println("Item: " + new Integer(j).toString());

if (saveResults[j].isSuccess()) {

System.out.println("An account with an id of: " +

saveResults[j].getId() + " was updated.\n");

}

else {

System.out.println("Item " + new Integer(j).toString() +

" had an error updating.");

System.out.println(" The error reported was: " +

saveResults[j].getErrors()[0].getMessage() + "\n");

}

} catch (Exception ex) {

System.out.println("An unexpected error has occurred." + ex.getMessage());

return;

}

C# Example

private void updateAccountSample()

{

//create the account object to hold our changes

sforce.sObject updateAccount = new sforce.sObject();

//need to have the id so that web service knows which account to update

//set a new value for the name property

updateAccount.Id = "00130000001dmJT";

System.Xml.XmlDocument doc = new System.Xml.XmlDocument();

System.Xml.XmlElement nameElement = new System.Xml.XmlElement("Name");

nameElement.InnerText = "New Account Name from Update Sample";

updateAccount.Any = new System.Xml.XmlElement[] { nameElement };

updateAccount.type = "Account";

//call the update passing an array of object

SaveResult[] saveResults = binding.update(new sforce.sObject[] { updateAccount

});

//loop through the results, checking for errors

for (int j=0;j<saveResults.Length;j++)

{

Console.WriteLine("Item: " + j);

if (saveResults[j].success)

Console.WriteLine("An account with an id of: " + saveResults[j].id +

" was updated.\n");

else

{

Console.WriteLine("Item " + j.ToString() + " had an error updating.");

Console.WriteLine(" The error reported was: " +

saveResults[j].errors[0].message + "\n");

}

Page 286

AppExchange API

HAPTER

S O A P H e a d e r O p t i o n s

The API provides SOAP header options to client applications. All of these options are available in both the Enterprise and Partner WSDL files.

Task / Call

AssignmentRuleHeader

QueryOptions

SessionHeader

Description

Specifies the assignment rule to use when creating or updating an

, Case , or

Specifies the assignment rule to use when creating or updating a Case or

Sets the batch size for query results.

Specifies the session ID returned from the login server after a

successful login .

AssignmentRuleHeader

The AssignmentRuleHeader must be specified in the create

. When updating

an Account

, specifies whether the territory assignment rules should be applied.

or update call of a

Case or

Lead for

the specified assignment rule to be applied, and it must be specified in the update

call of an

Account for the territory assignment rules to be applied.

API Calls

Fields

Element Name assignmentRuleId useDefaultRule

Type Description

ID of a specific assignment rule to run for the Case or

AssignmentRule object (for

. Can be an inactive assignment rule. The ID can be retrieved by querying the

details, see

AssignmentRule on page 157). If specified, do

not specify useDefaultRule.

This element is ignored for accounts, because all territory assignment rules are applied.

If True for a Case or

assignment rule for a Case or

, uses the default (active)

Account , all territory assignment rules are

. If specified, do not specify an assignmentRuleId.

If True for an

applied.

Page 287

AppExchange API

Sample Code

For a code example, see

AssignmentRule on page 157

See Also

create on page 61

update on page 117

MruHeader

In API version 7.0 and later, the create and

calls do not update the list of Recent Items on the Home tab unless this header is used. Be advised that using this header to update the

Recent Items list may negatively impact performance.

API Calls

Fields

Element Name updateMru

Type

Description

Indicates whether to update the list of most recently used items (True) or not (False).

See Also

create on page 61

update on page 117

QueryOptions

Specifies the batch size for queries. Batches that are larger or smaller than the specified size may be returned, in order to maximize performance.

Associated API Calls

Field

Element Name batchSize

Type

Description

Batch size for the number of records returned in a

Changing the Batch Size in Queries on page 42.

or queryMore

call. The default is 500; the minimum is

200, and the maximum is 2,000.

Page 288

AppExchange API

Sample Code

For code examples, see

See Also

query on page 104

Changing the Batch Size in Queries on page 42

SessionHeader

Specifies the session ID returned from the login server after a successful login . This session ID is

used in all subsequent calls.

Field

Element Name sessionId

Type