Introduction

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

Prerequisites

This document assumes that you are familiar with SuccessFactors and have an account.
To use this connector, you will need a working installation of Anypoint Studio with the SuccessFactors connector installed.

Compatibility

SuccessFactors Connector is compatible with:

Application/Service Version

Mule Runtime

3.7 or higher

Java

7

Installing and Configuring

The following sections describe how to install and configure the SuccessFactors Connector.

Installing

You can install a connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

Creating a New Project

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

  1. In Anypoint Studio, click File > New > Mule Project.

    PS_0001B_installing_new

  2. Enter a name for your new project and leave the remaining options with their default values.

    successfactors_new_project

  3. 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.

  4. Click Next to verify that Java 1.7 is set as your default JRE.

  5. Click Finish to create the project.

Configuring a SuccessFactors Global Element

To use the SuccessFactors Connector in your Mule application, you must configure a global configuration element that can be used by all SuccessFactors Connectors in the application (read more about global elements).

[tab,title="Studio Visual Editor"]
....
Follow these steps to create a SuccessFactors global element:

. 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 then select *Success Factors: Configuration*.
+
image:success-factors-choose-global-type.png[success-factors-choose-global-type]
+
. Click *OK*.
. Configure the parameters according to the instructions below.
+
image:success_factors_global_element.png[success_factors_global_element]
+
[width="100%",cols="50a,50a",options="header",]

|===
|*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.
|*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.
|*Proxy Host* |The hostname of the HTTP proxy to use. Optional.
|*Proxy Port* |The port number of the HTTP proxy. Default value is 3128.
|*Proxy Username* |The username for the HTTP proxy. Optional.
|*Proxy Password* |The password for the HTTP proxy. Optional.
|===
+
. Click *Test Connection* and confirm receipt of the _Connection Successful_ message.
If an HTTP Proxy was set, you may see the following dialog in Studio:
+
image:success_factors_global_element_proxy_dialog.png[success_factors_global_element_proxy_dialog]
+
Enter the credentials for the proxy. This is needed for the *Test Connection* functionality to work. The Mule application itself will still use the credentials set in the Global Configuration window.
+
. Click *OK* to save the global connector configurations.
+
....
[tab,title="XML Editor"]
....
Ensure the SuccessFactors namespaces are included in your configuration file.

[source, xml, linenums]
----
<?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>
----

Follow these steps to configure a SuccessFactors Connector in your application:

. Create a global SuccessFactors configuration outside and above your flows using the following global configuration code.
+
[source, xml, linenums]
----
<successfactors:config name="Success_Factors__Configuration" username="${username}" password="${password}" companyId="${companyId}" wsdlLocation="${wsdlLocation}" doc:name="Success Factors: Configuration" fetchAllEntities="false" proxyHost="${httpProxyHost}" proxyPassword="${httpProxyPassword}" proxyPort="${httpProxyPort}" proxyUsername="${httpProxyUsername}">
        <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>
----
+
[width="100%",cols="50a,50a",options="header",]

|===
|*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.
|*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.
|*Proxy Host* |The hostname of the HTTP proxy to use. Optional.
|*Proxy Port* |The port number of the HTTP proxy. Default value is 3128.
|*Proxy Username* |The username for the HTTP proxy. Optional.
|*Proxy Password* |The password for the HTTP proxy. Optional.
|===

....

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

This flow retrieves the list of entities in your organization.

list_flow

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

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.

describe_flow

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_flow_connector_config

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.

describe_flow_dataweave_config

The code to add in the Transform Message, which is the same depicted in the above image, is here for your reference:

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

To test this, run the flow in Mule Studio 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.

query_flow

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_flow_query_builder

You can leave the page size at the default value.

query_flow_connector_config

To test this flow, run the flow in Mule Studio and open a browser window. Visit http://localhost:8081/query. You will 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.

upsert_flow

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 will be taken from the payload returned by DataWeave.

upsert_flow_connector_config

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:

dataweave_payload

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 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.

update_flow

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:

dataweave_payload

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.

insert_flow

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.

insert flow connector config

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:

dataweave_payload

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 Goal$1 section to see the result of the insert operation in the browser.

Delete Use Case

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

delete_flow

The SuccessFactors endpoint needs to be configured with the Delete operation. Select the type of the entity you wish to delete, 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.

delete_flow_connector_config

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:

dataweave_payload

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$1 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:transformer>
    <scripting:transformer name="AddIdToEntity" doc:name="Groovy">
        <scripting:script engine="Groovy" file="src/main/resources/AddIdToEntity.groovy"/>
    </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>

See Also