Basic Concepts. salesforce.com API

PDF

Document

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 ,

update

, or

delete

such objects. Similarly, certain

fields within some objects can be specified on create

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

delete

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

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

values (timestamps), such as ActivityDateTime in the Event

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

Account

. 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

Contact object, the FirstName field is 40 characters, 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

Field

type, which is described in the fields property

of the DescribeSObjectResult .

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