一般情報
応答の形式
正常応答の場合はHTTPのレスポンスコード200を返し、データを返すメソッドの場合はレスポンスのbody部にUTF-8エンコードのJSON形式のテキストを含みます。エラーは、ユーザ認証に失敗した場合にはHTTPレスポンスコード401(Unauthorized)、認証されたユーザが指定した操作を実行する権限を持たない場合403(Forbidden)を返します。それ以外のエラーの場合 HTTP のレスポンスコード400を返し、body部にはエラーの内容をJSON形式のテキストで記述します。
応答オブジェクト
応答でデータを返す場合、応答のデータは以下の種類のオブジェクト、もしくはこれらのオブジェクトのリストです。
| オブジェクト種別 |
説明 |
| QuserEntry |
ユーザを表すオブジェクト |
| QgroupEntry |
組織を表すオブジェクト |
| MembershipEntry |
組織の所属メンバを表すオブジェクト |
以下に、これらのオブジェクトの属性を示します。
QuserEntry
QuserEntryはユーザ情報を表すオブジェクトです。QuserEntryにはパスワードに関する情報は含まれません。
| 属性名 |
説明 |
| id |
ユーザの ID |
| name |
ユーザの名前 |
| email |
ユーザのメールアドレス |
例: 単一ユーザを返す場合(ユーザ追加・更新・検索)
{"quser":{"email":"SouthPole@questetra.com","id":0,"name":"サウスポール"}}
例: 複数ユーザを返す場合(ユーザ一覧)
{"qusers":[
{"email":"SouthPole@questetra.com","id":0,"name":"サウスポール"},
{"email":"Sumatera@questetra.com","id":1,"name":"スマトラ"},
{"email":"Maldives@questetra.com","id":2,"name":"モルディブ"},
{"email":"Hawaii@questetra.com","id":3,"name":"ハワイ"},
{"email":"Oahu@questetra.com","id":4,"name":"オアフ"},
{"email":"Solomon@questetra.com","id":5,"name":"ソロモン"},
{"email":"Galapagos@questetra.com","id":6,"name":"ガラパゴス"},
{"email":"Midway@questetra.com","id":7,"name":"ミッドウェイ"},
{"email":"Canarias@questetra.com","id":8,"name":"カナリア"},
{"email":"SaintHelena@questetra.com","id":9,"name":"セントへレナ"}
]}
QgroupEntry
QgroupEntryは組織情報を表すオブジェクトです。
| 属性名 |
型 |
説明 |
| id |
数値 |
組織のID |
| name |
文字列 |
組織の名前 |
| email |
文字列 |
組織のメールアドレス |
| parentQgroupId |
数値 |
親組織の組織ID |
| parentQgroupName |
文字列 |
親組織の名前 |
| parentQgroupEmail |
文字列 |
親組織のメールアドレス |
例: 単一組織を返す場合(組織追加・更新)
{"qgroup":{"email":"accounting@questetra.com","id":2,"name":"経理部",
"parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"全社"}}
例: 複数組織を返す場合(組織一覧)
{"qgroups":[
{"email":"org@questetra.com","id":1,"name":"全社",
"parentQgroupEmail":null,"parentQgroupId":null,"parentQgroupName":null},
{"email":"accounting@questetra.com","id":2,"name":"経理部",
"parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"全社"},
{"email":"sales@questetra.com","id":3,"name":"営業部",
"parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"全社"},
{"email":"marketing@questetra.com","id":4,"name":"マーケティング部",
"parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"全社"},
{"email":"production@questetra.com","id":5,"name":"製造部",
"parentQgroupEmail":"org@questetra.com","parentQgroupId":1,"parentQgroupName":"全社"}
]}
MembershipEntry
MembershipEntryはユーザの組織への所属状態を表すオブジェクトです。
| 属性名 |
型 |
説明 |
| quserId |
数値 |
ユーザのID |
| quserName |
文字列 |
ユーザの名前 |
| quserEmail |
文字列 |
ユーザのメールアドレス |
| qgroupId |
数値 |
親組織の組織 ID |
| qgroupName |
文字列 |
親組織の名前 |
| qgroupEmail |
文字列 |
親組織のメールアドレス |
| role |
文字列 |
メンバのロール |
例: 単一メンバを返す場合(メンバ追加・更新)
{"membership":
{"qgroupEmail":"marketing@questetra.com","qgroupId"::4,"qgroupName":"マーケティング部",
"quserEmail":"Solomon@questetra.com","quserId":5,"quserName":"ソロモン","role":"_leader"}
例: 複数メンバを返す場合(所属メンバ・所属組織一覧)
{"memberships":[
{"qgroupEmail":"marketing@questetra.com","qgroupId":4,"qgroupName":"マーケティング部",
"quserEmail":"Solomon@questetra.com","quserId":5,"quserName":"ソロモン","role":"_leader"},
{"qgroupEmail":"marketing@questetra.com","qgroupId":4,"qgroupName":"マーケティング部",
"quserEmail":"Galapagos@questetra.com","quserId":6,"quserName":"ガラパゴス","role":null},
{"qgroupEmail":"marketing@questetra.com","qgroupId":4,"qgroupName":"マーケティング部",
"quserEmail":"Midway@questetra.com","quserId":7,"quserName":"ミッドウェイ","role":null}
]}
エラー応答オブジェクト
エラー応答をJSON形式で返す場合、errorsという名前でErrorEntryの配列を返します。ErrorEntryは以下の属性を持ちます。エラー種別の詳細は「エラー一覧」の節を参照してください。
ErrorEntry
| 属性名 |
型 |
説明 |
| errorCode |
文字列 |
エラーコード |
| type |
文字列 |
エラー種別 |
| input |
文字列 |
エラーの原因となった入力値 |
例: エラー応答
{"errors":[{"errorCode":"20002","input":"foo@questetra.com","type":"QuserDoesNotExist"}]}
処理一覧
ユーザ管理 API で実行可能な処理は以下のとおりです。URL 中の<ContextRoot>は接続先のQuestetra BPM Suiteのコンテキストルートを代入してください。
| 操作 |
URL |
| ユーザ追加 |
<ContextRoot>/API/UGA/Quser/add |
| ユーザ更新 |
<ContextRoot>/API/UGA/Quser/update |
| ユーザ削除 |
<ContextRoot>/API/UGA/Quser/delete |
| ユーザ一覧 |
<ContextRoot>/API/UGA/Quser/list |
| ユーザ検索 |
<ContextRoot>/API/UGA/Quser/findByEmail |
| 組織追加 |
<ContextRoot>/API/UGA/Qgroup/add |
| 組織更新 |
<ContextRoot>/API/UGA/Qgroup/update |
| 組織削除 |
<ContextRoot>/API/UGA/Qgroup/delete |
| 組織一覧 |
<ContextRoot>/API/UGA/Qgroup/list |
| 組織検索 |
<ContextRoot>/API/UGA/Qgroup/findByName |
| 組織へのメンバ追加 |
<ContextRoot>/API/UGA/Membership/add |
| メンバのロール変更 |
<ContextRoot>/API/UGA/Membership/update |
| 組織からのメンバ削除 |
<ContextRoot>/API/UGA/Membership/delete |
| 組織に所属するメンバ一覧 |
<ContextRoot>/API/UGA/Membership/listByQgroup |
| メンバの所属する組織一覧 |
<ContextRoot>/API/UGA/Membership/listByQuser |
ユーザ追加
新しいユーザを追加します。追加したユーザはどの組織にも所属していない状態となります。
パラメータ
(*) は必須のパラメータであることを表しています。
| パラメータ名 |
説明 |
| name * |
追加するユーザの名前 |
| email * |
追加するユーザのメールアドレス |
| password * |
追加するユーザのパスワード |
応答
| オブジェクト名 |
説明 |
| quser |
追加されたユーザのQuserEntry |
発生する可能性のあるエラー
- InvalidName
- InvalidEmail
- InvalidPassword
- QuserExists
- QuserNameExists(8.1.0以降)
ユーザ更新
ユーザの名前、メールアドレス、パスワードを変更します。送信しなかったパラメータは変更されません。
パラメータ
| パラメータ名 |
説明 |
| id * |
更新するユーザのID |
| name |
新しい名前 |
| email |
新しいメールアドレス |
| password |
新しいパスワード |
応答
| オブジェクト名 |
説明 |
| quser |
変更されたユーザのQuserEntry |
発生する可能性のあるエラー
- InvalidId
- InvalidName
- InvalidEmail
- InvalidPassword
- QuserDoesNotExist
- QuserExists
- QuserNameExists(8.1.0以降)
ユーザ一覧
将来、削除する可能性があります。ユーザ検索APIの「ユーザ一覧の取得」をご利用ください。
システム内の全ユーザのリストを返します。
パラメータ
なし
応答
| オブジェクト名 |
説明 |
| qusers |
全ユーザのQuserEntryのリスト |
発生する可能性のあるエラー
なし
ユーザ検索
メールアドレスをキーにしてユーザを検索します。該当のユーザが存在しない場合は QuserDoesNotExist エラーを返します。
パラメータ
| パラメータ名 |
説明 |
| email * |
検索するユーザのメールアドレス |
応答
| オブジェクト名 |
説明 |
| quser |
該当ユーザのQuserEntry |
発生する可能性のあるエラー
- InvalidEmail
- QuserDoesNotExist
ユーザ削除
ユーザを削除します。削除するユーザに割り当て済みのタスクを引き受けるユーザを指定する必要があります。
パラメータ
| パラメータ名 |
説明 |
| id * |
削除するユーザのID |
| delegateQuserId |
タスクを引き受けるユーザのID。
7.4.0以降、必須でなくなりました。削除するユーザがタスクを持っている場合、指定が必要です。 |
| delegateQgroupId |
タスクを引き受けるユーザが、どの組織としてタスクを実行するかを指定する組織のID。
7.4.0以降、必須でなくなりました。削除するユーザがタスクを持っている場合、指定が必要です。 |
応答
なし
発生する可能性のあるエラー
- InvalidId
- InvalidDelegateQuserId
- InvalidDelegateQgroupId
- QuserDoesNotExist
- DelegateDoesNotExist
- NoneSystemAdministrator
- DelegateIsSameWithDeletingQuser
- NeedDelegate(7.4.0以降)
- YourselfUndeletable(8.4.0以降)
組織追加
新しい組織を追加します。追加する組織がどの組織に所属するかを指定する必要があります。
パラメータ
| パラメータ名 |
説明 |
| name * |
追加する組織の名前 |
| email |
追加する組織のメールアドレス |
| parentQgroupId * |
追加する組織の親組織のID |
応答
| オブジェクト名 |
説明 |
| qgroup |
追加された組織のQgroupEntry |
発生する可能性のあるエラー
- InvalidName
- InvalidEmail
- InvalidParentQgroupId
- ParentQgroupDoesNotExist
- QgroupExists
組織更新
組織の名前、メールアドレス、親組織を変更します。送信しなかったパラメータは変更されません。
パラメータ
| パラメータ名 |
説明 |
| id * |
更新する組織の ID |
| name |
新しい名前 |
| email |
新しいメールアドレス |
| parentQgroupId |
新しい親組織の ID |
応答
| オブジェクト名 |
説明 |
| qgroup |
変更された組織のQgroupEntry |
発生する可能性のあるエラー
- InvalidId
- InvalidName
- InvalidEmail
- InvalidParentQgroupId
- QgroupDoesNotExist
- ParentQgroupDoesNotExist
- QgroupExists
- NoneSystemAdministrator
- LoopedOrganizaion
組織一覧
将来、削除する可能性があります。ユーザ検索APIの「組織一覧の取得」をご利用ください。
システム内の全組織のリストを返します。
パラメータ
なし
応答
| オブジェクト名 |
説明 |
| qgroups |
全組織のQgroupEntryのリスト |
発生する可能性のあるエラー
なし
組織削除
組織を削除します。子組織を持つ組織やルート組織は削除できません。削除した組織に所属していたユーザはすべてルート組織所属に変更されます。
パラメータ
応答
なし
発生する可能性のあるエラー
- InvalidId
- QgroupDoesNotExist
- RootQgroupUndeletable
- ParentQgroupUndeletable
組織検索
組織名をキーとして組織を検索します。該当の組織が存在しない場合はQgroupDoesNotExistエラーを返します。
パラメータ
| パラメータ名 |
説明 |
| name * |
検索する組織の名前 |
応答
| オブジェクト名 |
説明 |
| qgroup |
該当組織のQgroupEntry |
発生する可能性のあるエラー
- InvalidName
- QgroupDoesNotExist
組織へのメンバ追加
組織にメンバとしてユーザを追加します。1回の呼び出しで複数のユーザや組織を指定することはできません。
パラメータ
| パラメータ名 |
説明 |
| quserId * |
メンバとして追加されるユーザのID |
| qgroupId * |
メンバを追加する組織のID |
| role |
メンバのロール。リーダの場合、「_leader」を指定します |
応答
| オブジェクト名 |
説明 |
| membership |
追加されたメンバのMembershipEntry |
発生する可能性のあるエラー
- InvalidQuserId
- InvalidQgroupId
- InvalidRole
- QuserDoesNotExist
- QgroupDoesNotExist
- MembershipExists
メンバのロール変更
組織のメンバのロールを変更します。
パラメータ
| パラメータ名 |
説明 |
| quserId * |
ロールを変更するユーザのID |
| qgroupId * |
ロールを変更する組織のID |
| role |
新しいロール。リーダの場合、「_leader」を指定します |
応答
| オブジェクト名 |
説明 |
| membership |
変更されたメンバのMembershipEntry |
発生する可能性のあるエラー
- InvalidQuserId
- InvalidQgroupId
- InvalidRole
- QuserDoesNotExist
- QgroupDoesNotExist
- MembershipDoesNotExist
- NoneSystemAdministrator
組織からメンバ削除
組織のメンバを削除します。
パラメータ
| パラメータ名 |
説明 |
| quserId * |
削除するメンバのユーザID |
| qgroupId * |
メンバを削除する組織のID |
応答
なし
発生する可能性のあるエラー
- InvalidQuserId
- InvalidQgroupId
- QuserDoesNotExist
- QgroupDoesNotExist
- MembershipDoesNotExist
- NoneSystemAdministrator
組織に所属するメンバ一覧
指定した組織に直接所属するユーザの一覧を返します。応答はQuserEntryではなくMembershipEntryのリストを返します。
パラメータ
| パラメータ名 |
説明 |
| id * |
検索対象の組織のID |
応答
| オブジェクト名 |
説明 |
| memberships |
該当のMembershipEntryのリスト |
発生する可能性のあるエラー
- InvalidId
- QgroupDoesNotExist
メンバの所属する組織一覧
指定したユーザの直接所属する組織の一覧を返します。応答はQgroupEntryではなくMembershipEntryのリストを返します。
パラメータ
| パラメータ名 |
説明 |
| id * |
検索対象のユーザのID |
応答
| オブジェクト名 |
説明 |
| memberships |
該当のMembershipEntryのリスト |
発生する可能性のあるエラー
- InvalidId
- QuserDoesNotExist
エラー一覧
| エラー種別 |
エラーコード |
説明 |
| InvalidId |
10001 |
不正なidの指定。idは0.09223372036854775807の整数 |
| InvalidQuserId |
10002 |
不正なquserIdの指定。quserIdは0.09223372036854775807の整数 |
| InvalidQgroupId |
10003 |
不正なqgroupIdの指定。qgroupIdは0.09223372036854775807の整数 |
| InvalidName |
10004 |
不正なnameの指定。nameは64文字以内の文字列 |
| InvalidEmail |
10005 |
不正なemailの指定。emailは256文字以内のメールアドレス |
| InvalidPassword |
10006 |
不正なpasswordの指定。password は8.016文字の半角英数記号。システム管理者が設定したポリシーに適合していない(8.2.0以降) |
| InvalidDelegateQuserId |
10007 |
不正なdelegateQuserIdの指定。qgroupIdは0.09223372036854775807の整数 |
| InvalidDelegateQgroupId |
10008 |
不正なdelegateQgroupIdの指定。qgroupIdは0.09223372036854775807の整数 |
| InvalidParentQgroupId |
10009 |
不正なparentQgroupIdの指定。qgroupIdは0.09223372036854775807の整数 |
| InvalidRole |
10010 |
不正なroleの指定。ロールは空か「_leader」のみ |
| QuserExists |
20001 |
emailの重複するユーザが存在する |
| QuserDoesNotExist |
20002 |
指定したユーザが存在しない |
| QgroupExists |
20003 |
nameの重複する組織が存在する |
| QgroupDoesNotExist |
20004 |
指定した組織が存在しない |
| MembershipExists |
20005 |
重複する組織のメンバが存在する |
| MembershipDoesNotExist |
20006 |
指定した組織のメンバが存在しない |
| DelegateDoesNotExist |
20007 |
ユーザ削除時にタスクを引き継ぐユーザが存在しない |
| NoneSystemAdministrator |
20008 |
操作の結果システム管理者権限を持つユーザが1人もいなくなる |
| ParentQgroupUndeletable |
20009 |
子組織を持つ組織を削除しようとした |
| RootQgroupUndeletable |
20010 |
ルート組織を削除しようとした |
| LoopedOrganization |
20011 |
組織の階層構造がループになるような変更をしようとした |
| ParentQgroupDoesNotExist |
20013 |
親組織で指定した組織が存在しない |
| DelegateIsSameWithDeletingQuser |
20014 |
ユーザ削除時のタスク引き継ぎユーザに削除ユーザを指定した |
| NeedDelegate |
20015 |
ユーザ削除時に、削除するユーザがマイタスクを保持していているが、代理ユーザの指定がされていない(7.4.0以降) |
| QuserNameExists |
20017 |
nameが重複したユーザが存在する(8.1.0以降) |
| YourselfUndeletable |
20022 |
APIを実行しているユーザ自身は削除できません(8.4.0以降) |
| UserNumberExceeding |
30005 |
ユーザ数制限を超えてユーザを追加しようとした |
|