Salesforce Source

The Salesforce Organizational Identity Source Plugin is designed to integrate with Salesforce via the Force.com REST API. The Salesforce OIS Plugin is available in Registry v3.1.0 and later.

Modes

This is a non-core plugin, see Installing and Enabling Registry Plugins for more information.

Configuration (Registry v3.2.0 or later)

1.  If you already have a Salesforce Server defined with the appropriate configuration (perhaps for use with the Salesforce Provisioning Plugin) you can reuse it instead of defining a new one. Skip to step 6.
2. Add a new Server, via Servers > Add a New Server
   1. Set the server type to OAuth2.
   2. After the configuration has been saved, a Redirect URI will be available via the server configuration page. Keep this handy for the next step.
3. In another browser tab or window, login to Salesforce. Add a new Connected App via Setup > Quick Links > Manage Apps. Click the New button in the Connected Apps section.
   1. Set the Connected App Name and Contact Email.
   2. Under API, tick Enable OAuth Settings.
   3. Set the Callback URL to the URI provided in step 1, above.
   4. Added at least these two OAuth Scopes:
      1. Access and manage your data (api)
      2. Perform requests on your behalf at anytime (refresh_token, offline_access)
   5. Click Save. (You may need to scroll up to see the confirmation message.)
   6. On the next page, a Consumer Key and Consumer Secret will be made available. Keep these handy for the next step.
4. Return to the OAuth2 Server configuration and complete the configuration.
   1. Server URL: The base URL of your Salesforce instance with /services/oauth2 appended, eg https://test.salesforce.com/services/oauth2
      1.  The plugin will work with either the generic service name (test.salesforce.com) or a specific instance (cs123.salesforce.com), but note that Salesforce periodically migrates customers to new instances (in Salesforce terms, an instance refresh). In such an event, when configured with the generic service name the plugin should detect the new instance automatically, though it may be necessary to obtain a new token (described below).
   2. Client ID: The Consumer Key obtained in step 2.
   3. Client Secret: The Consumer Secret obtained in step 2.
   4. Access Token Grant Type: Authorization Code
   5. Scope: (Leave blank)
   6. Click Save.
5. Return to the Salesforce Connected App configuration page, click the Manage button at the top, then click the Edit Policies button. Update the policies as follows:
   1. Permitted Users: All users may self-authorize
   2. IP Relaxation: Relax IP restrictions
      1.  You may instead be able to set Trusted IP Range for OAuth Web server flow from the Connected App's main configuration page.
   3. Refresh Token Policy: Refresh token is valid until revoked
   4. Click Save.

6. Add a new Organizational Identity Source, via Configuration > Organizational Identity Sources > Add Organizational Identity Source.

   1. Set the Plugin type to SalesforceSource.

   2.  Because searching by email (eg: if configured as an Enrollment Source) uses the general search interface (meaning other fields can match, not just email address), Email Mismatch Mode should probably be set to Ignore.

   3. For information about other configuration options, see Organizational Identity Sources.

   4. Click Add.

7. From the Salesforce Source configuration page, complete the configuration.
   1. Server: Select the OAuth2 server created in step 1
   2. Instance URL: This can be left blank, as it will be automatically determined
   3. Select which objects you would like to be searched.
   1. 1.  If you do not select either Search Contacts or Search Users, then all objects will be searched. Such a configuration is not recommended.
      2.  Changes made to custom object records in Salesforce will not be automatically detected by Registry OIS sync processes. If changes are made to these records without changes to the corresponding Contact or User records, a manual sync will be required to update the record in Registry.
   2. Click Save.
8. Finally, return to the OAuth2 Server configuration to obtain an OAuth token.
   1. The configuration should indicate that the Access Token is "Not Set", and there should now be a button "Obtain New Token".
   2. Upon clicking that button, you will be taken to the Salesforce login page. Log in as a sufficiently authorized user.
   3. After successful login, you should be returned to the OAuth2 Server configuration page, and the Access Token should now be "Set".
   4.  Should it ever be necessary to obtain a new token (eg: if the administrator who performed the initial setup no longer has a valid Salesforce account), simply return to the configuration page and click the "Obtain New Token" button again.

Configuration (Registry v3.1.0)

1. Add a new Organizational Identity Source, via Configuration > Organizational Identity Sources > Add Organizational Identity Source.

   1. Set the Plugin type to SalesforceSource.

   2. For information about other configuration options, see Organizational Identity Sources.

   3. Click Add.

   4. After the configuration has been saved, a Salesforce Redirect URI will be available. Keep this handy for the next step.

      1.  Salesforce requires the use of HTTPS for the callback. Your Registry installation must be running under HTTPS.

2. In another browser tab or window, login to Salesforce. Add a new Connected App via Setup > Quick Links > Manage Apps. Click the New button in the Connected Apps section.
   1. Set the Connected App Name and Contact Email.
   2. Under API, tick Enable OAuth Settings.
   3. Set the Callback URL to the URI provided in step 1, above.
   4. Added at least these two OAuth Scopes:
      1. Access and manage your data (api)
      2. Perform requests on your behalf at anytime (refresh_token, offline_access)
   5. Click Save. (You may need to scroll up to see the confirmation message.)
   6. On the next page, a Consumer Key and Consumer Secret will be made available. Keep these handy for the next step.
3. Return to the Organizational Identity Source configuration and complete the configuration.
   1. Salesforce Base URL: The base URL of your Salesforce instance, eg https://test.salesforce.com
      1.  The plugin will work with either the generic service name (test.salesforce.com) or a specific instance (cs123.salesforce.com), but note that Salesforce periodically migrates customers to new instances (in Salesforce terms, an instance refresh). In such an event, when configured with the generic service name the plugin should detect the new instance automatically, though it may be necessary to obtain a new token (described below).
   2. Client ID: The Consumer Key obtained in step 2.
   3. Client Secret: The Consumer Secret obtained in step 2.
   4. Select which objects you would like to be searched.
      1.  If you do not select either Search Contacts or Search Users, then all objects will be searched. Such a configuration is not recommended.
      2.  Changes made to custom object records in Salesforce will not be automatically detected by Registry OIS sync processes. If changes are made to these records without changes to the corresponding Contact or User records, a manual sync will be required to update the record in Registry.
   5. Click Save.
4. Return to the Salesforce Connected App configuration page, click the Manage button at the top, then click the Edit Policies button. Update the policies as follows:
   1. Permitted Users: All users may self-authorize
   2. IP Relaxation: Relax IP restrictions
      1.  You may instead be able to set Trusted IP Range for OAuth Web server flow from the Connected App's main configuration page.
   3. Refresh Token Policy: Refresh token is valid until revoked
   4. Click Save.
5. Finally, return to the Organizational Identity Source configuration to obtain an OAuth token.
   1. The configuration should indicate that the Auth Token is "Not Set", and there should now be a button "Obtain New Token".
   2. Upon clicking that button, you will be taken to the Salesforce login page. Log in as a sufficiently authorized user.
   3. After successful login, you should be returned to the OIS configuration page, and the Auth Token should now be "Set".
   4.  Should it ever be necessary to obtain a new token (eg: if the administrator who performed the initial setup no longer has a valid Salesforce account), simply return to the configuration page and click the "Obtain New Token" button again.

Understanding API Usage

This documentation is intended to be a guide to understanding the approximate number of API calls that this plugin may make under various circumstances. It is not an exact formula, as there are various circumstances where additional calls must be made.

• A search operation, such as that performed via the web interface, consumes one API call plus one API call per search result (r) (= 1 + r).
• A retrieve operation, such as that performed to view an individual record from Salesforce, or a manual OIS sync, consumes one API call plus one API call per custom object (c) defined (= 1 + c).
  • As of Registry v3.2.0, if an Account ID is linked to the record, an additional API call is consumed to obtain the Account object (= 2 + c).
• An OIS sync in update mode consumes one API call plus, for each changed record (d), one API call plus one API call per custom object defined (u = 1 + (d * (1 + c)))
• An OIS sync in query mode consumes the calls required for update mode (u) plus, for each verified Email Address (e) attached to an Organizational Identity (less those already known if Do Not Query for Known Email Addresses is enabled), one API call plus, for each search result, one API call plus one API call per custom object defined (= u + e + (r * (1 + c))).
  
  

See Also

• cm_salesforce_sources