Skip to content

SonaRemoveUserRole

Description

This function removes a role from an existing user. If the user does not have the requested role, no change is made.

Warning

Removing a role may be blocked when it would remove participant signups, affect studies managed by the user, or leave the user without any role. Review the returned result and error message before treating the operation as successful.

Input Parameters

Below are the following input parameters for use with the SonaRemoveUserRole API function.

Parameter Description / Possible Values
api_key Use API key generated for Sona admin user
person_id Numeric identifier of the user whose role will be changed.
role Uppercase role code to remove:
E = Researcher
P = Principal Investigator
I = Instructor
S = Participant

The Administrator role (A) cannot be removed through this function.

Output Parameters

The function returns an integer result.

Type Return Value Description
Success 1 The role was removed.
No change 3 The user did not have the requested role.
Authentication Failed -1 through -7 Standard authentication errors.
Error -9 User not found.
Error -10 Invalid role.
Error -11 The PI feature is not enabled.
Error -12 Removing the participant role would remove existing study signups. The error message includes the affected signup count.
Error -13 Removing the role would affect studies managed by the user and may delete associated studies. The error message includes the affected signup count.
Error -14 The requested role is the user's only remaining role. Delete the user instead.
Error -15 The role could not be removed or another unclassified error occurred.

Sample Input

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaRemoveUserRole?api_key=YOUR_API_KEY&person_id=15&role=E

URL components

Component Value
Scheme https
Host myschool.sona-systems.com
Service path /services/SonaAPI.svc
Function SonaRemoveUserRole

Query parameters

api_key = YOUR_API_KEY
person_id = 15
role = E

Sample Output

<SonaRemoveUserRoleResponse
  xmlns="https://www.sona-systems.com/"
  xmlns:a="http://schemas.datacontract.org/2004/07/emsdotnet.sonasystems"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <SonaRemoveUserRoleResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaRemoveUserRoleResult>
</SonaRemoveUserRoleResponse>