You probably have heard of our Salesforce Connector, which we implemented a few months ago. This connector enables you to display contents that are stored in the Nuxeo repository directly into Salesforce.
We now want to take it a step further: We want to be able to display a dropdown list within the Nuxeo Platform that will fetch content from Salesforce in real time. So, essentially this use case is the reverse of the earlier one. As an example, we chose to implement a list of Organizations stored in Salesforce (into the Account Object).
The result is transparent for the end user as all the configuration is done behind the scene, and there is no difference between displaying a list of values stored in the Nuxeo Platform and fetching in real time from Salesforce!
Behind the Scene
The plugin is based on a Nuxeo addon named nuxeo-directory-connector which creates everything needed to plug a web service to retrieve a list of values inside a Vocabulary (also known as a Directory).
So, in this blog I will focus mainly on the points steps to Salesforce. The Web Service I used is the one based on Force.com REST API.
The authentication to Salesforce’s API is handled via OAuth2. Everything needed to configure an OAuth2 provider is already there in the Nuxeo Platform.
This is done in the Admin > Cloud Services > Service Providers menu.
Here we define the information related to Salesforce OAuth2. To retrieve the client ID and client secret information you need to create a “Connected App” in the Nuxeo Platform. In order to do that you need to go to Salesforce > Setup > Build > Create > Apps and then create a new App under the Connected Apps tab.
Here is an example of a Connected App configuration. There are 2 important things to note:
- The callback URL: it should look similar to https://hostname:port/nuxeo/site/oauth2/Salesforce/callback
Please note that your Nuxeo Platform should be in https (unless you are testing on localhost).
- Selected OAuth Scopes:
- Access and manage your data (api)
- Provide access to your data via the Web (web)
- Perform requests on your behalf at any time (refresh_token, offline_access)
In our demo, we will use Full access (full) for the sake of simplicity but you can adjust depending on your use case.
Once you save your configuration, you will get your Consumer Key and your Consumer Secret, which you need to copy and paste in the Nuxeo Platform.
Once we define the OAuth2 provider we need to authenticate on Salesforce via the Nuxeo Platform.
In order to do that, you need to go to Home > Cloud Services and click on Connect to Salesforce. Once you are connected and granted an offline access you are all set!
Again, for the sake of simplicity we used the Administrator account in the Nuxeo Platform for this.
<extension target="org.nuxeo.directory.connector.ConnectorBasedDirectoryFactory" point="directories"> <directory name="Salesforce_Organization" class="org.nuxeo.directory.connector.json.salesforce.SalesforceInMemoryConnector"> <idField>Id</idField> <schema>vocabulary</schema> <parameters> <parameter name="url">/services/data/v20.0/query/?q=SELECT+Id,Name+from+Account</parameter> <parameter name="label">Name</parameter> <parameter name="id">Id</parameter> <parameter name="autoRefresh">true</parameter> </parameters> <mapping> <map field="label">Name</map> <map field="id">Id</map> </mapping> </directory> </extension>
Here is the extension point where the configuration is done.
Salesforce_Organization, for instance, is the name of the Directory (aka Vocabulary) that you will use when you want to use it on a given suggestion widget. (I will explain this in detail in the next paragraph).
There are a certain number of parameters that are used to fetch content from Salesforce and to do the mapping against a Nuxeo Vocabulary.
The Salesforce query you put into the url (SELECT+Id,Name+from+Account) is completely configurable. For instance, you can get a list of Contacts, or even information from a custom object.
The important part to notice here is that in a Nuxeo vocabulary we have an id and a label. You must do the mapping with the result of your query to declare which Salesforce Object field is going to be used as the Id and which one as a label.
There is also an option to fetch the result in real time all the time (autoRefresh). If autoRefresh is set to false the request to Salesforce will be run once and the result is kept in the memory on the Nuxeo Platform’s side. So if you have some data that won’t change frequently it could be interesting to choose that option.
In order to use the Salesforce_Organization directory defined previously you just have to add a suggestion widget in your creation, read and edit layout, link it to a text field metadata and set the directoryName property under the Custom Properties Configuration.
You can find the plugin here. Try it out and let us know what you think!