Академический Документы
Профессиональный Документы
Культура Документы
Table of Contents
1 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
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.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
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.
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.
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.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.
The links can be accessed from here in the new Admin Page as shown.
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.
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..
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.
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. 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.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.
3.2.2.2 SFCredential
Name Description
companyId Identifies the SuccessFactors client instance.
developerKey NOT USED. Leave it blank.
password The password associated with the username.
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<SFParameters> params)
Creates the SFAPI session. A successful API session is required for any subsequent API
calls.
batchSize An integer batchSize will specify the default pageSize to use for data
from 1 to 800 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.4 LogOut
boolean logout()
Destroys the current API session.
Signature Description
DescribeResult[ ] describe(String[] Describes the SFObjects specified by the list of entity names. Note
types, List<SFParameter> params ) 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<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.
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.
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
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.
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).
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:
3.3.2.6 Label
A localized label object. Label contains the following properties:
3.3.3 List
String[] list()
List the entities in your company instance.
3.3.4 Describe
DescribeResult describe(String type[], SFParameter params[])
Returns metadata about the list of entities specified in the type parameter.
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.
Signature Description
DeleteResult[ ] delete(String type, Delete the SFObjects specified by the id field in
List<SFObject> sfobject, List the SFObject list, and report an error if the id is not
<SFParameter> processingParam) found.
InsertResult[ ] insert(String type, Insert the list of SFObjects. Errors will be reported
List<SFObject> sfobject, List if the rows to be inserted already exist in the
<SFParameter> processingParam) system.
Consult the individual SFObject types in the
separate SFAPI Data Dictionary for any
processingParam that may apply.
UpdateResult[ ] update(String type, Update the rows specified by the id field in the
List<SFObject> sfobject, List SFObject list, and report errors if the row id does
<SFParameter> processingParam) 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, The upsert operation will insert or update the given
List<SFObject> sfobject, List list of SFObjects. This operation will check if the
<SFParameter> processingParam) 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.
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.
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.
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:
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.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.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.6 Delete
3.4.6.1 Supported Parameters
Signature Description
QueryResult query(String queryString, Queries the SuccessFactor platform using SFQL
List<SFParameter> 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 Retrieve the next page data of the previous query.
querySessionId)
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.
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.
Signature Description
TaskStatus submitQueryJob(String Submit the asynchronous query job to the
queryString, SFParameter[] param) 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
3.6.3 SubmitQueryJob
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 includes the information of submitted task.
3.6.4 GetJobStatus
TaskStatus getJobStatus(String taskId)
Get the execution status of the submitted asynchronous job.
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.6 ListJobs
List<TaskStatus> listJobs()
List all running and waiting to run jobs.
3.6.7 CancelJob
TaskStatus cancelJob(String taskId)
Cancel a waiting to run job.