SuccessFactors Connector - Mule 3

Anypoint Connector for SAP SuccessFactors (SuccessFactors Connector) provides full support to query, create, update, and delete entities using the SFAPI API exposed by SuccessFactors. For more information about the product, visit SAP SuccessFactors HCM Suite site.

Release Notes: SuccessFactors Connector Release Notes
Exchange: SuccessFactors Connector

Before You Begin

To use this information, you should be familiar with SAP SuccessFactors and have an SAP account. To use this connector, you need a working installation of Anypoint Studio with the SuccessFactors connector installed.

Install the Connector

In Anypoint Studio, click the Exchange icon in the Studio taskbar.
Sign in to Exchange with your Anypoint Platform credentials.
From Anypoint Exchange, click Provided by MuleSoft.
Search for the Mule 3 connector and click Install.

Create a New Project

To use SuccessFactors Connector in a Mule app, first create a new Mule project in Anypoint Studio:

In Anypoint Studio, click File > New > Mule Project.
Enter a name for your new project and leave the remaining options with their default values.
If you plan to use Git, select Create a .gitignore file for the project with default ignore settings for Studio Projects, and then click Next.
Click Finish to create the project.

Namespace and Schema Location

When you drag a connector onto the Studio canvas, the configuration XML for your Mule app is populated with the namespace and schema.

Namespace:

xmlns:successfactors="http://www.mulesoft.org/schema/mule/successfactors"

Schema Location:

http://www.mulesoft.org/schema/mule/successfactors/current/mule-successfactors.xsd

If you are manually coding the Mule app in Studio’s XML editor or other text editor, define the namespace and schema location in the header of your Configuration XML, inside the <mule> tag.

To Configure a SuccessFactors Global Element with the Studio Visual Editor

To use SuccessFactors Connector in your Mule app, configure a global configuration element that can be used by all SuccessFactors Connectors in the app.
Click the Global Elements tab at the base of the canvas.
On the Global Mule Configuration Elements screen, click Create.
In the Choose Global Type wizard, expand Connector Configuration, and select Success Factors: Configuration.
Click OK.

Configure the parameters according to the instructions below.

Field	Description
Name	Enter a name for the configuration with which it can be referenced later.
Username	Username to log into SuccessFactors and access its API.
Password	Password for the username.
Company ID	ID of the organization in SuccessFactors which information you wish to manage.
Connection Timeout	Specifies the amount of time, in milliseconds, that the client attempts to establish a connection before it times out. 0 means attempt to open a connection indefinitely.
Receive Timeout	Specifies the amount of time, in milliseconds, that the client waits for a response before it times out. 0 means wait indefinitely.
WSDL Location	Location of the SFAPI SOAP 1.1 WSDL.
Fetch all entities	Check this if you wish to see the complete list of entities available for all operations. Building this list is a very slow process so checking this box is strongly discouraged. If you leave this unchecked, complete the Entity List.
Entity List	Required, if the Fetch All Entities box is not checked. Complete this with a list of names of all the entities you wish to work with.

Field

Description

Name

Enter a name for the configuration with which it can be referenced later.

Username

Username to log into SuccessFactors and access its API.

Password

Password for the username.

Company ID

ID of the organization in SuccessFactors which information you wish to manage.

Connection Timeout

Specifies the amount of time, in milliseconds, that the client attempts to establish a connection before it times out. 0 means attempt to open a connection indefinitely.

Receive Timeout

Specifies the amount of time, in milliseconds, that the client waits for a response before it times out. 0 means wait indefinitely.

WSDL Location

Location of the SFAPI SOAP 1.1 WSDL.

Fetch all entities

Check this if you wish to see the complete list of entities available for all operations. Building this list is a very slow process so checking this box is strongly discouraged. If you leave this unchecked, complete the Entity List.

Entity List

Required, if the Fetch All Entities box is not checked. Complete this with a list of names of all the entities you wish to work with.

Click Test Connection and confirm receipt of the Connection Successful message.
Click OK to save the global connector configurations.

To Configure a SuccessFactors Global Element with the XML Editor

To use SuccessFactors Connector in your Mule app, configure a global configuration element that can be used by all SuccessFactors Connectors in the app.

Include the SuccessFactors namespaces in your configuration file.

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:successfactors="http://www.mulesoft.org/schema/mule/successfactors"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
  xmlns:spring="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/successfactors http://www.mulesoft.org/schema/mule/successfactors/current/mule-successfactors.xsd">
</mule>

Create a global SuccessFactors configuration outside and above your flows using the following global configuration code.

<successfactors:config name="Success_Factors__Configuration" username="${username}" password="${password}" companyId="${companyId}" wsdlLocation="${wsdlLocation}" doc:name="Success Factors: Configuration" fetchAllEntities="false">
        <successfactors:entity-list>
            <successfactors:entity-list>Goal$1</successfactors:entity-list>
            <successfactors:entity-list>picklistlabel</successfactors:entity-list>
            <successfactors:entity-list>picklistoption</successfactors:entity-list>
            <successfactors:entity-list>TrendData_sysOverallCompetency</successfactors:entity-list>
            <successfactors:entity-list>user</successfactors:entity-list>
        </successfactors:entity-list>
    </successfactors:config>

Field	Description
Name	Enter a name for the configuration with which it can be referenced later.
Username	Username to log into SuccessFactors and access its API.
Password	Password for the username.
Company ID	ID of the organization in SuccessFactors which information you wish to manage.
Connection Timeout	Specifies the amount of time, in milliseconds, that the client attempts to establish a connection before it times out. 0 means attempt to open a connection indefinitely.
Receive Timeout	Specifies the amount of time, in milliseconds, that the client waits for a response before it times out. 0 means wait indefinitely.
WSDL Location	Location of the SFAPI SOAP 1.1 WSDL.
Fetch all entities	Set this to true if you wish to see the complete list of entities available for all operations. Building this list is a very slow process so checking this box is strongly discouraged. If you set this to false, fill out the Entity List field.
Entity List	Required if the Fetch All Entities parameter is false. Enter a list of names of all the entities you wish to work with.

Field

Description

Name

Enter a name for the configuration with which it can be referenced later.

Username

Username to log into SuccessFactors and access its API.

Password

Password for the username.

Company ID

ID of the organization in SuccessFactors which information you wish to manage.

Connection Timeout

Specifies the amount of time, in milliseconds, that the client attempts to establish a connection before it times out. 0 means attempt to open a connection indefinitely.

Receive Timeout

Specifies the amount of time, in milliseconds, that the client waits for a response before it times out. 0 means wait indefinitely.

WSDL Location

Location of the SFAPI SOAP 1.1 WSDL.

Fetch all entities

Set this to true if you wish to see the complete list of entities available for all operations. Building this list is a very slow process so checking this box is strongly discouraged. If you set this to false, fill out the Entity List field.

Entity List

Required if the Fetch All Entities parameter is false. Enter a list of names of all the entities you wish to work with.

Using the Connector

For details on operations see the SuccessFactors connector technical reference and click the APIdoc for your connector version.

Using the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule app, this XML snippet must be included in your pom.xml file.

<dependency>
  <groupId></groupId>
  <artifactId></artifactId>
  <version>x.y.z</version>
</dependency>

Replace x.y.z with the version that corresponds to the connector you are using.

To obtain the most up-to-date pom.xml file information, access the connector in Anypoint Exchange and click Dependency Snippets.

SuccessFactor Connector Use Cases and Demos

The SuccessFactors Connector is an operation-based connector that allows you to invoke web service operations exposed by the SFAPI API.

This section of the manual provides a brief description of simple use case scenarios for this connector:

List Entities Use Case
Describe Entity Use Case
Query Use Case
Upsert Use Case
Update Use Case
Insert Use Case
Delete Use Case

All of the example use cases are stored in one Mule app. See Flow XML for Use Cases.

List Entities Use Case

This flow retrieves the list of entities in your organization.

The connector itself does not require any additional configuration, apart from the operation to select:

List entities operation properties window

To test it, run the flow in Studio and open a browser window. Visit http://localhost:8081/ and click the List*button under the List Entities section to see the list of entities available.

Describe Entity Use Case

This flow retrieves all the available metadata from an entity in your organization.

The Describe entities operation only needs a list of strings corresponding to the entities you wish to retrieve the metadata for. In this example, this input is configured to take the payload sent to it by the preceding endpoint.

Describe entities operation properties window

In order to design the input for the connector, we use the Dataweave language made available through the Transform Message component. Its output is a list containing just one element, which is the query parameter 'entity' from the HTTP Connector.

Add the below DataWeave code to the DataWeave editor inside the Transform Message component.

%dw 1.0
%output application/java
---
[inboundProperties."http.query.params".'entity']

Run the flow in Studio to test this and open a browser window. Visit http://localhost:8081/. Click on List under List Entities, then click on an entity name. Finally, click the Describe button under the Describe Entities section to see all the available metadata for the entity selected.

Query Use Case

This flow runs a query on Success Factors and shows the response.

The Query operation needs a query and a page size.

You can either enter the native (SFQL) query language, or build it with the DataSense Query Builder.

Query builder window for query flow with fields selected

You can leave the page size at the default value.

To test this flow, run the flow in Mule Studio and open a browser window. Visit http://localhost:8081/query. You see the result of the query in the browser.

Upsert Use Case

This flow does the following:

Inserts a new User (or updates it, if it already exists).
Returns the output of the upsert.

The SuccessFactors endpoint needs to be configured with the Upsert operation. First, select the type of the entity you wish to upsert, which in this example is a User. If the Type dropdown is not populated, click the refresh button on the right. The input structure is taken from the payload returned by DataWeave.

DataWeave turns the JSON object taken from the payload of the HTTP endpoint and converts it to a map, which is the input needed for the Upsert operation.

To test this flow, run the flow in Mule Studio and open a browser window. Enter http://localhost:8081/ and click the Submit button under the Upsert User section to see the result of the upsert operation in the browser.

Update Use Case

This flow does the following:

Updates a User with a new username.
Returns the output of the last update.

The SuccessFactors endpoint needs to be configured with the Update operation. First, select the type of the entity you wish to update, which in this case is a User. If the Type dropdown is not populated, click the refresh button on the right. The input structure will be taken from the payload returned by DataWeave.

DataWeave turns the JSON object taken from the payload of the HTTP endpoint and converts it to a map, which is the input needed for the Update operation.

To test this flow, run the flow in Mule Studio and open a browser window. Visit http://localhost:8081/ and click the Submit button under the Update User section to see the result of the update operation in the browser. If you have already run the Upsert demo, the input for the Update job should have already been populated.

Insert Use Case

This flow inserts a new Goal$1 entity and returns the output of the insertion.

The SuccessFactors endpoint needs to be configured with the Insert operation. Select the type of the entity you wish to insert, which in this case is Goal$1. If the Type dropdown is not populated, click the refresh button on the right. The input structure will be taken from the payload returned by DataWeave.

DataWeave turns the JSON object taken from the payload of the HTTP endpoint and converts it to a map, which is the input needed for the Insert operation.

To test this flow, run the flow in Mule Studio and open a browser window. Visit http://localhost:8081/ and click the Submit button under the Insert Goals section to see the result of the insert operation in the browser.

Delete Use Case

This flow deletes an existing Goal entity and returns the output of the deletion.

The SuccessFactors endpoint needs to be configured with the Delete operation. Select the type of the entity you wish to delete. If the Type dropdown is not populated, click the refresh button on the right. The input structure is taken from the payload returned by DataWeave.

DataWeave turns the JSON object taken from the payload of the HTTP endpoint and converts it to a map, which is the input needed for the Delete operation:

To test this flow, run the flow in Mule Studio and open a browser window. Visit http://localhost:8081/ and click the Submit button under the Delete Goal section to see the result of the delete operation in the browser. If you have already run the Insert demo, the input for the Delete job should have already been populated.

Flow XML for Use Cases

Paste the below code into your XML Editor to run the use case examples.

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting"
xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking"
xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw"
xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:successfactors="http://www.mulesoft.org/schema/mule/successfactors" xmlns:mulexml="http://www.mulesoft.org/schema/mule/xml"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
  xmlns:spring="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/xml
http://www.mulesoft.org/schema/mule/xml/current/mule-xml.xsd
http://www.mulesoft.org/schema/mule/ee/dw
http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
http://www.mulesoft.org/schema/mule/successfactors
http://www.mulesoft.org/schema/mule/successfactors/current/mule-successfactors.xsd
http://www.mulesoft.org/schema/mule/json
http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
http://www.mulesoft.org/schema/mule/ee/tracking
http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/scripting
http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081"
    doc:name="HTTP Listener Configuration"/>
    <successfactors:config name="Success_Factors__Configuration" username="${username}"
    password="${password}" companyId="${companyId}" wsdlLocation="${wsdlLocation}"
    doc:name="Success Factors: Configuration">
        <successfactors:entity-list>
            <successfactors:entity-list>Goal$1</successfactors:entity-list>
            <successfactors:entity-list>picklistlabel</successfactors:entity-list>
            <successfactors:entity-list>picklistoption</successfactors:entity-list>
            <successfactors:entity-list>TrendData_sysOverallCompetency</successfactors:entity-list>
            <successfactors:entity-list>user</successfactors:entity-list>
        </successfactors:entity-list>
    </successfactors:config>

<scripting:transformer name="EntityForCrudObject" doc:name="Groovy">
  <scripting:script engine="Groovy" file="src/main/resources/EntityForCrudObject.groovy"></scripting:script>
</scripting:transformer>

<scripting:transformer name="AddIdToEntity" doc:name="Groovy">
  <scripting:script engine="Groovy" file="src/main/resources/AddIdToEntity.groovy"></scripting:script>
</scripting:transformer>

    <flow name="htmlFormFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="/"/>
        <parse-template location="form.html" doc:name="Parse Template"/>
        <set-property propertyName="Content-Type" value="text/html" doc:name="Property"/>
    </flow>
    <flow name="listEntitiesFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="list" doc:name="/list"/>
        <successfactors:list-entities config-ref="Success_Factors__Configuration" doc:name="Success Factors"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
    <flow name="describeEntitiesFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="describe" doc:name="/describe"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-variable variableName="entity"/>
            <dw:input-inbound-property doc:sample="map_string_string.dwl" propertyName="http.query.params"/>
            <dw:input-inbound-property propertyName="http.uri.params"/>
            <dw:set-payload><![CDATA[%dw 1.0%output application/java
---
[inboundProperties."http.query.params".'entity']]]></dw:set-payload>
        </dw:transform-message>
        <successfactors:describe-entities config-ref="Success_Factors__Configuration" doc:name="Success Factors"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
    <flow name="queryFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="query" doc:name="/query"/>
        <successfactors:query config-ref="Success_Factors__Configuration"  doc:name="Success Factors"
  queryString="dsql:SELECT email,externalId,firstName,lastName,username FROM user"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
    <flow name="submitQueryFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="submitQueryJob" doc:name="/submitQueryJob"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
inboundProperties."http.query.params".'query']]></dw:set-payload>
        </dw:transform-message>
        <successfactors:submit-query-job config-ref="Success_Factors__Configuration" doc:name="Success Factors"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
    </flow>
    <flow name="getJobResultFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="getJobResult" doc:name="/getJobResult"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-inbound-property propertyName="http.query.params" doc:sample="map_string_string_1.dwl"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
  format: "csv",
  taskId: inboundProperties."http.query.params".'taskId'
} as :object {
  class : "com.successfactors.sfapi.sfobject.GetJobResult"
}]]></dw:set-payload>
        </dw:transform-message>
        <successfactors:get-job-result config-ref="Success_Factors__Configuration" doc:name="Success Factors"/>
    </flow>
    <flow name="upsertFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="upsert" doc:name="/upsert" allowedMethods="POST,"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-payload doc:sample="json.json"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
// Some output fields were skipped as the structure is too deep (more than 2 levels).
// To add missing fields click on the scaffold icon (second on the toolbar).
payload]]></dw:set-payload>
        </dw:transform-message>
        <logger message="Executing upsert: #[payload]" level="INFO" doc:name="Logger"/>
        <successfactors:upsert config-ref="Success_Factors__Configuration" type="user" doc:name="Update/Insert a User"
  doc:description="try to create a new user, if the user exists only updates it">
            <successfactors:input ref="#[payload]"/>
        </successfactors:upsert>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
        <logger message="Upsert result: #[payload]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="updateFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/update" doc:name="/update"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-payload doc:sample="json_1.json"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
payload]]></dw:set-payload>
        </dw:transform-message>
        <logger message="Executing update: #[payload]" level="INFO" doc:name="Logger"/>
        <successfactors:update config-ref="Success_Factors__Configuration" type="user" doc:name="Update a User">
            <successfactors:input ref="#[payload]"/>
        </successfactors:update>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
        <logger message="Update result: #[payload]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="insertFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/insert" doc:name="/insert"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-payload doc:sample="json_2.json"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
payload]]></dw:set-payload>
        </dw:transform-message>
        <logger message="Executing insert: #[payload]" level="INFO" doc:name="Logger"/>
        <successfactors:insert config-ref="Success_Factors__Configuration" type="Goal$1" doc:name="Insert a Goal$1"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
        <logger message="Insert result: #[payload]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="deleteFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/delete" doc:name="/delete"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-payload doc:sample="json_3.json"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
payload]]></dw:set-payload>
        </dw:transform-message>
        <logger message="Executing delete: #[payload]" level="INFO" doc:name="Logger"/>
        <successfactors:delete config-ref="Success_Factors__Configuration" type="Goal$1" doc:name="Delete a Goal$1"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>
        <logger message="Delete result: #[payload]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="queryNativeFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="queryNative" doc:name="/queryNative"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
inboundProperties."http.query.params".'query']]></dw:set-payload>
        </dw:transform-message>
        <successfactors:query config-ref="Success_Factors__Configuration" queryString="#[payload]" doc:name="Success Factors"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>

  </flow>
</mule>