Synchronizing users

Whenever a new user is created or an existing user is updated in Salesforce.com, the user's data can be synchronized in Sterling™ Field Sales.

Prerequisites to automating the synchronization of user data

Before you can automate the synchronization of user data from Salesforce.com to Sterling Field Sales, you must have completed the following:

  • Created a user with a login ID and password of "SFDCIntegrationUser". This is normally achieved by loading the factory setup (reference implementation) for Salesforce.com integration, which will create both the "SFDCIntegrationUser" user and the "SFDCIntegrationUserGroup" user group to which it belongs. For security reasons, the "SFDCIntegrationUserGroup" user group should have access to only the "login" API and the SFS_EnqueueSFDCUserSyncRequest_1_0 service; access to the SFS_EnqueueSFDCUserSyncRequest_1_0 service is automatically granted as part of factory setup, but access to the "login" API must be manually granted. Also, the user must manually be assigned a password policy that will prevent the password from expiring.
  • Added the URL of the IBM® server (that is, the URL used to invoke the Web service) to the remote site settings of the Salesforce.com account, as follows:
    1. Navigate to the Setup screen of Salesforce.com. In the left panel, select Administration Setup -> Security Controls -> Remote Site Settings.
    2. The All Remote Sites screen displays a list of remote sites that your organization trusts. Click the New Remote Site button to add the URL of the IBM server in the remote site list of Salesforce.com.
  • Ensured that the Salesforce.com user specified in the yfs.ycd.sfdc.<EnterpriseCode>.userid property has Read/Write access on all Salesforce.com Sales users.
  • To build Web services, you need Apache ANT 1.8 or higher on your system, and the system environment variable <ANT_HOME> must point to it. In addition if you are using an external ANT, you must set USE_EXTERNAL_ANT=true in sandbox.cfg.
  • You need to place the following web service properties in the sandbox.cfg:
    • WEBSERVICES_BUILDS=SIXBeanXapiJaxWS
    • JAXB_LOCAL_SCOPING=true
    • JAXB_ALWAYS_ANNOTATE_CLASSNAMES=true

Overview of user synchronization

Whenever a new user is created or an existing user is updated in Salesforce.com, the user's data can be synchronized in Sterling Field Sales. To enable the transmission of user data from Salesforce.com to Sterling Field Sales, IBM has implemented the following:

  • A Salesforce.com trigger, SynchronizeCPQUsers trigger
  • Two Sterling Field Sales services:
    • SFS_EnqueueSFDCUserSyncRequest_1_0 (referred to as enqueueSFDCUserSync Web service)
    • Copy {Runtime}/reference/SFS_EnqueueSFDCUserSyncRequest_1_0_enqueueSFDCUserSyncRequest_input.xsd into {Runtime}/extensions/webservices
    • The SFS_EnqueueSFDCUserSyncRequest_1_0 service must be exposed as a JAX-WS Web service with an ExposedName of enqueueSFDCUserSync in the webservicebeans.xml file. To expose the service as enqueueSFDCUserSync, you can either create your own webservicebeans.xml file or edit the sample webservicebeans.xml.example file located in {Runtime}/reference. After you create your own xml file or edit the sample xml file , copy the webservicebeans.xml.example from {Runtime}/reference to {Runtime}/repository/eardata/platform/webservices/ and rename it as webservicebeans.xml.
    • SFS_ProcessSFDCUserSyncRequest_1.0
Note: If you are currently using the YCD_Send_Generated_Password_8.5 service, you must replace this existing service with the YCD_Send_Generated_Password_9.2 service. The YCD_Send_Generated_Password_9.2 service prevents generated passwords from being mailed to users who are Salesforce.com users.

The SynchronizeCPQUsers trigger is invoked whenever a new user is created or an existing user is updated in Salesforce.com. When invoked, this trigger takes into account the configurations of the following CPQ parameters, and subsequently determines whether a user synchronization request needs to be enqueued in Sterling Field Sales:

  • UserSyncEnabled
  • UserSyncEndpoint
  • UserSyncQuery
  • UserSyncPrevalidateQuery
  • UserSyncAllUpdates

If a user synchronization request is required, the SynchronizeCPQUsers trigger makes Web service callouts to log in to the IBM system and to the enqueueSFDCUserSync Web service. The enqueueSFDCUserSync Web service then posts the incoming request message, which has a format of <SFDCUserSyncRequest EnterpriseCode=”" QueryWhereClause=""/>, to a JMS queue for asynchronous processing.

Notes:
  • You can configure the UserSyncTimeout CPQ parameter to specify the timeout value for the IBM user synchronization Web service call. If a value is not specified, the Salesforce.com default timeout value will be used.
  • The login ID and password of a pseudo-guest user, SFDCIntegrationUser, are used to log in to Sterling Field Sales. These credentials are hard-coded in the Salesforce.com Web service callout code, and are shared by all organizations in Sterling Field Sales.

The SFS_ProcessSFDCUserSyncRequest_1.0 service processes the requests from the JMS queue using the com.sterlingcommerce.integration.sfdc.customapi.SFDCUserSync.processUserSyncRequest API. The input for this API matches the input of the enqueueSFDCUserSync Web service; that is, <SFDCUserSyncRequest EnterpriseCode=”" QueryWhereClause=""/>.

The out-of-the-box integration server name for this service is SFDCUserSyncServer.
  • To start the integration server, run the following command from the <INSTALL_DIR>/bin directory:

    For Windows:

    
startIntegrationServer.cmd SFDCUserSyncServer

    For Linux/UNIX:

    
./startIntegrationServer.sh SFDCUserSyncServer

The SFS_ProcessSFDCUserSyncRequest_1.0 service queries Salesforce.com for users to synchronize, and subsequently makes the necessary XAPI calls to create or update the users in Sterling Field Sales. It issues a full query each time it processes a message, enabling the following types of synchronizations:

  • First-time bulk synchronization of all pre-existing Salesforce.com users that match the synchronization criteria in Sterling Field Sales (initiated by the first create or update on any user that matches the synchronization criteria).
  • Synchronization of subsequent users that are created or updated to match the synchronization criteria.
  • "Catch-up" of previous synchronization requests that may have been lost (for example, if the Sterling Field Sales system was down for maintenance at the time of the prior Salesforce.com user create/update activity) on the next create/update of any user that matches the synchronization criteria.

SFS_processSFDCUserSyncRequest_1.0 service

The SFS_ProcessSFDCUserSyncRequest_1.0 service processes user synchronization requests from the JMS queue using the com.sterlingcommerce.integration.sfdc.customapi.SFDCUserSync.processUserSyncRequest API. This API:

  1. Performs a Partner WSDL Web service login using the yfs.ycd.sfdc.<EnterpriseCode>.userid and yfs.ycd.sfdc.<EnterpriseCode>.password properties.
  2. If the yfs.ycd.sfdc.<EnterpriseCode>.validateUserCreateRequests property is defined and set to true, it makes a Partner WSDL Web service call to read the input EnterpriseCode enterprise's "Active" CPQParameter record, and verifies that the UserSyncEnabled field is set to true and the UserSyncQuery value matches the input QueryWhereClause value; if either match fails, an error will be logged and no further processing is done by the API.
  3. Performs the following query using the Partner WSDL Web service "query" method:
    Select Id, Username, Email, Name, ProfileId, LocaleSidKey, TimeZoneSidKey, 
scpq_CPQUserKey_c from User where <QueryWhereClause> and 
CurrentInCPQSystem != true
    Notes:
    • The batch size is set to the Salesforce.com recommended maximum value of 2000.
    • A portion of the "where" clause is customer-specific because it may contain specifications of the particular Profiles and/or Roles the customer has assigned to the target users, the Ids (ProfileId, UserRoleId) of which will vary from enterprise to enterprise.
  4. For each returned user, the CPQUserKey field will be evaluated for the initial determination of whether a create (CPQUserKey is null) or update (CPQUserKey is non-null) operation needs to be performed.
    • For a create operation, the createUserHierarchy API will be called with the field mappings shown in the following table. Failures with a YFS83_0009 (“User already exists”) error code will be treated differently, because they are most likely the result of Salesforce.com users having previously been manually created in Sterling Field Sales; in this case, the getUserHierarchy API will be called to obtain the UserKey of the user, and the operation will be treated as an update operation.
    • For an update operation, the modifyUserHierarchy API will be called with the field mappings shown in the following table.

    The following table maps the user fields in Sterling Field Sales to the user fields in Salesforce.com for the createUserHierarchy and modifyUserHierarchy API calls:

    Sterling Field Sales Field Salesforce.com Field
    /User/@Loginid and /User/@DisplayUserID Username
    /User/@Username Name
    /User/@OrganizationKey (The <EnterpriseCode> from the input XML)
    /User/@GeneratePassword (for create operations only) “true”
    /User/@UserKey (for update operations only) CPQUserKey
    /User/@Localecode If there exists an IBM locale such that (SFDC) LocaleSidKey == (IBM) Locale/@Language + "_" + Locale/@Country, and (SFDC) TimeZoneSidKey == (IBM) Locale/@Timezone: that locale's Locale/@Localecode will be used. Otherwise, the system default localecode, which is obtained by YFSSystem.getProperty("yfs.install.localecode"), will be used.
    /User/UserGroupLists/@Reset (for update operations only) “false”
    /User/UserGroupLists/UserGroupList/@UsergroupId If the yfs.ycd.sfdc.<EnterpriseCode>.userGroupsListForUserSync property is defined, it will be treated as a comma-separated list, and a UserGroupList element will be created for each with the @UsergroupId set accordingly.

    Otherwise, two UserGroupList elements will be used with an @UsergroupId of “FieldSalesRepGroup” and “SFDCSalesUserGroup”.
    /User/ContactPersonInfo/@EmailID Email

    The success or failure result of each operation will be compiled in a list.

  5. When all batch results have been processed, the result list will be used to make as many calls as required to the Partner WSDL Web service “update” method (processing in batches of up to 200, which is the maximum allowed) to record the results in the following fields of the Salesforce.com User object:
    • LastCPQSyncDate - Stores a timestamp (date and time) when the user was last synchronized to the IBM system.
    • CurrentInCPQSystem - Indicates whether user data is up-to-date in the IBM system. true indicates that the previous change has been recorded in the IBM system; false or null indicates that synchronization is required for that user.
    • LastCPQSyncSuccessful - Indicates whether the last user synchronization to the IBM system was successful. Note that when an error occurs that causes LastCPQSyncSuccessful to be set to false, CurrentInCPQSystem will be set to true to prevent the systems from endlessly retrying a synchronization that is going to fail. When the condition causing the error is resolved, the failed Users will need to have their CurrentInCPQSystem flags reset in Salesforce.com (either manually or programmatically) to cause a new synchronization attempt.
    • CPQUserKey - The IBM system's UserKey, which is populated as a result of the first synchronization, except when a create operation fails.
    Note: You should set the Field Accessibility permissions for these fields to "Hidden" for all profiles except the integration user's profile. Also, when debugging synchronization issues, it may be helpful to set the permission to "Read-only" for certain administrator profiles.