Skip to content
Jump to bottom

Cleanup. Add comments to API methods. #12

Merged
merged 1 commit into from
Feb 29, 2024
+395 −344
Merged

Cleanup. Add comments to API methods. #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
415 changes: 192 additions & 223 deletions Controller/GrouperGroupsController.php
View file
Open in desktop

Large diffs are not rendered by default.

168 changes: 99 additions & 69 deletions Lib/GrouperApiAccess.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ public function __construct(array $cfg)
* @param string $groupName
* @param string $addUserId
*
* @example https://github.com/Internet2/grouper/blob/b1c7b14e30b3f73f58768fc75cf845ee9f1594ef/grouper-ws/grouper-ws/doc/samples/addMember/WsSampleAddMemberRest2_xml.txt
* @return bool Requests success or not
* @throws GrouperLiteWidgetException|JsonException
*/
Expand Down Expand Up @@ -202,7 +203,6 @@ public function createGroupWithTemplate(array $queryData): array
}

/**
*
* For creating/updating Ad-Hoc groups not using the Grouper Template format
*
* Create or Update a Group where User is Admin/Owner
Expand All @@ -215,6 +215,8 @@ public function createGroupWithTemplate(array $queryData): array
* @return bool True if added or updated successful
* @throws GrouperLiteWidgetException
* @throws JsonException
*
* @example https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/doc/samples/groupSave/WsSampleGroupSaveRestLite_xml.txt
*/
public function createUpdateGroup(string $actAsUserId, string $groupName, string $stem, string $groupDescription ): bool
{
Expand All @@ -238,7 +240,7 @@ public function createUpdateGroup(string $actAsUserId, string $groupName, string
]
]
];
$actionEndpoint = "/groups";
$actionEndpoint = '/groups';

try {
$results = $this->http->sendRequest('POST',
Expand All @@ -249,30 +251,37 @@ public function createUpdateGroup(string $actAsUserId, string $groupName, string
throw $e;
}

return isset($results['WsGroupSaveResults']['results']['resultMetadata']['resultCode'])
&& $results['WsGroupSaveResults']['results']['resultMetadata']['resultCode'] === GrouperResultCodesEnum::SUCCESS;
if(isset($results['error']) && $results['error']) {
$cakeExceptionClass = $results['cakeException'];
throw new $cakeExceptionClass($results['message']);
}

// XXX This is not required, since by now i know that the request has succeeded,
// but i am leaving it here for the time being
return isset($results['WsGroupSaveResults']['resultMetadata']['resultCode'])
&& in_array($results['WsGroupSaveResults']['resultMetadata']['resultCode'],
[GrouperResultCodesEnum::SUCCESS, GrouperResultCodesEnum::SUCCESS_UPDATED],
true);
}

/**
*
* Method used to DELETE a Group in Grouper via the Template method.
*
* @param array $queryData Array of conditions and data adding new Grouper Group
* @param string $actAsUserId
* @param string $workingGroupExt
*
* @return bool True if deleted successfully
* @throws GrouperLiteWidgetException|JsonException
*
* @throws GrouperLiteWidgetException
* @throws JsonException
*/
public function deleteGroupWithTemplate(array $queryData): bool
public function deleteGroupWithTemplate(string $actAsUserId, string $workingGroupExt): bool
{
$workingGroupExt = $queryData['workingGroupExt'];
$userId = $queryData['userId'];

$groupToDelete = [
'WsRestGshTemplateExecRequest' => [
'gshTemplateActAsSubjectLookup' => [
'subjectSourceId' => 'ldap',
'subjectId' => $userId
'subjectId' => $actAsUserId
],
'ownerStemLookup' => [
'stemName' => 'ref:incommon-collab'
Expand All @@ -288,7 +297,7 @@ public function deleteGroupWithTemplate(array $queryData): bool
]
];

$actionEndpoint = "/gshTemplateExec";
$actionEndpoint = '/gshTemplateExec';

try {
$results = $this->http->sendRequest('POST',
Expand Down Expand Up @@ -337,7 +346,7 @@ public function getGroupInfo(string $groupName): array
]
]
];
$actionEndpoint = "/attributeAssignments";
$actionEndpoint = '/attributeAssignments';

try {
$results = $this->http->sendRequest('POST',
Expand All @@ -360,7 +369,7 @@ public function getGroupInfo(string $groupName): array
}

/**
* Get Groups that User is a member of from Grouper.
* Returns all the groups the active user is a member of, that they are allowed to see.
*
* Note: Params added at end make sure that the groups returned can only be viewed by the member logged into
* Grouper Lite
Expand Down Expand Up @@ -392,19 +401,45 @@ public function getUserGroupMemberships(string $actorUserId, string $userId): ar
}

/**
* Returns either the groups the user is able to Opt into or can manage the memberships of.
* Used for requests made to Membership endpoint in Grouper WS
*
* @param string $userId
* @param string $actAsUserId
* @param string $groupType
*
* @return array Group records associated to calling method
* @throws GrouperLiteWidgetException
* @see getOwnedStems()
* @see getOptinGroups()
* @see getOptOutGroups()
* @see getOwnedGroups()
*
* @example https://github.com/Internet2/grouper/blob/b1c7b14e30b3f73f58768fc75cf845ee9f1594ef/grouper-ws/grouper-ws/doc/samples/getMemberships/WsSampleGetMembershipsRest2_xml.txt#L20
*
* $: > grouperClientAlias --debug --operation=getMembershipsWs --subjectIds=john.b.doe@at.internet2.edu,subjectAll --actAsSubjectId=john.b.doe@at.internet2.edu
*
* POST /grouper-ws/servicesRest/5.8.1/memberships HTTP/1.1
* Connection: close
* Authorization: Basic xxxxxxxxxxxxxxxx
* User-Agent: Jakarta Commons-HttpClient/3.1
* Host: grouper.dev.at.internet2.edu:-1
* Content-Length: 208
* Content-Type: application/json; charset=UTF-8
*
* {
* "WsRestGetMembershipsRequest":{
* "actAsSubjectLookup":{
* "subjectId":"john.b.doe@at.internet2.edu"
* },
* "wsSubjectLookups":[
* {
* "subjectId":"john.b.doe@at.internet2.edu"
* },
* {
* "subjectId":"subjectAll"
* }
* ]
* }
* }
*/
public function getGrouperUserMemberships(string $userId, string $groupType): array
public function getGrouperUserMemberships(string $userId, string $actAsUserId, string $groupType): array
{
if(!in_array($groupType, [
GrouperGroupTypeEnum::OPTINS,
Expand All @@ -423,9 +458,17 @@ public function getGrouperUserMemberships(string $userId, string $groupType): ar
true);

// Build request logic
$data = [];
$data['WsRestGetMembershipsRequest']['fieldName'] = $groupType;
$data['WsRestGetMembershipsRequest']['wsSubjectLookups'][0]['subjectId'] = $isOptinsOrOptouts ? GrouperConfigEnums::ALL : $userId;
$data = [
'WsRestGetMembershipsRequest' => [
'fieldName' => $groupType,
'actAsSubjectLookup' => [
'subjectId' => true ? '': $actAsUserId
],
'wsSubjectLookups' => [
['subjectId' => $isOptinsOrOptouts ? GrouperConfigEnums::ALL : $userId]
],
]
];

if ($isOptinsOrOptouts) {
// Build request logic, 2 subjectId's, second is for when user in "Secret" Optin/Optout Group
Expand All @@ -443,7 +486,7 @@ public function getGrouperUserMemberships(string $userId, string $groupType): ar
throw $e;
}

return $results;
return $results['WsGetMembershipsResults']['wsGroups'] ?? [];
}

/**
Expand All @@ -454,6 +497,36 @@ public function getGrouperUserMemberships(string $userId, string $groupType): ar
*
* @return array Listing of Members belonging to Grouper Group
* @throws GrouperLiteWidgetException|JsonException|NotFoundException
* @example https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/doc/samples/getGroups/WsSampleGetGroupsRest_json.txt
*
* $: > grouperClientAlias --debug=true --operation=getMembersWs --actAsSubjectId=john.b.doe@at.internet2.edu --subjectAttributeNames=name --groupNames=ref:incommon-collab:co:member
* WebService: connecting to URL: 'https://grouper.dev.at.internet2.edu/grouper-ws/servicesRest/5.8.1/groups'
*
* ################ REQUEST START (indented) ###############
*
* POST /grouper-ws/servicesRest/5.8.1/groups HTTP/1.1
* Connection: close
* Authorization: Basic xxxxxxxxxxxxxxxx
* User-Agent: Jakarta Commons-HttpClient/3.1
* Host: grouper.dev.at.internet2.edu:-1
* Content-Length: 201
* Content-Type: application/json; charset=UTF-8
*
* {
* "WsRestGetMembersRequest":{
* "wsGroupLookups":[
* {
* "groupName":"ref:incommon-collab:co:member"
* }
* ],
* actAsSubjectLookup":{
* "subjectId":"john.b.doe@at.internet2.edu"
* },
* "subjectAttributeNames":[
* "name"
* ]
* }
* }
*/
public function getGroupMembers(string $actorUserId, string $groupName): array
{
Expand Down Expand Up @@ -489,49 +562,6 @@ public function getGroupMembers(string $actorUserId, string $groupName): array
return $results['WsGetMembersResults']['results'][0]['wsSubjects'] ?? [];
}

/**
* Gets all available Optin/OptOut groups in Grouper
*
* Returns Optin/OptOut groups that can be joined/left
*
* @param string $userId
* @param string $groupType
*
* @return array Optin groups from Grouper
* @throws GrouperLiteWidgetException
*/
public function getOptionalGroups(string $userId, string $groupType): array
{
try {
$results = $this->getGrouperUserMemberships($userId, $groupType);
} catch (Exception $e) {
CakeLog::write('error', __METHOD__ . ': An error occurred');
throw $e;
}
return $results['WsGetMembershipsResults']['wsGroups'] ?? [];
}

/**
* Potential use was for creating adhoc group by a user, not associated to WG.
*
* Gets all Stems/Folders where User is admin/owner
*
* @param string $userId
*
* @return array Array of Stems/Folders from Grouper
* @throws GrouperLiteWidgetException
*/
public function getOwnedStems(string $userId): array
{
try {
$results = $this->getGrouperUserMemberships($userId, GrouperGroupTypeEnum::ADMIN);
} catch (Exception $e) {
CakeLog::write('error', __METHOD__ . ': An error occurred');
throw $e;
}
return $results['WsGetMembershipsResults']['wsStems'] ?? [];
}

/**
* Is the user member of the Group
*
Expand Down Expand Up @@ -559,8 +589,8 @@ public function isMemberOfGroup(string $groupName, string $userId): bool
throw $e;
}

return isset($results['WsHasMemberLiteResul']['resultMetadata']['resultCode'])
&& $results['WsHasMemberLiteResul']['resultMetadata']['resultCode'] === GrouperResultCodesEnum::IS_MEMBER;
return isset($results['WsHasMemberLiteResult']['resultMetadata']['resultCode'])
&& $results['WsHasMemberLiteResult']['resultMetadata']['resultCode'] === GrouperResultCodesEnum::IS_MEMBER;
}

/**
Expand Down
1 change: 1 addition & 0 deletions Lib/GrouperHTTPWrapper.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,7 @@ public function sendRequest(string $method, string $endPoint, string $body = '')
$this->_request['body'] = $body;

CakeLog::write('debug', __METHOD__ . '::connection url: ' . $uri);
CakeLog::write('debug', __METHOD__ . '::data: ' . $body);
try {
$apiResults = $this->request($this->_request);
} catch (Exception $e) {
Expand Down
6 changes: 6 additions & 0 deletions Lib/enum.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,16 @@ class GrouperSpecialGroups {
const GROUPER_EMAIL_STEM = 'app:sympa';
}

// https://software.internet2.edu/grouper/doc/master/grouper-ws-parent/grouper-ws/apidocs/edu/internet2/middleware/grouper/ws/rest/WsRestResultProblem.html
// https://software.internet2.edu/grouper/doc/master/grouper-ws-parent/grouper-ws/apidocs/edu/internet2/middleware/grouper/ws/coresoap/WsAddMemberResult.WsAddMemberResultCode.html#
class GrouperResultCodesEnum {
const SUCCESS_ALREADY_EXISTED = 'SUCCESS_ALREADY_EXISTED';
const EXECUTE_FAILED = 'EXECUTE_FAILED';
const GROUP_NOT_FOUND = 'GROUP_NOT_FOUND';
const IS_MEMBER = 'IS_MEMBER';
const IS_NOT_MEMBER = 'IS_NOT_MEMBER';
const INSUFFICIENT_PRIVILEGES = 'INSUFFICIENT_PRIVILEGES';
const INVALID_QUERY = 'INVALID_QUERY';
const NO_SUCH_OBJECT = 'NO_SUCH_OBJECT';
const PROBLEM_WITH_ASSIGNMENT = 'PROBLEM_WITH_ASSIGNMENT';
const PROBLEM_GETTING_MEMBERS = 'PROBLEM_GETTING_MEMBERS';
Expand All @@ -39,6 +43,8 @@ class GrouperResultCodesEnum {
class GrouperCodesToExceptionClassEnum {
const EXECUTE_FAILED = 'BadRequestException';
const GROUP_NOT_FOUND = 'NotFoundException';
const INSUFFICIENT_PRIVILEGES = 'UnauthorizedException';
const INVALID_QUERY = 'BadRequestException';
const NO_SUCH_OBJECT = 'NotFoundException';
const PROBLEM_WITH_ASSIGNMENT = 'BadRequestException';
const SUBJECT_NOT_FOUND = 'NotFoundException';
Expand Down
Loading