Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

SuccessFactors Connector

Introduction

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.

MuleSoft maintains this connector under the Select support policy.

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

Anypoint Studio

5.3.1 or higher

Java

7

To Install this Connector

  1. In Anypoint Studio, click the Exchange icon in the Studio taskbar.

  2. Click Login in Anypoint Exchange.

  3. Search for the connector and click Install.

  4. Follow the prompts to install the connector.

When Studio has an update, a message displays in the lower right corner, which you can click to install the update.

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.

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

  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 Finish to create the project.

Namespace and Schema Location

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

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 application 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. See example application below for placement details.

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

Follow these steps to create a SuccessFactors global element:

  1. Click the Global Elements tab at the base of the canvas.

  2. On the Global Mule Configuration Elements screen, click Create.

  3. In the Choose Global Type wizard, expand Connector Configuration, and then select Success Factors: Configuration.

    success-factors-choose-global-type

  4. Click OK.

  5. Configure the parameters according to the instructions below.

    success_factors_global_element

    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.

  6. Click Test Connection and confirm receipt of the Connection Successful message.

  7. Click OK to save the global connector configurations.

Ensure the SuccessFactors namespaces are included in your configuration file.


    
            
         
1
2
3
4
5
6
7
8
9
&lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;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"&gt;
&lt;/mule&gt;

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

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

    
           
                   
                
    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    &lt;successfactors:config name="Success_Factors__Configuration" username="${username}" password="${password}" companyId="${companyId}" wsdlLocation="${wsdlLocation}" doc:name="Success Factors: Configuration" fetchAllEntities="false"&gt;
            &lt;successfactors:entity-list&gt;
                &lt;successfactors:entity-list&gt;Goal$1&lt;/successfactors:entity-list&gt;
                &lt;successfactors:entity-list&gt;picklistlabel&lt;/successfactors:entity-list&gt;
                &lt;successfactors:entity-list&gt;picklistoption&lt;/successfactors:entity-list&gt;
                &lt;successfactors:entity-list&gt;TrendData_sysOverallCompetency&lt;/successfactors:entity-list&gt;
                &lt;successfactors:entity-list&gt;user&lt;/successfactors:entity-list&gt;
            &lt;/successfactors:entity-list&gt;
        &lt;/successfactors:config&gt;

    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.

Using the Connector

For details on operations see the SuccessFactors connector technical reference by clicking on an "APIdoc" for your connector version.

Using the Connector in a Mavenized Mule App

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


          
       
1
2
3
4
5
<dependency>
  <groupId></groupId>
  <artifactId></artifactId>
  <version></version>
</dependency>

Inside the <version> tags, put the desired version number, the word RELEASE for the latest release, or SNAPSHOT for the latest available version. The available versions to date are:

  • *x.y.z

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:

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

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.

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


          
       
1
2
3
4
%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.

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.

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.

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.

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.

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.


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<?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>