Important

   

Starting from version 8.9.03, BMC Network Automation is renamed to TrueSight Network Automation. This space contains information about TrueSight Network Automation 8.9.03 and the later service packs for 8.9. For earlier releases, see BMC Network Automation 8.9.

Device Agents API

TrueSight Network Automation REST API – Version 3.0 – Device Agents
The base URL for the API is:

https://serverName:portNumber/bca-networks/api
GET /v3.0/device_agents
 Retrieves device agents, matching any filter criteria
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

[
   #DeviceAgentDTO
]

401

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

403

Forbidden: Not allowed to access device agents

500

Internal server error: Unexpected exception occurred

POST /v3.0/device_agents
 Adds a new device agent
Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new device agent

#DeviceAgentDTO

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 the specified user is not logged in

403

Forbidden: Not allowed to add a new device agent

500

Internal server error: Unexpected exception occurred

GET /v3.0/device_agents/{nameOrKey}
 Retrieves one device agent either by name or by database key
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

#DeviceAgentDTO

401

Unauthorized: Failed to provide a suitable Authorization header 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

PUT /v3.0/device_agents/{nameOrKey}
 Modifies all attributes of an existing device agent
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

#DeviceAgentDTO

Authorization

header

Authorization token formatted as 'Bearer [token]'

string*

Responses

Code

Description

Schema

200

successful operation

#DeviceAgentDTO

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 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

DELETE /v3.0/device_agents/{nameOrKey}
 Deletes an unreferenced device agent
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 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

PATCH /v3.0/device_agents/{nameOrKey}
 Modifies only the specified attributes of an existing device agent, where the changes are specified in JSON Patch format (per RFC 6902)
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

#JsonPatch

Authorization

header

Authorization token formatted as 'Bearer [token]'

string*

Responses

Code

Description

Schema

200

successful operation

#DeviceAgentDTO

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 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

 Information about a device agent

{
    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

 Information about a device-facing NIC within a device agent

{
    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

 A dynamic field value

{
    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

 A list of JSON Patch operations

[
    A list of JSON Patch operations
 
     #JsonPatch.OneOperation
  ]

JsonPatch.OneOperation

JsonPatch.Pointer

 Pointer or path to an element or property

string
  Pointer or path to an element or property

JsonPatch.Add

 Add a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array. The value can be any JSON value.

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

JsonPatch.Remove

 Remove a value from an object or array.

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

JsonPatch.Replace

 Replace an existing value. THe value can be any JSON value.

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

JsonPatch.Move

 Move a value from one location to the other. "path" is the destination.

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

JsonPatch.Copy

 Copy a value from one location to another. "path" is the destination.

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

JsonPatch.Test

 Test that the specified value is set in the document at the specified path. If the test fails, then the patch as a whole is not applied. The Value can be any JSON value.

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

Was this page helpful? Yes No Submitting... Thank you

Comments