15 Managing Workflow

15.2.1 How the Status of a Change Affects Workflow Functionality

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 IRoutable.getStatus() method. The getStatus() method returns an IStatus object for the Workflow status. IStatus extends the INode interface and provides helpful methods for working with status nodes. The following example shows how to use getStatus() to determine whether a change is released.

Example: Getting the status of a change object

private static boolean isReleased(IChange change) throws APIException {
// Check if the user can change status
}

return (change.getStatus().getStatusType().equals(StatusConstants.TYPE_RELEASED);

15.2.2 How User Privileges Affect Workflow Functionality

Agile privileges determine the types of Workflow actions a user can perform on a change. The Agile system administrator assigns roles and privileges to each user. The table below lists privileges needed to perform Workflow actions.

To determine at run time whether a user has the appropriate privileges to perform an action, use the IUser.hasPrivilege() method. You can adjust your program's UI based on the user's privileges. The following example shows how to check whether a user has the privilege to change the status of a change before calling the IRoutable.changeStatus() method.

Example: Checking the privileges of a user before changing the status of a change

private void goToNextStatus(IChange change, IUser user) throws APIException {

if(user.hasPrivilege(UserConstants.PRIV_CHANGESTATUS, change)) {

IUser[] approvers = new IUser[] { user };

IStatus nextStatus = change.getDefaultNextStatus();

change.changeStatus(nextStatus, true, "", true, true, null, approvers, null, false);

} else {

System.out.println("Insufficient privileges to change status.");

}

}
// Get an Admin instance

public void modifyApprovers(IChange change) {
 
// Get current approvers for the change

// Get current observers for the change
// Add hhawkes to approvers

// Add flang to observers

// Add approvers and observers

// Add skubrick to approvers

// Add kwong to observers

// Remove skubrick from approvers and kwong from observers

}

public void addMeToApprovers(IChange change) {
 
// Get the current user

// Add the current user to the approvers list for the change

}

15.4.1 Approving or Rejecting Change

After a change is routed to a group of approvers, the online approval process begins. Users listed in the Workflow table for a change can approve or reject the change.

When you approve a change, the Agile system records the approval on the Workflow table. When all approvers have approved the change, the system sends an email Notification to the change analyst or component engineer indicating that the change is ready to be released.

When you use the IRoutable.approve() method, you specify the user's approval password and an optional comment. approve() methods allow you to specify a Notification list and a collection of user groups for which you're approving; refer to the API Reference files at Oracle® E-Cloud Web site (http://edelivery.oracle.com/) for details.

The following paragraphs document approving or rejecting a given routable object. The APIs that support approving or rejecting a change object when a second signature is required are described in detail in Setting the "Signoff User Dual Identification" Preference.

The following example shows how to approve a change.

Example: Approving a change

public void approveChange(IChange change) {

try {

change.approve("agile", "Looks good to me");

} catch (APIException ex) {

System.out.println(ex);

}

}

If a change has a fundamental flaw, users listed on the Workflow table may reject it. When you reject a change, the system records the rejection on the Workflow tab for the change and sends an email Notification to the change analyst or component engineer. The change analyst or component engineer may decide to return the rejected change to the originator, thus reverting its status to Pending.

When you use the IRoutable.reject() method, you must specify the userNotifications approval password and optional comments. An overloaded reject() method allows you to specify a Notification list and a collection of user groups for which you're approving; refer to the API Reference files at Oracle® E-Cloud Web site (http://edelivery.oracle.com/) for more information.

The following example shows how to reject a change.

Example: Rejecting a change

public void rejectChange(IChange change) {

try {

change.reject("agile", "Incorrect replacement part!");

} catch (APIException ex) {

System.out.println(ex);

}

}

15.4.2 Approving or Rejecting a Change Without Password

Agile PLM's Java Client provides the option to configure Workflow Settings to enable the approval or rejection of a change with or without typing a password. Users with the Administrator role and privileges configure this option by selecting the Yes or No option in the Password Required field shown in the following illustration.

The following example uses the Agile SDK to programmatically configure this requirement.

Example: Approving or rejecting change without a password

// Workflow settings - Password Required

Iadmin admin = session.getAdminInstance();

INode root = admin.getNode(NodeConstants.NODE_AGILE_WORKFLOWS);

INode CCBStatus = (INode)root.getChildNode("Default Change Orders/Status List/CCB/Status Properties");

IProperty PwdReq = CCBStatus.getProperty(PropertyConstants.PROP_WORKFLOW_PASSWORD_REQUIRED);

PwdReq.setValue("No");

// Approve change without passing password

change.approve(null, null, "Approve", null, null, null, null, true);

15.4.3 Commenting a Change

When you comment a change, you send a comment to other CCB reviewers during the online approval process. In addition to the comment, you can specify whether to notify the originator, the change analyst, and the change control board. An overloaded comment() method allows you to specify a Notification list. For more information, refer to the API Reference files at Oracle® E-Cloud Web site (http://edelivery.oracle.com/).

The following example shows how to comment a change.

Example: Commenting a change

public void commentChange(IChange change) {

try {

change.comment(true, true, true, "Change flagged for transfer to ERP.");

} catch (APIException ex) {

System.out.println(ex);

}

}

15.4.4 Auditing a Change

At any point in a change's workflow, you can audit it to determine if any required entry cells are not completed or if the change violates any Agile SmartRules. When you use the IRoutable.audit() method, the method returns a Map object containing ICell objects as keys and a List of APIException objects as values. The ICell key can be null if there are no problems with the change. The APIException object describes a problem with the associated entry cell.

The Map object returned by the audit() method may also contain null objects as keys. The APIException object associated with a null object describes a problem unrelated to data cells.

The following example shows how to audit a change.

Example: Auditing a change

public void auditChange(IChange change) {
// Audit the release

try {

Map results = change.audit();

// Get the set view of the map
// Get an iterator for the set

Set set = results.entrySet();

Iterator it = set.iterator();

// Iterate through the cells and print each cell name and exception

while (it.hasNext()) {

Map.Entry entry = (Map.Entry)it.next();

ICell cell = (ICell)entry.getKey();

if(cell != null) {

System.out.println("Cell : " + cell.getName());

} else {

System.out.println("Cell : No associated data cell");

}

//Iterate through exceptions for each map entry.

Iterator jt = ((Collection)entry.getValue()).iterator();

while (jt.hasNext()) {

APIException e = (APIException)jt.next();

System.out.println("Exception : " + e.getMessage());

}

}

} catch (APIException ex) {

System.out.println(ex);

}

}
// Get the next status of the change

15.4.5 Changing the Workflow Status of an Object

The IRouteable.changeStatus() method is a general purpose method for changing the status of an Agile object. For example, you can use changeStatus() to submit, release, or cancel a change. In instances such as failed audits, it throws the compound exception ExceptionConstants.API_SEE_MULTIPLE_ROOT_CAUSES. You can disable this exception by modifying the code that caught the exception. See the example below.

Example: Throwing compound exception s

while (true) {

try {

change.changeStatus(

wf.getStates(expectStatus)[0],

false,

"comment",

false,

false,

null,

null,

null,

false

);

} catch (APIException ae) {

try {

if

(ae.getErrorCode().equals(ExceptionConstants.API_SEE_MULTIPLE_ROOT_CAUSES)){

Throwable[] causes = ae.getRootCauses();

for (int i = 0; i < causes.length; i++) {

m_session.disableWarning(

(Integer)((APIException)causes[i]).getErrorCode());

}

} else {

m_session.disableWarning((Integer)ae.getErrorCode());

}

} catch (Exception e) {

throw ae;

}

continue;

}

break;

}

In general, you release a change after it is signed off by CCB members. In addition to modifying the status of a change, you can also use changeStatus() to specify a Notification list, optional comments, and whether to notify the originator and change control board.

Depending on the overloaded changeStatus() method you use, the notifyList parameter is an array of IUser or IUserGroup objects that should be notified about the change in status; refer to the API Reference files at Oracle® E-Cloud Web site (http://edelivery.oracle.com/) for details. To use the default Notification list for the Workflow status, specify a null value. To indicate that no users should be notified, specify an empty array.

For both the approvers and observers parameters of the changeStatus() method, you must explicitly pass an array of users or user groups. If you pass null, no approvers or observers are used. To get the default approvers and observers for a particular Workflow status, use getApproversEx() and getObserversEx(), respectively.

The following example shows how to check the Workflow status of a change.

Example: Checking the status of a change

void checkStatus(IChange change) {
// Get current workflow status (an IStatus object)

try {

IStatus status = change.getStatus();

System.out.println("Status name = " + status.getName());

// Get next available Workflow statuses

IStatus[] nextStatuses = change.getNextStatuses();

for (int i = 0; i < nextStatuses.length; i++) {

System.out.println("nextStatuses[" + i +"] = " +

nextStatuses[i].getName());

}

// Get next default Workflow status

IStatus nextDefStatus = change.getDefaultNextStatus();

System.out.println("Next default status = " + nextDefStatus.getName());

} catch (APIException ex) {

System.out.println(ex);

}

}

The following example shows how to change the status of a change.

Example: Changing the status of a change

public void nextStatus(IChange change, IUser[] notifyList,

IUser[] approvers, IUser[] observers) {

try {

// Check if the user has privileges to change to the next status

IStatus nextStatus = change.getDefaultNextStatus();

if (nextStatus == null) {

System.out.println("Insufficient privileges to change status.");

return;

}

// Change to the next status

else {

change.changeStatus(nextStatus, true, "", true, true, notifyList, approvers, observers, false);

}

} catch (APIException ex) {

System.out.println(ex);

}

}

The following example shows how to use the default approvers and observers when you change the status of a routable object.

Example: Changing the status and routing to the default approvers and observers

public void changeToDefaultNextStatus(IChange change) throws APIException {

IStatus nextStatus = change.getDefaultNextStatus();

// Get default approvers for the next status
Funcational Teams is a class under User Group Base Class having out of the box sub class 'Functional Team'. Creating Functional Team object is similar to creating any Agile object as detailed below:
// Get default observers for the next status

IDataObject[] defaultApprovers = change.getApproversEx(nextStatus);

IDataObject[] defaultObservers = change.getObserversEx(nextStatus);

// Change to the next status
 
}

change.changeStatus(nextStatus, false, "", false, false, null, defaultApprovers, defaultObservers, false);

15.4.6 Sending an Agile Object to Selected Users

You can send any Agile object to a selected group of users. When you send an object, such as an ECO, there is no signoff required. The selected recipients receive an email message with an attached link to the object. When you use the IDataObject.send() method, you can specify an array of Agile users and an optional comment. Unlike other Workflow commands, the send() method is not limited to routable objects. You can use it to send any type of Agile dataobject, including an item.

The following example shows how to send an object to all users.

Example: Sending an Agile object to selected users

public void sendToAll(IDataObject object) {
// Get all users

try {

IQuery q = (IQuery)m_session.createObject(IQuery.OBJECT_TYPE, "select * from [Users]");

ArrayList userList = new ArrayList();

Iterator i = q.execute().getReferentIterator();

while (i.hasNext()) {

userList.add(i.next());

}

IUser[] users = new IUser[userList.size()];

System.arraycopy(userList.toArray(), 0, users, 0, userList.size());

// Send the object to all users

object.send(users, "Please read this important document.");

} catch (APIException ex) {

System.out.println(ex);

}

}

15.4.7 Sending an Agile Object to User Groups

You can send an Agile change object or an item object to a user group. When you send an object, such as an ECO, there is no signoff required. The selected recipients receive an email message with an attached link to the object. When you use the IDataObject.send(IDataObject[] to, String Comment) method, you can specify an array of Agile User Groups and an optional comment. The IDataObject parent interface represents the IUserGroup Agile object. Unlike other Workflow commands, the send() method is not limited to routable objects. You can use it to send any type of Agile dataobject, including an item.

The following example shows how to send an object to all User Groups.

Example: Sending an Agile object to selected user groups

public void sendToAll(IDataObject[] object) {
 
// Get all user groups

try {

IQuery q = (IQuery)m_session.createObject(IQuery.OBJECT_TYPE, "select * from [UserGroup]");

ArrayList usergroupList = new ArrayList();

Iterator i = q.execute().getReferentIterator();

while (i.hasNext()) {

usergroupList.add(i.next());

}

IUserGroup[] group = (IUserGroup[])(usergroupList.toArray());

// Send the object to all user groups

object.send(usergroups, "Please read this important document.");

} catch (APIException ex) {

System.out.println(ex);

}

}

15.5.1 Job Functions, Functional Teams, and Workflow Actions

You can use the SDK to eliminate updating the approval criteria in the event of a change in the approval criteria by defining the following Workflow-related objects and attributes:

• Job Function - The job performed by a user. Examples are product manager, product marketing manager, development lead, development manager, and so on.

• Functional Team - Group of users and/or user groups who work as a team to perform specific job functions. Logically, a Functional Team is a Job Function and not a User, because a Job Function can be associated with a Functional Team without any Users, but a User can not be added to a Functional Team without an assigned Job Function.

• Reviewers - Based on the role, a Reviewer can be an Approver, an Acknowledger, or an Observer. A user can have more than one Reviewer role.

  
  

  Note: Users can have more than one Reviewer role, but they cannot be Acknowledgers, Observers and/or Approvers.

  
  

  • Observers - A workflow action that requires the notified users to signoff when notified. Observers can be Users, User Groups or Functional Teams.

  • Acknowledgers - A workflow action that requires the notified users to signoff the change they have approved. This is different from an approval signoff. Acknowledgers can be Users, User Groups or Functional Teams.

  • Approvers - Approvers can sign -off for multiple job functions. Approvers can be Users, User Groups or Functional Teams.

15.5.2 Creating a Functional Team

Functional Teams are uniquely identified by name and they are a class under the User Group Base Class with the Functional Team as the default sub class. Creating a Functional Team object is similar to creating any Agile object. To create a Functional Team, use the IAgileSession.createObject method, specifying both the class and the name of the Team.

All users cannot create a Functional Team. Only users who have the Create privilege for this object can create Functional Teams.

Example: Creating a Functional Team

IAgileClass ft_class = session.getAdminInstance().getAgileClass("Functional Team");

HashMap map = new HashMap();

//Put values into map // map.put(UserGroupConstants.ATT_GENERAL_INFO_NAME, "PGC");

map.put(UserGroupConstants.ATT_GENERAL_INFO_DESCRIPTION, "PGC Functional Team");

IDataObject FtObj = (IDataObject) (session.getObject(UserGroupConstants.CLASS_FUNCTIONAL_TEAM, map));

if (FtObj==null){

// Create Functional Team with this Map //

FtObj = (IDataObject) session.createObject(ft_class, map);

}

//Exmple to Create Functional Team
            IAgileClass ft_class = session.getAdminInstance().getAgileClass("Functional Team");
            HashMap map = new HashMap();
            //Put values into map // map.put(UserGroupConstants.ATT_GENERAL_INFO_NAME, "PGC");
            map.put(UserGroupConstants.ATT_GENERAL_INFO_DESCRIPTION, "PGC Functional Team");
            IDataObject FtObj = (IDataObject) (session.getObject(UserGroupConstants.CLASS_FUNCTIONAL_TEAM, map));
            if (FtObj==null){
                //   Create Functional Team with this Map     //
                FtObj = (IDataObject) session.createObject(ft_class, map);
            }
 

15.5.3 Managing Timesheets

PPM has the capability to manage the following Timesheet-related functions from the Web Client. The SDK enables performing the functions programmatically, by exposing the ITimesheetManager.

• Retrieving tasks a user can report time against - This feature enables retrieving the Web Client's Timesheet view and the list of tasks the user can report time against programmatically.

• Logging or modifying time reported for a user on a task - Similar to the Web Client, this feature supports logging or modifying time by day or activity for the user.

• Retrieving hours for a user or activity - This feature enables searching and retrieving hours for a user, an activity, a project, the date in between, and Canceled and Soft-Deleted activities. Results are provided as CSV or XLS similar to the UI

15.5.4 Creating a Job Functions Table

A Functional Team object contains a valid Job function and associated members such as users, user groups, and so on, in its Job Functions Table.

Example: Creating a Job Functions Table

//get Job Functions Table of the Functional Team Object

ITable jobFuncTbl=FtObj.getTable(UserGroupConstants.TABLE_JOBFUNCTION);

IDataObject usr0 = (IDataObject) session.getObject(UserConstants.CLASS_USER, "usr01");

IDataObject usr1 = (IDataObject) session.getObject(UserConstants.CLASS_USER, "usr02");

IDataObject uGp0 = (IDataObject) session.getObject(UserGroupConstants.CLASS_USER_GROUP, "usrGroup01");

IRow ft_jf_row;

try{

map.clear();

map.put(UserGroupConstants.ATT_JOB_FUNCTION_NAME, "Developer"); //a valid value from 'Job Functioins' list

map.put(UserGroupConstants.ATT_JOB_FUNCTION_USERS_USERGROUPS, new Object[] {usr0, usr1, uGp0});

ft_jf_row = jobFuncTbl.createRow(map);

map.clear();

map.put(UserGroupConstants.ATT_JOB_FUNCTION_NAME, "Product Manager"); //a valid value from 'Job Functioins' list

map.put(UserGroupConstants.ATT_JOB_FUNCTION_USERS_USERGROUPS, new Object[] {usr1, uGp0});

ft_jf_row = jobFuncTbl.createRow(map);

}catch(APIException e){

System.out.println(e.getRootCause());

}

15.5.5 Adding a Discussion to a Functional Team

Discussions are integrated into the Product Portfolio Management solution, and are also applicable to the Product Cost Management solution. Discussions are created similar to other Agile PLM objects. Discussions are always viewed in the Web Client. To access a discussion while using Java Client, you can search to locate an existing discussion and open the object, which will open the Web Client. Also, you can open the Web Client and proceed from there to create a discussions.

The following example shows how to add a Discussion to a Functional Team.

Example: Adding a discussion to Functional Team

ITable ft_dc_tbl = (ITable)FtObj.getTable(UserGroupConstants.TABLE_DISCUSSIONS);

//Create a New discussion and add it to Functional Team.Discussion Table

IAgileClass discClass = session.getAdminInstance().getAgileClass(DiscussionConstants.CLASS_DISCUSSION);

String discNmbr = "D00003";

map.put(DiscussionConstants.ATT_COVER_PAGE_NUMBER, discNmbr);

map.put(DiscussionConstants.ATT_COVER_PAGE_SUBJECT, "Testing Func Team: "+discNmbr );

IDiscussion disc = (IDiscussion)session.getObject(DiscussionConstants.CLASS_DISCUSSION, map);

if (disc == null){

disc = (IDiscussion)session.createObject(DiscussionConstants.CLASS_DISCUSSION, map);

}

//Add Discussion to FunctionalTeam.Discussions Table

map.clear();

//map.put(UserGroupConstants.ATT_DISCUSSIONS_NUMBER, disc.getName());

map.put(UserGroupConstants.ATT_DISCUSSIONS_NUMBER, disc);

IRow newRow = ft_dc_tbl.createRow(map);