v4.0 Remote File Servers API


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

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

remote_file_servers

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

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


Parameters

Name

Located in

Description

Default

Schema

query

Filter for remote file servers matching this name, asterisk wildcards allowed


string

orderBy

query

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

"+name"

string 
Enum: [
 "+name",
 "-name",
 "+address",
 "-address",
 "+ftpTransferUsername",
 "-ftpTransferUsername",
 "+scpTransferUsername",
 "-scpTransferUsername"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of remote file servers 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 remote file servers


500

Internal server error: Unexpected exception occurred


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

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


Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new remote file server


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

201

Created: New remote file server successfully added


400

Bad request: Input remote file server DTO is missing or new remote file server 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 remote file server


500

Internal server error: Unexpected exception occurred


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

 /v4.0/remote_file_servers/multiple_remote_file_server_updates
Click here to expand...


Description

Modifies the specified static and dynamic fields in the selected remote file servers; the response reports which remote file servers are successfully updated and which are not updated due to some validation error; note there are no partial updates; any one remote file server either has all the changes applied to it or none of them

Parameters

Name

Located in

Description

Default

Schema

body

body

What changes to make and to which remote file servers


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input DTO is missing or 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 remote file servers


500

Internal server error: Unexpected exception occurred


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

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


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the remote file server 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 remote file servers


404

Not found: No single matching remote file server found


500

Internal server error: Unexpected exception occurred


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

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


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the remote file server to be modified


string *

body

body

Complete new attribute values for the remote file server; anything left out will be considered to be null and will be nulled out in the remote file server


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input remote file server DTO is missing or modified remote file server 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 remote file server


404

Not found: No single matching remote file server found


500

Internal server error: Unexpected exception occurred


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

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


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the remote file server to be deleted


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

OK: Remote file servers update request was processed

string

400

Bad request: Remote file server is currently in use by a device or device import task


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 remote file server


404

Not found: No single matching remote file server found


500

Internal server error: Unexpected exception occurred


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

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


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the remote file server to be modified


string *

body

body

New attribute values for the remote file server, 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 remote file server 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 remote file server


404

Not found: No single matching remote file server found


500

Internal server error: Unexpected exception occurred



Object Definitions

Object

Schema

ComponentId


Click here to expand...


{ 
    id: string 
    The database key of the component; an incoming component can be identified either by its database key, or by its unique name, or by its name with qualifiers which are unique when combined; when this database key is present, it takes precedence and componentName and qualifiers(when present) are used to verify the retrieved component 

     componentName: string 
    The name of the component; an incoming component can be identified either by its database key, or by its unique name, or by its name with qualifiers which are unique when combined; this name is used to verify any component retrieved by database key, and is used if there is no database key or if the database key fails to resolve; for componentType Configuration and HardwareInventory, componentName is the created timestamp (in milliseconds); for componentType SecurityVulnerability, componentName is the securityVulnerabilityID; for componentType SnmpManagerStation, componentName is the address 

     componentType: string * 
    The type of the component, used to verify what is retrieved by key/name; valid values are: Combogroup, Condition, Configuration, Device, DeviceAdapter, DeviceAgent, DeviceSecurityProfile DynamicField, EmailDistributionList, Group, HardwareInventory, JobApprovalType, Keyword, Model, OsImage, PredefinedJob, Realm, RemoteFileServer, Role, Rule, RuleSet, SecurityVulnerability, SnmpManagerStation, Template, and User 

     qualifiers: { 
      Any additional single qualifier needed to identify the component uniquely, when the name alone is not sufficient; the map key is the extra attribute name string; the map value string completes the identification of the component; for componentType Configuration and HardwareInventory: key=deviceKey, value=database key of the device the item belongs to, key=deviceName, value=name of the device the item belongs to, key=timestamp, value=creation date/time in server display format; for componentType DeviceAdapter: key=adapterType, value=type of the device adapter, key=parent, value=parent or owner used for organizing certain types of adapters, key=vendorName, value=name of the vendor that owns a device type; for componentType DynamicField: key=type, value=base class name of the component associated with the dynamic field; for componentType Group, ComboGroup: key=realmName, value=name of the realm the group belongs to; for componentType Model: key=vendorGuid, value=the vendor GUID; for componentType OsImage: key=filename, value=name of the file(s) making up the image; for componentType SecurityVulnerability: key=vendorGuid, value=the vendor GUID 
    } 
}

DynamicFieldEditDTO


Click here to expand...


{ 
    clearExistingValueFlag: boolean 
    Whether or not to clear or null out the existing value for the dynamic field; when true, the newValues field must be null, and the current value is set to null; when false, the current value is set to the value(s) specified by newValues, which must not be null 

     id: string * 
    The database key of the dynamic field to be updated 

     newValues: [ 
      When clearExistingValueFlag is false, the new value(s) for the dynamic field; if the dynamic field is a single-value type of field, then only the first entry is used 

       string 
    ] 
}

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

RemoteFileServerDTO


Click here to expand...


{ 
    id: string 
    The remote file server's unique database key (read-only) 

     name: string * 
    The remote file server's unique display name 

     address: string * 
    Host name or IP address of the remote file server, as it is known to the devices that will access it 

     ftpTransferEnabledFlag: boolean 
    Whether or not the remote file server supports FTP file transfers and has an FTP server running on it; when true, files can be exchanged between devices and the remote file server using the FTP protocol 

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

     ftpTransferPassword: string 
    The FTP user's password 

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

     ftpTransferUsername: string 
    The username to be used when making an FTP connection from a device to this remote file server 

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

     readOnlyFileSystemFlag: boolean 
    Whether or not files can be written to this remote file server; when false, you will not be able to make OS image snapshots to this server,but will be able to read image files from it for OS image deploy actions 

     scpTransferEnabledFlag: boolean 
    Whether or not the remote file server supports SCP file transfers and has an SSH/SCP server running on it; when true, files can be exchanged between devices and the remote file server using the SCP protocol 

     scpTransferPassword: string 
    The SCP user's password 

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

     scpTransferUsername: string 
    The username to be used when making an SCP connection from a device to this remote file server 

     tftpTransferEnabledFlag: boolean 
    Whether or not the remote file server supports TFTP file transfers and has a TFTP server running on it; when true, files can be exchanged between devices and the remote file server using the TFTP protocol 

     dynamicFields: [ 
      The dynamic fields 

       DynamicFieldValueDTO
    ] 
}

RemoteFileServerMultiEditDTO


Click here to expand...


{ 
    dynamicFieldUpdates: [ 
      The updates or edits to be made to the dynamic fields in each selected remote file server 

       DynamicFieldEditDTO
    ] 

     itemsToUpdate: [ 
      Which remote file servers are to be updated or edited 

       ComponentId
    ] * 

     staticFieldUpdates: [ 
      The updates or edits to be made to the static fields in each selected remote file server 

       StaticFieldEditDTO
    ] 
}

RemoteFileServerMultiEditResultDTO


Click here to expand...


{ 
    errorMessage: string 
    Reason the update or edit failed 

     remoteFileServer: ComponentId
    The remote file server that was requested to be updated 

     successFlag: boolean 
    Whether or not the requested update was successful 
}

StaticFieldEditDTO


Click here to expand...


{ 
    clearExistingValueFlag: boolean 
    Whether or not to clear or null out the existing value for this field; when true, the newValue field must be null, and the current value is set to false or null; when false, the current value is set to the value specified by newValue, which must not be null 

     fieldName: string * 
    Which remote file server field is to be updated or edited; the legal field names are: ftptransferenabledflag, ftptransferhomedirectory, ftptransferpassword, ftptransferusername, ftpuserrestrictedtohomedirectoryflag, readonlyfilesystemflag, scptransferenabledflag, scptransferpassword, scptransferusername, tftptransferenabledflag 

     newValue: string 
    When clearExistingValueFlag is false, the new value for the field; if the field is a flag, this value must be either "true" or "false"; if the field is a password, this value must be the cleartext password 
}

 

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

TrueSight Network Automation 22.1