Initial set of documentation

This is where I am at with documentation, getting it
up so Chenfei and Liam can help me with it.

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

1 files changed, 57 insertions, 0 deletions

diff --git a/docs/design/tosca-policy-primer.rst b/docs/design/tosca-policy-primer.rst
new file mode 100644
index 00000000..bc35abc7
--- /dev/null
+++ b/docs/design/tosca-policy-primer.rst
@@ -0,0 +1,57 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _tosca-label:
+
+TOSCA Policy Primer
+-------------------
+
+.. contents::
+    :depth: 1
+
+Policy Type
+~~~~~~~~~~~
+
+A Policy Type is used to specify the types of policies that may be used in a service. The parameter definitions for a policy of this type, the entity types to which it applies, and what triggers policies of this type may be specified.
+
+The types of policies that are used in a service are defined in the policy_types section of the TOSCA service template as a Policy Type. More formally, TOSCA  defines a Policy Type as an artifact that "defines a type of requirement that affects or governs an application or service’s topology at  some stage of its lifecycle, but is not explicitly part of the topology itself". In the definition of a Policy Type in TOSCA, you specify:
+
+* its properties, which define the type of configuration parameters that the policy takes
+* its targets, which define the node types and/or groups to which the policy type applies
+* its triggers, which specify the conditions in which policies of this type are fired
+
+Policy
+~~~~~~
+
+A Policy is used to specify the actual instances of policies that are used in a service. The parameter values of the policy and the actual entities to which it applies may be specified.
+
+The policies that are used in a service are defined in the policies section of the TOSCA topology template as a Policy. More formally, TOSCA  defines a Policy as an artifact that "defines a policy that can be associated with a TOSCA topology or top-level entity definition". In the definition of a Policy in TOSCA, you specify:
+
+* its properties, which define the values of the configuration parameters that the policy takes
+* its targets, which define the node types and/or group types to which the policy type applies
+
+Note that policy triggers are specified on the Policy Type definition and are not specified on the Policy itself.
+
+Trigger
+~~~~~~~
+
+A Trigger defines an event, condition, and action that is used to initiate execution of a policy associated with it. The definition of the Trigger allows specification of the type of events to trigger on, the filters on those events, conditions and constraints for trigger firing, the action to perform on triggering, and various other parameters.
+
+The triggers that are used in a service are defined as reusable modules in the TOSCA service template as a Trigger. More formally, TOSCA  defines a Trigger as an artifact that "defines the event, condition and action that is used to “trigger” a policy it is associated with". In the definition of a Trigger in TOSCA, you specify:
+
+* its event_type, which defines the name of the event that fires the policy
+* its schedule, which defines the time interval in which the trigger is active
+* its target_filter, which defines specific filters for firing such as specific characteristics of the nodes or relations for which the trigger should or should not fire
+* its condition, which defines extra conditions on the incoming event for firing the trigger
+* its constraint, which defines extra conditions on the incoming event for not firing the trigger
+* its period, which defines the period to use for evaluating conditions and constraints
+* its evaluations, which defines the number of evaluations that must be performed over the period to assert the condition or constraint exists
+* its method, the method to use for evaluation of conditions and constraints
+* its action, the workflow or operation to invoke when the trigger fires
+
+Note that how a Trigger actually works with a Policy is not clear from the specification.
+
+
+End of Document
+