40
Step 1: Obtain a Salesforce Developer Edition Account
If you are not already a member of the developer community, go to http://www.salesforce.com/signup/dev_signup.jsp and
follow the instructions for signing up for a Developer Edition account. Even if you already have an Enterprise Edition or
Unlimited Edition account, it is strongly recommended that you use Developer Edition for developing, staging, and testing
your solutions against sample data to protect your organization’s live data.This is especially true for applications that will be
inserting, updating, or deleting data (as opposed to simply reading data).
Step 2: Generate or Obtain the Web Service WSDL
To access the Force.comWeb service, you need a Web Service Description Language (WSDL) file.The WSDL file defines
the Web service that is available to you.Your development platform uses this WSDL to generate an API to access the Force.com
Web service it defines.You can either obtain the WSDL file from your organization’s Salesforce administrator or you can
generate it yourself if you have access to the WSDL download page in the Salesforce user interface. For more information
about WSDL, see http://www.w3.org/TR/wsdl.
WSDL Files for Web Services
There are two Force.comWeb services for which you can obtain WSDL files for API access:
• Force.com Enterprise Web Services API (enterprise WSDL)—This API is for most enterprise users who are developing
client applications for their organization.The enterprise WSDL file is a strongly typed representation of your organization’s
data. It provides information about your schema, data types, and fields to your development environment, allowing for a
tighter integration between it and the Force.comWeb service.This WSDL changes if custom fields or custom objects are
added to, renamed, or removed from, your organization’s Salesforce configuration.
• Force.com Partner Web Services API (partner WSDL)—This API is for salesforce.com partners who are developing
client applications for multiple organizations. As a loosely-typed representation of the Salesforce object model, this API
can be used to access data within any organization. For more information, see Using the Partner WSDL.
Generating the WSDL File for Your Organization
Any user with the “Modify All Data” permission can download the Web Services Description Language (WSDL) file to
integrate and extend Salesforce using the API. (The System Administrator profile has this permission.)
The WSDL file is dynamically generated based on which type of WSDL file (enterprise or partner) you download.The
generated WSDL defines all of the API calls, objects (including standard and custom objects), and fields that are available for
API access for your organization.
To generate the WSDL file for your organization:
1. Log in to your Enterprise, Unlimited, or Developer Edition Salesforce account.You must log in as an administrator or as
a user who has the “Modify All Data” permission. Logins are checked to ensure they are from a known IP address. For
more information, see Setting Login Restrictions in the Salesforce online help.
2. Click Setup, and then under App Setup, click Develop.
3. Click API to display the WSDL download page.
4. Right-click Enterprise WSDL to display your browser's save options, and save the enterprise WSDL to a local directory.
(For information about the partner WSDL, see Calls and the Partner WSDL.)
Note: For the enterprise WSDL file, if new custom fields or objects are added to, renamed, or removed from your
organization’s information, you need to regenerate the WSDL file in order to access them.
13
Step 1: Obtain a Salesforce Developer Edition Account
48
Step 3: Import the WSDL File Into Your Development Platform
Once you have the WSDL file, you need to import it into your development platform so that your development environment
can generate the necessary objects for use in building client Web service applications in that environment.This section provides
sample instructions for Apache Axis and Microsoft Visual Studio. For instructions about other development platforms, see
your platform’s product documentation.
Note: The process for importing WSDL files is identical for the enterprise and partner WSDL files.
Instructions for Java Environments (Apache Axis)
Java environments access the API through Java objects that serve as proxies for their server-side counterparts. Before using
the API, you must first generate these objects from your organization’s WSDL file.
Each SOAP client has its own tool for this process. For Apache Axis, use the WSDL2Java utility.
Note: Before you run WSDL2Java, you must have Axis installed on your system and all of its component JAR files
must be referenced in your classpath.
The basic syntax for WSDL2Java is:
java –classpath pathToJAR/Filename org.apache.axis.wsdl.WSDL2Java -a pathToWsdl/WsdlFilename
The
-a
switch generates code for all elements, referenced or not, which may be necessary depending on your WSDL. For
more information, see the WSDL2Java documentation.
If you have JAR files in more than one location, list them with a semicolon separating the files. For example, if the Axis JAR
files are installed in
C:\axis-1_3
, and the WSDL is named
my_enterprise.wsdl
and is stored in
C:\mywsdls
:
java –classpath
c:\axis-1_3\lib\axis.jar;c:\axis-1_3\lib\axi-ant.jar;c:\axis-1_3\lib\axis-schema.jar;
c:\axis-1_3\lib\commons-discovery-0.2.jar;c:\axis-1_3\lib\commons-logging-1.0.4.jar;
c:\axis-1_3\lib\jaxrpc.jar;c:\axis-1_3\lib\log4j-1.2.8.jar;c:\axis-1_3\lib\saaj.jar;
c:\axis-1_3\lib\wsdl4j-1.5.2.jar;
org.apache.axis.wsdl.WSDL2Java -a
C:\myswdls\my_enterprise.wsdl
This command will generate a set of folders and Java source code files in the same directory in which it was run. After these
files are compiled, they can be included in your Java programs for use in creating client applications.
For most Java development environments, you can use wizard-based tools for this process instead of the command line. For
more information about using WSDL2Java, see http://ws.apache.org/axis/java/reference.html. For more information about
using WSDL2Java with Force.com, visit the message boards at http://www.salesforce.com/developer/boards.jsp.
Instructions for Microsoft Visual Studio
Visual Studio languages access the API through objects that serve as proxies for their server-side counterparts. Before using
the API, you must first generate these objects from your organization's WSDL file.
Visual Studio provides two approaches for importing your WSDL file and generating an XML Web service client: an IDE-based
approach and a command line approach.
Note: Before you begin, the first step is to create a new application or open an existing application in Visual Studio.
In addition, you need to have generated the WSDL file, as described in Generating the WSDL File for Your
Organization.
14
Step 3: Import the WSDL File Into Your Development Platform
54
An XML Web service client is any component or application that references and uses an XML Web service.This does not
necessarily need to be a client-based application. In fact, in many cases, your XML Web service clients might be other Web
applications, such as Web Forms or even other XML Web services.When accessing XML Web services in managed code, a
proxy class and the .NET Framework handle all of the infrastructure coding.
To access an XML Web service from managed code:
1. Add a Web reference to your project for the XML Web service that you want to access.The Web reference creates a proxy
class with methods that serve as proxies for each exposed method of the XML Web service.
2. Add the namespace for the Web reference.
3. Create an instance of the proxy class and then access the methods of that class as you would the methods of any other class.
To add a Web reference:
1. On the Project menu, choose Add Web Reference.
2. In the URL box of the Add Web Reference dialog box, type the URL to obtain the service description of the XML Web
service you want to access, such as:
file:///c:\WSDLFiles\enterprise.wsdl
3. Click Go to retrieve information about the XML Web service.
4. In the Web reference name box, rename the Web reference to
sforce
, which is the namespace you will use for this Web
reference.
5. Click Add Reference to add a Web reference for the target XML Web service. For more information, see the topic “Adding
and Removing Web References” in the Visual Studio documentation.
6. Visual Studio retrieves the service description and generates a proxy class to interface between your application and the
XML Web service.
Note: If you are using Visual Basic .Net 1.1 and the enterprise WSDL, you will need to modify the generated Web
service client to overcome a bug in Visual Studio's client generation utility.The API exposes two objects (Case and
Event) whose names conflict with Visual Basic keywords.When the classes that represent these objects are created,
Visual Studio wraps the class names with brackets (
[Case]
and
[Event]
).This is the method by which you can reuse
keywords.
Unfortunately, in the definition of the
SObject
class,Visual Studio does not wrap these to class references in the
System.Xml.Serialization.XmlIncludeAttribute
that are part of the
SObject
definition.To work around this
problem in Visual Studio, you need to edit the
XmlIncludeAttribute
settings for Case and Event as shown below.This
does not apply to C# and only applies when using the enterprise version of the WSDL.
System.Xml.Serialization.XmlIncludeAttribute(GetType([Event])), _
System.Xml.Serialization.XmlIncludeAttribute(GetType([Case])), _
Step 4: Walk Through the Sample Code
Once you have imported your WSDL file, you can begin building client applications that use the API. Use the following
samples to create a basic client application. Comments embedded in the sample explain each section of code.
Java Sample Code
This section walks through a sample Java client application that uses the Apache Axis SOAP client.The purpose of this sample
application is to show the required steps for logging into the login server and to demonstrate the invocation and subsequent
handling of several API calls.This sample application performs the following main tasks:
15
Step 4:Walk Through the Sample Code
68
1. Prompts the user for their Salesforce username and password.
2. Calls
login()
to log in to the single login server and, if the login succeeds:
• Sets the returned
sessionId
into the session header, which is required for session authentication on subsequent API
calls.
• Resets the endpoint to the returned
serverUrl
, which is the target of subsequent API calls.
All client applications that access the API must complete the tasks in this step before attempting any subsequent API
calls.
3. Calls
describeGlobal()
to retrieve a list of all available objects for the organization’s data.
4. Calls
describeSObject()
to retrieve metadata (field list and object properties) for a specified object.
5. Calls
query()
, passing a simple query string ( "
select FirstName, LastName from Contact
"), and iterating
through the returned QueryResult.
Note the error handling code that follows each API call.
//The sample client application begins by importing the necessary packages and objects.
package com.doc.samples;
import java.io.*;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import com.sforce.soap.enterprise.*;
import com.sforce.soap.enterprise.fault.ExceptionCode;
import com.sforce.soap.enterprise.fault.LoginFault;
import com.sforce.soap.enterprise.sobject.Contact;
/**
* Title: Login Sample
*
* Description: Console application illustrating login, session management,
* and server redirection.
*
* Copyright: Copyright (c) 2005
* Company: salesforce.com
*
* @version 7.0
*/
public class Samples {
private SoapBindingStub binding;
static BufferedReader rdr = new BufferedReader(new InputStreamReader(System.in));
public Samples() {
}
public static void main(String[] args) throws ServiceException {
Samples samples1 = new Samples();
samples1.run();
}
//The sample client application retrieves the user's login credentials.
// Helper function for retrieving user input from the console
String getUserInput(String prompt) {
System.out.print(prompt);
try {
return rdr.readLine();
}
catch (IOException ex) {
return null;
}
}
16
Step 4:Walk Through the Sample Code
67
/**
* The login call is used to obtain a token from Salesforce.
* This token must be passed to all other calls to provide
* authentication.
*/
private boolean login() throws ServiceException {
String userName = getUserInput("Enter username: ");
String password = getUserInput("Enter password: ");
/** Next, the sample client application initializes the binding stub.
* This is our main interface to the API through which all
* calls are made. The getSoap method takes an optional parameter,
* (a java.net.URL) which is the endpoint.
* For the login call, the parameter always starts with
* http(s)://www.salesforce.com. After logging in, the sample
* client application changes the endpoint to the one specified
* in the returned loginResult object.
*/
binding = (SoapBindingStub) new SforceServiceLocator().getSoap();
// Time out after a minute
binding.setTimeout(60000);
// Test operation
LoginResult loginResult;
try {
System.out.println("LOGGING IN NOW....");
loginResult = binding.login(userName, password);
}
catch (LoginFault ex) {
// The LoginFault derives from AxisFault
ExceptionCode exCode = ex.getExceptionCode();
if (exCode == ExceptionCode.FUNCTIONALITY_NOT_ENABLED ||
exCode == ExceptionCode.INVALID_CLIENT ||
exCode == ExceptionCode.INVALID_LOGIN ||
exCode == ExceptionCode.LOGIN_DURING_RESTRICTED_DOMAIN ||
exCode == ExceptionCode.LOGIN_DURING_RESTRICTED_TIME ||
exCode == ExceptionCode.ORG_LOCKED ||
exCode == ExceptionCode.PASSWORD_LOCKOUT ||
exCode == ExceptionCode.SERVER_UNAVAILABLE ||
exCode == ExceptionCode.TRIAL_EXPIRED ||
exCode == ExceptionCode.UNSUPPORTED_CLIENT) {
System.out.println("Please be sure that you have a valid username
and password.");
} else {
// Write the fault code to the console
System.out.println(ex.getExceptionCode());
// Write the fault message to the console
System.out.println("An unexpected error has occurred." + ex.getMessage());
}
return false;
} catch (Exception ex) {
System.out.println("An unexpected error has occurred: " + ex.getMessage());
ex.printStackTrace();
return false;
}
// Check if the password has expired
if (loginResult.isPasswordExpired()) {
System.out.println("An error has occurred. Your password has expired.");
return false;
}
/** Once the client application has logged in successfully, it will use
* the results of the login call to reset the endpoint of the service
* to the virtual server instance that is servicing your organization.
* To do this, the client application sets the ENDPOINT_ADDRESS_PROPERTY
* of the binding object using the URL returned from the LoginResult.
*/
binding._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_PROPERTY,
17
Step 4:Walk Through the Sample Code
67
loginResult.getServerUrl());
/** The sample client application now has an instance of the SoapBindingStub
* that is pointing to the correct endpoint. Next, the sample client application
* sets a persistent SOAP header (to be included on all subsequent calls that
* are made with the SoapBindingStub) that contains the valid sessionId
* for our login credentials. To do this, the sample client application
* creates a new SessionHeader object and set its sessionId property to the
* sessionId property from the LoginResult object.
*/
// Create a new session header object and add the session id
// from the login return object
SessionHeader sh = new SessionHeader();
sh.setSessionId(loginResult.getSessionId());
/** Next, the sample client application calls the setHeader method of the
* SoapBindingStub to add the header to all subsequent method calls. This
* header will persist until the SoapBindingStub is destroyed until the header
* is explicitly removed. The "SessionHeader" parameter is the name of the
* header to be added.
*/
// set the session header for subsequent call authentication
binding.setHeader(new SforceServiceLocator().getServiceName().getNamespaceURI(),
"SessionHeader", sh);
// return true to indicate that we are logged in, pointed
// at the right url and have our security token in place.
return true;
}
/**
* To determine the objects that are available to the logged-in user, the sample
* client application executes a describeGlobal call, which returns all of the
* objects that are visible to the logged-in user. This call should not be made
* more than once per session, as the data returned from the call likely does not
* change frequently. The DescribeGlobalResult is simply echoed to the console.
*/
private void describeGlobalSample() {
try {
DescribeGlobalResult describeGlobalResult;
describeGlobalResult = binding.describeGlobal();
String[] types = describeGlobalResult.getTypes();
for (String type : types) System.out.println(type);
getUserInput("\nDescribe global was successful.\n\nHit the enter key
to continue....");
}
catch (Exception ex) {
System.out.println("\nFailed to return types, error message was: \n"
+ ex.getMessage());
getUserInput("\nHit return to continue...");
}
}
/**
* The following code segment illustrates the type of metadata information that
* can be obtained for each object available to the user. The sample client
* application executes a describeSObject call on a given object and then echoes
* the returned metadata information to the console. Object metadata information
* includes permissions, field types and length and available values for picklist
* fields and types for referenceTo fields.
*/
private void describeSample() {
String objectToDescribe = getUserInput("\nType the name of the object to
describe (try Account): ");
try {
DescribeSObjectResult descSObjectRslt;
descSObjectRslt = binding.describeSObject(objectToDescribe);
if (descSObjectRslt != null) {
// Report object level information
Field[] fields = descSObjectRslt.getFields();
18
Step 4:Walk Through the Sample Code
Documents you may be interested
Documents you may be interested
