| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| // |
| === Salesforce Connector |
| |
| This connectors makes it possible to push and pull data to/from the Salesforce CRM. It can copy information between |
| Apache Unomi profiles and Salesforce Leads. |
| |
| ==== Getting started |
| |
| ===== Salesforce account setup |
| |
| . Create a new developer account here: |
| + |
| [source] |
| ---- |
| https://developer.salesforce.com/signup |
| ---- |
| + |
| . Create a new Connected App, by going into Setup -> App Manager and click "Create Connected App" |
| |
| . In the settings, make sure you do the following: |
| + |
| [source] |
| ---- |
| Enable OAuth settings -> Activated |
| Enable for device flow -> Activated (no need for a callback URL) |
| Add all the selected OAuth scopes you want (or put all of them) |
| Make sure Require Secret for Web Server flow is activated |
| ---- |
| + |
| . Make sure you retrieve the following information once you have created the app in the API (Enable OAuth Settings): |
| + |
| [source] |
| ---- |
| Consumer key |
| Consumer secret (click to see it) |
| ---- |
| + |
| . You must also retrieve your user's security token, or create it if you don't have one already. To do this simply |
| click on your user at the top right, select "Settings", the click on "Reset my security token". You will receive an email |
| with the security token. |
| |
| ===== Apache Unomi setup |
| |
| . You are now ready to configure the Apache Unomi Salesforce Connector. In the etc/unomi.custom.system.properties file |
| add/change the following settings: |
| + |
| [source] |
| ---- |
| org.apache.unomi.sfdc.user.username=${env:UNOMI_SFDC_USER_USERNAME:-} |
| org.apache.unomi.sfdc.user.password=${env:UNOMI_SFDC_USER_PASSWORD:-} |
| org.apache.unomi.sfdc.user.securityToken=${env:UNOMI_SFDC_USER_SECURITYTOKEN:-} |
| org.apache.unomi.sfdc.consumer.key=${env:UNOMI_SFDC_CONSUMER_KEY:-} |
| org.apache.unomi.sfdc.consumer.secret=${env:UNOMI_SFDC_CONSUMER_SECRET:-} |
| ---- |
| |
| ===== Deployment from Maven repository |
| |
| In this procedure we assume you have access to a Maven repository that contains a compiled version of the Salesforce connector. |
| If this is not the case or you prefer to deploy using a KAR bundle, see the KAR deployment instructions instead. |
| |
| . Connect to the Apache Unomi Karaf Shell using : |
| + |
| [source] |
| ---- |
| ssh -p 8102 karaf@localhost (default password is karaf) |
| ---- |
| + |
| . Deploy into Apache Unomi using the following commands from the Apache Karaf shell: |
| + |
| [source] |
| ---- |
| feature:repo-add mvn:org.apache.unomi/unomi-salesforce-connector-karaf-kar/${project.version}/xml/features |
| feature:install unomi-salesforce-connector-karaf-kar |
| ---- |
| |
| ===== Deployment using KAR bundle |
| |
| If you have a KAR bundle (for example after building from source in the `extensions/salesforce-connector/karaf-kar/target` directory), |
| you can follow these steps to install : |
| |
| . Ensure that Apache Karaf and Apache Unomi are started |
| . Execute the following command in karaf: `feature:install unomi-salesforce-connector-karaf-kar` |
| . The installation is done ! |
| |
| ===== Testing the connector |
| |
| . You can then test the connection to Salesforce by accessing the following URLs: |
| + |
| [source] |
| ---- |
| https://localhost:9443/cxs/sfdc/version |
| https://localhost:9443/cxs/sfdc/limits |
| ---- |
| + |
| The first URL will give you information about the version of the connectors, so this makes it easy to check that the |
| plugin is properly deployed, started and the correct version. The second URL will actually make a request to the |
| Salesforce REST API to retrieve the limits of the Salesforce API. |
| + |
| Both URLs are password protected by the Apache Unomi (Karaf) password. You can find this user and password information |
| in the etc/users.properties file. |
| |
| You can now use the connectors's defined actions in rules to push or pull data to/from the Salesforce CRM. You can |
| find more information about rules in the <<_concepts,Concepts>> and the <<_getting_started_with_unomi,Getting Started>> pages. |
| |
| ==== Properties |
| |
| To define how Salesforce attributes will be mapped to Unomi profile properties, edit the following entry using the pattern below : |
| |
| [source] |
| ---- |
| org.apache.unomi.sfdc.fields.mappings=${env:UNOMI_SFDC_FIELDS_MAPPINGS:-email<=>Email,firstName<=>FirstName,lastName<=>LastName,company<=>Company,phoneNumber<=>Phone,jobTitle<=>Title,city<=>City,zipCode<=>PostalCode,address<=>Street,sfdcStatus<=>Status,sfdcRating<=>Rating} |
| ---- |
| |
| Please note that Salesforce needs the company and the last name to be set, otherwise the lead won't be created. |
| An identifier needs to be set as well. The identifier will be used to map the Unomi profile to the Salesforce lead. By |
| default, the email is set as the identifier, meaning that if a lead in Salesforce and a profile in Unomi have the same |
| email, they'll be considered as the same person. |
| |
| [source] |
| ---- |
| org.apache.unomi.sfdc.fields.mappings.identifier=${env:UNOMI_SFDC_FIELDS_MAPPINGS_IDENTIFIER:-email<=>Email} |
| ---- |
| |
| ==== Hot-deploying updates to the Salesforce connector (for developers) |
| |
| If you followed all the steps in the Getting Started section, you can upgrade the Salesforce connectors by using the following steps: |
| |
| . Compile the connectors using: |
| + |
| [source] |
| ---- |
| cd extensions/salesforce-connector |
| mvn clean install |
| ---- |
| + |
| . Login to the Unomi Karaf Shell using: |
| + |
| [source] |
| ---- |
| ssh -p 8102 karaf@localhost (password by default is karaf) |
| ---- |
| + |
| . Execute the following commands in the Karaf shell |
| + |
| [source] |
| ---- |
| feature:repo-refresh |
| feature:uninstall unomi-salesforce-connector-karaf-feature |
| feature:install unomi-salesforce-connector-karaf-feature |
| ---- |
| + |
| . You can then check that the new version is properly deployed by accessing the following URL and checking the build date: |
| + |
| [source] |
| ---- |
| https://localhost:9443/cxs/sfdc/version |
| ---- |
| + |
| (if asked for a password it's the same karaf/karaf default) |
| |
| ==== Using the Salesforce Workbench for testing REST API |
| |
| The Salesforce Workbench contains a REST API Explorer that is very useful to test requests. You may find it here : |
| |
| [source] |
| ---- |
| https://workbench.developerforce.com/restExplorer.php |
| ---- |
| |
| ==== Setting up Streaming Push queries |
| |
| Using the Salesforce Workbench, you can setting streaming push queries (Queries->Streaming push topics) such as the |
| following example: |
| |
| [source] |
| ---- |
| Name: LeadUpdates |
| Query : SELECT Id,FirstName,LastName,Email,Company FROM Lead |
| ---- |
| |
| ==== Executing the unit tests |
| |
| Before running the tests, make sure you have completed all the steps above, including the streaming push queries setup. |
| |
| By default the unit tests will not run as they need proper Salesforce credentials to run. To set this up create a |
| properties file like the following one: |
| |
| test.properties |
| |
| [source] |
| ---- |
| # |
| # Licensed to the Apache Software Foundation (ASF) under one or more |
| # contributor license agreements. See the NOTICE file distributed with |
| # this work for additional information regarding copyright ownership. |
| # The ASF licenses this file to You under the Apache License, Version 2.0 |
| # (the "License"); you may not use this file except in compliance with |
| # the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| # |
| sfdc.user.username=YOUR_USER_NAME |
| sfdc.user.password=YOUR_PASSWORD |
| sfdc.user.securityToken=YOUR_USER_SECURITY_TOKEN |
| sfdc.consumer.key=CONNECTED_APP_CONSUMER_KEY |
| sfdc.consumer.secret=CONNECTED_APP_SECRET |
| ---- |
| |
| and then use the following command line to reference the file: |
| |
| [source] |
| ---- |
| cd extensions/salesforce-connector |
| mvn clean install -DsfdcProperties=../test.properties |
| ---- |
| |
| (in case you're wondering the ../ is because the test is located in the services sub-directory) |