Events
------

Events execute Provisioning Workflows in response to a
trigger. The trigger is an operation that is carried out on 
a selected model. The available actions for a selected model
define the list of available operations.

Event instances to trigger are searched for as follows:
the lower of:

* the transaction hierarchy (in other words the transaction "breadcrumb") 
* the triggering resource hierarchy 

When an Event instance is defined, the following 
values are specified:

* Workflow - the created Provisioning Workflow is selected.
* Active - if the Event is to be enabled, it is set to be active.
  This means events can be created without being active.
* Model Type - This is a part of the transaction. Operations 
  on Model Types define the transaction.
* Operation	- the available operations depend on the selected Model Type.	
* Phase	- the event can take place before or after the defined transaction.
  For example, if the Create Operation is available for the Model Type and
  the Phase is Pre Execution, then the event workflow is run *before* the
  Create Operation.
* Synchronous - if enabled, the transaction is only carried out
  if the HTTP response from the HTTP request in the workflow shows
  the request was received, in other words the response is of the 
  format ``HTTP 2xx``. If the Event is not set to be Synchronous,
  in other words it is asynchronous, the transaction is carried 
  out regardless of the HTTP response.


  .. warning::

     Always enable events as Synchronous, unless there is a good reason to set
     an event as asynchronous. Failed asynchronous events do not roll back
     the triggering transaction and can lead to unexpected issues. 


.. Firstly when looking upwards for events to trigger in the transaction code, 
   the lower of the transaction (execution / breadcrumb) or the triggering 
   instance hierarchy is used. If a matching event is lower then either of 
   these hierarchies, then that event will not trigger.

.. Secondly, when looking upwards for workflows to run in the event code, 
   the lower of the transaction (execution / breadcrumb) or the event 
   instance hierarchy is used. If the workflow instance is located 
   below either of these hierarchies, then the workflow execution 
   txn will fail with an error message like "Workflow not found 
   [site_event at or above hierarchy 5d1b7461a9d1cb0007a78b20]". 
   I am told that workflows are never located like this in 
   production, so this should be acceptable.

A hierarchy context of the selected model is available to a Workflow in 
the case of events. In the case where a model allows for a Move operation 
and a Post Execution Phase is specified, this hierarchy value would be 
changed to the new hierarchy.

Consider for example the following transaction context data: ::

    Pre event hierarchy: 5404f304c8e69d774458660e
    Post event hierarchy: 5404f711c8e69d774458a92a

    device/cucm/User Pre Asynchronous move:
    
    
    Step 0 - Executing workflow (testEVPWF) with the following context data: 
     {
        "input": {
            "device_pkid": "5404f345c8e69d7744586676"
        }, 
        "trigger": {
            "model_type": "device/cucm/User", 
            "phase": "preexecution", 
            "operation": "move", 
            "trigger_model_type": "data/Event", 
            "name": "testEV_cucmUser_Pre_async_move"
        }, 
        "resource_meta": {
            "model_type": "device/cucm/User", 
            "pkid": "5405ba26c8e69d77445b8769", 
            "hierarchy": "5404f304c8e69d774458660e", 
            "device_pkid": "5404f345c8e69d7744586676"
        }, 
    
    
    device/cucm/User Post Asynchronous move:
    
    
    Step 0 - Executing workflow (testEVPWF) with the following context data: 
     {
        "input": {
            "device_pkid": "5404f345c8e69d7744586676"
        }, 
        "trigger": {
            "model_type": "device/cucm/User", 
            "phase": "postexecution", 
            "operation": "move", 
            "trigger_model_type": "data/Event", 
            "name": "testEV_cucmUser_Post_async_move"
        }, 
        "resource_meta": {
            "model_type": "device/cucm/User", 
            "pkid": "5405ba26c8e69d77445b8769", 
            "hierarchy": "5404f711c8e69d774458a92a", 
            "device_pkid": "5404f345c8e69d7744586676"
        },


The Provisioning Workflow is triggered from the lower of: the transaction hierarchy
(eg. breadcrumb) and the hierarchy where the event instance is located.

To override this hierarchy in order
that the workflow is run in the target hierarchy, use the 
``{{ resource_meta.hierarchy }}`` macro for the workflow context hierarchy.

For example: ::
  
  
 {
    "meta": {},
    "resources": [
       {
          "meta": {
              "model_type": "data/ProvisioningWorkflow",
              "pkid": "53fde2d02afa4356c87e45c4",
              "schema_version": "0.3.9",
              "hierarchy": "sys",
              "tags": []
          },
           "data": {
              "name": "__post_event_test",
              "parameters": {
                 "max_workers": "1",
                 "parallel": "false"
              },
              "workflow": [
                 {
                   "entity_type": "model",
                   "hierarchy": "{{ resource_meta.hierarchy }}",
                   "entity": "data/Countries",
                   "method": "refresh",
                   "advanced_find_options": [
                       {
                           "model_attribute": "iso_country_code",
                           "mapped_value": "USA"
                       }
                     ],
                   "advanced_find_search_direction": "full_tree"
                 }
              ]
           }
       }
    ]
  }
  


.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM