v4.0 Roles API


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

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

roles

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

 /v4.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

filter.rightsManagement

query

Filter for roles whose rights you can manage in the specified context; a value of "copyable" selects roles whose rights you can copy from; a value of "editable" selects roles whose rights you are allowed to edit (which does not include any role with full network rights); when null, no such filtering occurs


string 
Enum: [
 "copyable",
 "editable"
]

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 accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access roles


500

Internal server error: Unexpected exception occurred


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

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


Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new role


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 accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to add a new role or not allowed to grant the new right(s)


500

Internal server error: Unexpected exception occurred


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

 /v4.0/roles/changes_to_rights
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Changes to be made in the selected roles


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

OK: Roles updated successfully


400

Bad request: Input DTO is missing or invalid or modified role 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 roles or not allowed to grant or revoke a particular right


500

Internal server error: Unexpected exception occurred


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

 /v4.0/roles/replication_of_rights
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

How rights are to be replicated from one role to another


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

OK: Role updated successfully


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 role or not allowed to grant or revoke a particular right


500

Internal server error: Unexpected exception occurred


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

 /v4.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

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 roles


404

Not found: No single matching accessible role found


500

Internal server error: Unexpected exception occurred


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

 /v4.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 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


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input role DTO is missing or modified role 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 role or not allowed to grant/revoke rights in the requested way


404

Not found: No single matching accessible role found


500

Internal server error: Unexpected exception occurred


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

 /v4.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 accessToken cookie, 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 subtle="false" colour="Yellow" title="PATCH"/}}

 /v4.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 modified


string *

body

body

New attribute values for the role, 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 role 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 role or not allowed to grant/revoke rights in the requested way


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

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

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) 

     canCopyFlag: boolean 
    Whether or not the user is allowed to copy this role (read-only) 

     canDeleteFlag: boolean 
    Whether or not the user is allowed to delete this role (read-only) 

     canEditFlag: boolean 
    Whether or not the user is allowed to edit 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
    ] 
}

RoleRightsChangesDTO

Click here to expand...


{ 
    roles: [ 
      The roles to be modified; cannot include any role that has full network rights 

       ComponentId
    ] * 

     realms: [ 
      The realms whose network rights are to be modified in the selected roles; required when network rights are to be modified 

       ComponentId
    ] 

     networkRights: { 
      The changes to be made to the network rights in the selected realms in the selected roles; this is a map where the key is a network right string, and the value is a flag indicating the type of change to make to the right; for the flag value, a null means no change, a true means grant the right, and a false means revoke the right 
    } 

     systemRights: { 
      The changes to be made to the system rights in the selected roles; this is a map where the key is a system right string, and the value is a flag indicating the type of change to make to the right; for the flag value, a null means no change, a true means grant the right, and a false means revoke the right 
    } 
}

RoleRightsReplicationDTO

Click here to expand...


{ 
    copyFullNetworkRightsFlag: boolean 
    Whether or not to enable full network rights in the destination role; allowed only when the source role has full network rights 

     copyGroupAclsFlag: boolean 
    Whether or not all static groups are updated to copy the source role's rights to the destination role 

     copyNetworkRightsToAllRealmsFlag: boolean 
    Whether or not the source realm's network right are copied to all the realms in the destination role 

     copyRuleSetAclsFlag: boolean 
    Whether or not all rule sets are updated to copy the source role's rights to the destination role 

     copySystemRightsFlag: boolean 
    Whether or not system rights are copied from the source role to the destination role 

     copyTemplateAclsFlag: boolean 
    Whether or not all templates are updated to copy the source role's rights to the destination role 

     destinationRole: ComponentId*
    The role whose rights are updated to be the same as the selected rights in the source role 

     networkRightsDestinationRealms: [ 
      When not copying to all realms, which specific destination realms are updated 

       ComponentId
    ] 

     networkRightsSourceRealm: ComponentId
    The realm within the source role whose network rights are to be copied into the selected realms in the destination role; can be used only when the source role does not have full network rights 

     sourceRole: ComponentId*
    The role whose rights are to be copied 
}

 

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