Archives manual 1.3
Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/667b57c3 Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/667b57c3 Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/667b57c3 Branch: refs/heads/master Commit: 667b57c35894cecd6e0a63013055457282ffc692 Parents: 191fbba Author: Francois Papon <[email protected]> Authored: Thu Sep 13 21:54:06 2018 +0400 Committer: Francois Papon <[email protected]> Committed: Thu Sep 13 21:54:06 2018 +0400 ---------------------------------------------------------------------- manual/src/archives/1.3/asciidoc/apache.css | 2448 ++++++++++++++++++ .../1.3/asciidoc/building-and-deploying.adoc | 276 ++ .../src/archives/1.3/asciidoc/clustering.adoc | 83 + manual/src/archives/1.3/asciidoc/concepts.adoc | 125 + .../archives/1.3/asciidoc/configuration.adoc | 397 +++ .../1.3/asciidoc/connectors/connectors.adoc | 22 + .../connectors/salesforce-connector.adoc | 224 ++ .../src/archives/1.3/asciidoc/consent-api.adoc | 139 + .../1.3/asciidoc/custom-extensions.adoc | 419 +++ .../1.3/asciidoc/extending-plugins.adoc | 113 + .../archives/1.3/asciidoc/getting-started.adoc | 121 + .../1.3/asciidoc/images/asf_logo_url.png | Bin 0 -> 21121 bytes .../1.3/asciidoc/images/incubator-logo.png | Bin 0 -> 8923 bytes .../1.3/asciidoc/images/unomi-request.png | Bin 0 -> 132731 bytes manual/src/archives/1.3/asciidoc/index.adoc | 69 + .../1.3/asciidoc/samples/login-sample.adoc | 73 + .../archives/1.3/asciidoc/samples/samples.adoc | 19 + .../1.3/asciidoc/samples/twitter-sample.adoc | 432 ++++ .../asciidoc/samples/weather-update-sample.adoc | 14 + 19 files changed, 4974 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/667b57c3/manual/src/archives/1.3/asciidoc/apache.css ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/apache.css b/manual/src/archives/1.3/asciidoc/apache.css new file mode 100644 index 0000000..2872ec3 --- /dev/null +++ b/manual/src/archives/1.3/asciidoc/apache.css @@ -0,0 +1,2448 @@ + +@import "https://fonts.googleapis.com/css?family=Open+Sans:400,700%7cDroid+Serif:400,700";; + +article, +aside, +details, +figcaption, +figure, +footer, +header, +hgroup, +main, +nav, +section, +summary { + display: block +} + +audio, +canvas, +video { + display: inline-block +} + +audio:not([controls]) { + display: none; + height: 0 +} + +script { + display: none !important +} + +html { + font-family: "Droid Serif"; + -ms-text-size-adjust: 100%; + -webkit-text-size-adjust: 100%; +} + +a { + background: transparent +} + +a:focus { + outline: thin dotted +} + +a:active, +a:hover { + outline: 0 +} + +h1 { + font-size: 2em; + margin: .67em 0 +} + +abbr[title] { + border-bottom: 1px dotted +} + +b, +strong { + font-weight: bold +} + +dfn { + font-style: italic +} + +hr { + -moz-box-sizing: content-box; + box-sizing: content-box; + height: 0 +} + +mark { + background: #ff0; + color: #000 +} + +code, +kbd, +pre, +samp { + font-family: monospace; + font-size: 1em +} + +pre { + white-space: pre-wrap +} + +q { + quotes: "\201C" "\201D" "\2018" "\2019" +} + +small { + font-size: 80% +} + +sub, +sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline +} + +sup { + top: -.5em +} + +sub { + bottom: -.25em +} + +img { + border: 0 +} + +svg:not(:root) { + overflow: hidden +} + +figure { + margin: 0 +} + +fieldset { + border: 1px solid silver; + margin: 0 2px; + padding: .35em .625em .75em +} + +legend { + border: 0; + padding: 0 +} + +button, +input, +select, +textarea { + font-family: inherit; + font-size: 100%; + margin: 0 +} + +button, +input { + line-height: normal +} + +button, +select { + text-transform: none +} + +button, +html input[type="button"], +input[type="reset"], +input[type="submit"] { + -webkit-appearance: button; + cursor: pointer +} + +button[disabled], +html input[disabled] { + cursor: default +} + +input[type="checkbox"], +input[type="radio"] { + box-sizing: border-box; + padding: 0 +} + +button::-moz-focus-inner, +input::-moz-focus-inner { + border: 0; + padding: 0 +} + +textarea { + overflow: auto; + vertical-align: top +} + +table { + border-collapse: collapse; + border-spacing: 0 +} + +*, +*::before, +*::after { + -moz-box-sizing: border-box; + -webkit-box-sizing: border-box; + box-sizing: border-box +} + +html, +body { + /*font-size: 100%*/ +} + +body { + background: #fff; + color: #333; + padding: 0; + margin: 0; + font-family: "Droid Serif", "DejaVu Serif", serif; + font-size: 14px; + font-style: normal; + line-height: 1.42857143; + position: relative; + cursor: auto; + tab-size: 4; + -moz-osx-font-smoothing: grayscale; + -webkit-font-smoothing: antialiased +} + +a:hover { + cursor: pointer +} + +img, +object, +embed { + max-width: 100%; + height: auto +} + +object, +embed { + height: 100% +} + +img { + -ms-interpolation-mode: bicubic +} + +.left { + float: left !important +} + +.right { + float: right !important +} + +.text-left { + text-align: left !important +} + +.text-right { + text-align: right !important +} + +.text-center { + text-align: center !important +} + +.text-justify { + text-align: justify !important +} + +.hide { + display: none +} + +img, +object, +svg { + display: inline-block; + vertical-align: middle +} + +textarea { + height: auto; + min-height: 50px +} + +select { + width: 100% +} + +.center { + margin-left: auto; + margin-right: auto +} + +.stretch { + width: 100% +} + +.subheader, +.admonitionblock td.content>.title, +.audioblock>.title, +.exampleblock>.title, +.imageblock>.title, +.listingblock>.title, +.literalblock>.title, +.stemblock>.title, +.openblock>.title, +.paragraph>.title, +.quoteblock>.title, +table.tableblock>.title, +.verseblock>.title, +.videoblock>.title, +.dlist>.title, +.olist>.title, +.ulist>.title, +.qlist>.title, +.hdlist>.title { + line-height: 1.45; + color: #585ac2; + font-weight: 400; + margin-top: 0; + margin-bottom: .25em +} + +div, +dl, +dt, +dd, +ul, +ol, +li, +h1, +h2, +h3, +#toctitle, +.sidebarblock>.content>.title, +h4, +h5, +h6, +pre, +form, +p, +blockquote, +th, +td { + margin: 0; + padding: 0; + direction: ltr +} + +a { + color: #585ac2; + text-decoration: underline; + line-height: inherit +} + +a:hover, +a:focus { + color: #373997; +} + +a img { + border: none +} + +p { + font-family: inherit; + font-weight: 400; + font-size: 1em; + line-height: 1.6; + margin-bottom: 1.25em; + text-rendering: optimizeLegibility +} + +p aside { + font-size: .875em; + line-height: 1.35; + font-style: italic +} + +h1, +h2, +h3, +#toctitle, +.sidebarblock>.content>.title, +h4, +h5, +h6 { + font-family: "Open Sans", "DejaVu Sans", sans-serif; + font-weight: bold; + /*font-style: bold;*/ + color: #303284; + text-rendering: optimizeLegibility; + margin-top: 1em; + margin-bottom: .5em; + line-height: 1.0125em; + text-transform: uppercase; +} + +h1 small, +h2 small, +h3 small, +#toctitle small, +.sidebarblock>.content>.title small, +h4 small, +h5 small, +h6 small { + font-size: 60%; + color: #303284; + line-height: 0 +} + +h1 { + font-size: 2.125em +} + +h2 { + font-size: 1.6875em +} + +h3, +#toctitle, +.sidebarblock>.content>.title { + font-size: 1.375em +} + +h4, +h5 { + font-size: 1.125em +} + +h6 { + font-size: 1em +} + +hr { + border: solid #dddddd; + border-width: 1px 0 0; + clear: both; + margin: 1.25em 0 1.1875em; + height: 0 +} + +em, +i { + font-style: italic; + line-height: inherit +} + +strong, +b { + font-weight: bold; + line-height: inherit +} + +small { + font-size: 60%; + line-height: inherit +} + +code { + font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace; + font-weight: 400; + color: #585ac2; +} + +ul, +ol, +dl { + font-size: 1em; + line-height: 1.6; + margin-bottom: 1.25em; + list-style-position: outside; + font-family: inherit +} + +ul, +ol { + margin-left: 1.5em +} + +ul li ul, +ul li ol { + margin-left: 1.25em; + margin-bottom: 0; + font-size: 1em +} + +ul.square li ul, +ul.circle li ul, +ul.disc li ul { + list-style: inherit +} + +ul.square { + list-style-type: square +} + +ul.circle { + list-style-type: circle +} + +ul.disc { + list-style-type: disc +} + +ol li ul, +ol li ol { + margin-left: 1.25em; + margin-bottom: 0 +} + +dl dt { + margin-bottom: .3125em; + font-weight: bold +} + +dl dd { + margin-bottom: 1.25em +} + +abbr, +acronym { + text-transform: uppercase; + font-size: 90%; + color: rgba(0, 0, 0, .8); + border-bottom: 1px dotted #ddd; + cursor: help +} + +abbr { + text-transform: none +} + +blockquote { + margin: 0 0 1.25em; + padding: .5625em 1.25em 0 1.1875em; + border-left: 1px solid #ddd +} + +blockquote cite { + display: block; + font-size: .9375em; + color: rgba(0, 0, 0, .6) +} + +blockquote cite::before { + content: "\2014 \0020" +} + +blockquote cite a, +blockquote cite a:visited { + color: rgba(0, 0, 0, .6) +} + +blockquote, +blockquote p { + line-height: 1.6; + color: rgba(0, 0, 0, .85) +} + +@media screen and (min-width:768px) { + h1, + h2, + h3, + #toctitle, + .sidebarblock>.content>.title, + h4, + h5, + h6 { + line-height: 1.2 + } + + h1 { + font-size: 2.75em + } + + h2 { + font-size: 2.3125em + } + + h3, + #toctitle, + .sidebarblock>.content>.title { + font-size: 1.6875em + } + + h4 { + font-size: 1.4375em + } + +} + +table { + background: #fff; + margin-bottom: 1.25em; + border: solid 1px #dddddd; +} + +table thead, +table tfoot { + background: #f7f8f7 +} + +table thead tr th, +table thead tr td, +table tfoot tr th, +table tfoot tr td { + padding: .5em .625em .625em; + font-size: inherit; + color: rgba(0, 0, 0, .8); + text-align: left +} + +table tr th, +table tr td { + padding: .5625em .625em; + font-size: inherit; + color: rgba(0, 0, 0, .8) +} + +table tr.even, +table tr.alt, +table tr:nth-of-type(even) { + background: #f8f8f7 +} + +table thead tr th, +table tfoot tr th, +table tbody tr td, +table tr td, +table tfoot tr td { + display: table-cell; + line-height: 1.6 +} + +h1, +h2, +h3, +#toctitle, +.sidebarblock>.content>.title, +h4, +h5, +h6 { + line-height: 1.2; + word-spacing: -.05em +} + +h1 strong, +h2 strong, +h3 strong, +#toctitle strong, +.sidebarblock>.content>.title strong, +h4 strong, +h5 strong, +h6 strong { + font-weight: 400 +} + +.clearfix::before, +.clearfix::after, +.float-group::before, +.float-group::after { + content: " "; + display: table +} + +.clearfix::after, +.float-group::after { + clear: both +} + +*:not(pre)>code { + font-size: .9375em; + font-style: normal !important; + letter-spacing: 0; + padding: .1em .5ex; + word-spacing: -.15em; + background-color: #f7f7f8; + -webkit-border-radius: 4px; + border-radius: 4px; + line-height: 1.45; + text-rendering: optimizeSpeed; + word-wrap: break-word +} + +*:not(pre)>code.nobreak { + word-wrap: normal +} + +*:not(pre)>code.nowrap { + white-space: nowrap +} + +pre, +pre>code { + line-height: 1.45; + color: #585ac2; + font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace; + font-weight: 400; + text-rendering: optimizeSpeed +} + +em em { + font-style: normal +} + +strong strong { + font-weight: 400 +} + +.keyseq { + color: rgba(51, 51, 51, .8) +} + +kbd { + font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace; + display: inline-block; + color: rgba(0, 0, 0, .8); + font-size: .65em; + line-height: 1.45; + background-color: #f7f7f7; + border: 1px solid #dddddd; + -webkit-border-radius: 3px; + border-radius: 3px; + -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, .2), 0 0 0 .1em white inset; + box-shadow: 0 1px 0 rgba(0, 0, 0, .2), 0 0 0 .1em #fff inset; + margin: 0 .15em; + padding: .2em .5em; + vertical-align: middle; + position: relative; + top: -.1em; + white-space: nowrap +} + +.keyseq kbd:first-child { + margin-left: 0 +} + +.keyseq kbd:last-child { + margin-right: 0 +} + +.menuseq, +.menuref { + color: #000 +} + +.menuseq b:not(.caret),.menuref { + font-weight: inherit +} + +.menuseq { + word-spacing: -.02em +} + +.menuseq b.caret { + font-size: 1.25em; + line-height: .8 +} + +.menuseq i.caret { + font-weight: bold; + text-align: center; + width: .45em +} + +b.button::before, +b.button::after { + position: relative; + top: -1px; + font-weight: 400 +} + +b.button::before { + content: "["; + padding: 0 3px 0 2px +} + +b.button::after { + content: "]"; + padding: 0 2px 0 3px +} + +p a>code:hover { + color: #585ac2; +} + +#header, +#content, +#footnotes, +#footer { + width: 100%; + margin-left: auto; + margin-right: auto; + margin-top: 0; + margin-bottom: 0; + max-width: 62.5em; + *zoom: 1; + position: relative; + padding-left: .9375em; + padding-right: .9375em +} + +#header::before, +#header::after, +#content::before, +#content::after, +#footnotes::before, +#footnotes::after, +#footer::before, +#footer::after { + content: " "; + display: table +} + +#header::after, +#content::after, +#footnotes::after, +#footer::after { + clear: both +} + +#content { + margin-top: 1.25em +} + +#content::before { + content: none +} + +#header>h1:first-child { + color: #303284; + margin-top: 2.25rem; + margin-bottom: 0 +} + +#header>h1:first-child+#toc { + margin-top: 8px; + border-top: 1px solid #dddddd +} + +#header>h1:only-child, +body.toc2 #header>h1:nth-last-child(2) { + border-bottom: 1px solid #dddddd; + padding-bottom: 8px +} + +#header .details { + border-bottom: 1px solid #dddddd; + line-height: 1.45; + padding-top: .25em; + padding-bottom: .25em; + padding-left: .25em; + color: rgba(0, 0, 0, .6); + display: -ms-flexbox; + display: -webkit-flex; + display: flex; + -ms-flex-flow: row wrap; + -webkit-flex-flow: row wrap; + flex-flow: row wrap +} + +#header .details span:first-child { + margin-left: -.125em +} + +#header .details span.email a { + color: rgba(0, 0, 0, .85) +} + +#header .details br { + display: none +} + +#header .details br+span::before { + content: "\00a0\2013\00a0" +} + +#header .details br+span.author::before { + content: "\00a0\22c5\00a0"; + color: rgba(0, 0, 0, .85) +} + +#header .details br+span#revremark::before { + content: "\00a0|\00a0" +} + +#header #revnumber { + text-transform: capitalize +} + +#header #revnumber::after { + content: "\00a0" +} + +#content>h1:first-child:not([class]) { + color: rgba(0, 0, 0, .85); + border-bottom: 1px solid #dddddd +; + padding-bottom: 8px; + margin-top: 0; + padding-top: 1rem; + margin-bottom: 1.25rem +} + +#toc { + border-bottom: 1px solid #dddddd; + padding-bottom: .5em +} + +#toc>ul { + margin-left: .125em +} + +#toc ul.sectlevel0>li>a { + font-style: italic +} + +#toc ul.sectlevel0 ul.sectlevel1 { + margin: .5em 0 +} + +#toc ul { + font-family: "Droid Serif", "DejaVu Sans", sans-serif; + list-style-type: none +} + +#toc li { + line-height: 1.3334; + margin-top: .3334em +} + +#toc a { + text-decoration: none +} + +#toc a:active { + text-decoration: underline +} + +#toctitle { + color: #303284; + font-size: 1.2em +} + +@media screen and (min-width:768px) { + #toctitle { + font-size: 1.375em + } + + body.toc2 { + padding-left: 15em; + padding-right: 0 + } + + #toc.toc2 { + margin-top: 0 !important; + background-color: #eee; + position: fixed; + width: 15em; + left: 0; + top: 0; + border-right: 1px solid #dddddd; + border-top-width: 0 !important; + border-bottom-width: 0 !important; + z-index: 1000; + padding: 1.25em 1em; + height: 100%; + overflow: auto + } + + #toc.toc2 #toctitle { + margin-top: 0; + margin-bottom: .8rem; + font-size: 1.2em + } + + #toc.toc2>ul { + font-size: .9em; + margin-bottom: 0 + } + + #toc.toc2 ul ul { + margin-left: 0; + padding-left: 1em + } + + #toc.toc2 ul.sectlevel0 ul.sectlevel1 { + padding-left: 0; + margin-top: .5em; + margin-bottom: .5em + } + + body.toc2.toc-right { + padding-left: 0; + padding-right: 15em + } + + body.toc2.toc-right #toc.toc2 { + border-right-width: 0; + border-left: 1px solid #dddddd; + left: auto; + right: 0 + } + +} + +@media screen and (min-width:1280px) { + body.toc2 { + padding-left: 20em; + padding-right: 0 + } + + #toc.toc2 { + width: 20em + } + + #toc.toc2 #toctitle { + font-size: 1.375em + } + + #toc.toc2>ul { + font-size: .95em + } + + #toc.toc2 ul ul { + padding-left: 1.25em + } + + body.toc2.toc-right { + padding-left: 0; + padding-right: 20em + } + +} + +#content #toc { + border-style: solid; + border-width: 1px; + border-color: #dddddd; + margin-bottom: 1.25em; + padding: 1.25em; + background: #f8f8f7; + -webkit-border-radius: 4px; + border-radius: 4px +} + +#content #toc>:first-child { + margin-top: 0 +} + +#content #toc>:last-child { + margin-bottom: 0 +} + +#footer { + max-width: 100%; + background-color: #303284; + padding: 1.25em +} + +#footer-text { + color: #fff; + line-height: 1.44 +} + +#content { + margin-bottom: .625em +} + +.sect1 { + padding-bottom: .625em +} + +@media screen and (min-width:768px) { + #content { + margin-bottom: 1.25em + } + + .sect1 { + padding-bottom: 1.25em + } + +} + +.sect1:last-child { + padding-bottom: 0 +} + +.sect1+.sect1 { + border-top: 1px solid #dddddd; +} + +#content h1>a.anchor, +h2>a.anchor, +h3>a.anchor, +#toctitle>a.anchor, +.sidebarblock>.content>.title>a.anchor, +h4>a.anchor, +h5>a.anchor, +h6>a.anchor { + position: absolute; + z-index: 1001; + width: 1.5ex; + margin-left: -1.5ex; + display: block; + text-decoration: none !important; + visibility: hidden; + text-align: center; + font-weight: 400 +} + +#content h1>a.anchor::before, +h2>a.anchor::before, +h3>a.anchor::before, +#toctitle>a.anchor::before, +.sidebarblock>.content>.title>a.anchor::before, +h4>a.anchor::before, +h5>a.anchor::before, +h6>a.anchor::before { + content: "\00A7"; + font-size: .85em; + display: block; + padding-top: .1em +} + +#content h1:hover>a.anchor, +#content h1>a.anchor:hover, +h2:hover>a.anchor, +h2>a.anchor:hover, +h3:hover>a.anchor, +#toctitle:hover>a.anchor, +.sidebarblock>.content>.title:hover>a.anchor, +h3>a.anchor:hover, +#toctitle>a.anchor:hover, +.sidebarblock>.content>.title>a.anchor:hover, +h4:hover>a.anchor, +h4>a.anchor:hover, +h5:hover>a.anchor, +h5>a.anchor:hover, +h6:hover>a.anchor, +h6>a.anchor:hover { + visibility: visible +} + +#content h1>a.link, +h2>a.link, +h3>a.link, +#toctitle>a.link, +.sidebarblock>.content>.title>a.link, +h4>a.link, +h5>a.link, +h6>a.link { + color: #ba3925; + text-decoration: none +} + +#content h1>a.link:hover, +h2>a.link:hover, +h3>a.link:hover, +#toctitle>a.link:hover, +.sidebarblock>.content>.title>a.link:hover, +h4>a.link:hover, +h5>a.link:hover, +h6>a.link:hover { + color: #a53221 +} + +.audioblock, +.imageblock, +.literalblock, +.listingblock, +.stemblock, +.videoblock { + margin-bottom: 1.25em +} + +.admonitionblock td.content>.title, +.audioblock>.title, +.exampleblock>.title, +.imageblock>.title, +.listingblock>.title, +.literalblock>.title, +.stemblock>.title, +.openblock>.title, +.paragraph>.title, +.quoteblock>.title, +table.tableblock>.title, +.verseblock>.title, +.videoblock>.title, +.dlist>.title, +.olist>.title, +.ulist>.title, +.qlist>.title, +.hdlist>.title { + text-rendering: optimizeLegibility; + text-align: left; + font-family: "Droid Serif", "DejaVu Serif", serif; + font-size: 1rem; + font-style: italic +} + +table.tableblock.fit-content>caption.title { + white-space: nowrap; + width: 0 +} + +.paragraph.lead>p, +#preamble>.sectionbody>[class="paragraph"]:first-of-type p { + font-size: 1.21875em; + line-height: 1.6; + color: rgba(0, 0, 0, .85) +} + +table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p { + font-size: inherit +} + +.admonitionblock>table { + border-collapse: separate; + border: 0; + background: none; + width: 100% +} + +.admonitionblock>table td.icon { + text-align: center; + width: 80px +} + +.admonitionblock>table td.icon img { + max-width: none +} + +.admonitionblock>table td.icon .title { + font-weight: bold; + font-family: "Open Sans", "DejaVu Sans", sans-serif; + text-transform: uppercase +} + +.admonitionblock>table td.content { + padding-left: 1.125em; + padding-right: 1.25em; + border-left: 1px solid #dddddd; + color: rgba(0, 0, 0, .6) +} + +.admonitionblock>table td.content>:last-child>:last-child { + margin-bottom: 0 +} + +.exampleblock>.content { + border-style: solid; + border-width: 1px; + border-color: #dddddd; + margin-bottom: 1.25em; + padding: 1.25em; + background: #fff; + -webkit-border-radius: 4px; + border-radius: 4px +} + +.exampleblock>.content>:first-child { + margin-top: 0 +} + +.exampleblock>.content>:last-child { + margin-bottom: 0 +} + +.sidebarblock { + border-style: solid; + border-width: 1px; + border-color: #dddddd; + margin-bottom: 1.25em; + padding: 1.25em; + background: #f8f8f7; + -webkit-border-radius: 4px; + border-radius: 4px +} + +.sidebarblock>:first-child { + margin-top: 0 +} + +.sidebarblock>:last-child { + margin-bottom: 0 +} + +.sidebarblock>.content>.title { + color: #303284; + margin-top: 0; + text-align: center +} + +.exampleblock>.content>:last-child>:last-child, +.exampleblock>.content .olist>ol>li:last-child>:last-child, +.exampleblock>.content .ulist>ul>li:last-child>:last-child, +.exampleblock>.content .qlist>ol>li:last-child>:last-child, +.sidebarblock>.content>:last-child>:last-child, +.sidebarblock>.content .olist>ol>li:last-child>:last-child, +.sidebarblock>.content .ulist>ul>li:last-child>:last-child, +.sidebarblock>.content .qlist>ol>li:last-child>:last-child { + margin-bottom: 0 +} + +.literalblock pre, +.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint { + background: #f7f7f8 +} + +.sidebarblock .literalblock pre, +.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint { + background: #f2f1f1 +} + +.literalblock pre, +.literalblock pre[class], +.listingblock pre, +.listingblock pre[class] { + -webkit-border-radius: 4px; + border-radius: 4px; + word-wrap: break-word; + padding: 1em; + font-size: .8125em +} + +.literalblock pre.nowrap, +.literalblock pre[class].nowrap, +.listingblock pre.nowrap, +.listingblock pre[class].nowrap { + overflow-x: auto; + white-space: pre; + word-wrap: normal +} + +@media screen and (min-width:768px) { + .literalblock pre, + .literalblock pre[class], + .listingblock pre, + .listingblock pre[class] { + font-size: .90625em + } + +} + +@media screen and (min-width:1280px) { + .literalblock pre, + .literalblock pre[class], + .listingblock pre, + .listingblock pre[class] { + font-size: 1em + } + +} + +.literalblock.output pre { + color: #f7f7f8; + background-color: rgba(0, 0, 0, .9) +} + +.listingblock pre.highlightjs { + padding: 0 +} + +.listingblock pre.highlightjs>code { + padding: 1em; + -webkit-border-radius: 4px; + border-radius: 4px +} + +.listingblock pre.prettyprint { + border-width: 0 +} + +.listingblock>.content { + position: relative +} + +.listingblock code[data-lang]::before { + display: none; + content: attr(data-lang); + position: absolute; + font-size: .75em; + top: .425rem; + right: .5rem; + line-height: 1; + text-transform: uppercase; + color: #999 +} + +.listingblock:hover code[data-lang]::before { + display: block +} + +.listingblock.terminal pre .command::before { + content: attr(data-prompt); + padding-right: .5em; + color: #999 +} + +.listingblock.terminal pre .command:not([data-prompt])::before { + content: "$" +} + +table.pyhltable { + border-collapse: separate; + border: 0; + margin-bottom: 0; + background: none +} + +table.pyhltable td { + vertical-align: top; + padding-top: 0; + padding-bottom: 0; + line-height: 1.45 +} + +table.pyhltable td.code { + padding-left: .75em; + padding-right: 0 +} + +pre.pygments .lineno, +table.pyhltable td:not(.code) { + color: #999; + padding-left: 0; + padding-right: .5em; + border-right: 1px solid #dddddd; +} + +pre.pygments .lineno { + display: inline-block; + margin-right: .25em +} + +table.pyhltable .linenodiv { + background: none !important; + padding-right: 0 !important +} + +.quoteblock { + margin: 0 1em 1.25em 1.5em; + display: table +} + +.quoteblock>.title { + margin-left: -1.5em; + margin-bottom: .75em +} + +.quoteblock blockquote, +.quoteblock blockquote p { + color: rgba(0, 0, 0, .85); + font-size: 1.05rem; + line-height: 1.75; + word-spacing: .1em; + letter-spacing: 0; + font-style: italic; + text-align: justify +} + +.quoteblock blockquote { + margin: 0; + padding: 0; + border: 0 +} + +.quoteblock blockquote::before { + content: "\201c"; + float: left; + font-size: 2.75em; + font-weight: bold; + line-height: .6em; + margin-left: -.6em; + color: #303284; + text-shadow: 0 1px 2px rgba(0, 0, 0, .1) +} + +.quoteblock blockquote>.paragraph:last-child p { + margin-bottom: 0 +} + +.quoteblock .attribution { + margin-top: .5em; + margin-right: .5ex; + text-align: right +} + +.quoteblock .quoteblock { + margin-left: 0; + margin-right: 0; + padding: .5em 0; + border-left: 3px solid rgba(0, 0, 0, .6) +} + +.quoteblock .quoteblock blockquote { + padding: 0 0 0 .75em +} + +.quoteblock .quoteblock blockquote::before { + display: none +} + +.verseblock { + margin: 0 1em 1.25em +} + +.verseblock pre { + font-family: "Open Sans", "DejaVu Sans", sans; + font-size: 1.15rem; + color: rgba(0, 0, 0, .85); + font-weight: 300; + text-rendering: optimizeLegibility +} + +.verseblock pre strong { + font-weight: 400 +} + +.verseblock .attribution { + margin-top: 1.25rem; + margin-left: .5ex +} + +.quoteblock .attribution, +.verseblock .attribution { + font-size: .9375em; + line-height: 1.45; + font-style: italic +} + +.quoteblock .attribution br, +.verseblock .attribution br { + display: none +} + +.quoteblock .attribution cite, +.verseblock .attribution cite { + display: block; + letter-spacing: -.025em; + color: rgba(0, 0, 0, .6) +} + +.quoteblock.abstract { + margin: 0 1em 1.25em; + display: block +} + +.quoteblock.abstract>.title { + margin: 0 0 .375em; + font-size: 1.15em; + text-align: center +} + +.quoteblock.abstract blockquote, +.quoteblock.abstract blockquote p { + word-spacing: 0; + line-height: 1.6 +} + +.quoteblock.abstract blockquote::before, +.quoteblock.abstract p::before { + display: none +} + +table.tableblock { + max-width: 100%; + border-collapse: separate +} + +p.tableblock:last-child { + margin-bottom: 0 +} + +td.tableblock>.content { + margin-bottom: -1.25em +} + +table.tableblock, +th.tableblock, +td.tableblock { + border: 0 solid #dddddd; +} + +table.grid-all>thead>tr>.tableblock, +table.grid-all>tbody>tr>.tableblock { + border-width: 0 1px 1px 0 +} + +table.grid-all>tfoot>tr>.tableblock { + border-width: 1px 1px 0 0 +} + +table.grid-cols>*>tr>.tableblock { + border-width: 0 1px 0 0 +} + +table.grid-rows>thead>tr>.tableblock, +table.grid-rows>tbody>tr>.tableblock { + border-width: 0 0 1px +} + +table.grid-rows>tfoot>tr>.tableblock { + border-width: 1px 0 0 +} + +table.grid-all>*>tr>.tableblock:last-child, +table.grid-cols>*>tr>.tableblock:last-child { + border-right-width: 0 +} + +table.grid-all>tbody>tr:last-child>.tableblock, +table.grid-all>thead:last-child>tr>.tableblock, +table.grid-rows>tbody>tr:last-child>.tableblock, +table.grid-rows>thead:last-child>tr>.tableblock { + border-bottom-width: 0 +} + +table.frame-all { + border-width: 1px +} + +table.frame-sides { + border-width: 0 1px +} + +table.frame-topbot, +table.frame-ends { + border-width: 1px 0 +} + +table.stripes-all tr, +table.stripes-odd tr:nth-of-type(odd) { + background: #f8f8f7 +} + +table.stripes-none tr, +table.stripes-odd tr:nth-of-type(even) { + background: none +} + +th.halign-left, +td.halign-left { + text-align: left +} + +th.halign-right, +td.halign-right { + text-align: right +} + +th.halign-center, +td.halign-center { + text-align: center +} + +th.valign-top, +td.valign-top { + vertical-align: top +} + +th.valign-bottom, +td.valign-bottom { + vertical-align: bottom +} + +th.valign-middle, +td.valign-middle { + vertical-align: middle +} + +table thead th, +table tfoot th { + font-weight: bold +} + +tbody tr th { + display: table-cell; + line-height: 1.6; + background: #f7f8f7 +} + +tbody tr th, +tbody tr th p, +tfoot tr th, +tfoot tr th p { + color: rgba(0, 0, 0, .8); + font-weight: bold +} + +p.tableblock>code:only-child { + background: none; + padding: 0 +} + +p.tableblock { + font-size: 1em +} + +td>div.verse { + white-space: pre +} + +ol { + margin-left: 1.75em +} + +ul li ol { + margin-left: 1.5em +} + +dl dd { + margin-left: 1.125em +} + +dl dd:last-child, +dl dd:last-child>:last-child { + margin-bottom: 0 +} + +ol>li p, +ul>li p, +ul dd, +ol dd, +.olist .olist, +.ulist .ulist, +.ulist .olist, +.olist .ulist { + margin-bottom: .625em +} + +ul.checklist, +ul.none, +ol.none, +ul.no-bullet, +ol.no-bullet, +ol.unnumbered, +ul.unstyled, +ol.unstyled { + list-style-type: none +} + +ul.no-bullet, +ol.no-bullet, +ol.unnumbered { + margin-left: .625em +} + +ul.unstyled, +ol.unstyled { + margin-left: 0 +} + +ul.checklist { + margin-left: .625em +} + +ul.checklist li>p:first-child>.fa-square-o:first-child, +ul.checklist li>p:first-child>.fa-check-square-o:first-child { + width: 1.25em; + font-size: .8em; + position: relative; + bottom: .125em +} + +ul.checklist li>p:first-child>input[type="checkbox"]:first-child { + margin-right: .25em +} + +ul.inline { + display: -ms-flexbox; + display: -webkit-box; + display: flex; + -ms-flex-flow: row wrap; + -webkit-flex-flow: row wrap; + flex-flow: row wrap; + list-style: none; + margin: 0 0 .625em -1.25em +} + +ul.inline>li { + margin-left: 1.25em +} + +.unstyled dl dt { + font-weight: 400; + font-style: normal +} + +ol.arabic { + list-style-type: decimal +} + +ol.decimal { + list-style-type: decimal-leading-zero +} + +ol.loweralpha { + list-style-type: lower-alpha +} + +ol.upperalpha { + list-style-type: upper-alpha +} + +ol.lowerroman { + list-style-type: lower-roman +} + +ol.upperroman { + list-style-type: upper-roman +} + +ol.lowergreek { + list-style-type: lower-greek +} + +.hdlist>table, +.colist>table { + border: 0; + background: none +} + +.hdlist>table>tbody>tr, +.colist>table>tbody>tr { + background: none +} + +td.hdlist1, +td.hdlist2 { + vertical-align: top; + padding: 0 .625em +} + +td.hdlist1 { + font-weight: bold; + padding-bottom: 1.25em +} + +.literalblock+.colist, +.listingblock+.colist { + margin-top: -.5em +} + +.colist td:not([class]):first-child { + padding: .4em .75em 0; + line-height: 1; + vertical-align: top +} + +.colist td:not([class]):first-child img { + max-width: none +} + +.colist td:not([class]):last-child { + padding: .25em 0 +} + +.thumb, +.th { + line-height: 0; + display: inline-block; + border: solid 4px #fff; + -webkit-box-shadow: 0 0 0 1px #ddd; + box-shadow: 0 0 0 1px #ddd +} + +.imageblock.left, +.imageblock[style*="float:left"] { + margin: .25em .625em 1.25em 0 +} + +.imageblock.right, +.imageblock[style*="float:right"] { + margin: .25em 0 1.25em .625em +} + +.imageblock>.title { + margin-bottom: 0 +} + +.imageblock.thumb, +.imageblock.th { + border-width: 6px +} + +.imageblock.thumb>.title, +.imageblock.th>.title { + padding: 0 .125em +} + +.image.left, +.image.right { + margin-top: .25em; + margin-bottom: .25em; + display: inline-block; + line-height: 0 +} + +.image.left { + margin-right: .625em +} + +.image.right { + margin-left: .625em +} + +a.image { + text-decoration: none; + display: inline-block +} + +a.image object { + pointer-events: none +} + +sup.footnote, +sup.footnoteref { + font-size: .875em; + position: static; + vertical-align: super +} + +sup.footnote a, +sup.footnoteref a { + text-decoration: none +} + +sup.footnote a:active, +sup.footnoteref a:active { + text-decoration: underline +} + +#footnotes { + padding-top: .75em; + padding-bottom: .75em; + margin-bottom: .625em +} + +#footnotes hr { + width: 20%; + min-width: 6.25em; + margin: -.25em 0 .75em; + border-width: 1px 0 0 +} + +#footnotes .footnote { + padding: 0 .375em 0 .225em; + line-height: 1.3334; + font-size: .875em; + margin-left: 1.2em; + margin-bottom: .2em +} + +#footnotes .footnote a:first-of-type { + font-weight: bold; + text-decoration: none; + margin-left: -1.05em +} + +#footnotes .footnote:last-of-type { + margin-bottom: 0 +} + +#content #footnotes { + margin-top: -.625em; + margin-bottom: 0; + padding: .75em 0 +} + +.gist .file-data>table { + border: 0; + background: #fff; + width: 100%; + margin-bottom: 0 +} + +.gist .file-data>table td.line-data { + width: 99% +} + +div.unbreakable { + page-break-inside: avoid +} + +.big { + font-size: larger +} + +.small { + font-size: smaller +} + +.underline { + text-decoration: underline +} + +.overline { + text-decoration: overline +} + +.line-through { + text-decoration: line-through +} + +.aqua { + color: #00bfbf +} + +.aqua-background { + background-color: #00fafa +} + +.black { + color: #000 +} + +.black-background { + background-color: #000 +} + +.blue { + color: #0000bf +} + +.blue-background { + background-color: #0000fa +} + +.fuchsia { + color: #bf00bf +} + +.fuchsia-background { + background-color: #fa00fa +} + +.gray { + color: #606060 +} + +.gray-background { + background-color: #7d7d7d +} + +.green { + color: #006000 +} + +.green-background { + background-color: #007d00 +} + +.lime { + color: #00bf00 +} + +.lime-background { + background-color: #00fa00 +} + +.maroon { + color: #600000 +} + +.maroon-background { + background-color: #7d0000 +} + +.navy { + color: #000060 +} + +.navy-background { + background-color: #00007d +} + +.olive { + color: #606000 +} + +.olive-background { + background-color: #7d7d00 +} + +.purple { + color: #600060 +} + +.purple-background { + background-color: #7d007d +} + +.red { + color: #bf0000 +} + +.red-background { + background-color: #fa0000 +} + +.silver { + color: #909090 +} + +.silver-background { + background-color: #bcbcbc +} + +.teal { + color: #006060 +} + +.teal-background { + background-color: #007d7d +} + +.white { + color: #bfbfbf +} + +.white-background { + background-color: #fafafa +} + +.yellow { + color: #bfbf00 +} + +.yellow-background { + background-color: #fafa00 +} + +span.icon>.fa { + cursor: default +} + +a span.icon>.fa { + cursor: inherit +} + +.admonitionblock td.icon [class^="fa icon-"] { + font-size: 2.5em; + text-shadow: 1px 1px 2px rgba(0, 0, 0, .5); + cursor: default +} + +.admonitionblock td.icon .icon-note::before { + content: "\f05a"; + color: #19407c +} + +.admonitionblock td.icon .icon-tip::before { + content: "\f0eb"; + text-shadow: 1px 1px 2px rgba(155, 155, 0, .8); + color: #111 +} + +.admonitionblock td.icon .icon-warning::before { + content: "\f071"; + color: #bf6900 +} + +.admonitionblock td.icon .icon-caution::before { + content: "\f06d"; + color: #bf3400 +} + +.admonitionblock td.icon .icon-important::before { + content: "\f06a"; + color: #bf0000 +} + +.conum[data-value] { + display: inline-block; + color: #fff !important; + background-color: rgba(0, 0, 0, .8); + -webkit-border-radius: 100px; + border-radius: 100px; + text-align: center; + font-size: .75em; + width: 1.67em; + height: 1.67em; + line-height: 1.67em; + font-family: "Open Sans", "DejaVu Sans", sans-serif; + font-style: normal; + font-weight: bold +} + +.conum[data-value] * { + color: #fff !important +} + +.conum[data-value]+b { + display: none +} + +.conum[data-value]::after { + content: attr(data-value) +} + +pre .conum[data-value] { + position: relative; + top: -.125em +} + +b.conum * { + color: inherit !important +} + +.conum:not([data-value]):empty { + display: none +} + +dt, +th.tableblock, +td.content, +div.footnote { + text-rendering: optimizeLegibility +} + +h1, +h2, +p, +td.content, +span.alt { + letter-spacing: -.01em +} + +p strong, +td.content strong, +div.footnote strong { + letter-spacing: -.005em +} + +p, +blockquote, +dt, +td.content, +span.alt { + /*font-size: 1.0625rem*/ +} + +p { + margin-bottom: 1.25rem +} + +.sidebarblock p, +.sidebarblock dt, +.sidebarblock td.content, +p.tableblock { + font-size: 1em +} + +.exampleblock>.content { + background-color: #fffef7; + border-color: #dddddd; + -webkit-box-shadow: 0 1px 4px #e0e0dc; + box-shadow: 0 1px 4px #e0e0dc +} + +.print-only { + display: none !important +} + +@page { + margin: 1.25cm .75cm +} + +@media print { + * { + -webkit-box-shadow: none !important; + box-shadow: none !important; + text-shadow: none !important + } + + html { + font-size: 80% + } + + a { + color: inherit !important; + text-decoration: underline !important + } + + a.bare, + a[href^="#"], + a[href^="mailto:";] { + text-decoration: none !important + } + + a[href^="http:"]:not(.bare)::after, + a[href^="https:"]:not(.bare)::after { + content: "("attr(href) ")"; + display: inline-block; + font-size: .875em; + padding-left: .25em + } + + abbr[title]::after { + content: " ("attr(title) ")" + } + + pre, + blockquote, + tr, + img, + object, + svg { + page-break-inside: avoid + } + + thead { + display: table-header-group + } + + svg { + max-width: 100% + } + + p, + blockquote, + dt, + td.content { + font-size: 1em; + orphans: 3; + widows: 3 + } + + h2, + h3, + #toctitle, + .sidebarblock>.content>.title { + page-break-after: avoid + } + + #toc, + .sidebarblock, + .exampleblock>.content { + background: none !important + } + + #toc { + border-bottom: 1px solid #dddddd !important; + padding-bottom: 0 !important + } + + body.book #header { + text-align: center + } + + body.book #header>h1:first-child { + border: 0 !important; + margin: 2.5em 0 1em + } + + body.book #header .details { + border: 0 !important; + display: block; + padding: 0 !important + } + + body.book #header .details span:first-child { + margin-left: 0 !important + } + + body.book #header .details br { + display: block + } + + body.book #header .details br+span::before { + content: none !important + } + + body.book #toc { + border: 0 !important; + text-align: left !important; + padding: 0 !important; + margin: 0 !important + } + + body.book #toc, + body.book #preamble, + body.book h1.sect0, + body.book .sect1>h2 { + page-break-before: always + } + + .listingblock code[data-lang]::before { + display: block + } + + #footer { + padding: 0 .9375em + } + + .hide-on-print { + display: none !important + } + + .print-only { + display: block !important + } + + .hide-for-print { + display: none !important + } + + .show-for-print { + display: inherit !important + } + +} + +@media print, amzn-kf8 { + #header>h1:first-child { + margin-top: 1.25rem + } + + .sect1 { + padding: 0 !important + } + + .sect1+.sect1 { + border: 0 + } + + #footer { + background: none + } + + #footer-text { + color: rgba(0, 0, 0, .6); + font-size: .9em + } + +} + +@media amzn-kf8 { + #header, + #content, + #footnotes, + #footer { + padding: 0 + } + +} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/667b57c3/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 new file mode 100644 index 0000000..b285779 --- /dev/null +++ b/manual/src/archives/1.3/asciidoc/building-and-deploying.adoc @@ -0,0 +1,276 @@ +// +// 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. +// + +=== Building + +==== Initial Setup + +1) 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 + 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 + 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 + +[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. + +==== 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] +---- +cluster.name: contextElasticSearch +---- + +. + +Launch the server using + +[source] +---- +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] + +==== Deploying the generated binary package + +The "package" sub-project generates a pre-configured Apache Karaf installation that is the simplest way to get started. +Simply uncompress the package/target/unomi-VERSION.tar.gz (for Linux or Mac OS X) or + package/target/unomi-VERSION.zip (for Windows) archive into the directory of your choice. + +You can then start the server simply by using the command on UNIX/Linux/MacOS X : + +[source] +---- +./bin/karaf +---- + +or on Windows shell : + +[source] +---- +bin\karaf.bat +---- + +You will then need to launch (only on the first Karaf start) the Apache Unomi packages using the following Apache Karaf +shell command: + +[source] +---- +unomi:start +---- + +==== Deploying into an existing Karaf server + +This is only needed if you didn't use the generated package. Also, this is the preferred way to install a development +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): + +[source] +---- + MY_DIRNAME=`dirname $0` + MY_KARAF_HOME=`cd "$MY_DIRNAME/.."; pwd` + export JAVA_MAX_MEM=3G + 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] +---- + feature:repo-add cxf 3.0.2 + feature:repo-add cellar 3.0.3 + feature:repo-add mvn:org.apache.unomi/unomi-kar/VERSION/xml/features + feature:install unomi-kar +---- + +. + +Create a new $MY_KARAF_HOME/etc/org.apache.cxf.osgi.cfg file and put the following property inside : + +[source] +---- + 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. + +==== JDK Selection on Mac OS X + +You might need to select the JDK to run the tests in the itests subproject. In order to do so you can list the +installed JDKs with the following command : + +[source] +---- +/usr/libexec/java_home -V +---- + +which will output something like this : + +[source] +---- +Matching Java Virtual Machines (7): + 1.7.0_51, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_51.jdk/Contents/Home + 1.7.0_45, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_45.jdk/Contents/Home + 1.7.0_25, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_25.jdk/Contents/Home + 1.6.0_65-b14-462, x86_64: "Java SE 6" /Library/Java/JavaVirtualMachines/1.6.0_65-b14-462.jdk/Contents/Home + 1.6.0_65-b14-462, i386: "Java SE 6" /Library/Java/JavaVirtualMachines/1.6.0_65-b14-462.jdk/Contents/Home + 1.6.0_65-b14-462, x86_64: "Java SE 6" /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home + 1.6.0_65-b14-462, i386: "Java SE 6" /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home +---- + +You can then select the one you want using : + +[source] +---- +export JAVA_HOME=`/usr/libexec/java_home -v 1.7.0_51` +---- + +and then check that it was correctly referenced using: + +[source] +---- +java -version +---- + +which should give you a result such as this: + +[source] +---- +java version "1.7.0_51" +Java(TM) SE Runtime Environment (build 1.7.0_51-b13) +Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode) +---- + +==== Running the integration tests + +The integration tests are not executed by default to make build time minimal, but it is recommended to run the +integration tests at least once before using the server to make sure that everything is ok in the build. Another way +to use these tests is to run them from a continuous integration server such as Jenkins, Apache Gump, Atlassian Bamboo or + others. + +Note : the integration tests require a JDK 7 or more recent ! + +To run the tests simply activate the following profile : + +[source] +---- +mvn -P integration-tests clean install +---- + +==== Running the performance tests + +Performance tests are based on Gatling. You need to have a running context server or cluster of servers before +executing the tests. + +Test parameteres are editable in the performance-tests/src/test/scala/unomi/Parameters.scala file. baseUrls should +contains the URLs of all your cluster nodes + +Run the test by using the gatling.conf file in performance-tests/src/test/resources : + +[source] +---- + export GATLING_CONF=<path>/performance-tests/src/test/resources + gatling.sh +---- + +Reports are generated in performance-tests/target/results. + +==== Testing with an example page + +A default test page is provided at the following URL: + +[source] +---- + http://localhost:8181/index.html +---- + +This test page will trigger the loading of the /context.js script, which will try to retrieving the user context +or create a new one if it doesn't exist yet. It also contains an experimental integration with Facebook Login, but it +doesn't yet save the context back to the context server. + +==== Integrating onto a page + +Simply reference the context script in your HTML as in the following example: + +[source,javascript] +---- +<script type="text/javascript"> + (function(){ var u=(("https:" ==== document.location.protocol) ? "https://localhost:8181/"; : "http://localhost:8181/";); + var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript'; g.defer=true; g.async=true; g.src=u+'context.js'; + s.parentNode.insertBefore(g,s); })(); +</script> +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/667b57c3/manual/src/archives/1.3/asciidoc/clustering.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/clustering.adoc b/manual/src/archives/1.3/asciidoc/clustering.adoc new file mode 100644 index 0000000..0abc1f5 --- /dev/null +++ b/manual/src/archives/1.3/asciidoc/clustering.adoc @@ -0,0 +1,83 @@ +// +// 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. +// +=== Cluster setup + +Apache Karaf relies on Apache Karaf Cellar, which in turn uses Hazelcast to discover and configure its cluster. +You just need to install multiple context servers on the same network, and then (optionally) change the Hazelcast + configuration in the following file : + +[source] +---- +etc/hazelcast.xml +---- + +All nodes on the same network, sharing the same cluster name will be part of the same cluster. + +For the actual ElasticSearch configuration however, this must be done using the following file: + +[source] +---- +etc/org.apache.unomi.persistence.elasticsearch.cfg +---- + +Depending on the cluster size, you will want to adjust the following parameters to make sure your setup is optimal in +terms of performance and safety. + +==== 2 nodes configuration + +One node dedicated to context server, 1 node for elasticsearch storage. + +Node A : + +[source] +---- +numberOfReplicas=0 +monthlyIndex.numberOfReplicas=0 +---- + +Node B : + +[source] +---- +numberOfReplicas=0 +monthlyIndex.numberOfReplicas=0 +---- + +==== 3 nodes configuration + +One node dedicated to context server, 2 nodes for elasticsearch storage with fault-tolerance + +Node A : + +[source] +---- +numberOfReplicas=1 +monthlyIndex.numberOfReplicas=1 +---- + +Node B : + +[source] +---- +numberOfReplicas=1 +monthlyIndex.numberOfReplicas=1 +---- + +Node C : + +[source] +---- +numberOfReplicas=1 +monthlyIndex.numberOfReplicas=1 +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/667b57c3/manual/src/archives/1.3/asciidoc/concepts.adoc ---------------------------------------------------------------------- diff --git a/manual/src/archives/1.3/asciidoc/concepts.adoc b/manual/src/archives/1.3/asciidoc/concepts.adoc new file mode 100644 index 0000000..0849fcc --- /dev/null +++ b/manual/src/archives/1.3/asciidoc/concepts.adoc @@ -0,0 +1,125 @@ +// +// 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 gathers information about users actions, information that is processed and stored by Unomi services. The collected information can then be used to personalize content, derive insights on user behavior, categorize the user profiles into segments along user-definable dimensions or acted upon by algorithms. + +=== Items and types + +Unomi structures the information it collects using the concept of `Item` which provides the base information (an identifier and a type) the context server needs to process and store the data. Items are persisted according to their type (structure) and identifier (identity). This base structure can be extended, if needed, using properties in the form of key-value pairs. + +These properties are further defined by the `Item`âs type definition which explicits the `Item`âs structure and semantics. By defining new types, users specify which properties (including the type of values they accept) are available to items of that specific type. + +Unomi defines default value types: `date`, `email`, `integer` and `string`, all pretty self-explanatory. While you can think of these value types as "primitive" types, it is possible to extend Unomi by providing additional value types. + +Additionally, most items are also associated to a scope, which is a concept that Unomi uses to group together related items. A given scope is represented in Unomi by a simple string identifier and usually represents an application or set of applications from which Unomi gathers data, depending on the desired analysis granularity. In the context of web sites, a scope could, for example, represent a site or family of related sites being analyzed. Scopes allow clients accessing the context server to filter data to only see relevant data. + +_Base `Item` structure:_ + +[source,json] +---- +{ + "itemType": <type of the item>, + "scope": <scope>, + "itemId": <item identifier>, + "properties": <optional properties> +} +---- + +Some types can be dynamically defined at runtime by calling to the REST API while other extensions are done via Unomi plugins. Part of extending Unomi, therefore, is a matter of defining new types and specifying which kind of Unomi entity (e.g. profiles) they can be affected to. For example, the following JSON document can be passed to Unomi to declare a new property type identified (and named) `tweetNb`, tagged with the `social` tag, targeting profiles and using the `integer` value type. + +_Example JSON type definition:_ + +[source,json] +---- +{ + "itemId": "tweetNb", + "itemType": "propertyType", + "metadata": { + "id": "tweetNb", + "name": "tweetNb", + "systemTags": ["social"] + }, + "target": "profiles", + "type": "integer" +} +---- + +____ + +Unomi defines a built-in scope (called `systemscope`) that clients can use to share data across scopes. +____ + +=== Events + +Users' actions are conveyed from clients to the context server using events. Of course, the required information depends on what is collected and users' interactions with the observed systems but events minimally provide a type, a scope and source and target items. Additionally, events are timestamped. Conceptually, an event can be seen as a sentence, the event's type being the verb, the source the subject and the target the object. + +_Event structure:_ + +[source,json] +---- +{ + "eventType": <type of the event>, + "scope": <scope of the event>, + "source": <Item>, + "target": <Item>, + "properties": <optional properties> +} +---- + +Source and target can be any Unomi item but are not limited to them. In particular, as long as they can be described using properties and Unomiâs type mechanism and can be processed either natively or via extension plugins, source and target can represent just about anything. Events can also be triggered as part of Unomiâs internal processes for example when a rule is triggered. + +Events are sent to Unomi from client applications using the JSON format and a typical page view event from a web site could look something like the following: + +_Example page view event:_ + +[source,json] +---- +{ + "eventType": "view", + "scope": "ACMESPACE", + "source": { + "itemType": "site", + "scope": "ACMESPACE", + "itemId": "c4761bbf-d85d-432b-8a94-37e866410375" + }, + "target": { + "itemType": "page", + "scope": "ACMESPACE", + "itemId": "b6acc7b3-6b9d-4a9f-af98-54800ec13a71", + "properties": { + "pageInfo": { + "pageID": "b6acc7b3-6b9d-4a9f-af98-54800ec13a71", + "pageName": "Home", + "pagePath": "/sites/ACMESPACE/home", + "destinationURL": "http://localhost:8080/sites/ACMESPACE/home.html";, + "referringURL": "http://localhost:8080/";, + "language": "en" + }, + "category": {}, + "attributes": {} + } + } +} +---- + +=== Profiles + +By processing events, Unomi progressively builds a picture of who the user is and how they behave. This knowledge is embedded in `Profile` object. A profile is an `Item` with any number of properties and optional segments and scores. Unomi provides default properties to cover common data (name, last name, age, email, etc.) as well as default segments to categorize users. Unomi users are, however, free and even encouraged to create additional properties and segments to better suit their needs. + +Contrary to other Unomi items, profiles are not part of a scope since we want to be able to track the associated user across applications. For this reason, data collected for a given profile in a specific scope is still available to any scoped item that accesses the profile information. + +It is interesting to note that there is not necessarily a one to one mapping between users and profiles as users can be captured across applications and different observation contexts. As identifying information might not be available in all contexts in which data is collected, resolving profiles to a single physical user can become complex because physical users are not observed directly. Rather, their portrait is progressively patched together and made clearer as Unomi captures more and more traces of their actions. Unomi will merge related profiles as soon as collected data permits positive association between distinct profiles, usually as a result of the user performing some identifying action in a context where the user hadnât already been positively identified. + +=== Sessions + +A session represents a time-bounded interaction between a user (via their associated profile) and a Unomi-enabled application. A session represents the sequence of actions the user performed during its duration. For this reason, events are associated with the session during which they occurred. In the context of web applications, sessions are usually linked to HTTP sessions. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/667b57c3/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 new file mode 100644 index 0000000..d6103e8 --- /dev/null +++ b/manual/src/archives/1.3/asciidoc/configuration.adoc @@ -0,0 +1,397 @@ +// +// 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. +// +=== Configuration + +==== Changing the default configuration + +If you want to change the default configuration, you can perform any modification you want in the $MY_KARAF_HOME/etc directory. + +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 : + +[source] +---- +contextserver.publicAddress=https://localhost:9443 +contextserver.internalAddress=http://127.0.0.1:8181 +---- + +If you need to specify an Elasticsearch cluster name, or a host and port that are different than the default, +it is recommended to do this BEFORE you start the server for the first time, or you will loose all the data +you have stored previously. + +To change these settings, you will need to modify a file called + +[source] +---- +$MY_KARAF_HOME/etc/org.apache.unomi.persistence.elasticsearch.cfg +---- + +with the following contents: + +[source] +---- +cluster.name=contextElasticSearch +# The elasticSearchAddresses may be a comma seperated list of host names and ports such as +# hostA:9300,hostB:9300 +# Note: the port number must be repeated for each host. +elasticSearchAddresses=localhost:9300 +index.name=context +---- + +==== Secured events configuration + +Unomi secures some events by default. You can find the default configuration in the following file (created after the +first server startup): + +[source] +---- +$MY_KARAF_HOME/etc/org.apache.unomi.thirdparty.cfg +---- + +Ususally, login events, which operate on profiles and do merge on protected properties, must be secured. For each +trusted third party server, you need to add these 3 lines : + +[source] +---- +thirdparty.provider1.key=secret-key +thirdparty.provider1.ipAddresses=127.0.0.1,::1 +thirdparty.provider1.allowedEvents=login,updateProperties +---- + +The events set in allowedEvents will be secured and will only be accepted if the call comes from the specified IP +address, and if the secret-key is passed in the X-Unomi-Peer header. + +==== Installing the MaxMind GeoIPLite2 IP lookup database + +The Context Server requires an IP database in order to resolve IP addresses to user location. +The GeoLite2 database can be downloaded from MaxMind here : +http://dev.maxmind.com/geoip/geoip2/geolite2/[http://dev.maxmind.com/geoip/geoip2/geolite2/] + +Simply download the GeoLite2-City.mmdb file into the "etc" directory. + +==== Installing Geonames database + +Context server includes a geocoding service based on the geonames database ( http://www.geonames.org/[http://www.geonames.org/] ). It can be +used to create conditions on countries or cities. + +In order to use it, you need to install the Geonames database into . Get the "allCountries.zip" database from here : +http://download.geonames.org/export/dump/[http://download.geonames.org/export/dump/] + +Download it and put it in the "etc" directory, without unzipping it. +Edit $MY_KARAF_HOME/etc/org.apache.unomi.geonames.cfg and set request.geonamesDatabase.forceImport to true, import should start right away. +Otherwise, import should start at the next startup. Import runs in background, but can take about 15 minutes. +At the end, you should have about 4 million entries in the geonames index. + +==== REST API Security + +The Context Server REST API is protected using JAAS authentication and using Basic or Digest HTTP auth. +By default, the login/password for the REST API full administrative access is "karaf/karaf". + +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] +---- + org.osgi.service.http.secure.enabled = true + org.ops4j.pax.web.ssl.keystore=${karaf.etc}/keystore + org.ops4j.pax.web.ssl.password=changeme + org.ops4j.pax.web.ssl.keypassword=changeme + org.osgi.service.http.port.secure=9443 +---- + +You should now have SSL setup on Karaf with your certificate, and you can test it by trying to access it on port 9443. + +. Changing the default Karaf password can be done by modifying the etc/users.properties file + +==== Automatic profile merging + +The context server is capable of merging profiles based on a common property value. In order to use this, you must +add the MergeProfileOnPropertyAction to a rule (such as a login rule for example), and configure it with the name + of the property that will be used to identify the profiles to be merged. An example could be the "email" property, + meaning that if two (or more) profiles are found to have the same value for the "email" property they will be merged + by this action. + +Upon merge, the old profiles are marked with a "mergedWith" property that will be used on next profile access to delete +the original profile and replace it with the merged profile (aka "master" profile). Once this is done, all cookie tracking +will use the merged profile. + +To test, simply configure the action in the "login" or "facebookLogin" rules and set it up on the "email" property. +Upon sending one of the events, all matching profiles will be merged. + +==== Securing a production environment + +Before going live with a project, you should _absolutely_ read the following section that will help you setup a proper +secure environment for running your context server. + +Step 1: Install and configure a firewall + +You should setup a firewall around your cluster of context servers and/or Elasticsearch nodes. If you have an +application-level firewall you should only allow the following connections open to the whole world : + +* http://localhost:8181/context.js[http://localhost:8181/context.js] +* http://localhost:8181/eventcollector[http://localhost:8181/eventcollector] + +All other ports should not be accessible to the world. + +For your Context Server client applications (such as the Jahia CMS), you will need to make the following ports +accessible : + +[source] +---- +8181 (Context Server HTTP port) +9443 (Context Server HTTPS port) +---- + +The context server actually requires HTTP Basic Auth for access to the Context Server administration REST API, so it is +highly recommended that you design your client applications to use the HTTPS port for accessing the REST API. + +The user accounts to access the REST API are actually routed through Karaf's JAAS support, which you may find the +documentation for here : + +* http://karaf.apache.org/manual/latest/users-guide/security.html[http://karaf.apache.org/manual/latest/users-guide/security.html] + +The default username/password is + +[source] +---- +karaf/karaf +---- + +You should really change this default username/password as soon as possible. To do so, simply modify the following +file : + +[source] +---- +$MY_KARAF_HOME/etc/users.properties +---- + +For your context servers, and for any standalone Elasticsearch nodes you will need to open the following ports for proper +node-to-node communication : 9200 (Elasticsearch REST API), 9300 (Elasticsearch TCP transport) + +Of course any ports listed here are the default ports configured in each server, you may adjust them if needed. + +Step 2 : Follow industry recommended best practices for securing Elasticsearch + +You may find more valuable recommendations here : + +* https://www.elastic.co/blog/found-elasticsearch-security[https://www.elastic.co/blog/found-elasticsearch-security] +* https://www.elastic.co/blog/scripting-security[https://www.elastic.co/blog/scripting-security] + +Step 4 : Setup a proxy in front of the context server + +As an alternative to an application-level firewall, you could also route all traffic to the context server through +a proxy, and use it to filter any communication. + +==== Integrating with an Apache HTTP web server + +If you want to setup an Apache HTTP web server in from of Apache Unomi, here is an example configuration using +mod_proxy. + +In your Unomi package directory, in /etc/org.apache.unomi.cluster.cfg for unomi.apache.org + +contextserver.publicAddress=https://unomi.apache.org/ + contextserver.internalAddress=http://192.168.1.1:8181 + +and you will also need to change the contextserver.domain in the /etc/org.apache.unomi.web.cfg file + +contextserver.domain=apache.org + +Main virtual host config: + +[source] +---- +<VirtualHost *:80> + Include /var/www/vhosts/unomi.apache.org/conf/common.conf +</VirtualHost> + +<IfModule mod_ssl.c> + <VirtualHost *:443> + Include /var/www/vhosts/unomi.apache.org/conf/common.conf + + SSLEngine on + + SSLCertificateFile /var/www/vhosts/unomi.apache.org/conf/ssl/24d5b9691e96eafa.crt + SSLCertificateKeyFile /var/www/vhosts/unomi.apache.org/conf/ssl/apache.org.key + SSLCertificateChainFile /var/www/vhosts/unomi.apache.org/conf/ssl/gd_bundle-g2-g1.crt + + <FilesMatch "\.(cgi|shtml|phtml|php)$"> + SSLOptions +StdEnvVars + </FilesMatch> + <Directory /usr/lib/cgi-bin> + SSLOptions +StdEnvVars + </Directory> + BrowserMatch "MSIE [2-6]" \ + nokeepalive ssl-unclean-shutdown \ + downgrade-1.0 force-response-1.0 + BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown + + </VirtualHost> +</IfModule> +---- + +common.conf: + +[source] +---- +ServerName unomi.apache.org +ServerAdmin [email protected] + +DocumentRoot /var/www/vhosts/unomi.apache.org/html +CustomLog /var/log/apache2/access-unomi.apache.org.log combined +<Directory /> + Options FollowSymLinks + AllowOverride None +</Directory> +<Directory /var/www/vhosts/unomi.apache.org/html> + Options FollowSymLinks MultiViews + AllowOverride None + Order allow,deny + allow from all +</Directory> +<Location /cxs> + Order deny,allow + deny from all + allow from 88.198.26.2 + allow from www.apache.org +</Location> + +RewriteEngine On +RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK) +RewriteRule .* - [F] +ProxyPreserveHost On +ProxyPass /server-status ! +ProxyPass /robots.txt ! + +RewriteCond %{HTTP_USER_AGENT} Googlebot [OR] +RewriteCond %{HTTP_USER_AGENT} msnbot [OR] +RewriteCond %{HTTP_USER_AGENT} Slurp +RewriteRule ^.* - [F,L] + +ProxyPass / http://localhost:8181/ connectiontimeout=20 timeout=300 ttl=120 +ProxyPassReverse / http://localhost:8181/ +---- + +==== Changing the default tracking location + +When performing localhost requests to Apache Unomi, a default location will be used to insert values into the session +to make the location-based personalization still work. You can find the default location settings in the file : + +[source] +---- +org.apache.unomi.plugins.request.cfg +---- + +that contains the following default settings: + +[source] +---- +# The following settings represent the default position that is used for localhost requests +defaultSessionCountryCode=CH +defaultSessionCountryName=Switzerland +defaultSessionCity=Geneva +defaultSessionAdminSubDiv1=2660645 +defaultSessionAdminSubDiv2=6458783 +defaultSessionIsp=Cablecom +defaultLatitude=46.1884341 +defaultLongitude=6.1282508 +---- + +You might want to change these for testing or for demonstration purposes. + +==== Apache Karaf SSH Console + +The Apache Karaf SSH console is available inside Apache Unomi, but the port has been changed from the default value of +8101 to 8102 to avoid conflicts with other Karaf-based products. So to connect to the SSH console you should use: + +[source] +---- +ssh -p 8102 karaf@localhost +---- + +or the user/password you have setup to protect the system if you have changed it. + +==== ElasticSearch X-Pack Support + +It is now possible to use X-Pack to connect to ElasticSearch. However, for licensing reasons this is not provided out +of the box. Here is the procedure to install X-Pack with Apache Unomi: + +=== Important ! + +Do not start Unomi directly with unomi:start, perform the following steps below first ! + +=== Installation steps + +. Create a directory for all the JARs that you will download, we will call it XPACK_JARS_DIRECTORY +. Download https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/5.6.3/x-pack-transport-5.6.3.jar[https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/5.6.3/x-pack-transport-5.6.3.jar] to XPACK_JARS_DIRECTORY +. Download https://artifacts.elastic.co/maven/org/elasticsearch/plugin/x-pack-api/5.6.3/x-pack-api-5.6.3.jar[https://artifacts.elastic.co/maven/org/elasticsearch/plugin/x-pack-api/5.6.3/x-pack-api-5.6.3.jar] to XPACK_JARS_DIRECTORY +. Download http://central.maven.org/maven2/com/unboundid/unboundid-ldapsdk/3.2.0/unboundid-ldapsdk-3.2.0.jar[http://central.maven.org/maven2/com/unboundid/unboundid-ldapsdk/3.2.0/unboundid-ldapsdk-3.2.0.jar] to XPACK_JARS_DIRECTORY +. Download http://central.maven.org/maven2/org/bouncycastle/bcpkix-jdk15on/1.55/bcpkix-jdk15on-1.55.jar[http://central.maven.org/maven2/org/bouncycastle/bcpkix-jdk15on/1.55/bcpkix-jdk15on-1.55.jar] to XPACK_JARS_DIRECTORY +. Download http://central.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.55/bcprov-jdk15on-1.55.jar[http://central.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.55/bcprov-jdk15on-1.55.jar] to XPACK_JARS_DIRECTORY +. Download http://central.maven.org/maven2/com/sun/mail/javax.mail/1.5.3/javax.mail-1.5.3.jar[http://central.maven.org/maven2/com/sun/mail/javax.mail/1.5.3/javax.mail-1.5.3.jar] to XPACK_JARS_DIRECTORY +. + +Edit etc/org.apache.unomi.persistence.elasticsearch.cfg to add the following settings: + +[source] +---- +transportClientClassName=org.elasticsearch.xpack.client.PreBuiltXPackTransportClient +transportClientJarDirectory=XPACK_JARS_DIRECTORY +transportClientProperties=xpack.security.user=elastic:changeme +---- + +You can setup more properties (for example for SSL/TLS support) by seperating the properties with commas, +as in the following example: + +[source] +---- +transportClientProperties=xpack.security.user=elastic:changeme,xpack.ssl.key=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.key,xpack.ssl.certificate=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.crt,xpack.ssl.certificate_authorities=/home/user/elasticsearch-5.6.3/config/x-pack/ca/ca.crt,xpack.security.transport.ssl.enabled=true +---- + +. + +Launch Karaf and launch unomi using the command from the shell : + +[source] +---- +unomi:start +---- + +Alternatively you could edit the configuration directly from the Karaf shell using the following commands: + +[source] +---- +config:edit org.apache.unomi.persistence.elasticsearch +config:property-set transportClientClassName org.elasticsearch.xpack.client.PreBuiltXPackTransportClient +config:property-set transportClientJarDirectory XPACK_JARS_DIRECTORY +config:property-set transportClientProperties xpack.security.user=elastic:changeme +config:update +unomi:start +---- + +You can setup more properties (for example for SSL/TLS support) by seperating the properties with commas, +as in the following example: + +[source] +---- +config:property-set transportClientProperties xpack.security.user=elastic:changeme,xpack.ssl.key=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.key,xpack.ssl.certificate=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.crt,xpack.ssl.certificate_authorities=/home/user/elasticsearch-5.6.3/config/x-pack/ca/ca.crt,xpack.security.transport.ssl.enabled=true +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/667b57c3/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 new file mode 100644 index 0000000..ee3551b --- /dev/null +++ b/manual/src/archives/1.3/asciidoc/connectors/connectors.adoc @@ -0,0 +1,22 @@ +// +// 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. +// +=== Connectors + +Apache Unomi provides the following connectors: + +* link:salesforce-connectors.html[Salesforce CRM connectors] + +==== 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 http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/667b57c3/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 new file mode 100644 index 0000000..23c0a22 --- /dev/null +++ b/manual/src/archives/1.3/asciidoc/connectors/salesforce-connector.adoc @@ -0,0 +1,224 @@ +// +// 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 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: + +[source] +---- +https://developer.salesforce.com/signup +---- + +. + +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: + +[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-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: + +[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 link:concepts.html[Concepts] and the link:getting-started.html[Getting Started] pages. + +==== Upgrading the Salesforce connectors + +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-connectors +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-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: + +[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->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-connectors +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
