Working with committees
This tutorial goes into detail on how to find, modify, delete and add committee members.
Finding committees
To find a committee, search either the GroupSummary or Group endpoint using a GroupClassId of Committee. The Group endpoint will retrieve everything that the GroupSummary endpoint will as well as all of the roles allowed within the group.
https://{{URL}}/api/GroupSummary?GroupClassId=COMMITTEE
If you'd rather just use the light weight GroupSummary, you can also retrieve all available committee roles is through the GroupClass endpoint.
https://{{URL}}/api/GroupClass/COMMITTEE
Finding committee members
After you find the committee, you can search for members via either the GroupMemberSummary or GroupMember endpoint. The GroupMemberSummary endpoint is light weight and read-only. If you only want to see who the members are and not their roles, GroupMemberSummary is probably sufficient. If however, you want to edit the committee member, the GroupMember enpoint is probably better. This is an example of finding Awards committee members.
https://{{URL}}/api/GroupMember?GroupId=COMMITTEE/AWARDS
Or if you want to find a particular committee member, you can search using both the GroupId and the PartyId
https://{{URL}}/api/GroupMember?GroupId=COMMITTEE/AWARDS&PartyId=18043
Note about GroupMemberId
Notice that the GroupMemberId for committees is a composite key in the pattern of {GroupId}:{PartyId}. This colon is considered an unsafe character to be in a URL path. So for committees, you cannot perform a GET by ID. Instead, you can include the GroupMemberId as a search parameter if needed.
Do not try to query a committee member with the composite key like the following example
https://{{URL}}/api/GroupMember?GroupMemberId=COMMITTEE/AWARDS:18043
It will return a result like this
{
"MembershipDetails": {
"$values": [
{
"GroupMemberDetailId": "COMMITTEE/AWARDS:18043:31266",
"Stage": {
"GroupStageId": "COMMITTEE"
},
"EffectiveDate": "2020-12-30T00:00:00",
"ExpirationDate": "2021-12-31T00:00:00",
"IsActive": true,
"Role": {
"RoleId": "COMMITTEE:M",
"Name": "Member"
}
}
]
},
"GroupMemberId": "COMMITTEE/AWARDS:18043",
"Group": {
"GroupId": "COMMITTEE/AWARDS",
"Name": "Awards Committee",
"Description": "This committee organizes and reviews the nominations for specific awards and selects a recommended winner for each award. \r",
"ParentIdentity": {
"EntityTypeName": "Public",
"IdentityElements": {
"$values": [
"Public Groups"
]
}
},
"GroupClass": {
"GroupClassId": "COMMITTEE",
"Name": "Committee",
"Description": ""
},
"StatusCode": "A"
},
"Party": {
"CityName": "Chicago",
"CountryName": "United States",
"CountrySubEntityName": "IL",
"Email": "[email protected]",
"Phone": "(312) 555-4450",
"PartyId": "18043",
"Id": "18043",
"UniformId": "2810b506-bbcc-4197-84db-501b4eddffa4",
"Status": {
"PartyStatusId": "A",
"Name": "Active",
"Description": "Active"
},
"Name": "Dr. Chris L. Baker, PhD",
"Sort": "BAKER, CHRIS",
"IsMarkedForDelete": false
},
"IsActive": true
}
Updating a committee member
In order to update a committee member's roles or term dates, you can make modifications to the MembershipDetails which is a collection of GroupMemberDetailDatas.
Adding a role
This is an example of adding the committee administrator role to ID 18043 in the Awards committee. Get the GroupMember that was returned up above, and add a new item to the MembershipDetails that looks like this:
{
"Stage": {
"GroupStageId": "COMMITTEE"
},
"EffectiveDate": "2020-12-30T00:00:00",
"ExpirationDate": "2021-12-31T00:00:00",
"Role": {
"RoleId": "COMMITTEE:_ADMIN",
"Name": "Committee Administrator"
}
}
The only required field when adding a new membership detail is the RoleId. Other optional fields are Stage, EffectiveDate and ExpirationDate.
Note about GroupMemberId
Because of the composite key containing a colon, you cannot use the PUT operation to update a committee member as you would when updating most entity types. Instead, just POST to the GroupMember endpoint and as long as the GroupMemberId is populated, iMIS will know to do an update rather than an add.
Changing a stage
Committees are different from other group types because they also have stages: Committee, Applicant and Proposed. These available stages can be seen in Group.AvailableStages property. To move a member between these stages, update the MemershipDetail.Stage.GroupStageId to COMMITTEE, APPLICANT or PROPOSED.
Deleting a committee member
Just like with PUT, we are not able to use the DELETE method for committee group members. Instead, to delete a member, simply remove all MembershipDetails and then post the GroupMember to the GroupMember endpoint. Make sure MembershipDetails has an empty values array like this:
{
"MembershipDetails": {
"$values": [
]
},
"GroupMemberId": "COMMITTEE/AWARDS:18043",
"Group": {
"GroupId": "COMMITTEE/AWARDS",
"Name": "Awards Committee",
"Description": "This committee organizes and reviews the nominations for specific awards and selects a recommended winner for each award. \r",
"ParentIdentity": {
"EntityTypeName": "Public",
"IdentityElements": {
"$values": [
"Public Groups"
]
}
},
"GroupClass": {
"GroupClassId": "COMMITTEE",
"Name": "Committee",
"Description": ""
},
"StatusCode": "A"
},
"Party": {
"CityName": "Chicago",
"CountryName": "United States",
"CountrySubEntityName": "IL",
"Email": "[email protected]",
"Phone": "(312) 555-4450",
"PartyId": "18043",
"Id": "18043",
"UniformId": "2810b506-bbcc-4197-84db-501b4eddffa4",
"Status": {
"PartyStatusId": "A",
"Name": "Active",
"Description": "Active"
},
"Name": "Dr. Chris L. Baker, PhD",
"Sort": "BAKER, CHRIS",
"IsMarkedForDelete": false
},
"IsActive": true
}
Adding a committee members
To add a committee member, the minimum required fields are MembershipDetails (at lest one), Group.GroupId, and Party.PartyId. Posting the following JSON will add ID 101 as a member to the Awards committee for the full 2021 term.
{
"MembershipDetails": {
"$values": [
{
"Stage": {
"GroupStageId": "COMMITTEE"
},
"EffectiveDate": "2021-01-01T00:00:00",
"ExpirationDate": "2021-12-31T00:00:00",
"Role": {
"RoleId": "COMMITTEE:M",
"Name": "Member"
}
}
]
},
"Group": {
"GroupId": "COMMITTEE/AWARDS",
},
"Party": {
"PartyId": "101"
},
"IsActive": true
}
Updated almost 3 years ago