POST: Create a user

The POST operation can be used to create both internal, native ALM Octane users or SSO users, and LDAP users.

Contexts in which you can add users

To create a user, perform a POST in one of the following contexts: 

Context Notes
Shared space

Space admin permissions are required.

You can create a shared space user without assigning a role. In this case, the user is created with the predefined viewer role. For an example on assigning roles later using the REST API, see PUT: Update a user's role.

If you do not specify a work space when POSTing the user, the default_workspace is used.
Workspace

Workspace admin permissions are required.

Note: Most roles can be customized. Roles and their permissions might be different for your organization.

You must assign a role when creating a workspace user.

You cannot add users in the site context using the REST API.

Back to top

Creating internal, native or SSO users

Use the following fields when creating a new user:

Field Required Must be unique
uid
name

(used for login)
first_name
last_name
email

If another user exists with the same email address, an error is returned.

Bulk POSTs are supported.

Back to top

Creating LDAP users

As with any other user, use the POST operation to create new LDAP users.

To update existing LDAP user details, re-import the users. For details, see Manage site users.

When creating LDAP users with the REST API, most LDAP properties must be provided with the values as specified in LDAP and ALM Octane Settings. For details about mapping attributes between LDAP and ALM Octane, see:

Property Description
uid

The LDAP attribute that should be used as the immutable, globally-unique identifier. Mandatory.

In this documentation, we also refer to this as the UUID (universally unique ID).

To work with ALM Octane, we generally use entryUUID for OpenLDAP. However, depending on your LDAP, this attribute might be different, such as objectGUID, GUID, or orclguid.

This is the attribute by which ALM Octane identifies each user internally for synchronization between ALM Octane and LDAP, including when importing users into ALM Octane.

If not provided, an error is returned.
ldap_dn

The LDAP dn (distinguished name) often set to the LDAP entryDN attribute. Mandatory. If not provided, an error is returned.

This is comprised of several pairs of attributes and values. The dn is a unique string that typically contains other LDAP attributes, such as cn, ou, and dc.

ldap_server_id ID for the LDAP server. Optional.
name

If using an actual email, this property is optional. In this case, ALM Octane uses the email as the default value for the name property.
password Passwords are managed by the LDAP system, and should not be provided in the POST command.

For an example, see Example: Adding an LDAP user to a workspace.

Back to top

Examples

  • Add a single user to the shared space

  • Internal, native ALM Octane user management

Because no workspace is specified in this example, the user is added to default_workspace. 

*** Request ***
POST .../api/shared_spaces/<space_id>/users
{
  "data": [
    {
      "email": "marta.santora@TheCompany.com",
      "first_name": "marta",
      "last_name": "santora",
      "name": "Marta Santora",
      "password": "Welcome1",
      "phone1": "969-979-9123"
    }
  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "sharedspace_user",
      "id": "1015"
    }
  ],
  "exceeds_total_count": false
}

Back to top

This example attempts to create two users. However only one is created, because the other user has the same email address as an existing user. Response code 409 is returned, "A site user with this ID already exists."

*** Request ***
POST .../api/shared_spaces/<space_id>/users
{
  "data": [
    {
      "email": "marta.santora@TheCompany.com",
      "first_name": "marta",
      "last_name": "santora",
      "name": "Marta Santora",
      "password": "Welcome1",
      "phone1": "969-979-9123"
    },
 
    {
      "email": "leroy.brown@TheCompany.com",
      "first_name": "leroy",
      "last_name": "brown",
      "name": "Leroy Brown",
      "password": "Welcome1",
      "phone1": "123-356-0123"
    }

  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "sharedspace_user",
      "id": "1018"
    }
  ],
  "exceeds_total_count": false,
  "errors": [
    {
      "index": 0,
      "error_code": "platform.duplicate_entity_error",
      "correlation_id": "md7goq75nzeyquvx77x1g8yzj",
      "description": "A site_user with this email already exists.",
      "description_translated": "A site_user with this email already exists.",
      "properties": {
        "entity_type": "site_user",
        "message": "service=[CreateServiceImpl], blFlowCommand=[SharedspaceUserCreateCommand], token=[SharedspaceUserEntityToken] has thrown an exception and terminated BL flow. See service result log message for details. Error=[A site_user with this email already exists.]",
      "field_name": "email"
      },
    }
  ]
}

Back to top

  • Add a single user to a workspace
  • Internal, native ALM Octane user management

When adding a user to a workspace, make sure to specify a role.

In this example, 1003 refers to the leader role. The PUT: Update a user's role example demonstrates how to get a list of existing roles. 

*** Request ***
POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/workspace_users
{
  "data": [
    {
      "email": "marta.santora@TheCompany.com",
      "first_name": "marta",
      "last_name": "santora",
      "name": "Marta Santora",
      "password": "Welcome1",
      "phone1": "969-979-9123", 
      "roles": {
        "data": [
          {
            "type": "user_role",
            "id": "1003"
          }
        ]
      }
    }
  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "workspace_user",
      "id": "1021"
    }
  ],
  "exceeds_total_count": false
}

  • Add a single user to a workspace

  • LDAP user management

*** Request ***
POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/workspace_users
{
  "data": [
    {
      "uid": "b5d4a886-2347-435a-8557-e3d8561b5f38",
      "email": "sally.smith@TheCompany.com",
      "first_name": "sally",
      "last_name": "smith",
      "ldap_dn": "cn=Sally.Smith@TheCompany,ou=MyConglomerate,dc=com",
      "ldap_server_id": 1001,
      "name": "sally@TheCompany.com",
      "phone1": "969-979-9123",
      "roles": {
        "data": [
          {
            "type": "user_role",
            "id": "1003"
          }
        ]
      }
    }
  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "workspace_user",
      "id": "1021"
    }
  ],
  "exceeds_total_count": false
}

Back to top

See also: