Collection Operations

This section contains a collection of CRUD operations that supports add/modify/delete actions. Multiple documents can be added in a single request and it can be updated/deleted based on the query.

Before you begin

Before attempting to use collection operations, you must ensure that the following permissions are available:
  • Workflow > Collection > Action > Create/Modify
  • Workflow > Collection > User Preference > Show Collection.
You can check this in the Platform module under IDENTITY > Role > Authorized functions.

Request Structure

Endpoint: /collection-operations
Type: POST
Sample URL: https://<IP/HostName/TenantName>:<GWPORT>/avxapi/collection-operations?gwsource=external

To understand the elements of the sample URL, click here.
Headers:
Content-Type: application/json
Table 1. Input Parameters
Name Description
sessionID

Header

 (Mandatory) Use session ID retrieved from login API is required if username and password are not provided.

Example: "sessionId": "ce7f1a14-2bf9-4e4a-89a8-bc780a255813"
username

Header

 (Mandatory) AppViewX login username is required if sessionId is not provided.

Example: "admin"
password

Header

 (Mandatory) AppViewX login password is required if sessionId is not provided..

Example: "AppViewX@123"
Content-Type

Header

 (Mandatory) The parameter should be set to application/json to specify the nature of the data in the payload.

Example: "application/json"
gwsource

Query

 (Mandatory) Source from which the request is triggered. The values can be:
  • web
  • external
Payload (Mandatory) Input data for request body in application/json format. For payload details, see Payload section.

Payload

Name Description
action

String

 (Mandatory) Action that has to be performed to the collection. Possible values are "add", "modify", and "delete".

Example: "add"
query

JSON

 (Optional) Query to update/delete the collections document. (Mandatory if the action is “modify” or “delete”).

Example: ""deviceName": "F5""
update

JSON

 (Mandatory) Fields to be updated/deleted in the collection (Mandatory if the action is "modify").

Example:

"fieldId": "device.connectionType",

"value": "wlan0",

"action": "overwrite"
update.fieldId

String

 (Optional) Identifier key of the field that has to be updated.

Example: "device.Bcast"
update.value

JSON

 (Optional) Values to be updated against the field identifier.

Example: ""
update.action

String

 (Optional) Action to be performed on the field. Possible values are "overwrite", "append", and "remove".

Example: "remove"
documents

JSON

 (Optional) Documents that have to be inserted to the collection. (Mandatory if the action is "add").

Example: ""
collection

String

 (Mandatory) Collection name that has to be updated.

Example: "test"

Response Structure

  • Status Code: 200 Added/Updated/Deleted
  • Message: Data added/Updated/Deleted successfully
  • Headers:
    • Content-Type: application/json
Table 2. Response Parameters
Name Description
response

Key value pair

 Contains the response object along with the hierarchy of the object mapped in field children.
message

String

 Success message or failure description in case of error.
appStatusCode

String

 Application specific status code for the response. Will be non-null for failure response.
tags

NA

 More info in case of failure response.

Status Codes

HTTP Code appStatusCode Message and Remediation
200 Added/Updated/Deleted NA Data added/Updated/Deleted successfully.
400 Bad Request NA The payload is not proper.
404 Not Found NA If the collection does not exist.

Sample Request/Response

Use Case: Add Document

Add the documents to the collections.

Request URL
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/collection-operations?gwsource=external
Request Payload
{
"payload": {
“collection”:”test” 
"action": "add", 
"documents": [
{
"deviceName": "F5",
"ip": "1.2.3.4"
},
{
"deviceName": "A10",
"ip": "15.25.35.45"
}
]
}
}
Sample Response
{
"response": "Data added successfully", 
"message": "Data added successfully", 
"appStatusCode": null,
"tags": null, 
"headers": null
}

Sample Request/Response

Use Case: Delete Document

Delete the documents from the collections.

Request URL
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/collection-operations?gwsource=external
Request Payload
{
"payload": {
“collection”:”test” 
"action": "delete", 
"query": { 
"deviceName": "F5"
}
}
}
Sample Response
{
"response": "Data deleted successfully", 
"message": "Data deleted successfully", 
"appStatusCode": null,
"tags": null, 
"headers": null
}

Sample Request/Response

Use Case: Update the Field (String or Numeric) Value

Modify the field (String or Numeric) value of the document.

Request URL
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/collection-operations?gwsource=external
Request Payload
{
"payload": {
“collection”:”test” 
"action": "modify", 
"query": { "deviceName": "A10"
},
"update": [
{
"fieldId": "IP", "value": "4.5.6.7",
"action": "overwrite"
}
]
}
}
Sample Response
{
"response": "Data updated successfully", 
"message": "Data updated successfully", 
"appStatusCode": null,
"tags": null, 
"headers": null
}
Sample Document
{
deviceName:"A10", IP:"1.2.3.4",
port:[99]
}
Updated Document
{
deviceName:"A10", IP:"4.5.6.7",
port:[99]
}

Sample Request/Response

Use Case: Append the Values into Existing Array Field

Append the values into an existing array field of a collection document.

Request URL
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/collection-operations?gwsource=external
Request Payload
{
"payload": 
	“collection”:”test” 
        "action": "modify", 
        "query": { "deviceName": "A10"
},
"update": [
{
"fieldId": "port",
"value": [22,55,66],
"action": "append"
}
]
}
}
Sample Response
{
"response": "Data updated successfully", 
"message": "Data updated successfully", 
"appStatusCode": null,
"tags": null, 
"headers": null
}
Sample Document
{
deviceName: "A10", IP: "1.2.3.4",
port: [99]
}
Updated Document
{
deviceName: "A10", IP:"4.5.6.7",
port:[99,22,55,66]
}

Sample Request/Response

Use Case: Modify the Nested Field Values

Modify the field values of a json object in a collection document.

Request URL
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/collection-operations?gwsource=external
Request Payload
{
"payload": {
“collection”:”test” 
"action": "modify", 
"query": { "deviceName": "F5"
},
"update": [
{
"fieldId": "device.connectionType", 
"value": "wlan0",
"action": "overwrite"
}
]
}
}
Sample Response
{
"response": "Data updated successfully", 
"message": "Data updated successfully", 
"appStatusCode": null,
"tags": null, 
"headers": null
}
Sample Document
{
device: {
name: "F5",
ipV6: "fe80::e206:e6ff:fe23:e07/64", 
connectionType: "eth0",
location: { dataCenter: "US",
clusterNodeId: "234rfg23456udcv"
}
}
}
Updated Document
{
device: {
name: "F5",
ipV6: "fe80::e206:e6ff:fe23:e07/64", 
connectionType: "wlan0",
location: { dataCenter: "US",
clusterNodeId: "234rfg23456udcv"
}
}
}

Sample Request/Response

Use Case: Modify by Removing a Field from an Existing Document

Modifying a document by removing a field.

Request URL
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/collection-operations?gwsource=external
Request Payload
{
"payload": {
“collection”:”test” 
"action": "modify", 
"query": { "deviceName": "F5"
},
"update": [
{
"fieldId": "device.Bcast", 
"action": "remove"
}
]
}
}
Sample Response
{
"response": "Data updated successfully",
"message": "Data updated successfully", 
"appStatusCode": null,
"tags": null, 
"headers": null
}
Sample Document
{
device: {
name: "F5",
ipV6: "fe80::e206:e6ff:fe23:e07/64", 
connectionType: "eth0",
location: { dataCenter: "US",
clusterNodeId: "234rfg23456udcv"
},
"Bcast": "192.168.138.255"
}
}
Updated Document
{
device: {
name: "F5",
ipV6: "fe80::e206:e6ff:fe23:e07/64", 
connectionType: "wlan0",
location: { dataCenter: "US",
clusterNodeId: "234rfg23456udcv"
}
}
}

Reference

Understanding the sample URL
  • IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
    • IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication

      The IP address will be included in the endpoint URL for an on-prem deployment.

    • HostName: A human-readable label assigned to a device (host) on a network

      The hostname will be included in the endpoint URL for an on-prem deployment.

    • TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify

      The tenant name will be included in the endpoint URL for a SaaS deployment.

  • GWPORT: AppViewX gateway port

    A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.

    Example: 31443

  • avxapi: Path parameter value (static) that is part of the endpoint's URL
  • Endpoint: Endpoint of the API, for example: execute-hook
  • gwsource: Source or origin of a gateway, for example: external.