Repository: incubator-unomi Updated Branches: refs/heads/master b88383a9e -> 167eb6330
UNOMI-116 Salesforce CRM Connector - Add documentation for the new connector Signed-off-by: Serge Huber <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/167eb633 Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/167eb633 Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/167eb633 Branch: refs/heads/master Commit: 167eb63302ea8885cb5cb5552960e3c394e43748 Parents: b88383a Author: Serge Huber <[email protected]> Authored: Wed Jul 19 15:18:44 2017 +0200 Committer: Serge Huber <[email protected]> Committed: Wed Jul 19 15:18:44 2017 +0200 ---------------------------------------------------------------------- extensions/salesforce-connector/README.md | 148 ------------------ src/site/markdown/index.md | 1 + src/site/markdown/versions/master/connectors.md | 26 ++++ .../versions/master/salesforce-connector.md | 156 +++++++++++++++++++ src/site/site.xml | 1 + 5 files changed, 184 insertions(+), 148 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/167eb633/extensions/salesforce-connector/README.md ---------------------------------------------------------------------- diff --git a/extensions/salesforce-connector/README.md b/extensions/salesforce-connector/README.md deleted file mode 100644 index 4bd7451..0000000 --- a/extensions/salesforce-connector/README.md +++ /dev/null @@ -1,148 +0,0 @@ -<!-- - ~ 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. - --> - -Unomi Salesforce Connector -========================== - -## Getting started - -1. Create a new developer account here: - - https://developer.salesforce.com/signup - -2. Create a new Connected App, by going into Setup -> App Manager and click "Create Connected App" - -3. In the settings, make sure you do the following: - - 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 - -4. Make sure you retrieve the following information once you have created the app in the API (Enable OAuth Settings): - - Consumer key - Consumer secret (click to see it) - -5. 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. - -6. You are now ready to configure the Apache Unomi Salesforce Connector. In the etc/org.apache.unomi.sfdc.cfg file -change the following settings: - - 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 - -7. Connected to the Apache Unomi Karaf Shell using : - - ssh -p 8102 karaf@localhost (default password is karaf) - -7. Deploy into Apache Unomi using the following commands from the Apache Karaf shell: - - feature:repo-add mvn:org.apache.unomi/unomi-salesforce-connector-karaf-kar/1.2.0-incubating-SNAPSHOT/xml/features - feature:install unomi-salesforce-connector-karaf-kar - -8. You can then test the connection to Salesforce by accessing the following URLs: - - https://localhost:9443/cxs/sfdc/version - https://localhost:9443/cxs/sfdc/limits - - The first URL will give you information about the version of the connector, 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. - -## Upgrading the Salesforce connector - -If you followed all the steps in the Getting Started section, you can upgrade the Salesforce connector by using the following steps: - -1. Compile the connector using: - - mvn clean install - -2. Login to the Unomi Karaf Shell using: - - ssh -p 8102 karaf@localhost (password by default is karaf) - -3. Execute the following commands in the Karaf shell - - feature:repo-refresh - feature:uninstall unomi-salesforce-connector-karaf-feature - feature:install unomi-salesforce-connector-karaf-feature - -4. You can then check that the new version is properly deployed by accessing the following URL and checking the build date: - - 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 : - - 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: - - 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 - - # - # 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: - - mvn clean install -DsfdcProperties=../test.properties - -(in case you're wondering the ../ is because the test is located in the services sub-directory) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/167eb633/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 1215a61..fd2d7c5 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -81,6 +81,7 @@ All communication is done using HTTP REST requests and JSON data formats. ### News +- 2017-07-19 New Salesforce CRM connector contributed - 2016-10-04 Released version 1.1.0-incubating - 2016-05-22 Released version 1.0.0-incubating - 2015-11-23 Initial code base import in [Git repository](source-repository.html) http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/167eb633/src/site/markdown/versions/master/connectors.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/versions/master/connectors.md b/src/site/markdown/versions/master/connectors.md new file mode 100644 index 0000000..3f688f2 --- /dev/null +++ b/src/site/markdown/versions/master/connectors.md @@ -0,0 +1,26 @@ +<!-- + ~ 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. + --> + +# Connectors + +Apache Unomi provides the following connector: + +- [Salesforce CRM connector](salesforce-connector.html) + +## Call for contributors + +We are looking for help with the development of additional connectors. Any contribution (large or small) is more than welcome. Feel free to discuss this in our [mailing list](../../mail-lists.html). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/167eb633/src/site/markdown/versions/master/salesforce-connector.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/versions/master/salesforce-connector.md b/src/site/markdown/versions/master/salesforce-connector.md new file mode 100644 index 0000000..d87d722 --- /dev/null +++ b/src/site/markdown/versions/master/salesforce-connector.md @@ -0,0 +1,156 @@ +<!-- + ~ 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. + --> + +Apache Unomi Salesforce Connector +================================= + +This connector 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 + +1. Create a new developer account here: + + https://developer.salesforce.com/signup + +2. Create a new Connected App, by going into Setup -> App Manager and click "Create Connected App" + +3. In the settings, make sure you do the following: + + 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 + +4. Make sure you retrieve the following information once you have created the app in the API (Enable OAuth Settings): + + Consumer key + Consumer secret (click to see it) + +5. 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. + +6. You are now ready to configure the Apache Unomi Salesforce Connector. In the etc/org.apache.unomi.sfdc.cfg file +change the following settings: + + 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 + +7. Connected to the Apache Unomi Karaf Shell using : + + ssh -p 8102 karaf@localhost (default password is karaf) + +7. Deploy into Apache Unomi using the following commands from the Apache Karaf shell: + + feature:repo-add mvn:org.apache.unomi/unomi-salesforce-connector-karaf-kar/1.2.0-incubating-SNAPSHOT/xml/features + feature:install unomi-salesforce-connector-karaf-kar + +8. You can then test the connection to Salesforce by accessing the following URLs: + + https://localhost:9443/cxs/sfdc/version + https://localhost:9443/cxs/sfdc/limits + + The first URL will give you information about the version of the connector, 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. + +9. You can now use the connector'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.html) and the [Getting Started](getting-started.html) pages. + +## Upgrading the Salesforce connector + +If you followed all the steps in the Getting Started section, you can upgrade the Salesforce connector by using the following steps: + +1. Compile the connector using: + + cd extensions/salesforce-connector + mvn clean install + +2. Login to the Unomi Karaf Shell using: + + ssh -p 8102 karaf@localhost (password by default is karaf) + +3. Execute the following commands in the Karaf shell + + feature:repo-refresh + feature:uninstall unomi-salesforce-connector-karaf-feature + feature:install unomi-salesforce-connector-karaf-feature + +4. You can then check that the new version is properly deployed by accessing the following URL and checking the build date: + + 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 : + + 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: + + 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 + + # + # 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: + + 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) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/167eb633/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 8d32262..c130897 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -119,6 +119,7 @@ <item name="Building and deploying" href="versions/master/building-and-deploying.html" /> <item name="Getting started" href="versions/master/getting-started.html"/> <item name="Configuration" href="versions/master/configuration.html" /> + <item name="Connectors" href="versions/master/connectors.html" /> <item name="Cluster setup" href="versions/master/clustering.html" /> <item name="Concepts" href="versions/master/concepts.html"/> </item>
