docs/development/actors/aai/aai.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _aai-label:
   6
   7 ##########
   8 A&AI Actor
   9 ##########
  10
  11 .. contents::
  12     :depth: 3
  13
  14 Overview of A&AI Actor
  15 ######################
  16 ONAP Policy Framework enables various actors, several of which require additional
  17 data to be gathered from A&AI via a REST call.  Previously, the request was built,
  18 and the REST call made, by the application.  However, A&AI queries have now been
  19 implemented using the new Actor framework.
  20
  21 Each operation supported by the actor is associated with its own java class, which is
  22 responsible for populating the request structure and invoking the REST service.  The
  23 class hierarchy is shown below.
  24
  25 .. image:: classHierarchy.png
  26
  27 Currently, the following operations are supported:
  28
  29 - Tenant
  30 - Pnf
  31 - CustomQuery
  32
  33 One thing that sets the A&AI Actor implementation apart from the other Actor
  34 implementations is that it is typically used to gather data for input to the
  35 other actors.  Consequently, when an A&AI operation completes, it places its
  36 response into the *properties* field of the *context*, which is passed via the
  37 *ControlLoopOperationParams*.  The names of the keys within the *properties*
  38 field are typically of the form, "AAI.<operation>.<targetEntity>", where
  39 "operation" is the name of the operation, and "targetEntity" is the *targetEntity*
  40 passed via the *ControlLoopOperationParams*.  For example, the response for
  41 the Tenant query for a target entity named "ozVserver" would be stored as a
  42 *properties* named "AAI.Tenant.ozVserver".
  43
  44 On the other hand, as there is only one "custom query" for a given ONSET, the
  45 *Custom Query* operation deviates from this, in that it always stores its response
  46 using the key, "AAI.AaiCqResponse".
  47
  48
  49 Request
  50 #######
  51
  52 Most of the the A&AI operations use "GET" requests and thus do not populate
  53 a request structure.  However, for those that do, the request structure is
  54 described in the table below.
  55
  56 Note: the Custom Query Operation requires tenant data, thus it performs a *Tenant*
  57 operation before sending its request.  The tenant data is gathered for the vserver
  58 whose name is found in the "vserver.vserver-name" field of the enrichment data provided
  59 by DCAE with the ONSET event.
  60
  61 +----------------------------------+---------+----------------------------------------------------------------------+
  62 | Field Name                       |  Type   |                         Description                                  |
  63 +----------------------------------+---------+----------------------------------------------------------------------+
  64 +----------------------------------+---------+----------------------------------------------------------------------+
  65 | Custom Query:                    |         |                                                                      |
  66 +----------------------------------+---------+----------------------------------------------------------------------+
  67 | *start*                          | string  |   Extracted from the *result-data[0].resource-link* field of the     |
  68 |                                  |         |   Tenant query response.                                             |
  69 +----------------------------------+---------+----------------------------------------------------------------------+
  70
  71
  72 Examples
  73 ########
  74
  75 Suppose the *ControlLoopOperationParams* were populated as follows, with the tenant
  76 query having already been performed:
  77
  78 .. code-block:: bash
  79
  80         {
  81             "actor": "AAI",
  82             "operation": "CustomQuery",
  83             "context": {
  84                 "enrichment": {
  85                     "vserver.vserver-name": "Ete_vFWCLvFWSNK_7ba1fbde_0"
  86                 },
  87                 "properties": {
  88                     "AAI.Tenant.Ete_vFWCLvFWSNK_7ba1fbde_0": {
  89                         "result-data": [
  90                             {
  91                                 "resource-type": "vserver",
  92                                 "resource-link": "/aai/v15/cloud-infrastructure/cloud-regions/cloud-region/CloudOwner/RegionOne/tenants/tenant/3f2aaef74ecb4b19b35e26d0849fe9a2/vservers/vserver/6c3b3714-e36c-45af-9f16-7d3a73d99497"
  93                             }
  94                         ]
  95                     }
  96                 }
  97             }
  98         }
  99
 100 An example of a Custom Query request constructed by the actor using the above
 101 parameters, sent to the A&AI REST server:
 102
 103 .. code-block:: bash
 104
 105         {
 106           "start": "/aai/v15/cloud-infrastructure/cloud-regions/cloud-region/CloudOwner/RegionOne/tenants/tenant/3f2aaef74ecb4b19b35e26d0849fe9a2/vservers/vserver/6c3b3714-e36c-45af-9f16-7d3a73d99497",
 107           "query": "query/closed-loop"
 108         }
 109
 110
 111 An example response received from the A&AI REST service:
 112
 113 .. code-block:: bash
 114
 115         {
 116             "results": [
 117                 {
 118                     "vserver": {
 119                         "vserver-id": "f953c499-4b1e-426b-8c6d-e9e9f1fc730f",
 120                         "vserver-name": "Ete_vFWCLvFWSNK_7ba1fbde_0",
 121                         "vserver-name2": "Ete_vFWCLvFWSNK_7ba1fbde_0",
 122                         "prov-status": "ACTIVE",
 123                         "vserver-selflink": "http://10.12.25.2:8774/v2.1/41d6d38489bd40b09ea8a6b6b852dcbd/servers/f953c499-4b1e-426b-8c6d-e9e9f1fc730f",
 124                         "in-maint": false,
 125                         "is-closed-loop-disabled": false,
 126             ...
 127         }
 128
 129
 130 Configuration of the A&AI Actor
 131 ###############################
 132
 133 The following table specifies the fields that should be provided to configure the A&AI
 134 actor.
 135
 136 =============================== ====================    ==================================================================
 137 Field name                         type                             Description
 138 =============================== ====================    ==================================================================
 139 clientName                        string                  Name of the HTTP client to use to send the request to the
 140                                                           A&AI REST server.
 141 timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
 142                                                           from the REST server.  Defaults to 90s.
 143 path                              string                  URI appended to the URL.  This field only applies to individual
 144                                                           operations; it does not apply at the actor level.  Note: the
 145                                                           *path* should not include a leading or trailing slash.
 146 =============================== ====================    ==================================================================
 147
 148 The individual operations are configured using these same field names.  However, all
 149 of them, except the *path*, are optional, as they inherit their values from the
 150 corresponding actor-level fields.