What's New in Force.com Web Services API Winter '08

Contents

Overview

The Winter '08 release, including the Force.com API, contains new features and bug fixes that improve the capabilities of applications that leverage the Force.com platform. Considerable effort has been made to ensure backwards capability with the API version 10.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 '08 release, please see the Winter '08 Admin Preview, or visit the Wiki. After version 11.0 has been released to your server, see the Force.com Web Services API Developers Guide.

Things to note:

After the Winter '08 release, the 10.0 version of the WSDL file will not be available. Instead, all requests for a WSDL will return an 11.0 version. Please remember to save WSDL files with your project, as the enterprise WSDL is custom to your organization. Salesforce.com maintains backwards compability on previous versions of our APIs in accordance with our stated support policy. Salesforce.com recommends that developers migrate to the latest version of the API as often as is feasible in order to receive the benefit of new enhancements from release to release. Developers with integrations on API versions prior to version 2.5 should be planning to migrate to the most recent API in preparation for the eventual end of support for the older API versions.

Platform Changes

  • The AJAX Toolkit and Web services API have been updated to 11.0.
  • The Force.com IDE has been updated. For details, see Force.com IDE. The Winter '08 release of the toolkit, called the Force.com Toolkit for Eclipse, will be released soon. More information will be posted here when it is available.
  • Developers of AppExchange packages can specify whether or not to restrict the API access of components in the package for greater security. Installers of AppExchange packages can view the API access given to components of a package they are installing, and after installation can modify that access.
  • In SOSL you can now set the LIMIT clause on individual objects. Setting individual object limits allows you to prevent results from a single object using up the maximum query limit before other objects are returned.
  • In SOSL you can now search solutions, products, and documents with other objects in a single query. Prior to this release you could only search those objects separately.

Metadata API—Developer Preview

Two new declarative metadata API calls, deploy and retrieve, are available in the Developer Preview. These two calls work with file representations of a number of components in an organization. You can now retrieve packages or components from an organization in as text files, manipulate the files, and deploy the changed packages or components. Although most developers should use Eclipse or Ant instead of these API calls, if you require lower-level access, you can use deploy and retrieve.

Note: Because this is a Developer Release, a migration path may not be supplied to the General Availability (GA) release.

For more information, see API Metadata Documentation after October 26, 2007.

New or Changed Calls

No new calls are being introduced, except for the the new calls for Metadata listed above.

The following calls or result objects returned by calls were changed for this release:

  • compileClass has a new property in CompileClassResult, name, which returns the name of the class.
  • runTest has new properties:
    • RunTestFailure has new property, time, which contains the amount of processor time spent in that area.
    • RuntTestFailure has a new property, id, which returns the ID of the class that failed.
    • RunTestResult has a new property, success, which contains a new result object, RunTestSuccess.
    • RunTestResult has a new property, totalTime, which contains the total amount of processor time spent on that test.
    • RunTestSuccess has a new property, id, which returns the ID of the class that succeeded.
  • The sendEmail call includes the following new arguments:
    • documentAttachments: An array listing the ID of each Document you want to attach to the email. You can attach multiple documents as long as the total size of all attachments does not exceed 10 MB. (For single email messages only.)
    • fileAttachments: An array listing the filenames of the binary and text files you want to attach to the email. You can attach multiple files as long as the total size of all attachments does not exceed 10 MB. (For single email messages only.)
    • senderDisplayName: The name that appears on the From line of the email. (For single and mass email messages.)
    • templateId: The ID of the template to use for the email. In previous releases, templates could only be used in mass email. Now, they can be used in single email.
    • whatId and whatIds: Specifies the context for single and mass email, respectively. The whatId helps to further ensure that merge fields in the template contain the correct data.

New Objects

  • AccountHistory - Represents the history of changes to the values in the fields of an account.
  • CampaignOwnerSharingRule - Represents the rules for sharing a campaign with Users other than the owner or anyone above the owner in the role hierarchy.*CampaignShare - Represents a sharing entry on a Campaign.
  • ContactHistory- Represents the history of changes to the values in the fields of an contact.
  • ForecastShare - Represents the sharing of a forecast at a given role and territory.
  • PartnerNetworkConnection - Represents a Salesforce to Salesforce connection between Salesforce organizations.
  • QuantityForecastHistory - Represents the historical information about quantity-based forecasts that have been submitted.

New or Changed Fields

  • The Campaign object has a new ParentCampaign field for creating campaign hierarchies and eight new aggregate statistic fields that provide data for a parent campaign and all the campaigns below it in the campaign hierarchy; all fields are read-only:
    • TotalAmountAllOpportunitites; label is Total Value Opportunities in Hierarchy
    • TotalAmountAllWonOpportunities; label is Total Value Won Opportunities in Hierarchy
    • TotalNumberOfContacts; label is Total Contacts in Hierarchy
    • TotalNumberOfConvertedLeads; label is Total Converted Leads in Hierarchy
    • TotalNumberOfLeads; label is Total Leads in Hierarchy
    • TotalNumberOfOpportunities; label is Total Opportunities in Hierarchy
    • TotalNumberOfResponses; label is Total Responses in Hierarchy
    • TotalNumberOfWonOpportunities; label is Total Won Opportunities in Hierarchy
  • For the Case object, if your organization has an active auto-response rule, then SuppliedEmail is required when creating a case via the API. For more information, see Setting Up Auto-Response Rules in the Salesforce online help.
  • For the Contact object, CanAllowPortalSelfReg indicates whether this contact can self-register for your organization's Customer Portal. For more information about the Customer Portal and self-registration, see Enabling Customer Portal Login and Settings in the Salesforce online help.
  • For the Lead and Opportunity objects, the following changes were implemented:
    • ConnectionReceivedId is the ID of the PatnerNetworkConnection that shared a record with your organization.
    • ConnectionSentId is the ID of the PatnerNetworkConnection that you shared a record with.
  • For the User object, the following changes occurred:
    • IsPortalSelfRegistered is a new field that indicates whether the user is a Customer Portal user who self-registered for your organization's Customer Portal. For more information about the Customer Portal and self-registration, see Enabling Customer Portal Login and Settings in the Salesforce online help.
    • ManagerIDdlookup is a new field that is used to select the user's manager. This establishes a hierarchical relationship, preventing you from selecting a user that directly or indirectly reports to itself.
    • ContactId is now visible to all organizations, regardless of whether or not an organization enabled a Customer Portal.

New or Changed SOAP Headers

The SOAP header DebuggingHeader now takes the following values:

  • CALLOUT
  • DB
  • DEBUGONLY
  • DETAIL
  • NONE
  • PROFILING

API Migration Issues

The following technical notes are available to assist you in migrating from versions earlier than 10.0:

Retrieved from "http://wiki.developerforce.com/index.php/What%27s_New_in_Force.com_Web_Services_API_Winter_%2708"