<UNDER CONSTRUCTION>

Table of Contents

Introduction

A&AI (Active and Available Inventory) is implemented using a graph database. A graph database is an online database management system with Create, Read, Update and Delete (CRUD) operations working on a graph data model.

The A&AI REST API provides access to the A&AI active inventory graph.  The API is largely configured off of models and configuration files.  Each vertex in the graph has an API that can be called separately or, if part of a tree structure, as a nested element with one or more generations (parent, grandparent, etc.).

The edges of the graph are provisioned using a relationship list construct.  For PUT methods, a relationship contains the vertex type or category (related-to) and a URI that provides the identity of the resource within A&AI.  The URI can be used with the server root  to call A&AI to get more details of the related resource but cannot be cached for long periods.   (e.g., the version of the URI may get deprecated when the release changes).

The REST API describes each API that A&AI provides, independent of the caller of the API, therefore there is no information to be found here regarding the expectations on the callers.  That information is conveyed in AID documents for each client.  AIDs will describe the information expected from specific clients, but may not contain the full payloads that would be needed on an update.  Please see the concurrency notes referenced below in order to do the right kind of PUTs (GET, replace just what you are changing, PUT) or use the PATCH capability.

Features of Release 10 can be found here: {needs link to A&AI document}

AAIService API

AAIService is an implementation of a REST API  client for SDNC-ADAPTORS feature.  It exposes its CRUD services through SvcLogicResource interface.

The most common utilization of AAIService is done in SLI DirectedGraph

Below are snippets of working directed graph code.

Plugin simply tells DirectedGraph we want to use the AAIService so the value will always be the same for any nodes using AAIService.

Resource - is a node type identifier. In general It must match the name found in A&AI documentation (xsd or html file). When invoking search services, resource can be set to nodes-query or named-query.

Key is a set of name-value pairs identifying the node.

pfx is short for prefix. if data is being retrieved this is where AAIService will write the data to in context memory.

force and local-only apply to some of the nodes. Values of these parameters are ignored in AAIService.

Create:<save/>

Save should be used when the caller wants to create a new resource in A&AI.

<save 
	plugin="org.onap.ccsdk.sli.adaptors.aai.AAIService" 
	resource="generic-vnf" 
	key="generic-vnf.vnf-id = $service-configuration-operation-input.ucpe-vms-service-information.vnf-list.vnf-information[0].vnf-id" 
	force="true" 
	local-only="false" 
	pfx="tmp.AnAI-data.vnf" > 
<parameter name="link-name" value="ckt126" />
<parameter name="circuit-id" value="DHEC.155095.ACC" />
<parameter name="speed-value" value="1000" />
<parameter name="speed-units" value="Mbps" />
<parameter name="dual-mode" value="Active" />
</save>

Delete

Delete should be used when the caller wants to remove a resource in A&AI.

<delete 
	plugin="org.onap.ccsdk.sli.adaptors.aai.AAIService" 
	resource="generic-vnf" 
	key="generic-vnf.vnf-id = $mypath.myvalue" >
</delete>

Retrieve: <get-resource/>

Get-resource should be used when the caller wants to retrieve an existing resource from A&AI. The caller must pass the key of the resource. If the resource is a child the keys of the resource's parent must be passed as well.

<get-resource plugin="org.onap.ccsdk.sli.adaptors.aai.AAIService" 
resource="vserver" 
key="vserver.vserver-name = $vnf-id" 
local-only="false" 
pfx="vnfProfile" />

update

Update should be used when the caller wants to update an existing resource in A&AI.

<update plugin="org.onap.ccsdk.sli.adaptors.aai.AAIService" 
resource="logical-link"   
key="logical-link.link-name = $vserver-id"   
force="true" 
local-only="false" 
pfx="tmp.AnAI-data.vnf" >
<parameter name="link-name" value="ckt126" />
<parameter name="circuit-id" value="DHEC.155095.ACC" />
<parameter name="speed-value" value="1000" />
<parameter name="speed-units" value="Mbps" />
<parameter name="dual-mode" value="Active" />
</update>

Understanding AAI Documentation

Before you start defining path identifiers in the key, you need to download the document listing all paths in AAI. . If you don't have access to this community you may need to request it.

Two important document each DirectedGraph developer should become familiar with are:

• the XSD document: {link is missing}
• the AAI index document {link is missing}

The XSD document defines the AAI model.

The Index document lists all API paths supported.

When viewing these documents the viewer should be able to:

• Identify the parent-child relationship among resources
• See all of the possible attributes for a resource
• Identify the keys required for a given resource

AAIService is tightly coupled to the A&AI schema. By viewing the AAI schema you get both insight into A&AI as well as AAIService.

Example of Using The HTML file

The v11_aai_index.html document lists paths supported by AAI REST API.

The path may contain multiple nodes. Each node is identified by the node type and its primary id.

If we look at vserver we can see it has the attributes vserver-id, vserver-name, vserver-name2, etc.

Vserver is quite indented in this document. If it appears under another resource it is a child of that resource.

From looking at the document we should be able to see how the full path is constructed

/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}/tenants/tenant/{tenant-id}/vservers/vserver/{vserver-id}

How to select right resource for AAIService

There are 3 types of resource names used by AAIService:

1. name of the data type to be used by the request. Names of these types have to match the names of data types supported by AAI, as defined in AAI documentation, usually aai_schema_vX.xsd, where X represents the release number in AAI system. Examples are: generic-vnf, pserver, tenant, and so on.
2. Extended name for processing of relationship-list. It consists of the data type from item 1 appended with ":relationship-list". This is used for adding/deleting relationship data to existing nodes.
3. Special functions: Currently there are 2 special functions: named-query and nodes-query.

How to create the key string for AAIService

The key string contains the identifiers of the elements in the path.

For example the path for generic-vnf looks as follows: /network/generic-vnfs/generic-vnf/{vnf-id}/. Each field enclosed in braces represents a key, so in this example {vnf-id}.

In the directed graph node the key needs to follow the format resource-name.resource-key. For this example attribute will appear as

key="generic-vnf.vnf-id = '$Some-value'"

Not that the key string does not use back ticks! Many developers think these are necessary and include them in error.

If you have a child resource its path will contain keys pertaining to its parent resources.

The path for vserver is below

/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}/tenants/tenant/{tenant-id}/vservers/vserver/{vserver-id}

In this case we have the following variables that need to be included in the key. They are:

• cloud-owner
• cloud-region-id
• tenant-id
• vserver-id

Since we have to include resource name with the identifier, the keys will be looking as follows:cloud-owner

• cloud-region.cloud-owner
• cloud-region.cloud-region-id
• tenant.tenant-id
• vserver.vserver-id

Below is an example of what this node might look like. Note that when multiple key fields are used they must be AND'ed together like below. (Note: use spaces around AND as well as around equal sign) 

<save plugin="org.onap.ccsdk.sli.adaptors.aai.AAIService"
      resource="vserver"
      key="cloud-region.cloud-owner = '$a' AND cloud-region.cloud-region-id = '$b' AND tenant.tenant-id = '$c' AND vserver.vserver-id = '$d'"
      force="true"
      local-only="false"
      pfx="tmp.AnAI-Assign-VNFs.AAI.VSERVER.RT">

Special key names

selflink

In some situations the developer may know the path to the resource, for example after calling nodes-query, the response contains the resource type and resource link.
To address such case, AAIService provides a special key name to be used to retrieve the data. The key name is 'selflink'. Developer can use returned resource-link to pass it to <get-resource> node.

The DG node to retrieve data using selflink is:

<get-resource 
  plugin="org.onap.ccsdk.sli.adaptors.aai.AAIService"
  resource="service-instance"  
  key="selflink = https://aai.test.onap.org:8443/aai/v9/business/customers/customer/PerfTestCust00020021/service-subscriptions/service-subscription/Gamma-L2/service-instances/service-instance/d5dd0e08-98c2-40da-b262-4ae4f4cf8d3f"  
  local-only="false"  
  pfx="vnfProfile" />  

depth

If you take for example the sub-paths starting with generic-vnf, user may not want to be retrieving full graphs that exists for an instance of generic-vnf, in which case retrieving the entire graph would be unnecessary but also may lead to straining the resources.

/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id} 
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/vf-modules/vf-module/{vf-module-id}                                                                                                                               
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/licenses/license/{group-uuid}/{resource-uuid}                                                                                                                       
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/entitlements/entitlement/{group-uuid}/{resource-uuid}                                                                                                           
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/l-interfaces/l-interface/{interface-name}/vlans/vlan/{vlan-interface}/l3-interface-ipv4-address-list/{l3-interface-ipv4-address}
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/l-interfaces/l-interface/{interface-name}/vlans/vlan/{vlan-interface}/l3-interface-ipv6-address-list/{l3-interface-ipv6-address}
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/l-interfaces/l-interface/{interface-name}/vlans/vlan/{vlan-interface}                                                                                      
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/l-interfaces/l-interface/{interface-name}/sriov-vfs/sriov-vf/{pci-id}                                                                                  
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/l-interfaces/l-interface/{interface-name}/l3-interface-ipv4-address-list/{l3-interface-ipv4-address}                             
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/l-interfaces/l-interface/{interface-name}/l3-interface-ipv6-address-list/{l3-interface-ipv6-address}                             
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/l-interfaces/l-interface/{interface-name}                                                                                                                       
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}/l-interfaces/l-interface/{interface-name}/vlans/vlan/{vlan-interface}/l3-interface-ipv4-address-list/{l3-interface-ipv4-address}
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}/l-interfaces/l-interface/{interface-name}/vlans/vlan/{vlan-interface}/l3-interface-ipv6-address-list/{l3-interface-ipv6-address}
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}/l-interfaces/l-interface/{interface-name}/vlans/vlan/{vlan-interface}                          
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}/l-interfaces/l-interface/{interface-name}/sriov-vfs/sriov-vf/{pci-id}                      
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}/l-interfaces/l-interface/{interface-name}/l3-interface-ipv4-address-list/{l3-interface-ipv4-address}
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}/l-interfaces/l-interface/{interface-name}/l3-interface-ipv6-address-list/{l3-interface-ipv6-address}
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}/l-interfaces/l-interface/{interface-name}                                                           
/aai/v11/network/generic-vnfs/generic-vnf/{vnf-id}/lag-interfaces/lag-interface/{interface-name}                                                                                                                 
 

To improve the performance of AAI database queries, the AAI system controls the amount of data being returned By default it will return the first layer or depth of zero layer, plus relationship list.

For users interested in getting sub-layers or data, AAI provides an option to specify the depth of the data to be returned. AAIService supports depth selection through key string. Simply add " AND depth = 1 " to the KEY string.

<get-resource plugin="org.onap.ccsdk.sli.adaptors.aai.AAIService" 
resource="generic-vnf" 
key="generic-vnf.vnf-is = $vnf-id AND depth = 'all'" 
local-only="false" 
pfx="vnfProfile" /> 

Difference between <save> and <update>

When writing data the developer should understand the difference between <save> and <update>.

• <save> command creates a new data entry, It can be compared to SQL INSERT command. Use this command to write new data entry to AAI datastore..
• <update> command modifies the state of existing data entry. It can be compared to SQL UPDATE command. Use this command to modify/update existing data entry in AAI datastore..

It is critical to follow this rule as <save> command will fail if the data entry with the same id already exists.