Add Match documentation

Adding documentation for new Match Policy Type.

Issue-ID: POLICY-2596
Change-Id: I97b033b345ae40e4684d5572d47132c304c735b9
Signed-off-by: Pamela Dragosh <pdragosh@research.att.com>

diff --git a/docs/xacml/decision.match.request.json b/docs/xacml/decision.match.request.json
new file mode 100644 (file)
index 0000000..72ddc31
--- /dev/null
+++ b/docs/xacml/decision.match.request.json
@@ -0,0 +1,10 @@
+{
+  "ONAPName": "my-ONAP",
+  "ONAPComponent": "my-component",
+  "ONAPInstance": "my-instance",
+  "requestId": "unique-request-1",
+  "action": "match",
+  "resource": {
+      "matchable": "foo"
+  }
+}
\ No newline at end of file

diff --git a/docs/xacml/decision.match.response.json b/docs/xacml/decision.match.response.json
new file mode 100644 (file)
index 0000000..0f9e465
--- /dev/null
+++ b/docs/xacml/decision.match.response.json
@@ -0,0 +1,18 @@
+{
+  "policies": {
+    "test_match_1": {
+      "type": "onap.policies.match.Test",
+      "type_version": "1.0.0",
+      "properties": {
+        "matchable": "foo",
+        "nonmatchable": "value1"
+      },
+      "name": "test_match_1",
+      "version": "1.0.0",
+      "metadata": {
+        "policy-id": "test_match_1",
+        "policy-version": "1.0.0"
+      }
+    }
+  }
+}
\ No newline at end of file

diff --git a/docs/xacml/match.policies.yaml b/docs/xacml/match.policies.yaml
new file mode 100644 (file)
index 0000000..d0e214c
--- /dev/null
+++ b/docs/xacml/match.policies.yaml
@@ -0,0 +1,19 @@
+tosca_definitions_version: tosca_simple_yaml_1_1_0
+topology_template:
+    policies:
+    -   test_match_1:
+            type: onap.policies.match.Test
+            version: 1.0.0
+            type_version: 1.0.0
+            name: test_match_1
+            properties:
+               matchable: foo
+               nonmatchable: value1
+    -   test_match_2:
+            type: onap.policies.match.Test
+            version: 1.0.0
+            type_version: 1.0.0
+            name: test_match_2
+            properties:
+               matchable: bar
+               nonmatchable: value2
\ No newline at end of file

diff --git a/docs/xacml/match.policy-type.yaml b/docs/xacml/match.policy-type.yaml
new file mode 100644 (file)
index 0000000..a131b84
--- /dev/null
+++ b/docs/xacml/match.policy-type.yaml
@@ -0,0 +1,16 @@
+tosca_definitions_version: tosca_simple_yaml_1_1_0
+policy_types:
+   onap.policies.match.Test:
+      derived_from: onap.policies.Match
+      version: 1.0.0
+      name: onap.policies.match.Test
+      description: Test Matching Policy Type to test matchable policies
+      properties:
+         matchable:
+            type: string
+            metadata:
+               matchable: true
+            required: true
+         nonmatchable:
+            type: string
+            required: true

diff --git a/docs/xacml/xacml.rst b/docs/xacml/xacml.rst
index 1010f8e..32949f4 100644 (file)
--- a/docs/xacml/xacml.rst
+++ b/docs/xacml/xacml.rst
@@ -23,6 +23,7 @@ The following Policy Types are supported by the XACML PDP Engine (PDP-X):
     "Optimization", "onap.policies.Optimization", "optimize", "Optimization policy types used by OOF"
     "Naming", "onap.policies.Naming", "naming", "Naming policy types used by SDNC"
     "Native", "onap.policies.native.Xacml", "native", "Native XACML Policies"
+    "Match", "onap.policies.Match", "native", "Matchable Policy Types for the ONAP community to use"
 
 Each Policy Type is implemented as an application that extends the **XacmlApplicationServiceProvider**, and provides a **ToscaPolicyTranslator** that translates the TOSCA representation of the policy into a XACML OASIS 3.0 standard policy.
 
@@ -45,6 +46,8 @@ A simple translator that wraps the TOSCA policy into a XACML policy and performs
 
 The Monitoring and Naming applications use this translator.
 
+.. _xacml-matchable-label:
+
 StdMatchableTranslator Translator
 ---------------------------------
 More robust translator that searches metadata of TOSCA properties for a **matchable** field set to **true**. The translator then uses those "matchable" properties to translate a policy into a XACML OASIS 3.0 policy which allows for fine-grained decision making such that ONAP applications can retrieve the appropriate policy(s) to be enforced during runtime.
@@ -257,6 +260,31 @@ This is an example Native Decision API payload made to retrieve a decision for w
 .. literalinclude:: decision.native.json
   :language: JSON
 
+Match Policy Type
+=================
+
+This Policy type can be used to design your own Policy Type and utilize the :ref:`StdMatchableTranslator <xacml-matchable-label>`, and does not need to build your own custom application. You can design your Policy Type by inheriting from the Match policy type (eg. onap.policies.match.<YourPolicyType>) and adding a **matchable** metadata set to **true** for the properties that you would like to request a Decision on. All a user would need to do is then use the Policy Lifecycle API to add their Policy Type and then create policies from it. Then deploy those policies to the XACML PDP and they would be able to get Decisions without customizing their ONAP installation.
+
+Here is an example Policy Type:
+
+.. literalinclude:: match.policy-type.yaml
+  :language: YAML
+
+Here are example Policies:
+
+.. literalinclude:: match.policies.yaml
+  :language: YAML
+
+This is an example Decision API request that can be made:
+
+.. literalinclude:: decision.match.request.json
+  :language: JSON
+
+Which would render the following decision response:
+
+.. literalinclude:: decision.match.response.json
+  :language: JSON
+
 Supporting Your Own Policy Types and Translators
 ************************************************