Chapter 4. Advanced Content Engine API programming
5.6 Process work items
5.6.3 Set step element parameter values
To process work from a process application, step elements have to be locked in order to set parameter values, and either save or complete the work.
Besides the common field types that comprise a workflow process, two workflow parameters require additional handling in order to set their values
programmatically: workflow attachments and participants. In this section, we show how to get and set values for the common workflow field types, and for workflow attachments and participants:
Workflow attachments
This parameter specifies the workflow attachments that a participant can use to complete a step in the workflow. These attachments can be objects such as documents, document arrays, folders, stored searches, URLs, or files that are located on a shared file system.
Workflow participants
This parameter specifies the participants who can process work in the workflow. Participants can be a user, users, a group, or groups. When
Table 5-10 Workflow attachment types
For a detailed description of the primary field flags required to properly handle step element and work item fields, see the list in Table 5-9 on page 144.
The following steps are required to update step element parameter values using the PE Java and Web services APIs:
1. Lock the step element.
2. Check whether the parameter is read only.
3. Switch through each data type for editable parameters.
4. For each data type, check whether the parameter is single or an array. 5. Set the value for the parameter.
6. Set the value for the system-defined response parameter.
Attachment type Integer value
Description
ATTACHMENT_TYPE_CUSTOM_OBJECT 6 Indicates the attachment type is a custom object ATTACHMENT_TYPE_DOCUMENT 3 Indicates the attachment is
the document type
ATTACHMENT_TYPE_FOLDER 2 Indicates the attachment is the folder type
ATTACHMENT_TYPE_LIBRARY 1 Indicates the attachment type is library or Object Store
ATTACHMENT_TYPE_STORED_SEARCH 4 Indicates the attachment is the stored search type ATTACHMENT_TYPE_UNDEFINED 0 Indicates the attachment
type is not known ATTACHMENT_TYPE_URL 5 Indicates the attachment
type is a UNC or URL
Note: The VWParticipant object represents the name of a user or user group in any of the following ways:
Short (logon) name Distinguished name (DN) Display name (configurable)
For further details about included steps to update step element parameter values by using the PE REST API, see the “Set step element parameter values: REST API scenario” on page 154.
Example 5-19 and Example 5-20 on page 152 show how to perform the steps required to set step elements parameter values, using both the Java API and a PEWS client.
Example 5-19 Set step element parameters and responses by using the Java API
// Create session object and log onto Process Engine ...
// Retrieve Step Element ...
// Retrieve Step Element Parameters ...
// Lock the Step Element stepElement.doLock(true);
// Process Step Element Parameters
for (int i = 0; i < parameters.length; i++ ) { // Check parameter mode
boolean readOnly =
(parameters[i].getMode() == VWModeType.MODE_TYPE_IN);
// If the parameter is editable, switch through each data type if (!readOnly) {
// For each data type,
// check whether the parameter is single or an array // and set the parameter value(s)
switch (parameters[i].getFieldType()) { case VWFieldType.FIELD_TYPE_STRING:
if (parameters[i].isArray()) { String[] arrParamValues =
new String[] {"value_1", "value_2", "value_3"}; stepElement.setParameterValue
case VWFieldType.FIELD_TYPE_ATTACHMENT: if (!parameters[i].isArray()) {
// Get the value for the VWAttachment VWAttachment attachment =
(VWAttachment) parameters[i].getValue(); // Set the attachment name
attachment.setAttachmentName("Document Title"); // Set the attachment description
attachment.setAttachmentDescription ("A document added programmatically"); // Set the type of object (Document) attachment.setType
(VWAttachmentType.ATTACHMENT_TYPE_DOCUMENT); // Set the library type and name (CE Object Store) attachment.setLibraryType
(VWLibraryType.LIBRARY_TYPE_CONTENT_ENGINE); attachment.setLibraryName("ObjectStoreName"); // Set the document ID and version
attachment.setId
("{BBE5AD7F-2449-4DC3-AA38-012A65EC4286}"); attachment.setVersion
("{BBE5AD7F-2449-4DC3-AA38-012A65EC4286}"); // Set the parameter value
stepElement.setParameterValue
(parameters[i].getName(),attachment,true); }
break;
case VWFieldType.FIELD_TYPE_PARTICIPANT: // Instantiate a new VWParticipant array
VWParticipant[] participant = new VWParticipant[1]; // Set the participant name using username value String participantUserName = "Administrator";
participant[0].setParticipantName(participantUserName); // Set the parameter value
stepElement.setParameterValue
(parameters[i].getName(),participant,true); break;
default:
// Do not take action for other data types break;
} }
}
// Set the value for the system-defined Response parameter if (stepElement.getStepResponses() != null) {
String responseValue = "Ok";
stepElement.setSelectedResponse(responseValue); }
Example 5-20 Set step element parameters and responses by using PEWS
// Create the PEWS RequestSoapContext header ...
// Retrieve and Lock Step Element // request.bLock = true;
// request.bOverrideLock = true; ...
// Retrieve Step Element Parameters // Process Step Element Parameters
foreach(peWS.Parameter param in parameters) {
// If the parameter is editable, switch through each data type bool readOnly = param.Mode == peWS.ModeTypeEnum.MODE_TYPE_IN; if (!readOnly)
{
switch(param.Type) {
case peWS.FieldTypeEnum.FIELD_TYPE_STRING: // Set the parameter value
string paramValue = "value_1";
peWS.Value stepvalue = new peWS.Value(); peWS.Value[] values = {paramValue}; param.Values = values;
param.Modified = true; break;
"A document added programmatically";
// Set the library type and name (CE Object Store) peAttachment.LibraryType =
peWS.LibraryTypeEnum.LIBRARY_TYPE_CONTENT_ENGINE; peAttachment.Library = "ObjectStoreName";
// Set the type of object (Document) peAttachment.Type =
peWS.AttachmentTypeEnum.ATTACHMENT_TYPE_DOCUMENT; // Set the document ID and version
peAttachment.Id = "{BBE5AD7F-2449-4DC3-AA38-012A65EC4286}"; peAttachment.Version =
"{BBE5AD7F-2449-4DC3-AA38-012A65EC4286}"; // Set the parameter value
peWS.Value stepvalue = new peWS.Value(); peWS.Value[] values = {peAttachment}; param.Values = values;
param.Modified = true; break;
case peWS.FieldTypeEnum.FIELD_TYPE_PARTICIPANT: // Set the participant name using username value string participantUserName = "Administrator"; // Set the parameter value
peWS.Value stepvalue = new peWS.Value(); peWS.Value[] values = {participantUserName}; param.Values = values;
param.Modified = true; break;
default:
// Do not take action for other data types break;
} } }
// Set the value for the system-defined Response parameter peWS.ArrayOfResponse stepResponses = stepElement.Responses; if (stepResponses!=null)
{
string responseValue = "Ok";
stepResponses.Selected = responseValue; }
Set step element parameter values: REST API scenario
The following steps are required to update step element parameter values using the PE REST API:
1. Send HTTP GET using the stepelements resource to retrieve the step element and eTag parameter.
2. Send HTTP PUT using the stepelements resource to lock the step element. 3. Set step element parameter values and response.
Example 5-21 shows how to set step element parameters and responses with a Dojo toolkit client.
Example 5-21 Set step element parameters and responses with a Dojo toolkit client
// Ensure to be authenticated with the Application Server container // Set request URI
var baseURL = "http://localhost:9080/WorkplaceXT/P8BPMREST/p8/bpm/v1/"; // Set REST API resource and work item number
var queueName = "Inbox";
var wobNumber = "5BDD567B70453C48A5388AC56ABC69E4"; var url = baseURL + "queues/" +
queueName + "/stepelements/" + wobNumber; var eTag;
var stepElement;
// Use the HTTP GET method to retrieve the step element and eTag dojo.xhrGet({
url: url,
handleAs: "json-comment-optional", // The callback to handle the response load: function(data, ioArgs) {
// Get the step element stepElement = data; // Get the eTag
eTag = ioArgs.xhr.getResponseHeader("ETag"); },
var urlForLock = url + "?action=lock&responseContent=1"; dojo.rawXhrPut({
url: urlForLock, handleAs: "text",
// Set the value of "If-Match" to the value of eTag // that you got in the 1st step
headers: {"Content-Type":"application/json","If-Match":eTag}, _raw: true,
// The callback to handle the response load: function(data, ioArgs) {
console.log(dojo.toJson(data)); console.log("Lock successfully"); },
// The error callback error: function(data) { console.dir(data); }, sync: true } );
// Set the step element parameter values
for (var dataFieldName in stepElement.dataFields) {
var dataField = stepElement.dataFields[dataFieldName]; if (dataField.type === 2) {
dataField.value = "Value_1"; dataField.modified = true;
console.log("Set the value for data field: " + dataFieldName); }
}
for (var attachmentName in stepElement.attachments) {
console.log("Set the value for attachment: " + attachmentName); var attachment = stepElement.attachments[attachmentName]; if (attachment.isArray) { attachment.value = [{"vsId":"{997E0AAC-8068-4990-AC08-D748E3063162}", "title":"Document Title", "type":3, "libraryName":"objectstore", "libraryType":3, "version":"{D48EE0A9-61CA-4DAD-8B61-961CE362434B}", "desc":"A document added programmatically"}]; } else {
attachment.value =
"title":"Document Title", "type":3,
"libraryName":"objectstore", "libraryType":3,
"version":"{D48EE0A9-61CA-4DAD-8B61-961CE362434B}", "desc":"A document added programmatically"};
}
attachment.modified = true; }
// set workflow group participant
for (var workflowGroupName in stepElement.workflowGroups) { console.log("Set the value for workflow group: " + workflowGroupName);
var workflowGroup = stepElement.workflowGroups[workflowGroupName]; if (workflowGroup.isArray) { workflowGroup.value = [{"Administrator"}]; } else { workflowGroup.value = {"Administrator"}; } workflowGroup.modified = true; }
// Set the selected Response
stepElement.systemProperties.selectedResponse = "Complete";