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.

Templates API

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

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

GET /v3.0/templates
 Retrieves templates, matching any filter criteria
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

filter.name

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


POST /v3.0/templates
 Adds a new template
Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new template


#TemplateDTO

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


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

#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


404

Not found: No single matching accessible template found


500

Internal server error: Unexpected exception occurred


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


#TemplateDTO

Authorization

header

Authorization token formatted as 'Bearer [token]'


String*

Responses

Code

Description

Schema

200

successful operation

#TemplateDTO

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


DELETE /v3.0/templates/{nameOrKey}
 Deletes a template
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


PATCH /v3.0/templates/{nameOrKey}
 Modifies only the specified attributes of an existing template, 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 template to be modified


string*

body

body

New attribute values for the template, in JSON Patch format


#JsonPatch

Authorization

header

Authorization token formatted as 'Bearer [token]'


String*

Responses

Code

Description

Schema

200

successful operation

#TemplateDTO

400

Bad request: Input JSON patch information 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


GET /v3.0/templates/{nameOrKey}/runtime_parameters
 Retrieves all runtime parameters referenced by the template of interest
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

[
   #TemplateRuntimeParameterDTO
]

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



Object Definitions

Object

Schema

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

TemplateContentDTO

 A single script that can be deployed to a device to effect configuration changes

{
    deviceTypeGuid: string
    The GUID of the device type compatible with this content; a null indicates the content is compatible with any device type
 
    deviceTypeName: string
    The name of the device type (read-only)
 
    injectionTemplateFlag: boolean
    Whether or not the contents contain an injection template, for making device configuration changes using an API; when true, the contents are validated for proper XML syntax
 
    minimumOSVersion: string
    The minimal OS version with which this content is compatible, in major.minor.build format; asterisk wildcard is allowed; required when deviceTypeGuid is not null
    Example: 13.8.120 or 12.4.*
 
    maximumOSVersion: string
    The maximal OS version with which this content is compatible, in major.minor.build format, asterisk wildcard is allowed; required when deviceTypeGuid is not null
    Example: 12.3.(14)T3 or 8..
 
    scriptContents: string*
    The configuration commands that are to be sent to a device during a deploy span action; any sensitive configuration data is masked when you retrieve the template if you are not granted the "Access Sensitive Data" system right; masked data cannot be stored into the contents
}

TemplateDTO

 Information about a template

{
    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
    ]
}

TemplateRuntimeParameterDTO

 Information about a runtime parameter referenced by a template.

{
    name: string
    The name of the runtime parameter
 
    defaultValue: string
    The default value assigned to the runtime parameter
 
    options: [
      The defined set of options fromwhich the user can assign a runtime value.
 
      string
    ]
}

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

Comments