CalGroups API Information

A knowledge base article about CalGroups API Information provided by the UC Berkeley IT Service Hub - Knowledge Portal

Web Services Account

Contact calnet-admin@berkeley.edu to request a web services account.

General Information

server domain name = https://group-test.berkeley.edu, https://calgroups.berkeley.edu
uri  = /grouper/servicesRest/json/v2_2_100/(groups|stems)/(group|stem name)
headers: Content-Type=text/x-json
Basic HTTP Authentication - Make sure that the api account has admin access to your groups and folders. Just add it as you would add person accounts to the admin group associated with a folder.
Grouper WS documentation = https://spaces.internet2.edu/display/Grouper/Grouper+Web+Services

Methods

Add Member (add member UID to group)

PUT  https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...

Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Add group as a member (add another group UUID as member to group)

PUT  https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...(link is external)
Reference: https://github.com/Internet2/grouper/blob/02221283c18c44d2d87776f9a91a60...(link is external)

Add multiple members to a group

Use person UID or group UUID as subjectId. Can replace membership with this list by setting replaceAllExisting to T.

URN:

PUT https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...

Body:

{
     "WsRestAddMemberRequest":{
          "replaceAllExisting":"F",
          "subjectLookups":[
             {"subjectId":"212374"},
             {"subjectId":"c466a9d915044c72a67e8999f2d3ce4b"},
             {"subjectId":"212375"}
         ] 
     }
}
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Delete Member (delete member UID from group)

Can also delete a nested group using UUID.

DELETE https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...
DELETE https://group-test.berkeley.edu/grouper/servicesRest/json/v2_2_100/group...
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Get Members (get list of all group members)

GET  https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...

Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Get Groups (get list of all groups where UID=1234 is a member)

GET  https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/subjec...
Reference:  https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Group Save (create a group) (can add description parameter as well)

POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...? \
wsLiteObjectType=WsRestGroupSaveLiteRequest&groupName=edu:berkeley:app:edu:berkeley:app:someapp:testgroup
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Group Delete (delete a group) 

DELETE https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Stem Save (create a new stem or folder)

POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/stems/...? \
wsLiteObjectType=WsRestStemSaveLiteRequest&stemName=edu:berkeley:app:edu:berkeley:app:someapp:teststem
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Has Member (Is member UID in group)

GET  https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups...
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Find Groups

finds all groups under specified stem

POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups? \
wsLiteObjectType=WsRestFindGroupsLiteRequest&queryFilterType=FIND_BY_STEM_NAME \
&stemName=edu:berkeley:app:someapp

find groups by name

POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups? \
wsLiteObjectType=WsRestFindGroupsLiteRequest&queryFilterType=FIND_BY_GROUP_NAME_APPROXIMATE \
&stemName=edu:berkeley:app:someapp&groupName=test
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Create a Composite Group

This method allows saving multiple groups at once, so the left/right groups can also be created before the composite group. See reference below.

URN:
https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups

BODY:
{
   "WsRestGroupSaveRequest":{
      "wsGroupToSaves":[
         {
           "wsGroup":{
               "description":"my composite group description",
               "detail":{
                    "compositeType":"intersection",
                    "hasComposite":"T",
                    "leftGroup":{
                           "name":"edu:berkeley:official:employees:all-emp"
                    },
                    "rightGroup":{
                           "name":"edu:berkeley:app:someapp:my-adhoc-group"
                    }
               },
               "name":"edu:berkeley:app:someapp:my-composite-group"
           },
           "wsGroupLookup":{
                    "groupName":"edu:berkeley:app:someapp:my-composite-group"
           }
         }
      ]
   }
}
Reference: https://github.com/Internet2/grouper/blob/master/grouper-ws/grouper-ws/d...

Add Provisioning Attributes to a Group

Use this to add provisioning attributes to a group. In this case, the sync to google attributes including metadata. Your app credentials need to have access to the attribute and group. To remove the provisioning attributes, see the next function.

The example below uses the value for syncing to Google (bConnected). 

The values for LDAP and AD are:

LDAPBerkeleyIMO

AD

URN:

POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/attributeAssignments

Body:

{

  "WsRestAssignAttributesBatchRequest": {

    "wsAssignAttributeBatchEntries": [

      {

        "wsOwnerGroupLookup": {

          "groupName": "edu:berkeley:org:testorg:testgroupname"

        },

        "attributeAssignType": "group",

        "attributeAssignOperation": "add_attr",

        "wsAttributeDefNameLookup": {

          "name": "etc:provisioning:provisioningMarker"

        }

      },

      {

        "wsOwnerAttributeAssignLookup": {

          "batchIndex": "0"

        },

        "attributeAssignType": "group_asgn",

        "attributeAssignOperation": "assign_attr",

        "attributeAssignValueOperation": "assign_value",

        "values":[

          {

            "valueSystem": "true"

          }

        ],

        "wsAttributeDefNameLookup": {

          "name": "etc:provisioning:provisioningDirectAssign"

        }

      },

      {

        "wsOwnerAttributeAssignLookup": {

          "batchIndex": "0"

        },

        "attributeAssignType": "group_asgn",

        "attributeAssignOperation": "assign_attr",

        "attributeAssignValueOperation": "assign_value",

        "values":[

          {

            "valueSystem": "bConnected"

          }

        ],

        "wsAttributeDefNameLookup": {

          "name": "etc:provisioning:provisioningDoProvision"

        }

      },

      {

        "wsOwnerAttributeAssignLookup": {

          "batchIndex": "0"

        },

        "attributeAssignType": "group_asgn",

        "attributeAssignOperation": "assign_attr",

        "attributeAssignValueOperation": "assign_value",

        "values":[

          {

            "valueSystem": "bConnected"

          }

        ],

        "wsAttributeDefNameLookup": {

          "name": "etc:provisioning:provisioningTarget"

        }

      },

      {

        "wsOwnerAttributeAssignLookup": {

          "batchIndex": "0"

        },

        "attributeAssignType": "group_asgn",

        "attributeAssignOperation": "assign_attr",

        "attributeAssignValueOperation": "assign_value",

        "values":[

          {

            "valueSystem": "bConnected"

          }

        ],

        "wsAttributeDefNameLookup": {

          "name": "etc:provisioning:provisioningDoProvision"

        }

      }

    ]

  }

}
Reference: https://spaces.at.internet2.edu/display/Grouper/Assign+Attributes+Batch

Remove Provisioning Attributes for a Group

Use this to remove provisioning attributes to a group. All provisioning attributes will be removed. To add provisioning attributes, see the previous function.

URN:
POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/attributeAssignments

Body:
{
"WsRestAssignAttributesLiteRequest":{
"wsAttributeDefNameName":"etc:provisioning:provisioningMarker",
"attributeAssignType":"group",
"wsOwnerGroupName":"edu:berkeley:org:calnet:test-ldap-provisioning",
"attributeAssignOperation":"remove_attr"
}
}

Reference: https://spaces.at.internet2.edu/display/Grouper/Assign+Attributes

Look at the Lite Samples.

Support 

Request access via a folder space using a Service Request form in ServiceNow.

If you have questions about CalGroups, including API questions, contact: calnet-admin@berkeley.edu.