What’s New in Version 18.0

Generally Available Enhancements

The Force.com Web Services API has been improved for Spring '10 (API version 18.0):

New SOSL Clause for Filtering By Data Categories
An additional SOSL clause has been added in API version 18.0. The optional WITH DATA CATEGORY clause allows you to filter all search results that are associated with one or more data categories and are visible to users. For more information, see “WITH DATA CATEGORY DataCategorySpec” in the Force.com Web Services API Developer's Guide.
New Support for API Version in Outbound Messages
In Spring '10, outbound messages include a new API Version field. Previously, all outbound messages used API version 8.0. Now, the API Version field is automatically set to the current API version when the outbound message was created.
Id field in sObject Now Required
The Id field in sObject no longer has minOccurs="0" in its WSDL definition. This means that the field is required, but it is still nillable as nillable="true". This change is necessary to accommodate the new AggregateResult object, which supports aggregate functions in SOQL. AggregateResult uses xsd:any to represent the set of aggregate values in your query. An optional Id field would result in a Unique Particle Attribution (UPA) violation in the XML schema. This change to the Id field circumvents the UPA issue.
New Objects
The following new objects have been added in API version 18.0:
  • The following new objects were added for Salesforce Chatter. To access these objects, Salesforce Chatter must be enabled for your organization.
    Note
    A feed is a list of recent activities in Salesforce.com, which can include status updates, changes to record fields, and posts about records. Feeds are a useful way to stay up-to-date with what's going on in Salesforce.com.
    • The AccountFeed object represents a single feed item in an account record feed.
    • The AssetFeed object represents a single feed item in an asset record feed.
    • The CampaignFeed object represents a single feed item in a campaign record feed.
    • The CaseFeed object represents a single feed item in a case record feed.
    • The ContactFeed object represents a single feed item in a contact record feed.
    • The ContractFeed object represents a single feed item in a contract record feed.
    • The EntitySubscription object represents a subscription for a user following a record.
    • The FeedComment object represents a comment added to a feed by a user.
    • The FeedPost object represents the following types of changes in a NewsFeed, UserProfileFeed, or record feed, such as AccountFeed: status updates, posts, link posts, and content posts.
    • The FeedTrackedChange object represents an individual field change in a feed.
    • The LeadFeed object represents a single feed item in a lead record feed.
    • The NewsFeed object represents a single feed item in the news feed on a user's home page. A news feed shows recent changes to records which the user is following.
    • The OpportunityFeed object represents a single feed item in an opportunity record feed.
    • The Product2Feed object represents a single feed item in a product record feed.
    • The SolutionFeed object represents a single feed item in a solution record feed.
    • The UserFeed object represents a single feed item in a user record feed.
    • The UserProfileFeed represents a user profile feed, which tracks all actions by a user on records that can be tracked in a feed. This feed is displayed on the user profile page.
  • The following new objects were added for Entitlement Management. To access these objects, entitlement management must be enabled for your organization.
    • The CaseMilestone object represents a required step in an entitlement process on a case.
    • The ContractLineItem object represents a product covered by a ServiceContract (customer support agreement).
    • The ContractLineItemHistory object represents the history of changes to field values on a product covered by a ServiceContract (customer support agreement).
    • The Entitlement object represents the customer support an Account or Contact is eligible to receive. This differs from a ServiceContract because some organizations don't require customer support agreements to provide service.
    • The EntitlementContact object represents a Contact eligible to receive customer support via an Entitlement.
    • The EntitlementHistory object represents the history of changes to field values on an Entitlement.
    • The EntitlementTemplate object represents predefined terms of customer support for products (Product2 object).
    • The MilestoneType object represents a milestone (required step in an entitlement process).
    • The ProductEntitlementTemplate object represents predefined terms of customer support that users can add to products.
    • The ServiceContract object represents a customer support agreement.
    • The ServiceContractHistory object represents the changes to field values on a ServiceContract.
    • The ServiceContractOwnerSharingRule object represents the rules for sharing a ServiceContract with users other than the owner.
    • The ServiceContractShare object represents a sharing entry on a ServiceContract.
  • The following objects are now generally available for Sites. To access these objects, Force.com Sites must be enabled for your organization.
    • The read-only Site object represents a public website that is integrated with a Salesforce.com organization.
    • The read-only SiteHistory object represents the history of changes to the values in the fields of a site.
  • The following objects are now generally available for the Answers feature. To access these objects, answers must be enabled for your organization.
    • The Question object represents a topic that a user has posted to an answers community.
    • The Reply object represents a reply that a user has posted in response to a question.
  • The following objects are now generally available for the Quotes feature. To access these objects, quotes must be enabled for your organization.

    • The Quote object represents a quote, which is a record showing proposed prices for products and services. Quotes can be created from and synced with opportunities, and emailed as PDFs to customers.

    • The QuoteDocument object represents a quote in document format.

    • The QuoteLineItem object represents a quote line item, which is a member of the list of Product2 products associated with a Quote, along with other information about those line items on that quote.
  • The KnowledgeArticleVersion object was added for Salesforce Knowledge. It represents an article. To access this object, Salesforce Knowledge must be enabled for your organization.
New Calls
The following new calls have been added in API version 18.0 for Salesforce Knowledge and the Answers feature:
  • describeDataCategoryGroups() call retrieves available category groups for objects specified in the request.
  • describeDataCategoryGroupStructures() call retrieves available category groups along with their data category structure for objects specified in the request.
Changed Objects
The following objects have been changed in API version 18.0:
  • The Attachment object includes a Description field that displays the description of the attachment.
  • The CallCenter object includes a Version field that displays the version number of call centers built with the CTI Developer's Toolkit 2.0 or higher.
  • The Case object includes an SlaStartDate field that displays the date a case entered an entitlement process. It also includes an IsStopped field that indicates whether an entitlement process on a case is stopped or not, as well as a StopStartDate field that displays the date an entitlement process was stopped on a case.
  • The EmailServicesFunction includes an IsTextAttachmentsAsBinary field to support converting text attachments to binary attachments.
  • ApexClassId is now a required field for the EmailServicesFunction object.
  • The Group object includes a DoesIncludeBosses field that indicates whether the managers have access (true) or do not have access (false) to records shared with members of the group. This field is only available for public groups.
  • The OpportunityLineItem object includes a Discount field to support discounts for opportunity products. It also includes a Subtotal field, which shows the difference between standard and discounted pricing.
  • The Organization object includes a MonthlyPageViewsEntitlement field that displays the number of page views allowed for the current calendar month for the sites in your organization. The Organization object also includes a MonthlyPageViewsUsed field that displays the number of page views used for the current calendar month for the sites in your organization. To access these fields, Sites must be enabled for your organization.
  • The User object includes a UserPreferencesDisableAutoSubForFeeds field for Salesforce Chatter. This field turns off automatic subscriptions to feeds created by the user.
  • The single email and mass email limits are now separate. SingleEmailMessage, used by the sendEmail() call, returns SINGLE_EMAIL_LIMIT_EXCEEDED when the limit is reached (version 18.0 and higher). MassEmailMessage, used by the sendEmail() call, continues to return MASS_MAIL_LIMIT_EXCEEDED.
  • The Vote object can now be used to vote on the new Reply object.
  • The UserLicense object now supports these field values:
    FieldValue
    NameAuthenticated Website: label is Authenticated Website
    LicenseDefinitionKeyPlatform_Portal_User: corresponds to the Authenticated Website User user license
Changed Calls
The following calls have been changed in API version 18.0:
  • The results of the describeSoftphoneLayout() call now include the new screenPopOptions setting for SoftPhone layouts associated with CTI 2.0 adapters or higher.
  • The read-only AggregateResult object contains the results returned by a query() call if the query contains an aggregate function, such as MAX().
  • The charset argument in SingleEmailMessage, used by the sendEmail() call, is unavailable if you are specifying the templateId because the template specifies the character set.
New SOAP Header
The DisableFeedTrackingHeader header specifies whether the changes made in the current call are tracked in feeds. Use this header if you want to process a large number of records without tracking the changes in various feeds related to the records. This header is available if the Chatter feature is enabled for your organization. For more information on Chatter, see “Salesforce Chatter Overview” in the Salesforce.com online help.

Generally Available Enhancements for SOQL

SOQL has been improved for Spring '10 (API version 18.0):

New GROUP BY Clause
Idea light bulb You asked for it! This enhancement is an idea from the IdeaExchange.
Spring '10 introduces a new GROUP BY clause in SOQL that is similar to GROUP BY in SQL. You can use GROUP BY with new aggregate functions, such as SUM() or MAX(), to summarize the data and roll up query results rather than having to process the individual records in your code. For example, you can use GROUP BY to determine how many leads are associated with each LeadSource value:
SELECT LeadSource, COUNT(Name)
FROM Lead
GROUP BY LeadSource
If you want a query to do the work of calculating subtotals so that you don't have to maintain that logic in your code, use GROUP BY ROLLUP. If you want to calculate subtotals for every possible combination of grouped field (to generate a cross-tabular report, for example), use GROUP BY CUBE instead.
For more information, see “GROUP BY” in the Force.com Web Services API Developer's Guide.
New HAVING Clause
There is a new HAVING clause in SOQL that is similar to HAVING in SQL. You can use a HAVING clause with a GROUP BY clause to filter the results returned by aggregate functions, such as SUM(). A HAVING clause is similar to a WHERE clause. The difference is that you can include aggregate functions in a HAVING clause, but not in a WHERE clause. For example, the following query returns accounts with duplicate names:
SELECT Name, Count(Id)
FROM Account
GROUP BY Name
HAVING Count(Id) > 1
For more information, see “HAVING” in the Force.com Web Services API Developer's Guide.
Aggregate Functions
Idea light bulb You asked for it! This enhancement is an idea from the IdeaExchange.
Aggregate functions allow you to roll up and summarize your data for analysis. You can use these functions without using a GROUP BY clause. For example, you could use the AVG() aggregate function to find the average Amount for all your opportunities. 
SELECT AVG(Amount) FROM Opportunity
However, these functions become a more powerful tool to generate reports when you use them with a GROUP BY clause. For example, you could find the average Amount for all your opportunities by campaign. 
SELECT CampaignId, AVG(Amount)
FROM Opportunity
GROUP BY CampaignId
This table lists all the aggregate functions supported by SOQL.
Aggregate FunctionDescription
AVG()Returns the average value of a numeric field. For example:
SELECT CampaignId, AVG(Amount)
FROM Opportunity
GROUP BY CampaignId
COUNT()Returns the number of rows matching the query criteria. There are two versions of count function: the existing COUNT() function and the new COUNT(fieldName) aggregate function. You can't use a GROUP BY clause with COUNT(), but you can with COUNT(fieldName). For example:
SELECT COUNT() FROM Account WHERE Name LIKE 'a%'
SELECT COUNT(Id) FROM Account WHERE Name LIKE 'a%'
Note
COUNT(Id) in SOQL is equivalent to COUNT(*) in SQL.
COUNT_DISTINCT()Returns the number of distinct non-null field values matching the query criteria. For example:
SELECT COUNT_DISTINCT(Company)
FROM Lead
Note
COUNT_DISTINCT(fieldName) in SOQL is equivalent to COUNT(DISTINCT fieldName) in SQL.

You can use a GROUP BY clause without an aggregated function to query all the distinct values, including null, for an object. The following query returns the distinct set of values stored in the LeadSource field.

SELECT LeadSource
FROM Lead
GROUP BY LeadSource
MIN()Returns the minimum value of a field. For example:
SELECT MIN(CreatedDate), FirstName, LastName
FROM Contact
GROUP BY FirstName, LastName

If you use the MIN() or MAX() functions on a picklist field, the function uses the sort order of the picklist values instead of alphabetical order.

MAX()Returns the maximum value of a field. For example:
SELECT Name, MAX(BudgetedCost)
FROM Campaign
GROUP BY Name
SUM()Returns the total sum of a numeric field. For example:
SELECT SUM(Amount)
FROM Opportunity
WHERE IsClosed = false AND Probability > 60
For more information, see “Aggregate Functions” in the Force.com Web Services API Developer's Guide.
Date Functions
Date functions allow you to group or filter your data by various date periods. For example, you could use the CALENDAR_YEAR() function to find the sum of the Amount values for all your opportunities for each calendar year. 
SELECT CALENDAR_YEAR(CreatedDate), SUM(Amount)
FROM Opportunity
GROUP BY CALENDAR_YEAR(CreatedDate)

This table lists all the date functions supported by SOQL.

Date Function Description Examples
CALENDAR_MONTH() Returns a number representing the calendar month of a date field.
  • 1 for January
  • 12 for December
CALENDAR_QUARTER() Returns a number representing the calendar quarter of a date field.
  • 1 for January 1 through March 31
  • 2 for April 1 through June 30
  • 3 for July 1 through September 30
  • 4 for October 1 through December 31
CALENDAR_YEAR() Returns a number representing the calendar year of a date field. 2009
DAY_IN_MONTH() Returns a number representing the day in the month of a date field. 20 for February 20
DAY_IN_WEEK() Returns a number representing the day of the week for a date field.
  • 1 for Sunday
  • 7 for Saturday
DAY_IN_YEAR() Returns a number representing the day in the year for a date field. 32 for February 1
DAY_ONLY() Returns a date representing the day portion of a dateTime field. 2009-09-22 for September 22, 2009

You can only use DAY_ONLY() with dateTime fields.
FISCAL_MONTH() Returns a number representing the fiscal month of a date field. This differs from CALENDAR_MONTH() if your organization uses a fiscal year that does not match the Gregorian calendar. If your fiscal year starts in March:
  • 1 for March
  • 12 for February

See “Setting the Fiscal Year” in the Salesforce.com online help.
FISCAL_QUARTER() Returns a number representing the fiscal quarter of a date field. This differs from CALENDAR_QUARTER() if your organization uses a fiscal year that does not match the Gregorian calendar. If your fiscal year starts in July:
  • 1 for July 15
  • 4 for June 6
FISCAL_YEAR() Returns a number representing the fiscal year of a date field. This differs from CALENDAR_YEAR() if your organization uses a fiscal year that does not match the Gregorian calendar. 2009
HOUR_IN_DAY() Returns a number representing the hour in the day for a dateTime field. 18 for a time of 18:23:10

You can only use HOUR_IN_DAY() with dateTime fields.
WEEK_IN_MONTH() Returns a number representing the week in the month for a date field. 2 for April 10

The first week is from the first through the seventh day of the month.
WEEK_IN_YEAR() Returns a number representing the week in the year for a date field. 1 for January 3

The first week is from January 1 through January 7.
Note
SOQL queries in a client application return dateTime field values as Coordinated Universal Time (UTC) values. To convert dateTime field values to your default time zone, use convertTimezone(dateTimeField). Note that you can only use convertTimezone() in a date function.
For more information, see “Date Functions” in the Force.com Web Services API Developer's Guide.
Semi-Join and Anti-Join Support For Reference Fields
A semi-join is a subquery on another object in an IN clause in a SOQL query. You can use semi-joins to create advanced queries, such as getting all contacts for accounts that have an opportunity with a particular record type. An anti-join is a subquery on another object in a NOT IN clause in a SOQL query. You can use anti-joins to create advanced queries, such as getting all accounts that do not have any open opportunities.
Prior to API version 18.0, the subquery could only filter by an ID (primary key) field. For example, the following query returns account IDs if an associated opportunity is lost:
 SELECT Id, Name 
 FROM Account 
 WHERE Id IN 
(SELECT AccountId FROM Opportunity WHERE StageName = 'Closed Lost')
Notice that the left operand, Id, of the IN clause is an ID field. Filtering by an ID field allows you to create parent-to-child semi- or anti-joins, such as Account to Contact.
With API version 18.0, the subquery can now filter by ID (primary key) or reference (foreign key) fields. This also allows you to create child-to-child semi- or anti-joins, such as Contact to Opportunity, or child-to-parent semi- or anti-joins, such as Opportunity to Account.The following query returns task IDs for all contacts in Twin Falls:
 SELECT Id
 FROM Task 
 WHERE WhoId IN 
(SELECT Id FROM Contact WHERE MailingCity = 'Twin Falls')
For more information, see “Comparison Operators” in the Force.com Web Services API Developer's Guide.
Filtering By Data Categories

The WITH DATA CATEGORY clause is used in a SELECT statement to filter records based on their classification in one or more data category groups. If WITH DATA CATEGORY is specified, the query() only returns matching records that are associated with the specified data categories and are visible to the user. If unspecified, the query() only returns the matching records that are visible to the user.

Note
The WITH DATA CATEGORY clause does not support bind variables.
The WITH DATA CATEGORY SOQL syntax is: 
WITH DATA CATEGORY  filteringExpression
The filteringExpression syntax is:
dataCategorySelection [AND  dataCategorySelection2 ...]
The WITH DATA CATEGORY clause only filters objects of type:
  • Question—to query questions.
  • KnowledgeArticleVersion—to query articles.

The examples in this section are based on the following data category group:

Geography__c
    ww__c
        northAmerica__c
            usa__c
            canada__c
            mexico__c
        europe__c
            france__c
            uk__c
        asia__c
The category filtering in the statements below is highlighted in bold. For more information on the syntax, see “WITH DATA CATEGORYfilteringExpression” in the Force.com Web Services API Developer's Guide.
  • SELECT Title FROM KnowledgeArticleVersion WITH DATA CATEGORY Geography__c ABOVE usa__c
  • SELECT Title FROM KnowledgeArticleVersion WHERE LastPublishedDate > 2009-01-01 WITH DATA CATEGORY Geography__c AT (usa__c, uk__c)
  • SELECT Language FROM KnowledgeArticleVersion WHERE FirstPublishedDate < 2009-01-01 WITH DATA CATEGORY Geography__c AT usa__c AND Product__c ABOVE_OR_BELOW mobile_phones__c ORDER BY Title

Earlier Versions

Information about changes for earlier versions is available:

© Copyright 2000-2010 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.