AIA API

Fetch inventory data through AIA API

In the CloudFabrix AIA application, users can use its RESTful API interface to query and get the inventory data.

Follow the below instructions to generate an access key and secret key for the logged-in user, which will be used for authentication while accessing the APIs.

Login into CloudFabrix AIA portal.

Click on Main Menu as shown below.

Click on Drop Down menu as shown below and click on Access Keys

Click on the + button to generate a new access key and secret key

Save the secret key from the pop-up window before closing it.

The access key is shown once the above pop-up window is closed.

Python-based API to get inventory data:

API Details and Usage:

Use below three APIs to query and get the inventory data:

• getReportRepositories - API for fetching all of the available repositories under the source lcm-manager-customer/asset-app-dependency within the AIA application.

• getReportsBySourceAndRepositoryName - API for fetching all available report definitions under 'assetLCMMaster' repository.

• getChartData_v1 - API for fetching the inventory data from a report, this API requires the url of the report (i.e. report-uri).

The API needs Source & Repository. These values are based on the page where the report resides in UI. Below table gives these values for different pages.

Page Name in UI	Source	Repository
Overall	lcm-manager-customer	assetLCMMaster
POR Insights	lcm-manager-customer	replacementProjection (or) assetLCMMaster
HW Assets	lcm-manager-customer	assetLCMMaster
SW Assets	lcm-manager-customer	assetLCMMaster
Contracts	lcm-manager-customer	contract-details
App Dependency	asset-app-dependency	adm
Assets List	lcm-manager-customer	assetLCMMaster

Each report in AIA has a Report ID in UUID format. Below are few example Report ID’s of some of the reports in AIA.

• Overall --> Assets by POR --> HW Devices POR Status (Report ID: cb0af4b2-60f3-4066-aefa-5d9afe36296e)

• Hardware --> HW Assets by POR --> HW Devices POR Status by Role (Report ID: 3aacdd76-5e89-41f1-bb46-ab81a0b4b1d1)

• Overview --> Apps by Site Code (Report ID: b2910f73-3ae7-4c02-b2af-5330f5b204b7)

Please follow the below instructions to download and use the python package.

Download the python package using the below command.

wget https://macaw-amer.s3.amazonaws.com/releases/AIA/caas-rest-client/caas-rest-client-v3.0.0.tar

The prerequisite is to have python 3.7.4 or above environment

Extract the Python package using the below command.

tar -xvf caas-rest-client-v3.0.0.tar

Configure the configfile.json with the user's access-key and secret-key

cd caas-rest-client

cat configfile.json

{
        "secure": true,
        "host": "<ip-address-of-cfxaia-platform>",
	"login-method": "access-key", 
	"access-key": "<access-key-id>", 
	"secret-key": "<secret-key-id>"
}

• host: AIA platform's IP address

• access-key: User's API access key id generated in the above steps

• secret-key: User's API secret key id generated in the above steps

Once configfile.json is configured with appropriate API credentials, run the below command to list all of the available reports and their metadata definitions. Save the output to a file to see all of the available report definitions.

python cfx_client.py --configfile configfile.json --get defs --app lcm-manager-customer --page assetLCMMaster

Report definitions are nothing but metadata of each widget (pie chart, tabular chart, etc..) available within the AIA portal under different pages/reports. Each report will have a URI path which will be used to query the data.

Below command provides an example URI of a report that fetches the inventory data of that report.

python cfx_client.py --configfile configfile.json --get report --uri "uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=56c98b9e-aa39-4cbd-9c42-e23d8012258a"

Use --curl option to see auto generated full curl command with syntax for the requested report.

python cfx_client.py --configfile configfile.json --get report --uri "uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=56c98b9e-aa39-4cbd-9c42-e23d8012258a" --curl

Use --filter option to apply the filters to limit the scope of the data from a report

python cfx_client.py --configfile configfile.json --get report --uri "uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=8cb11886-905a-409d-b988-18db5a957147" --filter "Equipment_Type in 'CHASSIS'"

Get report API syntax details:

python cfx_client.py --configfile configfile.json --get report --uri "<report-uri>” –filter “<filter-condition>” –debug

Get report API support the following options:

--configfile: location of the config file created (Instructions to create config file is in Page 1). 
--get report - Same for all reports
–filter “<filter condition>” - cfxql syntax is supported
--debug - Turn on debugging for this call (Optional)
--uri - Report URI contains the following parameters (Refer to Appendix A for different options of following parameters based on the report that is being accessed)
    Source: Source dataset name
            Repository - Location of the report file in minio
            Id - Report ID (Each report in AIA has an ID. Refer to Appendix B for getting ID of specific report) 
--totalresults - Inorder to get all results/rows of data
--nologout - Not to automatically logout from the session

Please refer CFXQL based filtering documentation for more information.

Python module:

To call RESTful APIs of AIA application, users can create their own python script with the help of macaw_helper python module provided in the above mentioned caas-rest-client package.

macaw_helper module takes care of session management by logging into the api gateway of AIA application automatically by using access-key, secret-key or by username and password.

Usage of macaw_helper python module:

1. Import 'macawclient' class from macaw_helper python module, and use 'myInvokeService' method in macawclient for API query.

2. Need to provide the configuration details while creating an instance to macawclient. Below is the example to pass configuration details to macawclient

from macaw_helper import Macawclient

config = {
           "secure": true,
            "host": "<ip-address-of-cfxaia-platform>",
            "login-method": "access-key", 
            "access-key": "<access-key-id>", 
            "secret-key": "<secret-key-id>"
    }
    
client = Macawclient(**config)

3. Use 'myInvokeService' method from macawclient to query any RESTful API. Below are the inputs needed for myInvokeService

Parameters:
    name: str (Name of the service)
    params: API input parameters (required to be in JSON formatted String)
    logout: bool, default True (True to logout after the API request, In scenarios like a series of continuous calls use logout=False)

4. Below are some of the examples to query an API using ‘myInvokeService’ from macawclient class

• To call "getReportsBySourceAndRepositoryName" api from reports-registry service for fetching all available report definitions under 'assetLCMMaster' repository

from macaw_helper import Macawclient
import json

config = {
           "secure": true,
            "host": "<ip-address-of-cfxaia-platform>",
            "login-method": "access-key", 
            "access-key": "<access-key-id>", 
            "secret-key": "<secret-key-id>"
    }
    
client = Macawclient(**config)

params = ["getReportsBySourceAndRepositoryName", 
json.dumps({"source": "lcm-manager-customer", "repository": "assetLCMMaster"})]

response = client.myInvokeService(name="reports-registry", params=params)

Each report definition from the above API response will have a report-uri string as shown in the below output, which is needed while querying the inventory data.

[
    {
                 "id": "61297c45-b6c6-4ee5-bb77-0751b4162348",
        "description": "Total Number of Vendors",
         "definition": {
        "dataset_tag": "asset-db:assetLCMMaster",
        "type": "COUNTER_TABLE",
        "title": "Total Number of Vendors",
        "limit": "10",
        "series_cols": [
         "Vendor"
        ],
        "function": "UNIQUE",
        "filter": null
     },
    "report-uri": "uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=61297c45-b6c6-4ee5-bb77-0751b4162348"
    }
]

• To call "getChartData_v1" api for fetching the inventory data from a report, this API requires url (i.e. report-uri)

from macaw_helper import Macawclient
import json

config = {
           "secure": true,
            "host": "<ip-address-of-cfxaia-platform>",
            "login-method": "access-key", 
            "access-key": "<access-key-id>", 
            "secret-key": "<secret-key-id>"
    }
    
client = Macawclient(**config)

filters = {
                   "column-id": "",
                   "column-label": "",
                   "condition": "",
                   "column-type": "pass-through",
                   "description": "",
                   "label": "",
                   "values": []
             }

payload = {
             "url": "uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=4f34527b-5657-4385-88cc-31cb0fe78538",
           "filters" : filters,
           "properties": {"offset": 0, "maxResults": 100},
           "no_cache": True
    }
            
params = ["getChartData_v1", json.dumps(payload)]

response = client.myInvokeService(name="dataset-caas", params=params, logout=False)

Native RESTful APIs to get inventory data:

Get API session auth token using the user's access key and secret key:

The below example shows how to run a curl command to get an API session auth token.

curl -k -X POST -H 'Content-Type: application/json' \ 
-d '{"login-method": "access-key", "access-key-id": "52249240-8909-48b5-879e-0df5801c831e", "secret-key": "d76f648f-9eb3-4213-9eea-8c40fb9232d4"}' \ 
https://10.95.117.30/api_gateway/login

API Response will include apiGatewaySessionId which needs to be used as an X-Auth-Token header in subsequent API queries to retrieve the data.

{"apiGatewaySessionId":"1674bd45-2c90-4229-9530-909e50ddf9ce",......

CloudFabrix AIA application's API needs Source & Repository details as input while querying the inventory data. These values are based on the page where the report resides in the AIA UI. The below table gives these values for different pages.

Page Name in UI	Source	Repository
Overall	lcm-manager-customer	assetLCMMaster
POR Insights	lcm-manager-customer	replacementProjection (or) assetLCMMaster
HW Assets	lcm-manager-customer	assetLCMMaster
SW Assets	lcm-manager-customer	assetLCMMaster
Contracts	lcm-manager-customer	contract-details
App Dependency	asset-app-dependency	adm
Assets List	lcm-manager-customer	assetLCMMaster

Below API query gets all of the available repositories under the source lcm-manager-customer within the AIA application

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: c8aa75d6-5bb4-42b4-8e75-f710edc14a6e' \
    -d '{"params": ["getReportRepositories", "{\"source\": \"lcm-manager-customer\"}"]}' \
        https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/reports-registry/1.0.0/invokeAppApi

API params:

• getReportRepositories: API to get existing repositories of a source within the AIA application.

  • source: Specify the source name. Supported values are listed in the above table

API Response:

[
    "admFilters",
    "contract-details",
    "projectionRateDictionary",
    "replacementProjection",
    "assetLCMMaster",
    "ipTelephony"
]

Below API query gets all available report definitions under 'assetLCMMaster' repository.

curl -k -X POST -H 'content-type: application/json' \ 
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["getReportsBySourceAndRepositoryName", "{\"source\": \"lcm-manager-customer\", \"repository\": \"assetLCMMaster\"}"]}' \
        https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/reports-registry/1.0.0/invokeAppApi

API params:

• getReportsBySourceAndRepositoryName: API to get available reports metadata/definition from a specified repository

  • source: Specify the source name of a repository. Supported values are listed in the above table

  • repository: Specify the repository name. Supported values are listed in the above table

Each report definition from the above API response will have a report-uri string like the below example output capture, which is needed while querying the inventory data from that report.

 [
    {
      "id": "61297c45-b6c6-4ee5-bb77-0751b4162348",
      "description": "Total Number of Vendors",
      "definition": {
        "dataset_tag": "asset-db:assetLCMMaster",
        "type": "COUNTER_TABLE",
        "title": "Total Number of Vendors",
        "limit": "10",
        "series_cols": [
          "Vendor"
        ],
        "function": "UNIQUE",
        "filter": null
      },
      "report-uri": "uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=61297c45-b6c6-4ee5-bb77-0751b4162348"
    }

Querying the Inventory data:

Example-1: For querying the inventory data from a report, API requires url (i.e. report-uri from the above API's response) and filters as input parameters as shown in the below example.

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["getChartData_v1", "{\"url\": \"uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=56c98b9e-aa39-4cbd-9c42-e23d8012258a\", \"filters\": []}"]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

API params:

• getChartData_v1: API to query the inventory data from a report, supports paginated data

• url: URI of a report from report repository to get the inventory data

• filters: (optional) supports CFXQL based filter syntax to filter the data.

  • column-type: pass-through (fixed value, mandatory)

  • values: CFXQL syntax based filter

Note: url and subsequent params need to be passed in stringified json format

Note: getChartData API to query the inventory data has been deprecated and it has been replaced with getChartData_v1 API. This new API has bug fixes and optimizations when querying the larger data with pagination support.

Example-2: In the below API example, apply the filter to query (using CFXQL format) Cisco vendor devices.

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d'{ "params": [ "getChartData_v1", "{\"url\": \"uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=27008245-2955-4d8f-bafe-17ae5ad57e8d\", \"filters\": [{\"column-type\": \"pass-through\", \"values\":[\"Vendor in '\''Cisco'\''\"]}]}]}" ]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

API params:

• getChartData_v1: API to query the inventory data from a report, supports paginated data

• url: URI of a report from report repository to get the inventory data

• filters: (optional) support CFXQL based filter syntax to filter the data.

  • column-type: pass-through (fixed value, mandatory)

  • values: CFXQL syntax based filter

Example-3: In the below API example, apply the filter to query (using CFXQL format) Cisco vendor devices and filter only Chassis out of them.

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d'{ "params": [ "getChartData_v1", "{\"url\": \"uri:///reports?source=lcm-manager-customer&repository=assetLCMMaster&id=27008245-2955-4d8f-bafe-17ae5ad57e8d\", \"filters\": [{\"column-type\": \"pass-through\", \"values\":[\"Vendor in '\''Cisco'\'' & Equipment_Type in ['\''CHASSIS'\'', '\''chassis'\'']\"]}]}]}" ]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

Example-4: In the below API example, it uses the below API properties to query the inventory data from a paginated report.

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["getChartData_v1", "{\"url\": \"uri:///reports?source=asset-app-dependency&repository=adm&id=e88c7caa-db83-4c0c-af19-7ef247d4914d\", \"filters\": [], \"properties\": {\"offset\": 0, \"maxResults\": 1000}, \"no_cache\": true}"]}'  \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

API params:

• getChartData_v1: API to query the inventory data from a report, supports paginated data

• url: URI of a report from report repository to get the inventory data

• filters: (optional) supports CFXQL based filter syntax to filter the data.

  • column-type: pass-through (fixed value, mandatory)

  • values: CFXQL syntax based filter

• properties: (for paginated reports)

  • offset: 0-n (starts from 0)

  • maxResults: 1 to 5000 (default: 20) - records per paginated query.

Get inventory data from dataset tags through API:

Dataset tags are the raw data source tables for all of the reports in the UI. Below are the two available APIs to query the inventory data from dataset tags.

• getDatasetTags: To query and list all the available dataset tags.

• executeCFXQLQuery: To query a specific dataset tag and retrieve the inventory data from it using CFXQL based filters. This API also support, querying only selective columns from the selected dataset tag.

Dataset Tags list:

Name	Description
asset-db:assetLCMMaster	Datasource of network devices inventory data that includes Chassis, Module, Power Supplies, aggregated interfaces state data etc. (UI Reference: AIA --> Assets List --> Network --> Assets Details)
asset-db:all_cdp	Datasource of network device's CDP neighbors data (UI Reference: AIA --> Assets List --> Network --> CDP Neighbors)
asset-db:aia_interface_poe	Datasource of network device's Interface states along with PoE data (UI Reference: AIA --> Hardware --> Network --> HW Assets by PoE)
asset-db:adm-apps	Datasource of network device's end point connectivity data (a.k.a ADM: application (hosts) dependency mapping) (UI Reference: AIA --> App Dependency). It includes all of the raw columns related to App Dependency data.
asset-db:adm-apps-network-overview	Datasource of network device's end points and applications summary reports (UI Reference: AIA --> App Dependency --> Overview)
asset-db:adm-apps-network	Datasource of network device's detailed information and brief information connected applications (UI Reference: AIA --> App Dependency --> Device Details)
asset-db:adm-apps-applications	Datasource of network device's brief information and detailed information on connected applications (UI Reference: AIA --> App Dependency --> App Details)

Below API example queries list of available dataset tags from AIA application.

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["getDatasetTags", "{\"context\": null}"]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

API params:

• getDatasetTags: API to query the list of available dataset tags

• context: null (fixed value, mandatory)

Querying the Inventory data from Dataset Tags:

Example-1: Below API example queries the specified dataset tag 'asset-db:assetLCMMaster' and gets the inventory data. By default i gets only 20 records in the response.

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["executeCFXQLQuery","{\"tag\":\"asset-db:assetLCMMaster\", \"cfxql_query\": \"*\"}"]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

API params:

• executeCFXQLQuery: To query a specific dataset tag and retrieve the inventory data from it using CFXQL based filters. This API also support, querying only selective columns from the selected dataset tag.

• tag: dataset tag name (mandatory: please refer the above dataset tags table for more information)

• cfxql_query: CFXQL query with or without 'GET' columns option. * means get all columns without applying any filters.

Example-2: Below API example queries the specified dataset tag 'asset-db:assetLCMMaster' and get first 1000 records from the inventory data. It supports paginated reports.

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["executeCFXQLQuery","{\"tag\":\"asset-db:assetLCMMaster\", \"offset\": 0, \"maxResults\": 1000, \"cfxql_query\": \"*\"}"]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

API params:

• executeCFXQLQuery: To query a specific dataset tag and retrieve the inventory data from it using CFXQL based filters. This API also support, querying only selective columns from the selected dataset tag.

• tag: dataset tag name (mandatory: please refer the above dataset tags table for more information)

• offset: 0-n (starts from 0)

• maxResults: 1 to 1000 (default: 20) - records per paginated query.

• cfxql_query: CFXQL query with or without 'GET' columns option. * means get all columns without applying any filters.

Example-3: Below API example queries the specified dataset tag 'asset-db:assetLCMMaster' and get first 1000 records from the inventory data after applying a filter to limit the records to Equipment_Type is 'CHASSIS'

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["executeCFXQLQuery","{\"tag\":\"asset-db:assetLCMMaster\", \"offset\": 0, \"maxResults\": 1000, \"cfxql_query\": \"Equipment_Type in '\''CHASSIS'\''\"}"]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

Note: In this executeCFXQLQuery API query, within the cfxql_query filter, for single quoted values (applicable for both filter values and selected columns to be reported as different names), each single quote need to be escaped in a specific format as shown in the above example. i.e. ' (each single quote) --> '\'' (escaped with single quote, back slash followed by 2 single quotes)

Example-4: Below API example queries the specified dataset tag 'asset-db:assetLCMMaster' and get first 1000 records from the inventory data after applying a filter to limit the records to Equipment_Type is 'CHASSIS' with only selected columns. (get IP_Address, DNS_Name, customerName as 'Customer Name')

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["executeCFXQLQuery","{\"tag\":\"asset-db:assetLCMMaster\", \"offset\": 0, \"maxResults\": 1000, \"cfxql_query\": \"Equipment_Type in '\''CHASSIS'\'' get IP_Address, DNS_Name, customerName as '\''Customer Name'\'' \"}"]}' \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi

Example-5: Below API example queries the specified dataset tag 'asset-db:assetLCMMaster' and get first 1000 records from the inventory data after applying a filter to limit the records to Equipment_Type is 'CHASSIS', Vendor is 'Cisco' & Site_Type is 'Data Center' with only selected columns. (get IP_Address, Hostname, Region, Site)

curl -k -X POST -H 'content-type: application/json' \
    -H 'X-Auth-Token: 1674bd45-2c90-4229-9530-909e50ddf9ce' \
    -d '{"params": ["executeCFXQLQuery","{\"tag\":\"asset-db:assetLCMMaster\", \"offset\": 0, \"maxResults\": 1000, \"cfxql_query\": \"Equipment_Type in '\''CHASSIS'\'' & Vendor in '\''Cisco'\'' & Site_Type in '\''Data Center'\''  get IP_Address, Hostname, Region, Site\"}"]}'  \
    https://10.95.117.30:443/api_gateway/service/io.cfx.dimensions.app/dataset-caas/1.0.0/invokeAppApi