Adding first set of apex-pdp document changes

Adding document changes for auth, context, core, model, services & the
main apex-pdp module.

Change-Id: Id0d026baa258f1dc6998978f9911f3c4a73b5b3b
Issue-ID: POLICY-867
Signed-off-by: ramverma <ram.krishna.verma@ericsson.com>

11 files changed, 715 insertions, 0 deletions

diff --git a/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc b/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc
new file mode 100644
index 000000000..973564df3
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc
@@ -0,0 +1,62 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== Application: Convert a Policy Model to CLI Editor Commands
+
+**Status: Experimental**
+
+This application takes a policy model (JSON or XML encoded) and generates commands for the APEX CLI Editor.
+This effectively reverses a policy specification realized with the CLI Editor.
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexApps.sh model-2-cli [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexApps.bat model-2-cli [args]
+----
+|====================
+
+The option `-h` provides a help screen.
+
+[source%nowrap,sh]
+----
+usage: gen-model2cli
+ -h,--help                 prints this help and usage screen
+ -m,--model <MODEL-FILE>   set the input policy model file
+ -sv,--skip-validation     switch of validation of the input file
+ -v,--version              prints the application version
+----
+
+For instance, running the tool with the __Sample Domain__ policy model as:
+[source%nowrap,sh]
+----
+apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli
+----
+
+will produce the following status messages:
+
+[source%nowrap,sh]
+----
+gen-model2cli: starting CLI generator
+ --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
+----
+
+and then run the generator application producing all CLI Editor commands and printing them to standard out.
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc b/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc
new file mode 100644
index 000000000..bd31bedf9
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc
@@ -0,0 +1,99 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== Application: Create Event Templates
+
+**Status: Experimental**
+
+This application takes a policy model (JSON or XML encoded) and generates templates for events in JSON format.
+This can help when a policy defines rather complex trigger or action events or complex events between states.
+The application can produce events for the types: stimuli (policy trigger events), internal (events between policy states), and response (action events).
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexApps.sh tpl-event-json [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexApps.bat tpl-event-json [args]
+----
+|====================
+
+The option `-h` provides a help screen.
+
+[source%nowrap,sh]
+----
+usage: gen-model2event
+ -h,--help                 prints this help and usage screen
+ -m,--model <MODEL-FILE>   set the input policy model file
+ -t,--type <TYPE>          set the event type for generation, one of:
+                           stimuli (trigger events), response (action
+                           events), internal (events between states)
+ -v,--version              prints the application version
+----
+
+The created templates are not valid events, instead they use some markup for values one will need to change to actual values.
+For instance, running the tool with the __Sample Domain__ policy model as:
+[source%nowrap,sh]
+----
+apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli
+----
+
+will produce the following status messages:
+
+[source%nowrap,sh]
+----
+gen-model2event: starting Event generator
+ --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
+ --> type: stimuli
+----
+
+and then run the generator application producing two event templates.
+The first template is called `Event0000`.
+
+[source%nowrap,json]
+----
+{
+        "name" : "Event0000",
+        "nameSpace" : "org.onap.policy.apex.sample.events",
+        "version" : "0.0.1",
+        "source" : "Outside",
+        "target" : "Match",
+        "TestTemperature" : ###double: 0.0###,
+        "TestTimestamp" : ###long: 0###,
+        "TestMatchCase" : ###integer: 0###,
+        "TestSlogan" : "###string###"
+}
+----
+The values for the keys are marked with `###` and the expected type of the value.
+To create an actual stimuli event, all these markers need to be change to actual values, for instance:
+[source%nowrap,json]
+----
+{
+        "name" : "Event0000",
+        "nameSpace" : "org.onap.policy.apex.sample.events",
+        "version" : "0.0.1",
+        "source" : "Outside",
+        "target" : "Match",
+        "TestTemperature" : 25,
+        "TestTimestamp" : 123456789123456789,
+        "TestMatchCase" : 1,
+        "TestSlogan" : "Testing the Match Case with Temperature 25"
+}
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc b/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc
new file mode 100644
index 000000000..f11bdf277
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc
@@ -0,0 +1,45 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== Application: Websocket Clients (Echo and Console)
+
+**Status: Production**
+
+The application launcher also provides a Websocket echo client and a Websocket console client.
+The echo client connects to APEX and prints all events it receives from APEX.
+The console client connects to APEX, reads input from the command line, and sends this input as events to APEX.
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexApps.sh ws-echo [args]
+# $APEX_HOME/bin/apexApps.sh ws-console [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexApps.bat ws-echo [args]
+> %APEX_HOME%\bin\apexApps.bat ws-console [args]
+----
+|====================
+
+The arguments are the same for both applications:
+
+- `-p` defines the Websocket port to connect to (defaults to `8887`)
+- `-s` defines the host on which a Websocket server is running (defaults to `localhost`)
+
+A discussion on how to use these two applications to build an APEX system is detailed HowTo-Websockets.
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc b/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc
new file mode 100644
index 000000000..4222b436a
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc
@@ -0,0 +1,80 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== The APEX Application Launcher
+The standard applications (Engine, CLI Editor, REST Editor) come with dedicated start scripts.
+For all other APEX applications, we provide an application launcher.
+
+On UNIX and Cygwin systems use:
+
+- apexApps.sh` - simply starts the application launcher
+
+On Windows systems use:
+
+- `apexApps.bat` - simply starts the application launcher
+
+
+Summary of alternatives to start the APEX application launcher:
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexApps.sh [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexApps.bat [args]
+----
+|====================
+
+The option `-h` provides a help screen with all launcher command line arguments.
+
+[source%nowrap,sh]
+----
+apexApps.sh - runs APEX applications
+
+       Usage:  apexApps.sh [options] | [<application> [<application options>]]
+
+       Options
+         -d <app>    - describes an application
+         -l          - lists all applications supported by this script
+         -h          - this help screen
+----
+
+Using `-l` lists all known application the launcher can start.
+
+[source%nowrap,sh]
+----
+apexApps.sh: supported applications:
+ --> ws-echo engine eng-monitoring full-client eng-deployment tpl-event-json model-2-cli rest-editor cli-editor ws-console
+----
+
+Using the `-d <name>` option describes the named application, for instance for the `ws-console`:
+
+[source%nowrap,sh]
+----
+apexApps.sh: application 'ws-console'
+ --> a simple console sending events to APEX, connect to APEX consumer port
+----
+
+Launching an application is done by calling the script with only the application name and any CLI arguments for the application.
+For instance, starting the `ws-echo` application with port `8888`:
+[source%nowrap,sh]
+----
+apexApps.sh ws-echo -p 8888
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc b/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc
new file mode 100644
index 000000000..e677079f2
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc
@@ -0,0 +1,82 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== The APEX CLI Editor
+The CLI Editor allows to define policies from the command line.
+The application uses a simple language and supports all elements of an APEX policy.
+It can be used in to different ways:
+
+- non-interactive, specifying a file with the commands to create a policy
+- interactive, using the editors CLI to create a policy
+
+When a policy is fully specified, the editor will generate the APEX core policy specification in JSON.
+This core specification is called the policy model in the APEX engine and can be used directly with the APEX engine.
+
+On UNIX and Cygwin systems use:
+
+- `apexCLIEditor.sh` - simply starts the CLI editor, arguments to the script determine the mode of the editor
+- `apexApps.sh cli-editor` - simply starts the CLI editor, arguments to the script determine the mode of the editor
+
+On Windows systems use:
+
+- `apexCLIEditor.bat` - simply starts the CLI editor, arguments to the script determine the mode of the editor
+- `apexApps.bat cli-editor` - simply starts the CLI editor, arguments to the script determine the mode of the editor
+
+
+Summary of alternatives to start the APEX CLI Editor:
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexCLIEditor.sh.sh [args]
+# $APEX_HOME/bin/apexApps.sh cli-editor [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexCLIEditor.bat [args]
+> %APEX_HOME%\bin\apexApps.bat cli-editor [args]
+----
+|====================
+
+The option `-h` provides a help screen with all command line arguments.
+
+[source%nowrap,sh]
+----
+usage: org.onap.policy.apex.auth.clieditor.ApexCLIEditorMain [options...]
+options
+
+ -a,--model-props-file <MODEL_PROPS_FILE>       name of the apex model properties file to use
+ -c,--command-file <COMMAND_FILE>               name of a file containing editor commands to run into the editor
+ -h,--help                                      outputs the usage of this command
+ -i,--input-model-file <INPUT_MODEL_FILE>       name of a file that contains an input model for the editor
+ -if,--ignore-failures <IGNORE_FAILURES_FLAG>   true or false, ignore failures of commands in command files and continue
+                                                executing the command file
+ -l,--log-file <LOG_FILE>                       name of a file that will contain command logs from the editor, will log
+                                                to standard output if not specified or suppressed with "-nl" flag
+ -m,--metadata-file <CMD_METADATA_FILE>         name of the command metadata file to use
+ -nl,--no-log                                   if specified, no logging or output of commands to standard output or log
+                                                file is carried out
+ -nm,--no-model-output                          if specified, no output of a model to standard output or model output
+                                                file is carried out, the user can use the "save" command in a script to
+                                                save a model
+ -o,--output-model-file <OUTPUT_MODEL_FILE>     name of a file that will contain the output model for the editor, will
+                                                output model to standard output if not specified or suppressed with
+                                                "-nm" flag
+ -wd,--working-directory <WORKING_DIRECTORY>    the working directory that is the root for the CLI editor and is the
+                                                root from which to look for included macro files
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc b/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc
new file mode 100644
index 000000000..52836a783
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc
@@ -0,0 +1,50 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== The APEX Deployment Client
+The standard way to use the APEX Deployment Client is via an installation of the __war__ file on a webserver.
+However, the Deployment Client can also be started via command line.
+This will start a Grizzly webserver with the __war__ deployed.
+Access to the Deployment Client is then via the provided URL 
+
+On UNIX and Cygwin systems use:
+
+- `apexApps.sh eng-deployment` - simply starts the webserver with the Deployment Client
+
+On Windows systems use:
+
+- `apexApps.bat eng-deployment` - simply starts the webserver with the Deployment Client
+
+
+The option `-h` provides a help screen with all command line arguments.
+
+[source%nowrap,sh]
+----
+usage: org.onap.policy.apex.services.client.deployment.rest.ApexDeploymentRestMain [options...]
+-h,--help                         outputs the usage of this command
+-p,--port <PORT>                  port to use for the Apex Services REST calls
+-t,--time-to-live <TIME_TO_LIVE>  the amount of time in seconds that the server will run for before terminating
+----
+
+If the Deployment Client is started without any arguments the final messages will look similar to this:
+
+[source%nowrap,sh]
+----
+INFO: [HttpServer] Started.
+Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
+----
+
+The last line states the URL on which the Deployment Client can be accessed.
+The example above stated `http://localhost:18989/apexservices`.
+In a web browser use the URL `http://localhost:18989`.
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc b/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc
new file mode 100644
index 000000000..960546d06
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc
@@ -0,0 +1,50 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== The APEX Monitoring Client
+The standard way to use the APEX Monitoring Client is via an installation of the __war__ file on a webserver.
+However, the Monitoring Client can also be started via command line.
+This will start a Grizzly webserver with the __war__ deployed.
+Access to the Monitoring Client is then via the provided URL 
+
+On UNIX and Cygwin systems use:
+
+- `apexApps.sh eng-monitoring` - simply starts the webserver with the Monitoring Client
+
+On Windows systems use:
+
+- `apexApps.bat eng-monitoring` - simply starts the webserver with the Monitoring Client
+
+
+The option `-h` provides a help screen with all command line arguments.
+
+[source%nowrap,sh]
+----
+usage: org.onap.policy.apex.services.client.monitoring.rest.ApexMonitoringRestMain [options...]
+-h,--help                         outputs the usage of this command
+-p,--port <PORT>                  port to use for the Apex Services REST calls
+-t,--time-to-live <TIME_TO_LIVE>  the amount of time in seconds that the server will run for before terminating
+----
+
+If the Monitoring Client is started without any arguments the final messages will look similar to this:
+
+[source%nowrap,sh]
+----
+INFO: [HttpServer] Started.
+Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
+----
+
+The last line states the URL on which the Monitoring Client can be accessed.
+The example above stated `http://localhost:18989/apexservices`.
+In a web browser use the URL `http://localhost:18989`.
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/engine.adoc b/src/site-docs/adoc/fragments/howto-apex/engine.adoc
new file mode 100644
index 000000000..819c2ca87
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/engine.adoc
@@ -0,0 +1,71 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== The APEX Engine
+The APEX engine can be started in different ways, depending your requirements.
+All scripts are located in the APEX __bin__ directory
+
+On UNIX and Cygwin systems use:
+
+- `apexEngine.sh` - this script will
+  ** Test if `$APEX_USER` is set and if the user exists, terminate with an error otherwise
+  ** Test if `$APEX_HOME` is set. If not set, it will use the default setting as `/opt/ericsson/apex/apex`.
+     Then the set directory is tested to exist, the script will terminate if not.
+  ** When all tests are passed successfully, the script will call `apexApps.sh` with arguments to start the APEX engine.
+- `apexApps.sh engine` - this is the general APEX application launcher, which will
+  ** Start the engine with the argument `engine`
+  ** Test if `$APEX_HOME` is set and points to an existing directory. If not set or directory does not exist, script terminates.
+  ** Not test for any settings of `$APEX_USER`.
+
+On Windows systems use `apexEngine.bat` and `apexApps.bat engine` respectively.
+Note: none of the windows batch files will test for `%APEX_USER%`.
+
+Summary of alternatives to start the APEX Engine:
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexEngine.sh [args]
+# $APEX_HOME/bin/apexApps.sh engine [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexEngine.bat [args]
+> %APEX_HOME%\bin\apexApps.bat engine [args]
+----
+|====================
+
+
+The APEX engine comes with a few CLI arguments for setting configuration and policy model.
+The configuration file is always required.
+The policy model file is only required if no model file is specified in the configuration, or if the specified model file should be over written.
+The option `-h` prints a help screen.
+
+[source%nowrap,sh]
+----
+usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
+options
+ -c,--config-file <CONFIG_FILE>   the full path to the configuration file to use,
+                                  the configuration file must be a Json
+                                  file containing the Apex configuration parameters
+ -h,--help                        outputs the usage of this command
+ -m,--model-file <MODEL_FILE>     the full path to the model file to use,
+                                  if set it overrides the model file set in the
+                                  configuration file
+ -v,--version                     outputs the version of Apex
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/full-client.adoc b/src/site-docs/adoc/fragments/howto-apex/full-client.adoc
new file mode 100644
index 000000000..97a18393b
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/full-client.adoc
@@ -0,0 +1,51 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== The APEX Full Client
+The APEX Full Client combines the REST Editor, the Monitoring Client, and the Deployment Client into a single application.
+The standard way to use the APEX Full Client is via an installation of the __war__ file on a webserver.
+However, the Full Client can also be started via command line.
+This will start a Grizzly webserver with the __war__ deployed.
+Access to the Full Client is then via the provided URL 
+
+On UNIX and Cygwin systems use:
+
+- `apexApps.sh full-client` - simply starts the webserver with the Full Client
+
+On Windows systems use:
+
+- `apexApps.bat full-client` - simply starts the webserver with the Full Client
+
+
+The option `-h` provides a help screen with all command line arguments.
+
+[source%nowrap,sh]
+----
+usage: org.onap.policy.apex.services.client.full.rest.ApexServicesRestMain [options...]
+-h,--help                         outputs the usage of this command
+-p,--port <PORT>                  port to use for the Apex Services REST calls
+-t,--time-to-live <TIME_TO_LIVE>  the amount of time in seconds that the server will run for before terminating
+----
+
+If the Full Client is started without any arguments the final messages will look similar to this:
+
+[source%nowrap,sh]
+----
+INFO: [HttpServer] Started.
+Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
+----
+
+The last line states the URL on which the Monitoring Client can be accessed.
+The example above stated `http://localhost:18989/apexservices`.
+In a web browser use the URL `http://localhost:18989`.
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/introduction.adoc b/src/site-docs/adoc/fragments/howto-apex/introduction.adoc
new file mode 100644
index 000000000..faa2f4949
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/introduction.adoc
@@ -0,0 +1,51 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== Introduction to APEX Engine and Applications
+The core of APEX is the APEX Engine, also known as the APEX Policy Engine.
+Beside this engine, an APEX system comes with a few applications intended to help with policy authoring, deployment, and execution.
+
+The engine itself and most applications are started from the command line with command line arguments.
+This is called a Command Line Interface (CLI).
+Some applications require an installation on a webserver, as for instance the REST Editor.
+Those applications can be accessed via a web browser.
+
+Starting with APEX version 0.5.6, we also provide plugins for Eclipse realizing a policy development environment.
+Those plugins support the main APEX policy language.
+Other, higher-level, policy languages will be added in future versions along with their Eclipse plugins.
+Furthermore, we are planning to provide a backend supporting the Language Server Protocol (LSP).
+This backend, run as a server, will allow to join any editor or IDE that is LSP-enabled to benefit from the APEX policy languages.
+
+Last not least, one can use the available APEX APIs and applications to develop other applications as required.
+This includes policy languages (and associated parsers and compilers / interpreters), GUIs to access APEX or to define policies, clients to connect to APEX, etc.
+Separate documentation will be available in APEX releases addressing this type of applications.
+
+For this documentation, we assume an installation of APEX as a full system (i.e. not minimal) of version 0.5.6 or higher.
+
+== CLI on Unix, Windows, and Cygwin
+A note on APEX CLI applications: all applications and the engine itself have been deployed and tested on different operating systems: Red Hat, Ubuntu, Debian, Mac OSX, Windows, Cygwin.
+Each operating system comes with its own way of configuring and executing Java.
+The main items here are:
+
+- For UNIX systems (RHL, Ubuntu, Debian, Mac OSX), the provided bash scripts work as expected
+  with absolute paths (e.g. `/opt/ericsson/apex/apex-{release-version}/examples`),
+  indirect and linked paths (e.g. `../apex/apex`),
+  and path substitutions using environment settings (e.g. `$APEX_HOME/bin/`)
+- For Windows systems, the provided batch files (`.bat`) work as expected with 
+  with absolute paths (e.g. `C:\apex\apex-{release-version}\examples`),
+  and path substitutions using environment settings (e.g. `%APEX_HOME%\bin\`)
+- For Cygwin system we assume a standard Cygwin installation with standard tools (mainly bash) using a Windows Java installation.
+  This means that the bash scripts can be used as in UNIX, however any argument pointing to files and directories need to use either a DOS path (e.g. `C:\apex\apex-{release-version}\examples\config\...`)
+  or the command `cygpath` with a mixed option.
+  The reason for that is: Cygwin executes Java using UNIX paths but then runs Java as a DOS/WINDOWS process, which requires DOS paths for file access.
+
diff --git a/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc b/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc
new file mode 100644
index 000000000..3be6f9f94
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc
@@ -0,0 +1,74 @@
+//
+// ============LICENSE_START=======================================================
+//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+// 
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== The APEX REST Editor
+The standard way to use the APEX REST Editor is via an installation of the __war__ file on a webserver.
+However, the REST editor can also be started via command line.
+This will start a Grizzly webserver with the __war__ deployed.
+Access to the REST Editor is then via the provided URL 
+
+On UNIX and Cygwin systems use:
+
+- `apexRESTEditor.sh` - simply starts the webserver with the REST editor
+- `apexApps.sh rest-editor` - simply starts the webserver with the REST editor
+
+On Windows systems use:
+
+- `apexRESTEditor.bat` - simply starts the webserver with the REST editor
+- `apexApps.bat rest-editor` - simply starts the webserver with the REST editor
+
+
+Summary of alternatives to start the APEX REST Editor:
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexRESTEditor.sh.sh [args]
+# $APEX_HOME/bin/apexApps.sh rest-editor [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexRESTEditor.bat [args]
+> %APEX_HOME%\bin\apexApps.bat rest-editor [args]
+----
+|====================
+
+The option `-h` provides a help screen with all command line arguments.
+
+[source%nowrap,sh]
+----
+usage: org.onap.policy.apex.auth.rest.ApexEditorMain [options...]
+-h,--help                        outputs the usage of this command
+-l,--listen <ADDRESS>            the IP address to listen on.  Default value is 0.0.0.0 to listen on all available
+                                 addresses. Use value 'localhost' to restrict access to the local machine only.
+-p,--port <PORT>                 port to use for the Apex RESTful editor REST calls.
+-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating. Default
+                                 value is -1 to run indefinitely.
+----
+
+If the REST Editor is started without any arguments the final messages will look similar to this:
+
+[source%nowrap,sh]
+----
+INFO: [HttpServer] Started.
+Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://0.0.0.0:18988/apex/, TTL=-1sec], State=RUNNING) started at http://0.0.0.0:18988/apex/
+----
+
+The last line states the URL on which the REST Editor can be accessed.
+The example above stated `http://0.0.0.0:18988/apex/`.
+In a web browser use the URL `http://localhost:18988` and the REST Editor will start.
+