SFAPI Functional Guide
SFAPI Functional Guide ©2012 SuccessFactors, Inc. All rights reserved. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, without the express written permission of SuccessFactors. This software is commercial computer software developed exclusively at private expense. The software and documentation are provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in DFARS 252.227.7202-3 or FAR 52.227-19, as applicable. Developer is SuccessFactors Inc., 1500 Fashion Island Blvd, Suite 300, San Mateo, CA 94404. The product described herein includes software developed by the Apache Software Foundation (http://www.apache.org/). All other brand and product names that are mentioned herein are the trademarks or registered trademarks of their respective holders. All examples, including the names of people in the examples or screen shots, are fictitious. 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 not represent 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, CA USA Website: www.successfactors.com
Page 2 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
Table of Contents 1
Introduction to SFAPI ............................................................................................................................7 1.1
Overview .......................................................................................................................................7
1.2
Background ..................................................................................................................................7
1.3
API Endpoints ...............................................................................................................................7 1.3.1
1.4 2
Endpoint URLs ................................................................................................................................ 7
WSDL ...........................................................................................................................................8
Using SFAPI ...........................................................................................................................................9 2.1
SFAPI Setup .................................................................................................................................9 2.1.1 2.1.2 2.1.2.1 2.1.2.2 2.1.3 2.1.4
2.2
Connecting to the API .................................................................................................................14 2.2.1 2.2.2 2.2.3
2.3
Enabling SFAPI ............................................................................................................................... 9 API Login Permission ...................................................................................................................... 9 Granting API Login Permission in the Traditional (aka User-Based) Permission System........ 9 Granting API Login Permission in the Role Based Permission System ................................. 10 Setting Password Policy Exceptions ............................................................................................. 11 Data Specific Permissions............................................................................................................. 13 Authentication................................................................................................................................ 14 Authorization ................................................................................................................................. 14 Handling HTTP Cookies ................................................................................................................ 14
Integration Tools .........................................................................................................................14 2.3.1 2.3.2 2.3.3 2.3.4 2.3.4.1
API Audit Log ................................................................................................................................ 14 API Metering Details...................................................................................................................... 15 API Data Dictionary ....................................................................................................................... 15 Permission Controls on Integration Tools...................................................................................... 15 User Based Permission System ............................................................................................ 15
2.3.4.2 2.3.5 2.3.5.1 2.3.5.2 2.3.5.3
Role Based Permission System............................................................................................. 17 Accessing the Integration Tools .................................................................................................... 17 API Audit Log ......................................................................................................................... 18 API Metering Details .............................................................................................................. 19 API Data Dictionary ............................................................................................................... 20
2.3.4.1.1 2.3.4.1.2 2.3.4.1.3
2.4 3
Accessing Administrative Privileges Page in New Admin Tools ............................................................. 15 Accessing Administrative Privileges Page in Old Admin Tools ............................................................... 16 Setting Permissions in the Administrative Privileges Page ..................................................................... 16
API Thresholds and Limits ..........................................................................................................21
SFAPI Operations ................................................................................................................................22 3.1
API Summary..............................................................................................................................22 3.1.1 3.1.2 3.1.3 3.1.4 3.1.5
Session Management Operations ................................................................................................. 22 MetaData Operations .................................................................................................................... 22 Data Manipulation Operations ....................................................................................................... 22 Data Query Operations ................................................................................................................. 23 Async Job Operations ................................................................................................................... 23
All rights reserved.
Page 3 of 80
SFAPI Functional Guide 3.2
Session Management Operations...............................................................................................24 3.2.1 3.2.2 3.2.2.1 3.2.2.2 3.2.2.3 3.2.3 3.2.3.1 3.2.3.2 3.2.3.3 3.2.3.4 3.2.3.5 3.2.3.6 3.2.4 3.2.4.1 3.2.4.2 3.2.4.3 3.2.4.4 3.2.4.5
3.3
MetaData Discovery Methods .....................................................................................................29 3.3.1 3.3.2 3.3.2.1 3.3.2.2 3.3.2.3 3.3.2.4 3.3.2.5 3.3.2.6 3.3.3 3.3.3.1 3.3.3.2 3.3.3.3 3.3.3.4 3.3.4 3.3.4.1 3.3.4.2 3.3.4.3 3.3.4.4 3.3.4.5 3.3.5 3.3.5.1 3.3.5.2 3.3.5.3 3.3.5.4
3.4
API Signature Description ............................................................................................................. 24 API Framework Objects ................................................................................................................ 24 LoginResult ........................................................................................................................... 24 SFCredential ......................................................................................................................... 24 SFParameter ......................................................................................................................... 25 Login ............................................................................................................................................. 25 Supported Parameters .......................................................................................................... 25 Optional SFParameter Values For Login .............................................................................. 25 Example Java Code .............................................................................................................. 26 Example SOAP Request XML............................................................................................... 27 Example SOAP Response XML ............................................................................................ 27 Example SOAP Failed Response ......................................................................................... 28 LogOut .......................................................................................................................................... 28 Supported Parameters .......................................................................................................... 28 Example Java Code .............................................................................................................. 28 Example SOAP Request XML............................................................................................... 29 Example SOAP Response XML ............................................................................................ 29 Example SOAP Failed Response ......................................................................................... 29 API Signature ................................................................................................................................ 30 API Framework Objects ................................................................................................................ 30 DescribeResult ...................................................................................................................... 30 Field Object ........................................................................................................................... 31 Field Object Data Types ........................................................................................................ 31 Picklist ................................................................................................................................... 32 Picklist Option ....................................................................................................................... 32 Label ..................................................................................................................................... 33 List ................................................................................................................................................ 34 Supported Parameters .......................................................................................................... 34 Example Java Code .............................................................................................................. 34 Example SOAP Request XML .............................................................................................. 34 Example SOAP Response XML ............................................................................................ 34 Describe ....................................................................................................................................... 35 Supported Parameters .......................................................................................................... 36 Example Java Code .............................................................................................................. 36 Example SOAP Request XML............................................................................................... 37 Example SOAP Response XML ............................................................................................ 37 Example SOAP Failed Response ......................................................................................... 38 DescribeEx ................................................................................................................................... 39 Supported Parameters .......................................................................................................... 39 Example SOAP Request XML............................................................................................... 39 Example SOAP Response XML ............................................................................................ 40 Example SOAP Failed Response ......................................................................................... 41
Data Manipulation Operations ....................................................................................................42 3.4.1 3.4.2 3.4.2.1 3.4.2.2 3.4.2.3
Page 4 of 80
API Signature ................................................................................................................................ 42 API Framework Objects ................................................................................................................ 43 SFObject ............................................................................................................................... 43 SFParameter ......................................................................................................................... 43 InsertResult/UpdateResult/DeleteResult/UpsertResult ......................................................... 44
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 3.4.2.4 3.4.3 3.4.3.1 3.4.3.2 3.4.3.3 3.4.3.4 3.4.3.5 3.4.4 3.4.4.1 3.4.4.2 3.4.4.3 3.4.4.4 3.4.5 3.4.5.1 3.4.5.2 3.4.5.3 3.4.5.4 3.4.5.5 3.4.6 3.4.6.1 3.4.6.2 3.4.6.3 3.4.6.4 3.4.6.5
3.5
Data Query Operations ...............................................................................................................59 3.5.1 3.5.2 3.5.2.1 3.5.3 3.5.3.1 3.5.3.2 3.5.3.3 3.5.3.4 3.5.3.5 3.5.3.6 3.5.4 3.5.4.1 3.5.4.2 3.5.4.3 3.5.4.4 3.5.4.5 3.5.5 3.5.5.1 3.5.5.2
3.6
ObjectEditResult .................................................................................................................... 44 Insert ............................................................................................................................................. 45 Supported Parameters ........................................................................................................... 45 Example Java Code ............................................................................................................... 46 Example SOAP Request XML ............................................................................................... 47 Example SOAP Response XML............................................................................................. 48 Example SOAP Failed Response .......................................................................................... 48 Update ........................................................................................................................................... 49 Supported Parameters ........................................................................................................... 49 Example SOAP Request XML ............................................................................................... 50 Example SOAP Response XML............................................................................................. 50 Example SOAP Failed Response .......................................................................................... 51 Upsert ............................................................................................................................................ 52 Supported Parameters ........................................................................................................... 52 Example Java Code ............................................................................................................... 52 Example SOAP Request XML ............................................................................................... 53 Example SOAP Response XML............................................................................................. 55 Example SOAP Failed Response .......................................................................................... 55 Delete ............................................................................................................................................ 56 Supported Parameters ........................................................................................................... 56 Example Java Code ............................................................................................................... 57 Example SOAP Request XML ............................................................................................... 57 Example SOAP Response XML............................................................................................. 58 Example SOAP Failed Response .......................................................................................... 58 API Signature................................................................................................................................. 59 API Framework Objects ................................................................................................................. 60 QueryResult ........................................................................................................................... 60 Query ............................................................................................................................................ 60 Supported Parameters ........................................................................................................... 61 Optional SFParameter Values For Query .............................................................................. 61 Example Java Code ............................................................................................................... 61 Example SOAP Request XML ............................................................................................... 63 Example SOAP Response XML............................................................................................. 63 Example SOAP Failed Response .......................................................................................... 65 QueryMore .................................................................................................................................... 65 Supported Parameters ........................................................................................................... 66 Example Java Code............................................................................................................... 66 Example SOAP Request XML ............................................................................................... 66 Example SOAP Response XML............................................................................................. 66 Example SOAP Failed Response .......................................................................................... 67 SuccessFactors Query Language ................................................................................................. 68 Overview ................................................................................................................................ 68 SFQL Grammar ..................................................................................................................... 68
Async Job Operations.................................................................................................................69 3.6.1 3.6.2 3.6.2.1 3.6.3 3.6.3.1
API Signature ................................................................................................................................ 69 API Framework Objects ................................................................................................................ 70 TaskStatus ............................................................................................................................. 70 SubmitQueryJob............................................................................................................................ 71 Supported Parameters ........................................................................................................... 71
All rights reserved.
Page 5 of 80
SFAPI Functional Guide 3.6.3.2 3.6.3.3 3.6.3.4 3.6.4 3.6.4.1 3.6.4.2 3.6.4.3 3.6.5 3.6.5.1 3.6.5.2 3.6.5.3 3.6.5.4 3.6.6 3.6.6.1 3.6.6.2 3.6.6.3 3.6.6.4 3.6.7 3.6.7.1 3.6.7.2 3.6.7.3 3.6.7.4
Page 6 of 80
Example Java Code .............................................................................................................. 71 Example SOAP Request XML .............................................................................................. 72 Example SOAP Response XML ............................................................................................ 73 GetJobStatus ................................................................................................................................ 73 Example Java Code .............................................................................................................. 74 Example SOAP Request XML .............................................................................................. 74 Example SOAP Response XML ............................................................................................ 74 GetJobResult ................................................................................................................................ 75 Supported Parameters .......................................................................................................... 75 Example Java Code .............................................................................................................. 75 Example SOAP Request XML .............................................................................................. 75 Example SOAP Response .................................................................................................... 75 ListJobs ........................................................................................................................................ 76 Supported Parameters .......................................................................................................... 76 Example Java Code .............................................................................................................. 76 Example SOAP Request XML .............................................................................................. 77 Example SOAP Response XML ............................................................................................ 77 CancelJob..................................................................................................................................... 79 Supported Parameters .......................................................................................................... 79 Example Java Code .............................................................................................................. 79 Example SOAP Request XML .............................................................................................. 80 Example SOAP Response XML ............................................................................................ 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
1 Introduction to SFAPI 1.1 Overview This document is the functional guide for SFAPI developers. This guide provides an overview of the SFAPI, technical information on how to use the SFAPI, details of the Web Service methods and the framework objects.
1.2 Background The SFAPI is SuccessFactors Data API. It is a SOAP Web Service designed for importing and 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 operations to allow runtime discovery of the data. Data are exposed as entities called SFObjects, which are conceptually analogous to database tables. Using the meta-data operations, you can list the SFObjects available to the API, and describe the fields in these entities. Using the CRUD operations you can query or edit the data. The combination of CRUD style data access operations along with meta-data driven operations for data discovery provides a generic API that offers the following benefits: 1. Provide a consistent mechanism for accessing data in the SuccessFactors platform. 2. Provide a mechanism to describe the data schema configuration, including the entities 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 can be in one of several data centers. Please contact your SuccessFactors representative if you 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 EMEA Amsterdam( ASM-2)
All rights reserved.
DC# Site 2 EU Production (Premium)
URLs 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 Page 7 of 80
SFAPI Functional Guide US
Arizona
4
EMEA
Amsterdam (ASM-5)
5
US
Ashburn
8
APJ
Sydney
10
EMEA
Rot
12
AZ Production (Standard) AZ Salesdemo EU Production (Standard) Ashburn Production (Premium) Ashburn Salesdemo Sydney Production (Premium) Rot Production (Standard)
https://api2.successfactors.eu resolve to the same servers) https://api4.successfactors.com/sfapi/v1/soap https://api4.successfactors.com/sfapi/v1/soap12 https://salesdemo4.successfactors.com/sfapi/v1/soap https://salesdemo4.successfactors.com/sfapi/v1/soap12 https://api5.successfactors.eu/sfapi/v1/soap https://api5.successfactors.eu/sfapi/v1/soap12 https://api8.successfactors.com/sfapi/v1/soap https://api8.successfactors.com/sfapi/v1/soap12 https://apisalesdemo8.successfactors.com/sfapi/v1/soap https://apisalesdemo8.successfactors.com/sfapi/v1/soap12 https://api10.successfactors.com/sfapi/v1/soap https://api10.successfactors.com/sfapi/v1/soap12 https://api012.successfactors.eu/sfapi/v1/soap https://api012.successfactors.eu/sfapi/v1/soap12
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
Page 8 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
2 Using SFAPI 2.1 SFAPI Setup 2.1.1 Enabling SFAPI In order to use the SFAPI, SuccessFactors must enable the API for your company instance. Please contact your SuccessFactors support representative details to enable the SFAPI for your instance.
2.1.2 API Login Permission Each user of the API must have API Login Permission. An administrator of your SuccessFactors system can grant this permission. The permission setting in the UI is Manage Users > API Login Permission. Setting this permission depends on which permission system you are using in your SuccessFactors instance. Below are instructions for 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 Login Permission link. This link is highlighted in the following page.
All rights reserved.
Page 9 of 80
SFAPI Functional Guide
2.1.2.2 Granting API Login Permission in the Role Based Permission System API Login Permission in the Role Based Permission system is listed under the General User Permission category in the Permission settings page. See below.
Page 10 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
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 manage for your integrations which are typically built against a specially designated API user account, where you don’t want to update the passwords on these accounts with the same frequency of the general user population. For this reason you can set exceptions to the password policy for your API user, and specify a different password expiration (maximum password age) policy. Since this is a tradeoff in security, we add in a requirement that users which have password policy exceptions (which relaxes security) must have an IP address restriction in order to connect to 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.
All rights reserved.
Page 11 of 80
SFAPI Functional Guide
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 of the expanded section. This will bring up the following dialog.
Page 12 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
Here you can add a user-specify password expiration. You must provide a username, and the desired maximum password age in days (-1 means the password will not expire, though we do not recommend this). You must also provide IP address restrictions for this user.
2.1.4 Data Specific Permissions In addition to API Login Permission, there are permissions that control access to data in the SFAPI. The permissions vary depending on the data being access. Please see the API ENTITY 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 the administrative permission of "Employee Export". In order to Insert, Update, or Upsert rows in the User entity, you must have administrative permission of "Employee Import."
All rights reserved.
Page 13 of 80
SFAPI Functional Guide
2.2 Connecting to the API 2.2.1 Authentication Authentication is established through the Login operation. A successful login will return a session ID as an HTTP Cookie. This cookie must be passed back to all subsequent HTTP Requests that invoke API operations in order to authenticate. The API session will timeout after 10 minutes of inactivity. You can also manually invalidate 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 permissions required 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 > Administrative Privileges > Manage Users > Import Employee to the SFAPI user link. This makes the SFAPI useful for data integrations between systems. However the SFAPI does not provide use cases appropriate for non-administrative access (aka – normal end users). Refer to the SFAPI Data Dictionary documentation to understand the permissions required for various API operations on each entity.
2.2.3 Handling HTTP Cookies The SFAPI is state aware, and there are several cookies that must be handled. One is for the 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 payload information 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 allows you 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 and debugging of API usage. The intended end user will be a developer who is using the API during an implementation or an administrator who can share information in this log with Page 14 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide SuccessFactors support to help resolve API related support issues. The tool allows you to download data from individual calls, which you could then send to a SuccessFactors support 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 30 days. You can use this page to see API call history analytics like how many times the API was 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 SF instance. 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 TYPE GUIDE, which will give entity specific details like business context and permission configuration 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 each individual tool by an administrator of your SuccessFactors system. Granting access to the Integration Tools pages depends on which permission system you are using in your SuccessFactors instance. The following are instructions for each permission system.
2.3.4.1 User Based Permission System Permission to access the Integration Tools is granted by an administrator of your SuccessFactors instance. These permissions can be found in the “Administrative Privileges” page. This location of this page depends on which Admin Tools version you are using:
2.3.4.1.1 Accessing Administrative Privileges Page in New Admin Tools The Administrative Privileges page is accessed through the Administrative Privileges link found under the Set User Permissions icon, as seen below:
All rights reserved.
Page 15 of 80
SFAPI Functional Guide
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 accessed through 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 the Integration Tools through the following steps: 1. Search for a user and select the checkbox for the user.
Page 16 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 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 in the 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 as links under Integration Tools in the older version of Admin page as shown
All rights reserved.
Page 17 of 80
SFAPI Functional Guide
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. Page 18 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
This page will show the last 10,000 API calls to this system. For each call, you can view the actual payload of data sent across. For example, if a call was to import Users, you could see the user data that was sent in the import call. The payload information can be viewed by selecting the button under the "SOAP" or "HTTP" columns in the log table. This will show you the actual SOAP payload or the raw HTTP payload details. IMPORTANT: Since this is sensitive data, care should be taken when granting permission on who can see this audit log. One safe strategy would be to grant this feature to developers only when necessary for development and debugging purposes, and then remove access to this feature. NOTE: that the log will always be captured, regardless of whether a particular user may see the log or not. Therefore, removing a user's access to the log will not remove the actual data in the log.
2.3.5.2 API Metering Details Selecting the API Metering Details link will bring up the following page.
All rights reserved.
Page 19 of 80
SFAPI Functional Guide
You can view API call history in time intervals selected at the top of the screen, ranging from 6 hours to 30 days. Here we have a selected a 6 hour time interval. You can also vary the information presented by using the text drop-down at the top left of the screen. Here we have selected "Call Count". You can also view record count (useful to see how many rows of data were accessed in either import or queries), bandwidth, and call processing time 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 TYPE GUIDE, which will give entity specific details like business context and permission configuration details for each entity. Page 20 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
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 be processed in a single Insert/Update/Upsert/Delete method. This number can be set to a value from 1 to 800 by specifying the batchSize parameter for insert, update, upsert or delete operations, or in the login method, which sets the default batchSize for the session.
2
By default, a maximum of 200 rows will be returned in a single Query/QueryMore method. This number can be set to a value from 1 to 800 by specifying the maxRows parameter in the query method.
3
A maximum SOAP message size (HTTP content-size) cannot exceed 5MB. This is the limit when upload binary attachment using SFAPI. In general, the total attachment storage size is controlled by the attachment storage configuration of the company instance
All rights reserved.
Page 21 of 80
SFAPI Functional Guide
3 SFAPI Operations 3.1 API Summary The SFAPI is intended to address import and export of SuccessFactors data. It is designed in a generic approach. The data that you can access from the API is not defined in the WSDL. Instead you can use the API metadata operations to discover the data and its schema in your SuccessFactors instance. There are five categories of methods in the API: 1. 2. 3. 4. 5.
Session Management (login/logout/isValidSession) MetaData Inspection (list/describe) Data Manipulation (insert/update/upsert/delete) Data Query (query/queryMore) 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 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 and entity information). DescribeExResult describeEx(String type[], SFParameter params[]) This method is in beta development and and is not stable yet. It will stabalize in the 1109 release. 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.
Page 22 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide InsertResult insert(String type, SFObject[] objects, SFParameter[] processingParam) Inserts the objects of the specified entity type. The operation will resume if one row has failed 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 has failed 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, perform the insert operation, if the row exists, perform the update operation. The operation will resume 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 if one 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 (SuccessFactors Query Language). For a detailed grammar description, please check the related section in this reference guide. QueryResult queryMore(String querySessionId) The queryMore call is provided to support paging. It requires a querySessionId to identify the 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 query string in SFQL (SuccessFactors Query Language). TaskStatus includes “taskId” which is used to identify a submitted job. For a detailed grammar description, please check the related 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()
All rights reserved.
Page 23 of 80
SFAPI Functional Guide 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 Operations Before accessing any SuccessFactors data, you must establish a login session. You can programmatically check to validate that you are in a login session and logout at the end of the session to maximize application security. Session management operations include:
3.2.1 API Signature Description Signature
Description
Boolean isValidSession()
Validate that the session is still operational.
LoginResult login(SFCredential) Create an API login session. LogoutResult logout()
Destroy the login 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. Name
Description
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.
3.2.2.2 SFCredential Name
Description
companyId
Identifies the SuccessFactors client instance.
developerKey NOT USED. Leave it blank. password
Page 24 of 80
The password associated with the username.
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 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 more details 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
Description
Name
The parameter name.
Value
The parameter value.
3.2.3 Login LoginResult login( SFCredential credential, List params) Creates the SFAPI session. A successful API session is required for any subsequent API calls.
3.2.3.1 Supported Parameters Name
Type
Description
credential
SFCredential
Specifies user login credentials.
params
List
batchSize will specify the default pageSize to use for data manipulation operations (Insert, Update or Upsert). This can be a value from 1 to 800. The system will default to pageSize of 200 if not specified.
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 specify session settings. SF Parameter Value
All rights reserved.
Description
Page 25 of 80
SFAPI Functional Guide batchSize
An integer from 1 to 800
batchSize will specify the default pageSize to use for data manipulation operations (Insert, Update or Upsert). This can be a value from 1 to 800. The system will default to pageSize 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), new QName(NS_SFAPI_SERVER, SFAPIService)); fProxy = fService.getSFAPI(); Map requestContext = ((BindingProvider) fProxy).getRequestContext(); // Need to set the property to maintain 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 params = new LinkedList(); LoginResult result = fProxy.login(credential, params); List 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.");
Page 26 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 3.2.3.4 Example SOAP Request XML acme user1 pwd batchSize 500
3.2.3.5 Example SOAP Response XML 676D4E614BC41AB6660A4DC8AE267F31 9223372036854775807 (Expired time in ms, this value means never expires) All rights reserved.
Page 27 of 80
SFAPI Functional Guide
3.2.3.6 Example SOAP Failed Response FAILED_AUTHENTICATION Login failure due to the invalid company!
3.2.4 LogOut boolean logout() Destroys the current API session.
3.2.4.1 Supported Parameters None.
3.2.4.2 Example Java Code if (fProxy.logout()) { System.out.println("Logout Successfully."); … Page 28 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide } else { System.out.println("Failed to logout"); }
3.2.4.3 Example SOAP Request XML
3.2.4.4 Example SOAP Response XML true
3.2.4.5 Example SOAP Failed Response false
3.3 MetaData Discovery Methods The MetaData methods allow for dynamic discovery of SFObjects available in the API. This allows you to list all the objects in the system, and describe objects to inspect their structure All rights reserved.
Page 29 of 80
SFAPI Functional Guide and provide meta information about the object, like which API data manipulation operations are supported for this object.
3.3.1 API Signature Signature
Description
DescribeResult[ ] describe(String[] types, List params )
Describes the SFObjects specified by the list of entity names. Note you can get all the available entity names of the SFObjects using the list() call below. The returned DescribeResult contains metadata to describe the object properties in terms of name, data type and other important metadata.
List 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 API Framework Objects 3.3.2.1 DescribeResult DescribeResult has the following properties: Name
Description
error
List of error codes and messages.
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 metadata about the field like field name, data type, etc. See the Field object definition for 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 to one of the values retuned in the API list() operation.
Page 30 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 3.3.2.2 Field Object The Field object contains metadata about an SFObject field. It is necessary for runtime discovery of field properties. The Field object has the following properties: Name
Description
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
A 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 beyond this length will be truncated.
name
A unique name for the field.
picklist
A Picklist object which provides enumerated values for this field. These can be configured / set up in the Administrative area 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).
All rights reserved.
Page 31 of 80
SFAPI Functional Guide 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 is 1.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 bytes when the string is converted to UTF-8 encoding.
3.3.2.4 Picklist Picklist has the following properties: Name
Type
Description
id
String
A unique id for this picklist.
picklistOptions
PicklistOption [ ]
An array of selectable options for this picklist.
source
String
The source is used.
3.3.2.5 Picklist Option PicklistOption has the following properties:
Page 32 of 80
Name
Type
Description
externalCode
String
An external code that can be associated with this value.
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide id
Integer
A unique id for this picklist option.
labels
Label [ ]
A list of localized labels for this picklist option.
status
String
A status for this picklist. Status can be "ACTIVE", "OBSOLETED" or "DELETED". Only "ACTIVE" picklist options will be displayed in the SuccessFactors application.
value
Integer
An integer value assigned to this picklist option.
3.3.2.6 Label A localized label object. Label contains the following properties: Name
Type
locale
String
Description Optional. The locale for this label, where the locale = language code + "_" + country code + "_" + variant. The language code should adhere to ISO 639, the country code to ISO 3166. Variant has no requirements on format. The following are valid locale strings: "en" - English language "en_US" - English language specific to the US "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 the SuccessFactors application will interpret the label as html, otherwise it will be rendered as plain text.
value
String
The localized label.
All rights reserved.
Page 33 of 80
SFAPI Functional Guide 3.3.3 List String[] list() List the entities in your company instance.
3.3.3.1 Supported Parameters None.
3.3.3.2 Example Java Code ListSFObjects param = new ListSFObjects(); ListSFObjectsResponse result = fProxy.list(param); System.out.println("Entity list:"); for (String fieldName : result.getName()) { System.out.println("\t" + fieldName); }
3.3.3.3 Example SOAP Request XML
3.3.3.4 Example SOAP Response XML User LearningActivity$4001 MatrixManager CustomManager SecondManager Background_googledocs Background_insideWorkExperience Page 34 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide Background_specialAssign Background_outsideWorkExperience Background_education Background_courses Background_certificates Background_awards Background_languages Background_funcExperience Background_leadExperience Background_preferredNextMove Background_mobility Background_memberships Background_community Background_promotability Background_compensation Background_varPayEmpHistData CalibrationSubject JobPosting BackgroundCheck Onboarding TrendData_sysOverallPerformance TrendData_sysOverallPotential TrendData_sysOverallObjective TrendData_sysOverallCompetency Goal$1 Goal$3
3.3.4 Describe DescribeResult describe(String type[], SFParameter params[]) Returns metadata about the list of entities specified in the type parameter.
All rights reserved.
Page 35 of 80
SFAPI Functional Guide 3.3.4.1 Supported Parameters Name
Type
Description
params
List
NOT USED. Leave it null.
type
String [ ]
A list of string values that specify entity names (entity types) that you want to describe. These values come from the list() operation.
3.3.4.2 Example Java Code 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 labelList = field.getLabel(); if (labelList != null & labelList.size() > 0) { for (Label label : field.getLabel()) { System.out.println("\tLabel : "); System.out.println("\t Value : " + 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()); Page 36 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide ++index; } System.out.println("Supported Operations : "); for (FeatureType featureType : result.getFeature()) { System.out.println(" " + featureType.value()); } }
3.3.4.3 Example SOAP Request XML LearningActivity$4001 locale en-US
3.3.4.4 Example SOAP Response XML LearningActivity$4001 GUID string
All rights reserved.
Page 37 of 80
SFAPI Functional Guide 256 true ParentId string 100 false upsert
3.3.4.5 Example SOAP Failed Response ns2:Server SFAPI Domain Error! UNDEFINED_ENTITY_ID Entity type 'Learn22ingActivity$4001' is undefined!
Page 38 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 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 an extended version of the describe method.
3.3.5.1 Supported Parameters Name
Type
Description
params
List
NOT USED. Leave it null.
type
String [ ]
A list of string values that specify entity names (entity types) that you want to describe. These values come from the list() operation.
3.3.5.2 Example SOAP Request XML LearningActivity$4001 locale en-US
All rights reserved.
Page 39 of 80
SFAPI Functional Guide
3.3.5.3 Example SOAP Response XML learningactivity$4001 GUID string 256 true false true false false false false false false ParentId string 100 false false true false false Page 40 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide false false false false upsert
3.3.5.4 Example SOAP Failed Response ns2:Server SFAPI Domain Error! UNDEFINED_ENTITY_ID Entity type 'Learn22ingActivity$4001' is undefined! Note Locale specifies the returned localized labels for each field.
All rights reserved.
Page 41 of 80
SFAPI Functional Guide
3.4 Data Manipulation Operations The data manipulation operations provide the CRUD (Create, Read, Update, Delete) style operations on the SFObjects exposed in the API. Refer to the separate SFAPI Data Dictionary document to ensure you have the proper permissions setup to access the desired SFObjects. There are four data manipulation operations, insert/update/upsert and delete().
3.4.1 API Signature Signature
Description
DeleteResult[ ] delete(String type, List sfobject, List processingParam)
Delete the SFObjects specified by the id field in the SFObject list, and report an error if the id is not found.
InsertResult[ ] insert(String type, List sfobject, List processingParam)
Insert the list of SFObjects. Errors will be reported if the rows to be inserted already exist in the system. Consult the individual SFObject types in the separate SFAPI Data Dictionary for any processingParam that may apply.
UpdateResult[ ] update(String type, List sfobject, List processingParam)
Update the rows specified by the id field in the SFObject list, and report errors if the row id does not exist in the system. Consult the individual SFObject types types in the separate SFAPI Data Dictionary for any processingParam that may apply.
UpsertResult[ ] upsert(String type, List sfobject, List processingParam)
The upsert operation will insert or update the given list of SFObjects. This operation will check if the specified 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 the separate SFAPI Data Dictionary for any processingParam that may apply.
Page 42 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 3.4.2 API Framework Objects 3.4.2.1 SFObject SFObject is a generic class for all SFAPI data objects. An SFObject is analogous to a row in 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 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 element which will contain the data fields requested in the queryString, or supplied by the user for import type operations. SFObject has the following fields: Name
Type
Description
any
List
The list of the SFObject fields. The format is: FieldValue. The list element is a DOM object.
id
String
A unique identifier for the object. This is required field when in update/delete operations. In insert/upsert operations, this field 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 to control method processing. For example, in user import you can pass in a parameter to control whether welcome messages are sent to new users. SFParameter has the following properties: Property Name
Type
Description
Name
String
The parameter name.
Value
String
The parameter value.
All rights reserved.
Page 43 of 80
SFAPI Functional Guide 3.4.2.3 InsertResult/UpdateResult/DeleteResult/UpsertResult All four of these result type objects have the same format. The result objects are used to contain results and status of the data manipulation request - where multiple objects were processed during the request. In addition to the overall status and error code, the status of the each row processed has a specific status and error message. Name
Type
Description
jobStatus
String
Indicates if there were errors encountered while 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 the return value is ERROR. For ex, if the required externalId is not specified in insert operation, the status will return ERROR code. Check the row level error by examining the objectEditResult for which row is causing the error. message
String
The message from this job. Usually this is a summary field indicating the number of rows processed, the number of rows failed and the processing time.
objectEditResult
List An array of the edit results for the objects that were imported. Each row in the request message will have a related ObjectEditResult.
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: Name
Page 44 of 80
Type
Description
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide errorStatus
String
Indicates if there was an error editing the object. Values can be one of the following:
OK ERROR NO_MATCH (only in Update or Delete operations)
Note that even if there was an ERROR encountered, the editStatus below should still be checked. An ERROR does not mean the editStatus is automatically NO_EDIT. Index
Integer
A zero based index into the input array of SFObjects that was submitted for edits to which this ObjectEditResult applies.
editStatus
String
Indicates what type of edit operation was performed on the object. Values can be one of the following:
message
String
CREATED UPDATED DELETED NO_EDIT
Contains an error message if an error was encountered. (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.
3.4.3.1 Supported Parameters Parameter Name
Type
Description
objects
SFObject [ ]
A list of SFObjects that you want to insert. Errors will be reported if the rows
All rights reserved.
Page 45 of 80
SFAPI Functional Guide already exist in the system, or if you are missing any required fields. The required fields can be discovered using the describe() operation for this entity. processingParam
List
List of optional parameters.
type
String
The entity type name that you want to insert. This must correspond to a value returned by the list() operation.
3.4.3.2 Example Java Code List sfobjects = new LinkedList(); // 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"); user1.getAny().add(element); element = factory.createElement("firstName"); element.addTextNode("Carla"); user1.getAny().add(element); element = factory.createElement("lastName"); element.addTextNode("Grant"); user1.getAny().add(element); element = factory.createElement("email");
Page 46 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide element.addTextNode("
[email protected]"); user1.getAny().add(element); 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()); }
3.4.3.3 Example SOAP Request XML user user cgrant cgrant active pwd Carla Grant
[email protected] USR-8 USR-8 test All rights reserved.
Page 47 of 80
SFAPI Functional Guide test test test PST 2010-01-01
3.4.3.4 Example SOAP Response XML OK USR-4389 OK CREATED 0
3.4.3.5 Example SOAP Failed Response
Page 48 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide ERROR ERROR NOEDIT 0 INTERNAL_ERROR : User already exists. 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 has failed to update.
3.4.4.1 Supported Parameters Parameter Name
Type
Description
objects
SFObject [ ]
A list of SFObjects that you want to update. Errors will be reported if the rows do not exist in the system.
processingParam
List
List of optional parameters.
type
String
The entity type name that you want to update. This
All rights reserved.
Page 49 of 80
SFAPI Functional Guide must correspond to a value returned by the list() operation.
3.4.4.2 Example SOAP Request XML user USR-4389 user test 123
3.4.4.3 Example SOAP Response XML OK USR-4389 OK
Page 50 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide UPDATED 0
3.4.4.4 Example SOAP Failed Response OK NO_MATCH NOEDIT 0 USER_NOT_FOUND : Cannot find user by user id. InternalId = USR-224389 Note
All rights reserved.
Page 51 of 80
SFAPI Functional Guide Update requires the ID key. Note you can update password just like other normal fields. For security, 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, perform the insert operation, if the row exists, perform the update operation. The operation will resume if one row has failed to upsert.
3.4.5.1 Supported Parameters Parameter Name
Type
Description
objects
SFObject [ ]
A list of SFObjects that you want to upsert. Errors will be reported if you are missing any required fields. The required fields can be discovered using the describe() operation for this entity
processingParam
List
List of optional parameters.
type
String
The entity type name that you want to upsert. This must correspond to a value returned by the list() operation.
3.4.5.2 Example Java Code List sfobjects = new LinkedList(); // 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");
Page 52 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide user1.getAny().add(element); element = factory.createElement("username"); element.addTextNode("user1"); user1.getAny().add(element); element = factory.createElement("firstName"); element.addTextNode("Carla"); user1.getAny().add(element); element = factory.createElement("lastName"); element.addTextNode("Grant"); user1.getAny().add(element); element = factory.createElement("email"); element.addTextNode("
[email protected]"); user1.getAny().add(element); sfobjects.add(user1); UpsertResult result = fProxy.upsert("User", sfobjects, null); System.out.println("Upsert 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()); }
3.4.5.3 Example SOAP Request XML user user All rights reserved.
Page 53 of 80
SFAPI Functional Guide cgrant cgrant active cgrant test test test test test test M
[email protected] USR-8 USR-8 test test test test PST 2010-01-01 test test test test test test test test test test test test test Page 54 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
3.4.5.4 Example SOAP Response XML OK USR-4388 OK UPDATED 0
3.4.5.5 Example SOAP Failed Response
All rights reserved.
Page 55 of 80
SFAPI Functional Guide ns2:Server SFAPI Domain Error! INVALID_ REQUEST_MESSAGE Invalid request message! Error: Invalid date value 2010-012-01 at message#=1,field#=108,field=servicedate! Note Upsert should return success code of "UPDATED" or "CREATED", otherwise it will return operation failed error code and message.
3.4.6 Delete 3.4.6.1 Supported Parameters
Page 56 of 80
Parameter Name
Type
Description
Objects
SFObject [ ]
A list of SFObjects that you want to delete. Errors will be reported if the row does not exist.
processingParam
List
List of optional parameters.
Type
String
The entity type name that you want to delete from. This must correspond to a value returned by the list() operation.
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
3.4.6.2 Example Java Code List sfobjects = new LinkedList(); // 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("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()); System.out.println("\tError Message : " + objectEditResult.getMessage()); }
3.4.6.3 Example SOAP Request XML MatrixManager MMGR-1484 MatrixManager
All rights reserved.
Page 57 of 80
SFAPI Functional Guide
3.4.6.4 Example SOAP Response XML OK MMGR-1484 OK DELETED 0
3.4.6.5 Example SOAP Failed Response ns2:Server SFAPI Domain Error!
Page 58 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide UNSUPPORTED_OPERATION Entity type 'User' doesn't support DELETE operation!
3.5 Data Query Operations The interfaces included data query feature using the SFQL. The methods also support query by pagination.
3.5.1 API Signature
Signature
Description
QueryResult query(String queryString, Queries the SuccessFactor platform using SFQL List params ) query string. The maximum rows count is 200. If the Use queryMore() to retrieve the data page by page. The returned QueryResult contains the matching SFObjects specified by SFQL, the row count returned and the querySessionId used with subsequent queryMore() method call to retrieve the data. QueryResult queryMore(String querySessionId)
All rights reserved.
Retrieve the next page data of the previous query.
Page 59 of 80
SFAPI Functional Guide 3.5.2 API Framework Objects 3.5.2.1 QueryResult QueryResult has the following properties: Name
Type
Description
hasMore
boolean
Flag to indicate if there are more result set available. 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 matching SFObjects.
querySessionId
String
A unique identifier used to pass into the queryMore operation if there are more rows. This will identify the next page of rows to retrieve in the queryMore operation.
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 (SuccessFactors Query Language). For detail grammar description, please check the related section in this reference 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 remaining results is accomplished using the queryMore() operation. The QueryResult object will return a boolean parameter "hasMorePages" to indicate if there are more pages remaining and a querySessionId, which must be passed into the queryMore() method to get the next page of results.
Page 60 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide You can set the page size for a query by setting the "maxRows" parameter in the query method to an integer value from 1 to 800. The default page size is 200, and the maximum page size is 800.
3.5.3.1 Supported Parameters 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 the pageSize for the returned result rows of the query. This can be a value from 1 to 800. The system will default to pageSize of 200 if not specified.
3.5.3.3 Example Java Code query() & queryMore() query() & queryMore() // display up to 25 records in all int numRowsToPrint = 25; String sfql = "SELECT externalId, userName, firstName, lastName, email FROM User"; List paramList = new LinkedList(); SFParameter param = new SFParameter(); // Set query page 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();
All rights reserved.
Page 61 of 80
SFAPI Functional Guide numRowsToPrint -= result.getNumResults(); } System.out.println("The total row count returned is " + count + "."); /** * Dump the query result. * * @param result *
the query result.
* @param numRowsToPrint *
the remaining rows to dump.
* @param startRowIndex *
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("="); } else { Page 62 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide System.out.println("='" + getNodeTextValue(field) + "'"); } } } } }
3.5.3.4 Example SOAP Request XML select id,username from user where hrId ='USR-91' and username is not null maxRows 10 startingRow 3
3.5.3.5 Example SOAP Response XML All rights reserved.
Page 63 of 80
SFAPI Functional Guide USR-4385 User test_noexport USR-4386 User test_110124102601 USR-4387 User test2_110124102602 USR-4388 User cgrant USR-4389 User cgrant_2 5 false 3209cbb1-2302-41ea-af76-b8158f34bd7d Page 64 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide
3.5.3.6 Example SOAP Failed Response ns2:Server SFAPI Domain Error! UNDEFINED_ENTITY_ID Entity type 'user23' is undefined! Note Query Session returned in query is used for queryMore operation (pagination), but the server 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 query operation. 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 if there are more results, along with a new querySessionId to be used in the next queryMore call.
All rights reserved.
Page 65 of 80
SFAPI Functional Guide 3.5.4.1 Supported Parameters None
3.5.4.2 Example Java Code See the example listed for the query operation.
3.5.4.3 Example SOAP Request XML 4afa1b00-81f5-4d37-be72-382967c4cb22
3.5.4.4 Example SOAP Response XML USR-4385 User test_noexport USR-4386 User test_110124102601
Page 66 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide USR-4387 User test2_110124102602 USR-4388 User cgrant USR-4389 User cgrant_2 5 false 3209cbb1-2302-41ea-af76-b8158f34bd7d
3.5.4.5 Example SOAP Failed Response ns2:Server SFAPI Domain Error!
All rights reserved.
Page 67 of 80
SFAPI Functional Guide UNDEFINED_ENTITY_ID Entity type 'user23' is undefined! 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 query session 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. The allowable grammar is documented in BNF Notation (Backus-Naur Form) in the next section.
3.5.5.2 SFQL Grammar ::= SELECT FROM WHERE ] [order by timeoutMs) {
All rights reserved.
Page 71 of 80
SFAPI Functional Guide 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(); } }
3.6.3.3 Example SOAP Request XML Page 72 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide select emp_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
3.6.3.4 Example SOAP Response XML TASK-ADHOC-2364 SFAPI_0109172739317_ectint 2012-01-09T09:27:41.612Z submitted
3.6.4 GetJobStatus TaskStatus getJobStatus(String taskId) Get the execution status of the submitted asynchronous job. All rights reserved.
Page 73 of 80
SFAPI Functional Guide 3.6.4.1 Example Java Code Please refer to code in above “SubmitQueryJob” section.
3.6.4.2 Example SOAP Request XML TASK-ADHOC-2364
3.6.4.3 Example SOAP Response XML TASK-ADHOC-2364 SFAPI_0109172739317_ectint 2012-01-09T09:27:41.612Z submitted 2364 2012-01-09T09:28:15.032Z 2012-01-09T09:28:08.266Z finished
Page 74 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 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: Name
Type
Description
taskId
String
TaskId which is returned in SubmitQueryJob
format
String
Currently, it supports csv and zipped_csv format only.
3.6.5.2 Example Java Code Please refer to code in above “SubmitQueryJob” section.
3.6.5.3 Example SOAP Request XML TASK-ADHOC-1021 csv
3.6.5.4 Example SOAP Response HTTP/1.1 200 OK Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.4; JBoss-4.0.5.GA (build: CVSTag=Branch_4_0 date=200610162339)/Tomcat-5.5 Content-Type: multipart/related; type="text/xml"; boundary="uuid:996a038b-52d8-42189af3-5da7177dbb31"
All rights reserved.
Page 75 of 80
SFAPI Functional Guide Transfer-Encoding: chunked Date: Wed, 25 May 2011 07:58:26 GMT --uuid:996a038b-52d8-4218-9af3-5da7177dbb31 Content-Type: text/xml --uuid:996a038b-52d8-4218-9af3-5da7177dbb31 Content-Id: Content-Type: application/octet-stream Content-Transfer-Encoding: binary "Email","Username","ANALYTICS_LIST_VIEW_BUILDER_SUBDOMAIN_ectint_ectint#us ers_sysinfo#USERS_SYS_ID" "
[email protected]","aceadmin","aceadmin" "
[email protected]","admin","admin" "
[email protected]","admin1","admin1" "
[email protected]","admin11","admin11" "
[email protected]","admin2","admin2" "
[email protected]","v4admin","v4admin" -uuid:996a038b-52d8-4218-9af3-5da7177dbb31
3.6.6 ListJobs List listJobs() List all running and waiting to run jobs.
3.6.6.1 Supported Parameters No parameters for now.
3.6.6.2 Example Java Code ... List tasks = sfapi.listJobs(); // Iterate tasks for (TaskStatus task : tasks) { System.out.println (task.getId() + “ “ + task.getName() + “ “ + task.getStatus()); } …
Page 76 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide 3.6.6.3 Example SOAP Request XML
3.6.6.4 Example SOAP Response XML TASK-ADHOC-2004 SFAPI_1101145047.222_ectint 2011-11-01T06:50:57.241Z submitted 2004 2011-11-01T07:14:42.016Z 2011-11-01T07:14:21.232Z Job Name:[SFAPI_1101145047.222_ectint (2004)] Job Instance Id:[2004] Process Notes:[Job successfully completed] running TASK-ADHOC-2005 SFAPI_1101151557.620_ectint 2011-11-01T07:15:57.760Z submitted
All rights reserved.
Page 77 of 80
SFAPI Functional Guide 2005 2011-11-01T07:16:28.608Z 2011-11-01T07:16:27.449Z Job Name:[SFAPI_1101151557.620_ectint (2005)] Job Instance Id:[2005] Process Notes:[Job successfully completed] running TASK-ADHOC-2006 SFAPI_1101152635.919_ectint 2011-11-01T07:26:35.959Z submitted 2006 2011-11-01T07:27:01.349Z 2011-11-01T07:26:59.876Z Job Name:[SFAPI_1101152635.919_ectint (2006)] Job Instance Id:[2006] Process Notes:[Job successfully completed] running TASK-ADHOC-2007 SFAPI_1101153644.590_ectint 2011-11-01T07:36:45.032Z submitted 2007 2011-11-01T07:37:14.127Z 2011-11-01T07:37:02.420Z Job Name:[SFAPI_1101153644.590_ectint (2007)] Job Instance Id:[2007] Process Notes:[Job successfully completed]
Page 78 of 80
Copyright ©2013 SuccessFactors, Inc.
SFAPI Functional Guide running TASK-ADHOC-2008 SFAPI_1101153701.852_ectint 2011-11-01T07:37:02.007Z submitted 2008 2011-11-01T07:37:14.127Z 2011-11-01T07:37:02.429Z Job Name:[SFAPI_1101153701.852_ectint (2008)] Job Instance Id:[2008] Process Notes:[Job successfully completed] running
3.6.7 CancelJob TaskStatus cancelJob(String taskId) Cancel a waiting to run job.
3.6.7.1 Supported Parameters “taskId” – TaskId is the id returned in “submitQueryJob”
3.6.7.2 Example Java Code ... TaskStatus task = sfapi.cancelJob(“TASK-ADHOC-1200”); System.out.println (task.getId() + “ “ + task.getName() + “ “ + task.getStatus()); …
All rights reserved.
Page 79 of 80
SFAPI Functional Guide 3.6.7.3 Example SOAP Request XML TASK-ADHOC-2011
3.6.7.4 Example SOAP Response XML TASK-ADHOC-2011 SFAPI_1101153813.779_ectint 2011-11-01T07:38:15.724Z canceled
Page 80 of 80
Copyright ©2013 SuccessFactors, Inc.
