Search this site

Workflow Sample

Workflow Sample
Workflow Sample

Contact

User Management API

Contents

  1. 1 General Information
    1. 1.1 Responses
    2. 1.2 Response Objects
    3. 1.3 Error Response Object
  2. 2 List of Operations
    1. 2.1 Add User
    2. 2.2 Update Users
    3. 2.3 See User List
    4. 2.4 Search User
    5. 2.5 Delete User
    6. 2.6 Add Organization
    7. 2.7 Update Organization
    8. 2.8 List Organizations
    9. 2.9 Delete Organization
    10. 2.10 Search Organization
    11. 2.11 Add Member to Organization
    12. 2.12 Change Member's Role
    13. 2.13 Delete Member From Organization
    14. 2.14 List members in a organization
    15. 2.15 List organizations a member belongs to
  3. 3 List of Errors

General Information

Responses

The response when there are no errors is HTTP 200. When there is data to be returned, UTF-8 encoded JSON text will be included in the body of the response. For errors regarding user authentication an HTTP 401 error (Unauthorized) will be returned, and when an authenticated user does not have authorization to perform an operation an HTTP  403 error (Forbidden) will be returned. Other errors will result in an HTTP 400 response with the error details included in the body in JSON text.

Response Objects

When data is returned, the response data will be one of the following objects or a list of these objects.
 Type of Object  Explanation
 QuserEntry  Object indicating a user
 QgroupEntry  Object indicating a organization
 MembershipEntry  Object indicating a member in a organization
Below are the attributes of these objects.

QuserEntry

QuserEntry is an object that includes user information. QuserEntry does not include password information.
 Attribute  Explanation
 id  User ID
 name  User name
 email  User email address

Sample: Returning a single user (Add, update or search)

{"quser":{"email":"SouthPole@questetra.com","id":0,"name":"SouthPole"}}

Sample: Returning multiple users (List)

{"qusers":[
  {"email":"SouthPole@questetra.com","id":0,"name":"SouthPole"},
  {"email":"Sumatera@questetra.com","id":1,"name":"Sumatera"},
  {"email":"Maldives@questetra.com","id":2,"name":"Maldives"},
  {"email":"Hawaii@questetra.com","id":3,"name":"Hawaii"},
  {"email":"Oahu@questetra.com","id":4,"name":"Oahu"},
  {"email":"Solomon@questetra.com","id":5,"name":"Solomon"},
  {"email":"Galapagos@questetra.com","id":6,"name":"Galapagos"},
  {"email":"Midway@questetra.com","id":7,"name":"Midway"},
  {"email":"Canarias@questetra.com","id":8,"name":"Canarias"},
  {"email":"SaintHelena@questetra.com","id":9,"name":"SaintHelena"}
]}

QgroupEntry

QgroupEntry is an object that includes organization information.

 Attribute  Type  Explanation
 id  Number  Organization ID
 name  String  Organization name
 email  String  Organization email address
 parentQgroupId  Number  Parent organization ID
 parentQgroupName  String  Parent organization name
 parentQgroupEmail  String  Parent organization email address

Sample: Returning a single organization (Add or update)

{"qgroup":{"email":"accounting@questetra.com","id":2,"name":"Accounting",
   "parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"Org"}}

Sample: Returning multiple organizations (List)

{"qgroups":[
  {"email":"org@questetra.com","id":1,"name":"Org",
   "parentQgroupEmail":null,"parentQgroupId":null,"parentQgroupName":null},
  {"email":"accounting@questetra.com","id":2,"name":"Accounting",
   "parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"Org"},
  {"email":"sales@questetra.com","id":3,"name":"Sales",
    "parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"Org"},
  {"email":"marketing@questetra.com","id":4,"name":"Marketing",
    "parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"Org"},
  {"email":"production@questetra.com","id":5,"name":"Production",
    "parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"Org"}
]}

MembershipEntry

MembershipEntry is an object that includes user information on organization membership.
 Attribute  Type  Explanation
 quserId  Number  User ID
 quserName  String  User name
 quserEmail  String  User email address
 qgroupId  Number  Organization ID
 qgroupName  String  Organization name
 qgroupEmail  String  Organization address
 role  String  Member's role

Sample: Returning a single member (Add or update)

{"membership":
  {"qgroupEmail":"marketing@questetra.com","qgroupId"::4,"qgroupName":"Marketing",
   "quserEmail":"Solomon@questetra.com","quserId":5,"quserName":"Solomon","role":"_leader"}

Sample: Returning multiple members (Member list, organization list)

{"memberships":[
  {"qgroupEmail":"marketing@questetra.com","qgroupId":4,"qgroupName":"Marketing",
   "quserEmail":"Solomon@questetra.com","quserId":5,"quserName":"Solomon","role":"_leader"},
  {"qgroupEmail":"marketing@questetra.com","qgroupId":4,"qgroupName":"Marketing",
   "quserEmail":"Galapagos@questetra.com","quserId":6,"quserName":"Galapagos","role":null},
  {"qgroupEmail":"marketing@questetra.com","qgroupId":4,"qgroupName":"Marketing",
   "quserEmail":"Midway@questetra.com","quserId":7,"quserName":"Midway","role":null}
]}

Error Response Object

When error response is returned as JSON text, an ErrorEntry sequence is always sent under the name "errors." ErrorEntry attributes are listed below. For details on error types, see the [List of Errors] section.

ErrorEntry

 Attribute  Type  Explanation
 errorCode  String  Error code
 type  String  Error type
 input  String  Input that caused error

Sample: Error response

{"errors":[{"errorCode":"20002","input":"foo@questetra.com","type":"QuserDoesNotExist"}]}

List of Operations

Operations that can be handled by User Management API are listed below. Replace <ContextRoot> in the URLs with the Questetra BPM Suite context root you are connecting to.
 Operation  URL
 Add user  <ContextRoot>/API/UGA/Quser/add
 Update user  <ContextRoot>/API/UGA/Quser/update
 Delete user  <ContextRoot>/API/UGA/Quser/delete
 List users  <ContextRoot>/API/UGA/Quser/list
 Search user  <ContextRoot>/API/UGA/Quser/findByEmail
 Add organization  <ContextRoot>/API/UGA/Qgroup/add
 Update organization  <ContextRoot>/API/UGA/Qgroup/update
 Delete organization  <ContextRoot>/API/UGA/Qgroup/delete
 List organizations  <ContextRoot>/API/UGA/Qgroup/list
 Search organization  <ContextRoot>/API/UGA/Qgroup/findByName
 Add member to organization  <ContextRoot>/API/UGA/Membership/add
 Change member's role  <ContextRoot>/API/UGA/Membership/update
 Delete member from organization  <ContextRoot>/API/UGA/Membership/delete
 List members in a organization  <ContextRoot>/API/UGA/Membership/listByQgroup
 List organizations a member belongs to  <ContextRoot>/API/UGA/Membership/listByQuser

Add User

This adds a new user. The added user will by default not belong to any organization.

Parameters

Asterisk (*) indicates required parameters.
 Parameter names  Explanation
 name *  Name of new user
 email *  Email address of new user
 password *  Password of new user

Response

 Object  Explanation
 quser  QuserEntry of new user

Possible Errors

  • InvalidName
  • InvalidEmail
  • InvalidPassword
  • QuserExists
  • QuserNameExists(8.1.0 or later)

Update Users

This changes the user name, email address and/or password. Parameters that are not sent are not changed.

Parameters

 Parameter names  Explanation
 id *  ID of updated user
 name  New user name
 email  New email address
 password  New password

Response

 Object  Explanation
 quser  QuserEntry of updated user

Possible Errors

  • InvalidId
  • InvalidName
  • InvalidEmail
  • InvalidPassword
  • QuserDoesNotExist
  • QuserExists
  • QuserNameExists(8.1.0 or later)

See User List

This may deleted in the future.　See　”Acquire User List” in User Search API

This returns a list of all users in the system.

Parameters

None

Response

 Object  Explanation
 qusers  List of QuserEntry of all users

Possible Errors

None

Search User

This may deleted in the future.　See　”Search User List” in User Search API

This uses an email address to search for a user. If there is no applicable user, a QuserDoesNotExist error will return.

Parameters

 Parameter names  Explanation
 email *  Email address of user to be searched

Response

 Object  Explanation
 quser  QuserEntry of user

Possible Errors

  • InvalidEmail
  • QuserDoesNotExist

Delete User

This deletes a user. You will need to specify another user to accept all unfinished Tasks that are allocated to the user you are going to delete.

Parameters

 Parameter names  Explanation
 id *  ID of user to be deleted
 delegateQuserId  ID of user who will accept unfinished Tasks
Not indispensable v.7.4.0. or later
Need delegation when deleting user holds task
 delegateQgroupId  Organization ID, to indicate which organization the user who will accept the Tasks will execute them under
Not indispensable v.7.4.0. or later
Need delegation when deleting user holds task

Response

None

Possible Errors

  • InvalidId
  • InvalidDelegateQuserId
  • InvalidDelegateQgroupId
  • QuserDoesNotExist
  • DelegateDoesNotExist
  • NoneSystemAdministrator
  • DelegateIsSameWithDeletingQuser
  • NeedDelegate (7.4.0 or later)
  • YourselfUndeletable (8.4.1 or later)

Add Organization

This adds a organization. You will need to specify which organization the new organization exists under.

Parameters

 Parameter names  Explanation
 name *  Name of new organization
 email  Email address of new organization
 parentQgroupId *  ID of parent organization of new organization

Response

 Object  Explanation
 qgroup  QgroupEntry of new organization

Possible Errors

  • InvalidName
  • InvalidEmail
  • InvalidParentQgroupId
  • ParentQgroupDoesNotExist
  • QgroupExists

Update Organization

This updates a organization's name, email address and/or parent organization. Parameters that are not sent are not changed.

Parameters

 Parameter names  Explanation
 id *  ID of organization to be updated
 name  New name
 email  New email address
 parentQgroupId  ID of new parent organization

Response

 Object  Explanation
 qgroup  QgroupEntry of updated organization

Possible Errors

  • InvalidId
  • InvalidName
  • InvalidEmail
  • InvalidParentQgroupId
  • QgroupDoesNotExist
  • ParentQgroupDoesNotExist
  • QgroupExists
  • NoneSystemAdministrator
  • LoopedOrganization

List Organizations

This may deleted in the future.　See　”Acquire Organization List” in User Search API

This returns a list of all organizations in the system.

Parameters

None

Response

 Object  Explanation
 qgroups  List of QgroupEntry of all organizations

Possible Errors

None

Delete Organization

This deletes a organization. Parent organizations and root organizations cannot be deleted. Users that belong to a organization that is to be deleted will all move to the root organization.

Parameters

 Parameter names  Explanation
 id *  ID of organization to be deleted

Response

None

Possible Errors

  • InvalidId
  • QgroupDoesNotExist
  • RootQgroupUndeletable
  • ParentQgroupUndeletable

Search Organization

This may deleted in the future.　See　”Search Organization” in User Search API

This uses a organization name to search for a organization. If there is no applicable organization, a QgroupDoesNotExist error will return.

Parameters

 Parameter names  Explanation
 name *  Name of organization to be searched

Response

 Object  Explanation
 qgroup  QgroupEntry of organization

Possible Errors

  • InvalidName
  • QgroupDoesNotExist

Add Member to Organization

This adds a user as a member to a organization. Multiple users/organizations cannot be specified in one request.

Parameters

 Parameter names  Explanation
 quserId *  ID of user to be added as member
 qgroupId *  ID of organization that member will be added to
 role  Member's role. If the user will be a leader, add _leader

Response

 Object  Explanation
 membership  MembershipEntry of added member

Possible Errors

  • InvalidQuserId
  • InvalidQgroupId
  • InvalidRole
  • QuserDoesNotExist
  • QgroupDoesNotExist
  • MembershipExists

Change Member's Role

This changes the role of a member of a organization.

Parameters

 Parameter names  Explanation
 quserId *  ID of user whose role is to be changed
 qgroupId *  ID of organization in which role is to be changed
 role  New role. If the new role is a leader, add _leader

Response

 Object  Explanation
 membership  MembershipEntry of user with changed role

Possible Errors

  • InvalidQuserId
  • InvalidQgroupId
  • InvalidRole
  • QuserDoesNotExist
  • QgroupDoesNotExist
  • MembershipDoesNotExist
  • NoneSystemAdministrator

Delete Member From Organization

This deletes a member from a organization.

Parameters

 Parameter names  Explanation
 quserId *  ID of member to be deleted
 qgroupId *  ID of organization the member is to be deleted from

Response

None

Possible Errors

  • InvalidQuserId
  • InvalidQgroupId
  • QuserDoesNotExist
  • QgroupDoesNotExist
  • MembershipDoesNotExist
  • NoneSystemAdministrator

List members in a organization

This returns a list of users that directly belong to a specified organization. The response is a list of MembershipEntry, not QgroupEntry.

Parameters

 Parameter names  Explanation
 id *  ID of organization to be searched

Response

 Object  Explanation
 memberships  Corresponding MembershipEntry list

Possible Errors

  • InvalidId
  • QgroupDoesNotExist

List organizations a member belongs to

This returns a list of organizations that a specified user directly belongs to. The response is a list of MembershipEntry, not QgroupEntry.

Parameters

 Parameter names  Explanation
 id *  ID of user to be searched

Response

 Object  Explanation
 memberships  Corresponding MembershipEntry list

Possible Errors

  • InvalidId
  • QuserDoesNotExist

List of Errors

 Error type  Error code  Explanation
 InvalidId  10001  An invalid ID was specified. ID should be between 0 and 9223372036854775807.
 InvalidQuserId  10002  An invalid quserId was specified. quserId should be an integer between 0 and 9223372036854775807.
 InvalidQgroupId  10003  An invalid qgroupId was specified. qgroupId should be an integer between 0 and 9223372036854775807.
 InvalidName  10004  An invalid name was specified. name should be a string with max 64 characters.
 InvalidEmail  10005  An invalid email was specified. email should be an email address with max 256 characters.
 InvalidPassword  10006  An invalid password was specified. Passwords must be strings with minimum 8, maximum 16 characters. Passwords must satifsy configured password policy(8.2.0 or later).
 InvalidDelegateQuserId  10007  An invalid delegateQuerId was specified. delegateQuerId should be an integer between 0 and 9223372036854775807.
 InvalidDelegateQgroupId  10008  An invalid delegateQgroupId was specified. delegateQgroupId should be an integer between 0 and 9223372036854775807.
 InvalidParentQgroupId  10009  An invalid parentQgroupId was specified. parentQgroupId should be an integer between 0 and 9223372036854775807.
 InvalidRole  10010  An invalid role was specified. Role should be blank or "_leader."
 QuserExists  20001  A user with the same email address already exists.
 QuserDoesNotExist  20002  The specified user does not exist.
 QgroupExists  20003  A organization with the same name already exists.
 QgroupDoesNotExist  20004  The specified organization does not exist.
 MembershipExists  20005  The same member already exists in the organization.
 MembershipDoesNotExist  20006  The specified member does not exist in organization.
 DelegateDoesNotExist  20007  There is no user to take over Tasks if specified user is deleted.
 NoneSystemAdministrator  20008  There will be no user with system administrator authorization if the operation is completed.
 ParentQgroupUndeletable  20009  Parent organizations cannot be deleted.
 RootQgroupUndeletable  20010  Root organizations cannot be deleted.
 LoopedOrganization  20011  The organization change will result in looped organizational structure.
 ParentQgroupDoesNotExist  20013  The specified parent organization does not exist.
 DelegateIsSameWithDeletingQuser  20014  Delegating deleted user as inheritor
 NeedDelegate  20015  Delegating  user is not specified when My task holder is deleted. (7.4.0 or later)
 QuserNameExists  20017  A user with the same name already exists. (8.1.0 or later)
 YourselfUndeletable  20022  A user running the API cannot delete itself. (8.4.0 or later)
 UserNumberExceeding  30005  The operation will result in the number of users exceeding the allowed limit.