GuidesiMIS ProfessionaliMIS EnterpriseClient Support

Working with committees

Suggest Edits

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 over 2 years ago