Concepts

In the sforce API, objects are data entities that represent your organization's information. For example, the Account object represents accounts-companies and organizations involved with your business, such as customers, partners, and competitors. To describe a particular occurrence of an object (such as a specific account that is represented by an Account 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 sforce API, your applications are able to 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.

Field Types

Field Types Used in the sforce API
Field Type	What the Field Contains
string	String values. See String Field Type.
boolean	Boolean (True / False) values. See Boolean Field Type.
int	Integer (int) values. See Int Field Type.
double	Double values. See Double Field Type.
date	Date values. See Date Field Type.
datetime	Date and time values. See DateTime Field Type.
base64	Base64-encoded arbitrary binary data (of type base64Binary). Used for Attachment, Document, and Scontrol objects. See Base64 Field Type.
id	Primary key field for the object. See Id Field Type.
reference	Cross-references to a different sforce object. Analogous to a foreign key field in SQL. See Reference Field Type.
currency	Currency values. See Currency Field Type.
textarea	String that is displayed as a multi-line text field. See Textarea Field Type.
percent	Percentage values. See Percent Field Type.
phone	Phone numbers. Values can include alphabetic characters. Client applications are responsible for phone number formatting. See Phone Field Type.
url	URL values. Client applications should commonly display these as hyperlinks. See URL Field Type.
email	Email addresses. See Email Field Type.
picklist	Picklists, which include a set of enumerated values from which one value can be selected. See Picklist Field Type.
multipicklist	Multi-select picklists, which include a set of enumerated values from which multiple values can be selected. See Multi-Select Picklist Field Type.
combobox	Combobox, which include a set of enumerated values and allow the user to specify a value not in the list. See Combobox Field Type.

These field types extend the primitive data types, which are described in Primitive Data Types. 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 predefined fields and custom fields. They are enumerated in the type field of the Field type, which is described in the fields property of the DescribeSObjectResult.

Some numeric fields have precision and scale limits. In addition, certain text fields have length restrictions. These restrictions are enforced when you create or update objects. However, the sforce API may return data that does not meet these restrictions.

String Field Type

String fields (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.

Boolean Field Type

Int Field Type

Integer fields (int) are numbers that contain 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.

Double Field Type

Double fields (double) can contain fractional portions (digits to the right of the decimal place), such as ConversionRate in CurrencyType. In the sforce API, all non-integer values (such as Currency Field Type and Percent Field Type) are of type double. For double fields, the following restrictions might exist:

Limitations on Double Fields
Fields	Description
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 to precision minus scale. In the salesforce.com user interface, precision is defined differently-it is the maximum number of digits allowed to the left of the decimal place.

Date Field Type

Date fields (date) 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.

DateTime Field Type

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.

DateTime (dateTime) fields handle date/time values (timestamps), such as ActivityDateTime in the Event object or the CreatedDate, LastModifiedDate, or SystemModstamp in many sforce objects. Regular Date/Time 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.

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.

Base64 Field Type

Base64 fields contain base64-encoded arbitrary binary data (of type base64Binary). These fields are used for storing binary files in Attachments, Documents, 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 an URL to the document instead of storing the document directly in the record.

Id Field Type

All objects have an Id field (of type ID) that uniquely identifies each record in that type. This is analogous to the concept of a primary key in relational databases. The value in the Id field is assigned by the sforce Web service when the record is originally created (create call) to ensure that it is globally unique. This value remains unchanged over the entire lifetime of the record. Its value contains a three-character code that identifies the object type, which client applications can retrieve via the describeSObject call (see keyPrefix).

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 update call accepts an array of sObjects-each sObject contains an Id field that uniquely identifies the sObject.

In .NET, the values in Id fields are treated simply as strings rather than as values of a special Id type.

Reference Field Type

A reference field contains an Id value (of type ID) 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 Opportunity object. It contains an Id value that uniquely identifies an Opportunity record.

In some cases, an object can refer to another object of its same type. For example, an Account can have a parent link that points to another Account.

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 Contact or Lead, and the WhatId field can point to an Account, Opportunity, Campaign, or Case. 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, 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.

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 multi-currency 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.com 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.

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 query call. To filter records on this field, you must do so while processing records in the QueryResult. For fields with this restriction, its filterable field in the Field type (described in the fields property of the DescribeSObjectResult) is False.

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.

URL Field Type

URL fields contain URLs. Client applications are responsible for specifying valid and properly formatted URLs in create and update calls.

Email Field Type

Email fields contain email addresses. Client applications are responsible for specifying valid and properly formatted email addresses in create and update calls.

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 Field object associated with the DescribeSObjectResult, the restrictedPicklist field defines whether it is a restricted picklist or not. The sforce API does not enforce the list of values for advisory (unrestricted) picklist fields on create or update. When inserting a 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.com user interface.

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 sforce API supports the retrieval of the certain picklists in the following objects: CaseStatus, ContractStatus, LeadStatus, OpportunityStage, PartnerRole, SolutionStatus, TaskPriority, 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, etc. 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 Cases) to determine more information about those objects (such as a given case). These objects are read-only via the sforce API. To modify items in picklists, you must use the salesforce.com user interface.

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.

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.

ID Fields

In the sforce API, all sforce objects, including custom objects, have a unique ID field (see Id Field Type) that uniquely identifies the object. This ID field is analogous to a primary key in relational databases. The ID field is automatically generated by salesforce.com when the object is created. Its value contains a three-character code that identifies the object type, which client applications can retrieve via the describeSObject call (see keyPrefix).

In addition, certain sforce objects, including custom objects, have one or more reference fields (see Reference Field Type) that contains the Id value (of type ID) of another, related object (such as a parent object). Reference fields are 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).

System Fields

The following fields are read-only fields commonly found in sforce objects. The sforce Web service updates these fields automatically.

Common Fields in sforce Objects
Field	Data Type	Description
Id	ID	Globally unique ID of this field. See Id Field Type.
CreatedById	ID	ID of the User who created this object. Read-only.
CreatedDate	dateTime	Date and time when this object was created. Read-only.
LastModifiedById	ID	ID of the User who last updated this object. Read-only.
LastModifiedDate	dateTime	Date and time when this object was last modified by a user. Read-only.
SystemModstamp	dateTime	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 and update calls:

When a client application invokes the create call, salesforce.com automatically populates the data 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 defaultedOnCreate), then salesforce.com 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), 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.

Relationships Among sforce Objects

Certain sforce 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 can not 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 sforce objects. For custom objects, you configure these relationships in the salesforce.com user interface. For detailed information, see the salesforce.com user interface online help.

Custom Objects and Custom Fields

In the salesforce.com user interface, organizations can extend their salesforce.com data by defining custom objects and, for certain objects, custom fields.

Custom Objects

Custom objects are custom salesforce.com 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. Custom objects are defined in the salesforce.com user interface-client applications cannot create custom objects via the sforce API. However, client applications with sufficient permissions can invoke other API calls on custom objects.

Custom Fields

Organizations can also define custom fields for standard or custom objects. For custom fields, the custom flag-a boolean field in the Field object-is true. Custom fields are defined in the salesforce.com user interface-client applications cannot define custom fields via the sforce API. For the most part, client applications do not need to know whether a field is a standard field or a custom field.

Note that all numeric custom fields are handled as type double. For more information, see Double Field Type.

Naming Conventions for Custom Objects and Custom Fields

Custom objects and custom fields have an associated name field that is defined by your salesforce.com administrator. Custom objects must have unique names within your organization, and custom fields must have unique names within the same object. In your WSDL file, custom object and field names have a __c suffix, such as myCustomObject__c and myCustomField__c.

Relationships Among Custom Objects

Custom objects related to other objects behave just like standard sforce objects, as described in Relationships Among sforce Objects. For example, cascading deletes are supported 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.

Common Fields in sforce Objects

OwnerID Fields

sforce Object	Master-Detail	Lookup	Custom Fields
Account	X	X	X
Campaign	X	X	X
Case	X	X	X
Contact	X	X	X
Contract	X	X	X
Event			X
Lead		X	X
Opportunity	X	X	X
Product2		X	X
Solution	X	X	X
Task			X
User		X	X

sforce objects have an ownerID field that is an object reference field to the user that 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, the ownerID field has the following limitations when being set:

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 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 Users based on their particular Profiles.

Record types are configured in the salesforce.com user interface. The RecordType object is read-only in the sforce API. A client application can retrieve the list of valid record type IDs for a given object by calling query on the RecordType object.

The RecordTypeId field can contain the ID of the RecordType associated with an sforce object. Client applications can set this field in create or update calls on these objects. If specified in a create or update call (the default is nill), the record type ID must refer to a valid record type for that object. The RecordTypeId field is associated with to the following objects: Account, Campaign, Case, Contact, Contract, Lead, Opportunity, and Solution.

The RecordTypeId field will appear in your WSDL file only if at least one record type is configured for your organization in the salesforce.com user interface.

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.