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

===== 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 <<Data Model Overview,Data Model>> 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-&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)