1. Using Web Services
  2. Quick Start

Quick Start

You will need a User Account with "Web Service" permissions to be able to access and use the API. If you do not have such an account, contact your System Administrator to request one.

The following steps will create a sample application in your development environment:

Step 1: Obtain and Activate a Taleo User Account

To access the API you need to have an activated Taleo User Account. While developing, staging, and testing your application, we strongly recommend to use a dedicated testing or staging application to test your application against sample data instead of 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). Your System Administrator will provide you with a login username and password for your product environment.

Step 2: Obtain the Web Services WSDL Files

To access the API, you need the Web Service Description Language (WSDL) files corresponding to the Web Services. A WSDL file defines a Web service that is available to you. Your development platform uses this WSDL to generate an API to access the Web service it defines. Each Web service available through the Taleo product is defined by a dedicated WSDL file. You can either obtain the WSDL files from your Customer Representative or you can generate them yourself if you have access to the WSDL download page in the Taleo product user interface. For more information about WSDL, see http://www.w3.org/TR/wsdl.

To obtain the WSDL File for Your Organization

The WSDL file is dynamically generated based on which Taleo product (i.e. Taleo Enterprise) you download. The generated WSDL defines all API calls, objects (including standard and common objects), and fields that are available for API access for your organization.

To generate the WSDL file for your organization:

  • Log in to your account using the URL specified in the data dictionary corresponding to your Taleo product.

  • You should see a list of Web services available for this product. If the Web service you are looking for is not in the list, you may not have enough privileges to access it, you may be using the wrong URL for the Product, or you are searching for a deprecated Web service that has been removed or replaced by another one since the last major version.

  • Right-click the Web service name to display your browser's save options, and save the WSDL to a local directory.

Note: If a new version of the data dictionary (Product API) is released, you will need to regenerate the WSDL file in order to access the newest call and type definitions.

Step 3: Import the WSDL Files 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.

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 Web service's WSDL file. If you are using more than one Web service in your application, you must generate these objects from each WSDL file.

Each SOAP Java client has its own tool for this process. For Apache Axis2, use the WSDL2Java utility.

Note: Before you run WSDL2Java, you must have Axis2 installed on your system.

The basic syntax for WSDL2Java from the Axis2 InstallPath/bin is:

wsdl2java.bat -uri pathToWsdl/WsdlFilename -d xmlbeans -ns2p namespaceURL=javaPackageName

The -d specifies the Databinding framework; here xmlbeans (http://xmlbeans.apache.org) is used. The -ns2p specifies a comma separated list of namespaces and packages where the given package will be used in the place of the auto generated package for the relevant namespace. For more information, see the WSDL2Java documentation.

Taleo strongly recommends to always specify a different target package name for each WSDL file (or Web service) because different WSDL files may refer to the same data type name although using different data type definition. Specifying different Java package names will prevent Java class name collisions when more than one Taleo Web service is used within the same application.

For example, if the Axis JAR files are installed in C:\axis2-1_3, and the WSDL is named CandidateService.wsdl and is stored in C:\mywsdls, and you want to map the Web service mapping version http://www.taleo.com/ws/art750/2006/12 to a specific com.taleo.art750.candidate package, you would invoke:

C:\axis2-1.3\bin\wsdl2java.bat -uri C:\mywsdls\CandidateService.wsdl -d xmlbeans -ns2p http://www.taleo.com/ws/art750/2006/12=com.taleo.art750.candidate,http://www.taleo.com/ws/integration/toolkit/2005/07=com.taleo.itk

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

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 Web service's WSDL file. If you are using more than one Web service in your application, you must generate these objects from each WSDL file.

Visual Studio provides two approaches for importing a WSDL file and generating an XML Web service client: an IDE-based approach and a command line approach.

Note: Before you begin, you must create a new application or open an existing application in Visual Studio. In addition, you need to have generated the WSDL file(s), as described in Step 3: Generate or Obtain the Web Services WSDL Files.

A Visual Studio 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\CandidateService.wsdl or https://hostname/servlets/soap?ServiceName=CandidateService&wsdl.

  3. Click Go to retrieve information about the XML Web service.

  4. In the Web reference name box, rename the Web reference, such as taleo.candidatesvc, 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.

To import other Web services in your application, follow the same procedure described above for each WSDL file.

For a walk through of sample code that uses the WSDL generated stub, refer to the Appendix WebServices Client Sample Code section.