| Agile Product Lifecycle Management Web Services Guide Release 9.3.6 E71166-01 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management Web Services Guide Release 9.3.6 E71166-01 |
|
Previous |
Next |
This chapter describes how to manage the Agile PLM workflows and provides sample code snippets.
Agile has electronic routing, notification, and signoff capabilities, thus automating the change control process and providing a simplified but powerful workflow mechanism. With these workflow features, you can:
Route changes automatically to the users who must approve or observe the change.
Send email alerts automatically to approvers/observers to notify them that a change has been routed to them.
Approve or reject changes online.
Attach comments to changes.
The workflow functionality available to each user for a particular routable object depends on the status of the routable object and the user's privileges. Your Agile API program must take these workflow dynamics into account and, where possible, adjust programs accordingly.
The workflow actions available for a pending change are different from those for a released change. To check the status of a change to determine whether it's pending or released, use the operation "getStatus." This operation returns an object for the workflow status.
The workflow actions available for a pending change are different from those for a released change. Using the getstatus operation , we get the status of a change. This operation returns statusName value for the workflow status, which are Pending, Submitted, or Released.
Example: Getting the status of a Change Object
GetStatusRequestType getStatusRequestType = new GetStatusRequestType();
AgileGetStatusRequestType agileGetStatusRequestType[] = new AgileGetStatusRequestType[1];
agileGetStatusRequestType[0] = new AgileGetStatusRequestType();
agileGetStatusRequestType[0].setClassIdentifier("ECO");
agileGetStatusRequestType[0].setObjectNumber( changeNumber );
getStatusRequestType.setStatusRequest(agileGetStatusRequestType);
Select a workflow when you create a new change, package, product service request, or quality change order. An object without a workflow assigned is in the Unassigned state and cannot progress through a workflow process. The Agile system defines multiple workflows for each type of routable object.
To get the valid workflows for a routable object, which has not yet been assigned a workflow, use the operation "getWorkflows."
Example: Getting a workflow
GetWorkflowsRequestType getWorkflowsRequestType = new GetWorkflowsRequestType();
AgileGetWorkflowsRequestType agileGetWorkflowsRequestType[] = new AgileGetWorkflowsRequestType[1];
agileGetWorkflowsRequestType[0] = new AgileGetWorkflowsRequestType();
agileGetWorkflowsRequestType[0].setClassIdentifier("ECO");
agileGetWorkflowsRequestType[0].setObjectNumber( changeNumber );
getWorkflowsRequestType.setWorkflowRequest(agileGetWorkflowsRequestType);
If a change is still in the Pending state, you can deselect a workflow to make the change "unassigned" using the operation "setWorkFlow." and specifying the setWorkFlowIdentifier parameter.
You can select a different workflow as long as a change is in the Pending status. Once a change moves beyond the Pending status, you cannot change the workflow.
Example: Setting a workflow
SetWorkFlowRequestType setWorkFlowRequestType = new SetWorkFlowRequestType();
AgileSetWorkFlowRequestType agileSetWorkFlowRequestType[] = new AgileSetWorkFlowRequestType[1];
agileSetWorkFlowRequestType[0] = new AgileSetWorkFlowRequestType();
agileSetWorkFlowRequestType[0].setClassIdentifier("ECO");
agileSetWorkFlowRequestType[0].setObjectNumber( changeNumber );
agileSetWorkFlowRequestType[0].setWorkFlowIdentifier( workflow );
setWorkFlowRequestType.setSetWorkFlowRequest(agileSetWorkFlowRequestType);
Agile privileges determine the types of workflow actions a user can perform on a Change Object. The Agile system administrator assigns roles and privileges to each user. The table below lists privileges needed to perform workflow actions.
| Privilege | Related operation |
|---|---|
| Change Status | changeStatus |
| Comment | commentRObject |
| Send | sendObject |
To determine at run time whether a user has the appropriate privileges to perform a particular action, use the operation "checkPrivilege." It yields a boolean value indicating if the user has the specified privilege.
Example: Checking User privileges
AgileUserIdentifierType user = new AgileUserIdentifierType();
user.setUserIdentifier("admin");
agileCheckPrivilegeRequestType[0].setUserIdentification(user);
AgilePrivilegeType privilege = AgilePrivilegeType.value1;
agileCheckPrivilegeRequestType[0].setPrivilege(privilege);
agileCheckPrivilegeRequestType[0].setClassIdentifier("Part");
agileCheckPrivilegeRequestType[0].setObjectNumber( partNumber );
checkPrivilegeRequestType.setRequests(agileCheckPrivilegeRequestType);
After you route a change and the approval process begins, it may be necessary to add or remove people from the list of approvers/observers. To add or remove approvers/observers, you must have both the Agile Product Change Server license and the Route privilege.
It is not necessary to load the Workflow table to modify the list of approvers. Once you have a routable object, say an ECO, you can modify its list of approvers using the operations addApprovers and removeApprovers. With these operations, you can specify the list of approvers/observers, whether the notification is urgent, and add an optional comment. Agile Web Services provides overloaded operations for adding or removing a user/user group from the list of approvers.
If the users you select as approvers or observers do not have appropriate privileges to view a change, your program throws an Exception. To avoid this, check the privileges (checkPrivilege) of each user before adding him to the approvers or observers list.
Example: Adding an Approver or Observer
agileAddApproversRequestType[0].setClassIdentifier("ECO");
agileAddApproversRequestType[0].setObjectNumber( changeNumber );
agileAddApproversRequestType[0].setStatusIdentifier("CCB");
AgileUserUserGroupIdentifierType users[] = new AgileUserUserGroupIdentifierType[2];
users[0].setClassIdentifier("User");
users[0].setObjectIdentifier(user1);
users[1].setClassIdentifier(User);
users[1].setObjectIdentifier(user2);
agileAddApproversRequestType[0].setApprovers(users);
agileAddApproversRequestType[0].setObservers(null);
agileAddApproversRequestType[0].setUrgent(false);
agileAddApproversRequestType[0].setComment("Comments");
addApproversRequestType.setAddApproversRequest(agileAddApproversRequestType);
Example: Removing an Approver or Observer
agileRemoveApproversRequestType[0].setClassIdentifier("ECO");
agileRemoveApproversRequestType[0].setObjectNumber( changeNumber );
agileRemoveApproversRequestType[0].setStatusIdentifier("CCB");
AgileUserUserGroupIdentifierType usergroups[] = new AgileUserUserGroupIdentifierType[1];
usergroups[0].setClassIdentifier("User");
usergroups[0].setObjectIdentifier( USERNAME );
agileRemoveApproversRequestType[0].setApprovers(usergroups);
agileRemoveApproversRequestType[0].setObservers(null);
agileRemoveApproversRequestType[0].setComment("Comments");
removeApproversRequestType.setRemoveApproversRequest(agileRemoveApproversRequestType);
Set the statusIdentifier in the operation getApprovers to obtain the list of approvers.
Example: Getting Approvers for an Object
agileGetApproversRequestType[0].setClassIdentifier("ECO");
agileGetApproversRequestType[0].setObjectNumber( changeNumber );
agileGetApproversRequestType[0].setStatusIdentifier( status );
getApproversRequestType.setApproversRequest(agileGetApproversRequestType);
This method informs users the object is approved by the approver, or when the approver is approving the object on behalf of one or more user groups. You can also use this method to specify the secondSignature, escalations, transfers, or signoffForSelf parameters as they are set in server's Preferences settings. Use the operation "approveRObject."
Example: Approving a routable object and notifying the Users
AgileUserUserGroupIdentifierType notifiers[] = new AgileUserUserGroupIdentifierType[1];
notifiers[0] = new AgileUserUserGroupIdentifierType();
notifiers[0].setClassIdentifier("User");
notifiers[0].setObjectIdentifier( notifier1 );
AgileApproveRObjectRequestType agileApproveRObjectRequestType[] = new AgileApproveRObjectRequestType[1];
agileApproveRObjectRequestType[0] = new AgileApproveRObjectRequestType();
agileApproveRObjectRequestType[0].setClassIdentifier("ECO");
agileApproveRObjectRequestType[0].setObjectNumber( changeNumber );
agileApproveRObjectRequestType[0].setPassword( PASSWORD );
agileApproveRObjectRequestType[0].setComment("Comment");
agileApproveRObjectRequestType[0].setSecondSignature(null);
agileApproveRObjectRequestType[0].setNotifiers(notifiers);
agileApproveRObjectRequestType[0].setEscalations(null);
agileApproveRObjectRequestType[0].setTransfers(null);
agileApproveRObjectRequestType[0].setApproveForGroup(null);
agileApproveRObjectRequestType[0].setSignoffForSelf(true);
approveRObjectRequestType.setApproveRObject(agileApproveRObjectRequestType); agileRejectRObjectRequestType[0].setObjectNumber( changeNumber );
This method informs users that the routable object is rejected by the approver, or when the approver is rejecting the object on behalf of one or more user groups. You can also use this method to specify the secondSignature, escalations, transfers, or SignoffForSelf parameters as they are set in server's Preferences settings. Use the operation "rejectRObject."
Example: Rejecting a routable object and notifying the Users
agileRejectRObjectRequestType[0].setClassIdentifier("ECO");
agileRejectRObjectRequestType[0].setPassword( PASSWORD );
agileRejectRObjectRequestType[0].setComment("Comment");
agileRejectRObjectRequestType[0].setSecondSignature(null);
AgileUserUserGroupIdentifierType notifiers[] = new AgileUserUserGroupIdentifierType[1];
notifiers[0] = new AgileUserUserGroupIdentifierType();
notifiers[0].setClassIdentifier("User");
notifiers[0].setObjectIdentifier( notifier1 );
agileRejectRObjectRequestType[0].setNotifiers(notifiers);
agileRejectRObjectRequestType[0].setEscalations(null);
agileRejectRObjectRequestType[0].setTransfers(null);
agileRejectRObjectRequestType[0].setRejectForGroups(null);
agileRejectRObjectRequestType[0].setSignoffForSelf(true);
rejectRObjectRequestType.setRejectRObject(agileRejectRObjectRequestType);
Use the operation "commentRObject" operation to comment on a change. Use Boolean variables to denote whether the originators, change analysts and CCB must be notified.
Example: Commenting on a Change
agileCommentRObjectRequestType[0].setClassIdentifier("ECO");
agileCommentRObjectRequestType[0].setObjectNumber( changeNumber );
agileCommentRObjectRequestType[0].setComment("Comment");
agileCommentRObjectRequestType[0].setNotifyOriginator(true);
agileCommentRObjectRequestType[0].setNotifyChangeAnalyst(true);
agileCommentRObjectRequestType[0].setNotifyCCB(false);
AgileUserUserGroupIdentifierType notifyList[] = new AgileUserUserGroupIdentifierType[1];
notifyList[0] = new AgileUserUserGroupIdentifierType();
notifyList[0].setClassIdentifier("User");
notifyList[0].setObjectIdentifier( USERNAME );
agileCommentRObjectRequestType[0].setNotifyList(notifyList);
commentRObjectRequestType.setCommentRObjectRequest(agileCommentRObjectRequestType);
Auditing a routable object, like an ECO, requires specifying the type of routable object in the operation AuditRObject.
Example: Auditing a Change
agileAuditRObjectRequestType[0].setClassIdentifier("ECO");
agileAuditRObjectRequestType[0].setObjectNumber( changeNumber );
agileAuditRObjectRequestType[0].setAuditRelease(true);
auditRObjectRequestType.setRequest(agileAuditRObjectRequestType);
Use the operation changeStatus to change the workflow status of an object.
agileChangeStatusRequestType[0].setClassIdentifier("ECO");
agileChangeStatusRequestType[0].setObjectNumber( changeNumber );
agileChangeStatusRequestType[0].setNewStatusIdentifier( newStatus );
AgileUserUserGroupIdentifierType users[] = new AgileUserUserGroupIdentifierType[1];
users[0] = new AgileUserUserGroupIdentifierType();
users[0].setClassIdentifier("User");
users[0].setObjectIdentifier( user1 );
agileChangeStatusRequestType[0].setApprovers(users);
agileChangeStatusRequestType[0].setObservers(null);
agileChangeStatusRequestType[0].setNotifiers(null);
agileChangeStatusRequestType[0].setComment("Comments");
agileChangeStatusRequestType[0].setPassword("password");
agileChangeStatusRequestType[0].setAuditRelease(false);
agileChangeStatusRequestType[0].setUrgent(false);
agileChangeStatusRequestType[0].setNotifyOriginator(true);
agileChangeStatusRequestType[0].setNotifyChangeAnalyst(true);
agileChangeStatusRequestType[0].setNotifyCCB(true);
changeStatusRequestType.setChangeStatusRequest(agileChangeStatusRequestType);
