Updating docs for Plugins module

Change-Id: Ia0837cf2f86c42eea71c3f71e8cd99d684912485
Signed-off-by: Dinh Danh Le <dinh.danh.le@ericsson.com>
Issue-ID: POLICY-867

3 files changed, 120 insertions, 0 deletions

diff --git a/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/ep-apex.adoc b/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/ep-apex.adoc
new file mode 100644
index 000000000..16d41ac89
--- /dev/null
+++ b/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/ep-apex.adoc
@@ -0,0 +1,28 @@
+//
+// ============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)
+//
+
+== APEX Event
+
+The event protocol for APEX events does not require a specific plugin, it is supported by default.
+Furthermore, there is no difference in the configuration for the input and output interface.
+
+For input and output APEX uses APEX events.
+
+The following JSON shows the configuration.
+
+[source%nowrap,json]
+----
+"eventProtocolParameters":{
+  "eventProtocol" : "APEX"
+}
+----
diff --git a/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/ep-json.adoc b/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/ep-json.adoc
new file mode 100644
index 000000000..107858dc2
--- /dev/null
+++ b/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/ep-json.adoc
@@ -0,0 +1,54 @@
+//
+// ============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)
+//
+
+== JSON Event
+
+The event protocol for JSON encoding does not require a specific plugin, it is supported by default.
+Furthermore, there is no difference in the configuration for the input and output interface.
+
+For an input, APEX requires a well-formed JSON string.
+Well-formed here means according to the definitions of a policy.
+Any JSON string that is not defined as a trigger event (consume) will not be consumed (errors will be thrown).
+For output JSON events, APEX will always produce valid JSON strings according to the definition in the policy model.
+
+The following JSON shows the configuration.
+
+[source%nowrap,json]
+----
+"eventProtocolParameters":{
+  "eventProtocol" : "JSON"
+}
+----
+
+For JSON events, there are a few more optional parameters, which allow to define a mapping for standard event fields.
+An APEX event must have the fields `name`, `version`, `source`, and `target` defined.
+Sometimes it is not possible to configure a trigger or actioning system to use those fields.
+However, they might be in an event generated outside APEX (or used outside APEX) just with different names.
+To configure APEX to map between the different event names, simply add the following parameters to a JSON event:
+
+[source%nowrap,json]
+----
+"eventProtocolParameters":{
+  "eventProtocol" : "JSON",
+  "nameAlias"     : "policyName", <1>
+  "versionAlias"  : "policyVersion", <2>
+  "sourceAlias"   : "from", <3>
+  "targetAlias"   : "to", <4>
+  "nameSpaceAlias": "my.name.space" <5>
+}
+----
+<1> mapping for the `name` field, here from a field called `policyName`
+<2> mapping for the `version` field, here from a field called `policyVersion`
+<3> mapping for the `source` field, here from a field called `from` (only for an input event)
+<4> mapping for the `target` field, here from a field called `to` (only for an output event)
+<5> mapping for the `nameSpace` field, here from a field called `my.name.space`
diff --git a/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/event-protocols.adoc b/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/event-protocols.adoc
new file mode 100644
index 000000000..603167194
--- /dev/null
+++ b/plugins/plugins-event/plugins-event-protocol/src/site-docs/adoc/fragments/event-protocols.adoc
@@ -0,0 +1,38 @@
+//
+// ============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)
+//
+
+== Event Protocols, Format and Encoding
+
+Event protocols define what event formats APEX can receive (input) and should send (output).
+They can be used in any combination for input and output, unless further restricted by a carrier technology plugin (for instance for JMS output).
+There can only be 1 event protocol per event plugin.
+
+Supported _input_ event protocols are:
+
+- JSON, the event as a JSON string
+- APEX, an APEX event
+- JMS object, the event as a JMS object,
+- JMS text, the event as a JMS text,
+- XML, the event as an XML string,
+- YAML, the event as YAML text
+
+Supported _output_ event protocols are:
+
+- JSON, the event as a JSON string
+- APEX, an APEX event
+- JMS object, the event as a JMS object,
+- JMS text, the event as a JMS text,
+- XML, the event as an XML string,
+- YAML, the event as YAML text
+
+New event protocols can be added as plugins to APEX or developed outside APEX and added to an APEX deployment.