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
Asset List
Next - Asset Intelligence Analytics (AIA) Solution
Enterprise Discovery
Last modified 3mo ago
Copy link
On this page
Python-based API to get inventory data:
Native RESTful APIs to get inventory data:
Get inventory data from dataset tags through API: