src/site-docs/adoc/fragments/install-guide/verify.adoc - onap/policy/apex-pdp - Gitiles

 //
 // ============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)
 //

 == Verify the APEX Installation
 When APEX is installed and all settings are realized, the installation can be verified.

 === Verify a Minimal Installation
 The minimal installation does not come with any configuration or policy model.
 It is therefore not possible to test all APEX features, or an engine running with policies.

 However, one can verify that the engine starts up to the point where it tries to load a configuration.

 On Unix (or Cygwin) start the engine using `$APEX_HOME/bin/apexEngine.sh`.
 The engine will fail to fully start.
 However, if the output looks similar to the following line, the APEX installation is realized.

 [source%nowrap,sh,numbered]
 ----
 Starting Apex service with parameters [] . . .
 start of Apex service failed: Apex configuration file was not specified as an argument
 2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed:
 ----

 On Windows start the engine using `%APEX_HOME%\bin\apexEngine.bat`.
 The engine will fail to fully start.
 However, if the output looks similar to the following line, the APEX installation is realized.

 [source%nowrap,bat,numbered]
 ----
 Starting Apex service with parameters [] . . .
 start of Apex service failed: Apex configuration file was not specified as an argument
 2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed:
 ----


 === Verify a Full Installation - run an Example
 A full APEX installation comes with several examples.
 Here, we can fully verify the installation by running one of the examples.

 We use the example called _SampleDomain_ and configure the engine to use standard in and standard out for events.
 Run the engine with the provided configuration.
 Note: Cygwin executes scripts as Unix scripts but runs Java as a Windows application, thus the configuration file must be given as a Windows path.

 [source%nowrap,sh,numbered,subs="attributes+"]
 ----
 # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <1>
 # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-{release-version}/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <2>
 >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json @@ <3>
 ----
 <1> UNIX
 <2> Cygwin
 <3> Windows


 The engine should start successfully.
 Assuming the logging levels are not change (default level is `info`), the output should look similar to this (last few lines)

 [source%nowrap,sh,numbered]
 ----
 2017-07-28 13:20:54,673 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model SamplePolicyModelJAVA:0.0.1 added to the engine-AxArtifactKey:(name=MyApexEngine-3,version=0.0.1)
 2017-07-28 13:20:54,675 Apex [Apex-apex-engine-service-0:0] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-0,version=0.0.1) processing ...
 2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:1] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-1,version=0.0.1) processing ...
 2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:2] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-2,version=0.0.1) processing ...
 2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:3] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) processing ...
 2017-07-28 13:20:54,680 Apex [main] INFO c.e.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine
 Started Apex service
 ----

 Important are the last two line, stating that APEX has added the final action listener to the engine and that the engine is started.

 The engine is configured to read events from standard input and write produced events to standard output.
 The policy model is a very simple policy.

 The following table shows an input event in the left column and an output event in the right column.
 Past the input event into the console where APEX is running, and the output event should appear in the console.
 Pasting the input event multiple times will produce output events with different values.

 [width="100%",options="header",cols="5a,5a"]
 |====================
 | Input Event | Example Output Event
 |
 [source%nowrap,json,numbered]
 ----
 {
   "nameSpace": "org.onap.policy.apex.sample.events",
   "name": "Event0000",
   "version": "0.0.1",
   "source": "test",
   "target": "apex",
   "TestSlogan": "Test slogan for External Event0",
   "TestMatchCase": 0,
   "TestTimestamp": 1469781869269,
   "TestTemperature": 9080.866
 }
 ----
 |
 [source%nowrap,json,numbered]
 ----
 {
   "nameSpace" : "org.onap.policy.apex.sample.events",
   "name" : "Event0004",
   "version" : "0.0.1",
   "source" : "Act",
   "target" : "Outside",
   "TestActCaseSelected" : 1,
   "TestActStateTime" : 1499280954832,
   "TestTemperature" : 9080.866,
   "TestDecideCaseSelected" : 2,
   "TestMatchCaseSelected" : 2,
   "TestTimestamp" : 1469781869269,
   "TestDecideStateTime" : 1499280954831,
   "TestMatchCase" : 0,
   "TestSlogan" : "Test slogan for External Event0",
   "TestEstablishCaseSelected" : 1,
   "TestEstablishStateTime" : 1499280954831,
   "TestMatchStateTime" : 1499280954828
 }
 ----
 |====================

 Terminate APEX by simply using `CTRL+C` in the console.


 === Verify a Full Installation - REST Editor
 APEX has a REST application for viewing policy models.
 The application can also be used to create new policy models close to the engine native policy language.
 Start the REST editor as follows.

 [source%nowrap,sh,numbered]
 ----
 # $APEX_HOME/bin/apexApps.sh rest-editor
 ----

 [source%nowrap,bat,numbered]
 ----
 >%APEX_HOME%\bin\apexApps.bat rest-editor
 ----

 The script will start a simple web server (link:https://javaee.github.io/grizzly/[Grizzly]) and deploy a `war` web archive in it.
 Once the editor is started, it will be available on `localhost:18988`.
 The last few line of the messages should be:

 [source%nowrap,sh,numbered]
 ----
 Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=READY) starting at http://localhost:18988/apex/ . . .
 Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.NetworkListener start
 INFO: Started listener bound to [localhost:18988]
 Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.HttpServer start
 INFO: [HttpServer] Started.
 Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=RUNNING) started at http://localhost:18988/apex/
 ----

 Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and use the URL `http://localhost:18988/`.
 This will connect the browser to the started REST editor.
 The start screen should be as follows.

 .REST Editor Start Screen
 image::install-guide/rest-start.png[REST Editor Start Screen]

 Now load a policy model by clicking the menu `File` and then `Open`.
 In the opened dialog, go to the directory where APEX is installed, then `examples`, `models`, `SampleDomain`, and there select the file `SamplePolicyModelJAVA.json`.
 This will load the policy model used to verify the policy engine (see above).
 Once loaded, the screen should look as follows.

 .REST Editor with loaded SampleDomain Policy Model
 image::install-guide/rest-loaded.png[REST Editor with loaded SampleDomain Policy Model]

 Now you can use the REST editor.
 To finish this verification, simply terminate your browser (or the tab), and then use `CTRL+C` in the console where you started the REST editor.
	//
	// ============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)
	//

	== Verify the APEX Installation
	When APEX is installed and all settings are realized, the installation can be verified.

	=== Verify a Minimal Installation
	The minimal installation does not come with any configuration or policy model.
	It is therefore not possible to test all APEX features, or an engine running with policies.

	However, one can verify that the engine starts up to the point where it tries to load a configuration.

	On Unix (or Cygwin) start the engine using `$APEX_HOME/bin/apexEngine.sh`.
	The engine will fail to fully start.
	However, if the output looks similar to the following line, the APEX installation is realized.

	[source%nowrap,sh,numbered]
	----
	Starting Apex service with parameters [] . . .
	start of Apex service failed: Apex configuration file was not specified as an argument
	2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed:
	----

	On Windows start the engine using `%APEX_HOME%\bin\apexEngine.bat`.
	The engine will fail to fully start.
	However, if the output looks similar to the following line, the APEX installation is realized.

	[source%nowrap,bat,numbered]
	----
	Starting Apex service with parameters [] . . .
	start of Apex service failed: Apex configuration file was not specified as an argument
	2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed:
	----


	=== Verify a Full Installation - run an Example
	A full APEX installation comes with several examples.
	Here, we can fully verify the installation by running one of the examples.

	We use the example called _SampleDomain_ and configure the engine to use standard in and standard out for events.
	Run the engine with the provided configuration.
	Note: Cygwin executes scripts as Unix scripts but runs Java as a Windows application, thus the configuration file must be given as a Windows path.

	[source%nowrap,sh,numbered,subs="attributes+"]
	----
	# $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <1>
	# $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-{release-version}/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <2>
	>%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json @@ <3>
	----
	<1> UNIX
	<2> Cygwin
	<3> Windows


	The engine should start successfully.
	Assuming the logging levels are not change (default level is `info`), the output should look similar to this (last few lines)

	[source%nowrap,sh,numbered]
	----
	2017-07-28 13:20:54,673 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model SamplePolicyModelJAVA:0.0.1 added to the engine-AxArtifactKey:(name=MyApexEngine-3,version=0.0.1)
	2017-07-28 13:20:54,675 Apex [Apex-apex-engine-service-0:0] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-0,version=0.0.1) processing ...
	2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:1] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-1,version=0.0.1) processing ...
	2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:2] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-2,version=0.0.1) processing ...
	2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:3] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) processing ...
	2017-07-28 13:20:54,680 Apex [main] INFO c.e.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine
	Started Apex service
	----

	Important are the last two line, stating that APEX has added the final action listener to the engine and that the engine is started.

	The engine is configured to read events from standard input and write produced events to standard output.
	The policy model is a very simple policy.

	The following table shows an input event in the left column and an output event in the right column.
	Past the input event into the console where APEX is running, and the output event should appear in the console.
	Pasting the input event multiple times will produce output events with different values.

	[width="100%",options="header",cols="5a,5a"]
	\|====================
	\| Input Event \| Example Output Event
	\|
	[source%nowrap,json,numbered]
	----
	{
	"nameSpace": "org.onap.policy.apex.sample.events",
	"name": "Event0000",
	"version": "0.0.1",
	"source": "test",
	"target": "apex",
	"TestSlogan": "Test slogan for External Event0",
	"TestMatchCase": 0,
	"TestTimestamp": 1469781869269,
	"TestTemperature": 9080.866
	}
	----
	\|
	[source%nowrap,json,numbered]
	----
	{
	"nameSpace" : "org.onap.policy.apex.sample.events",
	"name" : "Event0004",
	"version" : "0.0.1",
	"source" : "Act",
	"target" : "Outside",
	"TestActCaseSelected" : 1,
	"TestActStateTime" : 1499280954832,
	"TestTemperature" : 9080.866,
	"TestDecideCaseSelected" : 2,
	"TestMatchCaseSelected" : 2,
	"TestTimestamp" : 1469781869269,
	"TestDecideStateTime" : 1499280954831,
	"TestMatchCase" : 0,
	"TestSlogan" : "Test slogan for External Event0",
	"TestEstablishCaseSelected" : 1,
	"TestEstablishStateTime" : 1499280954831,
	"TestMatchStateTime" : 1499280954828
	}
	----
	\|====================

	Terminate APEX by simply using `CTRL+C` in the console.


	=== Verify a Full Installation - REST Editor
	APEX has a REST application for viewing policy models.
	The application can also be used to create new policy models close to the engine native policy language.
	Start the REST editor as follows.

	[source%nowrap,sh,numbered]
	----
	# $APEX_HOME/bin/apexApps.sh rest-editor
	----

	[source%nowrap,bat,numbered]
	----
	>%APEX_HOME%\bin\apexApps.bat rest-editor
	----

	The script will start a simple web server (link:https://javaee.github.io/grizzly/[Grizzly]) and deploy a `war` web archive in it.
	Once the editor is started, it will be available on `localhost:18988`.
	The last few line of the messages should be:

	[source%nowrap,sh,numbered]
	----
	Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=READY) starting at http://localhost:18988/apex/ . . .
	Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.NetworkListener start
	INFO: Started listener bound to [localhost:18988]
	Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.HttpServer start
	INFO: [HttpServer] Started.
	Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=RUNNING) started at http://localhost:18988/apex/
	----

	Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and use the URL `http://localhost:18988/`.
	This will connect the browser to the started REST editor.
	The start screen should be as follows.

	.REST Editor Start Screen
	image::install-guide/rest-start.png[REST Editor Start Screen]

	Now load a policy model by clicking the menu `File` and then `Open`.
	In the opened dialog, go to the directory where APEX is installed, then `examples`, `models`, `SampleDomain`, and there select the file `SamplePolicyModelJAVA.json`.
	This will load the policy model used to verify the policy engine (see above).
	Once loaded, the screen should look as follows.

	.REST Editor with loaded SampleDomain Policy Model
	image::install-guide/rest-loaded.png[REST Editor with loaded SampleDomain Policy Model]

	Now you can use the REST editor.
	To finish this verification, simply terminate your browser (or the tab), and then use `CTRL+C` in the console where you started the REST editor.