Roles API

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

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

roles

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

/v3.0/roles

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
filter.name	query	Filter for roles matching this name, asterisk wildcards allowed		string
orderBy	query	Sort by the specified attribute (name, associatedUsernames, or a listable dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)	"+name"	string Enum: [ "+name", "-name", "+associatedUsernames", "-associatedUsernames" ]
offset	query	Return the specified page number	1	integer
limit	query	Define the number of rows in a page or the maximum number of roles to return	25	integer
Authorization	header	Authorization token formatted as 'Bearer [token]'		String*

Responses

Code	Description	Schema
200	successful operation	[ #RoleDTO ]
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to access roles
500	Internal server error: Unexpected exception occurred

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

/v3.0/roles

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
body	body	Complete attributes of the new role		#RoleDTO
Authorization	header	Authorization token formatted as 'Bearer [token]'		string*

Responses

Code	Description	Schema
201	Created: New role successfully added
400	Bad request: Input role DTO is missing or new role 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 role
500	Internal server error: Unexpected exception occurred

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

/v3.0/roles/{nameOrKey}

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
nameOrKey	path	Name or database key of the role of interest		string*
Authorization	header	Authorization token formatted as 'Bearer [token]'		String*

Responses

Code	Description	Schema
200	successful operation	#RoleDTO
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to access roles
404	Not found: No single matching accessible role found
500	Internal server error: Unexpected exception occurred

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

/v3.0/roles/{nameOrKey}

Click here to expand...

Parameters

Name	Located in	Description	Schema
nameOrKey	path	Name or database key of the role to be modified	string*
body	body	Complete new attribute values for the role; anything left out will be considered to be null and will be nulled out in the role	#RoleDTO
Authorization	header	Authorization token formatted as 'Bearer [token]'	string*

Responses

Code	Description	Schema
200	successful operation	#RoleDTO
400	Bad request: Input role DTO is missing or modified role 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 role
404	Not found: No single matching accessible role found
500	Internal server error: Unexpected exception occurred

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

/v3.0/roles/{nameOrKey}

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
nameOrKey	path	Name or database key of the role to be deleted		string*
Authorization	header	Authorization token formatted as 'Bearer [token]'		string*

Responses

Code	Description	Schema
200	successful operation	string
400	Bad request: Role is currently in use by a user, a job approval type, or a system parameter; or role is the root role that cannot be deleted
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to delete the role
404	Not found: No single matching accessible role found
500	Internal server error: Unexpected exception occurred

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

/v3.0/roles/{nameOrKey}

Click here to expand...

Parameters

Name	Located in	Description	Schema
nameOrKey	path	Name or database key of the role to be modified	string*
body	body	New attribute values for the role, in JSON Patch format	#JsonPatch
Authorization	header	Authorization token formatted as 'Bearer [token]'	string*

Responses

Code	Description	Schema
200	successful operation	#RoleDTO
400	Bad request: Input JSON patch information is missing or modified role 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 role
404	Not found: No single matching accessible role 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 componentType: string* The type of the component, used to verify what is retrieved by key/name; valid values are: Combogroup, Condition, Configuration, Device, DynamicField, EmailDistributionList, Group, Keyword, Model, OsImage, Realm, 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: key=deviceName, value=name of the device the configuration belongs to; 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 } }
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	Click here to expand... Subclasses: #JsonPatch.Move #JsonPatch.Replace #JsonPatch.Remove #JsonPatch.Test #JsonPatch.Copy #JsonPatch.Add { }
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 * }
NetworkRightsDTO	Click here to expand... { realm: #ComponentId The realm rights: [ The network rights granted to the realm string ] }
RoleDTO	Click here to expand... { id: string The role's unique database key (read-only) name: string* The role's unique display name associatedUsernames: string The users who belong to this role (read-only) fullNetworkRightsFlag: boolean Whether or not this role has access to all network rights in all current and future realms; read-only and always true for the root role networkRights: [ The network rights granted to each specified realm, with no rights granted to any realm that does not appear; used only when the fullNetworkRightsFlag is false #NetworkRightsDTO ] restrictedToReportingSystemFlag: boolean Whether or not this role exists only to support an external reporting system which imports users and their role associations which are meaningful to that reporting system; when true, the role is intended to control access within an external reporting system that has no means for creating its own users and roles (hence they are imported); the role cannot have any system or network rights; when false, the role is a normal role for use within TSNA proper; read-only and always false for the root role rootRoleFlag: boolean Whether or not this is the root role, which grants universal access; true only for the Administrator role; false for all other roles (read-only) systemRights: [ System rights granted to this role; read-only for the root role string ] dynamicFields: [ The dynamic fields #DynamicFieldValueDTO ] }

Roles API

roles

{{status colour="Blue" title="GET"/}} /v3.0/roles

Parameters

Responses

{{status colour="Green" title="POST"/}} /v3.0/roles

Parameters

Responses

{{status colour="Blue" title="GET"/}} /v3.0/roles/{nameOrKey}

Parameters

Responses

{{status colour="Yellow" title="PUT"/}} /v3.0/roles/{nameOrKey}

Parameters

Responses

{{status colour="Red" title="DELETE"/}} /v3.0/roles/{nameOrKey}

Parameters

Responses

{{status colour="Yellow" title="PATCH"/}} /v3.0/roles/{nameOrKey}

Parameters

Responses

Object Definitions

ComponentId

DynamicFieldValueDTO

JsonPatch

JsonPatch.OneOperation

JsonPatch.Pointer

JsonPatch.Add

JsonPatch.Remove

JsonPatch.Replace

JsonPatch.Move

JsonPatch.Copy

JsonPatch.Test

NetworkRightsDTO

RoleDTO

On this page

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

/v3.0/roles

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

/v3.0/roles

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

/v3.0/roles/{nameOrKey}

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

/v3.0/roles/{nameOrKey}

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

/v3.0/roles/{nameOrKey}

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

/v3.0/roles/{nameOrKey}