PUT: Update a user's role

You can use the REST API to update users' roles.

Caution: Assigning a role to a user using the REST API overrides the existing set of roles for that user. Even if you want to add only one new role to a user, the update should include previously existing roles. Otherwise non-included roles are unassigned.

ALM Octane roles

The following roles are available in ALM Octane. For details about each role, see the information about setting up users and roles in the in the ALM Octane User Guide.

Name Logical name Notes
Shared space admin role.shared.space.admin

Allow shared space management and configuration (including user management).

Scope: Shared space

Workspace admin role.workspace.admin

Allow workspace management and configuration, including getting a list of users.

Scope: Workspace

Leader role.leader

Allow management of team members and workload.

Scope: Teams in workspace

Team member role.team.member

Allow working with, and editing, items that affect the member's work as part of a team.

Scope: Teams in workspace

Tester role.tester

Allow working with, and editing, items that are related to testing.

Scope: Teams in workspace

DevOps admin role.devops.admin

Allow management of CI servers and pipelines in a workspace context.

Scope: Workspace

Integration Bridge Service role.shared.space.integration.bridge

Allow the on-premise bridge (OPB) access to the OPB service in the shared space context.

Scope: Shared space

Synchronizor Service role.workspace.sync.service

Synchronization service role, allows:

  • Getting shared space users and roles from ALM Octane.

  • Create, read, update, delete of synced entities from ALM Octane.

  • Work with the on-premise bridge (OPB).

Scope: Workspace

CI/CD Configuration role.workspace.ci_cd_agent.configure

(For API Access keys only.)

Scope: All workspaces

Back to top

Add a role to a user

  1. Find the ID of the desired role according to desired workspace and role’s logical name.

    Roles might have the same logical names across different workspaces, but their IDs will be different.

    Example

    This is an example of getting the role ID.

    • Get the role of the shared space admin. In this case, do not specify a workspace ID. In this case, the role ID is 1007.

      Request:

      GET .../api/shared_spaces/<sharedSpaceId>/workspace_roles?query="role EQ {logical_name EQ ^role.shared.space.admin^}"

      Response:

      {
        "total_count": 1,
        "data": [
          {
            "type": "workspace_role",
            "creation_time": "2016-10-29T19:05:29Z",
            "workspace": null,
            "role": {
              "type": "role",
              "id": "1007"
            },
            "version_stamp": 1,
            "id": "1007",
            "last_modified": "2016-10-29T19:05:29Z"
          }
        ],
        "exceeds_total_count": false
      }
    • Get the role of the workspace admin in workspace 1002. In this case, the role ID is 1003.

      Request:

      GET .../api/shared_spaces/<shared_space_id>/workspace_roles?query="workspace EQ {id EQ ^1002^}; role EQ {logical_name EQ ^role.workspace.admin^}"

      Response:

      {
        "total_count": 1,
        "data": [
          {
            "type": "workspace_role",
            "creation_time": "2016-10-29T19:05:29Z",
            "workspace": {
              "type": "workspace",
              "id": "1002"
            },
            "role": {
              "type": "role",
              "id": "1003"
            },
            "version_stamp": 1,
            "id": "1011",
            "last_modified": "2016-10-29T19:05:29Z"
          }
        ],
        "exceeds_total_count": false
      }
  2. Find the user you want to update, such as by email, and get the existing roles for that user. We want to update the roles for Dan Mosko, whose name is Dan@mosko. His ID is 1003. His role IDs are 1011 and 1018.

    Request:

    GET .../api/shared_spaces/<shared_space_id>/users?fields=id,name,workspace_roles&query="name EQ ^<userName>^"

    Note: workspace_roles are a technical preview. Until made public, send an HPECLIENTTYPE header with the value: HPE_REST_API_TECH_PREVIEW in your requests.

    Response:

    {
      "total_count": 1,
      "data": [
        {
          "type": "sharedspace_user",
          "creation_time": "2016-10-30T07:14:44Z",
          "version_stamp": 1,
          "uid": "8l5m9xkkz8mr3h8jd0ywr2jek",
          "name": "Dan@mosko",
          "id": "1003",
          "workspaces": {
            "total_count": 2,
            "data": [
              {
                "type": "workspace",
                "name": "DAN_TEMP",
                "id": "1003"
              },
              {
                "type": "workspace",
                "name": "default_workspace",
                "id": "1002"
              }
            ]
          },
          "last_modified": "2016-10-30T07:14:44Z",
          "workspace_roles": {
            "total_count": 2,
            "data": [
              {
                "type": "workspace_role",
                "workspace": {
                  "type": "workspace",
                  "name": "DAN_TEMP",
                  "id": "1003"
                },
                "role": {
                  "type": "role",
                  "logical_name": "role.workspace.admin",
                  "name": "Workspace Admin",
                  "id": "1003"
                },
                "id": "1018"
              },
              {
                "type": "workspace_role",
                "workspace": {
                  "type": "workspace",
                  "name": "default_workspace",
                  "id": "1002"
                },
                "role": {
                  "type": "role",
                  "logical_name": "role.workspace.admin",
                  "name": "Workspace Admin",
                  "id": "1003"
                },
                "id": "1011"
              }
            ]
          }
        }
      ],
      "exceeds_total_count": false
    }
  3. Update the role for the user with a PUT request.

    Example

    Assume that:

    • The existing roles of the user ID 1003 are:

      {"workspace_roles": {"data": [{"type": "workspace_role","id": "1018"} , {"type": "workspace_role","id": "1011"}]}}

    • The ID of the new role you want to assign is 1004.

    The update request is:

    PUT .../api/shared_spaces/<shared_space_id>/users/1003

    The request body is:

    {"workspace_roles": {"data": [{"type": "workspace_role","id": "1018"} , {"type": "workspace_role","id": "1011"} , {"type": "workspace_role","id": "1004"} ]}}

    The response body is: 

    {
      "type": "sharedspace_user",
      "creation_time": "2016-10-30T07:14:44Z",
      "version_stamp": 2,
      "uid": "8l5m9xkkz8mr3h8jd0ywr2jek",
      "name": "Dan@mosko",
      "id": "1003",
      "workspaces": {
        "total_count": 2,
        "data": [
          {
            "type": "workspace",
            "name": "default_workspace",
            "id": "1002"
          },
          {
            "type": "workspace",
            "name": "DAN_TEMP",
            "id": "1003"
          }
        ]
      },
      "last_modified": "2016-10-30T12:24:34Z",
      "first_name": "Dan",
      "workspace_roles": {
        "total_count": 3,
        "data": [
          {
            "type": "workspace_role",
            "workspace": {
              "type": "workspace",
              "name": "DAN_TEMP",
              "id": "1003"
            },
            "role": {
              "type": "role",
              "logical_name": "role.workspace.admin",
              "name": "Workspace Admin",
              "id": "1003"
            },
            "id": "1018"
          },
          {
            "type": "workspace_role",
            "workspace": {
              "type": "workspace",
              "name": "default_workspace",
              "id": "1002"
            },
            "role": {
              "type": "role",
              "logical_name": "role.workspace.admin",
              "name": "Workspace Admin",
              "id": "1003"
            },
            "id": "1011"
          },
          {
            "type": "workspace_role",
            "workspace": null,
            "role": {
              "type": "role",
              "logical_name": "role.shared.space.opb.service",
              "name": "Integration Bridge Service",
              "id": "1008"
            },
            "id": "1004"
          }
        ]
      },
    }

Back to top

Add the site admin role to a user

This section is relevant for on-premise installations only.

To work with the admin REST API, the authenticated user has to have the site admin role.

  1. Connect to ALM Octane as a site admin user:

    POST .../authentication/sign_in

    {"user":"<site admin user name>","password":"<site admin password>"}

  2. Get the ID of the site admin role:

    GET .../admin/roles?query="logical_name EQ ^role.site.admin^"

  3. Retrieve the site admin role ID from the response.

  4. List the roles the user currently has:

    GET .../admin/users/<user id>?fields=roles
    "roles": {
                    "total_count": 1,
                    "data": [{
                                    "type": "role",
                                    "id": "<role ID>"
                    }]
    }
    
  5. Prepare the Json request body for the update request (in the next step) by adding the site admin role to the existing roles:

    {
                    "roles": {
                                    "data": [{
                                                    "id": "<current user role ID>",
                                                    "type": "role"
                                    },
                                    {
                                                    "id": "<site admin role ID>",
                                                    "type": "role"
                                    }]
                    }
    }
    
  6. Update the roles of the user who should be a site admin, adding the Json body created in the previous step:

    PUT .../admin/users/<user ID>

    {
                    "roles": {
                                    "data": [{
                                                    "id": "<current user role ID>",
                                                    "type": "role"
                                    },
                                    {
                                                    "id": "<site admin role ID>",
                                                    "type": "role"
                                    }]
                    }
    }
    

Back to top