Salesforce Connector

The Java-based Salesforce connector is built with the Identity Java Connector Integration Framework and uses the REST framework and its APIs.

Overview

The Salesforce connector implements the API methods "add(…)", "modify(…)", "delete(…)" and "search(…)". They represent the corresponding SPML requests"‘AddRequest", "ModifyRequest", "DeleteRequest" and "SearchRequest".

Currently it only supports Account, Contact, User, PermissionSet and Profile objects in Salesforce.

The Salesforce connector offers the following functionality:

Add an account, a contact or a user to Salesforce
Delete an account, a contact or a user from Salesforce
Modify an account, a contact or a user in Salesforce
Modify a permission set or a profile in Salesforce (attribute Description only)
Search accounts, contacts, users, permission sets and profiles in Salesforce

Prerequisites and Limitations

The Salesforce connector has the following limitations:

Users cannot be physically deleted in Salesforce. As a result, the Delete operation only sets the IsActive attribute to false and the customer-specific attribute StatusInfo__c to DELETED.
New profiles can’t be created or deleted using the REST APIs. Only a Modify operation is supported; for example, modifying the Description attribute of a profile.

Request and Response Handling

This section describes the supported attributes and requests for the Salesforce connector.

The following sections provide the supported attributes.

Supported Account Attributes

AccountNumber
AnnualRevenue
BillingCity
BillingCity
BillingCountry
BillingPostalCode
BillingState
BillingStreet
Description
Fax
Id - the identifier of the account; is returned as SPML identifier in the SPML ADD resonse; must be used as SPML identifier in an SPML MODIFY or DELETE request or in SPML SEARCH request if a single object is searched.
Industry
IsCustomerPortal - read only
IsDeleted - read only
IsPartner - read only
Name
OwnerId - reference to a Salesforce user that is defined if the account is used for defining a Customer Portal User.
Ownership
Phone
PhotoUrl
Rating
Site
ShippingCity
ShippingCountry
ShippingPostalCode
ShippingState
ShippingStreet
Type
Website

Supported Contact Attributes

AccountId - reference to a Salesforce account that is defined if the contact is used for defining a Customer Portal User.
AssistantName
Birthdate
Department
Description
Email
Fax
FirstName
Id - the identifier of the contact; is returned as SPML identifier in the SPML ADD resonse; must be used as SPML identifier in an SPML MODIFY or DELETE request or in SPML SEARCH request if a single object is searched
IsDeleted - read only
HomePhone
LastName
LeadSource
MailingCity
MailingCountry
MailingPostalCode
MailingState
MailingStreet
MobilePhone
Name
OtherCity
OtherCountry
OtherPhone
OtherPostalCode
OtherState
OtherStreet
OwnerId - reference to a Salesforce user that is defined if the contact is used for defining a Customer Portal User.
Phone
PhotoUrl
Salutation
Title

Supported Permission Set Attributes

Description
Id - the identifier of the permission set; is returned as SPML identifier in the SPML ADD resonse; must be used as SPML identifier in an SPML MODIFY or DELETE request or in SPML SEARCH request if a single object is searched.
LicenseId
Name
ProfileId

Supported Profile Attributes

Description
Id - the identifier of the profile; is returned as SPML identifier in the SPML ADD resonse; must be used as SPML identifier in an SPML MODIFY or DELETE request or in SPML SEARCH request if a single object is searched.
Name
UserLicenseId
UserType

Supported User Attributes

Alias - mandatory in ADD operations.
City
CommunityNickName - mandatory in ADD operations; must be unique.
CompanyName
Country
Department
Division
Email - mandatory.
EmailEncodingKey - mandatory in ADD operations.
EmployeeNumber
Extension
Fax
FirstName
Id - the identifier of the user; is returned as SPML identifier in the SPML ADD resonse; must be used as SPML identifier in an SPML MODIFY or DELETE request or in SPML SEARCH request if a single object is searched.
IsActive
LanguageLocaleKey - mandatory in ADD operations.
LastName
LocaleSidKey - mandatory.
MobilePhone
Password
Phone
ProfileId - mandatory.
PostalCode
State
StatusInfo__c - customer-specific attribute.
Street
TimeZoneSidKey - mandatory in ADD operations.
Title
Username - mandatory in ADD operations; must be, unique and in the form of an e-mail address (for example, john@acme.com).

Operational Attributes

All SPML requests contain a section for operational attributes. In this section, you specify the object type for your SPML request.

In the operational attribute objtype you can use the following values:

Account for Salesforce account objects
Contact for Salesforce contact objects
PermissionSet for Salesforce permission set objects
Profile for Salesforce profile objects
User for Salesforce user objects

Here is a sample operational attribute section for handling a Salesforce user:

<spml:operationalAttributes>
   <spml:attr name="objtype">
        <dsml:value type="string">User</dsml:value>
   </spml:attr>
</spml:operationalAttributes>

Note that for all requests, you must specify the OperationalAttributes section and define the kind of object.

In AddRequest, no Spml-Identifier is set. The Spml-Identifier of the new object that has been created in Salesforce and returned in the AddResponse.

All other requests use the Spml-Identifier in the request. For search operations, the Smpl-Identifier is optional. If you omit it, you should set the scope operational attribute to subtree to initiate a search with filter.

The following sections describe the operation details.

AddRequest

The following example request adds a user object:

<spml:addRequest  xmlns="urn:oasis:names:tc:SPML:1:0"
                             xmlns:spml="urn:oasis:names:tc:SPML:1:0"
                            xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
                             requestID="add_01">
<spml:operationalAttributes>
    <spml:attr name="objtype">
         <dsml:value type="string">user</dsml:value>
    </spml:attr>
</spml:operationalAttributes>
<spml:attributes>
    <dsml:attr name="Username">
         <dsml:value>Miller.Tom@My-Company.com</dsml:value>
    </dsml:attr>
    <dsml:attr name="LastName">
         <dsml:value>Miller</dsml:value>
    </dsml:attr>
    <dsml:attr name="FirstName">
         <dsml:value>Tom</ dsml:value>
    </dsml:attr>
    <dsml:attr name="CompanyName">
         < dsml:value>My-Company</dsml:value>
    </dsml:attr>
    <dsml:attr name="Department">
         <dsml:value>Sales</dsml:value>
    </dsml:attr>
    <dsml:attr name="City">
         <dsml:value>Munich</dsml:value>
    </dsml:attr>
    <dsml:attr name="Country">
         <dsml:value>US</dsml:value>
    </dsml:attr>
    <dsml:attr name="EmployeeNumber">
         <dsml:value>1234</dsml:value>
    </dsml:attr>
    <dsml:attr name="Alias">
         <dsml value>TMill</dsml value>
    </dsml:attr>
    <dsml:attr name="Password">
         <dsml value>dirxdirx1</dsml value>
    </dsml:attr>
    <dsml:attr name="IsActive">
         <dsml value>true</dsml value>
    </dsml:attr>
    <!-- Chatter Free User -->
    <dsml:attr name="ProfileId">
         <dsml:value>00ei0000001QzcCAAS</ dsml:value>
    </dsml:attr>
    <dsml:attr name="EmailEncodingKey">
         <dsml:value>ISO-8859-1</dsml:value>
    </dsml:attr>
    <dsml:attr name="TimeZoneSidKey">
         <dsml:value>America/Los_Angeles</dsml:value>
    </dsml:attr>
    <dsml:attr name="LocaleSidKey">
         <dsml:value>en_US</dsml:value>
    </dsml:attr>
    <dsml:attr name="LanguageLocaleKey">
         <dsml:value>en_US</dsml:value>
    </dsml:attr>
    <dsml:attr name="Email">
         <dsml:value>Miller.Tom@My-Company.com</dsml:value>
    </dsml:attr>
    <dsml:attr name="CommunityNickname">
         <dsml:value>Tom-Miller-1</dsml:value>
    </dsml:attr>
</spml:attributes>
</spml:addRequest>

ModifyRequest

The (user) modify request modifies a user in Salesforce. The same attributes as in AddRequest are supported.

The (profile) modify request modifies a profile in Salesforce. The only attribute that can be modified is Description.

The (permission set) modify request modifies a permission set in Salesforce. The only attribute that can be modified is Description.

The following example request modifies a user object:

<spml:modifyRequest  xmlns="urn:oasis:names:tc:SPML:1:0"
       xmlns:spml="urn:oasis:names:tc:SPML:1:0"
      xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
       requestID="mod_02"
       >
    <spml:identifier
        type="urn:oasis:names:tc:SPML:1:0#DN">
        <spml:id>005i0000003F84dAAC</spml:id>
    </spml:identifier>
   <spml:operationalAttributes>
       <spml:attr name="objtype">
           <dsml:value type="string">user</dsml:value>
       </spml:attr>
   </spml:operationalAttributes>
   <spml:modifications>
<spml:modification name="Title" operation="replace">
   <dsml:value>Dr.</dsml:value>
</spml:modification>
<spml:modification name="City" operation="replace">
   <dsml:value>Munich</dsml:value>
</spml:modification>
    </spml:modifications>
</spml:modifyRequest>

DeleteRequest

The delete request is used to delete an object from a Salesforce site.

Important: The identifier for each delete request must be set to the group name.

The delete request does not require additional attributes.

The following example request deletes a user object:

<spml:deleteRequest  xmlns="urn:oasis:names:tc:SPML:1:0"
                    xmlns:spml="urn:oasis:names:tc:SPML:1:0"
                    xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
                    requestID="delete_01">
      <spml:identifier type="urn:oasis:names:tc:SPML:1:0#DN">
             <spml:id>005i0000003FAX9AAO</spml:id>
      </spml:identifier>
      <spml:operationalAttributes>
             <spml:attr name="objtype">
                   <dsml:value type="string">user</dsml:value>
             </spml:attr>
      </spml:operationalAttributes>
</spml:deleteRequest>

SearchRequest

The search request is used to retrieve either an object by its name (defined in the “searchBase” XML component) or by a filter.

The following example requests search users. The first search request (search-01) searches the user object with the name; the second search request (search-02) searches the user objects with a filter:

<!-- search one user in SalesForce -->
<spml:searchRequest requestID="search-01"
                   xmlns="urn:oasis:names:tc:SPML:1:0"
                   xmlns:spml="urn:oasis:names:tc:SPML:1:0"
                   xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
     <spml:searchBase type="urn:oasis:names:tc:SPML:1:0#DN">
           <spml:id>005i0000003FAX9AAO</spml:id>
     </spml:searchBase>
     <spml:operationalAttributes>
           <spml:attr name="objtype">
                 <dsml:value type="string">user</dsml:value>
           </spml:attr>
           <spml:attr name="scope">
                 <dsml:value type="string">base</dsml:value>
           </spml:attr>
     </spml:operationalAttributes>
     <spml:attributes>
           <dsml:attribute name="Id"/>
           <dsml:attribute name="Username"/>
           <dsml:attribute name="LastName"/>
           <dsml:attribute name="FirstName"/>
           <dsml:attribute name="Name"/>
           <dsml:attribute name="CompanyName"/>
     </spml:attributes>
</spml:searchRequest>

<!—search several users in SalesForce with filter -->
<spml:searchRequest requestID="search-02"
                   xmlns="urn:oasis:names:tc:SPML:1:0"
                   xmlns:spml="urn:oasis:names:tc:SPML:1:0"
                   xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
     <spml:searchBase type="urn:oasis:names:tc:SPML:1:0#DN">
           <spml:id></spml:id>
     </spml:searchBase>
     <spml:operationalAttributes>
           <spml:attr name="objtype">
                 <dsml:value type="string">user</dsml:value>
           </spml:attr>
           <spml:attr name="scope">
                 <dsml:value type="string">subtree</dsml:value>
           </spml:attr>
     </spml:operationalAttributes>
     <spml:attributes>
           <dsml:attribute name="Id"/>
           <dsml:attribute name="Username"/>
           <dsml:attribute name="LastName"/>
           <dsml:attribute name="FirstName"/>
           <dsml:attribute name="Name"/>
           <dsml:attribute name="CompanyName"/>
     </spml:attributes>
     <spml:filter>
           <dsml:or>
                 <dsml:equalityMatch name="CompanyName">
                       <dsml:value>Atos</dsml:value>
                 </dsml:equalityMatch>
                 <dsml:equalityMatch name="Alias">
                       <dsml:value>mgoet</dsml:value>
                 </dsml:equalityMatch>
           </dsml:or>
     </spml:filter>
</spml:searchRequest>

Configuration

Here is a sample configuration snippet for the Salesforce connector:

<connector
    role="connector"
         className="net.atos.dirx.dxi.connector.salesforce.SalesForceConnector"
         name="ts"
         version="1.00">
    <connection
         type="SalesForce"
          user="<your user name>"
          password="<your password>"
          server="<your Salesforce installation, e.g.  login.salesforce.com>"
          port=""
          ssl="true"
    >
    <property name="debugfile" value="<your output file name>"/>
     <property name="clientId" value=”<your client id>"/>
     <property name="clientSecret" value=”<your client secret>"/>
     <property name="securityToken" value="<your security token>"/>
     <property name="loginPath" value="/services/oauth2/token" />
     <property name="path"  value="e.g. /services/data/v30.0" />
     <property name="proxyHost"  value="<IP address of your HTTP proxy>" />
     <property name="proxyPort"  value="<<port of your HTTP proxy>" />
     </connection>
</connector>

The Salesforce connector supports the following standard properties of the XML configuration file’s <connection> element:

server (mandatory) - the Salesforce login site, for example, login.salesforce.com.

port - not used.

user (mandatory) - the Salesforce user name of the Salesforce user that has administrative rights.

password (mandatory) - the password of the Salesforce user.

ssl (mandatory) - a flag that should normally be set to true because you access the Salesforce installation using HTTPS; for example, https:/login.salesforce.com.

Supported non-standard properties include:

clientId (mandatory) - the consumer key of your registered remote application. For details, see the section on the Salesforce workflow in the chapter "Using the Target System (Provisioning) Workflows" in the DirX Identity Application Development Guide.

clientSecret (mandatory) - the consumer secret of your registered remote application. For details, see the section on the Salesforce workflow in the chapter "Using the Target System (Provisioning) Workflows" in the DirX Identity Application Development Guide.

debugFile (optional) - the name of the file to which all SPML requests and responses are written.

loginPath (mandatory) - the HTTP path for performing OAuth authentication.

path (mandatory) - the HTTP path for performing the requests using the REST API; for example, ./services/data/v30.0. Note that the path contains the Salesforce REST API version; for example, 30.0.

proxyHost (optional) - the IP address of your HTTP proxy server.

proxyPort (mandatory) - the port of your securityToken.

securityToken (mandatory) - the security token that is assigned to your Salesforce user account when registering the user in Salesforce (the securityToken you will receive as e-mail from Salesforce).

Here are some hints for the handling of path and loginPath:

Using the following snippet:

server="login.salesforce.com"
loginPath="/services/oauth2/token"
path="/services/data/v30.0"

the Salesforce connector:

Connects to Salesforce using https:/login.salesforce.com/="/services/oauth2/token".
Receives an instance URL from Salesforce; for example, na15.salesforce.com.
Sends a search request to Salesforce using https:/na15.salesforce.com//services/data/v30.0/query.
Sends an update request to Salesforce using
https:/na15.salesforce.com//services/data/v30.0/sobjects/Account or
https:/na15.salesforce.com//services/data/v30.0/sobjects/Contact or
https:/na15.salesforce.com//services/data/v30.0/sobjects/PermissionSet or
https:/na15.salesforce.com//services/data/v30.0/sobjects/Profile or
https:/na15.salesforce.com//services/data/v30.0/sobjects/User