Roles Web Service

The API provides the roles web service to let you view, create, and modify user account roles.
You can view, create, and modify user account roles using the
roles
web service.
role
is a parameter assigned to a user account that controls user access to product features and dashboard pages. Based on user job functions, the role grants administrative access to
DX NetOps Performance Management
configuration using
role rights
. With roles, users can access data and
DX NetOps Performance Management
features that they require to perform their duties and restrict access to features that they do not require. To assign custom or factory roles to user accounts, use the users RESTful web service.
In this article:
Verify the Prerequisites
  • You have connected the REST client that you will use to invoke the
    NetOps Portal
    web services to the
    NetOps Portal
    RESTful web services.
  • You are a local admin user.
Access the roles Web Service Documentation
As a local admin user, issue the following call to see the parameters for the
roles
web service:
http://
PC_host
:8181/pc/center/webservice/roles
As a local admin user, issue the following call to see a list of supported operations:
http://
PC_host
:8181/pc/center/rest/roles/documentation
Basic roles Parameters
The current values for the following user account role settings are available from the GET command:
  • accessRights
    The role rights that are allocated to this role. Multiple role rights are available for allocation, and some are data source-specific. To get a list of all available role rights, the
    categoryId
    parameter is required. The
    categoryId
    parameter with value 1 corresponds to both
    NetOps Portal
    and the data aggregator.
  • culture
    Specifies a language (locale). Supply a language identifier from the following list:
    • en-US (English, United States)
    • ja-JP (Japanese)
    • zh-CN (Simplified Chinese)
    • fr-FR (French, France)
  • description
    (Optional) Describes the role to help you identify it.
  • enabled
    Determines whether the role is enabled for use (activated). Values are true or false.
  • name
    Is a name for the role. The name is limited to 50 characters.
  • selections
    Provides sets of access rights that you can selectively grant to this role, organized into categories.
  • userCount
    Is the number of users who have this role assigned to their user account.
  • userID
    Is an internally assigned value for the role.
Roles Web Service Example Syntax
Issue the following call to see the available operations and parameters for the roles web service:
http://
PC_host
:8181/pc/center/rest/roles/documentation
Available GET Methods
  • get access rights
    Retrieves a list of the role rights that are assigned to a specified role. Use the following syntax:
    http://
    PC_host
    :8181/pc/center/webservice/roles/idName/idValue/rights/cultureId
  • get access rights by category
    Retrieves a list of all available role rights for a specified category. The category is either
    NetOps Portal
    or a data source. A categoryId of 1 applies to both
    NetOps Portal
    and Data Aggregator.
    http://
    PC_host
    :8181/pc/center/webservice/roles/rights/categoryid/cultureId
  • get category
    Retrieves an XML document that includes the categoryId:
    http://
    PC_host
    :8181/pc/center/webservice/roles/rights/categories/en-US
  • get by tenant
    Retrieves a list of all roles that are associated with the tenant for the logged-in user. Use the following syntax:
    http://
    PC_host
    :8181/pc/center/webservice/roles/idName/idValue/rights/tenant/tenantIdName/tenantIdValue/cultureId
  • get categoryId
    Retrieves XML that shows the available category IDs:
    http://
    PC_host
    :8181/pc/center/webservice/roles/rights/categories/cultureId
    A value of 1 corresponds to
    NetOps Portal
    and Data Aggregator. Role rights in that category only apply to a Data Aggregator data source.
  • get id names
    Retrieves a list of identifiers that can be used to identify roles in other web service methods. Use the following syntax:
    http://
    PC_host
    :8181/pc/center/webservice/roles/idNames
Available PUT Methods
  • copy
    Copies a role. This method creates a copy of a specified role and associates it with the tenant for the logged-in user. Use the following syntax:
    http://
    PC_host
    :8181/pc/center/webservice/roles/idName/idValue/copy/roleName/description/enabled/cultureId
  • update
    Modifies a specified role. The role name and tenant ID are required elements of the role parameters:
    http://
    PC_host
    :8181/pc center/webservice/roles/idName/idValue/cultureId
Available POST Methods
  • create
    Creates a role. The new role is associated with the tenant for the logged-in user:
    http://
    PC_host
    :8181/pc/center/webservice/roles/
  • create for tenant
    Creates a role and assigns it to the specified tenant.
    http://
    PC_host
    :8181/pc/center/webservice/roles/tenant/tenantIdName/tenantIdValue
Create a User Account Role
Best Practice:
Create user account roles before creating user accounts.
Use the roles web service to create user account roles. The
role
is a parameter of the user account that grants the user access to certain administrative features and to perform selected tasks. The following procedure invokes the
roles
web service using a REST client.
Issue the following call to see the parameters for the roles web service:
http://
PC_host
:8181/pc/center/webservice/roles
Follow these steps:
  1. As a local admin user, in the REST client interface, enter the following URL in the
    URL
    field, and then select
    POST
    for the method:
    http://
    PC_host
    :8181/pc/center/webservice/roles/
  2. Select
    POST
    for
    "HTTP" Method
    .
  3. Provide a valid Username and Password for a user account that has global administrator access to
    NetOps Portal
    .
  4. Select
    'application/xml
    ' as the
    'Body Content-type'
    in the Body settings.
  5. Paste XML in the Body field that resembles the following example:
    <role> <name>TestRoleName</name> <description>Test Role Description</description> <enabled>true</enabled> <accessRights> <accessRight> <accessRightName>ViewToS</accessRightName> <categoryId>1</categoryId> <enabled>true</enabled> </accessRight> </accessRights> </role>
    • accessRights
      Correspond to role rights.
    • accessRightName
      The name of the role right. For example, the administerGroups role right allows the user with this role to manage a limited section of the Groups tree.
    • categoryId
      Identifies the category of role rights, such as
      NetOps Portal
      role rights or data-source-specific role rights.
  6. Run the method.
The user account role is created.