Skip Headers

Agile Product Lifecycle Management Web Services Guide Release 9.3.3 E39310-01 |
| Contents

Previous | Next |

# 7 Managing Workflows

This chapter describes how to manage the Agile PLM workflows and provides sample code snippets.

## 7.1 About Agile PLM Workflows

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 need to approve or observe the change.

- Send email alerts automatically to approvers and 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 should take these workflow dynamics into account and, where possible, adjust your program accordingly.

### 7.1.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 operation getStatus. This operation returns an object for the workflow status.

## 7.2 Getting the Status of a Workflow

The workflow actions available for a pending change are different from those for a released change. To check the status of a change use the operation getStatus. 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);

## 7.3 Getting the Workflow of a Routable Object

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);

## 7.4 Setting a Workflow

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);

## 7.5 Checking User Privileges

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.

Refer Schema documentation on Oracle eDelivery Site for AgilePrivilegeType enumerations.

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);

## 7.6 Adding and Removing Approvers

After a change has been routed and the online approval process has begun, it may be necessary to add or remove people from the list of approvers or observers. To add or remove approvers or observers, a user must have both the Agile Product Change Server license and the Route privilege.

You don't need to load the Workflow table to modify the list of approvers. Once you have a routable object, such as 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 and observers, whether the notification is urgent, and an optional comment. The Agile Web Services provides overloaded operations for adding or removing a user or a user group from the list of approvers.

If any users you select as approvers or observers do not have appropriate privileges to view a change, your program throws an Exception on page 20. To avoid the possible exception, 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);

## 7.7 Getting Approvers

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);

## 7.8 Approving a Routable Object

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 );

## 7.9 Rejecting a Routable Object

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);

## 7.10 Commenting a Change

Use the operation CommentRObject operation to comment a change. Use Boolean variables to denote whether the orginators, change analysts and CCB need to be notified.

Example: Commmenting 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);

## 7.11 Auditing a Change

Auditing a routable object, like an ECO, requires specifying the type of routable object in the operation AuditRObj.

Example: Auditing a Change

    agileAuditRObjectRequestType[0].setClassIdentifier("ECO");
    agileAuditRObjectRequestType[0].setObjectNumber( changeNumber );
    agileAuditRObjectRequestType[0].setAuditRelease(true);
    auditRObjectRequestType.setRequest(agileAuditRObjectRequestType);

## 7.12 Changing the Workflow Status of an Object

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);