You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@unomi.apache.org by sh...@apache.org on 2018/11/15 12:01:34 UTC
incubator-unomi git commit: UNOMI-208 Improve documentation - Fix
cross-references - Fix numbering in certain sections - Add documentation on
port number change
Repository: incubator-unomi
Updated Branches:
refs/heads/master 23b556fe1 -> 3ade4d26a
UNOMI-208 Improve documentation
- Fix cross-references
- Fix numbering in certain sections
- Add documentation on port number change
Signed-off-by: Serge Huber <sh...@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/3ade4d26
Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/3ade4d26
Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/3ade4d26
Branch: refs/heads/master
Commit: 3ade4d26a610e052e9e20261d1e6e0611bb5cb35
Parents: 23b556f
Author: Serge Huber <sh...@apache.org>
Authored: Thu Nov 15 13:01:23 2018 +0100
Committer: Serge Huber <sh...@apache.org>
Committed: Thu Nov 15 13:01:23 2018 +0100
----------------------------------------------------------------------
manual/pom.xml | 56 +++++-----
.../main/asciidoc/building-and-deploying.adoc | 22 ++--
manual/src/main/asciidoc/configuration.adoc | 10 ++
.../main/asciidoc/connectors/connectors.adoc | 7 +-
.../connectors/mailchimp-connector.adoc | 2 +-
.../connectors/salesforce-connector.adoc | 110 +++++++------------
manual/src/main/asciidoc/custom-extensions.adoc | 4 +-
manual/src/main/asciidoc/getting-started.adoc | 6 +-
.../src/main/asciidoc/samples/login-sample.adoc | 2 +-
manual/src/main/asciidoc/samples/samples.adoc | 4 +-
.../main/asciidoc/samples/twitter-sample.adoc | 2 +-
.../asciidoc/samples/weather-update-sample.adoc | 2 +-
12 files changed, 106 insertions(+), 121 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3ade4d26/manual/pom.xml
----------------------------------------------------------------------
diff --git a/manual/pom.xml b/manual/pom.xml
index bf1c47f..71bc125 100644
--- a/manual/pom.xml
+++ b/manual/pom.xml
@@ -46,7 +46,7 @@
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
- <version>1.5.6</version>
+ <version>1.5.7.1</version>
<executions>
<execution>
<id>output-html</id>
@@ -55,6 +55,12 @@
<goal>process-asciidoc</goal>
</goals>
<configuration>
+ <sourceDocumentName>index.adoc</sourceDocumentName>
+ <sourceDirectory>${doc.source}</sourceDirectory>
+ <outputDirectory>${doc.output.html}</outputDirectory>
+ <preserveDirectories>true</preserveDirectories>
+ <headerFooter>true</headerFooter>
+ <imagesDir>${doc.source}/images</imagesDir>
<backend>html5</backend>
<doctype>article</doctype>
<attributes>
@@ -67,11 +73,6 @@
</execution>
</executions>
<configuration>
- <sourceDirectory>${doc.source}</sourceDirectory>
- <outputDirectory>${doc.output.html}</outputDirectory>
- <preserveDirectories>true</preserveDirectories>
- <headerFooter>true</headerFooter>
- <imagesDir>${doc.source}/images</imagesDir>
</configuration>
</plugin>
</plugins>
@@ -86,7 +87,7 @@
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
- <version>1.5.6</version>
+ <version>1.5.7.1</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
@@ -94,26 +95,6 @@
<version>1.5.0-alpha.16</version>
</dependency>
</dependencies>
- <configuration>
- <sourceDirectory>${doc.source}</sourceDirectory>
- <outputDirectory>${doc.output.pdf}</outputDirectory>
- <preserveDirectories>true</preserveDirectories>
- <headerFooter>true</headerFooter>
- <backend>pdf</backend>
- <attributes>
- <project-version>${project.version}</project-version>
- <pdf-stylesdir>${project.basedir}/src/theme</pdf-stylesdir>
- <pdf-style>apache</pdf-style>
- <pdf-fontsdir>${project.basedir}/src/theme/fonts</pdf-fontsdir>
- <imagesdir>images</imagesdir>
- <icons>font</icons>
- <pagenums>true</pagenums>
- <toc/>
- <idprefix/>
- <idseparator>-</idseparator>
- <sectnums>true</sectnums>
- </attributes>
- </configuration>
<executions>
<execution>
<id>generate-pdf-doc</id>
@@ -121,6 +102,27 @@
<goals>
<goal>process-asciidoc</goal>
</goals>
+ <configuration>
+ <sourceDocumentName>index.adoc</sourceDocumentName>
+ <sourceDirectory>${doc.source}</sourceDirectory>
+ <outputDirectory>${doc.output.pdf}</outputDirectory>
+ <preserveDirectories>true</preserveDirectories>
+ <headerFooter>true</headerFooter>
+ <backend>pdf</backend>
+ <attributes>
+ <project-version>${project.version}</project-version>
+ <pdf-stylesdir>${project.basedir}/src/theme</pdf-stylesdir>
+ <pdf-style>apache</pdf-style>
+ <pdf-fontsdir>${project.basedir}/src/theme/fonts</pdf-fontsdir>
+ <imagesdir>images</imagesdir>
+ <icons>font</icons>
+ <pagenums>true</pagenums>
+ <toc/>
+ <idprefix/>
+ <idseparator>-</idseparator>
+ <sectnums>true</sectnums>
+ </attributes>
+ </configuration>
</execution>
</executions>
</plugin>
http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3ade4d26/manual/src/main/asciidoc/building-and-deploying.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc b/manual/src/main/asciidoc/building-and-deploying.adoc
index e7e5a11..03e80e2 100644
--- a/manual/src/main/asciidoc/building-and-deploying.adoc
+++ b/manual/src/main/asciidoc/building-and-deploying.adoc
@@ -16,40 +16,40 @@
==== 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) Get the code: `git clone https://git-wip-us.apache.org/repos/asf/incubator-unomi.git`
-2) Change to the top level directory of Apache Unomi source distribution.
-3) 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.
-4) The distributions will be available under "package/target" directory.
+. The distributions will be available under "package/target" directory.
==== Installing an ElasticSearch server
http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3ade4d26/manual/src/main/asciidoc/configuration.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/configuration.adoc b/manual/src/main/asciidoc/configuration.adoc
index 79b787c..2c57e83 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/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 :
http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3ade4d26/manual/src/main/asciidoc/connectors/connectors.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/connectors/connectors.adoc b/manual/src/main/asciidoc/connectors/connectors.adoc
index a701a09..961fc6a 100644
--- a/manual/src/main/asciidoc/connectors/connectors.adoc
+++ b/manual/src/main/asciidoc/connectors/connectors.adoc
@@ -15,10 +15,11 @@
Apache Unomi provides the following connectors:
-* link:connectors/salesforce-connectors.html[Salesforce CRM connectors]
+* <<_salesforce_connector,Salesforce CRM connector>>
-* link:connectors/mailchimp-connectors.html[MailChimp connectors]
+* <<_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:http://unomi.apache.org/community.html[mailing list, window="_blank"].
\ 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/3ade4d26/manual/src/main/asciidoc/connectors/mailchimp-connector.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/connectors/mailchimp-connector.adoc b/manual/src/main/asciidoc/connectors/mailchimp-connector.adoc
index e66b828..2a220ed 100644
--- a/manual/src/main/asciidoc/connectors/mailchimp-connector.adoc
+++ b/manual/src/main/asciidoc/connectors/mailchimp-connector.adoc
@@ -11,7 +11,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-=== Apache Unomi :: Extensions :: MailChimp Connector
+=== MailChimp Connector
This extension has 3 actions:
http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3ade4d26/manual/src/main/asciidoc/connectors/salesforce-connector.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/connectors/salesforce-connector.adoc b/manual/src/main/asciidoc/connectors/salesforce-connector.adoc
index 23c0a22..e3ff97b 100644
--- a/manual/src/main/asciidoc/connectors/salesforce-connector.adoc
+++ b/manual/src/main/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/3ade4d26/manual/src/main/asciidoc/custom-extensions.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/custom-extensions.adoc b/manual/src/main/asciidoc/custom-extensions.adoc
index c7e37b7..3ac0aae 100644
--- a/manual/src/main/asciidoc/custom-extensions.adoc
+++ b/manual/src/main/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/3ade4d26/manual/src/main/asciidoc/getting-started.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/getting-started.adoc b/manual/src/main/asciidoc/getting-started.adoc
index 1984310..bca312a 100644
--- a/manual/src/main/asciidoc/getting-started.adoc
+++ b/manual/src/main/asciidoc/getting-started.adoc
@@ -17,13 +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
===== Start Unomi
-Start Unomi according to the link:5-min-quickstart.html[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,
+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]
@@ -113,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/3ade4d26/manual/src/main/asciidoc/samples/login-sample.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/samples/login-sample.adoc b/manual/src/main/asciidoc/samples/login-sample.adoc
index 10d0084..94065f3 100644
--- a/manual/src/main/asciidoc/samples/login-sample.adoc
+++ b/manual/src/main/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.
http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/3ade4d26/manual/src/main/asciidoc/samples/samples.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/samples/samples.adoc b/manual/src/main/asciidoc/samples/samples.adoc
index 877a2e4..39fdd76 100644
--- a/manual/src/main/asciidoc/samples/samples.adoc
+++ b/manual/src/main/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/3ade4d26/manual/src/main/asciidoc/samples/twitter-sample.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/samples/twitter-sample.adoc b/manual/src/main/asciidoc/samples/twitter-sample.adoc
index f17bc80..a74f81c 100644
--- a/manual/src/main/asciidoc/samples/twitter-sample.adoc
+++ b/manual/src/main/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/3ade4d26/manual/src/main/asciidoc/samples/weather-update-sample.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/samples/weather-update-sample.adoc b/manual/src/main/asciidoc/samples/weather-update-sample.adoc
index cfde0f6..d40881e 100644
--- a/manual/src/main/asciidoc/samples/weather-update-sample.adoc
+++ b/manual/src/main/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