SFAPI Functional Guide 1308

7/17/2019 SFAPI Functional Guide 1308

http://slidepdf.com/reader/full/sfapi-functional-guide-1308 1/80

SFAPI Functional Guide




Page 2 of 80 Copyright ©2013 SuccessFactors, Inc.

©2012 SuccessFactors, Inc. All rights reserved.

No part of this manual may be reproduced or transmitted in any form or by anymeans, electronic or mechanical, without the express written permission ofSuccessFactors. This software is commercial computer software developedexclusively at private expense. The software and documentation are provided with

RESTRICTED RIGHTS. Use, duplication or disclosure by the U.S. Government issubject to restrictions as set forth in DFARS 252.227.7202-3 or FAR 52.227-19, asapplicable. Developer is SuccessFactors Inc., 1500 Fashion Island Blvd, Suite 300,San Mateo, CA 94404.

The product described herein includes software developed by the Apache SoftwareFoundation (http://www.apache.org/). All other brand and product names that arementioned herein are the trademarks or registered trademarks of their respectiveholders.

All examples, including the names of people in the examples or screen shots, arefictitious. No association with any real person (living or deceased), company (existing

currently or in the past), or events should be inferred from any example whatsoever.Information in this document is subject to change without notice and does notrepresent a commitment on the part of SuccessFactors.

Release Information:

Release Date: June, 2013

Product Version: 1308

SuccessFactors, Inc. 1500 Fashion Island Blvd, Suite 300

San Mateo, CAUSA

Website: www.successfactors.com

http://www.successfactors.com/







All rights reserved. Page 3 of 80

Table of Contents1

Introduction to SFAPI ............................................................................................................................7

1.1

Overview .......................................................................................................................................7

1.2

Background ..................................................................................................................................7

1.3

API Endpoints ...............................................................................................................................7

1.3.1 Endpoint URLs ................................................................................................................................ 7

1.4

WSDL ...........................................................................................................................................8

2

Using SFAPI ...........................................................................................................................................9

2.1

SFAPI Setup .................................................................................................................................9

2.1.1

Enabling SFAPI ............................................................................................................................... 9

2.1.2 API Login Permission ...................................................................................................................... 9

2.1.2.1 Granting API Login Permission in the Traditional (aka User-Based) Permission System ........ 9

2.1.2.2

Granting API Login Permission in the Role Based Permission System ................................. 10

2.1.3 Setting Password Policy Exceptions ............................................................................................. 11

2.1.4

Data Specific Permissions ............................................................................................................. 13

2.2

Connecting to the API .................................................................................................................14

2.2.1 Authentication ................................................................................................................................ 14

2.2.2 Authorization ................................................................................................................................. 14

2.2.3 Handling HTTP Cookies ................................................................................................................ 14

2.3

Integration Tools .........................................................................................................................14

2.3.1 API Audit Log ................................................................................................................................ 14

2.3.2 API Metering Details ...................................................................................................................... 15

2.3.3

API Data Dictionary ....................................................................................................................... 15

2.3.4

Permission Controls on Integration Tools ...................................................................................... 15

2.3.4.1 User Based Permission System ............................................................................................ 15

2.3.4.1.1

Accessing Administrative Privileges Page in New Admin Tools ............................................................. 15

2.3.4.1.2

Accessing Administrative Privileges Page in Old Admin Tools ............................................................... 16

2.3.4.1.3

Setting Permissions in the Administrative Privi leges Page ..................................................................... 16

2.3.4.2 Role Based Permission System ............................................................................................. 17

2.3.5 Accessing the Integration Tools .................................................................................................... 17

2.3.5.1 API Audit Log ......................................................................................................................... 18

2.3.5.2

API Metering Details .............................................................................................................. 19

2.3.5.3

API Data Dictionary ............................................................................................................... 20

2.4

API Thresholds and Limits ..........................................................................................................21

3

SFAPI Operations ................................................................................................................................22

3.1

API Summary..............................................................................................................................22

3.1.1 Session Management Operations ................................................................................................. 22

3.1.2 MetaData Operations .................................................................................................................... 22

3.1.3 Data Manipulation Operations ....................................................................................................... 22

3.1.4 Data Query Operations ................................................................................................................. 23

3.1.5 Async Job Operations ................................................................................................................... 23





3.2 Session Management Operations ...............................................................................................24

3.2.1

API Signature Description ............................................................................................................. 24

3.2.2

API Framework Objects ................................................................................................................ 24

3.2.2.1 LoginResult ........................................................................................................................... 24

3.2.2.2 SFCredential ......................................................................................................................... 24

3.2.2.3 SFParameter ......................................................................................................................... 25

3.2.3

Login ............................................................................................................................................. 25

3.2.3.1 Supported Parameters .......................................................................................................... 25

3.2.3.2

Optional SFParameter Values For Login .............................................................................. 25

3.2.3.3 Example Java Code .............................................................................................................. 26

3.2.3.4 Example SOAP Request XML ............................................................................................... 27

3.2.3.5 Example SOAP Response XML ............................................................................................ 27

3.2.3.6 Example SOAP Failed Response ......................................................................................... 28

3.2.4 LogOut .......................................................................................................................................... 28


3.2.4.2

Example Java Code .............................................................................................................. 28



3.2.4.5

Example SOAP Failed Response ......................................................................................... 29

3.3 MetaData Discovery Methods .....................................................................................................29

3.3.1 API Signature ................................................................................................................................ 30

3.3.2

API Framework Objects ................................................................................................................ 30

3.3.2.1

DescribeResult ...................................................................................................................... 30

3.3.2.2

Field Object ........................................................................................................................... 31

3.3.2.3 Field Object Data Types ........................................................................................................ 31

3.3.2.4 Picklist ................................................................................................................................... 32

3.3.2.5 Picklist Option ....................................................................................................................... 32

3.3.2.6 Label ..................................................................................................................................... 33

3.3.3

List ................................................................................................................................................ 34

3.3.3.1

Supported Parameters .......................................................................................................... 34

3.3.3.2


3.3.3.3 Example SOAP Request XML .............................................................................................. 34


3.3.4 Describe ....................................................................................................................................... 35

3.3.4.1

Supported Parameters .......................................................................................................... 36

3.3.4.2


3.3.4.3

Example SOAP Request XML ............................................................................................... 37



3.3.5 DescribeEx ................................................................................................................................... 39


3.3.5.2


3.3.5.3

Example SOAP Response XML ............................................................................................ 40


3.4

Data Manipulation Operations ....................................................................................................42

3.4.1 API Signature ................................................................................................................................ 42

3.4.2 API Framework Objects ................................................................................................................ 43

3.4.2.1 SFObject ............................................................................................................................... 43

3.4.2.2 SFParameter ......................................................................................................................... 43

3.4.2.3

InsertResult/UpdateResult/DeleteResult/UpsertResult ......................................................... 44





3.4.2.4 ObjectEditResult .................................................................................................................... 44

3.4.3 Insert ............................................................................................................................................. 45

3.4.3.1 Supported Parameters ........................................................................................................... 45

3.4.3.2 Example Java Code ............................................................................................................... 46


3.4.3.4 Example SOAP Response XML ............................................................................................. 48

3.4.3.5

Example SOAP Failed Response .......................................................................................... 48

3.4.4 Update ........................................................................................................................................... 49




3.4.4.4 Example SOAP Failed Response .......................................................................................... 51

3.4.5 Upsert ............................................................................................................................................ 52



3.4.5.3


3.4.5.4

Example SOAP Response XML ............................................................................................. 55


3.4.6

Delete ............................................................................................................................................ 56 3.4.6.1 Supported Parameters ........................................................................................................... 56


3.4.6.3


3.4.6.4

Example SOAP Response XML ............................................................................................. 58


3.5

Data Query Operations ...............................................................................................................59

3.5.1 API Signature ................................................................................................................................. 59

3.5.2 API Framework Objects ................................................................................................................. 60

3.5.2.1 QueryResult ........................................................................................................................... 60

3.5.3 Query ............................................................................................................................................ 60

3.5.3.1

Supported Parameters ........................................................................................................... 61

3.5.3.2

Optional SFParameter Values For Query .............................................................................. 61





3.5.4 QueryMore .................................................................................................................................... 65

3.5.4.1

Supported Parameters ........................................................................................................... 66

3.5.4.2

Example Java Code ............................................................................................................... 66




3.5.5 SuccessFactors Query Language ................................................................................................. 68

3.5.5.1

Overview ................................................................................................................................ 68

3.5.5.2

SFQL Grammar ..................................................................................................................... 68

3.6

Async Job Operations .................................................................................................................69

3.6.1 API Signature ................................................................................................................................ 69

3.6.2 API Framework Objects ................................................................................................................ 70

3.6.2.1 TaskStatus ............................................................................................................................. 70

3.6.3 SubmitQueryJob ............................................................................................................................ 71









3.6.4 GetJobStatus ................................................................................................................................ 73



3.6.4.3


3.6.5 GetJobResult ................................................................................................................................ 75




3.6.5.4 Example SOAP Response .................................................................................................... 75

3.6.6 ListJobs ........................................................................................................................................ 76



3.6.6.3

Example SOAP Request XML .............................................................................................. 77

3.6.6.4


3.6.7 CancelJob ..................................................................................................................................... 79

3.6.7.1

Supported Parameters .......................................................................................................... 79 3.6.7.2 Example Java Code .............................................................................................................. 79


3.6.7.4






1 Introduction to SFAPI

1.1Overview

This document is the functional guide for SFAPI developers. This guide provides anoverview of the SFAPI, technical information on how to use the SFAPI, details of the WebService methods and the framework objects.

1.2 Background

The SFAPI is SuccessFactors Data API. It is a SOAP Web Service designed for importingand exporting data to and from your SuccessFactors instance. It provides generic CRUD(Create, Read, Update, Delete) operations to access data, as well as meta-data operationsto allow runtime discovery of the data.

Data are exposed as entities called SFObjects, which are conceptually analogous todatabase tables. Using the meta-data operations, you can list the SFObjects available tothe API, and describe the fields in these entities. Using the CRUD operations you canquery or edit the data.

The combination of CRUD style data access operations along with meta-data drivenoperations for data discovery provides a generic API that offers the following benefits:

1. Provide a consistent mechanism for accessing data in the SuccessFactorsplatform.

2. Provide a mechanism to describe the data schema configuration, including theentities that are available and fields that appear in these entities.

3. Avoid WSDL changes with each release.

1.3 API Endpoints

Your API endpoint will depend on where your SuccessFactors instance is located. It canbe in one of several data centers. Please contact your SuccessFactors representative ifyou are unsure of which data center to use. The endpoints by data center are listed below.

1.3.1 Endpoint URLs

Each data center provides two endpoints, one for SOAP version 1.1 support and another

for SOAP version 1.2 support.

Region

Data Center DC#

Site

URLs

EMEA

Amsterdam( ASM-2)

2

EUProduction

(Premium)

https://api.successfactors.eu/sfapi/v1/soap https://api.successfactors.eu/sfapi/v1/soap12 https://api2.successfactors.eu/sfapi/v1/soap https://api2.successfactors.eu/sfapi/v1/soap12 (Both https://api.successfactors.eu and

https://api.successfactors.eu/sfapi/v1/soap


https://api.successfactors.eu/sfapi/v1/soap12


https://api2.successfactors.eu/sfapi/v1/soap


https://api2.successfactors.eu/sfapi/v1/soap12


https://api.successfactors.eu/












https://api2.successfactors.eu resolve to the same servers) US

Arizona

4

AZProduction

(Standard)

https://api4.successfactors.com/sfapi/v1/soap

https://api4.successfactors.com/sfapi/v1/soap12

AZ

Salesdemo

https://salesdemo4.successfactors.com/sfapi/v1/soap

https://salesdemo4.successfactors.com/sfapi/v1/soap12 EMEA

Amsterdam

(ASM-5)

5

EUProduction

(Standard)



US

Ashburn

8

AshburnProduction

(Premium)



AshburnSalesdemo

https://apisalesdemo8.successfactors.com/sfapi/v1/soap

https://apisalesdemo8.successfactors.com/sfapi/v1/soap12 APJ

Sydney

10

SydneyProduction

(Premium)



EMEA

Rot

12

RotProduction

(Standard)



1.4 WSDL

The WSDL can be accessed by appending "?wsdl" to any of the endpoints listed above.For example: https://api4.successfactors.com/sfapi/v1/soap?wsdl

https://api2.successfactors.eu/








https://salesdemo4.successfactors.com/sfapi/v1/soap12












https://apisalesdemo8.successfactors.com/sfapi/v1/soap12










https://api4.successfactors.com/sfapi/v1/soap?wsdl























2 Using SFAPI

2.1SFAPI Setup

2.1.1 Enabling SFAPI

In order to use the SFAPI, SuccessFactors must enable the API for your companyinstance. Please contact your SuccessFactors support representative details to enable theSFAPI for your instance.

2.1.2 API Login Permission

Each user of the API must have API Login Permission. An administrator of yourSuccessFactors system can grant this permission. The permission setting in the UI isManage Users > API Login Permission. Setting this permission depends on whichpermission system you are using in your SuccessFactors instance. Below are instructionsfor each permission system.

2.1.2.1 Granting API Login Permission in the Traditional (aka User-Based)Permission System

API Login Permission is granted in the Admin Tools > Manage Users > Manage API LoginPermission link. This link is highlighted in the following page.





2.1.2.2 Granting API Login Permission in the Role Based PermissionSystem

API Login Permission in the Role Based Permission system is listed under the General

User Permission category in the Permission settings page. See below.





2.1.3 Setting Password Policy Exceptions

Your SuccessFactors administrator has control on setting password policies for all users in

the system, including timing on password expirations. This can be a nuisance to managefor your integrations which are typically built against a specially designated API useraccount, where you don’t want to update the passwords on these accounts with the samefrequency of the general user population.

For this reason you can set exceptions to the password policy for your API user, andspecify a different password expiration (maximum password age) policy. Since this is atradeoff in security, we add in a requirement that users which have password policyexceptions (which relaxes security) must have an IP address restriction in order to connectto the API (which increases security).

Password policy exceptions are set in Admin Tools Company Settings Password &

Login Policy Settings. Select the link labeled “Set API login exceptions…” as seen below.





This will expand a section on the page as seen below.

To add API login exception to the password policy, select the “ Add” button in the top left ofthe expanded section. This will bring up the following dialog.





Here you can add a user-specify password expiration. You must provide a username, and the desiredmaximum password age in days (-1 means the password will not expire, though we do not recommendthis). You must also provide IP address restrictions for this user.

2.1.4 Data Specific PermissionsIn addition to API Login Permission, there are permissions that control access to data inthe SFAPI. The permissions vary depending on the data being access. Please see the APIENTITY TYPE GUIDE (LINK HERE) for detailed description of all SF data entities,including the permissions required for each entity.

For example, in order to Query the User entity in the SFAPI, you must have theadministrative permission of "Employee Export". In order to Insert, Update, or Upsert rowsin the User entity, you must have administrative permission of "Employee Import."





2.2 Connecting to the API

2.2.1 Authentication

Authentication is established through the Login operation. A successful login will return asession ID as an HTTP Cookie. This cookie must be passed back to all subsequent HTTPRequests that invoke API operations in order to authenticate.

The API session will timeout after 10 minutes of inactivity. You can also manuallyinvalidate a session using the Logout method.

2.2.2 Authorization

Access to different objects in the API will require the related permissions for authorization. Authorizations in the SFAPI are administrative in nature. This means that the permissionsrequired to access data through the SFAPI are appropriate for administrative access,

granting access to broad sets of data. These permission are not appropriate for end users.For example, to insert to the User entity, you need to grant the "Import Employee"administrative permission by using Admin Tools > Manage Security > AdministrativePrivileges > Manage Users > Import Employee to the SFAPI user link.

This makes the SFAPI useful for data integrations between systems. However the SFAPIdoes not provide use cases appropriate for non-administrative access (aka – normal endusers).

Refer to the SFAPI Data Dictionary documentation to understand the permissions requiredfor various API operations on each entity.

2.2.3 Handling HTTP CookiesThe SFAPI is state aware, and there are several cookies that must be handled. One is forthe login session as noted above. Another cookie is for load balancing in the data center.In the future there may be other cookies that must be handled.

API clients must be able to handle cookies.

2.3 Integration Tools

There are three tools that can be used to monitor traffic and/or get detailed payloadinformation about API requests made to your system and to understand the SF data

model.

2.3.1 API Audit Log

The API Audit log captures payload details for the last 10,000 API calls. This log allowsyou to inspect exactly the API payload request made to the system and the corresponding API response sent by the system. The API Audit Log is intended to help with support anddebugging of API usage. The intended end user will be a developer who is using the APIduring an implementation or an administrator who can share information in this log with





SuccessFactors support to help resolve API related support issues. The tool allows you todownload data from individual calls, which you could then send to a SuccessFactorssupport representative.

IMPORTANT: The API Audit Log allows access to potentially sensitive data and therefore,access to this should be limited to only trusted users.

2.3.2 API Metering Details

The API Metering Details page will give you analytics on your API usage for the last 30days. You can use this page to see API call history analytics like how many times the APIwas called, or what was the total record counts accessed in your system.

2.3.3 API Data Dictionary

The API Data Dictionary page will give you access to a list of all data entities in your SFinstance. The Data Dictionary displays the field meta data for each entity in a convenient,readable format.

Note that in November, 2012 we plan to release a separate document API ENTITY TYPEGUIDE, which will give entity specific details like business context and permissionconfiguration details for each entity

2.3.4 Permission Controls on Integration Tools

Permission to access any of the Integration Tools pages must be granted for eachindividual tool by an administrator of your SuccessFactors system. Granting access to theIntegration Tools pages depends on which permission system you are using in yourSuccessFactors instance. The following are instructions for each permission system.

2.3.4.1 User Based Permission SystemPermission to access the Integration Tools is granted by an administrator of yourSuccessFactors instance. These permissions can be found in the “AdministrativePrivileges” page. This location of this page depends on which Admin Tools version you areusing:

2.3.4.1.1 Accessing Administrative Privileges Page in New Admin Tools

The Administrative Privileges page is accessed through the Administrative Privileges linkfound under the Set User Permissions icon, as seen below:





2.3.4.1.2 Accessing Administrative Privileges Page in Old Admin Tools

If you are using the Old Admin Tools page, the Administrative Privileges page is accessedthrough the Manage Security > Administrative Privileges link as seen below

2.3.4.1.3 Setting Permissions in the Administrative Privileges Page

Once you are on the Administrative Privileges page, you can set permission to access theIntegration Tools through the following steps:

1. Search for a user and select the checkbox for the user.





2. Select the Integration Tools link.

3. Select the checkbox to access the desired Integration Tools, as shown.

4. Select the button Save Admin Permission for Selected Users.

2.3.4.2 Role Based Permission System

In the Role Based Permission system, the permission to Access to Integration Tools is inthe Manage Integration Tools section of the Permissions settings page.

2.3.5 Accessing the Integration Tools

The Integration Tools that a user has been granted permission to access will be visible aslinks under Integration Tools in the older version of Admin page as shown





The links can be accessed from here in the new Admin Page as shown.

2.3.5.1 API Audit Log

Selecting the API Audit Log brings up the following page.





This page will show the last 10,000 API calls to this system. For each call, you can viewthe actual payload of data sent across. For example, if a call was to import Users, youcould see the user data that was sent in the import call. The payload information can beviewed by selecting the button under the "SOAP" or "HTTP" columns in the log table. Thiswill show you the actual SOAP payload or the raw HTTP payload details.

IMPORTANT: Since this is sensitive data, care should be taken when granting permissionon who can see this audit log.

One safe strategy would be to grant this feature to developers only when necessary fordevelopment and debugging purposes, and then remove access to this feature.

NOTE: that the log will always be captured, regardless of whether a particular user maysee the log or not. Therefore, removing a user's access to the log will not remove theactual data in the log.

2.3.5.2 API Metering DetailsSelecting the API Metering Details link will bring up the following page.





You can view API call history in time intervals selected at the top of the screen, rangingfrom 6 hours to 30 days. Here we have a selected a 6 hour time interval. You can also varythe information presented by using the text drop-down at the top left of the screen. Herewe have selected "Call Count". You can also view record count (useful to see how manyrows of data were accessed in either import or queries), bandwidth, and call processingtime statistics..

2.3.5.3 API Data Dictionary

Selecting the API Data Dictionary link will bring up the following page.

This will allow you to view all the entities and fields as configured in your instance of SF.Note that in November, 2012 we plan to release a separate document API ENTITY TYPEGUIDE, which will give entity specific details like business context and permissionconfiguration details for each entity.





2.4 API Thresholds and Limits

There are several thresholds and limitations in the SFAPI.

# Thresholds and Limits

1 By default, a maximum of 200 rows will beprocessed in a singleInsert/Update/Upsert/Delete method. Thisnumber can be set to a value from 1 to 800 byspecifying the batchSize parameter for insert,update, upsert or delete operations, or in thelogin method, which sets the default batchSizefor the session.

2 By default, a maximum of 200 rows will bereturned in a single Query/QueryMore method.

This number can be set to a value from 1 to800 by specifying the maxRows parameter inthe query method.

3 A maximum SOAP message size (HTTPcontent-size) cannot exceed 5MB. This is thelimit when upload binary attachment usingSFAPI. In general, the total attachment storagesize is controlled by the attachment storageconfiguration of the company instance





3 SFAPI Operations

3.1API Summary

The SFAPI is intended to address import and export of SuccessFactors data. It is designedin a generic approach. The data that you can access from the API is not defined in theWSDL. Instead you can use the API metadata operations to discover the data and itsschema in your SuccessFactors instance.

There are five categories of methods in the API:

1. Session Management (login/logout/isValidSession)2. MetaData Inspection (list/describe)3. Data Manipulation (insert/update/upsert/delete)4. Data Query (query/queryMore)

5. Async Job (submitJob/getJobStatus/getJobResult/listJobs/cancelJob)Each of the operations above are documented in detail in the following sections.

3.1.1 Session Management Operations

LoginResult login( SFCredential credential, List<SFParameters> params)

Creates the SFAPI session.

boolean logout()

Destroys the current API session.

boolean isValidSession()

Returns true if the current API session is still valid.

3.1.2 MetaData Operations

String[] list()

List the entities in your company instance.

DescribeResult describe(String type[], SFParameter params[])

Returns metadata about the list of entities specified in the type parameter (both field andentity information).

DescribeExResult describeEx(String type[], SFParameter params[])This method is in beta development and and is not stable yet. It will stabalize in the 1109release. It will be an extended version of the describe method.

3.1.3 Data Manipulation Operations

The four data manipulation operations are equivalent to the SQL operations of insert,update, and delete, plus a combination of insert and update.





InsertResult insert(String type, SFObject[] objects, SFParameter[] processingParam)

Inserts the objects of the specified entity type. The operation will resume if one row hasfailed to insert.

UpdateResult update(String type, SFObject[] objects, SFParameter[] processinParam)

Updates the objects of the specified entity type. The operation will resume if one row hasfailed to update.

UpsertResult upsert(String type, SFObject[] objects, SFParameter[] processingParam)

Inserts or updates the objects of the specified entity type. If the row doesn't exist, performthe insert operation, if the row exists, perform the update operation. The operation willresume if one row has failed to upsert.

DeleteResult delete(String type, SFObject[] objects, SFParameter[] processingParam)

Deletes the SFObjects specified by the type and the objects. The operation will resume ifone row has failed to delete.

3.1.4 Data Query Operations

QueryResult query(String queryString, SFParameter[] param)

Queries the SuccessFactors platform with the given query string in SFQL (SuccessFactorsQuery Language). For a detailed grammar description, please check the related section inthis reference guide.

QueryResult queryMore(String querySessionId)

The queryMore call is provided to support paging. It requires a querySessionId to identifythe next page of results. The querySessionId is a parameter of the QueryResult object,obtained from a previous call to either the query or queryMore operation.

3.1.5 Async Job Operations

TaskStatus submitQueryJob(String queryString, SFParameter[] param)

Submit the asynchronous query job to the SuccessFactors platform with the given querystring in SFQL (SuccessFactors Query Language). TaskStatus includes “taskId” which isused to identify a submitted job. For a detailed grammar description, please check therelated section in this reference guide.

TaskStatus getJobStatus(String taskId)

Get the execution status of the submitted asynchronous job.

DataHandler getJobResult(GetJobResult parameters)

Download the result of submitted asynchronous query job.

TaskStatus[] listJobs()





List all Jobs which are in running or waiting to run.

TaskStatus cancelJob(String taskId)

Download the result of submitted asynchronous query job.

3.2 Session Management OperationsBefore accessing any SuccessFactors data, you must establish a login session. You canprogrammatically check to validate that you are in a login session and logout at the end ofthe session to maximize application security. Session management operations include:

3.2.1 API Signature Description

Si nature Descri tion

Boolean isValidSession Validate that the session is still o erational.

LoginResult login(SFCredential) Create an API login session.

Lo outResult lo out Destro the lo in session.

3.2.2 API Framework Objects

The following objects are used in the session management operations.

3.2.2.1 LoginResult

Extended from the SFObject.

3.2.2.2 SFCredential

Name Description ompanyId Identifies the SuccessFactors client instance.

developerKey NOT USED. Leave it blank.

password The password associated with the username.

Name Descri tion error List of the error messages which occurred in the login process.

msUntilPwdExpiration The number of the ms (milliseconds) until the password will expire.

sessionId The sessionId of the created session.





username Username for a valid user in the specified client instance. The user should have API Login Permission, and permissions to access any desired data. See moredetails in the Security

Overview section in the chapter on Using SFAPI.

3.2.2.3 SFParameter

SFParameter is a generic name/value container object, with the following fields:

Name Descri tion

Name The parameter name.

alue The arameter value.

3.2.3 Login

LoginResult login( SFCredential credential, List<SFParameters> params)

Creates the SFAPI session. A successful API session is required for any subsequent APIcalls.

3.2.3.1 Supported Parameters

Name Type Description

credential SFCredential Specifies user logincredentials.

params List<SFParameters> batchSize will specify thedefault pageSize to use fordata manipulationoperations (Insert, Updateor Upsert). This can be avalue from 1 to 800. Thesystem will default topageSize of 200 if notspecified.

3.2.3.2 Optional SFParameter Values For Login

Below is a table of SFParameter values that can be used in the Login operation to specifysession settings.

SF Parameter Value Description





batchSize An integerfrom 1 to 800

batchSize will specify the default pageSize to use for datamanipulation operations (Insert, Update or Upsert). Thiscan be a value from 1 to 800. The system will default topageSize of 200 if not specified.

3.2.3.3 Example Java Code

Declaration

/** The WS service object. */

private SFAPIService fService;

/** The WS invocation proxy. */

private SFAPI fProxy;

Initialization

fService = new SFAPIService(getWSEndpointURL(endpointURL), newQName(NS_SFAPI_SERVER, SFAPIService));

fProxy = fService.getSFAPI();

Map<String, Object> requestContext = ((BindingProvider) fProxy).getRequestContext();

// Need to set the property tomaintain the http session.requestContext.put(BindingProvider.SESSION_MAINTAIN_PROPERTY,true);

login()

SFCredential credential = new SFCredential(); credential.setCompanyId("acme");

credential.setUsername("user1"); credential.setPassword("pwd");List<SFParameter> params = new LinkedList<SFParameter>(); LoginResult result =fProxy.login(credential, params); List<com.successfactors.sfapi.sfobject.Error> errorList =result.getError();

if (errorList != null && errorList.size() > 0) {

// Login failed

System.out.println("Failed to login!");

System.out.println("Error code : " + errorList.get(0).getErrorCode()

+ ". Error message: " + errorList.get(0).getErrorMessage());

return false;

}

System.out.println("Successfully logged into SuccessFactors.");





3.2.3.4 Example SOAP Request XML

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/ "xmlns:urn="urn:sfobject.sfapi.successfactors.com">

<soapenv:Header/>

<soapenv:Body> <urn:login>

<urn:credential>

<urn:companyId>acme</urn:companyId>

<urn:username>user1</urn:username>

<urn:password>pwd</urn:password>

</urn:credential>



<urn:param>

<urn:name>batchSize</urn:name>

<urn:value>500</urn:value>

</urn:param>

</urn:login>

</soapenv:Body>

</soapenv:Envelope>

3.2.3.5 Example SOAP Response XML<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<loginResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<sessionId>

676D4E614BC41AB6660A4DC8AE267F31

</sessionId> <msUntilPwdExpiration>

9223372036854775807

</msUntilPwdExpiration>

(Expired time in ms, this value means never expires)

</result>

http://schemas.xmlsoap.org/soap/envelope/








</loginResponse>

</S:Body>

</S:Envelope>

3.2.3.6 Example SOAP Failed Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<loginResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<sessionId xsi:nil="true"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

<msUntilPwdExpiration xsi:nil="true"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

<error>

<errorCode>FAILED_AUTHENTICATION</errorCode>

<errorMessage>

Login failure due to the invalid company!

</errorMessage>

</error>

</result>

</loginResponse>

</S:Body>

</S:Envelope>

3.2.4 LogOut

boolean logout()

Destroys the current API session.


None.


if (fProxy.logout()) { System.out.println("Logout Successfully.");

…


http://www.w3.org/2001/XMLSchema-instance













} else {

System.out.println("Failed to logout");

}



<soapenv:Header/>

<soapenv:Body>

<urn:logout/>

</soapenv:Body>

</soapenv:Envelope>

3.2.4.4 Example SOAP Response XML<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<logoutResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>true</result>

</logoutResponse>

</S:Body>

</S:Envelope>



<S:Body>

<logoutResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>false</result>

</logoutResponse>

</S:Body>

</S:Envelope>

3.3 MetaData Discovery Methods

The MetaData methods allow for dynamic discovery of SFObjects available in the API. Thisallows you to list all the objects in the system, and describe objects to inspect their structure











and provide meta information about the object, like which API data manipulation operationsare supported for this object.

3.3.1 API Signature


3.3.2.1 DescribeResult

DescribeResult has the following properties:

Name Descri tion

error List of error codes and messa es.

feature The supported feature list, valid values are:

insert, upsert, delete, update, query, queryMore.

field An array of fields found in the SFObject. The Field object contains metadataabout the field like field name, data type, etc. See the Field object definitionfor more information.

type Describes the type of this SFObject. For example, "User" or "Goal$1".

The type is also referred to as the entity name. This value will correspond toone of the values retuned in the API list() operation.


DescribeResult[ ] describe(String[]types, List<SFParameter> params )

Describes the SFObjects specified by the list of entity names. Noteyou can get all the available entity names of the SFObjects usingthe list() call below.

The returned DescribeResult contains metadata to describe theobject properties in terms of name, data type and other importantmetadata.

List<String> list() Retrieves a list the entity names of all SFObjects available through

the SFAPI. You can use these names in the describe(String[] types)call.





3.3.2.2 Field Object

The Field object contains metadata about an SFObject field. It is necessary for runtimediscovery of field properties.

The Field object has the following properties:

Name Descri tion

dataType Specifies the field data type. One of the following:

Integer Long Float Double String Boolean

Date (with date only) DateTime (with both date and time) Binary

label list of localized labels for this field.

maxlength If not null, this field specifies the maximum length restriction(byte count in UTF-8 format) on the field. Any data beyondhis length will be truncated.

name uni ue name for the field.

picklist Picklist object which provides enumerated values for thisield. These can be configured / set up in the Administrativearea of the SuccessFactors system.

required Flag to indicate if this is a required field.

3.3.2.3 Field Object Data Types

The following data types are supported for fields of SFObjects in the SFAPI:

Type Name Description

The type for binary data. Embedded byte stream encoded in Base64 format.

Boolean type The accepted value is "true" or "false"(ignore case).





Date Type(date only) The accepted format is YYYY-MM-DD. For ex, 2008-02-23.

Date and Time Type(date and time) The accepted format is in ISO 8601 format in

UTC (YYYY-MM-DDThh:mm:ssZ).

For ex, 1999-01-01T23:01:01Z (In time zone GMT).

Double type(Signed) 8 bytes double. The maximum value is1.7976931348623157e+308.

Float type(Signed) 4 bytes float. The maximum value is 3.4028235e+38.

Integer type(Signed) 4 bytes integer. The range is (-2^31 ~ 2^31-1).

Long type(Signed) 8 bytes long. The range is (-2^63 ~ 2^63-1).

String type The maxlength field will return the maximum allowed byteswhen the string is converted to UTF-8 encoding.

3.3.2.4 Picklist

Picklist has the following properties:

Name T e Descri tion id String A unique id for this picklist.

picklistOptions PicklistOption [ ] An array of selectable options for thispicklist.

source String The source is used.

3.3.2.5 Picklist Option

PicklistOption has the following properties:


externalCode String An external code that can be associatedwith this value.





id Integer A unique id for this picklist option.

labels Label [ ] A list of localized labels for this picklistoption.

status String A status for this picklist. Status can be"ACTIVE", "OBSOLETED" or "DELETED".Only "ACTIVE" picklist options will bedisplayed in the SuccessFactorsapplication.

value Integer An integer value assigned to this picklistoption.

3.3.2.6 Label A localized label object. Label contains the following properties:


locale String Optional. The locale for this label, wherethe locale = language code + "_" + countrycode + "_" + variant. The language codeshould adhere to ISO 639, the countrycode to ISO 3166. Variant has no

requirements on format. The following arevalid locale strings:

"en" - English language

"en_US" - English language specific to theUS "en_US_CA" - English in California,U.S.A.

mime-type String Allows mime type specification of either"text-plain", or "text-html". If mime type of"text-html" is specified then theSuccessFactors application will interpret

the label as html, otherwise it will berendered as plain text.

value String The localized label.





3.3.3 List

String[] list()

List the entities in your company instance.

3.3.3.1 Supported ParametersNone.


ListSFObjects param = new ListSFObjects();

ListSFObjectsResponse result = fProxy.list(param);

System.out.println("Entity list:");

for (String fieldName : result.getName()) {

System.out.println("\t" + fieldName);

}


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:urn="urn:sfobject.sfapi.successfactors.com">

<soapenv:Header/>

<soapenv:Body>

<urn:listSFObjects/>

</soapenv:Body></soapenv:Envelope>

3.3.3.4 Example SOAP Response XML


<S:Body>

<listSFObjectsResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<name>User</name>

<name>LearningActivity$4001</name>

<name>MatrixManager</name>

<name>CustomManager</name>

<name>SecondManager</name>

<name>Background_googledocs</name>

<name>Background_insideWorkExperience</name>





<name>Background_specialAssign</name>

<name>Background_outsideWorkExperience</name>

<name>Background_education</name>

<name>Background_courses</name>

<name>Background_certificates</name>

<name>Background_awards</name>

<name>Background_languages</name>

<name>Background_funcExperience</name>

<name>Background_leadExperience</name>

<name>Background_preferredNextMove</name>

<name>Background_mobility</name>

<name>Background_memberships</name>

<name>Background_community</name>

<name>Background_promotability</name>

<name>Background_compensation</name>

<name>Background_varPayEmpHistData</name>

<name>CalibrationSubject</name>

<name>JobPosting</name>

<name>BackgroundCheck</name>

<name>Onboarding</name><name>TrendData_sysOverallPerformance</name>

<name>TrendData_sysOverallPotential</name>

<name>TrendData_sysOverallObjective</name>

<name>TrendData_sysOverallCompetency</name>

<name>Goal$1</name>

<name>Goal$3</name>

</listSFObjectsResponse>

</S:Body>

</S:Envelope>

3.3.4 Describe

DescribeResult describe(String type[], SFParameter params[])

Returns metadata about the list of entities specified in the type parameter.







params List <SFParameters> NOT USED. Leave it null.

type String [ ] A list of string values thatspecify entity names (entitytypes) that you want todescribe. These valuescome from the list()operation.


DescribeSFObjects param = new DescribeSFObjects();

param.getType().add("User");

DescribeSFObjectsResponse response = fProxy.describe(param);

for (DescribeResult result : response.getResult()) {

System.out.println("Entity Type : " + result.getType());

int index = 0;

for (Field field : result.getField()) {

System.out.println("Field #" + index + " : " + field.getName());

System.out.println("\tRequired : " + field.isRequired());System.out.println("\tData Type : " + field.getDataType().value());System.out.println("\tMax Length : " + field.getMaxlength()); List<Label>labelList = field.getLabel();

if (labelList != null & labelList.size() > 0) {

for (Label label : field.getLabel()) {

System.out.println("\tLabel : "); System.out.println("\tValue : " + label.getValue());

System.out.println("\t Locale : " + label.getValue());

}

}

Picklist picklist = field.getPicklist();

if (picklist != null) { System.out.println("\tPick List: ");

System.out.println("\t Id : " + picklist.getId());

System.out.println("\t Source : " + picklist.getSource());





++index;

}

System.out.println("Supported Operations : ");

for (FeatureType featureType : result.getFeature()) {

System.out.println(" " + featureType.value());

}

}



<soapenv:Header/>

<soapenv:Body>

<urn:describeSFObjects>



<urn:type>LearningActivity$4001</urn:type>


<urn:param>

<urn:name>locale</urn:name>

<urn:value>en-US</urn:value>

</urn:param> </urn:describeSFObjects>

</soapenv:Body>

</soapenv:Envelope>


<S:Body>

<describeSFObjectsResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<type>LearningActivity$4001</type>

<field>

<name>GUID</name>

<dataType>string</dataType>







<maxlength>256</maxlength>

<required>true</required>

</field>

<field>

<name>ParentId</name>



<required>false</required>

</field>



<feature>upsert</feature>

</result>

</describeSFObjectsResponse>

</S:Body>



<S:Body>

<ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/ "xmlns:ns3="http://www.w3.org/2003/05/soap-envelop e">

<faultcode>ns2:Server</faultcode><faultstring>SFAPI Domain Error!</faultstring>

<detail>

<ns2:SFWebServiceFaultxmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<ns2:errorCode>

UNDEFINED_ENTITY_ID

</ns2:errorCode>

<ns2:errorMessage>

Entity type 'Learn22ingActivity$4001' is undefined!

</ns2:errorMessage>

</ns2:SFWebServiceFault>

</detail>



http://www.w3.org/2003/05/soap-envelope








</ns2:Fault>

</S:Body>

</S:Envelope>

Note

Locale only affect the returned localized labels for each fields.

3.3.5 DescribeEx

DescribeExResult describeEx(String type[], SFParameter params[])

This method is in beta development and will change in the 1109 release. It will be anextended version of the describe method.



params List <SFParameters> NOT USED. Leave it null.

type String [ ] A list of string values thatspecify entity names (entitytypes) that you want todescribe. These valuescome from the list()operation.


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/env elope/"xmlns:urn="urn:sfobject.sfapi.successfactors.com">

<soapenv:Header/>

<soapenv:Body>

<urn:describeSFObjectsEx>


<urn:type>LearningActivity$4001</urn:type>


<urn:param>

<urn:name>locale</urn:name>

<urn:value>en-US</urn:value>

</urn:param>

http://schemas.xmlsoap.org/soap/env

http://schemas.xmlsoap.org/soap/env





</urn:describeSFObjectsEx>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<describeSFObjectsExResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<type>learningactivity$4001</type>

<field>

<name>GUID</name>



<required>true</required>

<insertable>false</insertable>

<upsertable>true</upsertable>

<supportInOperator>false</supportInOperator>

<updateable>false</updateable>

<selectable>false</selectable><filterable>false</filterable>

<supportLikeOperator>false</supportLikeOperator>

<sortable>false</sortable>

</field>

<field>

<name>ParentId</name>



<required>false</required>

<insertable>false</insertable>

<upsertable>true</upsertable>

<supportInOperator>false</supportInOperator>

<updateable>false</updateable>







<selectable>false</selectable>

<filterable>false</filterable>

<supportLikeOperator>false</supportLikeOperator>

<sortable>false</sortable>

</field>



<feature>upsert</feature>

</result>

</describeSFObjectsExResponse>

</S:Body>

</S:Envelope>

3.3.5.4 Example SOAP Failed Response<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>


<faultcode>ns2:Server</faultcode>

<faultstring>SFAPI Domain Error!</faultstring>

<detail>


<ns2:errorCode>UNDEFINED_ENTITY_ID</ns2:errorCode>

<ns2:errorMessage>

Entity type 'Learn22ingActivity$4001' is undefined!

</ns2:errorMessage>


</detail>

</ns2:Fault>

</S:Body>

</S:Envelope>

Note

Locale specifies the returned localized labels for each field.











3.4 Data Manipulation Operations

The data manipulation operations provide the CRUD (Create, Read, Update, Delete) styleoperations on the SFObjects exposed in the API. Refer to the separate SFAPI DataDictionary document to ensure you have the proper permissions setup to access thedesired SFObjects.

There are four data manipulation operations, insert/update/upsert and delete().

3.4.1 API Signature


DeleteResult[ ] delete(String type,List<SFObject> sfobject, List<SFParameter> processingParam)

Delete the SFObjects specified by the id field inthe SFObject list, and report an error if the id is notfound.

InsertResult[ ] insert(String type,List<SFObject> sfobject, List<SFParameter> processingParam)

Insert the list of SFObjects. Errors will be reportedif the rows to be inserted already exist in thesystem.

Consult the individual SFObject types in theseparate SFAPI Data Dictionary for anyprocessingParam that may apply.

UpdateResult[ ] update(String type,List<SFObject> sfobject, List<SFParameter> processingParam)

Update the rows specified by the id field in theSFObject list, and report errors if the row id doesnot exist in the system.

Consult the individual SFObject types types in theseparate SFAPI Data Dictionary for anyprocessingParam that may apply.

UpsertResult[ ] upsert(String type,List<SFObject> sfobject, List<SFParameter> processingParam)

The upsert operation will insert or update the givenlist of SFObjects. This operation will check if thespecified row exists and then will update the row,and if the row is not found, insert the row.

Consult the individual SFObject types types in theseparate SFAPI Data Dictionary for any

processingParam that may apply.






3.4.2.1 SFObject

SFObject is a generic class for all SFAPI data objects. An SFObject is analogous to a rowin a database table. Each SFObject will have fields that are evaluated at runtime. As a

generic object the fields are implemented as un-typed data in the generic xsd<any>element.

The allowable fields for the SFObject can be discovered using the describe operation.Below are the attributes of the SFObject. There are only three, the ID, the type and the xsd<any> element which will contain the data fields requested in the queryString, or suppliedby the user for import type operations.

SFObject has the following fields:

Name T e Descri tion

any List<Object> The list of the SFObject fields. The formatis:

<FieldName>FieldValue</FieldName>. Thelist element is a DOM object.

id String A unique identifier for the object. This isrequired field when in update/deleteoperations. In insert/upsert operations, thisfield MUST NOT exist.

type String The type of this object.For example "User" or "Transcript".

3.4.2.2 SFParameter

SFParameter is a generic structure used to pass in name - value pairs of information tocontrol method processing. For example, in user import you can pass in a parameter tocontrol whether welcome messages are sent to new users.

SFParameter has the following properties:

Pro ert Name T e Descri tion

Name String The parameter name.

Value String The parameter value.





3.4.2.3 InsertResult/UpdateResult/DeleteResult/UpsertResult

All four of these result type objects have the same format. The result objects are used tocontain results and status of the data manipulation request - where multiple objects wereprocessed during the request. In addition to the overall status and error code, the status ofthe each row processed has a specific status and error message.


jobStatus String Indicates if there were errors encounteredwhile processing the operations.

Values can be one of the following:

OK ERROR

If all the rows are validated and processed

without error, the value is OK.Check the row level detail status/error if thereturn value is ERROR.

For ex, if the required externalId is notspecified in insert operation, the status willreturn ERROR code. Check the row levelerror by examining the objectEditResult forwhich row is causing the error.

message String The message from this job. Usually this isa summary field indicating the number ofrows processed, the number of rows failedand the processing time.

objectEditResult List<ObjectEditResult> An array of the edit results for the objectsthat were imported. Each row in therequest message will have a relatedObjectEditResult.

3.4.2.4 ObjectEditResult

ObjectEditResult is used to contain the results and status of edit related calls on an object.

ObjectEditResult has the following properties:






errorStatus String Indicates if there was an error editing theobject. Values can be one of the following:

OK ERROR

NO_MATCH (only in Update orDelete operations)

Note that even if there was an ERRORencountered, the editStatus below shouldstill be checked. An ERROR does notmean the editStatus is automaticallyNO_EDIT.

Index Integer A zero based index into the input array ofSFObjects that was submitted for edits to

which this ObjectEditResult applies.

editStatus String Indicates what type of edit operation wasperformed on the object. Values can be oneof the following:

CREATED UPDATED DELETED NO_EDIT

message String Contains an error message if an error wasencountered. (i.e., the errorStatus =ERROR).

3.4.3 Insert

InsertResult insert(String type, SFObject[] objects, SFParameter[] processingParam)

Insert the list of SFObjects. Errors will be reported if the rows already exist in the system.


Parameter Name Type Description

objects SFObject [ ] A list of SFObjects that youwant to insert. Errors willbe reported if the rows





already exist in the system,or if you are missing anyrequired fields. Therequired fields can bediscovered using the

describe() operation for thisentity.

processingParam List <SFParameters> List of optional parameters.

type String The entity type name thatyou want to insert. Thismust correspond to a valuereturned by the list()operation.


List<SFObject> sfobjects = new LinkedList<SFObject>();

// For upsert / insert operation, all required fields are needed. Please see

// the describe result to find out which fields are required.

// Fill user info for user1

SFObject user1 = new SFObject();

user1.setType("User");

SOAPFactory factory = SOAPFactory.newInstance();

SOAPElement element = factory.createElement("externalId");element.addTextNode("user_1");

user1.getAny().add(element);

element = factory.createElement("username");

element.addTextNode("user1");


element = factory.createElement("firstName");

element.addTextNode("Carla");


element = factory.createElement("lastName");

element.addTextNode("Grant");


element= factory.createElement("email");





element.addTextNode("[email protected]");


sfobjects.add(user1);

InsertResult result = fProxy.insert("User", sfobjects, null);

System.out.println("Insert status : " + result.getJobStatus());

System.out.println("Message : " + result.getMessage());

for (ObjectEditResult objectEditResult : result.getObjectEditResult())

{

System.out.println("Object #" + objectEditResult.getIndex());System.out.println("\tId : " + objectEditResult.getId());

System.out.println("\tEdit Status : " + objectEditResult.getEditStatus());

System.out.println("\tError Status : " + objectEditResult.getErrorStatus());

}



<soapenv:Header/>

<soapenv:Body>

<urn:insert>

<urn:type>user</urn:type>


<urn:sfobject>


<externalId>cgrant</externalId>

<username>cgrant</username>

<status>active</status>

<password>pwd</password>

<firstName>Carla</firstName> <lastName>Grant</lastName>

<email>[email protected]</email>

<managerId>USR-8</managerId>

<hrId>USR-8</hrId>

<department>test</department>

mailto:[email protected]










<jobCode>test</jobCode>

<division>test</division>

<location>test</location>

<timeZone>PST</timeZone>

<hireDate>2010-01-01</hireDate>

</urn:sfobject>

</urn:insert>

</soapenv:Body>

</soapenv:Envelope>



<S:Body> <insertResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<jobStatus>OK</jobStatus>

<message xsi:nil="true"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />

<objectEditResult>

<id>USR-4389</id>

<errorStatus>OK</errorStatus>

<editStatus>CREATED</editStatus>

<index>0</index>

<message xsi:nil="true"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

</objectEditResult>

</result>

</insertResponse>

</S:Body>

</S:Envelope>

















<S:Body>

<insertResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<jobStatus>ERROR</jobStatus><message xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

<objectEditResult>

<errorStatus>ERROR</errorStatus>

<editStatus>NOEDIT</editStatus>

<index>0</index>

<message>INTERNAL_ERROR : User already exists.</message>

</objectEditResult> </result>

</insertResponse>

</S:Body>

</S:Envelope>

Note

Insert and Upsert cannot have "ID" field in the SFObject.

3.4.4 Update

UpdateResult update(String type, SFObject[] objects, SFParameter[]processingParam)

Updates the objects of the specified entity type. The operation will resume if one row hasfailed to update.



objects SFObject [ ] A list of SFObjects that youwant to update. Errors willbe reported if the rows donot exist in the system.


type String The entity type name thatyou want to update. This









must correspond to a valuereturned by the list()operation.



<soapenv:Header/>

<soapenv:Body>

<urn:update>



<urn:sfobject>

<urn:id>USR-4389</urn:id>


<firstName>test</firstName>

<password>123</password>

</urn:sfobject>

</urn:update>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<updateResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>



<objectEditResult>

<id>USR-4389</id>












<editStatus>UPDATED</editStatus>

<index>0</index>

<message xsi:nil="true"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

</objectEditResult>

</result>

</updateResponse>

</S:Body>

</S:Envelope>



<S:Body>

<updateResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>



<objectEditResult>

<errorStatus>NO_MATCH</errorStatus><editStatus>NOEDIT</editStatus>

<index>0</index>

<message>

USER_NOT_FOUND : Cannot find user by user id.InternalId = USR-224389

</message>

</objectEditResult>

</result> </updateResponse>

</S:Body>

</S:Envelope>

Note













Update requires the ID key. Note you can update password just like other normal fields. Forsecurity, the password content will not be saved in the log or audit history.

3.4.5 Upsert

UpsertResult upsert(String type, SFObject[] objects, SFParameter[]

processingParam)

Inserts or updates the objects of the specified entity type. If the row doesn't exist, performthe insert operation, if the row exists, perform the update operation. The operation willresume if one row has failed to upsert.



objects SFObject [ ] A list of SFObjects that you

want to upsert. Errors willbe reported if you aremissing any required fields.The required fields can bediscovered using thedescribe() operation for thisentity


type String The entity type name thatyou want to upsert. This

must correspond to a valuereturned by the list()operation.



// For upsert / insert operation, all required fields are needed. Please see

// the describe result to find out which fields are required.

// Fill user info for user1SFObject user1 = new SFObject();

user1.setType("User");

SOAPFactory factory = SOAPFactory.newInstance();

SOAPElement element = factory.createElement("externalId");element.addTextNode("user_1");






element = factory.createElement("username");

element.addTextNode("user1"); user1.getAny().add(element);

element = factory.createElement("firstName");

element.addTextNode("Carla");


element = factory.createElement("lastName");

element.addTextNode("Grant");


element = factory.createElement("email");

element.addTextNode("[email protected]");


sfobjects.add(user1);

UpsertResult result = fProxy.upsert("User", sfobjects, null);

System.out.println("Upsert status : " + result.getJobStatus());



{

System.out.println("Object #" + objectEditResult.getIndex());

System.out.println("\tId : " + objectEditResult.getId());System.out.println("\tEdit Status : " + objectEditResult.getEditStatus());System.out.println("\tError Status : " + objectEditResult.getErrorStatus());

}



<soapenv:Header/>

<soapenv:Body> <urn:upsert>



<urn:sfobject>










<externalId>cgrant</externalId>


<status>active</status>

<password>cgrant</password>

<firstName>test</firstName>

<lastName>test</lastName>

<mi>test</mi>

<nickname>test</nickname>

<suffix>test</suffix>

<salutation>test</salutation>

<gender>M</gender>

<email>[email protected]</email>

<managerId>USR-8</managerId>

<hrId>USR-8</hrId>

<department>test</department>

<jobCode>test</jobCode>

<division>test</division>

<location>test</location>

<timeZone>PST</timeZone>

<hireDate>2010-01-01</hireDate><empId>test</empId>

<title>test</title>

<businessPhone>test</businessPhone>

<fax>test</fax>

<addressLine1>test</addressLine1>

<addressLine2>test</addressLine2>

<city>test</city>

<state>test</state>

<zipCode>test</zipCode>

<country>test</country>

<reviewFreq>test</reviewFreq>

<lastReviewDate>test</lastReviewDate>

<custom01>test</custom01>









</urn:sfobject>

</urn:upsert>

</soapenv:Body>

</soapenv:Envelope>


<?xmlversion='1.0' encoding='UTF-8'?>


<S:Body>

<upsertRes ponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>


<message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instanc e"xsi:nil="true"/>

<objectEditResult>

<id>USR-4388</id>


<editStatus>UPDATED</editStatus>

<index>0</index>

<message

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:nil="true"/>

</objectEditResult>

</result>

</upsertResponse>

</S:Body>

</S:Envelope>


<?xmlversion='1.0' encoding='UTF-8'?>


<S:Body>
















<detail><ns2:SFWebServiceFault xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<ns2:errorCode>

INVALID_ REQUEST_MESSAGE

</ns2:errorCode>

<ns2:errorMessage>

Invalid request message! Error: Invalid date value 2010-012-01 atmessage#=1,field#=108,field=servicedate!

</ns2:errorMessage>

</ns2:SFWeb ServiceFault>

</detail>

</ns2:Fault>

</S:Body>

</S:Envelope>

Note

Upsert should return success code of "UPDATED" or "CREATED", otherwise it will returnoperation failed error code and message.

3.4.6 Delete



Objects SFObject [ ] A list of SFObjects that you want todelete. Errors will be reported if the

row does not exist.


Type String The entity type name that you want todelete from. This must correspond to avalue returned by the list() operation.











// Fill user info for user1

SFObject mmgr1 = new SFObject();

user1.setType("MatrixManager");

user1.setId("MMGR-1484");

sfobjects.add(mmgr1);

DeleteResult result = fProxy.delete("MatrixManager", sfobjects, null);System.out.println("Update status : " + result.getJobStatus());



{

System.out.println("Object #" + objectEditResult.getIndex());

System.out.println("\tId : " + objectEditResult.getId());

System.out.println("\tEdit Status : " + objectEditResult.getEditStatus());

System.out.println("\tError Status : " + objectEditResult.getErrorStatus());

System.out.println("\tError Message : " + objectEditResult.getMessage());

}



<soapenv:Header/>

<soapenv:Body>

<urn:delete>

<urn:type>MatrixManager</urn:type>



<urn:sfobject>



<urn:id>MMGR-1484</urn:id>

<urn:type>MatrixManager</urn:type>

</urn:sfobject>







</urn:delete>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<deleteResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>


<message/>

<objectEditResult>

<id>MMGR-1484</id>


<editStatus>DELETED</editStatus>

<index>0</index>


</objectEditResult>

</result>

</deleteResponse>

</S:Body>

</S:Envelope>



<S:Body>

<ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ns3="http://www.w3.org/2003/05/soap-envelop e"><faultcode>ns2:Server</faultcode>


<detail>
















<ns2:errorCode>UNSUPPORTED_OPERATION</ns2:errorCode>

<ns2:errorMessage>

Entity type 'User' doesn't support DELETE operation!

</ns2:errorMessage>


</detail>

</ns2:Fault>

</S:Body>

</S:Envelope>

3.5 Data Query Operations

The interfaces included data query feature using the SFQL. The methods also supportquery by pagination.

3.5.1 API Signature

Si nature Descri tion QueryResult query(String queryString,List<SFParameter> params )

Queries the SuccessFactor platform using SFQLquery string. The maximum rows count is 200. Ifthe Use queryMore() to retrieve the data page bypage.

The returned QueryResult contains the matchingSFObjects specified by SFQL, the row countreturned and the querySessionId used withsubsequent queryMore() method call to retrievethe data.

QueryResult queryMore(StringquerySessionId)

Retrieve the next page data of the previous query.






3.5.2.1 QueryResult

QueryResult has the following properties:


hasMore boolean Flag to indicate if there are more result setavailable.

For ex, the following code is the pattern

r = query("select * from User");

while (r.hasMore()) {

r = queryMore(r.querySessioId);

}

numResults int Return the row count of the matchingSFObjects.

querySessionId String A unique identifier used to pass into thequeryMore operation if there are morerows. This will identify the next page ofrows to retrieve in the queryMoreoperation.

sfobject SFObject[] Return the list of the SFObjects.

3.5.3 Query

QueryResult query(String queryString, SFParameter[] param)

Queries the SuccessFactors system with the given query string in SFQL (SuccessFactorsQuery Language). For detail grammar description, please check the related section in thisreference guide.

The following is an example query String:SELECT FirstName, LastName, JobCode, Title FROM User WHERE externalId = 'cgrant'.

The QueryResult object will contain the first page of results. Paging through the remainingresults is accomplished using the queryMore() operation. The QueryResult object willreturn a boolean parameter "hasMorePages" to indicate if there are more pages remainingand a querySessionId, which must be passed into the queryMore() method to get the nextpage of results.





You can set the page size for a query by setting the "maxRows" parameter in the querymethod to an integer value from 1 to 800. The default page size is 200, and the maximumpage size is 800.


startingRow, maxRows

3.5.3.2 Optional SFParameter Values For Query

Below is a table of SFParameter values that can be used in the query operation.

SFParameter Name SFParameter Value Description

maxRows An integer from 1 to 800 maxRows will specify thepageSize for the returnedresult rows of the query.This can be a value from 1to 800. The system will

default to pageSize of 200 ifnot specified.


query() & queryMore() query() & queryMore()

// display up to 25records in all int numRowsToPrint = 25;

String sfql = "SELECTexternalId, userName, firstName, lastName, email FROM User";

List<SFParameter> paramList = new LinkedList<SFParameter>();

SFParameter param = new SFParameter();

// Set querypage size to retrieve 10 records per page param.setName("maxRows");

param.setValue("10");

paramList.add(param);

QueryResult result = fProxy.query(sfql, paramList);

int count = 0;

Utils.dumpQueryResult(result, numRowsToPrint, count);

count += result.getNumResults();numRowsToPrint -= result.getNumResults();

while (numRowsToPrint > 0 && result.isHasMore() && result.getNumResults() > 0) {

result = fProxy.queryMore(result.getQuerySessionId());

// Dump the first n limits rows Utils.dumpQueryResult(result, numRowsToPrint,count); count += result.getNumResults();





numRowsToPrint -= result.getNumResults();

}

System.out.println("The total row count returned is " + count + ".");

/**

* Dump the query result.

*

* @param r esult

* the query result.

* @paramnumRowsToPrint

* the remaining rows to dump.

* @paramstartRowIndex

* the start row index.

*/

public static void dumpQueryResult(QueryResult result, int numRowsToPrint, int startRowIndex) {

System.out.println("The number of the records in a query: " + result.getNumResults());

int index = 0;

for (SFObject sfobject : result.getSfobject()) {

index++;

if (index > numRowsToPrint) {

continue;

}

System.out.print("Row#" + String.valueOf(index + startRowIndex));

System.out.println("(Id:" + sfobject.getId() + ", Type:" + sfobject.getType()+ ")");

for (Object fieldObject : sfobject.getAny()) {

if (fieldObject instanceof Element) {

Element field = (Element) fieldObject;

System.out.print("\t" + field.getLocalName());

if ("true".equals( field.getAttributeNS(XMLConstants.W3C_XML_SCHEMA_INSTANCE_NS_URI,"nil"))) {

System.out.println("=<NULL>");

} else {

mailto:@param

mailto:@param

mailto:@param

mailto:@param

mailto:@param

mailto:@param





System.out.println("='" + getNodeTextValue(field) + "'");

}

}

}}

}



<soapenv:Header/>

<soapenv:Body>

<urn:query>

<urn:queryString>select id,username from user where hrId

='USR-91' and username is not null</urn:queryString>


<urn:param>

<urn:name>maxRows</urn:name>


</urn:param>

<urn:param>

<urn:name>startingRow</urn:name>


</urn:param>

</urn:query>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<queryResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>









<sfobject>

<id>USR-4385</id>

<type>User</type>

<username>test_noexport</username>

</sfobject>

<sfobject>

<id>USR-4386</id>

<type>User</type>

<username>test_110124102601</username>

</sfobject>

<sfobject>

<id>USR-4387</id>

<type>User</type>

<username>test2_110124102602</username>

</sfobject>

<sfobject>

<id>USR-4388</id>

<type>User</type>


</sfobject> <sfobject>

<id>USR-4389</id>

<type>User</type>

<username>cgrant_2</username>

</sfobject>

<numResults>5</numResults>

<hasMore>false</hasMore>

<querySessionId>

3209cbb1-2302-41ea-af76-b8158f34bd7d

</querySessionId>

</result>

</queryResponse>

</S:Body>





</S:Envelope>



<S:Body>




<detail>


<ns2:errorCode>UNDEFINED_ENTITY_ID</ns2:errorCode> <ns2:errorMessage>

Entity type 'user23' is undefined!

</ns2:errorMessage>


</detail>

</ns2:Fault>

</S:Body>

</S:Envelope>

Note

Query Session returned in query is used for queryMore operation (pagination), but theserver only keep the last 5 query session id. Older query operation expire.

startingRow starts with 1, not 0.

3.5.4 QueryMore

QueryResult queryMore(String querySessionId)

The queryMore operation is used to support paging through results generated by the queryoperation.

Like the query operation, the queryMore operation also returns a QueryResult object,which contains the next page of results, and a hasMoreResults parameter to indicate ifthere are more results, along with a new querySessionId to be used in the next queryMorecall.












None


See the example listed for the query operation.



<soapenv:Header/>

<soapenv:Body>

<urn:queryMore>

<urn:querySessionId>

4afa1b00-81f5-4d37-be72-382967c4cb22</urn:querySes sionId>

</urn:queryMore>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<queryResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<sfobject>

<id>USR-4385</id>

<type>User</type>

<username>test_noexport</username>

</sfobject>

<sfobject>

<id>USR-4386</id>

<type>User</type>

<username>test_110124102601</username>

</sfobject>







<sfobject>

<id>USR-4387</id>

<type>User</type>

<username>test2_110124102602</username>

</sfobject>

<sfobject>

<id>USR-4388</id>

<type>User</type>


</sfobject>

<sfobject>

<id>USR-4389</id>

<type>User</type>

<username>cgrant_2</username>

</sfobject>

<numResults>5</numResults>

<hasMore>false</hasMore>

<querySessionId>

3209cbb1-2302-41ea-af76-b8158f34bd7d

</querySessionId> </result>

</queryResponse>

</S:Body>

</S:Envelope>



<S:Body>




<detail>












<ns2:errorCode>UNDEFINED_ENTITY_ID</ns2:errorCode>

<ns2:errorMessage>

Entity type 'user23' is undefined!

</ns2:errorMessage>


</detail>

</ns2:Fault>

</S:Body>

</S:Envelope>

Note The querySessionId returned in the queryResponse is used for the queryMore operation(for pagination), but the server will only keep the last 5 query session ids. Older querysession operations will expire.

startingRow starts with 1, not 0.

3.5.5 SuccessFactors Query Language

3.5.5.1 Overview

SFQL(SuccessFactors Query Language) is a SQL-like language used to query data the

SuccessFactors platform. It is used in queryString parameter of the query call. Theallowable grammar is documented in BNF Notation (Backus-Naur Form) in the nextsection.

3.5.5.2 SFQL Grammar

<SFQL_select> ::= SELECT <select_items> FROM <sfapi_object> WHERE <exp>] [orderby <order_by_items]

<order_by_items> ::= <order_by_item> {"," <order_by_item> }*

<order_by_item> ::= <field_name> [ASC | DESC]

<select_items> ::= "*" | <select_item> {"," <select_item> }*<select_item> ::= <field_name>

<sfapi_object> ::= User | UserRelationship

<exp> ::= <or_exp> | <paren_exp>

<paren_exp> ::= "(" <exp> ")"

<or_exp> ::= <and_exp> { OR <and_exp> }*





<and_exp> ::= <condition> | "(" <or_exp> ")" { AND <condition> | "(" <or_exp> ")"}*

<condition> ::= <sql_condition> | <regular-condition>

<regular_condition> ::= <comparison_item> <comp_op> <comparison_item>

<comp_op> ::= ">" | "<" | "=" | ">=" | "<=" | "<>"<comparison_item> ::= <simple_exp>

<sql_condition> ::= <in_exp> | <like_exp> | <is_null_exp>

<in_exp> ::= <simple_exp> [ NOT ] IN "(" <simple_exp_list> ")"

<like_exp> ::= <simple_exp> [ NOT ] LIKE <simple_exp>

<is_null_exp> ::= <simple_exp> IS [ NOT ] NULL

<comparison_item> ::= <simple_exp>

<simple_exp> ::= <primary_exp> | "(" <primary_exp> ")"

<simple_exp_list> ::= <simple_exp> { "," <simple_exp> }*

<primary_exp> ::= NULL | <numeric_literal> | <string_literal> | <field_name> |<date_function_literal>

<date_function_literal> ::= to_date ( <date_string_in_quotes> ,<date_format_pattern_in_quotes> )

3.6 Async Job Operations

Async Job Operations provide an approach to invoke the API asynchronously. Currentlythe Async Job Operations are limited to running queries on only the Adhoc_XXX entities.

Explain the process flow:

1. SubmitQueryJob2. GetJobStatus (explain status values)3. GetJobResults or GetJobResultsEmbedded

3.6.1 API Signature

Signature Description

TaskStatus submitQueryJob(StringqueryString, SFParameter[] param)

Submit the asynchronous query job to theSuccessFactors platform with the givenquery string in SFQL (SuccessFactorsQuery Language). TaskStatus includes“taskId” which is used to identify asubmitted job. For a detailed grammardescription, please check the related





section in this reference guide.

TaskStatus getJobStatus(String taskId) Get the execution status of the submittedasynchronous job.

DataHandler getJobResult(GetJobResult job) Download the result of submitted

asynchronous query job.TaskStatus[] listJobs() List all Jobs which are in running or

waiting to run.

TaskStatus cancelJob(String taskId) Download the result of submittedasynchronous query job.


3.6.2.1 TaskStatus

TaskStatus has the following properties:


taskId String Task Identification. User usesthis id to check task status,download task result andcancel a task.

taskName String The name of a task. Thisname can be used to find a

task from GUI.

createDate String Creation Datetime of a task.The format is ISO-8601.Such as “2012-01-09T03:34:57.964Z”

status TaskStatusEnum Enumeration of task status.Status values can be:

unsubmitted submitted

processing finished failed undefined cancelled deleted

taskResult TaskResultStatus Object to indicate task resultinformation.





3.6.3 SubmitQueryJob

TaskStatus submitQueryJob(String queryString, SFParameter[] param)

Submit the asynchronous query job to the SuccessFactors platform with the given querystring in SFQL (SuccessFactors Query Language). TaskStatus includes “taskId” which isused to identify a submitted job. For a detailed grammar description, please check therelated section in this reference guide.

TaskStatus includes the information of submitted task.


No parameters for now.


...logger.info("[QUERY] Async query started.");

// Submit Query Job

TaskStatus taskStatus = sfapi.submitQueryJob(sfql, null);

logger.info("[QUERY] Async job started. Job Id: " + taskStatus.getTaskId()

+ ". Job Name: " + taskStatus.getTaskName() + ".");

long startTime = System.currentTimeMillis();

// Check Query Job status by Polling

while ((taskStatus.getTaskResult() == null)

|| (taskStatus.getTaskResult().getStatus() != TaskResultStatusEnum.FINISHED)) {

if ((taskStatus.getTaskResult() != null)

&& (taskStatus.getTaskResult().getStatus() == TaskResultStatusEnum.FAILED)) {

String msg = "Job failed! Job Id: " + taskStatus.getTaskId()

+ " Job Name: " + taskStatus.getTaskName() + " Error Code: "

+ taskStatus.getTaskResult().getErrorCode() + " Error Message: "

+ taskStatus.getTaskResult().getMessage();

logger.error(msg);

// Add error handling code

}

long startTime = System.currentTimeMillis();

if (currentTime - startTime > timeoutMs) {





logger.error(“Connection timeout”);

// Add error handling code

}

Thread.sleep(100);

// Get Job Status

taskStatus = sfapi.getJobStatus(taskStatus.getTaskId());

}

logger.info("[QUERY] Job finished. Start to get the async query result.");

// Got Job result

DataHandler data = sfapi.getJobResult(

Constants.FORMAT_ZIPPED_CSV, taskStatus.getTaskId());

FileOutputStream out = new FileOutputStream(new File("queryResult.zip"));

DataHandler d = new DataHandler(ds);

InputStream in = d.getInputStream();

if (out != null && in != null) {

try {

int ch = 0;

while ((ch = in.read()) > 0) {

out.write(ch);

}out.flush();

} finally {

in.close();

out.close();

}

}



<soapenv:Header/>

<soapenv:Body>

<urn:submitQueryJob>

<urn:queryString>





selectemp_personal_info_t_FIRST_NAME,emp_personal_info_t_GENDER,emp_personal_info_t_LAST_NAME,

emp_personal_info_t_MIDDLE_NAME

from adhoc_ectint

where emp_personal_info_t_FIRST_NAME is not null

and emp_personal_info_t_GENDER = 'M'

constrain by filter_dept='all' and filter_div='all' and filter_loc='all'

and custom01 = 'all' and custom02 = 'all' and custom03 = 'all'

and custom04 = 'all' and custom07 = 'all' and custom12 = 'all'

and asOfDate = '2011-10-10'

order by emp_personal_info_t_FIRST_NAME

</urn:queryString></urn:submitQueryJob>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<submitQueryJobResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>

<taskId>TASK-ADHOC-2364</taskId>

<taskName>SFAPI_0109172739317_ectint</taskName>

<createDate>2012-01-09T09:27:41.612Z</createDate>

<status>submitted</status>

</result>

</submitQueryJobResponse>

</S:Body>

</S:Envelope>

3.6.4 GetJobStatus

TaskStatus getJobStatus(String taskId)

Get the execution status of the submitted asynchronous job.






Please refer to code in above “SubmitQueryJob” section.



<soapenv:Header/>

<soapenv:Body>

<urn:getJobStatus>

<urn:taskId>TASK-ADHOC-2364</urn:taskId>

</urn:getJobStatus>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<getJobStatusResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>


<taskName>SFAPI_0109172739317_ectint</taskName><createDate>2012-01-09T09:27:41.612Z</createDate>


<taskResult>

<taskResultId>2364</taskResultId>

<lastFinishTime>2012-01-09T09:28:15.032Z</lastFinishTime>

<lastStartTime>2012-01-09T09:28:08.266Z</lastStartTime>

<status>finished</status>

</taskResult>

</result>

</getJobStatusResponse>

</S:Body>

</S:Envelope>





3.6.5 GetJobResult

DataHandler getJobResult(GetJobResult job)

Get data handler of job result, user can use it to get the download stream.

3.6.5.1 Supported Parameters“GetJobResult” has the following attributes:


taskId String TaskId which is returned inSubmitQueryJob

format String Currently, it supports csv andzipped_csv format only.


Please refer to code in above “SubmitQueryJob” section.



<soapenv:Header/>

<soapenv:Body>

<urn:getJobResult>


<urn:format>csv</urn:format>

</urn:getJobResult>

</soapenv:Body>

</soapenv:Envelope>

3.6.5.4 Example SOAP Response

HTTP/1.1 200 OKServer: Apache-Coyote/1.1

X-Powered-By: Servlet 2.4; JBoss-4.0.5.GA (build: CVSTag=Branch_4_0date=200610162339)/Tomcat-5.5

Content-Type: multipart/related; type="text/xml"; boundary="uuid:996a038b-52d8-4218-9af3-5da7177dbb31"





Transfer-Encoding: chunked

Date: Wed, 25 May 2011 07:58:26 GMT

--uuid:996a038b-52d8-4218-9af3-5da7177dbb31

Content-Type: text/xml

<?xml version='1.0' encoding='UTF-8'?><S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body /></S:Envelope>

--uuid:996a038b-52d8-4218-9af3-5da7177dbb31

Content-Id:<[email protected]>

Content-Type: application/octet-stream

Content-Transfer-Encoding: binary

"Email","Username","ANALYTICS_LIST_VIEW_BUILDER_SUBDOMAIN_ectint_ectint#users_sysinfo#USERS_SYS_ID"

"[email protected]","aceadmin","aceadmin""[email protected]","admin","admin"

"[email protected]","admin1","admin1"



"[email protected]","v4admin","v4admin"

-uuid:996a038b-52d8-4218-9af3-5da7177dbb31

3.6.6 ListJobs

List<TaskStatus> listJobs()

List all running and waiting to run jobs.


No parameters for now.


...

List<TaskStatus> tasks = sfapi.listJobs();

// Iterate tasks

for (TaskStatus task : tasks) {

System.out.println (task.getId() + “ “ + task.getName() + “ “ + task.getStatus());

}

…







<soapenv:Header/>

<soapenv:Body><urn:listJobs/>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<listJobsResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>


<taskName>SFAPI_1101145047.222_ectint</taskName>



<taskResult>




<message>Job Name:[SFAPI_1101145047.222_ectint (2004)] Job InstanceId:[2004] Process Notes:[Job successfully completed]</message>

<status>running</status>

</taskResult>

</result>

<result>





<taskResult>








<message>Job Name:[SFAPI_1101151557.620_ectint (2005)] Job Instance

Id:[2005] Process Notes:[Job successfully completed]</message><status>running</status>

</taskResult>

</result>

<result>





<taskResult>






</taskResult>

</result>

<result>





<taskResult>










</taskResult>

</result>

<result>





<taskResult>






</taskResult>

</result>

</listJobsResponse>

</S:Body>

</S:Envelope>

3.6.7 CancelJob

TaskStatus cancelJob(String taskId)

Cancel a waiting to run job.


“taskId” – TaskId is the id returned in “submitQueryJob”


...TaskStatus task = sfapi.cancelJob(“TASK-ADHOC-1200”);

System.out.println (task.getId() + “ “ + task.getName() + “ “ + task.getStatus());

…






<soapenv:Header/>

<soapenv:Body><urn:cancelJob>


</urn:cancelJob>

</soapenv:Body>

</soapenv:Envelope>



<S:Body>

<cancelJobResponse xmlns="urn:sfobject.sfapi.successfactors.com"xmlns:ns2="urn:fault.sfapi.successfactors.com">

<result>




<status>canceled</status>

</result>

</cancelJobResponse>

</S:Body>

</S:Envelope>

Documents

SFAPI Functional Guide 1308