v4.0 Device Agents API


TrueSight Network Automation REST API – DeviceAgentService
The base URL for the API is:

https://serverName:portNumber/bca-networks/api

device_agents

{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/device_agents
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

orderBy

query

Sort by the specified attribute (name, address, enabledFlag, state, or a listable device agent dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+name"

string 
Enum: [
 "+name",
 "-name",
 "+address",
 "-address",
 "+enabledFlag",
 "-enabledFlag",
 "+state",
 "-state"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of device agents to return

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access device agents


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/device_agents
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new device agent


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

201

Created: New device agent successfully added


400

Bad request: Input device agent DTO is missing or new device agent is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to add a new device agent


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/device_agents/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the device agent of interest


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access device agents


404

Not found: No single matching device agent found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Yellow" title="PUT"/}}

 /v4.0/device_agents/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the device agent to be modified


string *

body

body

Complete new attribute values for the device agent; anything left out will be considered to be null and will be nulled out in the device agent


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input device agent DTO is missing or modified device agent is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to modify the device agent


404

Not found: No single matching device agent found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Red" title="DELETE"/}}

 /v4.0/device_agents/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the device agent to be deleted


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: device agent is currently in use


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to delete the device agent


404

Not found: No single matching device agent found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /v4.0/device_agents/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the device agent to be modified


string *

body

body

New attribute values for the device agent, in JSON Patch format


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input JSON patch information is missing or modified device agent is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to modify the device agent


404

Not found: No single matching device agent found


500

Internal server error: Unexpected exception occurred



Object Definitions

Object

Schema

DeviceAgentDTO


Click here to expand...


{ 
    id: string 
    The device agent's unique database key (read-only) 

     name: string * 
    The device agent's unique display name 

     address: string * 
    A resolvable DNS host name or the IP address of the remote device agent, used by the server to reach this agent 

     agentLocalFileTransferDirectory: string 
    When useProxyFileServerFlag is true, the local directory on the device agent which holds temporary files received from or sent to the proxy file server 

     clearSyslogQueueDuringAgentInitializationFlag: boolean 
    Whether or not syslog messages received while the device agent is alive but not communicating with the server, are sent to the server once agent communication is established; when true, such messages are discarded 

     deviceFacingNICs: [ 
      List of NICs to use to communicate with devices both for connections to the device and for syslog messages received from the device; at least one default IPv4 or IPv6 device-facing NIC is required 

       DeviceAgentNICDTO
    ] * 

     enabledFlag: boolean 
    Whether or not this device agent is enabled; when false, the server does not communicate with the agent at all; when true, the server links up with the agent and executes device actions on it 

     ftpTransferEnabledFlag: boolean 
    Whether or not the device agent supports FTP file transfers; when true, files can be exchanged between devices and the device agent using the FTP protocol, or can be exchanged between devices and the proxy file server using the FTP protocol 

     ftpTransferAccountHomeDirectory: string 
    The FTP user's home directory, where transferred files are placed for certain path-aware devices (such as Cisco Nexus and Juniper WX); stored into the %transferPath% property during OS image snapshot and OS image deploy actions 

     ftpTransferAccountUsername: string 
    The username to be used when making an FTP connection from a device to this device agent or its proxy file server 

     ftpTransferAccountPassword: string 
    The FTP user's password 

     ftpTransferAccountPasswordEncryptedFlag: boolean 
    Whether or not the ftpTransferAccountPassword value is encrypted; when false, ftpTransferAccountPassword is in clear text 

     ftpTransferRestrictedPathAccessFlag: boolean 
    whether or not the FTP server is configured to restrict users to their one specific home or root directory; controls whether or not certain path-aware devices (such as Cisco Nexus and Juniper WX) include a full path in FTP copy commands; if the FTP server is unrestricted, a full path is included to ensure the file is saved to the ftpTransferHomeDirectory (stored into the %transferPath% property); if the FTP server is restricted, no full path appears in FTP commands and the file is saved to the user's default permitted directory 

     localFlag: boolean 
    Whether or not this device agent is the local agent embedded within the server (read-only) 

     nameResolutionEnabledFlag: boolean 
    Whether or not the device agent should attempt to perform host name resolution as needed, both when connecting to devices the agent manages and when parsing syslog messages received from those devices; set this to false when an agent has overlapping address spaces across its NICs, where name resolution may not be accurate 

     port: integer * 
    The port the server uses to communicate with the device agent 

     proxyFileServerAddress: string 
    The devie agent-facing host name or IP address of the proxy file server, used when the device agent performs file transfers to/from the proxy file server 

     proxyFileServerIPv4Address: string 
    Device-facing IPv4 address of the proxy file server, used when devices perform file transfers to/from the proxy file server 

     proxyFileServerIPv6Address: string 
    Device-facing IPv6 address of the proxy file server, used when devices perform file transfers to/from the proxy file server 

     proxyFileServerSftpPort: integer 
    The port number (usually port 22) on which the device agent connects to the proxy file server when exchanging files using SFTP 

     proxyFileServerSftpTransferAccountUsername: string 
    The username to be used when making an SFTP connection from the device agent to the proxy file server 

     proxyFileServerSftpTransferAccountPassword: string 
    The proxy file server SFTP user's password 

     proxyFileServerSftpTransferAccountPasswordEncryptedFlag: boolean 
    Whether or not the proxyFileServerSftpTransferAccountPassword value is encrypted; when false, proxyFileServerSftpTransferAccountPassword is in clear text 

     scpTransferEnabledFlag: boolean 
    Whether or not the device agent supports SCP file transfers; when true, files can be exchanged between devices and the device agent using the SCP protocol, or can be exchanged between devices and the proxy file server using the SCP protocol 

     scpTransferAccountHomeDirectory: string 
    Location on the device agent's disk where files are stored temporarily during SCP transfers 

     scpTransferAccountUsername: string 
    The username to be used when making an SCP connection from a device to this device agent or its proxy file server 

     scpTransferAccountPassword: string 
    The SCP user's password 

     scpTransferAccountPasswordEncryptedFlag: boolean 
    Whether or not the scpTransferAccountPasswordEncryptedFlag value is encrypted; when false, scpTransferAccountPasswordEncryptedFlag is in clear text 

     scpTransferRelativeHomeDirectory: string 
    The home directory of the SCP user from the device SCP client's perspective; the SCP server might treat paths supplied by a client (a device in this case) as paths relative to some configured root or home directory; the SCP command for some types of devices must include this relative path (saved in the %scpRelativeHomeDirectory% property) in place of an absolute path 

     state: string 
    The current state of the device agent (read-only) 

     syslogDebuggingEnabledFlag: boolean 
    Whether or not syslog debugging is enabled; when true, Debug category events are logged tracing received syslog messages 

     syslogEnabledFlag: boolean 
    Whether or not the device agent processes incoming syslog messages 

     syslogLogEnabledFlag: boolean 
    Whether or not the device agent logs all received syslog messages to the file specified by syslogLogFileName 

     syslogLogFileName: string 
    When syslogLogEnabledFlag is true, name of the local file on the device agent disk used for logging received syslog messages; an external program must read and shrink this file, to prevent it from growing infinitely 

     syslogPort: integer 
    The port number (usually port 514) on which the device agent receives syslog messages from devices 

     syslogRelays: { 
      Per-NIC syslog relays that receive device syslog messages and forward them to this device agent; this is a map where the key is a NIC name and the value is one or more syslog relay host names or IP addresses (separated by a newline) 
    } 

     tftpTransferEnabledFlag: boolean 
    Whether or not the device agent supports TFTP file transfers; when true, files can be exchanged between devices and the device agent using the TFTP protocol, or can be exchanged between devices and the proxy file server using the TFTP protocol 

     tftpTransferDirectory: string 
    Location on the device agent's disk where files are stored temporarily during TFTP transfers 

     transferFilenamePrefix: string * 
    Prefix used on file names when creating temporary files for configurations and OS images being exchanged with devices 

     useProxyFileServerFlag: boolean 
    Whether or not the device agent uses a proxy file server for file transfers to and from devices; when true, every file exchanged by the device agent and a device passes through an intermediate file server and a device never makes a connection directly to the device agent 

     dynamicFields: [ 
      The dynamic fields 

       DynamicFieldValueDTO
    ] 
}

DeviceAgentNICDTO


Click here to expand...


{ 
    address: string * 
    IP address for the NIC 

     defaultFlag: boolean 
    Whether or not this NIC is considered to be the device agent's default NIC; a device agent must have exactly one default NIC 

     mask: integer 
    IP CIDR mask in the case of an IPv4 NIC, or prefix length in the case of an IPv6 NIC 

     name: string * 
    Uniquely identifies this NIC within the agent that owns it 

     v6Flag: boolean 
    Whether or not this NIC is IPv6; when false, the NIC is IPv4; when true, the NIC is IPv6 
}

DynamicFieldValueDTO


Click here to expand...


{ 
    id: string 
    The database key of the dynamic field whose value this is (read-only) 

     name: string 
    The name of the dynamic field (read-only) 

     values: [ 
      The value(s) for the dynamic field; for a single-value field, only the first entry is relevant; read-only for Auto Derived and Configuration Profiled types 

       string 
    ] 

     dynamicFieldDetailsLink: string 
    Link to get more detailed information about the dynamic field (read-only) 
}

JsonPatch


Click here to expand...


[ 
    A list of JSON Patch operations 

     JsonPatch.OneOperation
  ]

JsonPatch.OneOperation

JsonPatch.Pointer


Click here to expand...


string 
  Pointer or path to an element or property

JsonPatch.Add


Click here to expand...


{ 
    op: string * 
   Enum: [
     "add"
   ]
    value: any * 
    path: JsonPatch.Pointer*
}

JsonPatch.Remove


Click here to expand...


{ 
    op: string * 
   Enum: [
     "remove"
   ]
    path: JsonPatch.Pointer*
}

JsonPatch.Replace


Click here to expand...


{ 
    op: string * 
   Enum: [
     "replace"
   ]
    value: any * 
    path: JsonPatch.Pointer*
}

JsonPatch.Move


Click here to expand...


{ 
    op: string * 
   Enum: [
     "move"
   ]
    path: JsonPatch.Pointer*
    from: JsonPatch.Pointer*
}

JsonPatch.Copy


Click here to expand...


{ 
    op: string * 
   Enum: [
     "copy"
   ]
    path: JsonPatch.Pointer*
    from: JsonPatch.Pointer*
}

JsonPatch.Test


Click here to expand...


{ 
    op: string * 
   Enum: [
     "test"
   ]
    value: any * 
    path: JsonPatch.Pointer*
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

TrueSight Network Automation 21.08