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.

Roles API

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

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

roles

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

POST /v3.0/roles
 Adds a new role
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

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

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

#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

DELETE /v3.0/roles/{nameOrKey}
 Deletes an unreferenced non-root role
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

PATCH /v3.0/roles/{nameOrKey}
 Modifies only the specified attributes of an existing role, 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 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

 Identifies a component in a form that can be input to either the same TrueSight Network Automation server that emitted it or to a different TrueSight Network Automation server; the name, qualifiers, and type uniquely identify a component; and they verify that anything successfully retrieved by a database key is the right component

{
    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

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

NetworkRightsDTO

 Information about network rights for a specific realm

{
    realm: #ComponentId
    The realm
 
    rights: [
      The network rights granted to the realm
 
      string
    ]
}

RoleDTO

 Information about a role

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

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

Comments