IBM Business Process Manager, Version 8.5.5

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

Update the user preferences associated with a user. Non-privileged users are able to update self-manageable attributes of the current user, but no attribute of other users. Users authorized in ACTION_MANAGE_ANY_USERATTRIBUTE can update any attribute of any user.

Sample method invocation

PUT /rest/bpm/wle/v1/user/{userNameOrID}?action={string}&key={string}&value={string}

Alternative Method Invocation

POST /rest/bpm/wle/v1/user/{userNameOrID}?action={string}&key={string}&value={string}

Parameters

Required parameters
NameValue TypeDescription
action string
Action to be performed for the specified task instance.
ValueDescription
setPreference
Sets the user preference specified by the key and value parameters.
key string
A string which indicates the user preference to be set. In addition to the pre-defined user attribute names listed below, other custom user attribute names can also be specified, provided that they have been defined in Process Designer.
ValueDescription
email
Sets the user's 'task email address' user attribute. The 'value' parameter should be a valid email address.
primarygroup
Sets the user's 'primary role' user attribute. The 'value' parameter should be a string representing the group name or id associated with the primary group.
notification
Sets the user's 'task notification' user attribute. The 'value' parameter should be one of 'true' or 'false'.
assignandrun
Sets the user's 'alert on assign and run' user attribute. The 'value' parameter should be one of 'true' or 'false'.
locale
Sets the user's preferred locale. The 'value' parameter should be a valid locale name.
calendartype
Sets the user's 'calendar type' user attribute. The 'value' parameter should be one of the following values:
  • generalPreference.fields.calendarType.gregorian
  • generalPreference.fields.calendarType.hebrew
  • generalPreference.fields.calendarType.islamic
value string
A string representing the value of the user preference to be set. This value will depend on the 'key' parameter as described above.

Request content

None

Response content

User - the updated details associated with the user (User complexType).

The default content type is application/json.

MIME type: application/json


+ View schema
{  "description": "User", 
   "type": "object",
   "properties":
   {  
      "userID": {"type": "integer",
         "description": "The user ID of the user that is described by this object."
      },
      "userName": {"type": "string",
         "description": "The user name of the user that is described by this object.",
      },
      "fullName": {"type": "string",
         "description": "The full name of the user that is described by this object.",
      },
      "isDisabled": {"type": "boolean",
         "description": "States whether this user is disabled. This field is set to false and cannot be changed."
      },
      "primaryGroup": {"type": "string",
         "description": "The primary group associated with this user."
      },
      "emailAddress": {"type": "string",
         "description": "The email address associated with this user."
      },
      "userPreferences":
      [
   	{ "key" : { "type": "string",
   	  	    "description": "The key associated with the user preference."
   		  },
   	  "value" : { "type": "string",
   	  	    "description": "They value associated with the user preference."
   		  }
   	}
      ],
      "memberships": {"type": "[string]",
      	"description": "List of groups in which the user is a member."
      }
   }
}
+ View example content
{
   "status":"200",
   "data":{
      "userID":1,
      "userName":"tw_admin",
      "fullName":"Internal TW Admin user",
      "isDisabled":false,
      "primaryGroup":null,
      "emailAddress":null,
      "userPreferences":{
         "Task Email Address":"user1@my.company.com",
         "Task Notification":null,
         "Locale":"en",
         "Alert On Assign And Run":"false"
      },
      "memberships":[
         "Debug",
         "tw_admins",
         "tw_authors",
         "tw_portal_admins",
         "tw_process_owners",
         "tw_allusers",
         "All Users_T_da7e4d23-78cb-4483-98ed-b9c238308a03.40551a86-bac6-474e-a666-85f9a8a83426",
         "All Users_S_da7e4d23-78cb-4483-98ed-b9c238308a03.40551a86-bac6-474e-a666-85f9a8a83426",
         "All Users_T_da7e4d23-78cb-4483-98ed-b9c238308a03.36c07d6c-ad75-4a42-9675-95275f281c3f",
         "Process Owner_T_9a9f919e-6644-4592-b900-3eaa46838454.2e16e361-17b4-49c6-9092-66c6a4ffd8bf",
      ]
   }
}

MIME type: application/xml


+ View 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 disabled. This field is set to false and cannot be changed. -->
		    <element name="isDisabled" type="boolean" />

		    <!-- The timestamp when the user last logged in, This field cannot be changed. -->
		    <element name="lastLoginDate" type="dateTime" />

		    <!-- 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 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 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>
+ View 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:User'>
    <userID>1</userID>
    <userName>tw_admin</userName>
    <fullName>Internal TW Admin user</fullName>
    <isDisabled>false</isDisabled>
    <userPreferences>
      <item key='Task Email Address'>
        <value xmlns:ns5='http://www.w3.org/2001/XMLSchema' xsi:type='ns5:string'>user1@my.company.com</value>
      </item>
      <item key='Task Notification' />
      <item key='Locale'>
        <value xmlns:ns5='http://www.w3.org/2001/XMLSchema' xsi:type='ns5:string'>en</value>
      </item>
      <item key='Alert On Assign And Run'>
        <value xmlns:ns5='http://www.w3.org/2001/XMLSchema' xsi:type='ns5:string'>false</value>
      </item>
    </userPreferences>
    <memberships>Debug</memberships>
    <memberships>tw_admins</memberships>
    <memberships>tw_authors</memberships>
    <memberships>tw_portal_admins</memberships>
    <memberships>tw_process_owners</memberships>
    <memberships>tw_allusers</memberships>
    <memberships>All Users_T_da7e4d23-78cb-4483-98ed-b9c238308a03.40551a86-bac6-474e-a666-85f9a8a83426</memberships>
    <memberships>All Users_S_da7e4d23-78cb-4483-98ed-b9c238308a03.40551a86-bac6-474e-a666-85f9a8a83426</memberships>
    <memberships>All Users_T_da7e4d23-78cb-4483-98ed-b9c238308a03.36c07d6c-ad75-4a42-9675-95275f281c3f</memberships>
    <memberships>Process Owner_T_9a9f919e-6644-4592-b900-3eaa46838454.2e16e361-17b4-49c6-9092-66c6a4ffd8bf</memberships>
  </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


+ View 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


+ View 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>
	</sequence>
    </complexType>
</schema>

MIME type: application/x-javascript

Status codes

The method returns one of the following status codes:
CodeDescription
200 OKSuccess completion.
400 Bad RequestThe parameters are not valid or they are missing.
401 UnauthorizedThe caller is not authorized for this request.
406 Not AcceptableThe requested content type or content encoding is not supported.
500 Internal Server ErrorA severe problem has occurred, programmer's details are provided.

Available since

7.5.0

Parent Topic: User Resource



Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)