REST interface for BPD-related resources - Group Resource - PUT Method

Update the membership for a group that has been defined to the IBM Business Automation Workflow installation.

Sample method invocation

PUT /rest/bpm/wle/v1/group/{groupNameOrID}?action={string}&user={string}&group={string}[&parts={string}]

Usage Notes

With IBM BPM V8.5.7 cumulative fix 2016.09 installed, only valid group membership updates are allowed. The following list describes acceptable and unacceptable updates by group type. Parent group refers to the group that is updated. subgroup refers to a nested group that is either added to, or removed from, the parent group.

Parent group type: security group
- Add users: not allowed
- Remove users: not allowed
- Add subgroups: not allowed
- Remove subgroups: allowed
Parent group type: participant group
- Add users: allowed
- Remove users: allowed
- Add subgroups: allowed only for security and internal groups
- Remove subgroups: allowed
Parent group type: ad hoc group
- Add users: not allowed
- Remove users: not allowed
- Add subgroups: not allowed
- Remove subgroups: not allowed
Parent group type: internal group
- Add users: allowed
- Remove users: allowed
- Add subgroups: allowed only for security and internal groups
- Remove subgroups: allowed
Parent group type: dynamic group
- Add users: not allowed
- Remove users: not allowed
- Add subgroups: not allowed
- Remove subgroups: not allowed

Parameters

Required parameters

Name Value Type Description

action

string

The action to be performed for the specified group.

Value	Description
addMember	Adds a `user` or `group` to the membership of the specified group.
removeMember	Removes a `user` or `group` from the membership of the specified group.

user

string

The user identifier or user name to be added to the membership of the specified group. The user or group parameter is required.

group

string

The group identifier or group name to be added to the membership of the specified group. The user or group parameter is required.

Optional parameters

Name	Value Type	Description
parts	string	The parts of the response data to be returned. You can use the following values: `members`, `all` (the default), or `none`.

Request content

None

Response content

Group - the updated details associated with a group that has been defined to the IBM Business Automation Workflow installation (Group complexType).

The default content type is application/json.

MIME type: application/json

Schema

{  "description": "Group", 
   "type": "object",
   "properties":
   {  
      "groupID": {"type": "integer",
         "description": "The group ID of the group that is described by this object."
      },
      "groupName": {"type": "string",
         "description": "The group name of the group that is described by this object."
      },
      "displaylName": {"type": "string",
         "description": "The display name of the group that is described by this object."
      },
      "description": {"type": "string",
         "description": "The description of the group associated with this object."
      },
      "members": {"type": "[string]",
      	"description": "List of users which are members of the group associated with this object."
      },
      "managerGroupName": {"type": "string",
         "description": "The group name of the manager group that is associated with this object."
      }
   }
}

Example content

{
   "status":"200",
   "data":{
      "groupID":3,
      "groupName":"tw_admins",
      "displayName":"tw_admins",
      "description":"Group for people with full access to Teamworks.",
      "members":[
         "tw_admin"
      ],
      "managerGroupName": "mTeam_T_8d643861-ec74-4877-a18b-0728ad57033e.e0b4a6b9-12eb-4565-8857-831847d11ad9"
   }
}

MIME type: application/xml

Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://rest.bpm.ibm.com/v1/data/usergroup"
	elementFormDefault="unqualified" xmlns="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://rest.bpm.ibm.com/v1/data/usergroup"
	xmlns:data="http://rest.bpm.ibm.com/v1/data/root" 
	xmlns:cmn="http://rest.bpm.ibm.com/v1/data/common">

    <import schemaLocation="BPMRestData.xsd" namespace="http://rest.bpm.ibm.com/v1/data/root" />
    <import schemaLocation="Common.xsd" namespace="http://rest.bpm.ibm.com/v1/data/common" />

    <!-- 
	 This type represents a user that has been defined to the IBM BPM installation.
    -->
    <complexType name="User">
	<complexContent>
	    <extension base="data:Data">
		<sequence>

		    <!-- The numeric ID of the user -->
		    <element name="userID" type="long" />

		    <!-- The alphanumeric user name associated with the user -->
		    <element name="userName" type="string" />

		    <!-- The user's full name -->
		    <element name="fullName" type="string" minOccurs="0" />

		    <!-- This field indicates whether or not this user is deactivated. -->
		    <element name="isDisabled" type="boolean" />

		    <!-- not used -->
		    <element name="primaryGroup" type="string" minOccurs="0" />

		    <!-- not used -->
		    <element name="emailAddress" type="string" minOccurs="0" />

		    <!-- A list of user preferences (extended attributes) associated with this user -->
		    <element name="userPreferences" type="cmn:Map" minOccurs="0" />

		    <!-- A list of user preferences the user is allowed to manage -->
		    <element name="editableUserPreferences" type="string" minOccurs="0" maxOccurs="unbounded" />

		    <!-- A list of Tasks (taskIds) that the user is collaborating on -->
		    <element name="tasksCollaboration" type="string" minOccurs="0" maxOccurs="unbounded" />

		    <!-- A list of groups to which this user belongs -->
		    <element name="memberships" type="string" maxOccurs="unbounded" minOccurs="0" />
		</sequence>
	    </extension>
	</complexContent>
    </complexType>

    <!-- 
	 This type represents a user with a workload defined to the IBM BPM installation.
    -->
    <complexType name="TeamMember">
	<complexContent>
	    <extension base="tns:User">
		<sequence>

		    <!-- The numeric ID of the user -->
		    <element name="workload" type="integer" />

		</sequence>
	    </extension>
	</complexContent>
    </complexType>
    
    <!-- 
	 This type represents a user with a workload defined to the IBM BPM installation.
    -->
    <complexType name="Expert">
	<complexContent>
	    <extension base="tns:TeamMember">
		<sequence>

		    <!-- TODO what is this -->
		    <element name="completed" type="integer" />
		    
		    <!-- TODO what is this -->
		    <element name="avgHours" type="double" />		    

		</sequence>
	    </extension>
	</complexContent>
    </complexType>
    
    <!-- 
     This type represents an array of Experts
    -->
    <complexType name="Experts">
	<complexContent>
	    <extension base="data:Data">
	    	<sequence>
	    		<!-- MAY CONTAIN  -->
		    	<element name="Experts" type="tns:Expert"  minOccurs="0" maxOccurs="unbounded"/>
		    </sequence>
	    </extension>
	</complexContent>
    </complexType>	
    
   <!-- 
	 This type represents a list of expert users with a workload defined to the IBM BPM installation.
    -->
    <complexType name="ExpertList">
	<complexContent>
	    <extension base="data:Data">
		<sequence>

		    <!--group of users the system identifies as experts on a task  -->
		    <element name="systemIdentifiedUsers" type="tns:Expert" maxOccurs="unbounded" minOccurs="0" />
		    
		    <!--group of users included in the the task expert participant group  -->
		    <element name="expertParticipantGroupUsers" type="tns:Expert" maxOccurs="unbounded" minOccurs="0" />	

		    <!--task expert participant group  -->
		    <element name="expertParticipantGroupDetails" type="tns:Group" />

		</sequence>
	    </extension>
	</complexContent>
    </complexType>    
    
    <!-- 
	 This type represents a user that has been defined to the IBM BPM installation.
    -->
    <complexType name="UserPreferences">
	<complexContent>
	    <extension base="data:Data">
		<sequence>

		    <!-- The user's display name -->
		    <element name="displayName" type="string" />

		    <!-- The user's "Primary Role Description -->
		    <element name="primaryRoleDescription" type="string" />

		    <!-- The user's Task Email Address -->
		    <element name="taskEmailAddress" type="string" />

		    <!-- The user's Phone Number -->
		    <element name="phoneNumber" type="string" />
		    
		    <!-- The user's Street Address -->
		    <element name="streetAddress" type="string" />
		    
		    <!-- The user's City -->
		    <element name="city" type="string" />
		    
		    <!-- The user's State -->
		    <element name="state" type="string" />
		    
  		    <!-- The user's Country -->
		    <element name="country" type="string" />
		    
		    <!-- The user's Postal Code-->
		    <element name="postalCode" type="string" />
		    
		    <!-- The user's Image -->
		    <element name="image" type="string" />

		    <!-- The user's Toolbar Collapsed setting -->
		    <element name="toolbarCollapsed" type="boolean" />			    		    		    
		</sequence>
	    </extension>
	</complexContent>
    </complexType>    

    <!--
	This type represents a group that has been defined to the IBM BPM installation.
    -->
    <complexType name="Group">
	<complexContent>
	    <extension base="data:Data">
		<sequence>

		    <!-- The numeric ID of the group -->
		    <element name="groupID" type="long" />

		    <!-- The alphanumeric name of the group -->
		    <element name="groupName" type="string" />

		    <!-- The display name associated with the group -->
		    <element name="displayName" type="string" />

		    <!-- The description associated with the group -->
		    <element name="description" type="string" />

		    <!-- The information if this group is logically deleted -->
		    <element name="deleted" type="boolean" />

		    <!-- The list of users that are members of this group -->
		    <element name="members" type="string" maxOccurs="unbounded" minOccurs="0" />
		    
		    <!-- The alphanumeric name of the manager group -->
		    <element name="managerGroupName" type="string" minOccurs="0" />		    
		</sequence>
	    </extension>
	</complexContent>
    </complexType>    
    
    <!-- 
	 This type represents a list of zero or more users that have been defined to the IBM BPM installation.
    -->
    <complexType name="UserList">
	<complexContent>
	    <extension base="data:Data">
		<sequence>
		    <element name="users" type="tns:User" maxOccurs="unbounded" minOccurs="0" />
		</sequence>
	    </extension>
	</complexContent>
    </complexType>

    <!-- 
	 This type represents a list of zero or more user groups that have been defined to the IBM BPM installation.
    -->
    <complexType name="GroupList">
	<complexContent>
	    <extension base="data:Data">
		<sequence>
		    <element name="groups" type="tns:Group" maxOccurs="unbounded" minOccurs="0" />
		</sequence>
	    </extension>
	</complexContent>
    </complexType>
    
   	<element name="User" type="tns:User" /> 
  	<element name="TeamMember" type="tns:TeamMember" />
   	<element name="Expert" type="tns:Expert" />    	    
   	<element name="Experts" type="tns:Experts" />    	    
   	<element name="UserPreferences" type="tns:UserPreferences" />
   	<element name="Group" type="tns:Group" />    	
   	<element name="UserList" type="tns:UserList" />    	
   	<element name="GroupList" type="tns:GroupList" />    	

</schema>

Example content

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bpm:ResponseData xmlns:bpm='http://rest.bpm.ibm.com/v1/data'>
  <status>200</status>
  <data xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ug='http://rest.bpm.ibm.com/v1/data/usergroup' xsi:type='ug:Group'>
    <groupID>3</groupID>
    <groupName>tw_admins</groupName>
    <displayName>tw_admins</displayName>
    <description>Group for people with full access to Teamworks.</description>
    <members>tw_admin</members>
    <managerGroupName>mTeam_T_8d643861-ec74-4877-a18b-0728ad57033e.e0b4a6b9-12eb-4565-8857-831847d11ad9</managerGroupName>
  </data>
</bpm:ResponseData>

MIME type: application/x-javascript

Error Response content

Detailed error information

The default content type is application/json.

MIME type: application/json

Schema

{  "description": "WLE Error Response", 
   "type": "object",
   "properties":
   {  "status": {"type": "string",
         "description": "The status of the previous API call."
      },
      "exceptionType": {"type": "string",
         "description": "The classname associated with the exception."
      },
      "errorNumber": {"type": "string",
         "description": "Message ID of the exception."
      },
      "errorMessage": {"type": "string",
         "description": "Message text of the exception."
      },
      "errorMessageParameters": {"type": ["string"], "optional": true,
         "description":"Message text parameters of the exception."
      },
      "programmersDetails": {"type": "object", "optional": true,
         "description":"Additional exception details, for example, a stack trace."
      }
   }
}

MIME type: application/xml

Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://rest.bpm.ibm.com/v1/data/exception"
	elementFormDefault="unqualified" xmlns="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://rest.bpm.ibm.com/v1/data/exception"
	xmlns:dat="http://rest.bpm.ibm.com/v1/data/root">

    <import schemaLocation="BPMRestData.xsd" namespace="http://rest.bpm.ibm.com/v1/data/root" />
    
    <!--
	This type represents an error response.
    -->    
    <element name="RestRuntimeException">
	<complexType>
	    <sequence>
		<element name="status" type="string"/>
		<element name="Data" type="tns:ExceptionData">
    		</element>
	    </sequence>
	</complexType>
    </element>

    <!-- 
	 This type contains detailed error information associated with an exception.
    -->
    <complexType name="ExceptionData">
	<sequence>
	    <element name="status" type="string"/>

	    <!-- This specifies the java class name of the exception -->
	    <element name="exceptionType" type="string"/>

	    <!-- The message ID of the error message -->
	    <element name="errorNumber" type="string" minOccurs="0"/>

	    <!-- The complete error message -->
	    <element name="errorMessage" type="string"/>

	    <!-- The list of strings inserted into the error message -->
	    <element name="errorMessageParameters" type="string" minOccurs="0" maxOccurs="unbounded"/>

	    <!-- 
		 The stacktrace associated with the exception.
		 Note that this will be omitted unless the "server-stacktrace-enabled" property
		 is enabled in the server's 100Custom.xml file.
	    -->     
	    <element name="programmersDetails" type="string"></element>
	    
	    <!-- Prior responses.  Set if a bulk command was used -->
	    <element name="responses" type="dat:BulkCommandResponses" minOccurs="0"></element>

            <element name="errorData" type="tns:ErrorData" minOccurs="0" />
	</sequence>
    </complexType>

    <complexType name="ErrorData">
        <sequence>
            <element name="code" type="string" />
            <element name="data" type="string" minOccurs="0" />
        </sequence>
    </complexType>
    
</schema>

MIME type: application/x-javascript

Status codes

The method returns one of the following status codes:

Code	Description
200 OK	Success completion.
400 Bad Request	The parameters are not valid or they are missing.
401 Unauthorized	The caller is not authorized for this request.
406 Not Acceptable	The requested content type or content encoding is not supported.
500 Internal Server Error	A severe problem has occurred, programmer's details are provided.

Available since

8.5.0.1

Parent Topic: Group Resource