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

Image:header_technote.gif

S-Controls

Note: S-controls have been superseded by Visualforce pages. For more information, please visit S-Control_Deprecation


Contents

Overview

The Winter '07 release, including the Force.com API version 8.0, contains significant new features and bug fixes that improve the capabilities of applications that leverage the Forece.com 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 Force.com 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

  • AJAX toolkit - You can now call the API from JavaScript.
  • 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 Force.com Explorer (formerly Apex 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

  • Managed packages downloaded from the AppExchange prepend a unique namespace prefix (obtained as part of the packaging process) to custom objects, fields, scontrols and other components. If you have an unmanaged package and wish to install a managed package version of the app, you should export your data, remove the unmanaged package, install the managed package, and import your data. For detailed instructions, see the Salesforce online help.
  • The describeLayout call in 8.0 requires a second parameter, recordTypeID. For behavior similar to 7.0, you can supply the value NULL for the second parameter. (bug 70406)
  • The Pricebook and Product objects, deprecated for several releases, have been removed from API Version 8.0.
  • The EntityHistory object has been removed. Use the history object appropriate for the object you are working with: CaseHistory, ContractHistory, LeadHistory, OpportunityHistory, OrderHistory, ProcessInstanceHistory, QuantityForecastHistory, RevenueForecastHistory, SolutionHistory, or a history object created for your custom objects.
  • Four fields in the Case object have changed name and one field was added--note that the old and new names are available in 8.0 and 7.0 to aid migration: 
          7.0 API      -->         8.0 API
     ClosedOnCreate    -->  IsClosedOnCreate
     IsVisibleInCss    -->  IsVisibleInSelfService
     IsSelfClosed      -->  IsSelfServiceClosed
     HasCSSComments    -->  HasSelfServiceComments
                            HasCommentsUnreadByOwner
  • In Force.com API 8.0, you can share queues across object types or use queues with custom objects. A queue is a Group with multiple QueueSobject records that map the queue to objects like cases, leads, or custom objects. However, once you associate a queue with more than one type of object, you must use the 8.0 API to access the queues. If you use an earlier version of the API, the Group records disappear because there is no valid value to put in the Type field of the Group object.
  • In all versions of the API, if you use the SOAP header AssignmentRuleHeader, the value specified for the AssignmentRuleId element must conform to the 15-character or 18-character Salesforce ID format, or a MALFORMED_ID exception is returned. Previously, the format was not validated.
  • Some picklists in the Salesforce user interface may demonstrate a change in the ordering of picklist items, but this should not affect any client application.
  • In version 7.0, Lead.FirstName and Lead.LastName are flagged as name fields and Lead.Name is available and not flagged as such. In 8.0 Lead.FirstName and Lead.LastName are not flagged as name fields while Lead.Name is flagged as such.
  • Ending Support for Weak SSL. Salesforce.com is ending support for the following on 3/31/07:
    • SSLv2 - SSLv2 has known vulnerabilities which render it insecure for all purposes. It was superceded 10 years ago by SSLv3. Implementations of SSLv3 are widely and freely available for all common development platforms.
    • SSLv3 and TLSv1 with key lengths less than 128 bits - Due to advances in cryptography and computing power, key lengths lower than 128-bits are no longer considered sufficient for long term security.
  • The following technical notes are available to assist you in migrating from versions earlier than 8.0:

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 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.
    • 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 Force.com platform. Be sure to visit

http://www.salesforce.com/services-training/education-services/public/developers/index.jsp

to learn more.

Retrieved from "http://wiki.developerforce.com/page/What%27s_New_in_Force.com_Web_Services_API_Winter_%2707"