What's New in Apex Web Services API Winter
'07
Overview
The Winter '07 release, including the Apex API
version 8.0, contains significant new features and bug fixes that improve the
capabilities of applications that leverage the Apex platform. Considerable
effort has been made to ensure backward capability with the API version 7.0 for
applications that have been written against previous versions of the API,
starting with API 2.5. Note: older XML-RPC APIs remain unchanged with this
release.
The new API
provides a number of powerful enhancements that further improve any integration
already in place between Salesforce and your other systems. For additional
information on the Winter '07 release, please see the Winter '07 Admin Preview,
or visit: http://www.salesforce.com/developer.
Things to
note:
- With this release, the name of the platform has changed from AppExchange to Apex.
- After the Winter '07 release, the 7.0 version of the WSDL file will not be available. Instead, all requests for a WSDL will return an 8.0 version. Please remember to save WSDL files with your project, as the enterprise WSDL is custom to your organization.
- The XML-RPC APIs have not changed -- or been enhanced -- with Apex API 8.0. Developers are encouraged to migrate to the SOAP-based API to leverage the new features of the platform. These have not been updated since December 2003. We will soon be asking customers using XML/RPC versions 1.5 through 1.7 to upgrade to at least version 1.8. This is a simple change for most XML/RPC integrations.
Major API Changes
- SOQL Relationship Queries -
Relationships between objects have been exposed in the API so that you can
query on more than one type of object, as long as a relationship exists
between the objects. You can also query on the parent of objects that may have
more than one type of parent. The new version of the Apex Explorer (formerly sforce Explorer) supports
relationship queries.
- SOQL and SOSL
enhancements - SOQL now supports ORDER BY, COUNT(*), LIMIT, toLabel,
convertCurrency, and dateTime. SOSL, which already supported LIMIT, now
supports ORDER BY, toLabel and convertCurrency.
- Outbound
Messaging - You can use the outbound messaging WSDL available in
the Salesforce user interface to handle outbound messages sent by Salesforce.
This allows you to eliminate polling.
- Workflow and
Approvals - You can submit workflow items for approval, or submit them
for processing after approval. See process in the New Calls section below for more information.
- New field type masterrecord and new field
isDeleted - Supports the new merge call (see New Calls below). When
records are merged, the ID of the record that is saved is returned. The other
records are deleted. You can filter on deleted records (as long as it is
before they are permanently deleted by periodic Salesforce processes) using
the IsDeleted field with queryAll (see New Calls below).
- Upsert improvements - You can now use
external IDs to set other ID fields on an object. You can issue an upsert call based on external IDs without
having to retrieve Salesforce IDs at all. The new data loader utility supports this new functionality.
- Metadata enhancements - You can use the
enhanced describeLayout call for
efficient retrieval of page layouts for large organizations. You can use the
optional recordTypeId to limit the
layout data that is returned to just the record types given. You can specify
that just the master record type page layout be
returned.
API Migration
Issues
Improved Performance
- Bulk deletes of some objects will now be
much faster.
Major Platform
Changes
- Validation rules - You can use
validation formulas, define error message text, and enforce these rules
through the API as well as the Salesforce user interface.
- Field requiredness - You can make
fields conditionally required or use the new "Required" and "Unique" custom
field properties to universally enforce your business rules.
- Workflow approval processes - You
can automate approval processes and use workflow rules to send a customizable
XML message to a Web-available listener.
- Workflow updates - You can
trigger state changes and calculations with field action updates, filter with
the advanced "OR" and special date values. You can create up to 300 workflow
rules per object for your organization.
- S-Controls - You can display custom
HTML/JavaScript content or content via an external URL. You can also create
"mashboards" by integrating third-party analytics into dashboards with
S-Controls. You can use existing formula functions to do server-side
calculations and evaluations before rendering your content, and generate
client-side JavaScript. You can hide standard buttons.
- Custom buttons and links - You can
add custom buttons to any list view, detail page, or related list. You can
execute inline JavaScript or display S-Control content in the current browser
window without a Salesforce header or sidebar.
For more
information about these platform changes, see the Salesforce
Feature Detail Pages.
New Calls
- merge - You can now merge up to
three records into one with the merge call.
- queryAll - You can find all
records, deleted or not. You can also use queryAll with the new IsArchived field on Tasks and Events to filter for archived objects.
- undelete - You can undelete
records.
- process - You can now submit an
array of workflow process instances for approval, or you can process an array
of workflow instances that have already been submitted.
New Objects
- ProcessInstance, ProcessInstanceStep,
ProcessInstanceWorkitem - These new workflow approval objects are
used by the process call.
- History objects: CaseHistory (available in API Version 7.0), ContractHistory, LeadHistory, OpportunityHistory (available in API Version
7.0), OrderHistory, ProcessInstanceHistory, QuantityForecastHistory (available in API Version 7.0), RevenueForecastHistory (available in API Version 7.0), and SolutionHistory now replace EntityHistory, which is deprecated beginning
API Version 8.0. Also, custom objects can have history objects if you enable
history tracking on them.
- BrandTemplate and EmailTemplate are templates for email
letterhead and email, respectively, for messages sent when the activity
history related list of a record is modified. EmailStatus represents the status of such
email.
- CampaignMemberStatus represents the member
status values defined for a campaign. Use this object to create picklist items
for the member status in a campaign.
- Name represents the first and last name, and other metadata, of an object. Use it
to navigate foreign keys which point to more than one type of object as
parent. For example UserId might point to contact or lead. Can only be used in
a SOQL SELECT statement.
- NoteAndAttachment represents all the notes
and attachments associated with an object. It is read only.
- Order represents a shipment or other provisioning of products associated with an
account (an order), and OrderItem represents items in that shipment.
- Organization represents key configuration information for an
organization.
- QueueSobject represents the mapping between a queue Group and the sObject types associated with
the queue.
New and Changed SOAP
Headers
- EmailHeader - Sends an email notification when a request is
processed.
- LoginScopeHeader - Specifies the
organization ID so that you can authenticate Self Service users for your
organization using the login call.
- UserTerritoryDeleteHeader -
Specifies a user to whom open opportunities are assigned when the current
owner is removed from a territory.
New & Changed API
Behavior
- Non-breaking spaces - If you insert
non-breaking spaces via the API, they are now preserved. In previous versions,
they were converted to regular spaces.
- Specifying an Account for Case. In previous
releases, the account assigned to a case was always derived from the contact's
account. With this release, you can specify any account to relate to the case.
No changes are required to maintain information in existing records, with one
exception noted in the API documentation for Case.
- Some objects cannot be queried. In
previous releases, all objects could be queried. With this release, some
objects such as ActivityHistory are
read-only, and cannot be queried. To access information, use the appropriate
describe call.
- GetUserInfoResult now contains a ProfileID, RowID, and UserName field for the user.
- upsert. If you are upserting
against a unique index (external ID indexed as unique), you do not need
special privileges. If you are upserting against a non-unique index, you need
the ViewAllData permission. This is to prevent the unintentional insertion of
duplicate records (you might try to insert a record that existed, but that you
didn't have permission to see).
- Solution. The SolutionName field now has a limit of 255
characters. Previously, the limit was 80.
- Profile. Profile no longer supports the create call.
- Product and Pricebook. The Product and Pricebook objects have been removed from the
8.0 WSDL. Requests that use these two objects will be refused, and responses
containing them will not be generated.
- date and dateTime filtering. If you
specify a dateTime value in a query, you can filter on dateTime fields only.
Similarly, if you specify a date value, you can filter on date fields only. In
previous releases, you could use a date value when filtering on dateTime
fields.
- CaseComment. Any user with
appropriate permissions can edit the CaseComment object. You need not
be an administrator.
- Field changes:
-
The LastActivityDate field has been added to Account, Contact, Lead, Opportunity, Campaign, and Contract.
-
A new field Name has been added to Contact, User, Lead, and SelfServiceUser. This field's value is the
concatenation of FirstName and LastName, and cannot be directly updated.
-
The field AccountAccessLevel has been added to AccountTeamMember.
-
The fields IsRecurrence and RecurrenceActivityId on Event are now updateable.
-
The field SystemModStamp has been added to OpportunityHistory.
-
The field OpportunityAccessLevel has been added to OpportunityTeamMember.
-
The length of the field Company on Lead has changed from 80 255.
-
New fields HasOptedOutOfFax and DoNotCall have been added to Contact.
-
The label changed from Email Address to Email for the Email field on Contact.
-
Byte length for the field Company on Lead has changed from 80 to 255.
-
New fields HasCommentsUnreadByOwner, HasSelfServiceComments, IsClosedOnCreate, and IsSelfServiceClosed have been added to Case.
-
The new field TimesUsed has been added to Solution.
-
The label for field IsPublished in Solution changed from Published to Visible in SelfServiceUser.
-
The length of field SolutionName on Solution changed from 80 to 255 characters.
-
The new field HasSchedule has been added to OpportunityLineItem.
-
New fields LastModifiedDate and LastModifiedById have been added to CaseComment.
-
There is a new reference to SelfServiceUser on the field CreatedById in CaseHistory. This means that CaseHistory can be created by a SelfServiceUser.
-
The label for the Id field on CaseHistory has been
changed from Case History ID to Entity History ID.
- The Description field on Document changed from type String to type
TextArea.
- The new
field BillingName has been added to Contract.
- The new
field DeveloperName has been added to SControl.
- The
label on field Name in the object SControl has been changed to
"Label".
- The
field CommentBody in the object CaseComment can now be updated only by an
administrator user.
- The
field CaseId on the object CaseHistory can be null.
- The WebLink object has had the following
field changes:
- The label changed from "Custom Link" to "Custom Button or Link".
- The label plural form changed from "Custom Link" to "Custom Buttons or
Links".
- EncodingKey field: changed the value of the label from
"Encoding" to "Link Encoding".
- Height field: changed the label from "Height" to "Height (in
pixels)".
- Width field: changed the label from "Width" to "Width (in
pixels)".
- ShowsLocation field: changed the label from "Shows Location" to
"Show Address Bar".
- HasScrollbars field: changed the label from "Has Scrollbars" to
"Show Scrollbars".
- HasToolbar field: changed the label from "Has Toolbar" to "Show
Toolbars".
- HasMenubar field: changed the label from "Has Menubar" to "Show
Menu Bar".
- ShowsStatus field: changed the label from "Shows Status" to
"Show Status Bar".
- IsResizable field: changed the label from "Is Resizable" to
"Resizeable".
- Position field: changed the label from "Position" to "Window
Position".
- ScontrolId field: changed the label from "custom s-control ID"
to "Custom S-Control ID".
- OpenType field: changed the label from Label "Open Type"
changed to "Behavior".
- Changed the label for the picklist value newWindow from null to
"Display in new window".
- Changed the label for the picklist value sidebar from null to
"Display in existing window with sidebar".
- Changed the label for the picklist value noSidebar from null to
"Display in existing window without sidebar".
- Added the picklist value "replace".
- Added the picklist value "onClickJavaScript".
- LinkType field: changed the value of the label from "Link Type"
to "Content Source".
- Changed the label for the picklist value url from null to "URL".
- Changed the label for the picklist value sControl from null to
"Custom S-Control".
- Added the picklist value "javascript".
- Url field:
- Changed the byteLength from 4000 to 1048576.
- You can now filter on the field, previously you could not.
- Changed the length from 4000 to 1048576.
- Changed the type from string to textarea.
- Case object change. In the Case object, four fields changed name and one new field was added. For details, see the fifth bullet under API Migration Issues above.
- XML/RPC label change. In XML/RPC,
the label Probability is now Probability
(%).
Describe Changes
- describe now returns a value for
the field IsQueryable. If IsQueryable is set to true (for example, ActivityHistory), then you cannot query the
object as a top level item in a SOQL relationship query, however, you can
query it as a related item. For example, the following query is valid for ActivityHistory:
SELECT Name, (SELECT Subject from
ActivityHistories) from Contact
- DescribeTabSetResult contains a projectId, field which reports the
project that the tabset came from.
- DescribeSObjectResult now contains
a recordTypeId field. The value is NULL
if there is no record type Id assigned.
- describe on Lead and Case shows that Lead and Case can be owned by users and queues (Group).
- describe on the Note child relationship on Account has been changed to NoteAndAttachment and includes the child
SObject name.
Bug Fixes
- 89527 - Asset object can now be
replicated.
- 67351 - You can now use describeLayout with Asset and Contract objects. These objects are now
layoutable.
- 93850 - The global element decl has been removed from the
enterprise WSDL definition for each object because it was not used.
- 102740 - The Title field of the Note object is flagged as a name field.
- 102766 - When using MRUheader with
a retrieve call, if the result has only one row, MRU is updated to the ID of
the retrieve result. For query, if the result has only one row and the ID
field is selected, the MRU is updated to the ID of the query result.
Documentation
Improvements
- Each object lists all of its fields (excluding some fields that are
exposed only with certain features, and system fields, which are described in
a separate section).
- Each call now includes JavaScript samples in support of the AJAX Toolkit.
- An AJAX Toolkit Developer's Guide is now available.
- A Best Practices section has been added to help developers work with
complex features in the API for the best results.
Training
Salesforce.com Education Services offers a suite of training courses to
enable developers to design, create, integrate, and extend applications built on
the Apex platform. Be sure to visit http://www.salesforce.com/trainingsupport/developers.jsp to
learn more.
|