SuccessFactors HCM Suite PUBLIC

November 2014 Release

Version: 1.0 - December 5, 2014

SuccessFactors HCM Suite Boomi

Connector Reference Guide
Content
1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Creating a Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

2 SuccessFactors Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
2.2 Other Endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Company Id. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Username. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
2.5 Password. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Default Write Batch Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
2.7 Default Query Page Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
2.8 Default Timeout Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.9 Default Sleep/Wait Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.10 Object ID Type List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 SuccessFactors Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

3.1 Creating New Operations with the SuccessFactors Import Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1.1 SuccessFactors Import Wizard - Import Object Definitions from a Company Id. . . . . . . . . . . . 13
3.1.2 SuccessFactors Import Wizard - Choose the Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.3 Request and Response XML Profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2 Configuring SuccessFactors Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.1 Query Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.2 Write Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4 SuccessFactors Tools and Reference Material. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

2 © 2014 SAP SE or an SAP affiliate company. All rights reserved. Content
1 Introduction
The SuccessFactors Dell Boomi connector extends the SuccessFactors HCM Suite SFAPI to the Boomi platform.
The SFAPI is an entity/object based web services (SOAP) interface that provides typical Create/Read/Update/
Delete operations for specified BixX object types and forms. This connector provides a user-friendly interface for
creating and managing SFAPI connections and operations.

There are three kinds of SFAPI object types:

● Form Based Object Types: These are objects that reference custom BixX Form objects. These objects have a
suffix in the form of “<object type>$<form id>”.

Note
The form id is a unique identifier for the form object that can vary from Company Id to Company Id.

● Standard Object Types: These are basic objects that do not have the Form ID suffix. The objects names are
consistent between Company Id’s.
● ADHOC Object Types: These are objects that extend Ad-Hoc Reports to the SFAPI. They only support a read
operation known as “Asynchronous Query”. There are two types of ADHOC object types:

○ Object types that create new reports when queried. These object types provide access to all the fields of
the ADHOC report. These object types are all prefixed with “ADHOC_”.
○ Object types that represent saved reports created in the SuccessFactors Adhoc Report Builder user
interface. These expose only a subset of the fields defined in the corresponding ADHOC_ report object
type. These object types are named “AdhocReport_<reportId>”.

Asynchronous query operations run “asynchronously”: the query is executed in the HCM Suite cloud and the
cloud is polled periodically using a “get job status” operation, waiting for the report to be queued and completed.
Once completed, the results will be fetched by the SuccessFactors Connector.

Best Practice: Asynchronous queries are very useful because they provide the ability to join multiple related ob­
ject types. Synchronous queries only allow return records from a single object type. For example, an asynchro­
nous query from an Adhoc object type can return employee data that includes personal information, job history
and postal address information related to each employee.

The steps that occur when running an asynchronous query are:

1. The report is created from query and saved as an Adhoc Report (ADHOC_ object types only)
2. A report job is submitted to the scheduler for execution. (Both ADHOC_ and AdhocReport_/saved reports).
3. The connector periodically executes a “get job status” operation waiting for the report to complete execution.
4. The report definition is deleted from the Adhoc Saved Reports (ADHOC_ object types only).
5. The results are downloaded from the SuccessFactors cloud to the connector.

Note: Even though the Adhoc SFAPI returns CSV files in either zip’ed or non compressed text formats, the Boomi
Connector converts these results to XML, matching the XML profile generated by the connector when an Adhoc
object type is imported into the connector.

Best Practice: Report execution results are stored in the SuccessFactors cloud for 30 days. You can log into
SuccessFactors and download any report execution form the Saved Reports page.

To find the name of the report that is executed, open the Boomi execution log and scroll down to where the report
name is logged. Both the report name (prefixed with SFAPI) and the Task/Job ID will appear in the Boomi log file|

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

Introduction © 2014 SAP SE or an SAP affiliate company. All rights reserved. 3
1.1 Terminology

● "Object Type" is synonymous with "entity". Boomi's preferred term is "object" while the SuccessFactors
SFAPI materials refer to "entities".
● Company Id is synonymous with tenant or cloud-instance. Specifically, the Company Id represents a specific
instance in a specific data center.

1.2 Creating a Connector

Procedure

1. Select SuccessFactors from the Connector drop down list.

2. Choose the Action the connector will perform (Create, Update, Upsert, Delete,Execute(OData write) or
Query)
3. Choose an existing Connection or create a new Connection. SuccessFactors Connection [page 5]
4. Choose an existing Operation or create a new Operation. SuccessFactors Operation [page 10]

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

4 © 2014 SAP SE or an SAP affiliate company. All rights reserved. Introduction
2 SuccessFactors Connection
The Connection is where you specify the data center, company id and credentials for executing SFAPI
transactions. Connecting to an existing company id requires both the endpoint URL to the data center and the
company Id specifying a specific instance in the data center. Please refer to the SuccessFactors Tools and
Reference Material [page 35] for more information on configuring SFAPI connections.

2.1 Endpoint

This list allows the user to specify the endpoint to the SFAPI servers. The endpoint is specific to the global
datacenter where the HCM Suite Company Id instance is deployed. The endpoint URL specifies where to send the
SOAP XML request payloads.

Select the URL from the drop down menu. If the URL is not listed in the dropdown menu, select the Other option in
the menu and manually enter the URL in the Other Endpoint field. There is an endpoint and accompanying WSDL
for each data center.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Connection © 2014 SAP SE or an SAP affiliate company. All rights reserved. 5
2.2 Other Endpoint

To connect to an endpoint/server not included in the Endpoint list, provide a custom URL endpoint in this field.
Note, you must select Other in the Endpoint list to enable this field.

2.3 Company Id

The Company Id specifies the instance for the connection. In combination with the endpoint, this specifies a
unique instance in a specific global data center.

Note
The SFAPI must be provisioned for this specific Company Id in order for SFAPI transactions to be executed.

2.4 Username

Username for a valid user in the specified client instance. The user should have the SFAPI Login Permission, and
permissions to access any desired data objects and read/write operations.

Best Practice: Prefix this user name in the form "sfapi-<vendor or module use>" in lower case, for example:
sfapi-ec, sfapi-rcm, sfapi-saperp, sfapi-sapbyd, etc.. This will provide indication to administrators that this user
is being used for integration, and not to disable the user which would disable SFAPI access and break scheduled
integration processes.

2.5 Password

The password associated with the username.

Best Practice: It is best to configure this password so that it does not expire. This also requires white-listing the
IP address of any Boomi atoms/clouds that access the SFAPI. This can be setup in the Set Password ?Policy
section of Admin Tools.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

6 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Connection
 Best Practice: expose the endpoint, username and password connection attributes as Process Extensions so
they can be specified for different Boomi Environments. For example, the values specified can reflect develop­
ment values. Extensions can be specified for a "Test" Boomi Environment so the connector connects to a Test
instance. Different values can be specified for a "Production" environment. An added security benefit is that the
product credentials will be stored only on the Production Cloud (password strongly encrypted of course!) and
not in the Atomsphere development cloud. These credentials can be controlled only by Boomi users with privi­
leges to access the Production Cloud for the Boomi account.

2.6 Default Write Batch Size

Batch Size will specify the default pageSize to use for data manipulation / Write Operations [page 31] (Insert,
Update, Upsert, Execute(Odata) or Delete). This can be a value from 1 to 800. The default value is 200. It should
be set to a reasonably large number to limit the number of individual SOAP transactions, but not so large that
slower SOAP transactions exceed 1-2 minutes and risk timing out.

Note
This value is shared for all operations that reference the connection but can be overridden on a per operation
basis (see Connection Operation in this document).

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Connection © 2014 SAP SE or an SAP affiliate company. All rights reserved. 7
2.7 Default Query Page Size

This specifies the default result page size for Query Operation [page 20]. It is similar to the Batch Size
parameter but it controls the batch size for returned query results. It should be set to a reasonably large number
to limit the number of individual SOAP transactions but note the maximum value supported by the SFAPI is 800.

Note
This value is shared for all operations that reference the connection but can be overridden on a per operation
basis. For more formation see SuccessFactors Operation [page 10].

2.8 Default Timeout Time

For Asynchronous Queries Only. This specifies the time the system will wait for the completion of an
“Asynchronous Query” job for an Adhoc report.

Best Practice: Set this value large enough to allow for slow running queries and long scheduler queues.

Note
This value is shared for all operations that reference the connection but can be overridden on a per operation
basis. For more information please refer to SuccessFactors Operation [page 10].

2.9 Default Sleep/Wait Time

For Asynchronous Queries Only. This controls the frequency that the connector checks the status of an
“Asynchronous Query” job of an Ad Hoc report. A longer sleep/wait time limits the number of "get job status"
transactions

Best Practice: for long Timeout times, this value should also be set to a relatively large value to limit the number
of "get job status" transactions that occur while waiting for the query to complete.

Note
This value is shared for all operations that reference the connection but can be overridden on a per operation
basis.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

8 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Connection
2.10 Object ID Type List

Enables the setting of Form type entity Ids from a Connection Environment Extension. Specifies list of form IDs to
use in format PMForm=PMForm$1;JobRequisition=JobRequesition$13; In this case all PMForm type ids will be
set to PMForm$1 in order to function for a specific SuccessFactors tenant.

Note
This only allows one Form type per process.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Connection © 2014 SAP SE or an SAP affiliate company. All rights reserved. 9
3 SuccessFactors Operation

The Operation specifies the action that will be performed and the object type on which that action will be
performed.

The actions supported are:

● Query (OData and SFAPI) - Read a set of objects optionally sorted and limited to those records that meet a
specified search criteria (filter).
● Create (SFAPI only) - Insert a new record. This operation returns the new ID of the inserted object.
● Update(SFAPI only) - Update the specified field values of an existing record. The ID specifies the record to
update.
● Delete (SFAPI only)- Remove the record. The ID specifies the record to delete.

Note
Very few SuccessFactors object types support the Delete operation. Most perform "soft deletes" that
update the record with a status flag of "Inactive".

● Upsert (SFAPI only)- Write a record specified by a unique External ID. If a record with that external ID exists,
the record will be updated. Else a new record will be created.
● Execute - (Odata Only) - This operation is for writing SFOData entities. The type of write operation is specified
by the ODATA Method/Operation.

Note
For some object types, an internal ID will be returned as generated by the system.

3.1 Creating New Operations with the SuccessFactors Import

Wizard

Context

The only way to create a new SuccessFactors Operation is to Import an operation from a specific SuccessFactors
instance using the SuccessFactors Import Wizard. This is because each instance may have a unique set of
entities/forms/object types each with their own unique custom fields. The goal of an import operation is to select
an object definition from the instance and generate the input and output XML profiles for the object definition and
the respective action/operation type.

For more information on object types and allowed operations for an object, please refer to the SFAPI Data
Dictionary in the Admin Tools web page for the specific instance.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

10 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
Before importing a new operation you must first choose the Connector Action that will be used. There are two
ways to create a new SuccessFactors Operation and specify the Connector Action:

Procedure

1. Select Create Component from the Component Explorer. In this case you can select the Connector Action
from the new operation dialog that appears.
2. Create a new operation from an existing Connector. In this case the Connector Action will be disabled
because the operation is specified in the Connector.
In either case, a blank SuccessFactors Operation will be displayed.

Note
The Query Operations and Write (Create/Update/Upsert/Delete) operations have slight differences (see
images below).

Figure 1: A New Query Connector

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 11
 Figure 2: A New Write Operation

The full object list for a specific Company ID can be viewed using the Admin Tools SFAPI Data Dictionary.
3. Launch the SuccessFactors Import Wizard by clicking on the Import button.
The first page of the SuccessFactors Import Wizard appears.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

12 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
3.1.1 SuccessFactors Import Wizard - Import Object
Definitions from a Company Id

The first page of the wizard is used to specify from which SuccessFactors instance object definitions will be
imported.

3.1.1.1 Atom

Importing is an active operation that must execute on a Boomi Atom server.

Note
For security purposes, the Import operation is disabled on Boomi clouds. Hence a standalone atom (or a
development cloud if available for the Boomi account) must be used. If necessary, install a standalone atom on
a local computer for use when importing.

3.1.1.2 Connection

The Connection will specify which SuccessFactors instance from which to import object definitions. For more
information please refer to SuccessFactors Connection [page 5].

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 13
 Note
It is important to consider what instance the import is performing against because each instance may have a
different set of forms, object types and custom fields.

3.1.1.3 Filter Entities by Module

Selecting from this list will filter the list object definitions pertaining to the HCM Suite module selected. To see all
object types, select <All>. Selecting specific a specific HCM Suite module from the list will filter accordingly.

● Employee Central
● Goal Management
● Performance Management
● Platform
● Recruiting

3.1.1.4 Filter Entities by Name

Alternatively, you can perform a "wildcard" search for object types by specifying a search pattern in this field.

Note
Text in this field will override any selection made in the Filter Entities by Module list. For example, specifying
"erp" will return only PerPerson, PerPersonal, PerPhone, UserPhoto and UserPhotoSource.

If this field is left blank, the objects specified by the Filter Entities by Module will be returned.

Best Practice: The Boomi Connector framework doesn't allow more than 500 entity types to be listed. If your
HCM Suite tenant includes more than 500 entity types, you must provide a filter to limit the list to be smaller
than 500 records.

When the information is specified, click on Next to display the object list.

3.1.1.5 Set Min Occurs to 1 for all Fields

All elements will have min occurs set to 1 for write operations. This is useful to clear or set all fields of an object
type, in conjunction with the Respect Min Occurs? XML profile option.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

14 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
3.1.2 SuccessFactors Import Wizard - Choose the Object

Context

The second page of the SuccessFactors Import Wizard displays a list of object types for the Company Id specified
on the first page.

Procedure

1. Choose an object from the list to create the specified action/operation type for that object type.

After a few moments, the operation will be populated with the object specific information and respective XML
profiles will be created.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 15
2. Click on the Finish button to complete the generation of the SuccessFactors Operation.

Note: If the selected operation/action type is not supported for the selected object type, an error will be
displayed at this point. For more information, please refer to the SFAPI Data Dictionary in the SuccessFactors
Admin Tools page for the specified instance.

3.1.3 Request and Response XML Profiles

The SuccessFactors Import Wizard will automatically generate Request and Response XML Profiles.

Note
Field IDs are used as elements in the XML Profile. Field labels, if they exist, are indicated in the Comment field
displayed when clicking on a specific field ID element. For saved report object types, (Those with the
AdhocReport_ prefix, the Comment field will contain the descriptive name of the saved report.

3.1.3.1 XML Profiles for Write Operations

Write Operations [page 31] including Create, Update and Delete operations have both a Request and Response
profile.

The Request Profile for a Delete Operations contains only an element to specify the ID for the record to delete.
Request profiles for other write operations are those fields indicated as Insertable (Create operations),
_Updateable (Update operations) or _Upsertable (Upsert operations) per the object type specification in the SFAP
Data Dictionary.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

16 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
Request documents will have Constraints set according to the SFAPI Data Dictionary metadata for each field. If a
maximum length is specified for a field, this value would be reflected in the Constraint section. If the field is
required, Min Occurs will be set to 1 and the Minimum Length constraint will be set to 1.

For update and upsert operations for non-effective dated HCM Suite objects, you can leave an existing field value
unchanged by leaving the field value blank. To clear a value from an existing record, set the Min Occurs to 1 and
and select the Respect Min Occurs? option on the Options tab.

Upserts of effective data HCM Suite objects have a different behavior. By default, leaving a field blank will initiate a
NO_OVERWRITE behavior where the field for a new effective dated record will be set to the value for the field in
the previous record. Similarly to above, to clear a field and prevent the previous value to be propagated, set the
Min Occurs to 1 and and select the Respect Min Occurs? option on the Options tab.

Write operation Response Profiles provide the status of writing each document and any error indication. An index
is also provided to associate specific documents to specific response elements. For more information, please
refer to the SFAPI Error Messages Guide.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 17
 Note
The index is a 1 based ordinal that corresponds with the respective input documents. This ordinal can be used
to correlate the input data with each respective edit result.

3.1.3.2 XML Profile for Query Operations

Query Operations [page 20] only have a Response Profile.

Note
The only fields that will appear on the Response Profile are those fields indicated as Selectable or Constrainable
per the object type specification in the SFAP Data Dictionary.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

18 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
 Figure 3: Adhoc XML Response structure

3.1.3.3 Picklist Fields

Picklists fields are associated with SuccessFactors picklist tables. These are name/value pairs that appear in drop
down lists within the SuccessFactors user interface pages. For more information on picklists, refer to the
SuccessFactors Configuration Guide.

A picklist entry consists of:

1. The ID of the picklist. This ID is the same for each entry that appears in each individual drop down list.
2. The picklist label is displayed in the user interface and on reports. This label will be displayed in the language
of the SFAPI user.
3. The picklist option ID. This integer value is automatically generated when importing a picklist to a
SuccessFactors Company Id.
4. An optional externalCode that provides an alternate value that can be associated with a picklist entry.
5. A status field indicating whether or not the picklist is Active or Intactive (soft deleted).

The values contained in picklist fields are limited to the values contained in the associated picklist.

Enumerations are similar to picklist but are not configurable. Rather the possible set values are hard coded by the
object type. The picklist status field mentioned above is an example of an Enumeration field type.

Best Practice: Always use an SFAPI user that is associated with the en_US locale. This will ensure all labels will
use the en_US picklist labels.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 19
When a field is associated with a picklist, the picklist ID will be included in the Comment for the field. Similarly if
the field is associated with an Enumeration, the set of possible values will be included in the Comment for the field.

Best Practice: It is often useful to translate field values from one picklist field value to another. For example,
asynchronous query results will always contain the picklist label value, as will other object types. It may be nec­
essary to translate this value to the externalCode for writing to an external system (for example translate United
States to "USA"). It is tempting to use a hard coded Cross Reference Table to perform this but it is a much better
approach to use the picklist values because the spelling of the labels is guaranteed to match. If the label spelling
fails to match a Cross Reference Table entry, the field will be translated to a blank and may result in data integ­
rity issues.

Many object types require the picklist option ID when writing values to fields. Similarly a translation can be
performed to convert an externalCode value to the associated picklist Option ID.

The best way to perform these translations is to use the SuccessFactors Common Component to load picklists
into memory. Then use another Common Component map function to perform the translations.

Alternatively, picklists can be queried and written to Document Cache steps, but this will be a very cumbersome
approach as it will require a Document Cache for each picklist ID.

<Editors note, end Best Practice border here>

3.2 Configuring SuccessFactors Operations

Existing Operations will have the Object type and the Action defined as specified during the Import process. These
fields cannot be changed. To define a new Action/Operation type or to generate an operation for a different object
type, rerun the SuccessFactors Import Wizard.

Best Practice: Specify a small set of Tracked fields on the Tracking tab for ID, external ID and/or other record
identifiers such as last name, email, etc. This makes it easier to identify documents when analyzing process exe­
cutions. Note tracked fields must be defined for the Account on the Setup page before the are available on the
operation Tracking tab.

Once the operation definition has been imported, query and write operations can be configured using the
SuccessFactor Operation dialog windows.

3.2.1 Query Operation

This action will query records in the SuccessFactors object defined in the Create operation. All records will be
returned as individual Boomi Documents. Paging will be performed automatically according to the Page Size
parameter.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

20 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
This action returns zero to many object record documents from a single Query request based on zero or more
"filters".

3.2.1.1 Connector Action

Indicates the operation is indeed a Query operation.

Note
If you change the Connector Action, a new import will be required and the existing query settings will be
deleted.

3.2.1.2 Object

Defines the object on which the operation is executing. This is only set during an import operation.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 21
3.2.1.3 Response Profile

The XML profile that defines the XML schema/structure of the response document returned by the operation. For
more information regarding profiles, please see XML Profiles.

3.2.1.4 Return Application Error Responses

Defines whether to return exception responses through the process or fail at the connector level.

Best Practice: Leave Return Application Error Responses unchecked and catch the errors using a Try Catch
step.

3.2.1.5 Page Size

Overrides the write Page Size specified in the SuccessFactors Connection. For more information please refer to
Connection Page Size.

Note
If you override this value, you cannot control it from a Process Extension.

3.2.1.6 Starting Row

For synchronous queries only. Indicates to skip the first number of records specified. For example, a value of 10
skips the first 9 records. A value of 1 (default) returns all records.

3.2.1.7 Max Rows

Specifies the maximum number of records/documents to return. A value of -1 indicates returning all records.

Best Practice: Boomi allows querying a maximum of 10 documents during a Run as Test. Change this value to
10 to allow executing a Run as Test without error. *If you do this, don't forget to change it back to -1 before de­
ploying the process.

For simple processes, configure the Connector in the Start step which automatically prompts to override a large
number of returned records and rerun with only 10 documents.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

22 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
 Best Practice: For unit testing, disconnect the Connector and attach a Message step that contains a test docu­
ment. This allows your process to Run as Test much faster, especially when executing longer running Asynchro­
nous Queries.

You can even simulate multiple documents by adding a Split Documents Data Process step after the Message
step. Configure the Split Documents to split by line with no message header|

3.2.1.8 Timeout Time

For Asynchronous Queries Only . Overrides the value specified in the SuccessFactors Connection. For more
information please refer to Connection Timeout Time.

Note
If you override this value, you can not control it from a Process Extension.

3.2.1.9 Sleep/Wait Time

For Asynchronous Queries Only. Overrides the value specified in the SuccessFactors Connection. For more
information please refer to Connection Sleep/Wait Time.

Note
If you override this value, you can not control it from a Process Extension.

3.2.1.10 Keep Report Definition

For Asynchronous Queries Only. Selecting this option will leave the report definition in the Adhoc Saved Reports.
This option only works when directly running queries against report subdomain schemas (Object types with a
prefix of "ADHOC_").

Note
This option has no effect when running Asynchronous Queries on "saved reports" (Object types with a prefix of
"AdhocReport_").

Best Practice: Saving an Adhoc report is useful if you like to rerun a report directly from the Adhoc Report
Builder user interface in the SuccessFactors product.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 23
3.2.1.11 Remove Namespaces

This will remove the namespaces from the response payload of the EmployeeCompound entity so that they will
match the generated XML profile. This was added for compatibility with old operations and it is recommend you
turn this on for EmployeeCompound queries.

3.2.1.12 Results Format(async query only)

Specifies the format of the document returned from the Asynchronous Query Operation.

● XML - returns the results as multiple documents in XML format.

● Split CSV Documents - returns the results as multiple documents in CSV format. Each document has a
header. The header names match the element names of the XML format.
● Single CSV Document - returns the results as a single document. The headers match the field labels.
● Compressed (Zip) - Same as Single CSV Document but the document is in Zip format.

3.2.1.13 Object ID Process Property

(Optional) Specifies the name of the process property that contains the object type. This overrides the object type
ID extracted during Import. This is generally used for Form object type types to allow the object type ID to be
specified dynamically as an Environment Extension.

Best Practice: you should always use this field for Form object types because the integer component of a Form
object type ID (For example, "PMForm$22") can vary from instance to instance.

3.2.1.14 Filter Process Property

Context

(Optional) Specifies the name of the process property that contains the object type. This overrides the object type
ID extracted during Import. This is generally used for Form object type types to allow the object type ID to be
specified dynamically as an Environment Extension.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

24 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
To use this feature:

Procedure

1. Create a Set Properties step that sets the value of a Dynamic Process Property to be the SFQL/Odata URI
string you wish to use.
2. Enter the name of the the Dynamic Process Property in this field.
3. When you execute the process, the contents of the property are used for the filter

Best Practice: you must exam the Boomi Log File connector entries to verify that your filter was generated
properly.

OData Example: set the contents of the process property to &fromDate=2013-01-01&toDate=2014-12-31 in

order to perform a date range query for an effective dated entity. Similarly you can perform an as-of-date
query using &asOfDate=2014-12-31. You can also set the $filter= uri parameter but you must be
knowledgeable of the odata filter syntax to do so.

SFAPI Example: set the contents of the process property to companyTerritoryCode=XXX AND
department=YYY in order to override the entire SFQL WHERE clause

3.2.1.15 SFAPI Parameters

(optional) For specifying SFAPI SFParameters. For example: traceLevel=detailedLogging.

3.2.1.16 OData Import Depth (import only)

Determines how deep to traverse associations/navigation properties to the entity in order to do join/expand
query operations. For example, a depth of 2 for the SFOData.PerPerson entity will result in the ability to query/join
down to related entities like SFOData.JobInfo. The larger the depth, the deeper and more complex the query will
result.

Caution
WARNING: Deep queries will result in all fields selected by default. You should turn off only those fields
necessary our your query will not perform well.

3.2.1.17 OData Allow Circular References (Import Only)

Allows query results to include self references and circular references to same entity type.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 25
3.2.1.18 Filter Entities by Module (Import Only)

For Import Only. For more information, please refer to SuccessFactors Import Wizard. For existing operations this
field has no effect and will only reflect what value, if any, was used during import.

3.2.1.19 Filter Entities by Name (Import Only)

For Import Only. For more information, please refer to SuccessFactors Import Wizard. For existing operations this
field has no effect and will only reflect what value, if any, was used during import.

3.2.1.20 The Query Operation sub tabs

Upon complete of an Import of a query operation, three sub tabs appear in the Query Operation dialog: Query
Fields, Query Filter, Query Sort. The following sections describe these sub tabs.

3.2.1.21 Query Fields

This sub tab specifies what subset of fields to return in the resultant document. Select the topmost checkbox to
select all the fields.

Note: The only fields that will appear on the Query Fields sub tab are those fields indicated as Selectable per the
object type specification in the SFAP Data Dictionary.

Deep OData queries are supported by selecting fields within the field hierarchy. Any field selected at the top level
will be included in the OData $select statement. Any fields selected in child entities will cause that entity to be
included in an OData $expand operation, causing all the fields in the entity to be joined into the query

Best Practice: By Default, all fields will be selected for query. This can result in extremely complex and poorly
performing queries, especially for OData.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

26 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
 Best Practice: For best performance it is best to select only the fields necessary for the integration process but
beware, if you fail to select a field, it will always be blank in the response profile and you will get no indication of
that unless the response XML Profile has it flagged as a mandatory field.

Note
If you perform a re-import of an operation, any newly added fields will be automatically selected. It may be
necessary to turn off these fields if not used in the integration process.

3.2.1.22 Query Filter

This sub tab specifies filter criteria to limit the records returned that conform to a specified search criteria.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 27
 Note
The only fields that will appear on the Query Filter sub tab are those fields indicated as Filterable or
Constrainable per the object type specification in the SFAPI Data Dictionary.

Both filterable and constrainable fields will support at least one of the following filter operators as specified in the
Operator drop down list:

● EQUAL TO - a record's field value matches the specified filter parameter value
● GREATER THAN - a record's field value is greater than the specified filter parameter value
● LESS THAN - a record's field value is less than the specified filter parameter value
● GREATER THAN OR EQUAL TO - a record's field value is greater than or equal to the specified filter parameter
value
● LESS THAN OR EQUAL TO - - a record's field value is less than or equal to the specified filter parameter value
● IS NULL - a record's field field is blank
● IS NOT NULL - a record's field field is not blank
● IN - a record's field value matches one of a comma delimited list of values specified in the filter parameter.

Note
The operator drop down list will only include filter operators that field supports per the object type specification
in the SFAPI Data Dictionary.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

28 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
 Note
Important: Except for IS NULL and IS NOT NULL operators, you must also specify a value for each filter
argument on the Connectors Parameters Tab accessible by double clicking on the Connector step.

Best Practice: The IN operator can be used to join the results of several synchronous queries of individual object
types. This provides an alternate to using ADHOC reports to join related object types. This technique will result
in fast performance, but use with caution with extremely large data sets.

1. First query the set of parent records using filter criteria to limit the number of documents returned.
2. Connect this record to two branches, the first of which builds a comma delimited list of parent ID's from the
result set.
3. Feed this comma delimited list to one or more branches connecting to synchronous query operations for
each of the child object types of the join, each of which has a filter that uses an IN operator on the foreign
keys (parent ID) for each record.
4. Feed the result set of each child query operation to a Document Cache step indexed by the foreign key (pa­
rent ID). Note the IN filter parameter will be set to receive the Current Data which contains the comma de­
limited list of parent IDs.
5. Connect the second branch from the parent query to a map function that uses the parent documents as the
main profile, and uses Document Cache Map Lookups to join in each child object type.

Note
An IN operator has a maximum of 1000 values, so use of the Boomi Flow Control step may be required to
batch comma separated ID values to a query that utilizes an IN filter operation.

3.2.1.23 Filterable vs. Constrainable

Synchronous query operations only support Filterable fields. Filters for such operations can specify complex
boolean expressions consisting of nested AND and OR logical operators.

ADHOC_ object types support both Filterable and Constrainable fields. Constrainable fields represent "required
fields" for a report filter. These are fields that specify the population of users to include in the query results (the
report builder People tab) and required fields for effective dated reports such as effective date ranges to limit the
dates of returned records.

Filters using Constrainable fields must be a single level of filter operators using only the AND logical operator.
Neither complex nest expressions nor OR operators are supported.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 29
Use of filters with constrainable fields requires restrictions on the structure of a filter "tree" as displayed in the
figure below:

AdhocReport_ object types only provide Constrainable fields for the filter set up by the report designer. No
filterable fields are exposed.

An example of of a setting up filter using Constrainable fields is displayed below. This filter specifies the "Snapshot
date" to limit the values of effective dated records to values that are in effect on the specified date.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

30 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
3.2.1.24 Query Sort

This sub tab enables sorting the results of a query by the specified fields values. Sortable fields support either
Ascending or Descending sort order.

Note
The only fields that will appear on the Query Sort sub tab are those fields indicated as Sortable per the object
type specification in the SFAP Data Dictionary.

Best Practice: Open the Boomi log file to view the raw query statement for the executed query operation. Sim­
ply scroll down to where the "SELECT " statement appears.

3.2.2 Write Operations

Write operations are those that perform the Create, Update, Upsert or Delete actions. For more information
regarding SFAPI specifics of these actions, please refer to SuccessFactors Operation.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 31
3.2.2.1 Connector Action

Indicates the type of write operation.

Note
If you change the Connector Action, a new import will be required and the existing settings will be deleted.

3.2.2.2 Object

Defines the object on which the operation is executing. This is only set during an import operation.

3.2.2.3 ODATA Method/Operation

This specifies the type of ODATA write operation that will be performed. User can choose from Delete, Update/
Merge, Update/Replace, Create/Post, Upsert/Post.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

32 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
3.2.2.4 Request Profile

The XML profile that defines the XML schema/structure of the response document returned by the operation. For
more information regarding profiles, please see XML Profiles.

3.2.2.5 Response Profile

The XML profile that defines the XML schema/structure of the response document returned by the operation. For
more information regarding profiles, please see XML Profiles.

3.2.2.6 Batch Size

Overrides the write Batch Size specified in the SuccessFactors Connection. For more information, please refer to
Connection Batch Size.

Note
If you override this value, you cannot control it from a Process Extension.

3.2.2.7 Return Application Error Responses

Defines whether to return exception responses through the process or fail at the connector level.

Best Practice: Leave Return Application Error Responses unchecked and catch the errors using a Try Catch
step.

3.2.2.8 Filter Entities by Module

For Import Only. For more information, please refer to SuccessFactors Import Wizard. For existing operations this
field has no effect and will only reflect what value, if any, was used during import.

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Operation © 2014 SAP SE or an SAP affiliate company. All rights reserved. 33
3.2.2.9 Filter Entities by Name

For Import Only. For more information, please refer to SuccessFactors Import Wizard. For existing operations this
field has no effect and will only reflect what value, if any, was used during import.

3.2.2.10 Object ID Process Property

(Optional) Specifies the name of the process property that contains the object type. This overrides the object type
ID extracted during Import. This is generally used for Form object types to allow the object type ID to be specified
dynamically as an Environment Extension.

Best Practice: you should always use this field for Form object types because the integer component of a Form
object type ID (For example, "PMForm$22") can vary from instance to instance.

3.2.2.11 SFAPI Parameters

Use this field to specify a comma delimited list of name/value pairs that specify extra parameters available to
specific HCM Suite object types. For example, a User object type create operation, this field could contain
"managerTransfer:true, routeInboxDoc:false" specified as SFAPI parameters to set the managerTransfer
parameter to "true" and routeInboxDoc parameter to "false".

For more information, please refer to the SFAPI Entity Type Guide.

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

34 © 2014 SAP SE or an SAP affiliate company. All rights reserved. SuccessFactors Operation
4 SuccessFactors Tools and Reference
Material
● SFAPI Admin Tools

○ SFAPI Data Dictionary

○ SFAPI Audit Log

● SuccessFactors Reference Library

● SFAPI Functional Guide
● SFAPI Error Messages Guide
● SFAPI Entity Type Guide
● SuccessFactors Configuration Guide for info on picklists??

SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC

SuccessFactors Tools and Reference Material © 2014 SAP SE or an SAP affiliate company. All rights reserved. 35
Important Disclaimers and Legal Information

Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.

Accessibility
The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a
binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does
not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales
person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not
exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages
caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency
(see: http://help.sap.com/disclaimer).

PUBLIC SuccessFactors HCM Suite Boomi Connector Reference Guide

36 © 2014 SAP SE or an SAP affiliate company. All rights reserved. Important Disclaimers and Legal Information
SuccessFactors HCM Suite Boomi Connector Reference Guide PUBLIC
Important Disclaimers and Legal Information © 2014 SAP SE or an SAP affiliate company. All rights reserved. 37
www.sap.com/contactsap

© 2014 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any

form or for any purpose without the express permission of SAP SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only
warranties for SAP or SAP affiliate company products and services
are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein
should be construed as constituting an additional warranty.
SAP and other SAP products and services mentioned herein as well
as their respective logos are trademarks or registered trademarks
of SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the
trademarks of their respective companies.
Please see http://www.sap.com/corporate-en/legal/copyright/
index.epx for additional trademark information and notices.