Using Approval Framework Base Classes

This chapter provides an overview of Approval Framework base classes and discusses:

• How to import Approval Framework type classes.

• The LaunchManager class.

• The ApprovalManager class.

Understanding Approval Framework Base Classes

Approval Framework Base Classes provide functions to launch workflow, manager approvals, display approval monitor. In order to build custom Approval Framework processes, you will need to extend these class in your PeopleCode.

How to Import Approval Framework Base Classes

The Approval Framework base classes are not built-in classes, like Rowset, Field, Record, and so on. They are application classes. Before you can use these classes in your PeopleCode program, you must import them to your program.

An import statement names either all the classes in a package or one particular application class. For importing Approval Framework base classes, Oracle recommends that you import the functions class in the application package that is specific to your needs.

The function classes are stored in EOAW_CORE application packages:

You should use construct your import statement to include the classes necessary for your code. Some examples are:

import EOAW_CORE:*;
import EOAW_CORE:LaunchManager;
import EOAW_CORE:ApproverManager

LaunchManager Class

This class provides the utility methods to launch Approval Framework.

LaunchManager Class Methods

Application developers should instantiate this class as a component-scoped variable. The best place to initialize this class is in the component post-build event. This section describes the LaunchManager class methods. The methods are discussed in alphabetical order.

LaunchManager

Syntax

LaunchManager(&awprcs_id, &hdr_ , &requester_)

Description

Launches the Approval Framework process.

Parameters

Returns

None.

Example

This is an example to launch Approval Framework for VoucherApproval.

import EOAW_CORE:*;
Component EOAW_CORE:LaunchManager &launchMgr;

If VOUCHER.VCHR_APPRVL_FLG = "W" Then
   &vchrRecord = CreateRecord(Record.VCHR_AF_HDR_VW);⇒
   GetLevel0()(1).GetRecord(Record.VOUCHER).CopyFieldsTo(&vchrRecord);
   &launchMgr = create EOAW_CORE:LaunchManager("VoucherApproval", &vchrRecord,⇒
 %OperatorId);

DoSubmit

Syntax

DoSubmit()

Description

Used to submit a new transaction for approval. An exception is thrown if the property submitEnabled is not true.

Parameters

None.

Returns

None.

Example

This is an example of submitting the transaction.

import EOAW_CORE:*;

Component EOAW_CORE:LaunchManager &launchMgr;

&launchMgr.DoSubmit();

DoReSubmit

Syntax

DoReSubmit()

Description

Used to resubmit a transaction which was previously submitted, and the previous approval processes have completed (approved, denied or terminated). An exception is thrown if the property resubmitEnabled is false.

Parameters

None.

Returns

None.

Example

This is an example to resubmit a process:

import EOAW_CORE:*;

Component EOAW_CORE:LaunchManager &launchMgr;

&launchMgr.DoReSubmit();

DoRestart

Syntax

DoRestart()

Description

Used to restart a currently running approval process. An exception is thrown if the property restartEnabled is false.

For example, in eProcurement, a requisition can be modified after has been approved. Since it was approved, Approval Framework sees it as closed (ended) and will not allow it to be resubmitted. The only option is to restart the transaction. Restart will reset all approval actions and route to the first approver regardless of the previous approvals.

Parameters

None.

Returns

None.

PrepareToSubmit

Syntax

PrepareToSubmit()

Description

This method instantiates an approval process, but does not save or launch it. Repeated calls to this method do nothing, if an approval process has been instantiated (or if an approval process is running), this method simply returns. The point is that the requester can add ad-hoc approvers while previewing which will be included in the process launched by DoSubmit(). The DoSubmit(), DoResubmit(), DoPreview() and DoRestart() methods all call this method. So any approval process instantiated by DoPreview() will be reused by the above methods. When this behavior is not desired, application developers use the Reset() method.

Note. Repeated calls to prepare to submit can result in performance problems. Typically, this method is only used when ready to submit or when previews are necessary.

Parameters

None.

Returns

None.

SetHeader

Syntax

SetHeader(&hdr_)

Description

When creating a new application transaction, some applications do not fully populate the key fields until it is saved. For instance, eProcurement uses a generated id number for requisitions, but does not populate the id field until a new transaction is saved. Since applications need to initialize the LaunchManager object in the component post-build event code, this poses a challenge. In such situations, application developers can safely call this method to reset the header record before submitting a new transaction for approvals. It is always safe to call this method as long as the header record being passed in is valid. However when this method will re-instantiate the approval process, which eliminates any performance improvements achieved by caching previewed instances.

Parameters

Returns

None.

Example

&reqRecord = CreateRecord(Record.PV_REQHDR_AW_VW);
GetLevel0()(1).GetRecord(Record.REQ_HDR).CopyFieldsTo(&reqRecord);
&launchMgr.SetHeader(&reqRecord);
&launchMgr.DoSubmit();

Reset

Syntax

Reset()

Description

This method clears the approval process instance cached by the DoPreview() method. Approval process instances are cached between DoPreview() and DoSubmit() calls because a requester can add ad-hoc approvers to the previewed process before submitting. If ad-hoc approvers are added, using DoSubmit() to regenerate the approval process instance would cause the ad-hoc approvers to be lost. However, application developers must take care to call Reset() if the requester changes any significant fields between calls to DoPreview() and DoSubmit(). Since the Approval Framework does not know which fields are significant, this responsibility falls to the application developer. If concerned about catching all such situations, developers can adopt the strategy of always calling Reset() before calling DoSubmit() or any of its cousins. But this runs the risk of losing any ad-hoc approvers added by the requester during preview. Finally, if the application allows users to change the requester (for instance, when one user submits a transaction on behalf of another), the LaunchManager property requester needs to be updated. Updating the requestor property automatically calls the Reset() method.

Parameters

None.

Returns

None.

FindDefinitionID

Syntax

FindDefinitionID()

Description

This method will return all definition IDs that have criteria matches. A developer can set the definition ID using the definitionID property. If a method such as DoSubmit or DoResubmit is called before this property is set, Approval Framework will use the first definition ID returned based on priority order.

Parameters

None.

Returns

Array of records.

TerminateRunningProcess

Syntax

TerminateRunningProcess()

Description

Terminates a running process.

Parameters

None.

Returns

None.

LaunchManager Class Properties

This section describes the LaunchManager class properties.

hasTxn

Description

True if the application's process id valid.

definition

Description

Set the definition and re-initialize the AppDef.

hasAppDef

Description

True if an approval process has been defined.

hasAppInst

Description

True if an approval process is currently running on this application transaction.

hasEndedAppInst

Description

True if an approval process has previously been run on this application transaction.

EOAW_CORE:DEFN:AppDef appDef

Description

The approval process definition currently active on this application.

resubmitEnabled

Description

Used to determine if this transaction can be re-submitted for approval. This will be true when:

1. A transaction registry entry exists.

2. An approval process has been defined.

3. One or more approval processes were launched on this transaction, but none are currently running (they were either approved, denied, or terminated.

Example

If &launchMgr.resubmitEnabled = True Then
      &launchMgr.DoReSubmit();
 End-If;

submitEnabled

Description

Used to determine if the submit action (which triggers launching of the Approval Framework) is currently enabled on this application transaction. Submit will be enabled when:

1. A transaction registry entry exists.

2. An approval process has been defined.

3. No approval process has previously been launched on this transaction.

Example

If (&launchMgr.submitEnabled) Then
   &launchMgr.DoSubmit();
End-If;

restartEnabled

Description

Used to determine if this transaction's approval process be restarted. This will be true if an approval process is currently running.

monitorEnabled

Description

Used to determine if the Approval Monitor is enabled. The monitor is enabled if an approval process is running.

previewEnabled

Description

Preview is enabled if a process is not currently running on this transaction. The DoPreview() method only presents a preview of the approval process to be launched going forward. It is not meant for a review of prior processes.

Note. DoPreview does not display completed approval processes for this transaction.

EOAW_CORE:ENGINE:AppInst appInst

Description

The approval process instance currently running. Can be null.

EOAW_CORE:DEFN:AWTxn txn

Description

The application transaction registry entry.

This property is read-only.

requester

Description

Use this property to get or set the requester on whose behalf this transaction is to be submitted for approval. Note that this property is not read-only. Applications may change the requester even after constructing the LaunchManager, but with certain caveats.

Approval Manager Class

This class provides the methods to manage the approval process.

ApprovalManager Class Methods

The approval manager object is the application developers interface to the Approval Framework. Most developers will not find it necessary to directly access any other Approval Framework objects. Application developers should instantiate this class as a component-scoped variable. The best place to initialize this class is in the component post-build event. The class can be instantiated with information readily available to developers at component post-build time. Developers should examine the boolean-valued properties of this object to know whether or not the user entering the approval component has any pending approvals work. If there are any pending approvals, the GetPending() method will identify what is pending, and the action methods such as DoApprove(), or DoDeny(), will enable them to implement the full approval functionality.

This section lists the Approval Manager class methods in alphabetical order.

ApprovalManager

Syntax

ApprovalManager(&awprcs_id, &hdr_, &approver_)

Description

Developers need to know their transaction id, and need to pass in an instance of their application's main record, which describes the request being submitted for approval. They also need to explicitly tell the Approval Framework who the approver is.

Parameters

Example

import EOAW_CORE:*;
Component EOAW_CORE:ApprovalManager &approvalMgr;
&vchrRecord = CreateRecord(Record.VCHR_AF_HDR_VW);
GetLevel0()(1).GetRecord(Record.VCHR_FS).CopyFieldsTo(&vchrRecord);
&approvalMgr = create EOAW_CORE:ApprovalManager("VoucherApproval",⇒
 &vchrRecord, %UserId);

DoApprove

Syntax

DoApprove(&rec)

Description

Use this method to approve the transaction for the record.

Parameters

DoApproveRowSet

Syntax

DoApproveRowSet(&rs)

Description

Use this method to approve transactions for the entire rowset. If this is a line-level record, then all paths which had routed this record to the approver are advanced.

For example, if an expense report has 3 lines o and you want to approve all 3 lines, you would insert the records into a rowset and pass that rowset to DoApproveRowset. Approval Framework will approve each line in that rowset. This avoids repeated calls to Approve.

Parameters

Returns

None.

DoReassign

Syntax

DoReassign(&rec, &reassignee, &bAllowAutoApprove, &bAllowSelfApprove, &comment)

Description

Use this method to reassign the record instance to a different approver.

Parameters

Returns

String.

DoReassignAll

Syntax

DoReassignAll(&reassignee, &bAllowAutoApprove, &bAllowSelfApprove, &comment)

Description

Note. Use this method to reassign all line items for the transaction to a different user for approval.

Parameters

Returns

String.

DoDeny

Syntax

DoDeny(&rec)

Description

Use this method to deny approval on a record instance. If the record is a header record, then the approval process ends. If the record is a line-level record, that particular line's processing ends, while the other records in that transaction continue.

Parameters

Returns

None.

Example

&approvalMgr.DoDeny(&reqRecord);

DoDenyRowset

Syntax

DoDenyRowset(&rs)

Description

Use this method to deny approval on a rowset. This is used to enable Approval Framework to deny multiple lines at once rather than looping through each line.

Parameters

Returns

None.

DoDenyWithAllowUndeny

Syntax

DoDenyWithAllowUndeny(&rs)

Description

Use this method to deny approval on a rowset, where resubmits are not allowed.

Parameters

Returns

None.

DoHardDeny

Syntax

DoHardDeny(&rec)

Description

Use this method to deny approval on a record instance and not allow re-submits. If the record is a header record, then the approval process ends. If the record is a line-level record, that particular line's processing ends, while the other records in that transaction continue.

Parameters

Returns

None.

DoLineResubmit

Syntax

DoLineResubmit(&rec, &start)

Description

Allows the line being passed in to be resubmitted to a running transaction. The user decides if the line is restarted from the current stage or the beginning. If it starts from the beginning, all history after the first header stage is lost.

Parameters

Returns

None.

Example

&approvalMgr.DoLineResubmit(&reqLnRecord, True);

DoAddNewLine

Syntax

DoAddNewLine(&rec, &start)

Description

Use to allow the line being passed in to be added to a running transaction. The user decides if the line is restarted from the current stage or the beginning. If it starts from the beginning, all history after the first header stage is lost.

Parameters

Returns

None.

GetPending

Syntax

GetPending()

Description

This method returns a rowset in the form of the applications header or line record that includes any header row or line row that is pending.

Parameters

None.

Returns

Rowset containing pending transactions.

Example

&LINERS = CreateRowset(Record.PV_REQLIN_AW_VW);
&LINERS = &approvalMgr.GetPending();

DoPushback

Syntax

DoPushback(&rec)

Description

Use this method to send the process back to the previous approver. This is used to give the approver a means of requesting a prior approver to make a clearer case for approving the transaction.

Note. Pushback only works to push back the workflow to a prior step in the same path. Calling Pushback() on the first step its path does nothing.

Parameters

Returns

None.

Example

&approvalMgr.DoPushback(&reqRecord);

AddComments

Syntax

AddComments(&username, &rec, &comments)

Description

Use this method to add comments in the approval process.

Parameters

Returns

None.

Example

&approvalMgr.AddComments(getUserName(%OperatorId),⇒
 &reqRecord, PV_REQ_APPPG_WK.COMMENTS_2000);

TakeNoAction

Syntax

TakeNoAction(&rec)

Description

Use this method to update the user's status as no action taken. If all approvers at this step take no action, then the step will advance and the current step will store the status for No Action Taken.

Parameters

Returns

None.

PutOnHold

Syntax

PutOnHold(&rec)

Description

Used to put the record instance passed in on hold for this step. If this is a line-level record, then all paths which had routed this record to the approver are advanced.

Parameters

Returns

None.

PutOnHoldCount

Syntax

PutOnHoldCount(&rec)

Description

This method is used to count how many approvers have put an approval transaction on hold. For example, if there are 10 approvers and 5 approvals are needed, checking to see that 3 approvers put it on hold will tell you that there are still 7 approvers that have not looked at the transaction yet.

Parameters

Returns

Array of string.

GetPushedBack

Syntax

GetPushedBack()

Description

Use this method to retrieve all the rows in a transaction that were pushed back.

Returns

Rowset.

GetPertinentThreads

Syntax

GetPertinentThreads(&checkApprover, &userType)

Description

Use this method to determine what threads are pending review or approval.

Parameters

Returns

Rowset.

GetStage

Syntax

GetStage(&rec)

Description

Use this method to retrieve the current stage of the approval process for a transaction.

Parameters

Returns

EOAW_CORE:ENGINE:StageInst

GetPendingSteps

Syntax

GetPendingSteps()

Description

Use this method to determine all pending steps for an approval process. This method returns a list of step-instance objects pending for this transaction.

Parameters

None.

Returns

Array of EOAW_CORE:ENGINE:UserStepInst.

DoLineTerminate

Syntax

DoLineTerminate(&LineRec)

Description

Use this method to terminate the given line level approval.

Parameters

GetParticipant

Syntax

GetParticipant(&username)

Description

Use this method to determine whether or not the user is a participant in the approval process. This method returns the participation status for a user that is currently pending or has taken an action.

Parameters

Returns

Returns a string to determine user participation in the approval process:

• N- if the user is not a participant in the approval.

• AA- if the user is the actual approval.

• OA- if the user is the original approval.

• RR- if the user is a reviewer.

• O- if the user is the originator.

• R- if the user is the requestor.

GetAllActiveParticipants

Syntax

GetAllActiveParticipants()

Description

Use this method to retrieve a list of all users that have either been flagged as Approvers, Reviewers, requestor or initiator.

Parameters

None.

Returns

Array of string.

RequestInformation

Syntax

RequestInformation(&user, &rs)

Description

Use this method to put a step on hold until the specified user provides more information.

Parameters

Returns

None.

SetAttributeObject

Syntax

SetAttributeObject(&attrObj_)

Description

Use this method to set the Approval Attribute class on the Appinst class.

Parameters

Returns

None.

ApprovalManager Class Properties

This section describes the ApprovalManager class properties.

hasAppInst

Description

True if the current transaction (header record) has a currently pending Approval Framework instance.

definition

Description

Get the current definition ID set on the App Def.

level

Description

The level of the pending approval work--0 for header, 1 for line-level. The Approval Framework architecture guarantees that header and line-level approval work cannot be pending at the same time.

This property is read-only.

hasPending

Description

True if the user has any pending approval tasks for the current transaction.

Note. Typically this will be the signed on user, but it does not have to be.

pushbackEnabled

Description

This method is used to determine if there is any path that is pending with a step number greater than one. If there is a step greater than one, True is returned and push back is enabled.

This is a read-only property.

EOAW_CORE:ENGINE:AppInst the_inst

Description

The current approval process instance.

isReviewer

Description

True if the user is a reviewer in the approval process.

This is a read-only property.

Approval Event Handler Class

This class provides methods to monitor events and notify the approval framework.

ApprovalEventHandler Class Methods

The ApprovalEventHandler class is used to perform actions that are required at the specific points in the process. For instance, if a new Employee has been approved, then the required action would be to activate that user. The purpose of this class is to move the check for specific statuses or actions from the Component to Approval Framework. This sections lists the ApprovalEventHandler class methods.

ApprovalEventHandler

Syntax

ApprovalEventHandler()

Description

This method is the constructor for the ApprovalEventHandler class. Its only purpose is to create an object that can be used to access the other methods.

OnProcessLaunch

Syntax

OnProcessLaunch(&appInst)

Description

This method is called with the newly-launched approval process instance, after the launch operation is successful.

Parameters

Returns

None.

Example

method OnProcessLaunch

   /+ &appInst as EOAW_CORE:ENGINE:AppInst +/

   /+ Extends/implements EOAW_CORE:ApprovalEventHandler.OnProcessLaunch +/

   

   &appInst.thread.SetAppKeys(&vndrRecord);

   %This.updateProcessFlag(&PENDING);

end-method;

OnStepActivate

Syntax

OnStepActivate(&stepinst)

Description

Use this method when a step instance is activated, the approvers and reviewers associated with the step will receive a worklist entry, if they do not already have one). The activated step instance itself is passed in as the argument.

Parameters

Returns

None.

OnStepHold

Syntax

OnStepHold(&userinst)

Description

Use this method to put this step on hold when a user performs an action. On Hold means that the user plans to take action at a later time.

Parameters

Returns

None.

OnStepReassign

Syntax

OnStepReassign(&userinst, &origApprover)

Description

Use this method to indicate the action when a step is reassigned.

Parameters

Returns

None.

OnStepComplete

Syntax

OnStepComplete(&stepinst)

Description

Use this method to indicate the action to take place when the step is complete.

Parameters

OnStepPushback

Syntax

OnStepPushback(&userinst)

Parameters

OnStepReactivate

Syntax

OnStepReactivate(&stepins)

Description

Use this method when a step is reactivated.

Parameters

OnFinalHeaderDeny

Syntax

OnFinalHeaderDeny(&appinst As EOAW_CORE:ENGINE:AppInst);

Description

Use this method for the final denial.

Parameters

Returns

None.

OnHeaderDeny

Syntax

OnHeaderDeny(&userinst)

Description

Use this method for header denial.

Parameters

OnHeaderApprove

Syntax

OnHeaderApprove(&appinst)

Description

Use this method to indicate the action to take when the header is approved.

Parameters

OnNoApprovalNecessary

Syntax

OnNoApprovalNecessary(&appinst)

Description

Use this method when no approval is necessary.

Parameters

OnLineDeny

Syntax

OnLineDeny(&userstep)

Description

Use this method to indicate the action to take when a line is denied.

Parameters

OnLineApprove

Syntax

OnLineApprove(&appinst, &thread)

Parameters

OnAllLinesProcessed

Syntax

OnAllLinesProcessed(&appinst, &approved, &denied)

Description

Use this method when all lines are processed.

Parameters

OnTerminate

Syntax

OnTerminate(&appinst As EOAW_CORE:ENGINE:AppInst);

Description

Use this method when the application instance is terminated.

Parameters

OnError

Syntax

OnError(&stepinst)

Description

Use this method when an error occurs in a step.

Parameters

OnStepReview

Syntax

OnStepReview(&stepinst, &reviewers)

Description

Use this method to indicate the action to take when the step instance is reviewed.

Parameters

OnTimeout

Syntax

OnTimeout(&userinst, &notify)

Parameters

OnAdHocInsert

Syntax

OnAdHocInsert(&stepinst, &approver)

Description

Use this method when new adhoc reviewers are inserted.

Parameters

OnAdHocDelete

Syntax

OnAdHocDelete(&stepinst)

Description

Use this method when an adhoc step is deleted.

Parameters

OnUserLocked

Syntax

OnUserLocked(&userinst)

Description

Use this method to indicate the action to be taken if a user is locked out. If a user is locked out, then the administrator should be notified. This acts more as a warning because the system will still route the approval to that person.

Parameters

OnStepRequestInformation

Syntax

OnStepRequestInformation(&userinst)

Description

Use this method when there is a request for information.

Parameters

OnRequestInformationAdded

Syntax

OnRequestInformationAdded(&appinst As EOAW_CORE:ENGINE:AppInst, &level As number, &notifyList As array of string);

Description

Use this method when request information has been added.

Parameters

ProcessNotifications

Syntax

ProcessNotifications(&appinst)

Description

Use this method to process notifications.

Parameters

OnLineTerminate

Syntax

OnLineTerminate(&appinst, &thread)

Description

Use this method when a line is terminated.

Parameters

ApprovalEventHandler Class Properties

This section lists the ApprovalEvent Hander Class properties.

wlPrefix

Description

Worklist prefix.

wlBusinessProc

Description

Business process.

wlActivityName

Description

Activity name.