POST: Create a user
The POST operation can be used to create both internal, native ALM Octane 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.
Creating internal, native ALM Octane users
When creating a user, the email address must be unique. If another user exists with the same email address, an error is returned.
Bulk POSTs are supported.
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:
-
Information about configuring LDAP settings in the ldap.conf file: Modify site settings
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.
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 }
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"
},
} ] }
- 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 }
See also: