//
// 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.
//

=== 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

. 

Create a new developer account here:

[source]
----
https://developer.salesforce.com/signup
----

. 

Create a new Connected App, by going into Setup -&gt; 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.

. 

You are now ready to configure the Apache Unomi Salesforce Connector. In the etc/org.apache.unomi.sfdc.cfg file
change the following settings:

[source]
----
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
----

. 

Connected 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/1.2.0-incubating-SNAPSHOT/xml/features
feature:install unomi-salesforce-connector-karaf-kar
----

. 

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 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.

. 

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 link:concepts.html[Concepts] and the link:getting-started.html[Getting Started] pages.

==== Troubleshooting

In case you're having problem retrieving or sending data to Salesforce, make sure you check the logs (log:display from the
Karaf shell) or in the data/log/karaf.log file. It should usually tell you what went wrong.

Common problems include trying to send profiles that don't include mandatory fields in Salesforce. By default the
mandatory fields are : Last name, Company and Email. If you are missing some mandatory fields, the connector will not
pushed any new leads to Salesforce. 

==== 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:

. 

Compile the connector 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-&gt;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)