Merge "Docs for PDP-PAP interaction"

4 files changed, 592 insertions, 273 deletions

diff --git a/docs/development/development.rst b/docs/development/development.rst
index 87f49bc4..b0eef5d6 100644
--- a/docs/development/development.rst
+++ b/docs/development/development.rst
@@ -9,4 +9,5 @@ Policy Platform Development
    :maxdepth: 3
 
    devtools/devtools.rst
+   pdp/pdp-pap-interaction.rst
    actors/actors.rst
diff --git a/docs/development/pdp/images/PDP_PAP.svg b/docs/development/pdp/images/PDP_PAP.svg
new file mode 100644
index 00000000..3594c762
--- /dev/null
+++ b/docs/development/pdp/images/PDP_PAP.svg
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="550px" preserveAspectRatio="none" style="width:1152px;height:550px;background:#FFFFFF;" version="1.1" viewBox="0 0 1152 550" width="1152px" zoomAndPan="magnify"><defs><filter height="300%" id="fd44imp969z1w" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><text fill="#000000" font-family="sans-serif" font-size="18" lengthAdjust="spacing" textLength="230" x="462" y="28.708">PDP interaction with PAP</text><rect fill="#FFFFFF" filter="url(#fd44imp969z1w)" height="46.2656" style="stroke:#000000;stroke-width:2.0;" width="884.5" x="92" y="315.0469"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="27" x2="27" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="125" x2="125" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="192" x2="192" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="943.5" x2="943.5" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="1130" x2="1130" y1="123.25" y2="465.7109"/><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="41" x="5" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="27" x="12" y="107.9482">K8S</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="41" x="5" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="27" x="12" y="484.7061">K8S</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="43" x="102" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="29" x="109" y="107.9482">PDP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="43" x="102" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="29" x="109" y="484.7061">PDP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="62" x="159" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="48" x="166" y="107.9482">DMaaP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="62" x="159" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="48" x="166" y="484.7061">DMaaP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="42" x="920.5" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="28" x="927.5" y="107.9482">PAP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="42" x="920.5" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="28" x="927.5" y="484.7061">PAP</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="31" x="1112" y="119.9482">User</text><ellipse cx="1130.5" cy="49.9531" fill="#FEFECE" filter="url(#fd44imp969z1w)" rx="8" ry="8" style="stroke:#A80036;stroke-width:2.0;"/><path d="M1130.5,57.9531 L1130.5,84.9531 M1117.5,65.9531 L1143.5,65.9531 M1130.5,84.9531 L1117.5,99.9531 M1130.5,84.9531 L1143.5,99.9531 " fill="none" filter="url(#fd44imp969z1w)" style="stroke:#A80036;stroke-width:2.0;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="31" x="1112" y="477.7061">User</text><ellipse cx="1130.5" cy="491.0078" fill="#FEFECE" filter="url(#fd44imp969z1w)" rx="8" ry="8" style="stroke:#A80036;stroke-width:2.0;"/><path d="M1130.5,499.0078 L1130.5,526.0078 M1117.5,507.0078 L1143.5,507.0078 M1130.5,526.0078 L1117.5,541.0078 M1130.5,526.0078 L1143.5,541.0078 " fill="none" filter="url(#fd44imp969z1w)" style="stroke:#A80036;stroke-width:2.0;"/><polygon fill="#A80036" points="113.5,150.3828,123.5,154.3828,113.5,158.3828,117.5,154.3828" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="27.5" x2="119.5" y1="154.3828" y2="154.3828"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="34.5" y="149.3169">1</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="61" x="47.5" y="149.3169">Start PDP</text><polygon fill="#A80036" points="931.5,179.5156,941.5,183.5156,931.5,187.5156,935.5,183.5156" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="183.5156" y2="183.5156"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="178.4497">2</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="697" x="145.5" y="178.4497">Send PDP_STATUS (registration message) with state as PASSIVE and other info like PDP's Group/Type/Name.</text><polygon fill="#A80036" points="136.5,208.6484,126.5,212.6484,136.5,216.6484,132.5,212.6484" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="130.5" x2="942.5" y1="212.6484" y2="212.6484"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="8" x="142.5" y="207.5825">3</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="643" x="154.5" y="207.5825">Send PDP_UPDATE message with info like subgroup, heartbeat interval, policiesToBeDeployed if any</text><polygon fill="#A80036" points="931.5,237.7813,941.5,241.7813,931.5,245.7813,935.5,241.7813" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="241.7813" y2="241.7813"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="236.7153">4</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="731" x="145.5" y="236.7153">Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.</text><polygon fill="#A80036" points="136.5,266.9141,126.5,270.9141,136.5,274.9141,132.5,270.9141" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="130.5" x2="942.5" y1="270.9141" y2="270.9141"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="142.5" y="265.8481">5</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="530" x="155.5" y="265.8481">Send PDP_STATE_CHANGE message asking the PDP to go from PASSIVE to ACTIVE</text><polygon fill="#A80036" points="931.5,296.0469,941.5,300.0469,931.5,304.0469,935.5,300.0469" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="300.0469" y2="300.0469"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="294.981">6</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="781" x="145.5" y="294.981">Send PDP_STATUS (response to PDP_STATE_CHANGE) with added information such as responseStatus/responseMessage.</text><path d="M92,315.0469 L170,315.0469 L170,322.0469 L160,332.0469 L92,332.0469 L92,315.0469 " fill="#EEEEEE" style="stroke:#000000;stroke-width:1.0;"/><rect fill="none" height="46.2656" style="stroke:#000000;stroke-width:2.0;" width="884.5" x="92" y="315.0469"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="33" x="107" y="328.1138">loop</text><text fill="#000000" font-family="sans-serif" font-size="11" font-weight="bold" lengthAdjust="spacing" textLength="61" x="185" y="327.2573">[forever]</text><polygon fill="#A80036" points="931.5,349.3125,941.5,353.3125,931.5,357.3125,935.5,353.3125" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="353.3125" y2="353.3125"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="348.2466">7</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="394" x="145.5" y="348.2466">Send PDP_STATUS which is the heartbeat message from PDP</text><polygon fill="#A80036" points="954.5,385.4453,944.5,389.4453,954.5,393.4453,950.5,389.4453" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="948.5" x2="1129.5" y1="389.4453" y2="389.4453"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="960.5" y="384.3794">8</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="150" x="973.5" y="384.3794">Deploy/Undeploy Policy</text><polygon fill="#A80036" points="136.5,414.5781,126.5,418.5781,136.5,422.5781,132.5,418.5781" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="130.5" x2="942.5" y1="418.5781" y2="418.5781"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="142.5" y="413.5122">9</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="464" x="155.5" y="413.5122">Send PDP_UPDATE message with the policiesToBeDeployed/Undeployed</text><polygon fill="#A80036" points="931.5,443.7109,941.5,447.7109,931.5,451.7109,935.5,447.7109" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="447.7109" y2="447.7109"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="19" x="132.5" y="442.645">10</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="731" x="155.5" y="442.645">Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.</text><!--MD5=[e6c667340a3c9400f3b529b4b1acf584]
+@startuml
+title PDP interaction with PAP
+
+participant K8S
+participant PDP
+participant DMaaP
+participant PAP
+actor User
+
+autonumber
+
+K8S - -> PDP : Start PDP
+
+PDP - -> PAP: Send PDP_STATUS (registration message) with state as PASSIVE and other info like PDP's Group/Type/Name.
+
+PAP - -> PDP: Send PDP_UPDATE message with info like subgroup, heartbeat interval, policiesToBeDeployed if any
+
+PDP - -> PAP: Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.
+
+PAP - -> PDP: Send PDP_STATE_CHANGE message asking the PDP to go from PASSIVE to ACTIVE
+
+PDP - -> PAP: Send PDP_STATUS (response to PDP_STATE_CHANGE) with added information such as responseStatus/responseMessage.
+
+loop forever
+  PDP - -> PAP: Send PDP_STATUS which is the heartbeat message from PDP
+end
+
+User - -> PAP: Deploy/Undeploy Policy
+
+PAP - -> PDP: Send PDP_UPDATE message with the policiesToBeDeployed/Undeployed
+
+PDP - -> PAP: Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.
+@enduml
+
+PlantUML version 1.2021.11beta6(Unknown compile time)
+(GPL source distribution)
+Java Runtime: Java(TM) SE Runtime Environment
+JVM: Java HotSpot(TM) 64-Bit Server VM
+Default Encoding: UTF-8
+Language: en
+Country: US
+--></g></svg>
\ No newline at end of file
diff --git a/docs/development/pdp/pdp-pap-interaction.rst b/docs/development/pdp/pdp-pap-interaction.rst
new file mode 100644
index 00000000..45988192
--- /dev/null
+++ b/docs/development/pdp/pdp-pap-interaction.rst
@@ -0,0 +1,299 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _pdp-pap-interaction-label:
+
+Guidelines for PDP-PAP interaction
+###################################
+
+.. contents::
+    :depth: 3
+
+A PDP (Policy Decision Point) is where the policy execution happens. The administrative actions such as
+managing the PDPs, deploying or undeploying policies to these PDPs etc. are handled by PAP
+(Policy Administration Point). Any PDP should follow certain behavior to be registered and functional in
+the Policy Framework. All the communications between PAP and PDP happen over DMaaP on topic *POLICY-PDP-PAP*.
+The below diagram shows how a PDP interacts with PAP.
+
+.. image:: images/PDP_PAP.svg
+
+**1. Start PDP**
+
+A PDP should be configured to start with the below information in its startup configuration file.
+
+- *pdpGroup* to which the PDP should belong to.
+- *DMaaP topic* 'POLICY-PDP-PAP' which should be the source and sink for communicating with PAP.
+
+**2. PDP sends PDP_STATUS (registration message)**
+
+As soon as a PDP is up, it sends a registration message to POLICY-PDP-PAP topic.
+Some of the information included in the message are:
+
+- *pdpType* the type of the PDP (apex/drools/xacml etc.).
+- *pdpGroup* to which the PDP should belong to.
+- *state* the initial state of the PDP which is PASSIVE.
+- *healthy* whether the PDP is "HEALTHY" or not.
+- *name* a name that is unique to the PDP instance.
+
+
+.. code-block:: json
+  :caption: Sample PDP_STATUS Registration message (from APEX-PDP)
+  :linenos:
+
+    {
+      "pdpType": "apex",
+      "state": "PASSIVE",
+      "healthy": "HEALTHY",
+      "description": "Pdp Heartbeat",
+      "statistics": {
+        ..... Omitted for brevity
+      },
+      "messageName": "PDP_STATUS",
+      "requestId": "54926ad0-440f-4b40-9237-40ca754ad00d",
+      "timestampMs": 1632325024286,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup"
+    }
+
+**3. PAP sends PDP_UPDATE message**
+
+On receiving the registration message from a PDP, PAP checks and assigns it to a subgroup under the group.
+If there are policies that were already deployed (for e.g. previously deployed, and the PDP is restarted)
+under the subgroup, then the *policiesToBeDeployed* are also sent along with the *subgroup* it is assigned to.
+PAP also sends the *pdpHeartbeatIntervalMs* which is the time interval in which PDPs should send heartbeats to PAP.
+
+.. code-block:: json
+  :caption: Sample PDP_UPDATE message (for APEX-PDP)
+  :linenos:
+
+    {
+      "source": "pap-56c8531d-5376-4e53-a820-6973c62bfb9a",
+      "pdpHeartbeatIntervalMs": 120000,
+      "policiesToBeDeployed": [],
+      "messageName": "PDP_UPDATE",
+      "requestId": "3534e54f-4432-4c68-81c8-a6af07e59fb2",
+      "timestampMs": 1632325037040,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup",
+      "pdpSubgroup": "apex"
+    }
+
+**4. PDP sends PDP_STATUS response to PDP_UPDATE**
+
+PDP on receiving the PDP_UPDATE message from the DMaaP topic, it first checks if the message is intended for the PDP.
+If so, it updates itself with the information in PDP_UPDATE message from PAP such as *pdpSubgroup*,
+*pdpHeartbeatIntervalMs* and *policiesToBeDeployed* (if any). After handling the PDP_UPDATE message, the PDP sends
+a response message back to PAP with the current status of the PDP along with the result of the PDP_UPDATE operation.
+
+.. code-block:: json
+  :caption: Sample PDP_STATUS response message (from APEX-PDP)
+  :linenos:
+
+    {
+      "pdpType": "apex",
+      "state": "PASSIVE",
+      "healthy": "HEALTHY",
+      "description": "Pdp status response message for PdpUpdate",
+      "policies": [],
+      "statistics": {
+        ..... Omitted for brevity
+      },
+      "response": {
+        "responseTo": "3534e54f-4432-4c68-81c8-a6af07e59fb2",
+        "responseStatus": "SUCCESS",
+        "responseMessage": "Pdp update successful."
+      },
+      "messageName": "PDP_STATUS",
+      "requestId": "e3c72783-4e91-4cb5-8140-e4ac0630706d",
+      "timestampMs": 1632325038075,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup",
+      "pdpSubgroup": "apex"
+    }
+
+
+**5. PAP sends PDP_STATE_CHANGE message**
+
+PAP sends PDP_STATE_CHANGE message to PDPs to change the state from PASSIVE to active
+or ACTIVE to PASSIVE. When a PDP is in PASSIVE state, the policy execution will not happen.
+All PDPs start up in PASSIVE state, and they can be changed to ACTIVE/PASSIVE using PAP.
+After registration is complete, PAP makes a PDP ACTIVE by default.
+
+.. code-block:: json
+  :caption: Sample PDP_STATE_CHANGE message
+  :linenos:
+
+    {
+      "source": "pap-56c8531d-5376-4e53-a820-6973c62bfb9a",
+      "state": "ACTIVE",
+      "messageName": "PDP_STATE_CHANGE",
+      "requestId": "90eada6d-bb98-4750-a4e1-b439cb5e041d",
+      "timestampMs": 1632325037040,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup",
+      "pdpSubgroup": "apex"
+    }
+
+**6. PDP sends PDP_STATUS response to PDP_STATE_CHANGE**
+
+PDP updates its state as per the PDP_STATE_CHANGE received from PAP. When a PDP is changed
+to ACTIVE, any policies that are already pushed to the PDP start execution
+and start processing events as per the policies deployed. If no policies are running in a PDP,
+then it waits in ACTIVE state, ready to execute any policies as and when they are pushed
+to them from PAP. After handling the PDP_STATE_CHANGE message, the PDP sends a response message
+back to PAP with the current status of the PDP along with the result of the PDP_STATE_CHANGE operation.
+
+.. code-block:: json
+  :caption: Sample PDP_STATUS response message (from APEX-PDP)
+  :linenos:
+
+    {
+      "pdpType": "apex",
+      "state": "ACTIVE",
+      "healthy": "HEALTHY",
+      "description": "Pdp status response message for PdpStateChange",
+      "policies": [],
+      "statistics": {
+        ..... Omitted for brevity
+      },
+      "response": {
+        "responseTo": "90eada6d-bb98-4750-a4e1-b439cb5e041d",
+        "responseStatus": "SUCCESS",
+        "responseMessage": "State changed to active. No policies are running."
+      },
+      "messageName": "PDP_STATUS",
+      "requestId": "8a88806c-4d3e-4c80-8048-dc85d4bb75dd",
+      "timestampMs": 1632325043068,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup",
+      "pdpSubgroup": "apex"
+    }
+
+**7. PDP sends PDP_STATUS Heartbeat messages**
+
+A PDP has to send Heartbeat messages to PAP periodically with the current status information
+of the PDP. PAP receives this information and makes sure they are updated. In case of any mismatch
+with the data in the database, PAP sends out a PDP_UPDATE message to update the PDP.
+PAP considers a PDP as expired if three consecutive heartbeats are missing from the PDP,
+and removes the PDP instance details from the database.
+
+.. code-block:: json
+  :caption: Sample PDP_STATUS response message (from APEX-PDP)
+  :linenos:
+
+    {
+      "pdpType": "apex",
+      "state": "ACTIVE",
+      "healthy": "HEALTHY",
+      "description": "Pdp Heartbeat",
+      "policies": [],
+      "statistics": {
+        ..... Omitted for brevity
+      },
+      "messageName": "PDP_STATUS",
+      "requestId": "e3c72783-4e91-4cb5-8140-e4ac0630706d",
+      "timestampMs": 1632325038075,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup",
+      "pdpSubgroup": "apex"
+    }
+
+**8. Deploy/Undeploy Policy using PAP**
+
+Policies can be deployed or undeployed using PAP APIs. PAP fetches the policies to be deployed
+from the database, and send the whole policies' list under *policiesToBeDeployed* field.
+In case of undeployment, PAP sends the list of policies with their name and version under
+*policiesToBeUndeployed* in the PDP_UPDATE message.
+
+**9. PAP sends PDP_UPDATE message with policiesToBeDeployed/Undeployed**
+
+PAP sends a PDP_UPDATE message with information about policies to be deployed and
+undeployed. If there are some policies that are already deployed, then only the new ones
+are sent under the *policiesToBeDeployed* field.
+
+.. code-block:: json
+  :caption: Sample PDP_STATUS response message (from APEX-PDP)
+  :linenos:
+
+    {
+      "source": "pap-56c8531d-5376-4e53-a820-6973c62bfb9a",
+      "pdpHeartbeatIntervalMs": 120000,
+      "policiesToBeDeployed": [
+        {
+          "type": "onap.policies.native.Apex",
+          "type_version": "1.0.0",
+          "properties": {
+          ..... Omitted for brevity
+          },
+          "name": "onap.policies.apex.Simplecontrolloop",
+          "version": "1.0.0",
+          "metadata": {
+            "policy-id": "onap.policies.apex.Simplecontrolloop",
+            "policy-version": "1.0.0"
+          }
+        }
+      ],
+      "policiesToBeUndeployed":[],
+      "messageName": "PDP_UPDATE",
+      "requestId": "3534e54f-4432-4c68-81c8-a6af07e59fb2",
+      "timestampMs": 1632325037040,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup",
+      "pdpSubgroup": "apex"
+    }
+
+**10. PDP sends PDP_STATUS response to PDP_UPDATE**
+
+All policies to be deployed/undeployed are updated in the PDP engine.
+Policies that are part of policiesToBeDeployed are updated to the engine, and
+all policies under policiesToBeUndeployed are removed from the PDP engine.
+Once the processing of PDP_UPDATE message is complete, PDP sends back a PDP_STATUS
+message with the updated status, the current list of policies that are in the
+engine, and the result of the PDP_UPDATE operation.
+
+.. code-block:: json
+  :caption: Sample PDP_STATUS response message (from APEX-PDP)
+  :linenos:
+
+    {
+      "pdpType": "apex",
+      "state": "ACTIVE",
+      "healthy": "HEALTHY",
+      "description": "Pdp status response message for PdpUpdate",
+      "policies": [
+        {
+          "name": "onap.policies.apex.Simplecontrolloop",
+          "version": "1.0.0"
+        }
+      ],
+      "statistics": {
+        "pdpInstanceId": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+        "timeStamp": "2021-09-22T15:37:18.075436Z",
+        "pdpGroupName": "defaultGroup",
+        "pdpSubGroupName": "apex",
+        "policyExecutedCount": 0,
+        "policyExecutedSuccessCount": 0,
+        "policyExecutedFailCount": 0,
+        "policyDeployCount": 1,
+        "policyDeploySuccessCount": 1,
+        "policyDeployFailCount": 0,
+        "policyUndeployCount": 0,
+        "policyUndeploySuccessCount": 0,
+        "policyUndeployFailCount": 0
+      },
+      "response": {
+        "responseTo": "4534e54f-4432-4c68-81c8-a6af07e59fb2",
+        "responseStatus": "SUCCESS",
+        "responseMessage": "Apex engine started. Deployed policies are: onap.policies.apex.Simplecontrolloop:1.0.0"
+      },
+      "messageName": "PDP_STATUS",
+      "requestId": "e3c72783-4e91-4cb5-8140-e4ac0630706d",
+      "timestampMs": 1632325038075,
+      "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+      "pdpGroup": "defaultGroup",
+      "pdpSubgroup": "apex"
+    }
+
+More details about the messages used for PDP-PAP internal communication and their structure can be found here
+:ref:`The Internal Policy Framework PAP-PDP API <pap-pdp-label>`.
diff --git a/docs/pap/InternalPapPdp.rst b/docs/pap/InternalPapPdp.rst
index 41730a62..132e0df1 100644
--- a/docs/pap/InternalPapPdp.rst
+++ b/docs/pap/InternalPapPdp.rst
@@ -15,7 +15,7 @@ API <https://wiki.onap.org/display/DW/DMaaP+API>`__ messaging. The APIs in this
 communication in the Policy Framework. The APIs are NOT supported for use by components outside the Policy Framework and
 are subject to revision and change at any time.
 
-There are four messages on the API:
+There are three messages on the API:
 
 1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP
 
@@ -25,68 +25,68 @@ There are four messages on the API:
 3. PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message with the result
    of the PDP_STATE_CHANGE operation
 
-4. PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a health check on PDPs, triggers a PDP_STATUS message with the
-   result of the PDP_HEALTH_CHECK operation
 
 The fields in the table below are valid on API calls:
 
-=============================== ======== ======== ======== ======= =====================================================
-**Field**                       **PDP    **PDP    **PDP    **PDP   **Comment**
-                                STATUS** UPDATE** STATE    HEALTH
-                                                  CHANGE** CHECK**
-=============================== ======== ======== ======== ======= =====================================================
-(message_name)                  M        M        M        M       pdp_status, pdp_update, pdp_state_change, or
-                                                                   pdp_health_check
-name                            M        M        C        C       The name of the PDP, for state changes and health
-                                                                   checks, the PDP group and subgroup can be used to
-                                                                   specify the scope of the operation
-version                         M        N/A      N/A      N/A     The version of the PDP
-pdp_type                        M        M        N/A      N/A     The type of the PDP, currently xacml, drools, or apex
-state                           M        N/A      M        N/A     The administrative state of the PDP group: PASSIVE,
-                                                                   SAFE, TEST, ACTIVE, or TERMINATED
-healthy                         M        N/A      N/A      N/A     The result of the latest health check on the PDP:
-                                                                   HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
-description                     O        O        N/A      N/A     The description of the PDP
-pdp_group                       O        M        C        C       The PDP group to which the PDP belongs, the PDP group
-                                                                   and subgroup can be used to specify the scope of the
-                                                                   operation
-pdp_subgroup                    O        M        C        C       The PDP subgroup to which the PDP belongs, the PDP
-                                                                   group and subgroup can be used to specify the scope
-                                                                   of the operation
-supported_policy_types          M        N/A      N/A      N/A     A list of the policy types supported by the PDP
-policies                        M        N/A      N/A      N/A     The list of policies running on the PDP
-policiesToBeDeployed            N/A      M        N/A      N/A     The list of policies to be deployed on the PDP
-policiesToBeUndeployed          N/A      M        N/A      N/A     The list of policies to be undeployed from the PDP
-->(name)                        O        M        N/A      N/A     The name of a TOSCA policy running on the PDP
-->policy_type                   O        M        N/A      N/A     The TOSCA policy type of the policyWhen a PDP starts,
-                                                                   it commences periodic sending of *PDP_STATUS*
-                                                                   messages on DMaaP. The PAP receives these messages
-                                                                   and acts in whatever manner is appropriate.
-->policy_type_version           O        M        N/A      N/A     The version of the TOSCA policy type of the policy
-->properties                    O        M        N/A      N/A     The properties of the policy for the XACML, Drools,
-                                                                   or APEX PDP for details
-instance                        M        N/A      N/A      N/A     The instance ID of the PDP running in a Kuberenetes
-                                                                   Pod
-deployment_instance_info        M        N/A      N/A      N/A     Information on the node running the PDP
-properties                      O        O        N/A      N/A     Other properties specific to the PDP
-statistics                      M        N/A      N/A      N/A     Statistics on policy execution in the PDP
-->policy_download_count         M        N/A      N/A      N/A     The number of policies downloaded into the PDP
-->policy_download_success_count M        N/A      N/A      N/A     The number of policies successfully downloaded into
-                                                                   the PDP
-->policy_download_fail_count    M        N/A      N/A      N/A     The number of policies downloaded into the PDP where
-                                                                   the download failed
-->policy_executed_count         M        N/A      N/A      N/A     The number of policy executions on the PDP
-->policy_executed_success_count M        N/A      N/A      N/A     The number of policy executions on the PDP that
-                                                                   completed successfully
-->policy_executed_fail_count    M        N/A      N/A      N/A     The number of policy executions on the PDP that
-                                                                   failed
-response                        O        N/A      N/A      N/A     The response to the last operation that the PAP
-                                                                   executed on the PDP
-->response_to                   M        N/A      N/A      N/A     The PAP to PDP message to which this is a response
-->response_status               M        N/A      N/A      N/A     SUCCESS or FAIL
-->response_message              O        N/A      N/A      N/A     Message giving further information on the successful
-                                                                   or failed operation
-=============================== ======== ======== ======== ======= =====================================================
+=============================== ======== ======== ======== =====================================================
+**Field**                       **PDP    **PDP    **PDP    **Comment**
+                                STATUS** UPDATE** STATE
+                                                  CHANGE**
+=============================== ======== ======== ======== =====================================================
+(message_name)                  M        M        M        pdp_status, pdp_update, pdp_state_change, or
+                                                           pdp_health_check
+name                            M        M        M        The name of the PDP, for state changes and health
+                                                           checks, the PDP group and subgroup can be used to
+                                                           specify the scope of the operation
+pdpType                         M        N/A      N/A      The type of the PDP, currently xacml, drools, or apex
+state                           M        N/A      M        The administrative state of the PDP group: PASSIVE,
+                                                           SAFE, TEST, ACTIVE, or TERMINATED
+healthy                         M        N/A      N/A      The result of the latest health check on the PDP:
+                                                           HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
+description                     O        O        N/A      The description of the PDP
+pdpGroup                        M        M        C        The PDP group to which the PDP belongs, the PDP group
+                                                           and subgroup can be used to specify the scope of the
+                                                           operation
+pdpSubgroup                     O        M        C        The PDP subgroup to which the PDP belongs, the PDP
+                                                           group and subgroup can be used to specify the scope
+                                                           of the operation
+source                          N/A      M        M        The source of the message
+policies                        M        N/A      N/A      The list of policies running on the PDP
+policiesToBeDeployed            N/A      M        N/A      The list of policies to be deployed on the PDP
+policiesToBeUndeployed          N/A      M        N/A      The list of policies to be undeployed from the PDP
+->(name)                        O        M        N/A      The name of a TOSCA policy running on the PDP
+->policy_type                   O        M        N/A      The TOSCA policy type of the policyWhen a PDP starts,
+                                                           it commences periodic sending of *PDP_STATUS*
+                                                           messages on DMaaP. The PAP receives these messages
+                                                           and acts in whatever manner is appropriate.
+->policy_type_version           O        M        N/A      The version of the TOSCA policy type of the policy
+->properties                    O        M        N/A      The properties of the policy for the XACML, Drools,
+                                                           or APEX PDP for details
+                                                           Pod
+properties                      O        N/A      N/A      Other properties specific to the PDP
+statistics                      O        N/A      N/A      Statistics on policy execution in the PDP
+->policyDeployCount             M        N/A      N/A      The number of policies deployed into the PDP
+->policyDeploySuccessCount      M        N/A      N/A      The number of policies successfully deployed into
+                                                           the PDP
+->policyDeployFailCount         M        N/A      N/A      The number of policies deployed into the PDP where
+                                                           the deployment failed
+->policyUndeployCount           M        N/A      N/A      The number of policies undeployed from the PDP
+->policyUndeploySuccessCount    M        N/A      N/A      The number of policies successfully undeployed from
+                                                           the PDP
+->policyUndeployFailCount       M        N/A      N/A      The number of policies undeployed from the PDP where
+                                                           the undeployment failed
+->policyExecutedCount           M        N/A      N/A      The number of policy executions on the PDP
+->policyExecutedSuccessCount    M        N/A      N/A      The number of policy executions on the PDP that
+                                                           completed successfully
+->policyExecutedFailCount       M        N/A      N/A      The number of policy executions on the PDP that
+                                                           failed
+response                        O        N/A      N/A      The response to the last operation that the PAP
+                                                           executed on the PDP
+->responseTo                    M        N/A      N/A      The PAP to PDP message to which this is a response
+->responseStatus                M        N/A      N/A      SUCCESS or FAIL
+->responseMessage               O        N/A      N/A      Message giving further information on the successful
+                                                           or failed operation
+=============================== ======== ======== ======== =====================================================
 
 YAML is used for illustrative purposes in the examples in this section. JSON (application/json) is used as the content
 type in the implementation of this API.
@@ -98,12 +98,12 @@ Administration. There is a single *PDP_STATUS* message on this API. PDPs send th
 *POLICY_PDP_PAP* DMaaP topic. The PAP listens on this topic for messages.
 
 When a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and
-acts in whatever manner is appropriate. *PDP_UPDATE*, *PDP_STATE_CHANGE*, and *PDP_HEALTH_CHECK* operations trigger a
+acts in whatever manner is appropriate. *PDP_UPDATE* and *PDP_STATE_CHANGE* operations trigger a
 *PDP_STATUS* message as a response.
 
 The *PDP_STATUS* message is used for PDP heartbeat monitoring. A PDP sends a *PDP_STATUS* message with a state of
 *TERMINATED* when it terminates normally. If a *PDP_STATUS* message is not received from a PDP periodically or in
-response to a pdp_update, pdp-state_change, or pdp_health_check message in a certain configurable time, then the PAP
+response to a pdp_update or pdp-state_change message in a certain configurable time, then the PAP
 assumes the PDP has failed.
 
 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. If the PDP group, subgroup, or any policy
@@ -114,170 +114,144 @@ sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks t
   :linenos:
 
   pdp_status:
-    name: xacml_1
-    version: 1.2.3
-    pdp_type: xacml
-    state: active
-    healthy: true
+    pdpType: xacml
+    state: ACTIVE
+    healthy: HEALTHY
     description: XACML PDP running control loop policies
-    pdp_group: onap.pdpgroup.controlloop.operational
-    pdp_subgroup: xacml
-    supported_policy_types:
-      - onap.policies.controlloop.guard.FrequencyLimiter
-      - onap.policies.controlloop.guard.BlackList
-      - onap.policies.controlloop.guard.MinMax
     policies:
-      - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
-          policy_type: onap.policies.controlloop.guard.FrequencyLimiter
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
-     - onap.policies.controlloop.guard.blacklist.eastRegion:
-          policy_type: onap.policies.controlloop.guard.BlackList
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
-      - onap.policies.controlloop.guard.minmax.eastRegion:
-          policy_type: onap.policies.controlloop.guard.MinMax
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
-    instance: xacml_1
-    deployment_instance_info:
-      node_address: xacml_1_pod
-      # Other deployment instance info
+      - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
+        version: 1.0.0
+      - name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
+        version: 1.0.0
+      - name: onap.policies.controlloop.guard.blacklist.eastRegion
+        version: 1.0.0
+      - name: .policies.controlloop.guard.minmax.eastRegion
+        version: 1.0.0
+    messageName: PDP_STATUS
+    requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
+    timestampMs: 1633534472002
+    name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
+    pdpGroup: defaultGroup
+    pdpSubgroup: xacml
     statistics:
-      policy_download_count: 0
-      policy_download_success_count: 0
-      policy_download_fail_count: 0
-      policy_executed_count: 123
-      policy_executed_success_count: 122
-      policy_executed_fail_count: 1
+      policyDeployCount: 0
+      policyDeploySuccessCount: 0
+      policyDeployFailCount: 0
+      policyExecutedCount: 123
+      policyExecutedSuccessCount: 122
+      policyExecutedFailCount: 1
+
 
 .. code-block:: yaml
   :caption: PDP_STATUS message from a Drools PDP running control loop policies
   :linenos:
 
   pdp_status:
-    name: drools_2
-    version: 2.3.4
-    pdp_type: drools
-    state: safe
-    healthy: true
+    pdpType: drools
+    state: ACTIVE
+    healthy: HEALTHY
     description: Drools PDP running control loop policies
-    pdp_group: onap.pdpgroup.controlloop.operational
-    pdp_subgroup: drools
-    supported_policy_types:
-      - onap.controllloop.operational.drools.vCPE
-      - onap.controllloop.operational.drools.vFW
     policies:
-      - onap.controllloop.operational.drools.vcpe.EastRegion:
-          policy_type: onap.controllloop.operational.drools.vCPE
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
-      - onap.controllloop.operational.drools.vfw.EastRegion:
-          policy_type: onap.controllloop.operational.drools.vFW
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
+      - name: onap.controllloop.operational.drools.vcpe.EastRegion
+        version: 1.0.0
+      - name: onap.controllloop.operational.drools.vfw.EastRegion
+        version: 1.0.0
     instance: drools_2
     deployment_instance_info:
       node_address: drools_2_pod
       # Other deployment instance info
     statistics:
-      policy_download_count: 3
-      policy_download_success_count: 3
-      policy_download_fail_count: 0
-      policy_executed_count: 123
-      policy_executed_success_count: 122
-      policy_executed_fail_count: 1
+      policyDeployCount: 3
+      policyDeploySuccessCount: 3
+      policyDeployFailCount: 0
+      policyExecutedCount: 123
+      policyExecutedSuccessCount: 122
+      policyExecutedFailCount: 1
+      policyUndeployCount: 0
+      policyUndeploySuccessCount: 0
+      policyUndeployFailCount: 0
     response:
-      response_to: PDP_HEALTH_CHECK
-      response_status: SUCCESS
+      responseTo: 52117e25-f416-45c7-a955-83ed929d557f
+      responseStatus: SUCCESSSS
+    messageName: PDP_STATUS
+    requestId: 52117e25-f416-45c7-a955-83ed929d557f
+    timestampMs: 1633355052181
+    name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
+    pdpGroup: defaultGroup
+    pdpSubgroup: drools
 
 .. code-block:: yaml
   :caption: PDP_STATUS message from an APEX PDP running control loop policies
   :linenos:
 
-  pdp_status:
-    name: apex_3
-    version: 2.3.4
-    pdp_type: apex
-    state: safe
-    healthy: true
-    description: APEX PDP running control loop policies
-    pdp_group: onap.pdpgroup.controlloop.operational
-    pdp_subgroup: apex
-    supported_policy_types:
-      - onap.controllloop.operational.apex.BBS
+    pdpType: apex
+    state: ACTIVE
+    healthy: HEALTHY
+    description: Pdp status response message for PdpUpdate
     policies:
-      - onap.controllloop.operational.apex.bbs.EastRegion:
-          policy_type: onap.controllloop.operational.apex.BBS
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
-      - onap.controllloop.operational.apex.bbs.WestRegion:
-          policy_type: onap.controllloop.operational.apex.BBS
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
-    instance: apex_3
-    deployment_instance_info:
-      node_address: apex_3_pod
-      # Other deployment instance info
+      - name: onap.controllloop.operational.apex.bbs.EastRegion
+        version: 1.0.0
     statistics:
-      policy_download_count: 3
-      policy_download_success_count: 3
-      policy_download_fail_count: 0
-      policy_executed_count: 123
-      policy_executed_success_count: 122
-      policy_executed_fail_count: 1
+      policyExecutedCount: 0
+      policyExecutedSuccessCount: 0
+      policyExecutedFailCount: 0
+      policyDeployCount: 1
+      policyDeploySuccessCount: 1
+      policyDeployFailCount: 0
+      policyUndeployCount: 0
+      policyUndeploySuccessCount: 0
+      policyUndeployFailCount: 0
     response:
-      response_to: PDP_HEALTH_CHECK
-      response_status: SUCCESS
+      responseTo: 679fad9b-abbf-4b9b-971c-96a8372ec8af
+      responseStatus: SUCCESS
+      responseMessage: >-
+        Apex engine started. Deployed policies are:
+        onap.policies.apex.sample.Salecheck:1.0.0
+    messageName: PDP_STATUS
+    requestId: 932c17b0-7ef9-44ec-be58-f17e104e7d5d
+    timestampMs: 1633435952217
+    name: apex-d0610cdc-381e-4aae-8e99-3f520c2a50db
+    pdpGroup: defaultGroup
+    pdpSubgroup: apex
+
 
 .. code-block:: yaml
   :caption: PDP_STATUS message from an XACML PDP running monitoring policies
   :linenos:
 
   pdp_status:
-    name: xacml_1
-    version: 1.2.3
-    pdp_type: xacml
-    state: active
-    healthy: true
-    description: XACML PDP running monitoring policies
-    pdp_group: onap.pdpgroup.Monitoring
-    pdp_subgroup: xacml
-    supported_policy_types:
-      - onap.monitoring.tcagen2
-     policies:
-      - onap.scaleout.tca:message
-          policy_type: onap.policies.monitoring.tcagen2
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
-    instance: xacml_1
-    deployment_instance_info:
-      node_address: xacml_1_pod
-      # Other deployment instance info
+    pdpType: xacml
+    state: ACTIVE
+    healthy: HEALTHY
+    description: XACML PDP running control loop policies
+    policies:
+      - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
+        version: 1.0.0
+      - name: onap.scaleout.tca:message
+        version: 1.0.0
+    messageName: PDP_STATUS
+    requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
+    timestampMs: 1633534472002
+    name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
+    pdpGroup: onap.pdpgroup.Monitoring
+    pdpSubgroup: xacml
     statistics:
-      policy_download_count: 0
-      policy_download_success_count: 0
-      policy_download_fail_count: 0
-      policy_executed_count: 123
-      policy_executed_success_count: 122
-      policy_executed_fail_count: 1
+      policyDeployCount: 0
+      policyDeploySuccessCount: 0
+      policyDeployFailCount: 0
+      policyExecutedCount: 123
+      policyExecutedSuccessCount: 122
+      policyExecutedFailCount: 1
+
 
 2 PDP API for PAPs
 ==================
 
-The purpose of this API is for the PAP to load and update policies on PDPs and to change the state of PDPs. It also
-allows the PAP to order health checks to run on PDPs. The PAP sends *PDP_UPDATE*, *PDP_STATE_CHANGE*, and
-*PDP_HEALTH_CHECK* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic. PDPs listen on this topic for messages.
+The purpose of this API is for the PAP to load and update policies on PDPs and to change the state of PDPs.
+The PAP sends *PDP_UPDATE* and *PDP_STATE_CHANGE* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic.
+PDPs listen on this topic for messages.
 
-The PAP can set the scope of *PDP_STATE_CHANGE* and *PDP_HEALTH_CHECK* messages:
+The PAP can set the scope of *PDP_STATE_CHANGE* message:
 
 -  PDP Group: If a PDP group is specified in a message, then the PDPs in that PDP group respond to the message and all
    other PDPs ignore it.
@@ -288,13 +262,12 @@ The PAP can set the scope of *PDP_STATE_CHANGE* and *PDP_HEALTH_CHECK* messages:
 -  Single PDP: If the name of a PDP is specified in a message, then only that PDP responds to the message and all other
    PDPs ignore it.
 
-Note: *PDP_UPDATE* messages must be issued individually to PDPs because the *PDP_UPDATE* operation can change the PDP
-group to which a PDP belongs.
 
 2.1 PDP Update
 --------------
 
-The *PDP_UPDATE* operation allows the PAP to modify the PDP group to which a PDP belongs and the policies in a PDP.
+The *PDP_UPDATE* operation allows the PAP to modify the PDP with information such as policiesToBeDeployed/Undeployed,
+the interval to send heartbeats, subgroup etc.
 
 The following examples illustrate how the operation is used.
 
@@ -303,62 +276,76 @@ The following examples illustrate how the operation is used.
   :linenos:
 
   pdp_update:
-    name: xacml_1
-    pdp_type: xacml
-    description: XACML PDP running control loop policies, Upgraded
-    pdp_group: onap.pdpgroup.controlloop.operational
-    pdp_subgroup: xacml
+    source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
+    pdpHeartbeatIntervalMs: 120000
     policiesToBeDeployed:
-      - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
-          policy_type: onap.policies.controlloop.guard.FrequencyLimiter
-          policy_type_version: 1.0.1
-          properties:
-            # Omitted for brevity
-     - onap.policies.controlloop.guard.blackList.EastRegion:
-          policy_type: onap.policies.controlloop.guard.BlackList
-          policy_type_version: 1.0.1
-          properties:
-            # Omitted for brevity
-      - onap.policies.controlloop.guard.minmax.EastRegion:
-          policy_type: onap.policies.controlloop.guard.MinMax
-          policy_type_version: 1.0.1
-          properties:
-            # Omitted for brevity
+      - type: onap.policies.Naming
+        type_version: 1.0.0
+        properties:
+          # Omitted for brevity
+        name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
+        version: 1.0.1
+        metadata:
+          policy-id: onap.policies.controlloop.guard.frequencylimiter.EastRegion
+          policy-version: 1.0.1
+    messageName: PDP_UPDATE
+    requestId: cbfb9781-da6c-462f-9601-8cf8ca959d2b
+    timestampMs: 1633466294898
+    name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
+    description: XACML PDP running control loop policies, Upgraded
+    pdpGroup: defaultGroup
+    pdpSubgroup: xacml
+
 
 .. code-block:: yaml
   :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy
   :linenos:
 
   pdp_update:
-    name: drools_2
-    pdp_type: drools
-    description: Drools PDP running control loop policies, extra policy added
-    pdp_group: onap.pdpgroup.controlloop.operational
-    pdp_subgroup: drools
+    source: pap-0674bd0c-0862-4b72-abc7-74246fd11a79
+    pdpHeartbeatIntervalMs: 120000
     policiesToBeDeployed:
-      - onap.controllloop.operational.drools.vfw.WestRegion:
-          policy_type: onap.controllloop.operational.drools.vFW
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
+      - type: onap.controllloop.operational.drools.vFW
+        type_version: 1.0.0
+        properties:
+          # Omitted for brevity
+        name: onap.controllloop.operational.drools.vfw.WestRegion
+        version: 1.0.0
+        metadata:
+          policy-id: onap.controllloop.operational.drools.vfw.WestRegion
+          policy-version: 1.0.0
+    messageName: PDP_UPDATE
+    requestId: e91c4515-86db-4663-b68e-e5179d0b000e
+    timestampMs: 1633355039004
+    name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
+    description: Drools PDP running control loop policies, extra policy added
+    pdpGroup: defaultGroup
+    pdpSubgroup: drools
+
 
 .. code-block:: yaml
   :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy
   :linenos:
 
-    pdp_update:
-    name: apex_3
-    pdp_type: apex
-    description: APEX PDP updated to remove a control loop policy
-    pdp_group: onap.pdpgroup.controlloop.operational
-    pdp_subgroup: apex
-    policiesToBeDeployed: []
-    policiesToBeUndeployed:
-      - onap.controllloop.operational.apex.bbs.WestRegion:
-          policy_type: onap.controllloop.operational.apex.BBS
-          policy_type_version: 1.0.0
-          properties:
-            # Omitted for brevity
+  pdp_update:
+    source: pap-56c8531d-5376-4e53-a820-6973c62bfb9a
+    pdpHeartbeatIntervalMs: 120000
+    policiesToBeDeployed:
+      - type: onap.policies.native.Apex
+        type_version: 1.0.0
+        properties:
+          # Omitted for brevity
+        name: onap.controllloop.operational.apex.bbs.WestRegion
+        version: 1.0.0
+        metadata:
+          policy-id: onap.controllloop.operational.apex.bbs.WestRegion
+          policy-version: 1.0.0
+    messageName: PDP_UPDATE
+    requestId: 3534e54f-4432-4c68-81c8-a6af07e59fb2
+    timestampMs: 1632325037040
+    name: apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02
+    pdpGroup: defaultGroup
+    pdpSubgroup: apex
 
 2.2 PDP State Change
 --------------------
@@ -367,54 +354,43 @@ The *PDP_STATE_CHANGE* operation allows the PAP to order state changes on PDPs i
 following examples illustrate how the operation is used.
 
 .. code-block:: yaml
-  :caption: Change the state of all control loop Drools PDPs to ACTIVE
+  :caption: Change the state of Drools PDP to ACTIVE
   :linenos:
 
   pdp_state_change:
-    state: active
-    pdp_group: onap.pdpgroup.controlloop.Operational
-    pdp_subgroup: drools
+    source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
+    state: ACTIVE
+    messageName: PDP_STATE_CHANGE
+    requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
+    timestampMs: 1633466294899
+    name: drools-23d33c2a-8715-43a8-ade5-5923fc0f185c
+    pdpGroup: defaultGroup
+    pdpSubgroup: drools
 
 .. code-block:: yaml
-  :caption: Change the state of all monitoring PDPs to SAFE
+  :caption: Change the state of all XACML PDPs to ACTIVE
   :linenos:
 
   pdp_state_change:
-    state: safe
-    pdp_group: onap.pdpgroup.Monitoring
+    source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
+    state: ACTIVE
+    messageName: PDP_STATE_CHANGE
+    requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
+    timestampMs: 1633466294899
+    name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
+    pdpGroup: defaultGroup
+    pdpSubgroup: xacml
 
 .. code-block:: yaml
-  :caption: Change the state of a single APEX PDP to TEST
+  :caption: Change the state of APEX PDP to passive
   :linenos:
 
   pdp_state_change:
-    state: test
-    name: apex_3
-
-2.3 PDP Health Check
---------------------
-
-The *PDP_HEALTH_CHECK* operation allows the PAP to order health checks on PDPs in PDP groups and subgroups. The
-following examples illustrate how the operation is used.
-
-.. code-block:: yaml
-  :caption: Perform a health check on all control loop Drools PDPs
-  :linenos:
-
-  pdp_health_check:
-    pdp_group: onap.pdpgroup.controlloop.Operational
-    pdp_subgroup: drools
-
-.. code-block:: yaml
-  :caption: perform a health check on all monitoring PDPs
-  :linenos:
-
-  pdp_health_check:
-    pdp_group: onap.pdpgroup.Monitoring
-
-.. code-block:: yaml
-  :caption: Perform a health check on a single APEX PDP
-  :linenos:
-
-  pdp_health_check:
-    name: apex_3
+    source: pap-e6272159-e1a3-4777-860a-19c47a14cc00
+    state: PASSIVE
+    messageName: PDP_STATE_CHANGE
+    requestId: 60d9a724-ebf3-4434-9da4-caac9c515a2c
+    timestampMs: 1633528747518
+    name: apex-a3c58a9e-af72-436c-b46f-0c6f31032ca5
+    pdpGroup: defaultGroup
+    pdpSubgroup: apex