Repository: incubator-unomi Updated Branches: refs/heads/master 3ade4d26a -> 3b808eed1
UNOMI-208 Improve documentation - Backport doc improvements to 1.3.x documentation Signed-off-by: Serge Huber <shu...@apache.org> Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/3b808eed Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/3b808eed Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/3b808eed Branch: refs/heads/master Commit: 3b808eed14863c1e1f0c5fd751d19349717722af Parents: 3ade4d2 Author: Serge Huber <shu...@apache.org> Authored: Thu Nov 15 13:19:18 2018 +0100 Committer: Serge Huber <shu...@apache.org> Committed: Thu Nov 15 13:19:18 2018 +0100 ---------------------------------------------------------------------- .../1.3/asciidoc/building-and-deploying.adoc | 39 ++----- .../archives/1.3/asciidoc/configuration.adoc | 14 ++- .../1.3/asciidoc/connectors/connectors.adoc | 7 +- .../connectors/salesforce-connector.adoc | 110 +++++++------------ .../1.3/asciidoc/custom-extensions.adoc | 4 +- .../archives/1.3/asciidoc/getting-started.adoc | 11 +- manual/src/archives/1.3/asciidoc/index.adoc | 29 +++-- .../1.3/asciidoc/samples/login-sample.adoc | 12 +- .../archives/1.3/asciidoc/samples/samples.adoc | 4 +- .../1.3/asciidoc/samples/twitter-sample.adoc | 2 +- .../asciidoc/samples/weather-update-sample.adoc | 2 +- 11 files changed, 94 insertions(+), 140 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/building-and-deploying.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/building-and-deploying.adoc b/manual/src/archives/1.3/asciidoc/building-and-deploying.adoc index b285779..558ddd2 100644 --- a/manual/src/archives/1.3/asciidoc/building-and-deploying.adoc +++ b/manual/src/archives/1.3/asciidoc/building-and-deploying.adoc @@ -16,59 +16,54 @@ ==== Initial Setup -1) Install J2SE 8.0 SDK (or later), which can be downloaded from +. Install J2SE 8.0 SDK (or later), which can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/index.html] -2) Make sure that your JAVA_HOME environment variable is set to the newly installed +. Make sure that your JAVA_HOME environment variable is set to the newly installed JDK location, and that your PATH includes %JAVA_HOME%\bin (windows) or $JAVA_HOME$/bin (unix). -3) Install Maven 3.0.3 (or later), which can be downloaded from +. Install Maven 3.0.3 (or later), which can be downloaded from http://maven.apache.org/download.html[http://maven.apache.org/download.html]. Make sure that your PATH includes the MVN_HOME/bin directory. ==== Building -1) Change to the top level directory of Apache Unomi source distribution. -2) Run - +. Get the code: `git clone https://git-wip-us.apache.org/repos/asf/incubator-unomi.git` +. Change to the top level directory of Apache Unomi source distribution. +. Run ++ [source] ---- $> mvn clean install ---- - ++ This will compile Apache Unomi and run all of the tests in the Apache Unomi source distribution. Alternatively, you can run - ++ [source] ---- $> mvn -P \!integration-tests,\!performance-tests clean install ---- - ++ This will compile Apache Unomi without running the tests and takes less time to build. -3) The distributions will be available under "package/target" directory. +. The distributions will be available under "package/target" directory. ==== Installing an ElasticSearch server Starting with version 1.2, Apache Unomi no longer embeds an ElasticSearch server as this is no longer supported by the developers of ElasticSearch. Therefore you will need to install a standalone ElasticSearch using the following steps: -. - Download an ElasticSearch version. Here's the version you will need depending on your version of Apache Unomi. Apache Unomi <= 1.2 : https://www.elastic.co/downloads/past-releases/elasticsearch-5-1-2[https://www.elastic.co/downloads/past-releases/elasticsearch-5-1-2] Apache Unomi >= 1.3 : https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3[https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3] -. - Uncompress the downloaded package into a directory -. - In the config/elasticsearch.yml file, uncomment and modify the following line : [source] @@ -76,8 +71,6 @@ In the config/elasticsearch.yml file, uncomment and modify the following line : cluster.name: contextElasticSearch ---- -. - Launch the server using [source] @@ -86,8 +79,6 @@ bin/elasticsearch (Mac, Linux) bin\elasticsearch.bat (Windows) ---- -. - Check that the ElasticSearch is up and running by accessing the following URL : http://localhost:9200[http://localhost:9200] @@ -128,8 +119,6 @@ environment if you intend to re-deploy the context server KAR iteratively. Additional requirements: * Apache Karaf 3.x, http://karaf.apache.org[http://karaf.apache.org] -. - Before deploying, make sure that you have Apache Karaf properly installed. You will also have to increase the default maximum memory size and perm gen size by adjusting the following environment values in the bin/setenv(.bat) files (at the end of the file): @@ -142,8 +131,6 @@ files (at the end of the file): export JAVA_MAX_PERM_MEM=384M ---- -. - Install the WAR support, CXF and Karaf Cellar into Karaf by doing the following in the Karaf command line: [source] @@ -154,8 +141,6 @@ Install the WAR support, CXF and Karaf Cellar into Karaf by doing the following feature:install unomi-kar ---- -. - Create a new $MY_KARAF_HOME/etc/org.apache.cxf.osgi.cfg file and put the following property inside : [source] @@ -163,8 +148,6 @@ Create a new $MY_KARAF_HOME/etc/org.apache.cxf.osgi.cfg file and put the followi org.apache.cxf.servlet.context=/cxs ---- -. - If all went smoothly, you should be able to access the context script here : http://localhost:8181/cxs/cluster[http://localhost:8181/cxs/cluster] . You should be able to login with karaf / karaf and see basic server information. If not something went wrong during the install. http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/configuration.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/configuration.adoc b/manual/src/archives/1.3/asciidoc/configuration.adoc index d6103e8..2c57e83 100644 --- a/manual/src/archives/1.3/asciidoc/configuration.adoc +++ b/manual/src/archives/1.3/asciidoc/configuration.adoc @@ -17,6 +17,16 @@ If you want to change the default configuration, you can perform any modification you want in the $MY_KARAF_HOME/etc directory. +If you want to change the HTTP ports that the server is listening on, you will need to add/change the following lines in the $MY_KARAF_HOME/etc/custom.properties file: + +[source] +---- +org.osgi.service.http.port.secure=9443 +org.osgi.service.http.port=8181 +---- + +If you change these ports, also make sure you adjust the following file in the cluster configuration. + The context server configuration is kept in the $MY_KARAF_HOME/etc/org.apache.unomi.cluster.cfg . It defines the addresses where it can be found : @@ -100,14 +110,10 @@ By default, the login/password for the REST API full administrative access is "k The generated package is also configured with a default SSL certificate. You can change it by following these steps : -. - Replace the existing keystore in $MY_KARAF_HOME/etc/keystore by your own certificate : http://wiki.eclipse.org/Jetty/Howto/Configure_SSL[http://wiki.eclipse.org/Jetty/Howto/Configure_SSL] -. - Update the keystore and certificate password in $MY_KARAF_HOME/etc/custom.properties file : [source] http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/connectors/connectors.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/connectors/connectors.adoc b/manual/src/archives/1.3/asciidoc/connectors/connectors.adoc index ee3551b..961fc6a 100644 --- a/manual/src/archives/1.3/asciidoc/connectors/connectors.adoc +++ b/manual/src/archives/1.3/asciidoc/connectors/connectors.adoc @@ -15,8 +15,11 @@ Apache Unomi provides the following connectors: -* link:salesforce-connectors.html[Salesforce CRM connectors] +* <<_salesforce_connector,Salesforce CRM connector>> + +* <<_mailchimp_connector,Mailchimp connector>> ==== 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 link:../../mail-lists.html[mailing list]. \ No newline at end of file +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 link:http://unomi.apache.org/community.html[mailing list, window="_blank"]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/connectors/salesforce-connector.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/connectors/salesforce-connector.adoc b/manual/src/archives/1.3/asciidoc/connectors/salesforce-connector.adoc index 23c0a22..e3ff97b 100644 --- a/manual/src/archives/1.3/asciidoc/connectors/salesforce-connector.adoc +++ b/manual/src/archives/1.3/asciidoc/connectors/salesforce-connector.adoc @@ -11,30 +11,24 @@ // See the License for the specific language governing permissions and // limitations under the License. // -=== Apache Unomi Salesforce Connector +=== 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 -. - -Create a new developer account here: - +. 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" -. - -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: - +. In the settings, make sure you do the following: ++ [source] ---- Enable OAuth settings -> Activated @@ -42,28 +36,22 @@ 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): - ++ +. 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 ++ +. 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 +. 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 @@ -72,91 +60,75 @@ 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 : - ++ +. 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: - ++ +. Deploy into Apache Unomi using the following commands from the Apache Karaf shell: ++ [source] ---- feature:repo-add mvn:org.apache.unomi/unomi-salesforce-connectors-karaf-kar/${project.version}/xml/features feature:install unomi-salesforce-connectors-karaf-kar ---- - -. - -You can then test the connection to Salesforce by accessing the following URLs: - ++ +. 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.adoc,Concepts>> and the link:getting-started.html[Getting Started] pages. -. - -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 link:concepts.html[Concepts] and the link:getting-started.html[Getting Started] pages. - -==== Upgrading the Salesforce connectors +==== 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: - +. Compile the connectors using: ++ [source] ---- cd extensions/salesforce-connectors mvn clean install ---- - -. - -Login to the Unomi Karaf Shell using: - ++ +. 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 - ++ +. Execute the following commands in the Karaf shell ++ [source] ---- feature:repo-refresh feature:uninstall unomi-salesforce-connectors-karaf-feature feature:install unomi-salesforce-connectors-karaf-feature ---- - -. - -You can then check that the new version is properly deployed by accessing the following URL and checking the build date: - ++ +. 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 http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/custom-extensions.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/custom-extensions.adoc b/manual/src/archives/1.3/asciidoc/custom-extensions.adoc index 20faa72..0ab8d46 100644 --- a/manual/src/archives/1.3/asciidoc/custom-extensions.adoc +++ b/manual/src/archives/1.3/asciidoc/custom-extensions.adoc @@ -14,8 +14,8 @@ === Custom extensions Apache Unomi is a pluggeable server that may be extended in many ways. This document assumes you are familiar with the -link:concepts.html[Apache Unomi concepts] . This document is mostly a reference document on the different things that may -be used inside an extension. If you are looking for complete samples, please see the link:samples.html[samples page]. +<<_concepts,Apache Unomi concepts>> . This document is mostly a reference document on the different things that may +be used inside an extension. If you are looking for complete samples, please see the <<_samples,samples page>>. ==== Creating an extension http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/getting-started.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/getting-started.adoc b/manual/src/archives/1.3/asciidoc/getting-started.adoc index b0307a2..bca312a 100644 --- a/manual/src/archives/1.3/asciidoc/getting-started.adoc +++ b/manual/src/archives/1.3/asciidoc/getting-started.adoc @@ -17,18 +17,13 @@ We will first get you up and running with an example. We will then lift the corn ==== Prerequisites -This document assumes that you are already familiar with Unomi's link:concepts.html[concepts]. On the technical side, we also assume working knowledge of https://git-scm.com/[git] to be able to retrieve the code for Unomi and the example. Additionnally, you will require a working Java 7 or above install. Refer to http://www.oracle.com/technetwork/java/javase/[http://www.oracle.com/technetwork/java/javase/] for details on how to download and install Java SE 7 or greater. +This document assumes that you are already familiar with Unomi's <<_concepts,concepts>>. On the technical side, we also assume working knowledge of https://git-scm.com/[git] to be able to retrieve the code for Unomi and the example. Additionnally, you will require a working Java 7 or above install. Refer to http://www.oracle.com/technetwork/java/javase/[http://www.oracle.com/technetwork/java/javase/] for details on how to download and install Java SE 7 or greater. ==== Running Unomi -===== Building Unomi - -. Get the code: `git clone https://git-wip-us.apache.org/repos/asf/incubator-unomi.git` -. Build and install according to the link:building-and-deploying.html[instructions] and install Unomi. - ===== Start Unomi -Start Unomi according to the link:building-and-deploying.html#Deploying_the_generated_package[instructions]. Once you have Karaf running, +Start Unomi according to the <<_5-min-quickstart,5 minute quick start>> or by compiling using the building link:building-and-deploying.html#Deploying_the_generated_package[instructions]. Once you have Karaf running, you should wait until you see the following messages on the Karaf console: [source] @@ -118,4 +113,4 @@ to send additional events. ===== Where to go from here -* Read the link:twitter-samples.html[Twitter samples] documentation that contains a detailed example of how to integrate with Apache Unomi. \ No newline at end of file +* Read the <<_twitter_sample,Twitter sample>> documentation that contains a detailed example of how to integrate with Apache Unomi. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/index.adoc b/manual/src/archives/1.3/asciidoc/index.adoc index 7008160..cc87b35 100644 --- a/manual/src/archives/1.3/asciidoc/index.adoc +++ b/manual/src/archives/1.3/asciidoc/index.adoc @@ -24,23 +24,21 @@ Apache Software Foundation image::incubator-logo.png[pdfwidth=35%,align=center] -== Concepts - -include::concepts.adoc[] +== Quick start -== Extending Unomi via plugins +include::5-min-quickstart.adoc[] -include::extending-plugins.adoc[] +== Concepts -== Quick start +include::concepts.adoc[] -include::building-and-deploying.adoc[] +== Setup include::getting-started.adoc[] include::configuration.adoc[] -== Sample +== Integration samples include::samples/samples.adoc[] @@ -56,14 +54,21 @@ include::connectors/connectors.adoc[] include::connectors/salesforce-connector.adoc[] +include::connectors/mailchimp-connector.adoc[] + == Cluster setup include::clustering.adoc[] -== Custom extensions +== Consent API -include::custom-extensions.adoc[] +include::consent-api.adoc[] +== Developers -== Consent API +include::building-and-deploying.adoc[] -include::consent-api.adoc[] \ No newline at end of file +include::shell-commands.adoc[] + +include::extending-plugins.adoc[] + +include::custom-extensions.adoc[] http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/samples/login-sample.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/samples/login-sample.adoc b/manual/src/archives/1.3/asciidoc/samples/login-sample.adoc index b1664d8..94065f3 100644 --- a/manual/src/archives/1.3/asciidoc/samples/login-sample.adoc +++ b/manual/src/archives/1.3/asciidoc/samples/login-sample.adoc @@ -11,7 +11,7 @@ // See the License for the specific language governing permissions and // limitations under the License. // -=== Login samples +=== Login sample This samples is an example of what is involved in integrated a login with Apache Unomi. @@ -25,8 +25,6 @@ only be sent if the user has authenticated properly, and only the authentication ==== Installing the samples -. - Login into the Unomi Karaf SSH shell using something like this : [source] @@ -34,8 +32,6 @@ Login into the Unomi Karaf SSH shell using something like this : ssh -p 8102 karaf@localhost (default password is karaf) ---- -. - Install the login samples using the following command: [source] @@ -45,8 +41,6 @@ bundle:install mvn:org.apache.unomi/login-integration-samples/${project.version} when the bundle is successfully install you will get an bundle ID back we will call it BUNDLE_ID. -. - You can then do: [source] @@ -54,8 +48,6 @@ You can then do: bundle:start BUNDLE_ID ---- -. - If all went well you can access the login samples HTML page here : [source] @@ -63,8 +55,6 @@ If all went well you can access the login samples HTML page here : http://localhost:8181/login/index.html ---- -. - You can fill in the form to test it. Note that the hardcoded password is: [source] http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/samples/samples.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/samples/samples.adoc b/manual/src/archives/1.3/asciidoc/samples/samples.adoc index 877a2e4..39fdd76 100644 --- a/manual/src/archives/1.3/asciidoc/samples/samples.adoc +++ b/manual/src/archives/1.3/asciidoc/samples/samples.adoc @@ -15,5 +15,5 @@ Apache Unomi provides the following samples: -* link:twitter-samples.html[Twitter integration] -* link:login-samples.html[Login integration] \ No newline at end of file +* <<_twitter_sample,Twitter integration>> +* <<_login_sample,Login integration>> http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/samples/twitter-sample.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/samples/twitter-sample.adoc b/manual/src/archives/1.3/asciidoc/samples/twitter-sample.adoc index f17bc80..a74f81c 100644 --- a/manual/src/archives/1.3/asciidoc/samples/twitter-sample.adoc +++ b/manual/src/archives/1.3/asciidoc/samples/twitter-sample.adoc @@ -11,7 +11,7 @@ // See the License for the specific language governing permissions and // limitations under the License. // -=== Twitter samples +=== Twitter sample ==== Overview http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3b808eed/manual/src/archives/1.3/asciidoc/samples/weather-update-sample.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/samples/weather-update-sample.adoc b/manual/src/archives/1.3/asciidoc/samples/weather-update-sample.adoc index cfde0f6..d40881e 100644 --- a/manual/src/archives/1.3/asciidoc/samples/weather-update-sample.adoc +++ b/manual/src/archives/1.3/asciidoc/samples/weather-update-sample.adoc @@ -11,4 +11,4 @@ // See the License for the specific language governing permissions and // limitations under the License. // -=== Weather update samples \ No newline at end of file +=== Weather update sample \ No newline at end of file
