Space banner This version of the product is in limited support. However, the documentation is available for your convenience. You will not be able to leave comments.

Endpoints in the REST API v3.0 (deprecated)

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

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

templates

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

  /v3.0/templates
Click here to expand...
Description

Retrieves templates, matching any filter criteria; may filter by filterable template dynamic fields by including query parameters in the form 'filter.dynamicFieldName=value'

Parameters

Name

Located in

Description

Default

Schema

query

Filter for templates matching this name, asterisk wildcards allowed

 

string

filter.contents

query

Filter for templates whose content matches this text, asterisk wildcards allowed

 

string

filter.deviceType

query

Filter for templates with a content of this device type, by GUID

 

string

orderBy

query

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

"+name"

string 
Enum: [
 "+name",
 "-name"
]

offset

query

Return the specified page number

1

integer

limit

query

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

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'

 

String *

Responses

Code

Description

Schema

200

successful operation

[ 
  #TemplateDTO 
]

401

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

 

403

Forbidden: Not allowed to access templates

 

500

Internal server error: Unexpected exception occurred

 

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

  /v3.0/templates
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new template

 

Authorization

header

Authorization token formatted as 'Bearer [token]'

 

String *

Responses

Code

Description

Schema

201

Created: New template successfully added

 

400

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

 

500

Internal server error: Unexpected exception occurred

 

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

  /v3.0/templates/{nameOrKey}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the template 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 the specified user is not logged in

 

403

Forbidden: Not allowed to access templates

 

404

Not found: No single matching accessible template found

 

500

Internal server error: Unexpected exception occurred

 

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

  /v3.0/templates/{nameOrKey}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the template to be modified

 

string *

body

body

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

 

Authorization

header

Authorization token formatted as 'Bearer [token]'

 

String *

Responses

Code

Description

Schema

200

successful operation

400

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

 

404

Not found: No single matching accessible template found

 

500

Internal server error: Unexpected exception occurred

 

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

  /v3.0/templates/{nameOrKey}
Click here to expand...
Description

Deletes a template that is not referenced by any jobs, predefined jobs, policies, or rule corrective actions; if this template is instead referenced only in the subject of a rule, or in the contents of another template, this delete request will succeed, but then the rule/template may produce an "unresolved parameter" error during a snapshot or a refresh device status operation, or when displaying the compliance summary report

Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the template to be deleted

 

string *

Authorization

header

Authorization token formatted as 'Bearer [token]'

 

String *

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: Template is currently in use by a job, predefined job, policy, or rule corrective action

 

401

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

 

403

Forbidden: Not allowed to delete the template

 

404

Not found: No single matching accessible template found

 

500

Internal server error: Unexpected exception occurred

 

global_substitution_parameters

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

 /v3.0/global_substitution_parameters
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

query

Filter for global substitution parameters matching this name, asterisk wildcards allowed

 

string

orderBy

query

Sort by the specified attribute (name, value, or a listable global substitution parameter dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+name"

string 
Enum: [
 "+name",
 "-name",
 "+value",
 "-value"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of global substitution parameters 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 the specified user is not logged in

 

403

Forbidden: Not allowed to access global substitution parameters

 

500

Internal server error: Unexpected exception occurred

 

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

 /v3.0/global_substitution_parameters
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new global substitution parameter

 

Authorization

header

Authorization token formatted as 'Bearer [token]'

 

String *

Responses

Code

Description

Schema

201

Created: New global substitution parameter successfully added

 

400

Bad request: Input global substitution parameter DTO is missing or new global substitution parameter 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 global substitution parameter

 

500

Internal server error: Unexpected exception occurred

 

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

 /v3.0/global_substitution_parameters/{nameOrKey}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the global substitution parameter 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 the specified user is not logged in

 

403

Forbidden: Not allowed to access global substitution parameters

 

404

Not found: No single matching global substitution parameter found

 

500

Internal server error: Unexpected exception occurred

 

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

 /v3.0/global_substitution_parameters/{nameOrKey}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the global substitution parameter to be modified

 

string *

body

body

Complete new attribute values for the global substitution parameter; anything left out will be considered to be null and will be nulled out in the global substitution parameter

 

Authorization

header

Authorization token formatted as 'Bearer [token]'

 

String *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input global substitution parameter DTO is missing or modified global substitution parameter 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 global substitution parameter

 

404

Not found: No single matching global substitution parameter found

 

500

Internal server error: Unexpected exception occurred

 

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

 /v3.0/global_substitution_parameters/{nameOrKey}
Click here to expand...
Description

If global substitution parameter is currently referenced in a template,then the template may produce an "unresolved parameter" error during a deploy to active or deploy to stored operation. If this parameter is currently referenced in a rule, then the rule may produce an "unresolved parameter" error during a snapshot or a refresh device status operation, or when displayingthe compliance summary report

Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the global substitution parameter to be deleted

 

string *

Authorization

header

Authorization token formatted as 'Bearer [token]'

 

String *

Responses

Code

Description

Schema

200

successful operation

string

401

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

 

403

Forbidden: Not allowed to delete the global substitution parameter

 

404

Not found: No single matching global substitution parameter found

 

500

Internal server error: Unexpected exception occurred

 

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

 /v3.0/global_substitution_parameters/{nameOrKey}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the global substitution parameter to be modified

 

string *

body

body

New attribute values for the global substitution parameter, 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 global substitution parameter 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 global substitution parameter

 

404

Not found: No single matching global substitution parameter found

 

500

Internal server error: Unexpected exception occurred

 


supporting components

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

  /v3.0/dynamic_fields/{nameOrKey}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the one dynamic field 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 the specified user is not logged in

 

403

Forbidden: Not allowed to access dynamic fields

 

404

Not found: No single matching dynamic field found

 

500

Internal server error: Unexpected exception occurred

 

Object Definitions

Object

Schema

TemplateDTO

Click here to expand...

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

     name: string * 
    The template's unique display name 

     annotation: string 
    Notes, comments, description, explanation 

     contents: [ 
      The scripts that make up this template; there must be at least one 

       #TemplateContentDTO 
    ] * 

     validateSubstitutionParametersFlag: boolean 
    Whether or not substitution parameter syntax is validated in the contents before the template is stored; when true, invalid use of substitution parameters causes create, update, and patch requests to fail with an error; when false, the contents are not examined 

     dynamicFields: [ 
      The dynamic fields 

       #DynamicFieldValueDTO 
    ] 
}

DynamicFieldDTO

Click here to expand...

{ 
    id: string 
    The dynamic field's unique database key 

     name: string 
    The dynamic field's display name, unique within a component type 

     annotation: string 
    Notes, comments, description, explanation 

     assignmentMechanism: string 
    The assignment mechanism for the dynamic field's value 

     autoGroupFlag: boolean 
    For a device dynamic field, whether or not devices are auto-grouped based on this field's value 

     displayInListsFlag: boolean 
    Whether or not this dynamic field is displayed as a column in the component list 

     enabledFlag: boolean 
    Whether or not the dynamic field is enabled 

     filterableFlag: boolean 
    Whether or not components can be filtered by this dynamic field's value 

     component: string 
    The component in which this dynamic field appears 

     valueType: string 
    The type of values that can be assigned 
}

GlobalSubstitutionParameterDTO

Click here to expand...

{ 
    id: string 
    The global substitution parameter's unique database key (read-only) 

     name: string * 
    The global substitution parameter's unique display name 

     value: string * 
    The global substitution parameter's value 

     hideValueFlag: boolean 
    Whether or not the value should be hidden or masked whenever it is displayed in the user interface 

     dynamicFields: [ 
      The dynamic fields 

       #DynamicFieldValueDTO 
    ] 
}


 

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