AME B DeveloperGuide

1
2 Oracle
3 Approvals
4 Management
5 Developers Guide
6 RELEASE AME.B
7 May 2006
2 Oracle Approvals Management Developers Guide 1

1
1 Oracle Approvals Management Release R11i

2 Copyright © 2001, 2002, 2003, 2004 Oracle
3 Corporation. All rights reserved.
4 Contributors: Todd Morley, Nilakshi Soni, Bill Kerr
5 The Programs (which include both the software and
6 documentation) contain proprietary information of Oracle
7 Corporation; they are provided under a license agreement
8 containing restrictions on use and disclosure and are also
9 protected by copyright, patent and other intellectual property
10 law. Reverse engineering, disassembly or decompilation of the
11 Programs, except to the extent required to obtain
12 interoperability with other independently created software or
13 as specified by law, is prohibited.
14 Program Documentation is licensed for use solely to support
15 the deployment of the Programs and not for any other purpose.
16 The information contained in this document is subject to
17 change without notice. If you find any problems in the
18 documentation, please report them to us in writing. Oracle
19 Corporation does not warrant that this document is error free.
20 Except as may be expressly permitted in your license
21 agreement for these Programs, no part of these Programs may
22 be reproduced or transmitted in any form or by any means,
23 electronic or mechanical, for any purpose, without the express
24 written permission of Oracle Corporation.
25 If the Programs are delivered to the US Government or anyone
26 licensing or using the Programs on behalf of the US
27 Government, the following notice is applicable:
28 RESTRICTED RIGHTS NOTICE
29 Programs delivered subject to the DOD FAR Supplement are
30 ”commercial computer software” and use, duplication and
31 disclosure of the Programs, including documentation, shall be
32 subject to the licensing restrictions set forth in the applicable
33 Oracle license agreement. Otherwise, Programs delivered
34 subject to the Federal Acquisition Regulations are ”restricted
35 computer software” and use, duplication, and disclosure of the
36 Programs shall be subject to the restrictions in FAR 52.227-19,
37 Commercial Computer Software - Restricted Rights (June,
38 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City,
39 CA 94065.
40 The Programs are not intended for use in any nuclear, aviation,
41 mass transit, medical, or other inherently dangerous
42 applications. It shall be licensee’s responsibility to take all
43 appropriate fail-safe, back up, redundancy and other measures
44 to ensure the safe use of such applications if the Programs are
45 used for such purposes, and Oracle disclaims liability for any
46 damages caused by such use of the Programs.
47 The Programs may provide links to Web sites and access to
48 content, products, and services from third parties. Oracle is
49 not responsible for the availability of, or any content provided
50 on, third-party Web sites. You bear all risks associated with the
51 use of such content. If you choose to purchase any products or
52 services from a third party, the relationship is directly between
53 you and the third party. Oracle is not responsible for: (a) the
54 quality of third-party products or services; or (b) fulfilling any of
55 the terms of the agreement with the third party, including
56 delivery of products or services and warranty obligation related
57 to purchased products or services. Oracle is not responsible for
58 any loss or damage of any sort that you may incur from dealing
59 with any third party.
60 Oracle is a registered trademark and ConText, Enabling the
61 Information Age, Oracle7, Oracle8, Oracle8i, Oracle Access,
62 Oracle Application Object Library, Oracle HRMS, Oracle

1
1 Discoverer, Oracle Web Customers, Oracle Web Employees,

2 Oracle Workflow, Oracle Work in Progress, PL/SQL, Pro*C,
3 SmartClient, SQL*, SQL*Forms, SQL*Loader, SQL*Menu,
4 SQL*Net, SQL*Plus, and SQL*Reports are trademarks or
5 registered trademarks of Oracle Corporation. Other names
6 may be trademarks of their respective owners.
7

1
1Table of Contents
21
3Integrating AME into an Application..........................................................................6
4 Overview....................................................................................................................7
5 Audience ................................................................................................................7
6 Steps Required to Integrate AME into an Application..........................................7
7 AME Security.........................................................................................................8
8 Deciding how Many Transaction Types to Create.................................................8
9 Creating a Transaction Type..................................................................................8
102
11Building an Action Type.............................................................................................10
12 Overview..................................................................................................................11
13 Important – Changes from 11i9 version of AME.................................................11
14 Deciding Whether to Create an Action Type.......................................................11
15 Creating an Action Type......................................................................................12
16 Coding an Action-Type Handler..........................................................................13
17 Registering an Action Type..................................................................................24
18 Major changes in the Engine/ Handler Interface since R11i9..............................25
193
20Defining an Approver Type........................................................................................28
21 Overview .................................................................................................................29
22 Approver Types in AME......................................................................................29
23 Registering an Approver Type.............................................................................29
244
25Defining an Item Class...............................................................................................36
26 Overview..................................................................................................................37
27 When to Define an Item Class..............................................................................37
28 How to Define an Item Class...............................................................................37
295
30Integrating AME with Workflow................................................................................39
31 Overview..................................................................................................................40
32 Notifications.........................................................................................................40
33 The Basic Algorithm............................................................................................40
34 Modifications to the Basic Algorithm..................................................................41
35 Frequently Asked Questions................................................................................43
36 Sample Workflow.................................................................................................44
37Appendix A
38API Functional Specifications...................................................................................52
39 Overview .................................................................................................................53
40 Calling AME API Routines..................................................................................53
41 ame_api2 ........................................................................................................54
42 ame_api3..............................................................................................................68
43 ame_api4..............................................................................................................77
44 ame_api5..............................................................................................................78
1
1 ame_api6..............................................................................................................79
2 ame_api................................................................................................................80
3 What New APIs Map to the 11.5.9 APIs?............................................................86
4Appendix B
5ame_util and ame_util2 Packages..............................................................................88
6 Overview .................................................................................................................89
7 Data Types............................................................................................................89
8 ame_util................................................................................................................89
9 ame_util2............................................................................................................109
10Appendix C
11The Action-Type-Handler Programming Interface.................................................111
12 Overview ...............................................................................................................112
13 The ame_engine.engStApprovers Data Structure..............................................112
14 Engine Functions................................................................................................112
15 Engine Procedures..............................................................................................119
16Appendix D
17Sample AME Objects................................................................................................126
18 Overview ...............................................................................................................127
19 Transaction Type................................................................................................127
20
1
2 1
3 Integrating AME into
4 an Application
2 Integrating AME into an Application 6

1
1Overview
2 AME is a powerful application. It provides a great deal of flexibility for
3 creating the approvals processes an organization needs, usually without
4 writing any custom code. AME is highly extensible. If an organization has
5 special requirements that AME’s seeded functionality does not provide, one
6 can often write AME extensions that meet the organization’s requirements.
7Audience
8 This guide has two principle audiences:
9 1. Customer requiring additional Action Types to those supplied by
10 Oracle Corporation
11 2. Development team wishing to integrate AME into their own
12 application module
13 For the second audience it is normally expected that such a development
14 team would be part of the Oracle EBusiness Suite development. However, it
15 is possible that a customer may wish to provide approval management
16 capabilities to their own custom applications. It is for this reason that this
17 guide is supplied to customers.
18 For any Action Types that are not seeded or any Oracle Application module
19 that is not integrated with AME, please submit a request to your support
20 representative with a business case for this addition.
21 Your principle reference to AME is the Implementation Guide rather than
22 this Development Guide.
23 Steps Required to Integrate AME into an Application
24 1. Understand AME’s features and functionality. Study the AME
25 Implementation Guide carefully to understand the system’s various
26 intricacies.
27 2. Identify and document the types of approval processes that the
28 application’s customers typically require.
29 3. Determine how to configure AME to satisfy each of the requirements in
30 step two.
31 4. Document any requirements in step two that AME’s seeded functionality
32 does not satisfy.
33 5. Determine how to extend AME to satisfy the requirements in step four.
34 6. Define one or more transaction types for the application.

1
1 7. Build and test any AME extensions required by step five.
2 8. Integrate the application’s workflow with AME’s runtime APIs.
3 Note: The remainder of this guide assumes that you have studied the
4 implementation guide.
5AME Security
7 Inorder to access the new AME UI, a user should have one of the seeded,
8 responsibilities and roles assigned to him. The user should also have the
9 function(for doing operations on AME objects) and data grant(to restrict the
10 transaction types). For more details, please refer to the “chapter 2” in the
11 AME Implementation Guide.
12Deciding how Many Transaction Types to Create
13 An originating application always has at least one transaction type (by
14 definition). One of the main design decisions involved in integrating AME
15 into an originating application is deciding how many transaction types to
16 create for the application. Multiple transaction types may be necessary
17 whenever customers might have good business reasons to vary any of the
18 following, depending on the nature of a transaction generated by the
19 originating application:
20 • an attribute usage
21 • approvalprocess parallelization ordering numbers and modes that
22 are transactiontype specific
23 • an item class usage
24 • a configuration variable’s value(s)
25Creating a Transaction Type
26 1. To create a transaction type, follow these steps: Select the ” Approvals
27 Management Administrator” responsibility and click on “Admin
28 Dashboard” menu.
29 2. Click on “Create Transaction Type” button. Select the originating
30 application that will own the transaction type from the “Application,
31 Enter the transaction type’s description. (This should be a short, user
32 friendly description.) and Enter the transaction type’s ID. (This should
33 be an acronym, typically related to the originating application’s
34 Workflow item type. Click on “Next”.
35 3. In the “Create New Transaction Type: Item Classes” page, the header

1
1 item class usage is added for the transaction type by default. Enter the
2 “Order Number” and “Sublist Mode” details for this item class usage.
3 Click on “Go” button and give the details to add Usages for other item
4 classes. Click on “Next” to continue.
5 4. In the “Create New Transaction Type: Mandatory Attributes” page, enter
6 the relevant values for all the mandatory attributes and click on “Next”
7 to continue.
8 5. In the “Create New Transaction Type: Review” page, review all the
9 details and click on “Finish” button to create the transaction type.
10 6.
11 See Chapter 3 of the implementation guide to learn how to edit your
12 transaction type’s attribute usages.
13 See Chapter 11 of the implementation guide to learn how to edit your
14 transaction type’s configuration variables.

1
2 2
3 Building an Action
4 Type
2 Building an ActionType 10
1
1Overview
2 Note: Chapter 5 of the Oracle Approvals Management Implementation Guide
3 explains actions and action types. Please study that chapter carefully before
4 reading this one.
5 There are six categories of action type:
6 • chain of authority
7 • list–modification
8 • substitution
9 • preapproval
10 • postapproval
11 • production
12 An action type except for production category is implemented as a PL/SQL
13 package called an actiontype handler.
14Important – Changes from 11i9 version of AME
15 The engine/handler interface has changed in AME 11.5.10 / AME.A. As
16 such the old custom handlers created and used in AME 11.5.9 will have to be
17 modified before it can be called in AME 11.5.10.
18 Please review the section at the end of this chapter on changes to the handler
19 interface.
20Deciding Whether to Create an Action Type
21 The programming interface between the AME engine and actiontype
22 handlers has changed several times, and is likely to continue evolving. In
23 contrast, AME’s attribute and approvalgroup architecture is more stable.
24 These facts make custom action types more difficult to maintain than other
25 approaches to expressing an organization’s business rules in AME. Even
26 when you understand the actiontypehandler programming interface,
27 coding an actiontype handler that is both correct and efficient can be a
28 challenge. For these reasons, we encourage you to create a custom action
29 type only when you have no alternative.
30 To determine whether you need to create a custom action type, follow these
31 steps:
1
1 1. Review the seeded action types’ descriptions in Chapter 5 of the
2 implementation guide. Make sure you can’t express the approvals logic
3 you require with one or more existing action types.
4 2. If you need to use a hierarchy of approvers not supported by a seeded
5 action type, and the hierarchy does not exist outside AME, consider
6 using nested approval groups to create the approver hierarchy you need
7 in AME, and then using the approvalgroup chainofauthority action
8 type to generate chains of authority from the nested approval groups.
9 3. If you need to use an approver hierarchy that resides outside of AME
10 (say in the schema of an originating application), consider using dynamic
11 approval groups to access the hierarchy, and the approvalgroup chain
12 ofauthority action type to generate chains of authority from the dynamic
13 approval groups.
14 4. If the approvers you want to use reside in a hierarchy supported by an
15 AME action type, but their signing limits reside elsewhere, consider
16 defining an attribute whose dynamic usage indicates the number or
17 levels of approvers required, and referencing that attribute in your rules’
18 conditions. The rules’ actions would then be of an action type using the
19 supported approver hierarchy. For example, the custom attribute might
20 be TRANSACTION_SUPERVISORY_LEVELS. Its usage could fetch a
21 function that ascended the hierarchy until it found an approver with
22 sufficient signing authority, and then it could return the number of
23 approvers it ascended. The rules would then have the form,
24 If TRANSACTION_SUPERVISORY_LEVELS = 4 then
25 require approvals up to the first four supervisors.
26 5. If the above approaches don’t meet your needs, contact AME
27 development and request that we consider building the action type.
28 If none of the above approaches meets your needs, you may elect to build a
29 custom action type.
30 NOTE: AME development and Oracle Support offer best effort support for
31 custom action types.
32Creating an Action Type
33 Creating an action type takes five steps:
34 1. Identify the approver types that the action type is based on. (See Chapter
35 3 of this guide for details about approver types.)
36 2. Code the action type’s handler, and give the APPS account execute
37 privileges on it.
38 3. Register the action type in AME using the action typess tab and clicking
39 on “Use Existing Action Type” in the AME UI. Remember to create the
1
1 config for that action type in your transaction type to use it after
2 creating.
3 4. Create actions for the new action type. (See Chapter 5 of the
4 implementation guide for details.)
5 5. Test the action type. (See Chapter 10 of the implementation guide for
6 details.)
7 The remainder of this chapter explains how to do steps 2 and 3.
8Coding an ActionType Handler
9Defining Action Parameters
10 Most action types have several actions, and each action has a set of (zero, one,
11 or two) parameters defined for it. How the action type’s handler interprets
12 an action’s parameters varies with the action type. The parameters of an
13 authority action type’s actions typically represent requirements for certain
14 levels of authority, and the handler typically generates a chain of authority
15 satisfying the most stringent of such requirement. The parameters of
16 approver–group action types’ actions typically identify approval groups.
17 The parameters of list–editing actions represent specific types of alterations
18 to an approver list, for example changes that reflect non–uniformities in an
19 organization’s signing–authority rules.
20 Before you code your handler, you should define the syntax and semantics
21 rules for the parameters of your action type’s actions. The rules should make
22 it easy for your handler efficiently to sort, aggregate, and interpret the
23 parameters of several actions.
24Coding an Efficient Handler
25 AME may call your actiontype handler very frequently. Recall that list
26 modification and substitution rules apply to an entire transaction’s approver
27 list. As a result, AME’s engine invokes the handlers of the action types used
28 by these rules once per transaction. In contrast, The other rules types
29 (ignoring the production rule type) can apply to each item in a transaction’s
30 lists of subordinate items. AME’s engine may invoke the handlers of the
31 action types used by these rules once per item. So if, for example, a
32 transaction has 50 line items, AME’s engine may invoke an authority action
33 type’s handler 50 times for the transaction. If the originating application
34 generates 1,000 transactions of the same type per day, AME’s engine might
35 invoke the handler 50,000 times per day. So if the number of transactions
36 and items that use your action type may be substantial, it is critical that you
37 make your handler efficient.
38 Efficient PL/SQL architecture is far beyond the scope of this chapter. We
39 recommend you do at least three things to make your handler efficient:
1
1 1. Minimize the number of database queries your handler executes per
2 transaction using language features such as bulk fetches.
3 2. Tune your handler’s database queries.
4 3. Compare your handler’s asymptotic (long run) performance to that of
5 one of the seeded handlers.
6 In our experience, a test set of a few thousand transactions suffices to
7 measure asymptotic performance. Code a PL/SQL test procedure that
8 follows these steps:
9 1. Bulk fetch a set of several thousand testtransaction IDs into a local
10 PL/SQL table.
11 2. Loop through the testtransaction IDs, calling
12 ame_api2.getAllApprovers7 once for each ID, using
13 dbms_utility.get_time to measure the execution time to the nearest
14 hundredth of a second.
15 3. Calculate and output the mean execution time per transaction ID.
16 Set up your rules to use a seeded action type (and not use the action type
17 you’re testing), and run the test procedure. Then, change the rules using the
18 seeded action type to use your action type instead, and rerun the test
19 procedure. The results should be comparable.
20Programming Interface
21 Appendix C of this guide documents AME’s actiontypehandler
22 programming interface. Please review it carefully after reading this chapter.
23 Package Specification
24 Package Name
25 An actiontype handler’s package name should be of the form
26 ame_actionType_handler
27 where actionType suggests the name of the action type. For
28 example, if your handler ascended an approver custom hierarchy
29 called the “functional” hierarchy, the handler package could be
30 named ‘ame_functional_handler’.
31 EntryPoint Procedure
32 Each handler must have a public entrypoint procedure named
33 ‘handler’. The procedure should take no arguments. (The AME
34 engine calls the handler procedure to invoke the handler.) The
1
1 handler procedure should be the only public feature of your handler
2 package. Thus your entire package specification might be:
3 create or replace package ame_functional_handler as
4 procedure handler;
5 end ame_function_handler;
6 Package Body
7 An actiontype handler alters a transaction’s approver list in
8 response to a combination of requiredattribute values and action
9 parameter values. It should use AMEengine routines to fetch these
10 values as necessary (see Appendix C for details). AME’s
11 fundamental architectural principle is to encode in approval rules,
12 attribute usages, and configurationvariable values all decisions
13 about the general structure of a transaction’s approval process. While
14 writing an AME action–type handler, it is possible to violate this
15 principle by hardcoding business rules into the handler. Doing so
16 hides business logic from the end users whose responsibility it is to
17 define it, so please avoid the practice.
18 HandlerProcedure Architecture
19 There are three different kinds of actiontype handler architectures:
20 1. Authority handlers generate chains of authority for action types
21 used by listcreation and exception rules.
22 2. Approvalgroup handlers add approval groups to an approver
23 list for action types used by pre or postapproval rules.
24 3. Listediting handlers modify the approver list when a target
25 approver is in it, for action types used by listmodification or
26 substitution rules.
27 The following subsections describe the architecture appropriate for each type
28 of handler.
29 AuthorityHandler Architecture
30 An authority handler translates requiredattribute and action
31 parameter values into one or more chains of authority, either for a
32 given subordinate item, or for the header item. For each approver
33 that the handler adds to the item’s approver list, the handler must
34 populate all but one of the fields in the approver’s
35 ame_util.approverRecord2. (AME’s engine calculates the value of
36 the record’s approver_order_number field.) The handler procedure
37 should implement the following pseudocode to generate the chains
38 of authority:
1
1 1. Call ame_engine.getHandlerRules2 to fetch the applicable rules’
2 IDs and action parameters, and the approver categories that the
3 rule usages assign them.
4 2. Call one of the engine’s attributevaluefetching routines to fetch
5 any required attributes.
6 3. Analyze the action parameters to determine how many chains of
7 authority the rules require, and when to end each chain.
8 4. For each required chain, loop.
9 a. Fetch the chain’s first approver. Check for a nondefault
10 first approver identified by a required attribute (in
11 analogy with the
12 JOB_LEVEL_NON_DEFAULT_STARTING_POINT_PER
13 SON_ID attribute for the seeded absolutejoblevel action
14 type). Also check for an inserted first approver (by
15 calling ame_engine.getHandlerCOAFirstApprover). If
16 the required attribute has a nonnull value, it should
17 override the default value. An inserted starting point
18 should override all others.
19 b. Make the first approver the current approver.
20 c. Populate the approver’s ame_util.approverRecord2 and
21 add it to the engine’s approver list using
22 ame_engine.addApprover().
23 d. Check whether the current approver has final authority.
24 e. Try to fetch the chainofauthority insertion following
25 the current approver (by calling
26 ame_engine.getHandlerCOAInsertion).
27 f. If an insertion exists, make them the current approver
28 and go to step 4c
29 g. If final authority was found at step 4d, iterate at step 4.
30 h. Fetch the next approver in the chain of authority.
31 i. Make the next approver the current approver.
32 j. Go to step 4d.
33 Notes:
34 1. At step 3, you may eliminate duplicate action parameters, but if you do,
35 you should keep track of the IDs of all rules requiring a given parameter,
36 for use in populating each approver’s source field.
1
1 2. When a handler populates an approver’s ame_util.approverRecord2
2 fields at steps 4.a, 4.c, 4.e, and 4.h, it should follow the instructions in this
3 table:
Field Value
name, orig_system, The handler fetches these values at steps 4.a, 4.e,
orig_system_id and 4.h. The handler may start by fetching an
approver’s wf_roles.name value, and then use
ame_approver_type_pkg.
getOrigSystemIdAndDisplayName to fetch the
other fields’ values. Or, the handler may start
by fetching the approver’s orig_system_id value
(such as a per_all_people_f.person_id value),
and then use ame_approver_type_pkg.
getWfRolesNameAndDisplayName to fetch the
other values.
approver_category The handler calculates this value from data
returned by ame_engine.getHandlerRules2 in
step 1, depending on which rules require the
approver. The value is
ame_util.approvalApproverCategory if any of
the rule usages requiring the approver is this
value; otherwise the value is
ame_util.fyiApproverCategory.
api_insertion For rulegenerated approvers, the handler
should set this value to ame_util.oamGenerated.
For inserted approvers, the handler should set
this value to ame_util.apiAuthorityInsertion.
authority The handler should always set this value to
ame_util.authorityApprover.
approval_status The handler should call
ame_engine.getHandlerApprovalStatus once
per approver to fetch this value.
action_type_id The handler should call
ame_engine.getHandlerActionTypeId once per
handler cycle to fetch this value.
group_or_chain_id The handler should calculate this value by
setting it to once for the first chain it generates,
and incrementing the value once for each
iteration of the loop at step 4.
1
Field Value
occurrence The handler should call
ame_engine.getHandlerOccurrence once per
approver to fetch this value.
source For rulegenerated approvers, the source value
should be a list of the IDs of the rules requiring
the approver, separated by
ame_util.fieldDelimiter. In this case, you
should use ame_util.appendRuleIdToSource to
build a valid source value. For inserted
approvers, the ame_engine.
getHandlerCOAFirstApprover or
ame_engine.getHandlerCOAInsertion
procedure outputs the correct source value for
each inserted approver.
item_class The handler should call
ame_engine.getHandlerItemClassName once
per handler cycle to fetch this value.
item_id The handler should call
ame_engine.getHandlerItemId once per handler
cycle to fetch this value.
item_class_order_number The handler should call
ame_engine.getHandlerItemClassOrderNumber
once per handler cycle to fetch this value.
item_order_number The handler should call
ame_engine.getHandlerItemOrderNumber once
sub_list_order_number The handler should call
ame_engine.getHandlerSublistOrderNum once
action_type_order_numb The handler should call
er ame_engine.getHandlerActionTypeOrderNum
group_or_chain_order_n The handler should call ame_engine.
umber getActionTypeChainOrderMode once per
handler cycle to fetch the chainordering mode
of its action type. If the mode is
ame_util.serialChainsMode, the
1
Field Value
group_or_chain_order_number should have the
same value as the group_or_chain_id. If the
mode is ame_util. parallelChainsMode, the
group_or_chain_order_number should always
be one.
member_order_number The handler should call
ame_engine.getActionTypeVotingRegime once
per handler cycle to fetch the voting regime of
its action type. If the regime is
ame_util.consensusVoting or
ame_util.firstApproverVoting, the
member_order_number should always be one.
If the regime is ame_util.serializedVoting, the
member_order_number should be one for the
first approver in each chain, and should
increment at step 4.3.
approver_order_number The handler should leave this field null (AME’s
engine populates this field.)
1 You can help make your handler code efficient by reusing a
2 local ame_util.approverRecord2 variable for the current
3 approver, and calling the functions that return a constant value
4 for the handler’s cycle just once each at the start of the handler
5 cycle, to populate the constant fields of the currentapprover
6 record.
7 3. If the handler only needs to generate one chain of authority, eliminate the
8 loop at step 4, and simply do invidual steps contained 4 once.
9 ApproverGroupHandler Architecture
10 An approvalgroup handler translates requiredattribute and action
11 parameter values into one or more preapproval or postapproval
12 approval groups, either for a given subordinate item, or for the header
13 item. For each approver that the handler adds to the item’s approval list,
14 the handler must populate all but one of the fields in the approver’s
15 ame_util.approverRecord2. (AME’s engine calculates the value of the
16 record’s approver_order_number field.) The handler procedure should
17 implement the following pseudocode to generate the approval groups:
18 1. Call ame_engine.getHandlerRules to fetch the applicable rules’ IDs and
19 action parameters (which are the IDs of the approval groupsthat the rules
20 require), and the approver categories that the rule usages assign them.
21 2. Call one of the engine’s attributevaluefetching routines to fetch the
1
1 values of any required attributes.
2 3. Remove any duplicate approvergroup IDs from the list of action
3 parameters.
4 4. Fetch the required groups’ order numbers and ordering modes by calling
5 ame_engine.getApprovalGroupConfigs. (Note that this procedure sorts
6 the group IDs in place by group order number first, then by group ID.)
7 5. For each required approval group, loop.
8 a. Fetch the group’s membership by calling
9 ame_engine.getRuntimeGroupMembers.
10 b. For each approver returned by getRuntimeGroupMembers, loop
11 • Set the values of the fields of the approver’s
12 ame_util.approverRecord2.
13 • Call ame_engine.addApprover.
14 Notes:
15 1. At step 3, you may eliminate duplicate action parameters, but if you do,
16 you should preserve in your ruleID list the IDs of all the applicable
17 rules, for use in populating each approver’s source field.
18 2. When a handler populates an approver’s ame_util.approverRecord2
19 fields at step 5b, it should follow the instructions in this table:
Field Value
name, orig_system, The ame_engine.getRuntimeGroupMembers
orig_system_id procedure returns all of these values.
approver_category The handler calculates this value from data
returned by ame_engine.getHandlerRules2 in
step a, depending on which rules require the
approver. The value is
ame_util.approvalApproverCategory if any of
the rule usages requiring the approver is this
value; otherwise the value is
ame_util.fyiApproverCategory.
api_insertion The handler should always set this value to
ame_util.oamGenerated.
authority The handler should set this value to
ame_util.preApprover or
1
Field Value
ame_util.postApprover.
approval_status The handler should call
ame_engine.getHandlerApprovalStatus once
per approver to fetch this value.
action_type_id The handler should call
ame_engine.getHandlerActionTypeId once per
handler cycle to fetch this value.
group_or_chain_id The parameters returned by
ame_engine.getHandlerRules at step 1 are
approvergroup IDs. The loop at step 5 iterates
through the group IDs (typically after any
duplicates have been removed).
occurrence The handler should call
ame_engine.getHandlerOccurrence once per
approver to fetch this value.
source The source value should be a list of the IDs of
the rules requiring the approver, separated by
ame_util.fieldDelimiter. You should use
ame_util.appendRuleIdToSource to build a
valid source value.
item_class The handler should call
ame_engine.getHandlerItemClassName once
item_id The handler should call
ame_engine.getHandlerItemId once per handler
cycle to fetch this value.
item_class_order_number The handler should call
ame_engine.getHandlerItemClassOrderNumber
item_order_number The handler should call
ame_engine.getHandlerItemOrderNumber once
sub_list_order_number The handler should call
1
Field Value
ame_engine.getHandlerSublistOrderNum once
action_type_order_numb The handler should call
er ame_engine.getHandlerActionTypeOrderNum
group_or_chain_order_n The call to
umber ame_engine.getApprovalGroupConfigs at step
4 fetches each group’s order number.
member_order_number The call to
ame_engine.getApprovalGroupConfigs at step
4 fetches each group’s voting regime. If the
regime is ame_util.consensusVoting or
ame_util.firstApproverVoting, the
member_order_number should always be one.
If the regime is ame_util.serializedVoting, the
member_order_number should be the index of
the approver in the approverNamesOut output
argument of
ame_engine.getRuntimeGroupMembers. If the
regime is ame_util.orderNumberVoting, the
member_order_number should be the member
order number in the
approverOrderNumbersOut argument of
ame_engine.getRuntimeGroupMembers.
approver_order_number The handler should leave this field null (AME’s
engine populates this field.)
1 You can help make your handler code efficient by reusing a
2 local ame_util.approverRecord2 variable for the current
3 approver, and calling the functions that return a constant value
4 for the handler’s cycle just once each at the start of the handler
5 cycle, to populate the constant fields of the currentapprover
6 record.
7 ListEditingHandler Architecture
8 AME seeds three listediting handlers, one each to reduce an
9 approver’s authority, extend it, and substitute one approver for
10 another. The first two of these operations are for listmodification
11 rules, the third is for substitution rules. The architectural feature
12 these handlers share is, they all modify the approver list only when a
13 target approver appears in an appropriate context in the list. Here is
1
1 the basic algorithm:
2 1. Call ame_engine.getHandlerRules3 to fetch the list of applicable
3 rules.
4 2. Optionally sort the values returned by
5 ame_engine.getHandlerRules3 to eliminate duplicates and leave
6 the values in an order that is meaningful to your handler.
7 3. For each (remaining) row in the output variables of
8 ame_engine.getHandlerRules3, loop.
9 a. Call ame_engine.getHandlerLMApprovers to fetch the
10 approvers that match the current listmodification
11 condition.
12 b. For each row in the output variables of
13 ame_engine.getHandlerLMApprovers, loop.
14 c. Perform some operation on the approver list targeting
15 the approver identified by the current approver.
16 Notes:
17 1. Call ame_engine.substituteApprover to effect substitututions.
18 2. Call ame_engine.truncateChain to truncate a chain of authority
19 after a target approver.
20 3. If your handler extends a chain of authority, it should populate
21 the new approvers’ ame_util.approverRecord2 fields according
22 to note 2 under “AuthorityHandler Architecture” above.
23 4. Substituted approvers should have the same
24 ame_util.approverRecord2 field values as the approvers they
25 replace. The ame_engine.substituteApprover sets all of the fields
26 values; your handler code should not change any of them.
27 5. A listmodification handler that removes approvers from the
28 approver list should not change the ame_util.approverRecord2
29 fields of any remaining approvers.
30 PL/SQL Exceptions
31 Every routine in your handler should include an exception block. The
32 exception block should at least have a whenothers exception handler. The
33 last two statements in each exception handler for an unhandled exception
34 should always be a call to ame_util.runtimeException, followed by a raise
35 statement or raise_application_error call. In the latter case it is idiomatic in
36 AME coding to have the enclosing routine declare the local variables
37 errorCode integer;
1
1 errorMessage ame_util.longestStringType
2 and then begin your exception handler by setting these variables’
3 values. Then the last two statements in the exception handler
4 can reference these variables, rather than their values. The
5 following example illustrates both kinds of exception handlers:
6 exception
7 when jobLevelException then
8 errorCode := -20001;
9 errorMessage :=
10 ame_util.getMessage(
11 applicationShortNameIn => 'PER',
12 messageNameIn =>
13 AME_400448_AJHA_JOB_NOT_ASSD');
14 ame_util.runtimeException(
15 packageNameIn =>
16 'ame_absolute_job_level_handler',
17 routineNameIn => 'getJobLevelAndSupervisor',
18 exceptionNumberIn => errorCode,
19 exceptionStringIn => errorMessage);
20 raise_application_error(errorCode,
21 errorMessage);
22 when others then
23 ame_util.runtimeException(
24 packageNameIn =>
25 'ame_absolute_job_level_handler',
26 routineNameIn => 'getJobLevelAndSupervisor',
27 exceptionNumberIn => sqlcode,
28 exceptionStringIn => sqlerrm);
29 raise;
30Registering an Action Type
31 Once your handler is ready, you need to register it with AME using the
32 actions tab. Note that this tab requires administrative or developer
33 privileges.
34 To create an action type, follow these steps:
35 1. Select “Business Analyst Dashboard”and click on “Action Types” after
36 selecting your transaction type in the conten container.
37 2. Click on “Use Existing Action Type” to navigate to “Use Existing Action
38 Type: Select Action Types” page.
39 3. Click on “Create” button to navigate to the “Create New Action Type”
40 page.
41
42 For a dynamic Action Description, enter a dynamic action
43 description query. Such a query can refer the bind variables
44 “:parameterOne” and (for list editing action types)
1
1 “:parameterTwo”,which AME binds to an action’s parameter values.
2 For Example,
3 Select :parameterOne || ‘/’ || :parameterTwo from dual
4 might be a dynamic action description for a list modification action
5 type.
6 Enter all the relevant details and click on “Apply” to create the new
7 action type. Now create a config for this action type in your
8 transaction type(Using “Use Existing Action Type.) Here, you can
9 create actions for this action type using “Create” button.
10 See Chapter 5 of the implementation guide for additional information about
11 an action type’s properties and configuration values.
12
13
14Major changes in the Engine/ Handler Interface since R11i9
15 As discussed at the start of this chapter there has been some
16 major changes to the way custom action type handlers are
17 required to be coded. The conversion steps to move handlers
18 developed on R11i9 and earlier and preceeding the patchset
19 AME.A, that was released in early Dec 2005.
20
Step AME 11.5.9 AME 11.5.10 / AME.A
1. The handler has 3 public routines The handler has only one public routine
which are called by the engine. They which is called by the engine. It is:
are: getFirstApprover(), handler()
getNextApprover() and
hasFinalAuthourity()
2. The handler returns at most one The handler does not have any
approver back to the engine. arguments being passed IN or OUT.
3. No special routines needed to define Special callable engine routines are
the handler context. The relevant available to set handler context.
information is passed in as arguments.
4. The engine makes multiple calls to a The engine calls the handler once. All
handler in order to get all the approvers are processed by this one
approvers. call.
5. The approver recovered is of type The approver record is of type
ame_util.approverRecord ame_util.approverRecord2
6. The approver list being maintained by The approver list being maintained by
the engine is stored in public tables the engine is private and cannot be
which can be directly accessed by the directly accessed by the handler.
1
handler. Special callable engine routines are

defined to do this.
7. The approver record is passed between No serialization of the approver record
the handler and the engine after is necessary.
serialization.
8. The logic to identify the starting point The logic to identify the starting point
approver is embedded partly in the approver is part of the handler code
engine and partly in the handler. only.
9. The logic to take into account COA The logic to take into account COA
insertions resides in the engine. insertions resides in the handler.
10. The logic to identify surrogate The logic to identify surrogate
approvers resides in the handler. approvers resides in the approver type
object layer.
11. The handler transaction state needs to Temporary tables/ global engine
be maintained in temporary tables/ variables are not needed to maintain
global engine variables. transaction state. This can be done by
using private handler package
variables.
12. The rules which require the approver The rules which require the approver to
to be part of the approver list are not be part of the approver list are
accurately identified. All applicable accurately identified. Only rules which
rules are included in the source require the approver to be included in
column of the approver record. the approver list are mentioned in the
source column of the approver record.
13. The List Modification actions which The List Modification actions which
truncates the approver list actually truncates the approver list will either set
delete the approvers from the approver the approvers approver_category to
list. ame_util.fyiApproverCategory, if
possible or will set the approvers
approval_status to
ame_util.suppressedStatus.
14. The attribute The attribute
“ALLOW_REQUESTOR_APPROVA “ALLOW_REQUESTOR_APPROVA
L” is processed in the engine. L” is processed in the respective
handlers.
3 Environment to Migrate Custom Handler
4
5 The new custom handler code can be written and tested on an
6 AME 11.5.10 instance only. Hence it is recommended
7
8 • Upgrade a test instance to 11.5.10.
1
1 • Migrate/code the new custom handler on this

2 test instance
3 • System test the new custom handler on this test
4 instance
5 • Upgrade production instance to 11.5.10.
6 • Implement new custom handler on the
7 production instance
1
2 3
3 Defining an
4 Approver Type
2 Defining an Approver Type 28
1
1Overview
2 An approver type is any Workflow Directory Services originating system that
3 defines entities that can receive Workflow notifications requesting approval.
4 For example, the HRMS application exports employees from its
5 per_all_people_f table to the PER Directory Services originating system so an
6 HR employee can be an approver in AME.
7Approver Types in AME
8 For AME to use an approver type, it must be be registered with AME (not
9 merely Workflow Directory Services). Currently there is no user interface to
10 register an approver type. Rather, one must execute a set of SQL statements
11 that insert rows into the ame_approver_types and
12 ame_approver_type_usages tables, and you must customize several runtime
13 routines in AME code. (AME enhancement request 32767685 requests
14 eliminating the need to customize AME code when adding an approver
15 type.) If you need to use an approver type that AME does not yet seed, we
16 strongly encourage you to request that AME development release a patch
17 supporting the approver type, rather than registering it yourself.
18 Note: Unless AME development provides support for an approver type in
19 this fashion, you will have to modify an AME PL/SQL package each time
20 you patch AME. Oracle Support and AME development do not support
21 custom approver types other than through best effort.
22Registering an Approver Type
23 Registering an approver type takes four steps:
24 1. Code a PL/SQL procedure that AME users can invoke to query for
25 approvers of the new type.
26 2. Insert a row into ame_approver_types for the approver type.
27 3. Identify the action types that can use the new approver type. For each
28 such action type, insert a row into ame_approver_type_usages.
29 4. Update certain routines in ame_approver_type_pkg that AME uses at
30 runtime.
31 The rest of this chapter explains how to perform each of these steps.
32
33 Coding an ApproverQuery Procedure
34 AME’s user interface includes an approverquery wizard. AME uses the
35 wizard in various contexts where an end user must identify an approver, for
1
1 example while populating an approval group or creating a listmodification
2 condition. Each approver type registered with AME must provide an
3 approverquery procedure that the approverquery wizard can invoke. The
4 wizard can prompt end users to provide up to five query criteria (first name,
5 last name, etc.), which the wizard passes to the query procedure.
6 Procedure Signature
7 Procedure Name
8 The name of your approverquery procedure should have the
9 following form:
10 [approverType]ApproverQuery
11 where approverType suggests the approver type. For example,
12 ‘PER’ is the originating system for HR employees, so that the
13 approver type’s approverquery procedure is
14 ame_approver_type_pkg.perApproverQuery.
15 Argument List
16 Your approverquery procedure’s signature should be:
17 procedure approverTypeApproverQuery(
18 criterion1In in varchar2 default null,
23 excludeListCountIn in integer,
24 approverNamesOut out nocopy varchar2,
25 approverDescriptionsOut out nocopy varchar2);
26 At run time, the first five arguments contain the query criteria
27 that the end user entered or selected on the approverquery form
28 of the approverquery wizard. The integer excludeListCountIn
29 sets appropriately the the number of rows that the procedure
30 may output, to account for a set of excluded approvers known to
31 the approverquery wizard at run time. The two output
32 arguments identify approvers that match the query criteria.
33 Functionality
34 When you register your approver type with AME, you provide a
35 set of query criteria that the approverquery wizard should
36 present when an end user queries for approvers of your
37 approver type. The end user may leave any or all of these blank,
38 so that your procedure may receive null values in any
39 combination of its criterion[n]In arguments. The simplest way to
40 accommodate such null query criteria is to have your cursor
41 define a cursor that encapsulates your approver query. The
42 cursor’s argument list should match exactly the input argument
43 list of the query procedure. The cursor’s where clause should
1
1 accommodate null query criteria like this:
2 where
3 (criterion1In is null or
4 some_column like ‘%’ || criterion1In || ‘%’) and
5 (criterion2In is null or
6 some_column like ‘%’ || criterion2In || ‘%’) and . .
7 .
8 Your procedure should limit the number of rows it returns by
9 including the following line in its main cursor’s where clause:
10 rownum < 52 + rowsToExcludeIn
11 The approverquery wizard checks your procedure’s output
12 values for a set of approvers to exclude. This set has
13 rowsToExcludeIn members. So worst case, the set of approvers
14 that the approverquery wizard presents to the end user, after
15 filtering out the approvers to exclude, should have 50 approvers
16 in it. The value 52 lets the cursor return one row too many. Your
17 code should check for this condition and raise an exception, as
18 follows (assuming the procedure fetches the cursor into a local
19 approverNames variable):
20 if(approverNames.count - rowsToExcludeIn > 50) then
21 raise ame_util.tooManyApproversException;
22 approverNamesOut := null;
23 approverDescriptionsOut := null;
24 return;
25 end if;
26 If the cursor does not select too many rows, your procedure
27 should check that it returns at least one:
28 if(approverNames.count = 0) then
29 raise ame_util.zeroApproversException;
30 approverNamesOut := null;
31 approverDescriptionsOut := null;
32 return;
33 end if;
34 If the cursor selects an apprpriate number of rows, your
35 procedure should serialize the lists of approver names and
36 descriptions selected by the query, and return the serialized lists
37 in the procedure’s output arguments, like this:
38 ame_util.serializeApprovers(
39 approverNamesIn => approverNames,
40 approverDescriptionsIn => approverDescriptions,
41 maxOutputLengthIn =>
42 ame_util.longestStringTypeLength,
43 approverNamesOut => approverNamesOut,
44 approverDescriptionsOut => approverDescriptionsOut);
45Inserting a Row into ame_approver_types
46 Use the following insert statement to register the new approver type with
47 AME:
48 insert into ame_approver_types(
1
1 approver_type_id,
2 orig_system,
3 query_variable_1_label,
8 variable_1_lov_query,
13 query_procedure,
14 created_by,
15 creation_date,
16 last_updated_by,
17 last_update_date,
18 last_update_login,
19 start_date,
20 end_date)
21 values(
22 approverTypeId,
23 origSystem,
24 queryVariable1Label,
29 variable1LovQuery,
34 queryProcedure,
35 createdBy,
36 creationDate,
37 lastUpdatedBy,
38 lastUpdateDate,
39 lastUpdateLogin,
40 startDate,
41 endDate);
42 Below are descriptions of the values you must supply in the
43 above insert statement.
44 approverTypeId
45 To determine the appropriate approverTypeId value, execute the
46 following query:
47 select 1 + max(approver_type_id) from ame_approver_types;
48 origSystem
49 The origSystem value should be the wf_roles.orig_system value that
50 approvers of the new approver type have. You can view all of the
51 available orig_system values by executing the following query:
52 select distinct orig_system from wf_directory_partitions;
1
1 queryVariable[n]Label
2 If you want the approverquery wizard to present k query criteria for
3 your approver type, you must supply userfriendly labels for these
4 criteria in the first k queryVariable[n]Label columns, and null in the
5 remaining 5 – k queryVariable[n]Label columns. Each label may be
6 up to 50 bytes long.
7 variable[n]LovQuery
8 If you want the ith query criterion to be a select list,
9 variable[i]LovQuery should be an SQL query that returns the values
10 you want to appear in the select list. The query may be up to 4000
11 bytes long, and should not include a terminating semicolon. If
12 variable[I]LovQuery is null, the ith query criterion will be a text
13 entry input.
14 queryProcedure
15 This value should be the name of your query procedure. If the
16 procedure resides in a package, prepend the package name and a
17 period to the procedure’s name.
18 createdBy
19 This value should be the fnd_user.user_id value of the user that
20 inserts the row.
21 creationDate
22 Use sysdate for this value.
23 lastUpdatedBy
24 This value should be the same as the createdBy value.
25 lastUpdateDate
27 lastUpdateLogin
28 This value should be the same as the createdBy value.
29 startDate
31 endDate
32 The endDate value should be null.
1
1Identifying the Action Types that can use the new Approver Type
2 Once you have inserted a row into ame_approver_types for your approver
3 type, you must tell AME which custom action types may use the approver
4 type. Do not include seeded action types in your list. For each action type in
5 your list, follow these steps:
6 1. Select the action tab.
7 2. Select the action type on the list of action types.
8 3. Select the ‘Add Approver Types’ button at the bottom of the ‘Edit Action
9 Type’ form.
10 4. Select the new approver type from the ‘Approver Type’ select list, and
11 then select the ‘Add’ button.
12Updating ame_approver_type_pkg Runtime Routines
13 There are three runtime ame_approver_type_pkg routines that you must
14 modify to accommodate your new approver type. Be very careful not to alter
15 the existing code, and remember that you will have to repeat your additions
16 each time you install an AME patch. AME’s engine calls these procedures, so
17 your code should be as efficient as possible.
18 isASubordinate
19 The function ame_approver_type_pkg.isASubordinate returns true if the
20 approver possibleSubordApproverIn is a subordinate of the approver
21 approverIn (presumably within a common approver hierarchy), and false
22 otherwise. The function returns false by default. If your approver type does
23 not represent an organizational hierarchy, you do not need to modify the
24 procedure (because in this case no subordination relations exist among your
25 approver type’s approvers). Otherwise, you must modify the procedure so
26 that if the two input approvers belong to your approver type, the procedure
27 checks whether the one is a subordinate of the other.
28 getSuperior
29 The procedure ame_approver_type_pkg.getSuperior returns in superiorOut
30 the superior of the input approver approverIn, raising the procedure’s
31 noSurrogateException exception if no superior exists. The procedure raises
32 the exception by default, so if your approver type does not represent an
33 organizational hierarchy, you do not need to modify the procedure (because
34 in this case no subordination relations exist among your approver type’s
35 approvers). Otherwise, you must modify the procedure so that when the
36 input approver belongs to your approver type, the procedure returns the
37 input approver’s superior.
38 getSurrogate
39 The ame_approver_type_pkg.getSurrogate procedure outputs the surrogate
40 approver that AME should substitute for the unresponsive approver
1
1 identified by the procedure’s input arguments, raising the local exception
2 noSurrogateException if no surrogate exists. The procedure raises the
3 exception by default, so if your approver type does not admit surrogate
4 approver functionality, you do not need to modify the procedure.
5 Otherwise, you must modify the procedure so that when the input approver
6 belongs to your approver type, the procedure returns the input approver’s
7 surrogate.
8 The current way to identify surrogate approver is based on the orig_system
9 of the approver. If the approver is of type 'PER' and 'POSITION', then the
10 surrogate is the approvers manager/or the position which is one above the
11 current approvers position in the relevant hierarchy.
12
13
1
2 4
3 Defining an Item
4 Class
2 Defining an Item Class 36

1
1Overview
2 This chapter explains when and how to define an item class. You must have
3 the AME Developer responsibility to define an item class. See Chapter 8 of
4 the Oracle Approvals Management Implementation Guide for more
5 information about item classes.
6When to Define an Item Class
7 AME currently seeds item classes for a transaction’s header, line items, cost
8 centers, and project codes. Your originating application may recognize other
9 entities having a manytoone relation to a transaction. For example, your
10 application may divide a transaction’s cost among several entities of the same
11 kind. If you want to enable any of your transaction types to define attributes
12 for these entities, or to generate one approver list per entity, you should
13 define an AME item class for the entity.
14
15How to Define an Item Class
16 As an item class is associated with a transaction type, it can be created either
17 while creating a transaction type or while updating it. While creating the
18 transaction type as explained in chapter 1, in the “Create Transaction Type:
19 Item Classes” page, select “Create New” and click on “Go” button. Now
20 continue creating the transaction type. Both the transaction type as well as
21 the item class get created.
22

1

1
2 5
3 Integrating AME
4 with Workflow
2 Integrating AME with Workflow 39
1
1Overview
2 AME’s basic design imperative is to locate all approvals–related logic in a
3 single module, rather than having each application provide its own
4 approvals logic. This chapter explains how you can integrate AME into your
5 application’s Workflow processes.
7Notifications
8Information to Include in Notifications
9 AME’s APIs provide a variety of information you can include in the
10 notifications you send the approvers in a transaction’s approver list:
11 • whether the notification should be informational or should
12 request the approver’s approval
13 • which subordinate items require the approver’s attention
14 • which approval rules required that the approver receive the
15 notification
16 • which productions appy to the approver
17 • which productions apply to the transaction.
18 (See Appendix A for details.) Your application should interpret the
19 productions before presenting them to an end user in a notification.
20Encoding Responses to Notifications Requesting Approval
21 Appendix B’s description of the approval_status field of the
22 ame_util.approverRecord2 data type lists and describes the ame_util
23 constants your code may use to represent an approver’s response to a
24 notification requesting approval. If you try to pass any other approval_status
25 value to AME’s APIs, AME will raise an exception.
26The Basic Algorithm
27 Here is the basic algorithm that an application should implement in its
28 Workflow processes, to let AME manage the approval processes of a
29 transaction type that the application owns.
30 1. Call one of the ame_api2.getNextApprovers[n] procedures to get the
31 wf_role.name values of any approvers that currently require
32 notification, and to determine whether the transaction’s approval
33 process is complete.
1
1 2. If ame_api2.getNextApprovers[n] outputs the value
2 ame_util.booleanTrue in approvalProcessCompleteYNOut, stop (the
3 transaction is approved).
4 3. Notify any approvers output by ame_api2.getNextApprovers[n] at
5 step two above, and wait for a response from each approver who
6 must approve.
7 4. When an approver who must approve responds, communicate the
8 response to AME by calling ame_api2.updateApprovalStatus or
9 ame_api2.updateApprovalStatus2, and go to step one above.
10 Telling AME that an Approver has been Notified
11 Usually you should pass ame_util.booleanTrue in
12 flagApproversAsNotifiedIn. Otherwise you must update each notified
13 approver’s status to ame_util.notifiedStatus upon notifying the approver at
14 step three.
15Exception Handling
16 AME complies with the Workflow exceptionhandling model by raising all
17 runtime exceptions to the originating application’s Workflow processes,
18 without issuing a rollback. To clear an exception from a transaction’s
19 approvalprocess state in AME, you need to pass the status
20 ame_util.clearExceptionsStatus at step four in the basic algorithm. Note that
21 this only clears the transaction’s exception status within AME. It does not
22 affect the transaction’s status in its Workflow process.
23Modifications to the Basic Algorithm
24 There are several ways to enhance the basic algorithm. This section describes
25 some of them. To learn about other ways to enhance the basic algorithm,
26 review the API specifications in Appendix A.
27Handling Rejections
28 The basic algorithm does not terminate if one of the approvers rejects the
29 transaction. In the event of a rejection, you may wish to stop at step four to
30 make sure the algorithm terminates.
31Inserting Approvers into the Default Approver List
32 In the basic algorithm, your application does not determine the membership
33 of a transaction’s approver list. It leaves all such decisions to AME. If your
34 application needs to let an end user insert approvers into the approver list
35 that AME generates for a given transaction, modify the basic algorithm as
36 follows:
37 1. Call ame_api2.getAllApprovers[n] to get a transaction’s default
38 approver list.
1
1 2. Display the approver list to the end user. Include suppressed and
2 repeated approvers, but flag them as such (perhaps by greying out
3 their names).
4 3. Prompt the user to choose a location (index) in the approver list at
5 which to perform the insertion, or to stop.
6 4. If the user chooses to stop, stop.
7 5. Call ame_api3.getAvailableInsertions for that location.
8 6. Display the resulting list of available insertions.
9 7. Prompt the user to choose one of the available insertions.
10 8. Prompt the user to query for an approver to insert.
11 9. Call ame_api2.validateApprover to validate the approver chosen at
12 step seven above.
13 10. If the approver is invalid, go to step 8 above.
14 11. If the insertion type is ame_util.firstAuthority, call
15 ame_api2.setFirstAuthorityApprover to perform the insertion.
16 Otherwise, call ame_api3.insertApprover to perform the insertion.
17Suppressing Approvers in the Default Approver List
18 If your application needs to let an end user suppress approvers in the
19 approver list that AME generates for a given transaction, modify the basic
20 algorithm as follows:
21 1. Call ame_api2.getAllApprovers[n] to get a transaction’s default
22 approver list.
23 2. Display the approver list to the end user. (You don’t need to include
24 suppressed or repeated approvers, but you should track internally
25 the indexes of the approvers you display.)
26 3. Prompt the user to choose an approver to suppress, or to stop.
27 4. If the user chooses to stop, stop.
28 5. Call ame_api3.suppressApprover to suppress the approver.
29 6. Go to step one.
30Accounting for Unresponsive Approvers
31 You may wish to account for notification timeouts in your
32 application’s Workflow process. To do so, modify step three of the
33 basic algorithm by timing each notification. Modify step four to
34 catch timeouts as well as responses, and to pass
35 ame_util.noResponseStatus to ame_api2.updateApprovalStatus or
1
1 ame_api2.updateApprovalStatus2 in the event of an unresponsive
2 approver.
3Forcing an Approver who has Already Approved an Item to Approve it Again
4 If you want to force a single approver to reapprove an item they
5 have already approved, update the approver’s status to null.
6Frequently Asked Questions
7What does final (signing) authority mean in AME?
8 The basic algorithm only uses Workflow to send and receive
9 notifications. It does not use Workflow to determine which approver
10 has final or signing authority (in any sense). AME determines final
11 authority internally. Your application’s Workflow process knows
12 that a transaction has been approved when AME so indicates (at step
13 two of the basic algorithm).
14 AME can generate an approver list for each item in a transaction.
15 Each approver list can have several chains of authority. Each chain
16 of authority has at least one approver with final (signing) authority
17 (arriving at such an approver is how AME decides to end the chain).
18 So in general, no single approver has final authority for the overall
19 approver list. Furthermore, AME’s parallelapprovals functionality
20 makes it possible for an approver having signing authority to be
21 notified along with previous approvers in the chain of authority. So
22 the temporal order of notifications does not generally reveal which
23 approver is a final approver.
24Why call AME each time an approver responds to a notification requesting
25approval?
26 Calling ame_api2.getNextApprovers[n] each time an approver
27 responds to a notification requesting is natural in several ways.
28 1. It accounts for the possibility that a transaction’s approver list
29 will change during the transaction’s approval process. Several
30 phenomena can cause the approver list to change:
31 • An attribute value can change.
32 • A currency conversion rate can change.
33 • An organizational hierarchy can change.
34 • An approval group can change.
35 • The rules that apply to a transaction can change.
36 • The relevant transaction type’s configurationvariable
1
1 values can change.
2 • The relevant transaction type’s mandatoryattribute
3 values can change.
4 2. An approver may be unresponsive long enough for your
5 application to tell AME that the approver was unresponsive, in
6 which case AME will add the approver’s surrogate to the
7 approver list.
8 3. An approver may reject some but not all items, and AME may
9 stop those items’ approval processes while continuing the
10 approval processes of remaining items.
11 4. It checks for more approvers to notify at the exact moment when
12 their existence becomes likely.
13 5. It is efficient with respect to performance overhead in the sense
14 that the least upper bound on the number of different
15 approver_order_number values is the number of approvers, and
16 in the typical scenario (where each approver approves), the
17 number of approver responses is the same as the number of
18 approvers.
19 Does AME do transaction management?
20 AME does not perform any commits or rollbacks while responding
21 to an API call originating within a workflow. (Where necessary,
22 AME determines whether it has been called from within a workflow
23 by checking the value of the useWorkflow configuration variable.) If
24 the calling application does not use Workflow, the only transaction
25 management that AME performs at runtime is to commit inserts into
26 its exception log within autonomous transactions. Thus, if an
27 application integrates AME without using Workflow, it must commit
28 or rollback AME’s work within the code that calls AME’s APIs.
29Sample Workflow
30 This section explains how to implement the basic algorithm in Workflow.
31Overview
32 To implement the basic algorithm in Workflow, you need to do three things:
33 1. Create a Workflow item type to manage your transaction type’s
34 approval processes.
35 2. Create the following things within your item type:
36 • Create an item attribute of type text (say ‘Approver’) to
37 contain notification performer data.
1
1 • Create an item attribute of type text (say ‘Master Item
2 Key’) to contain the master process’ itemkey value.
3 • Create a lookup type (say ‘Approval Status’), and add to
4 it the approval_status values that your item type will
5 use. (See ‘Encoding Responses to Notifications
6 Requesting Approval’ above.)
7 • Create a message of type response (say ‘Response
8 Message’) by attaching the result to its result tab, with
9 the display name ‘Result’, the description ‘Response
10 Result’, and the lookup type ‘Approval Status’.
11 3. Create two processes, one each for master and detail. (See below
12 for details.)
13 4. Create a PL/SQL package whose procedures call AME’s API
14 routines on behalf of your Workflow.
15Workflow Processes
16 The master process essentially does the following:
17 1. Fetch the next approvers to notify (if any) using
18 ame_api2.getNextApprovers4.
19 2. For each approver fetched, spawn a child process.
20 3. Wait for a response from at least one child process to
21 continue.
22 4. When a child process receives a response, process the
23 response and go to step one above.
24 The child process essentially does the following:
25 1. Send a notification to the approver.
26 2. If the notification requests a response, wait for a
27 response from the approver.
28 3. When the response arrives, so indicate to the master
29 process.
30 The Master Process
31 The master process has four nodes. Here are descriptions of each
32 node:
33 Start Node
34 The first node is a standard function activity that simply marks the
35 start of the process.
1
1 Function WF_STANDARD.NOOP
2 Result Type none
3 Required yes
4 Prerequisite Activities none
5 Item Attributes Set by Function none
6 Item Attributes Retrieved by Function none
8 IsApprovalComplete Node
9 The second node fetches the next set of approvers (if any) by calling
10 your PL/SQL package’s wrapper procedure for
11 ame_api2.getNextApprovers4. The node also checks whether the
12 transaction’s approval process is complete. If the process is
13 incomplete, the node creates and starts a child process for each
14 approver requiring notification.
15 Function <package_name>.<procedure_name>
16 Result Type yes/no (determines whether the transaction is
17 completed or not)
18 Required yes
19 Prerequisite Activities none (initially none, subsequently waits
20 for the response from the notified approver at the third node)
23 The following pseudocode describes this node’s logic:
24 1. Call your ame_api2.getNextApprovers4 wrapper procedure
25 to get the next set of approvers to notify (if any).
26 2. If approvalProcessCompleteYN = ame_util.booleanTrue, end
27 the process.
28 3. Loop through the approvers returned at step one. Follow
29 these steps for each approver:
30 • A Create a child processes by calling
31 wf_engine.createProcess(
32 itemType => <itemType>,
33 itemKey => <childItemKey>,
1
1 process => <childProcessName>);
2 • B Set the item Approver attribute to the approver’s
3 wf_roles.name value by calling
4 wf_engine.SetItemAttrText(
7 aName => ‘Approver’,
8 aValue => <approver’s wf_roles.name>);
9 C - Set the item Master Item Key attribute to the
10 master item’s item key by calling
11 wf_engine.SetItemAttrText(
14 aName => ‘Master Item Key’,
15 aValue => <itemKey>);
16 D - Start the child processes by calling
17 wf_engine.StartProcess(
18 <itemType>,
19 <childItemKey>);
20 Each child process’ item key must be unique.
21 WaitforApproverResponse Node
22 The third node is a customized standard function activity that
23 waits for a response from the child processes.
24 Function WF_STANDARD.BLOCK
25 Result Type none
26 Required yes
27 Prerequisite Activities third node of child process (Get
28 Approver Response)
1
1 End Node
2 This is a standard function activity that marks the end of the
3 process.
5 Result Type none
6 Required yes
7 Prerequisite Activities node two, if result type = Y
10 The Child Process
11 Start Node
12 The start node is a standard function activity that marks the start
13 of the process.
14 Function WF_STANDARD.NOOP
15 Result Type none
16 Required yes
20 SendNotification Node
21 The sendnotification node is a standard notification activity that
22 notifies the approver.
23 Function none
24 Message response message
25 Result Type Approval Status
26 Required yes
28 Item Attributes Set by Function Set the performer attribute to
29 the approver’s wf_roles.name value.
1
2 GetApproverResponse Node
3 This activity node should call a procedure in your PL/SQL
4 package that gets the approver’s response, passes it to AME, and
5 then completes the master process’ waiting activity (its Wait for
6 Approver Response node).
7 Function <package_name>.<procedure_name>
8 Result Type none
9 Required yes
13 The following pseudocode describes this node’s logic:
14 1. Get approver attribute’s value by calling
15 wf_engine.GetItemAttrText(
18 aName => ‘Approver’);
19 2. Get the approver’s response notification response for the
20 above approver
21 3. Update the approver’s status calling
22 ame_api2.updateApprovalStatus or
23 ame_api2.updateApprovalStatus2.
24 4. Communicate the response to the master process’
25 waiting node by setting
26 masterItemKey := wf_engine.GetItemAttrText(
29 aName => 'Master Item Key');
30 and then calling
1
1 wf_engine.CompleteActivity(
3 itemKey => <masterItemKey>,
4 activity => <Wait for Approver Response>,
5 result => null);
6 End Node
7 This is a standard function activity that marks the end of the
8 process.
10 Result Type none
11 Required yes
1
1
2 Appendix A
3 API Functional
4 Specifications
2 Appendix A API Functional Specifications 52
1
1Overview
2 AME provides three runtime API packages. The ame_api2 package contains
3 routines that a typical workflow uses to process a typical approval process,
4 while ame_api3 contains ancillary routines. The ame_api package is
5 available for backwards compatibility only. If you are integrating AME into
6 your product for the first time, use ame_api2 and ame_api3 only. This
7 chapter explains how to call AME API routines.
8Calling AME API Routines
9Arguments
10 Many of AME’s API routines share certain arguments. Here are
11 brief descriptions of each.
12 applicationIdIn is the fnd_application.application_id value of
13 the originating application calling the AME API routine.
14 transactionTypeIn is a string up to 50 bytes long. It
15 distinguishes one transaction type from another, within a given
16 originating application. transactionIdIn is a string up to 50 bytes
17 long. It identifies a transaction within a transaction type. Its
18 value must not contain whitespace characters, and must not be
19 the character representation of a negative integer.
20 approverIn is an ame_util.approverRecord2 (or an
21 ame_util.approverRecord in ame_api) that represents an
22 approver.
23 For ame_api2 and ame_api3, the above four arguments always
24 appear at the top of a procedure’s input in the above order, when
25 they appear at all.
26 approvalProcessCompleteYNOut is an out parameter which
27 returns any of the following values.
28 ame_util2.completeFullyApproved This means that the
29 approval process is complete and the transaction is approved.
30 ame_util2.completeFullyRejected –This means that the approval
31 process is complete and the transaction is rejected,
32 ame_util2.completePartiallyApproved – This means that the
33 approval process is completed but the transaction is partially
34 approved/rejected.
35 ame_util2.completeNoApprovers – This means that there are no
36 approvers for this transaction.
1
1 ame_util2.notCompleted – This means that the transaction is not
2 yet completed and still in progress.
3Passing Arguments by Name
4 Always pass arguments by name to AME’s APIs. This lets AME
5 development add defaultnull arguments to an API routine
6 without breaking preexisting code that references the routine.
7Approver Comparisons
8 When AME must determine whether two
9 ame_util.approverRecord2 records represent the same
10 occurrence of an approver in a given transaction’s approver list,
11 it compares the following fields:
12 • item_class
13 • item_id
14 • name
15 • action_type_id
16 • group_or_chain_id
17 • occurrence.
18 The two records represent the same occurrence of the approver if
19 and only if all of these fields have the same values.
20
21 ame_api2
22 validateApprover
23 Syntax
24 function validateApprover(
25 approverIn in ame_util.approverRecord2)
26 return boolean;
27 Description
28 The validateApprover function returns true if the approver
29 represented by approverIn has a current wf_roles entry,
30 otherwise returns false. Use this API to check whether an
31 ame_util.approverRecord2 that your application generates is
32 valid, especially before passing an ame_util.approverRecord2 to
33 an AME API routine. (AME always validates approvers before
34 returning them via its APIs, so your code need not do so)
1
1 clearAllApprovals
2 Syntax
3 procedure clearAllApprovals(
4 applicationIdIn in number,
5 transactionTypeIn in varchar2,
6 transactionIdIn in varchar2);
7 Description
8 The clearAllApprovals procedure clears a transaction’s approval
9 process state. Restores the default approver list (removing
10 approver insertions, suppressions, forwardings, etc.). Use this
11 API to restart a transaction’s approval process from scratch,
12 undoing any operations that have already modified the approval
13 process.
14 getAdminApprover
15 Syntax
16 procedure getAdminApprover(
19 adminApproverOut out nocopy
20 ame_util.approverRecord2);
21 Description
22 The getAdminApprover procedure outputs in
23 adminApproverOut an ame_util.approverRecord2 representing
24 the input transaction type’s administrative approver. An
25 originating application may wish to notify this approver when
26 AME raises an exception.
27 getAllApprovers1
28 Syntax
29 procedure getAllApprovers1(
32 transactionIdIn in varchar2,
33 approvalProcessCompleteYNOut out varchar2,
34 approversOut out nocopy ame_util.approversTable2,
35 itemIndexesOut out nocopy ame_util.idList,
36 itemClassesOut out nocopy ame_util.stringList,
37 itemIdsOut out nocopy ame_util.stringList,
38 itemSourcesOut out nocopy
39 ame_util.longStringList);
40 Description
41 The getAllApprovers1 procedure Outputs in approversOut a
42 transaction’s current approver list, including both rule–
1
1 generated and inserted approvers. The approvers’ indexes in
2 approversOut are consecutive ascending integers starting at one.
3 The order induced by the indexes is consistent with the ordering
4 inducd by the approvers’ approver_order_number values (which
5 AME’s parallelapprovalprocess functionality generates). The
6 approvers’ approval_status values reflect the approvers’ latest
7 responses to requests for approvals, assuming the originating
8 application has communicated such responses to AME via
11 If approvalProcessCompleteYNOut is ame_util.booleanTrue, the
12 transaction’s approval process is complete; otherwise it is
13 incomplete. If an approver’s item_id value is null, several items
14 require the approver. If such an approver is at index i in
15 approversOut, and itemIndexesOut(j) = i, then itemIdsOut(j) is
16 the ID of an item requiring the approver, itemClassesOut(i) is the
17 item’s item class, and itemSourcesOut(j) is the source field
18 indicating which rules required the approver for the same item.
19 (There will be at least two such entries in itemIndexesOut,
20 itemIdsOut, itemClassesOut, and itemSourcesOut, for an
21 approver in approversOut required by multiple items.)
22 Use this API to fetch and display the entire approver list, either
23 for information or to prompt for approver insertions or
24 suppresions. Do not use getAllApprovers1 by calling it, storing
25 its output approver list, and then iterating through that list in
26 your application. Doing so would risk inaccuracies in the
27 approver list introduced by changes in transaction values,
28 organizational structures, approval rules, etc.
29 GetAllApprovers2
30 Syntax
40 itemSourcesOut out nocopy ame_util.longStringList,
41 productionIndexesOut out nocopy ame_util.idList,
42 variableNamesOut out nocopy ame_util.stringList,
43 variableValuesOut out nocopy ame_util.stringList);
44 Description
45 The getAllApprovers2 procedure has the same functionality as
46 getAllApprovers1, but it also returns perapprover productions
47 stored in variableNamesOut and variableValuesOut. Several
48 productions can be assigned a single approver, so
49 productionIndexesOut contains for each production the index of
1
1 the approver in approversOut to which the production is
2 assigned. That is, if productionIndexesOut(i) = j, then the
3 production in variableNamesOut(i) and variableValuesOut(i) is
4 assigned to approversOut(j). Use getAllApprovers2 as you
5 would getAllApprovers1, when you need to display per
6 approver productions with the approvers. See also
7 ame_api2.getAllApprovers1.
8 getAllApprovers3
9 Syntax
22 variableValuesOut out nocopy ame_util.stringList,
23 transVariableNamesOut out nocopy
24 ame_util.stringList,
25 transVariableValuesOut out nocopy
26 ame_util.stringList);
27 Description
29 getAllApprovers2, but it also returns pertransaction
30 productions. Use getAllApprovers3 as you would
31 getAllApprovers2, when you need to display pertransaction
32 productions as well as the approver list. See also
33 ame_api2.getAllApprovers1 and ame_api2.getAllApprovers2.
34 getAllApprovers4
35 Syntax
45 itemSourcesOut out nocopyame_util.longStringList,
46 ruleIndexesOut out nocopy ame_util.idList,
47 sourceTypesOut out nocopy ame_util.stringList,
48 ruleIdsOut out nocopy ame_util.idList);
1
1 Description
3 getAllApprovers1, but it also classifies the approvers in
4 approversOut according to the reasons for their occurrence in the
5 approver list. When one or more rules require an approver,
6 ruleIdsOut identifies the rules. More particularly: every
7 approver in approversOut has at least one row in
8 ruleIndexesOut, sourceTypesOut and ruleIdsOut. If
9 ruleIndexesOut(i) = j, then the values in sourceTypesOut(i) and
10 ruleIdsOut(i) pertain to the approver in approversOut(j). Every
11 approver in approversOut has only one source value, no matter
12 how many rules required the approver. That is, if
13 ruleIndexesOut(i1) = j and ruleIndexesOut(i2) = j for i1 ¹ i2,
14 sourceTypesOut(i1) = sourceTypesOut(i2). Some source values
15 indicate that an approver is not required by any rules, but is
16 present for other reasons. In such cases, if the approver is at
17 index i, then if sourceTypesOut(j) = i, then ruleIdsOut(j) = null.
18 Use getAllApprovers4 when you need to display the approver
19 list, along with the rules requiring each approver. See also
20 ame_api2.getAllApprovers1. Note that getAllApprovers4
21 requires significantly more performance overhead than some of
22 its sibling getAllApprovers[n] procedures.
23 getAllApprovers5
24 Syntax
37 ruleDescriptionsOut out nocopy
39 Description
41 getAllApprovers4, but it returns rule descriptions rather than
42 rule IDs. See also ame_api2.getAllApprovers4.
43 getAllApprovers6
44 Syntax
1
10 ruleIdsOut out nocopy ame_util.idList,
11 ruleDescriptionsOut out nocopy
13 Description
15 getAllApprovers4, but it returns both rule IDs and rule
16 descriptions. See also ame_api2.getAllApprovers4.
17 getAllApprovers7
18 Syntax
24 approversOut out nocopy ame_util.approversTable2);
25 Description
27 getAllApprovers1, but omitting the peritem outputs. This is the
28 lowestoverhead getAllApprovers[n] procedure. See also
30 getAllItemApprovers
31 Syntax
32 procedure getAllItemApprovers1(
36 itemClassIdIn in number,
37 itemIdIn in varchar2,
39 approversOut outnocopy ame_util.approversTable2);
40 Description
41 The getAllItemApprovers1 procedure has the same functionality
42 as getAllApprovers1, but for the single item with ID itemIdIn of
43 the item class with the ID itemClassIdIn. See also
1
2 getAllItemApprovers2
3 Syntax
4 procedure getAllItemApprovers2(
8 itemClassNameIn in varchar2,
12 Description
13 The getAllItemApprovers2 procedure has the same functionality
14 as getAllItemApprovers1, but it identifies the input item class by
15 name in itemClassNameIn. See also ame_api2.getAllApprovers1
16 and ame_api2.getAllItemApprovers1.
17 getAndRecordAllApprovers
18 Syntax
19 procedure getAndRecordAllApprovers(
27 itemSourcesOut out nocopy
29 Description
30 The getAndRecordAllApprovers procedure has the same
31 functionality as getAllApprovers1, but it also updates the state of
32 the transaction’s approval process in AME (in particular
33 accounting for any approver insertions or suppressions made via
34 the API since the last AME engine cycle). You can call this API
35 to make sure AME has accounted for an approver insertion or
36 suppression before calling ame_api3.getOldApprovers.
37 Otherwise, calling getAndRecordAllApprovers is generally not
38 necessary. See also ame_api2.getAllApprovers1.
39 getItemStatus1
40 Syntax
41 procedure getItemStatus1(
1
2 itemClassIdIn in integer,
4 approvalProcessCompleteYNOut out varchar2);
5 Description
6 The getItemStatus1 procedure outputs the status of the approval
7 process of the item identified by itemIdIn of the item class
8 identified by itemClassIdIn for the input transaction. If
9 approvalProcessCompleteYNOut is ame_util.booleanTrue, the
10 item has been approved; otherwise the item’s approval process is
11 incomplete.
12 getItemStatus2
13 Syntax
14 procedure getItemStatus2(
20 approvalProcessCompleteYNOut out varchar2);
21 Description
22 The getItemStatus2 procedure outputs the status of the approval
23 process of the item identified by itemIdIn for the item class
24 identified by its name in itemClassNameIn. See also
25 ame_api2.getItemStatus1.
26 getItemStatuses
27 Syntax
28 procedure getItemStatuses(
32 itemClassNamesOut out nocopy ame_util.stringList,
34 approvalProcessesCompleteYNOut out nocopy
35 ame_util.charList);
36 Description
37 The getItemStatuses procedure outputs the statuses of the
38 approval processes of the input transaction’s items. If
39 approvalProcessesCompleteYNOut(i) is ame_util.booleanTrue,
40 the item with ID itemIdsOut(i) of the item class
41 itemClassNamesOut(i) has been approved; otherwise the item’s
42 approval process is incomplete.
1
1 getNextApprovers1
2 Syntax
3 procedure getNextApprovers1(
7 flagApproversAsNotifiedIn in varchar2 default
8 ame_util.booleanTrue,
10 nextApproversOut out nocopy
11 ame_util.approversTable2,
15 itemSourcesOut out nocopy ame_util.longStringList)
16 Description
17 The getNextApprovers1 procedure outputs in
18 nextApproversOut the approvers requiring notification for the
19 current stage of the input transaction’s approval process. Once
20 an originating application updates an approver’s status to
21 ame_util.notifiedStatus, getNextApprovers1 excludes the
22 approver from nextApproversOut. An originating application
23 can update an approver’s status to ame_util.notifiedStatus by
24 passing ame_util.booleanTrue as flagApproversAsNotifiedIn to
25 a call to getNextApprovers1 that includes the approver in
26 nextApproversOut. Or the originating application can pass
27 ame_util.booleanFalse in flagApproversAsNotifiedIn, and
28 instead call updateApprovalStatus or updateApprovalStatus2 to
29 update the approver’s status independently of a call to
30 getNextApprovers.
31 (See getAllApprovers1 above for an explanation of
32 itemIndexesOut, itemClassesOut, itemIdsOut, and
33 itemSourcesOut.) Use getNextApprovers1 to iterate through a
34 transaction’s approval process one stage at a time. See also
36 getNextApprovers2
37 Syntax
1

6 Description
7 The getNextApprovers2 procedure has the same functionality as
8 as getNextApprovers1, but it also returns perapprover
9 productions. Use getNextApprovers2 to iterate through a
10 transaction’s approval process one stage at a time when your
11 application enables perapprover productions, for example to
12 track perapprover eSignature requirements. See also
13 ame_api2.getAllApprovers2 and ame_api2.getNextApprovers1.
15 Syntax

32 variableValuesOut out nocopy ame_util.stringList,
33 transVariableNamesOut out nocopy
35 transVariableValuesOut out nocopy
37 Description
39 getNextApprovers2, but it also returns pertransaction
40 productions. Use getNextApprovers3 when your application
41 enables perapprover and pertransaction productions, for
42 example to track eSignature requirements per approver and
43 transaction. See also ame_api2.getAllApprovers3 and
44 ame_api2.getNextApprovers2.
46 Syntax
1
8 ame_util.approversTable2);
9 Description
11 getNextApprovers1, but it omits peritem outputs. This is the
12 lowestoverhead getNextApprovers[n] procedure. See also
13 ame_api2.getAllApprovers7 and ame_api2.getNextApprovers1.
14 getPendingApprovers
15 Syntax
16 procedure getPendingApprovers(
22 Description
23 The getPendingApprovers procedure outputs in approversOut
24 the approvers with approver_category
25 ame_util.approvalApproverCategory and approval_status
26 ame_util.notifiedStatus. These are the approvers who must
27 approve before the input transaction’s approval process will
28 continue to the next stage. If approvalProcessCompleteYNOut is
29 ame_util.booleanTrue, the transaction’s approval process is
30 complete. If approvalProcessCompleteYNOut is
31 ame_util.booleanFalse and approversOut.count is zero, the
32 application should call one of the getNextApprovers[n]
33 procedures, and notify the approvers returned by that
34 procedure.
35 getTransactionProductions
36 Syntax
37 procedure getTransactionProductions(
43 Description
44 The getTransactionProductions procedure outputs all per
1
1 transaction productions for the input transaction. Use this API
2 when your application uses AME as a generalpurpose
3 productionrule engine. See also ame_api2.getAllApprovers3.
4 initializeApprovalProcess
5 Syntax
6 procedure initializeApprovalProcess(
10 recordApproverListIn in boolean default false);
11 Description
12 The initializeApprovalProcess procedure causes AME’s engine to
13 prepare a transaction’s approval process, if it has not already
14 done so. In particular, the engine sets the approval process’ start
15 date to sysdate. This API does not clear the state of the approval
16 process; use clearAllApprovals for that. When
17 recordApproverListIn is true, this API has the same effect as
18 getAndRecordAllApprovers. Calling initializeApprovalProcess
19 guarantees that subsequent calls to getAllApprovers1 will be
20 read only.
21 setFirstAuthorityApprover
22 Syntax
23 procedure setFirstAuthorityApprover(
27 approverIn in ame_util.approverRecord2,
28 clearChainStatusYNIn in varchar2);
29 Description
30 The setFirstAuthorityApprover procedure sets the approver
31 represented by approverIn as the first chainofauthority
32 approver in the chain of authority identified by the
33 action_type_id and group_or_chain_id fields of approverIn. This
34 procedure succeeds only if the approval_status field of
35 approverIn is null, and all the approvers in the target chain of
36 authority also have null approval statuses. If
37 clearChainStatusYNIn is ame_util.booleanTrue, AME clears the
38 target chain of authority’s approval status before making
39 approverIn the chain’s new first approver. Use this API to force
40 AME to generate a chain of authority that satisfies a given set of
41 rules, but that starts from an unusual first approver.
1
1 updateApprovalStatus
2 Syntax
3 procedure updateApprovalStatus(
8 forwardeeIn in ame_util.approverRecord2 default
9 ame_util.emptyApproverRecord2,
10 updateItemIn in boolean default false);
11 Description
12 The updateApprovalStatus procedure updates the approval
13 status of the approver identified by approverIn to
14 approverIn.approval_status. If the approvalstatus value
15 indicates that the approver forwarded (with or without
16 approving), forwardeeIn identifies the forwardee. If the
17 approval_status value is ame_util.clearExceptionsStatus, the
18 procedure clears the transaction’s exception log in AME without
19 changing any approver’s status, regardless of the approver
20 identified by approverIn. When a chainofauthority approver
21 forwards, the forwardee is also a chain–of–authority approver.
22 Otherwise, the forwardee has the api_insertion value
23 ame_util.apiInsertion, and the same authority value as the
24 forwarder. Use this API to update the state of a transaction’s
25 approval process when an approver responds to a notification
26 requesting approval.
27 updateApprovalStatus2
28 Syntax
29 procedure updateApprovalStatus2(
33 approvalStatusIn in varchar2,
34 approverNameIn in varchar2,
35 itemClassIn in varchar2 default null,
36 itemIdIn in varchar2 default null,
37 actionTypeIdIn in number default null,
38 groupOrChainIdIn in number default null,
39 occurrenceIn in number default null,
41 ame_util.emptyApproverRecord2);
42 Description
43 The updateApprovalStatus2 procedure has the same
44 functionality as updateApprovalStatus, but it lets you identify
45 the target approver by their wf_roles.name value, and as many
46 other approverdistinguishing ame_util.approverRecord2 fields
47 as you care to specify. When you leave one or more of the fields
1
1 null, AME matches updates the status of the first occurrence of
2 the approver having an approval status that does not indicate
3 approval or forwarding. See also
4 ame_api2.updateApprovalStatus.
5 updateApprovalStatuses
6 Syntax
7 procedure updateApprovalStatuses(
12 approvalStatusesIn in ame_util.stringList default
13 ame_util.emptyStringList,
14 itemClassesIn in ame_util.stringList default
16 itemIdsIn in ame_util.stringList default
18 forwardeesIn in ame_util.approversTable2 default
19 ame_util.emptyApproversTable2);
20 Description
21 The updateApprovalStatuses procedure is currently a stub, and
22 has no present functionality. Do not use it.
23 updateApprovalStatuses2
24 Syntax
25 procedure updateApprovalStatuses2(
37 approvalStatusesIn in ame_util.stringList default
39 itemClassesIn in ame_util.stringList default
41 itemIdsIn in ame_util.stringList default
43 forwardeesIn in ame_util.approversTable2 default
44 ame_util.emptyApproversTable2);
45 Description
46 The updateApprovalStatuses2 procedure is currently a stub, and
47 has no present functionality. Do not use it.
1
3ame_api3
4 getRuleDescription
5 Syntax
6 function getRuleDescription(
7 ruleIdIn in varchar2)
8 return varchar2;
9 Description
10 The getRuleDescription function returns the description of the
11 rule with ID ruleIdIn. Rule descriptions are at most 100 bytes
12 long.
13 clearSuppression
14 Syntax
15 procedure clearSuppression(
19 approverIn in ame_util.approverRecord2);
20 Description
21 The clearSuppression procedure clears an approver suppression
22 previously submitted by a call to suppressApprover or
23 suppressApprovers, as long as approverIn is an AME generated
24 approver. Use this API to reactivate an AMEgenerated
25 approver who has been suppressed from the input transaction’s
26 approver list. See also ame_api3.suppressApprover and
27 ame_api3.suppressApprovers.
28 clearSuppressions
29 Syntax
30 procedure clearSuppressions(
34 Description
35 The clearSuppressions procedure has the effect of
36 clearSuppression for all suppressed AMEgenerated approvers.
1
1 See also ame_api3.suppressApprover,
2 ame_api3.suppressApprovers, and ame_api3.clearSuppression.
3 clearInsertion
4 Syntax
5 procedure clearInsertion(
10 Description
11 The clearInsertion procedure removes the input approver from
12 the input transaction’s approver list. Use this API to remove an
13 inserted approver from a transaction’s approver list.
14 clearInsertions
15 Syntax
16 procedure clearInsertions(
20 Description
21 The clearInsertions procedure has the effect of clearInsertion for
22 all inserted approvers in the input transaction’s approver list.
23 Use this API to remove all previously inserted approvers from a
24 transaction’s approver list. See also ame_api3.clearInsertion.
25 getAllApprovalGroups
26 Syntax
27 procedure getAllApprovalGroups(
28 groupIdsOut out nocopy ame_util.idList,
29 groupNamesOut out nocopy ame_util.stringList);
30 Description
31 The getAllApprovalGroups procedure outputs all current AME
32 approval groupsin ascending order of their names.
33 getApplicableRules1
34 Syntax
35 procedure getApplicableRules1(
1
3 Description
4 The getApplicableRules1 procedure outputs in ruleIdsOut the
5 IDs of the rules that apply to the input transaction. Use this API
6 when you only need the rule IDs. See also
7 ame_api3.getApplicableRules2 and getApplicableRules3.
9 Syntax
14 ruleDescriptionsOut out nocopy ame_util.stringList);
15 Description
16 The getApplicableRules2 procedure outputs in
17 ruleDescriptionsOut the descriptions of the rules that apply to
18 the input transaction. Use this API when you only need the rule
19 descriptions. See also ame_api3.getApplicableRules1 and
20 ame_api3.getApplicableRules3.
22 Syntax
28 ruleDescriptionsOut out nocopy ame_util.stringList);
29 Description
30 The getApplicableRules3 procedure outputs in ruleIdsOut and
31 ruleDescriptionsOut the IDs and descriptions of the rules that
32 apply to the input transaction. This procedure is useful to
33 construct a displayable list of descriptiosn of applicable rules,
34 where each rule description hyperlinks to a more detailed
35 description of the rule (generated by one of the
1
1 ame_api3.getRuleDetails[n] procedures). See also
2 ame_api3.getApplicableRules1, ame_api3.getApplicableRules1,
3 and the three ame_api3.getRuleDetails[n] procedures.
4 getApprovalGroupId
5 Syntax
6 procedure getApprovalGroupId(
7 groupNameIn ame_util.stringType,
8 groupIdOut out nocopy number);
9 Description
10 The getApprovalGroupId procedure outputs in groupIdOut the
11 ID of the approval group with the name groupNameIn.
12 getAttributeValue
13 Syntax
14 procedure getAttributeValue(
18 attributeNameIn in varchar2,
20 attributeValue1Out out varchar2,
21 attributeValue2Out out varchar2,
22 attributeValue3Out out varchar2);
23 Description
24 The getAttributeValue procedure outputs in attributeValue1Out,
25 attributeValue2Out, and attributeValue3Out the values of the
26 attribute with the name attributeNameIn for the item with ID
27 itemIdIn, for the input transaction. An attribute is always
28 associated with an item classes, and attribute names are unique
29 across item classes; so it is not necessary to input the item class.
30 If the attribute pertains to the header item class, itemIdIn should
31 have the same value as transactionIdIn. For all attribute types
32 other than currency attributes, attributeValue1Out contains the
33 attribute’s value, and attributeValue2Out and
34 attributeValue3Out are null. For currency attributes,
35 attributeValue1Out is the amount, attributeValue2Out is the
36 General Ledger currency code, and attributeValue3Out is the
37 General Ledger conversion type.
38 Note: Do not call this api from within a function which is likely
39 to be called from an attribute which could itself be interrogated
40 by the called function otherwise a loop condition will exist.
1
1 getConditionDetails
2 Syntax
3 procedure getConditionDetails(
4 conditionIdIn in number,
5 attributeNameOut out nocopy varchar2,
6 attributeTypeOut out nocopy varchar2,
7 attributeh4 DescriptionOut out nocopy varchar2,
8 lowerLimitOut out nocopy varchar2,
9 upperLimitOut out nocopy varchar2,
10 includeLowerLimitOut out nocopy varchar2,
11 includeUpperLimitOut out nocopy varchar2,
12 currencyCodeOut out nocopy varchar2,
13 allowedValuesOut out nocopy
14 ame_util.longestStringList);
15 Description
16 The getConditionsDetails procedure outputs various descriptive
17 details about the condition with ID conditionIdIn.
18 getGroupMembers1
19 Syntax
20 procedure getGroupMembers1(
21 applicationIdIn in number default null,
22 transactionTypeIn in varchar2 default null,
23 transactionIdIn in varchar2 default null,
24 groupIdIn in number,
25 memberDisplayNamesOut out nocopy
27 Description
28 The getGroupMembers procedure outputs the display names of
29 the members of the AME approval group with ID groupIdIn. If
30 applicationIdIn, transactionIdIn, and transactionTypeIn default
31 null, the ID must be for a static approval group. If the group is
32 dynamic, these three inputs must identify the transaction for
33 which AME should calculate the group’s membership.
34 getGroupMembers2
35 Syntax
41 memberNamesOut out nocopy ame_util.longStringList,
1
1 Description
2 The getGroupMembers2 procedure has the same functionality as
3 getGroupMembers, but it also outputs the group members’
4 wf_roles.name values. See also ame_api3.getGroupMembers1.
5 getGroupMembers3
6 Syntax
13 memberOrderNumbersOut out nocopy ame_util.idList,
16 Description
18 getGroupMembers2, but it also outputs the members’ order
19 numbers. See also ame_api3.getGroupMembers2.
20 getGroupMembers4
21 Syntax
30 ame_util.longStringList,
31 memberOrigSystemIdsOut out nocopy ame_util.idList,
32 memberOrigSystemsOut out nocopy
34 Description
36 getGroupMembers3, but it also outputs the members’
37 wf_roles.orig_system and wf_roles.orig_system_id values. See
38 also ame_api3.getGroupMembers3.
39 getItemClasses
40 Syntax
41 procedure getItemClasses(
1

3 itemClassIdsOut out nocopy ame_util.idList,
4 itemClassNamesOut out nocopy ame_util.stringList);
5 Description
6 The getItemClasses procedure outputs the IDs and names of the
7 item classes used by the input transaction.
8 getItemClassId
9 Syntax
10 procedure getItemClassId(
12 itemClassIdOut out number);
13 Description
14 The getItemClassId procedure outputs in itemClassIdOut the
15 itemclass ID of the item class with the name itemClassNameIn.
16 getItemClassName
17 Syntax
18 procedure getItemClassName(
20 itemClassNameOut out varchar2);
21 Description
22 The getItemClassName procedure outputs in
23 itemClassNameOut the name of the item class with the ID
24 itemClassIdIn.
25 getOldApprovers
26 Syntax
27 procedure getOldApprovers(
31 oldApproversOut out nocopy
32 ame_util.approversTable2);
33 Description
34 The getOldApprovers procedure outputs in oldApproversOut
35 the approver list that AME calculated most recently for the input
36 transaction. This approver list may not be the transaction’s
37 current list. That is, simultaneous calls to getAllApprovers1 and
38 getOldApprovers could return different approver lists (and the
1
1 list returned by getOldApprovers would then be outdated). This
2 API is a deprecated routine available only for the sake of
3 backwards compatibility.
4 getRuleDetails1
5 Syntax
6 procedure getRuleDetails1(
7 ruleIdIn in number,
8 ruleTypeOut out nocopy varchar2,
9 ruleDescriptionOut out nocopy varchar2,
10 conditionIdsOut out nocopy ame_util.idList,
11 actionTypeNamesOut out nocopy ame_util.stringList,
12 actionTypeDescriptionsOut out nocopy
14 actionDescriptionsOut out nocopy ame_util.stringList);
15 Description
16 The getRuleDetails1 procedure outputs various descriptive
17 details about the rule with ID ruleIdIn. Use getRuleDetails1 in
18 connection with one of the getApplicableRules procedures. See
19 also the getApplicableRules[n] procedures.
20 getRuleDetails2
21 Syntax
26 conditionDescriptionsOut out nocopy
27 ame_util.longestStringList,
32 Description
33 The getRuleDetails2 procedure has the same functionality as
34 getRuleDetails1, but it outputs condition descriptions rather than
35 condition IDs. See also ame_api3.getRuleDetails1.
36 getRuleDetails3
37 Syntax
1
1 conditionIdsOut out nocopy ame_util.idList,

2 conditionDescriptionsOut out nocopy
3 ame_util.longestStringList,
4 conditionHasLOVsOut out nocopy ame_util.charList,
9 Description
10 The getRuleDetails3 procedure has the same functionality as
11 getRuleDetails1, but it outputs condition ID and descriptions,
12 and indicates whether each condition has a list of allowed values.
13 See also ame_api3.getRuleDetails2.
14 insertApprover
15 Syntax
16 procedure insertApprover(
21 positionIn in number,
22 insertionIn in ame_util.insertionRecord2);
23 Description
24 The insertApprover procedure inserts approverIn into the input
25 transaction’s approver list at the approverlist index positionIn
26 using the insertion parameter and order relation in insertionIn.
27 See also ame_api3.getAvailableInsertions.
28 parseApproverSource
29 Syntax
30 procedure parseApproverSource(
31 approverSourceIn in varchar2,
32 sourceTypeOut out varchar2,
34 Description
35 The parseApproverSource procedure parses the
36 ame_util.approverRecord2 source field in approverSourceIn into
37 a source designator in sourceTypeOut and a possibly empty rule
38 ID list in ruleIdsOut. When the list is nonempty, it contains the
39 IDs of the rules requiring the approver having the input source
40 value. Use this API to determine (and optionally display) the
41 reason an approver occurs in a transaction’s approver list.
1
1 suppressApprover
2 Syntax
3 procedure suppressApprover(
8 Description
9 The suppressApprover procedure suppresses approverIn from
10 the input transaction’s approver list. The approver must match
11 an approver in the transaction’s approver list according to the
12 comparison rules explained earlier in this appendix. If
13 approverIn matches a rulegenerated approver from the
14 transaction’s approver list and the mandatory boolean attribute
15 ALLOW_DELETING_RULE_GENERATED_APPROVERS has
16 the value ’true’, the target approver’s status is set to
17 ame_util.suppressedStatus. If approverIn matches an inserted
18 approver, the approver is deleted (undoing the insertion
19 entirely).
20 suppressApprovers
21 Syntax
22 procedure suppressApprovers(
26 approverIn in ame_util.approversTable2);
27 Description
28 The suppressApprovers procedure has the same effect as
29 suppressApprover, but for each approver in approversIn. See
30 also ame_api3.suppressApprover.
31
32ame_api4
33 getGroupMembers
34 Syntax
35 getGroupMembers(
41 memberPersonIdsOut out nocopy ame_util.idList,
1
1 memberUserIdsOut out nocopy ame_util.idList);
2 Description
3 The API will return the approval group members' person id or
4 user id and their corresponding order numbers.
5ame_api5
6 clearItemClassApprovals1
7 Syntax
9 (applicationIdIn in number,
13 itemIdIn in varchar2 default null);
14 Description
15 The clearItemClassApprovals1 procedure clears a
16 transaction’s approvalprocess state for the given item id.
17 ClearItemClassApprovals2
18 Syntax
24 itemIdIn in varchar2 default null);
25 Description
26 Same as ClearItemClassApprovals1 but the item

27 class name has to be passed instead of item
28 class id.
29
30 getApprovalGroupName
31 Syntax
32 getApprovalGroupName
33 (groupIdIn in number
34 ,groupNameOut out nocopy ame_util.stringType);
1
1 Description
2 The API will return the approval group’s name for a given
3 approval group id.
4 getAllApproversAndInsertions
5 Syntax
6 procedure getAllApproversAndInsertions
7 (applicationIdIn in number
8 ,transactionTypeIn in varchar2
9 ,transactionIdIn in varchar2
10 ,activeApproversYNIn in varchar2
11 default ame_util.booleanFalse
12 ,coaInsertionsYNIn in varchar2
13 default ame_util.booleanFalse
14 ,approvalProcessCompleteYNOut out nocopy
15 varchar2
16 ,approversOut out nocopy
17 ame_util.approversTable2
18 ,availableInsertionsOut out nocopy
19 ame_util2.insertionsTable3
20 );
21
22 Description
23 The API will return the approvers and the corresponding
24 available insertions for these approvers for a given transaction.
25 For more details see ame_api2.getAvailableInsertions.
26ame_api6
28 Syntax
29 UpdateApprovalStatus
34 notificationIn in ame_util2.notificationRecord
35 default ame_util2.emptyNotificationRecord,
37 ame_util.emptyApproverRecord2,
38 updateItemIn in boolean default false) ;
39
40 Description
41 This is similar to the ame_api2.updateApprovalStatus except that
42 it stores the user comments and the notification ids in the history
1
1 table. Consumer Teams using the AME Approval History table
2 should use this api.
4 Syntax
16 notificationIn in ame_util2.notificationRecord
17 default ame_util2.emptyNotificationRecord,
18 forwardeeIn in ame_util.approverRecord2
19 default ame_util.emptyApproverRecord2,
20 updateItemIn in boolean default false);
21 Description
22 Same as updateApprovalStatus but the approver details are
23 passed instead of the approver record as such.
24
25ame_api
26 validateApprover
27 Syntax
28 function validateApprover(
29 approverIn in ame_util.approverRecord)
30 return boolean;
31 Description
32 The validateApprover function returns true if the approver is
33 valid, otherwise false. AME’s APIs always return valid
34 approvers, so you don’t need to validate approvers returned by
35 AME. You should call validateApprover to validate an approver
36 you plan to insert into a transaction’s approver list. See also
37 ame_api2.validateApprover.
1
1 clearAllApprovals
2 Syntax
3 procedure clearAllApprovals(
4 applicationIdIn in integer,
6 transactionTypeIn in varchar2 default null);
7 Description
8 The clearAllApprovals procedure has the same functionality as
9 ame_api2.clearAllApprovers. See also
10 ame_api2.clearAllApprovers.
11 deleteApprover
12 Syntax
13 procedure deleteApprover(
16 approverIn in ame_util.approverRecord,
18 Description
19 The deleteApprover procedure suppresses the approver
20 represented by approverIn in the input transaction’s approver
21 list. See also ame_api3.suppressApprover.
22 deleteApprovers
23 Syntax
24 procedure deleteApprovers(
27 approversIn in ame_util.approversTable,
29 Description
30 The deleteApprovers procedure suppresses the approvers
31 represented by approversIn in the input transaction’s approver
32 list. See also ame_api3.suppressApprovers.
33 getAdminApprover
34 Syntax
35 procedure getAdminApprover(
36 applicationIdIn in integer default null,
38 adminApproverOut out ame_util.approverRecord);
1
1 Description
2 The getAdminApprover procedure outputs an
3 ame_util.approverRecord identifying the administrative
4 administrator for the input transaction type. See also
5 ame_api3.getAdminApprover.
6 getAllApprovers
7 Syntax
8 procedure getAllApprovers(
12 approversOut out ame_util.approversTable);
13 Description
14 The getAllApprovers procedure outputs the input transaction’s
15 current approver list, including rule–generated, inserted,
16 suppressed, and repeated approvers. The rows in approversOut
17 are indexed by consecutive ascending integers starting at one.
18 The approval_status values in approversOut reflect each
19 approver’s most recent response to any request for approval they
20 have received, assuming the originating application has passed
21 such responses to AME via updateApprovalStatus or
22 updateApprovalStatus2. In AME 11.5.9, the AME engine
23 excluded from the approver list any approvers deleted by calls to
24 ame_api.deleteApprover(s), or suppressed to account for the
25 value of the repeatedApprovers configuration variable. In AME
26 11.5.10, this behavior has changed. The approver list in
27 approversOut now includes deleted and repeated approvers, but
28 assigns them one of the approval_status values
29 ame_util.suppressedStatus and ame_util.repeatedStatus. Your
30 code should treat these statuses as logically equivalent to
31 ame_util.approvedStatus. The ame_api.getNextApprover will
32 skip approvers with either status when it iterates through the
33 approver list to find the first approver that has not yet approved.
34 See also the ame_api2.getAllApprovers[n] procedures.
35 getAvailableInsertions
36 Syntax
37 procedure getAvailableInsertions(
40 positionIn in integer,
42 availableInsertionsOut out nocopy
43 ame_util.insertionsTable);
1
1 Description
2 The getAvailableInsertions procedure outputs a list of
3 ame_util.insertionRecord records representing the approver
4 insertions possible at the index positionIn in the transaction’s
5 current approver list. See also ame_api3.getAvailableInsertions.
6 getAvailableOrders
7 Syntax
8 procedure getAvailableOrders(
13 availableOrdersOut out ame_util.ordersTable);
14 Description
15 The getAvailableOrders procedure outputs a list of
16 ame_util.orderType records. Each orderType record indicates a
17 possible order type for an approver insertion at the index
18 positionIn in the transaction’s current approver list. This
19 procedure is deprecated. Use getAvailableInsertions instead.
20 See also ame_api3.getAvailableInsertions.
21 getNextApprover
22 Syntax
23 procedure getNextApprover(
27 nextApproverOut out ame_util.approverRecord);
28 Description
29 The getNextApprover procedure outputs the next approver that
30 should approve the input transaction. Unlike the
31 ame_api2.getNextApprovers[n] procedures,
32 ame_api.getNextApprover outputs the same approver each time
33 the procedure is called for a given transaction, until the approver
34 approves the input transaction.
35 getGroupMembers
36 Syntax
37 procedure getGroupMembers(
1

2 memberPersonIdsOut out nocopy ame_util.idList,
3 memberUserIdsOut out nocopy ame_util.idList);
4 Description
5 The getGroupMembers procedure outputs the members of the
6 approval group with ID groupIdIn. See also
7 ame_api3.getGroupMembers.
8 getOldApprovers
9 Syntax
10 procedure getOldApprovers(
14 oldApproversOut out ame_util.approversTable);
15 Description
16 The getOldApprovers procedure outputs the approver list that
17 AME calculated the last time it generated the input transaction’s
18 approver list. See also ame_api3.getOldApprovers.
19 insertApprover
20 Syntax
26 orderIn in ame_util.orderRecord,
28 Description
29 The insertApprover procedure inserts approverIn into the input
30 transaction’s approver list at the index positionIn using the
31 insertion parameter and order relation in insertionIn. See also
32 ame_api3.insertApprover.
33 setFirstAuthorityApprover
34 Syntax
35 procedure setFirstAuthorityApprover(
36 applicationIdIn in Integer,
37 transactionIdIn in varchar2
1
1 Description
2 The setFirstAuthorityApprover procedure sets the first approver
3 for each chain of authority in the input transaction’s approver
4 list. Thus if the approver list includes several chains of authority,
5 they will all start with approverIn. See also
6 ame_api2.setFirstAuthorityApprover.
8 Syntax
9 procedure updateApprovalStatus(
14 forwardeeIn in ame_util.approverRecord default
15 ame_util.emptyApproverRecord);
16 Description
17 The updateApprovalStatus procedure updates the status of the
18 approver approverIn in the input transaction’s approver list. A
19 given person ID or user ID can appear several times in a
20 transaction’s approver list, so AME uses all of the approver
21 comparison fields that occur in ame_util.approverRecord to
22 match approverIn to an ame_util.approverRecord in the input
23 transaction’s approver list. See also
24 ame_api2.updateApprovalStatus and
25 ame_api.updateApprovalStatus2.
27 Syntax
28 procedure updateApprovalStatus2(
32 approverPersonIdIn in integer default null,
33 approverUserIdIn in integer default null,
35 forwardeeIn in ame_util.approverRecord default
36 ame_util.emptyApproverRecord);
37 Description
38 The updateApprovalStatus2 procedure has the same
39 functionality as updateApprovalStatus, except that it updates the
40 first ame_util.approverRecord in the input transaction’s
41 approver list that matches whichever of approverPersonIdIn and
42 approverUserIdIn is nonnull, if the record’s status is not already
43 an approving or forwarding response. See also
1
1 ame_api2.updateApprovalStatus2 and
2 ame_api.updateApprovalStatus.
3What New APIs Map to the 11.5.9 APIs?
4 Most of the ame_api routines are essentially wrappers for
5 ame_api2 or ame_api3 routines, with modifications to preserve
6 preexisting ame_api functionality. The following table tells you
7 which ame_api routine serves as a wrapper for a given ame_api2
8 or ame_api3 routine.
ame_api Routine Equivalent ame_api2 or ame_api3
Routine
getRuleDescription ame_api3.getRuleDescription
validateApprover ame_api2.validateApprover
clearAllApprovals ame_api2.clearAllApprovals
clearDeletion ame_api3.clearSuppression
clearDeletions ame_api3.clearSuppressions
clearInsertion ame_api3.clearInsertion
clearInsertions ame_api3.clearInsertions
deleteApprover ame_api3.suppressApprover
deleteApprovers ame_api3.suppressApprovers
getAdminApprover ame_api2.getAdminApprover
getAllApprovers ame_api2.getAllApprovers7
getAndRecordAllApprovers ame_api2.getAndRecordAllApprovers
getApplicableRules1 ame_api3.getApplicableRules1
getApproversAndRules1 ame_api2.getAllApprovers4
1
ame_api Routine Equivalent ame_api2 or ame_api3
Routine
getAvailableInsertions ame_api3.getAvailableInsertions
getAvailableOrders Not available anymore
getConditionDetails ame_api3.getConditionDetails
getGroupMembers ame_api3.getGroupMembers4
getNextApprover ame_api2.getNextApprovers4
getOldApprovers ame_api3.getOldApprovers
getRuleDetails1 ame_api3.getRuleDetails1
initializeApprovalProcess ame_api2.initializeApprovalProcess
insertApprover ame_api3.insertApprover
setFirstAuthorityApprover ame_api2.setFirstAuthorityApprover
updateApprovalStatus ame_api2.updateApprovalStatus
updateApprovalStatus2 ame_api2.updateApprovalStatus2
1
2 Appendix B
3 ame_util and
4 ame_util2 Packages
2 Appendix B ame_util Package 88
1
1Overview
2 Many of the constants, data types, and routines in ame_util can
3 be useful to originating applications. In fact, it’s important that
4 you use appropriate ame_util features in your code, so that
5 changes to AME functionality do not break your code. This
6 appendix documents the ame_util features that your code should
7 incorporate where appropriate.
8Data Types
9 All of the AME data types your code requires are declared in
10 ame_util’s package specification (in the packageheader file
11 ameoutil.pkh). This section describes the data types you may
12 find useful.
13ame_util
14approverRecord2
15 The ame_api2 and ame_api3 packages use the approverRecord2
16 record to represent an approver. This type has the declaration
17 type approverRecord2 is record(
18 name varchar2(320),
19 orig_system varchar2(30),
20 orig_system_id number,
21 display_name varchar2(360),
22 approver_category varchar2(1),
23 api_insertion varchar2(1),
24 authority varchar2(1),
25 approval_status varchar2(50),
26 action_type_id integer,
27 group_or_chain_id integer,
28 occurrence integer,
29 source varchar2(500),
1
1 item_class ame_item_classes.name%type,
2 item_id ame_temp_old_approver_lists.item_id%type,
3 item_class_order_number integer,
4 item_order_number integer,
5 sub_list_order_number integer,
6 action_type_order_number integer,
7 group_or_chain_order_number integer,
8 member_order_number integer,
9 approver_order_number integer);
10 Here are explanations of the allowed values and semantics of the
11 record’s fields.
12 name
13 This is the approver’s wf_roles.name value, which essentially
14 identifies the approver uniquely in wf_roles.
15 orig_system
16 This is the approver's wf_roles.orig_system value, which
17 represents the system in which the approver originates. For
18 example, the orig_system ‘PER’ is for approvers originating in
19 the HRMS per_all_approvers_f table (that is, HR employees).
20 orig_system_id
21 This is the approver's wf_roles.orig_system_id value. The
22 combination of the approver's orig_system and orig_system_id
23 values also essentially identifies the approver uniquely in
24 wf_roles.
25 display_name
26 This is the approver's wf_roles.display_name value.
27 approver_category
28 This field may contain either of two constants.
29 • ame_util.approvalApproverCategory indicates that this
30 occurrence of the approver must approve one or more items
31 of the transaction in whose approver list the record occurs.
32 • ame_util.fyiApproverCategory indicates that this
1
1 occurrence of the approver should just receive an
2 informational notification describing the transaction in
3 whose approver list the record occurs, and does not need to
4 approve any of the transaction’s items.
5 api_insertion
6 This field may contain any of three constants:
7 • ame_util.apiAuthorityInsertion indicates that the approver
8 was inserted into a chain of authority as a chainofauthority
9 approver, so that the chain should continue with the
10 superior of the inserted approver. The inserted approver
11 must be from an originating system consistent with the
12 action type that generated the chain of authority. This
13 situation often arises when one chainofauthority approver
14 forwards a request for approval to the inserted approver.
15 • ame_util.apiInsertion indicates that the approver was
16 inserted into a transaction’s approver list as an ad hoc
17 approver—that is, an approver who is not part of a chain of
18 authority (even if the approver occurs between two chainof
19 authority approvers who belong to the same approver list).
20 • ame_util.oamGenerated indicates that the rules applying to
21 the transaction in whose approver list the approver occurs,
22 required the approver’s presence in the transaction’s
23 approver list. In this case the approver’s source field
24 contains a value that includes the requiring rules’ IDs. (See
25 ame_api3.parseApproverSource in Appendix A.)
26 authority
27 This field may contain any of three constants:
28 • ame_util.preApprover identifies a pre–approver.
29 • ame_util.authorityApprover identifies an authority
30 approver.
31 • ame_util.postApprover identifies a post–approver.
32 approval_status
33 This field may contain any of twelve constants. Some of these
34 represent possible approver responses to notifications requesting
35 approval, and so are allowed values in the approvalstatus input
36 arguments of the ame_api2.updateApprovalStatus and
37 ame_api2.updateApprovalStatus2 procedures. Others must be
38 generated by AME. The items within the relevant transaction to
39 which the approver’s approval_status value applies are
40 identified by certain output arguments of the
41 ame_api[n].getAllApprovers[n] and getNextApprovers[n]
1
1 procedures.
2 • ame_util.approvedStatus means the approver approved
3 one or more of the relevant transaction’s items, without
4 forwarding the notification requesting approval. You
5 can pass this status to ame_api2.updateApprovalStatus
6 and ame_api2.updateApprovalStatus2.
7 • ame_util.approveAndForwardStatus means the
8 approver approved one or more of the relevant
9 transaction’s items, and also forwarded the notification
10 requesting approval. You can pass this status to
13 • ame_util.beatByFirstResponderStatus means the
14 approver either has not responded, or responded after
15 the first responder in the approval group or chain of
16 authority containing the approver. (In the latter case,
17 AME logs the approver's response and otherwise ignores
18 it.) AME generates this status when the firstresponder
19 wins voting regime is in force for the group or chain
20 containing the approver. You cannot pass this status to
23 • ame_util.clearExceptionsStatus should be passed to
24 ame_api[n].updateApprovalStatus or
25 ame_api[n].updateApprovalStatus2 to clear a
26 transaction’s exception log when the transaction’s
27 workflow is restarted. This is necessary when the
28 approver's status is ame_util.exceptionStatus.
29 • ame_util.exceptionStatus is sometimes returned by the
30 API routines when AME raises an unhandled exception
31 in the process of calculating a transaction’s approver list.
32 (You cannot pass this status to
34 ame_api2.updateApprovalStatus2.) In this case, the
35 originating application may wish to stop the
36 transaction’s workflow.
37 • ame_util.forwardStatus means the approver forwarded
38 the notification requesting approval, without approving
39 the items identified in the notification. You can pass this
40 status to ame_api2.updateApprovalStatus and
42 • ame_util.noResponseStatus means the originating
43 application sent the approver a notification requesting
44 approval, but the approver did not respond to the
45 notification in a timely fashion. (The originating
46 application decides what "timely" means.) You can pass
47 this status to ame_api2.updateApprovalStatus and
1
1 ame_api2.updateApprovalStatus2. AME responds to it
2 by inserting the approver’s surrogate into the approver
3 list, immediately after the approver.
4 • ame_util.notifiedStatus means the originating
5 application has told AME that it has sent the approver a
6 notification, and—if the notification requested approval
7 —the approver has not yet responded to it.
8 • ame_util.nullStatus (or better yet, a null approval_status
9 value) means the approver has not yet been notified, or
10 that their previous approval_status value was cleared.
11 • ame_util.rejectStatus means the approver rejected one
12 or more of the items in the approver list of the relevant
13 transaction. You can pass this status to
16 • ame_util.repeatedStatus means this occurrence of the
17 approver has been aggregated with one or more other
18 occurrences of the same approver, in the relevant
19 transaction's approver list. (See the documentation of
20 the repeatedApprovers configuration variable in Chapter
21 11 of the Oracle Approvals Management Implementation
22 Guide for details.) The ame_api2.getNextApprovers[n]
23 routines treat this status as equivalent to
24 ame_util.approvedStatus, and so never output approvers
25 with this status.
26 • ame_util.suppressedStatus means this occurrence of the
27 approver has been suppressed, typically by a call to one
28 of the ame_api3.suppressApprover(s) routines. The
29 ame_api2.getNextApprovers[n] routines treat this status
30 as equivalent to ame_util.approvedStatus, and so never
31 output approvers with this status.
32 action_type_id
33 For AMEgenerated approvers, this field contains the ID that
34 AME assigns to the action type that generated the approver. For
35 example, if a rule using the absolutejoblevel action type
36 requires an approver, and that action type has the actiontype ID
37 456, the approver's action_type_id value would be 456. For
38 inserted chainofauthority approvers, this field contains the
39 same value that AME assigns to the AMEgenerated approvers
40 in the same chain. For inserted adhoc approvers, this field
41 contains the constant ame_util.nullInsertionActionTypeId.
42 group_or_chain_id
43 This field's semantics depend on whether the approver belongs
44 to an approval group or a chain of authority. In the former case,
45 the field contains the ID that AME assigns to the approval group.
1
1 In the latter case, the action type generating the chain of
2 authority assigns its chains ascending positive integer
3 group_or_chain_id values, starting at one. For example, the dual
4 chainsofauthority approval type generates two chains of
5 authority. Approvers in the first chain have a group_or_chain_id
6 value of one, and approvers in the second chain have a
7 group_or_chain_id value of two. For inserted chainofauthority
8 approvers, this field contains the same value that AME assigns to
9 rulegenerated approvers in the same chain. For ad hoc inserted
10 approvers, this field contains the constant
11 ame_util.nullInsertionGroupOrChainId.
12 occurrence
13 The occurrence field indicates how many times the approver's
14 wf_roles.name value has occurred in the approver's approval
15 group or chain of authority, including the approver proper. For
16 example, if an approver occurs twice in a given chain of
17 authority, the first occurrence has the occurrence value one, and
18 the second the value two.
19 source
20 This field's semantics may vary over time. You should never
21 parse or interpret this field yourself. Instead, use
22 ame_api3.parseApproverSource to do so. AME development
23 will not support any code you write to parse the source field.
24 item_class
25 This field contains the name of the item class of the item ID
26 identified by the approver's item_id field.
27 item_id
28 When an approver must approve or be notified about a single
29 item, this field contains the ID of the item. When the approver
30 must approver or be notified about several items, this field is
31 null, and the list of items appears in certain API routines’ output
32 arguments instead. See the ame_api2.getNextApprovers1
33 documentation in Appendix A for details.
34 item_class_order_number
35 AME uses this field internally to calculate the approver's
36 approver_order_number value.
37 item_order_number
1
1 sub_list_order_number
4 action_type_order_number
7 group_or_chain_order_number
10 member_order_number
13 approver_order_number
14 AME uses the six other ordernumber fields to calculate the
15 approver_order_number value by treating them as a sixtuple
16 and sorting them in lexicographic order. AME uses the
17 approver_order_number to determine which approvers to return
18 in successive calls to the ame_api2.getNextApprovers[n]
19 routines. See Chapter 11 of the implementation guide for details.
20 approversTable2
21 AME’s API represents approver lists as arguments of type
22 approversTable2, which is a PL/SQL table of approverRecord2
23 records. Objects of this type should always be indexed by
24 consecutive ascending integers starting at one.
25 insertionRecord2
26 The ame_api3.getAvailableInsertions procedure uses the
27 insertionRecord2 record to represent a possible approver
28 insertion. This type has the declaration,
29 type insertionRecord2 is record(
1
1 order_type varchar2(50),
2 parameter ame_temp_insertions.parameter%type,
5 description varchar2(200));
6 Fields that also Occur in approverRecord2
7 The item_class, item_id, action_type_id, group_or_chain_id,
8 api_insertion, and authority fields have the same semantics here
9 as they do for the approverRecord2 type. Here are explanations
10 of the other fields.
11 The order_type, parameter, and description Fields
12 The order_type field indicates the order relation that AME uses
13 to determine the insertion’s index in an approver list. AME
14 recalculates the location each time it generates the approver list.
15 Here are brief explanations of each possible value for the
16 order_type field, with accompanying syntax and semantics rules
17 for the parameter and description fields.
18 Absolute Order
19 The value ame_util.absoluteOrder means the insertionRecord’s
20 parameter field should be interpreted as an absolute order
21 number. In this case the parameter should be the string
22 representation of a positive integer between one and one more
23 than the number of approvers already in the approver list. The
24 description should have the syntax
25 ame_util.absoluteOrderDescription || n || '. '
26 where n is the index at which the insertion should take place.
27 For example, if the insertee should always be third in the
28 transaction's approver list, the parameter should be ’3’.
29 After an Approver
30 The value ame_util.afterApprover means the insertee should
31 immediately follow the approver that the insertion parameter
32 identifies. In this case the parameter should have the syntax
33 approver.name ||
34 ame_util.fieldDelimiter ||
35 approver.item_class ||
37 approver.item_id ||
39 approver.action_type_id ||
1
1 approver.group_or_chain_id ||
3 approver.occurrence
4 and the description should have the form
5 ame_util.afterApproverDescription || approver.display_name
6 Before an Approver
7 The value ame_util.beforeApprover means the insertee should
8 immediately precede the approver that the insertion parameter
9 identifies. In this case the parameter should have the syntax
10 approver.name ||
18 approver.group_or_chain_id ||
20 approver.occurrence
22 ame_util.afterApproverDescription ||
23 approver.display_name
24 First Authority
25 The value ame_util.firstAuthority means the insertee should be
26 the first chain–of–authority approver in the chain of authority
27 identified by the parameter. In this case the parameter should
28 have the syntax
29 ame_util.firstAuthorityParameter ||
37 approver.group_or_chain_id
39 ame_util.firstAuthorityDescription
40 First PostApprover
41 The value ame_util.firstPostApprover means the insertee should
42 be the first post–approver in the approver list for the item
44 have the syntax
45 ame_util.firstPostParameter ||
1
1 approver.item_id
3 ame_util.firstPostApproverDescription
4 First PreApprover
5 The value ame_util.firstPreApprover means the insertee should
6 be the first pre–approver in the approver list for the item
8 have the syntax
9 ame_util.firstPreParameter ||
13 approver.item_id
15 ame_util.firstPreApproverDescription
16 Last PostApprover
17 The value ame_util.lastPostApprover means the insertee should
18 be the last post–approver in the approver list for the item
20 have the syntax
21 ame_util.lastPostParameter ||
25 approver.item_id
26 and the description should the form
27 ame_util.lastPostApproverDescription
28 Last PreApprover
29 The value ame_util.lastPreApprover means the insertee should
30 be the last pre–approver in the approver list for the item
32 have the syntax
33 ame_util.lastPreParameter ||
37 approver.item_id
39 ame_util.lastPreApproverDescription
40 insertionsTable2
41 The insertionsTable2 type is a PL/SQL table of
42 ame_util.insertionRecord2 records. The getAvailableInsertions
43 procedure uses an argument of this type to represent the set of
44 possible approver insertions at a given index in an approver list.
45 Objects of this type should always be indexed by consecutive
46 ascending integers starting at one.
1
1 approverRecord
2 In AME versions prior to 11.5.10 the approverRecord type
3 represented an approver in an approver list. This data type is
4 available for backward compatibility. It has the declaration
5 type approverRecord is record(
6 user_id fnd_user.user_id%type,
7 person_id per_all_people_f.person_id%type,
8 first_name per_all_people_f.first_name%type,
9 last_name per_all_people_f.last_name%type,
12 approval_status varchar2(50),
13 approval_type_id integer,
15 occurrence integer,
16 source varchar2(500));
17 Below are explanations of the allowed values and semantics for
18 each field that does not occur in the ame_util.approverRecord2
19 type. (The rules for the other fields are the same here as there.)
20 user_id
21 The user_id field is null if and only if the person_id field is not
22 null. If the user_id field is not null, it must contain a valid
23 fnd_user.user_id value.
24 person_id
25 The person_id field is null if and only if the user_id field is not
26 null. If the person_id field is not null, it must contain a valid
27 per_all_people_f.person_id value.
28 first_name
29 If the person_id field is null, the first_name field contains the
30 approver's fnd_user.user_name value. Otherwise the first_name
31 field contains the approver's per_all_people_f.first_name value.
1
1 last_name
2 If the person_id field is null, the last_name field is also null.
3 Otherwise the last_name field contains the approver's
4 per_all_people_f.last_name value.
5 approval_type_id
6 The approval_type_id field has the same semantics as the
7 action_type_id field in an approverRecord2. See
8 “approverRecord2” above.
9 approversTable
10 This data type is a PL/SQL table of approverRecord records.
11 The ame_api package represents approver lists as
12 approversTable objects. Objects of this type should always be
13 indexed by consecutive ascending integers starting at one. (This
14 type is available for backward compatibility.)
15 insertionRecord
16 In AME versions prior to 11.5.10 the ame_util.insertionRecord
17 record represented a possible approver insertion. This type is
18 available for backward compatibility. It has the declaration,
19 type insertionRecord is record(
24 description ame_temp_insertions.description%type);
25 The api_insertion and authority fields have the same
26 interpretation here as for the approverRecord type. See the
27 description above of the insertionOrder2 type for explanations of
28 the available order types. Below are explanations of the syntax
29 and semantics rules for each order type’s parameter and
30 description values.
31 Absolute Order
32 The absoluteorder order relation has the same order_type,
33 parameter, and description values here as for the
34 insertionRecord2 type.
1
1 After an Approver
2 The afterapprover order type requires parameters with the
3 syntax
4 {person_id,user_id}:n
5 The string preceding the colon indicates the semantics of n,
6 where n is the person or user ID of the approver that the insertee
7 should follow. For example, ’person_id:123’ indicates that the
8 insertee should follow the approver with the person ID 123. The
9 description should have the form
10 ame_util.afterApproverDescription || first_name || ‘ ‘ ||
11 last_name
12 where first_name and last_name are the values that you would
13 assign to the first_name and last_name fields of an
14 approverRecord representing the inserted approver.
15 Before an Approver
16 The beforeapprover order type requires parameters of the same
17 form as those for the afterapprover order type. The description
18 should have the form
19 ame_util.beforeApproverDescription || first_name || ‘ ‘ ||
20 last_name
21 where first_name and last_name are the values that you would
22 assign to the first_name and last_name fields of an
23 approverRecord representing the inserted approver. See “After
24 an Approver” above.
25 First Authority
26 The firstauthority order type does not use the parameter field.
27 The description should be
28 ame_util.firstAuthorityDescription
29 First PostApprover
30 The first postapprover order relation does not use the parameter
31 field. The description should be
32 ame_util.firstPostApproverDescription
33 First PreApprover
34 The first preapprover order relation does not use the parameter
36 ame_util.firstPreApproverDescription
1
1 Last PostApprover
2 The last postapprover order relation does not use the parameter
4 ame_util.lastPostApproverDescription
5 Last PreApprover
6 The last preapprover order relation does not use the parameter
8 ame_util.lastPreApproverDescription
9 insertionTable
10 The insertionsTable type is a PL/SQL table of insertionRecord
11 records. The ame_api.getAvailableInsertions procedure uses an
12 argument of this type to represent the set of possible approver
13 insertions at a given index in an approver list. Objects of this
14 type should always be indexed by consecutive ascending
15 integers starting at one. (This type is available for backward
16 compatibility.)
17Constants
18 The following table lists and describes frequently used ame_util
19 constants, sorted first by purpose and then by alphabetical order.
20
Purpose Name Description
approval status approveAndForwardStatus The approver approved and

forwarded.
approvedStatus The approver approved without
forwarding.
beatByFirstResponderStatus The approver’s approval group or
chain of authority had the first
responderwins voting regime, and
the approver was not the first
responder.
clearExceptionsStatus When passed to
ame_api[n].updateApprovalStatus[
n], tells AME to clear an exception
raised by the transaction’s approval
process.
1
exceptionStatus The transaction’s approval process
raised an exception.
forwardStatus The approver forwarded.
noResponseStatus The approver did not respond in
the time allowed by the originating
application.
notifiedStatus The approver has been notified, and
—if the approver must approve—
has not yet responded.
nullStatus The approver has not yet been
notified.
rejectStatus The approver rejected.
repeatedStatus AME aggregated the approver with
another occurrence of the same
approver in the transaction's
approver list.
suppressedStatus The originating application
suppressed the approver from the
transaction’s approver list.
approver approvalApproverCategory The approver’s response is

category required.
fyiApproverCategory The approver’s response is not
required.
API insertion apiAuthorityInsertion The approver is an inserted chain

ofauthority approver.
apiInsertion The approver is an ad hoc approver.
oamGenerated The approver is generated by
approval rules.
attribute names allowAutoApprovalAttribute ALLOW_REQUESTOR_APPROVA

L.
1
allowEmptyGroupAttribute ALLOW_EMPTY_APPROVAL_GR
OUPS
effectiveRuleDateAttribute EFFECTIVE_RULE_DATE
firstStartingPointAttribute FIRST_STARTING_POINT_PERSO
N_ID
jobLevelStartingPointAttribute JOB_LEVEL_NON_DEFAULT_STA
RTING_POINT_PERSON_ID
includeAllApproversAttribute INCLUDE_ALL_JOB_LEVEL_APP
ROVERS
lineItemStartingPointAttribute LINE_ITEM_STARTING_POINT_P
ERSON_ID
nonDefStartingPointPosAttr NON_DEFAULT_STARTING_POI
NT_POSITION_ID
nonDefPosStructureAttr NON_DEFAULT_POSITION_STR
UCTURE_ID
secondStartingPointAttribute SECOND_STARTING_POINT_PER
SON_ID
simplePosStartPointAttribute SIMPLE_POS_NON_DEFAULT_ST
ARTING_POINT_PERSON_ID
supStartingPointAttribute SUPERVISORY_NON_DEFAULT_
STARTING_POINT_PERSON_ID
topPositionIdAttribute TOP_POSITION_ID
topSupPersonIdAttribute TOP_SUPERVISOR_PERSON_ID
transactionDateAttribute TRANSACTION_DATE
transactionRequestorAttribute TRANSACTION_REQUESTOR_PE
RSON_ID
transactionReqUserAttribute TRANSACTION_REQUESTOR_US
ER_ID
1
transactionOrgAttribute TRANSACTION_ORG_ID
transactionGroupAttribute TRANSACTION_GROUP_ID
transactionReqPositionAttr TRANSACTION_REQUESTOR_PO
SITION_ID
transactionSetOfBooksAttribute TRANSACTION_SET_OF_BOOKS_
ID
authority authorityApprover The approver is a member of a

chain of authority.
postApprover The approver is a member of a post
approval approval group.
preApprover The approver is a member of a pre
approval approval group.
insertion order absoluteOrder The approver should be inserted at

the approverlist index identified by
the insertion parameter.
afterApprover The approver should be inserted
right after the approver specified by
the insertion parameter.
beforeApprover The approver should be inserted
right before the approver specified
by the insertion parameter.
firstAuthority The approver should be the first
approver in the target chain of
authority.
firstPreApprover The approver should be the first
preapprover for the item_class and
item_id specified by insertion
parameter.
firstPostApprover The approver should be the first
postapprover for the item_class
and item_id specified by insertion
parameter.
1
lastPreApprover The approver should be the last
preapprover for the item_class and
item_id specified by insertion
parameter.
lastPostApprover The approver should be the last
postapprover for the item_class
and item_id specified by insertion
parameter.
itemclass names costCenterItemClassName the costcenter item class
headerItemClassName the header item class
lineItemItemClassName the lineitem item class
originating fndRespOrigSystem the FND_RESP originating system

system names
fndUserOrigSystem the FND_USR originating system
perOrigSystem the PER originating system
posOrigSystem the POS originating system
pseudoboolean booleanAttributeFalse the false value for boolean

constants attributes
booleanAttributeTrue the true value for boolean attributes
booleanFalse a varchar2(1) pseudoboolean
constant for false
booleanTrue a varchar2(1) pseudoboolean
constant for true
no the false value for boolean
configuration variables
yes the true value for boolean
configuration variables
REJECTION_RES continueAllOtherItems Only the rejected item’s approval

PONSE possible
1
values process stops.
continueOtherSubItems The header and rejected
subordinate items’ approval
processes stop. Other items’
approval processes continue.
StopAllItems All items’ approval processes stop.
2Routines
3 Here are some frequently used ame_util routines.
4 getAdminName
5 Syntax
6 function getAdminName(
7 applicationIdIn in integer default null)
8 return varchar2;
9 Description
10 This function returns the default value of the the adminApprover
11 configuration variable. You should only call this function in
12 actiontype handlers.
13 fieldDelimiter
14 Syntax
15 function fieldDelimiter
16 return varchar2;
17 Description
18 This function returns the field delimiter used by AME. You
19 should only call this function in actiontype handlers.
20 recordDelimiter
21 Syntax
22 function recordDelimiter
23 return varchar2;
1
1 Description
2 This function returns the record delimiter used by AME. You
3 should only call this function in actiontype handlers.
4 appendRuleIdToSource
5 Syntax
6 procedure appendRuleIdToSource(
7 ruleIdIn in integer,
8 sourceInOut in out nocopy varchar2);
9 Description
10 This procedure appends the input rule ID to the input source
11 value, and outputs the source value in place. Use this function in
12 an actiontype handler to build an approverRecord2’s source
13 value.
14 copyApproverRecord2
15 Syntax
16 procedure copyApproverRecord2(
17 approverRecord2In in approverRecord2,
18 approverRecord2Out out nocopy approverRecord2);
19 Description
20 This procedure copies the input approverRecord2 to the output
21 approverRecord2.
22 copyApproversTable2
23 Syntax
24 procedure copyApproversTable2(
25 approversTable2In in approversTable2,
26 approversTable2Out out nocopy approversTable2);
27 Description
28 This procedure copies the input approversTable2 to the output
29 approversTable2.
30 runtimeException
31 Syntax
32 procedure runtimeException(
33 packageNameIn in varchar2,
34 routineNameIn in varchar2,
35 exceptionNumberIn in integer,
36 exceptionStringIn in varchar2);
1
1 Description
2 All code that extends AME functionality should call
3 runtimeException. This routine logs runtime exceptions in the
4 AME exception log, and in the Workflow exception stack as
5 appropriate.
6ame_util2
7notificationRecord
8 The ame_api6 uses the notificationRecord This type has the
9 declaration
10 type notificationRecord is record(
11 notification_id number,
12 user_comments varchar2(4000));
13 notification_id
14 This is the notification id of the notification .
15 user_comments
16 This is the comment made by the user while responding to a
17 notification .
18
19notificationTable
20 This datatype is pl/sql table of notificationRecord. Objects of this
22 integers starting at one.
23 type notificationTable is table of
24 notificationRecord index by binary_integer;
25
26 /*
27 None of the empty[whatever] variables below
28 should ever be overwritten. They
29 are only to be used as default arguments where
30 empty defaults are required.
31 */
32
33 emptyNotificationRecord notificationRecord;
34 emptyNotificationTable notificationTable;
35
36
37
38insertionRecord3
39 This is same as ame_util.insertionRecord2 except the position
1
1 field. This record is used to return the value in ame_api5.
2 getAllApproversAndInsertions
3 type insertionRecord3 is record(
4 position integer,
13 description varchar2(200));
14 position
15 This denotes the position in the approval list.
16insertionsTable3
17 This datatype is pl/sql table of insertionRecord3. Objects of this
19 integers starting at one.
20 type insertionsTable3 is table of insertionRecord3
21 index by binary_integer;
22Constants
23 New constants added to denote the status for “approvalProcessCompleteYNOut”.
24 completeFullyApproved constant varchar2(1) :=
25 ame_util.booleanTrue;
26 completeFullyRejected constant varchar2(1) :=
27 ame_util.booleanFalse;
28 completePartiallyApproved constant varchar2(1) :=
29 'P';
30 completeNoApprovers constant varchar2(1) :=
31 'X';
32 notCompleted constant varchar2(1) :=
33'W';
34
35 This is the new approval status introduced.
36 reassignStatus constant varchar2(20) := 'REASSIGN';
1
2 Appendix C
3 The ActionType
4 Handler
5 Programming
6 Interface
2 Appendix C The ActionTypeHandler Programming Interface 111
1
1Overview
2 The ame_util and ame_engine PL/SQL packages define a
3 programming interface for actiontype handlers. The ame_util
4 package defines a set of datatypes and utility routines. The
5 ame_engine package provides a collection of routines that it uses
6 to exchange data with actiontype handlers. See Appendix B of
7 this guide for details about ame_util. This appendix documents
8 the relevant ame_engine routines.
9The ame_engine.engStApprovers Data Structure
10 The engine stores and manipulates a transaction’s approver list
11 in a private data structure, ame_engine.engStApprovers, which
12 is of type ame_util.approversTable2. This section refers to the
13 data structure for convenience only. You should not modify the
14 engine to access this data structure directly. (For one thing, the
15 engine’s internal implementation may change, breaking your
16 code’s references to ame_engine.engStApprovers.)
17Engine Functions
18 getActionTypeChainOrderMode
19 Syntax
20 function getActionTypeChainOrderMode(
21 actionTypeIdIn in integer)
22 return varchar2;
23 Description
24 Returns the chainordering mode of the action type with ID
25 actionTypeIdIn. The possible values are
26 ame_util.parallelChainsMode and ame_util.serialChainsMode.
27 An authority handler typically uses this function to calculate the
28 group_or_chain_order_number values of the approvers it
29 generates.
30 getActionTypeVotingRegime
31 Syntax
32 function getActionTypeVotingRegime(
33 actionTypeIdIn in integer)
34 return varchar2;
1
1 Description
2 Returns the voting regime of the action type with ID
3 actionTypeIdIn. The possible values are
4 ame_util.consensusVoting, ame_util.firstApproverVoting, and
5 ame_util.serializedVoting. An authority handler typically uses
6 this function to calculate the member_order_number values of
7 the approvers it generates.
8 getAttributeName
9 Syntax
10 function getAttributeName(
11 attributeIdIn in integer)
12 return varchar2;
13 Description
14 Returns the name of the attribute with the ID attributeIdIn.
15 getAttributeIdByName
16 Syntax
17 function getAttributeIdByName(
18 attributeNameIn in varchar2)
19 return integer;
20 Description
21 Returns the ID of the attribute with the name attributeNameIn.
22 getEffectiveRuleDate
23 Syntax
24 function getEffectiveRuleDate
25 return date;
26 Description
27 Returns the value of the RULE_EFFECTIVE_DATE attribute for
28 the transaction that the engine is currently processing.
29 getHandlerActionTypeId
30 Syntax
31 function getHandlerActionTypeId
32 return integer;
1
1 Description
2 Only an actiontype handler may call this function. It returns the
3 ID of the action type that uses the handler. Typically a handler
4 calls this function to populate an ame_util.approverRecord2
5 record’s action_type_id field.
6 getHandlerActionTypeOrderNum
7 Syntax
8 function getHandlerActionTypeOrderNum
9 return integer;
10 Description
12 order number of the action type that uses the handler. Typically
13 a handler calls this function to populate an
14 ame_util.approverRecord2 record’s action_type_order_number
15 field.
16 getHandlerApprovalStatus
17 Syntax
18 function getHandlerApprovalStatus(
19 approverIn in ame_util.approverRecord2)
20 return varchar2;
21 Description
23 current approval status of the approver identified by approverIn.
24 Typically a handler calls this function to populate an
25 ame_util.approverRecord2 record’s approval_status field.
26 getHandlerAuthority
27 Syntax
28 function getHandlerAuthority
29 return varchar2;
30 Description
32 ame_util sublist (authority) constant of the approvers that the
33 handler generates. A handler should only call this function if it
34 always generates approvers in a fixed sublist. Typically a
35 handler calls this function to populate an
36 ame_util.approverRecord2 record’s authority field.
1
1 getHandlerItemClassId
2 Syntax
3 function getHandlerItemClassId
4 return integer;
5 Description
7 ID of the item class of the item whose approver list the engine is
8 currently constructing. (This is not necessarily the ID of the item
9 class of the item that satisfies the rule that uses the handler’s
10 action type. These items, and their item classes, differ for
11 headerlevel rules with conditions on subordinateitemclass
12 attributes, when peritem evaluation is enabled.) A handler
13 might call this function when preparing to populate an
14 am_util.approverRecord2 record’s item_class field (using
15 ame_engine.getItemClassName) or item_class_order_number
16 field (using ame_engine.getItemClassOrderNumber). It is
17 usually more efficient simply to call
18 ame_engine.getHandlerItemClassName or
19 ame_engine.getHandlerItemClassOrderNumber directly.
20 getHandlerItemClassName
21 Syntax
22 function getHandlerItemClassName
23 return varchar2;
24 Description
26 name of the item class of the item whose approver list the engine
27 is currently constructing. Typically a handler calls this function
28 to populate an ame_util.approverRecord2 record’s item_class
29 field. See also getHandlerItemClassId above.
30 getHandlerItemClassOrderNumber
31 Syntax
32 function getHandlerItemClassOrderNumber
33 return integer;
34 Description
36 order number of the item class of the item whose approver list
37 the engine is currently constructing. Typically a handler calls
38 this function to populate an ame_util.approverRecord2 record’s
39 item_class_order_number field. See also getHandlerItemClassId
40 above.
1
1 getHandlerItemId
2 Syntax
3 function getHandlerItemId
4 return integer;
5 Description
7 ID of the item whose approver list the engine is currently
8 constructing. Typically a handler calls this function to populate
9 an ame_util.approverRecord2 record’s item_id field. See also
10 getHandlerItemClassId above.
11 getHandlerItemOrderNumber
12 Syntax
13 function getHandlerItemOrderNumber
14 return integer;
15 Description
17 order number of the item whose approver list the engine is
18 currently constructing. Typically a handler calls this function to
19 populate an ame_util.approverRecord2 record’s
20 item_order_number field. See also getHandlerItemClassId
21 above.
22 getHandlerOccurrence
23 Syntax
24 function getHandlerOccurrence(
25 nameIn in varchar2,
28 actionTypeIdIn in integer default null,
29 groupOrChainIdIn in integer default null)
30 return integer;
31 Description
33 occurrence value of the approver identified by the input
34 arguments (which should have the values of the corresponding
35 fields in the approver’s ame_util.approverRecord2 record). If
36 any of the defaultnull input arguments is null, the function
37 returns the occurrence value appropriate for adding the
38 approver to the end of the approver list in
39 ame_engine.engStApprovers. Typically a handler calls this
40 function to populate an ame_util.approverRecord2 record’s
41 occurrence field.
1
1 getHandlerSublistOrderNum
2 Syntax
3 function getHandlerSublistOrderNum
4 return integer;
5 Description
7 order number of the sublist that the engine is currently
8 populating. Typically a handler calls this function to populate an
9 ame_util.approverRecord2 record’s sub_list_order_number field.
10 getHeaderAttValue1
11 Syntax
12 function getHeaderAttValue1(
13 attributeIdIn in integer)
14 return varchar2;
15 Description
16 This function returns the value of the headerlevel attribute with
17 the ID attributeIdIn, for the transaction that the engine is
18 currently processing. The function only works for attributes that
19 are not of the currency attribute type. For headerlevel currency
20 attributes, use one of the getHeaderAttValues[n] procedures (see
21 below). A handler could call this function to fetch the value of
22 one of its required attributes, but it would have to fetch the
23 attribute’s ID (using ame_engine.getAttributeIdByName) first.
24 Typically a handler would take the direct route by calling
25 ame_engine.getHeaderAttValue2 (see below) instead. Note that
26 any attribute referenced by your handler must be listed among
27 the corresponding action type’s required attributes. (See
28 “Creating an Action Type” below for details.)
29 getHeaderAttValue2
30 Syntax
31 function getHeaderAttValue2(
32 attributeNameIn in varchar2)
33 return varchar2
34 Description
35 This function returns the value of the headerlevel attribute with
36 the name attributeNameIn, for the transaction that the engine is
37 currently processing. The function only works for attributes that
38 are not of the currency attribute type. For headerlevel currency
39 attributes, use one of the getHeaderAttValues[n] procedures (see
40 below). Typically a handler calls this function to fetch the value
41 of one of its required attributes. Note that any attribute
1
1 referenced by your handler must be listed among the
2 corresponding action type’s required attributes. (See “Creating
3 an Action Type” below for details.)
4 getItemClassId
5 Syntax
6 function getItemClassId(
7 itemClassNameIn in varchar2)
8 return integer;
9 Description
10 This function returns the ID of the item class with the name
11 itemClassNameIn.
12 getItemClassName
13 Syntax
14 function getItemClassName(
15 itemClassIdIn in integer)
16 return varchar2;
17 Description
18 This function returns the name of the item class with ID
19 itemClassIdIn.
20 getItemClassOrderNumber
21 Syntax
22 function getItemClassOrderNumber(
23 itemClassIdIn in integer)
24 return integer;
25 Description
26 This function returns the order number of the item class with ID
27 itemClassIdIn, for the transaction type of the transaction that the
28 engine is currently processing. Typically a handler calls this
29 function to populate an ame_util.approverRecord2 record’s
30 item_class_order_number field.
31 getItemOrderNumber
32 Syntax
33 function getItemOrderNumber(
35 itemIdIn in varchar2)
36 return integer;
1
1 Description
2 This function returns the order number for the item with the ID
3 itemIdIn in the item class with the name itemClassNameIn.
4 Typically a handler calls this function to populate populate an
5 ame_util.approverRecord2 record’s item_order_number field.
6 getRuntimeGroupCount
7 Syntax
8 function getRuntimeGroupCount(
9 groupIdIn in integer)
10 return integer;
11 Description
12 This function returns the number of static members of the
13 approval group with ID groupIdIn.
14 getSublistOrderNum
15 Syntax
16 function getSublistOrderNum(
18 authorityIn in varchar2)
19 return integer;
20 Description
21 This function returns the sublist order number for the sublist
22 identified by the ame_util sublist (authority) constant
23 authorityIn, for the item class with the name itemClassNameIn.
24 Typically a handler calls this function to populate an
25 ame_util.approverRecord2 record’s sub_list_order_number field.
26Engine Procedures
27 addApprover
28 Syntax
29 procedure addApprover(
31 Description
32 This procedure appends the record approverIn to the end of the
33 approver list in ame_engine.engStApprovers. Typically a
34 handler calls this procedure to add an approver to the end of the
35 approver list.
1
1 getApprovalGroupConfigs
2 Syntax
3 procedure getApprovalGroupConfigs(
4 groupIdsInOut in out nocopy ame_util.idList,
5 orderNumbersOut out nocopy ame_util.idList,
6 votingRegimesOut out nocopy ame_util.charList);
7 Description
8 This procedure sorts the approvergroup IDs groupIdsInOut in
9 place by group order number first and then by group ID. It then
10 returns the groups’ order numbers and voting regimes in a
11 consistent order. Typically an approvergroup handler uses this
12 procedure to populate the group_or_chain_order_number and
13 member_order_number fields of the ame_util.approverRecord2
14 records representing the approvers in the input approval groups.
15 (For details about approvergroup voting regimes, see Appendix
16 C of the implementation guide.)
17 getHandlerCOAFirstApprover
18 Syntax
19 procedure getHandlerCOAFirstApprover(
20 itemClassIn in varchar2,
22 actionTypeIdIn in integer,
23 groupOrChainIdIn in integer,
24 nameOut out nocopy varchar2,
25 origSystemOut out nocopy varchar2,
26 origSystemIdOut out nocopy integer,
27 displayNameOut out nocopy varchar2,
28 sourceOut out nocopy varchar2);
29 Description
30 Only an actiontype handler may call this procedure. If the
31 originating application has inserted a starting point (first
32 approver) for the chain of authority that the engine is currently
33 constructing, this procedure returns the inserted approver in
34 nameOut, origSystemOut, origSystemIdOut, and
35 displayNameOut; and it returns the appropriate sourcefield
36 value for the returned approver’s ame_util.approverRecord2
37 record. If no starting point has been inserted, the output
38 arguments’ values are null.
39 getHandlerCOAInsertion
40 Syntax
41 procedure getHandlerCOAInsertion(
43 itemClassIn in varchar2,
1
1 actionTypeIdIn in integer,
2 groupOrChainIdIn in integer,
3 occurrenceIn in integer,
5 nameOut out nocopy varchar2,
6 origSystemOut out nocopy varchar2,
7 origSystemIdOut out nocopy integer,
8 displayNameOut out nocopy varchar2,
9 sourceOut out nocopy varchar2);
10 Description
11 Only an actiontype handler may call this procedure. If the
12 originating application has inserted a chainofauthority
13 approver into the chain of authority immediately after the input
14 approver (identified by all of the input arguments), this
15 procedure returns the inserted approver in nameOut,
16 origSystemOut, origSystemIdOut, and displayNameOut; and it
17 returns the appropriate sourcefield value for the returned
18 approver’s ame_util.approverRecord2 record. If no such
19 insertion has occurred, the output arguments’ values are null.
20 getHandlerRules
21 Syntax
22 procedure getHandlerRules(
24 approverCategoriesOut out nocopy
25 ame_util.charList,
26 parametersOut out nocopy ame_util.stringList,
27 parameterTwosOut out nocopy ame_util.stringList);
28 Description
29 Only an actiontype handler may call this procedure. It returns
30 in ruleIdsOut the IDs of the rules that apply to the transaction
31 the engine is currently processing, which use the action type. For
32 each rule ID, the procedure also returns in
33 approverCategoriesOut the approver category of the transaction
34 type’s rule usage for the rule, and the action parameters of the
35 rule’s action in parametersOut and parameterTwosOut. (If an
36 applicable rule has several actions of the same action type, they
37 appear in separate rows in the output arguments.)
38 Typically a handler uses getHandlerRules for several purposes.
39 First, it uses the action parameters to compute the set of
40 approvers the rules require. Second, it uses the rule usages’
41 approver categories to determine each required approver’s
42 approver category (that is, the approver_category field of the
43 approver’s ame_util.approverRecord2). Third, it uses the rule
44 IDs to populate the source field of each approver’s
45 ame_util.approverRecord2.
46 Use getHandlerRules2 if the actions processed by the handler
1
1 only have one parameter each.
2 getHandlerRules2
3 Syntax
4 procedure getHandlerRules2(
6 approverCategoriesOut out nocopy
7 ame_util.charList,
8 parametersOut out nocopy ame_util.stringList);
9 Description
10 The handlers of action types whose actions only have one
11 parameter should use getHandlerRules2 instead of
12 getHandlerRules (which a handler expecting two parameters per
13 action should use). Otherwise, this procedure functions just like
14 getHandlerRules. See “getHandlerRules” above for details.
15 getHandlerRules3
16 Syntax
20 parametersOut out nocopy ame_util.stringList,
21 listModParameterOnesOut out nocopy
23 listModParameterTwosOut out nocopy
25 Description
26 Only a handler for an action type used by listmodification rules
27 may call this procedure. It functions in much the same way as
28 getHandlerRules1, but for listmodification action types. The
29 ruleIndexesOut contains the indeces of the rule ids (ruleIdsOut)
30 in the rules data structure used by the engine. Each row in the
31 two listModParameter[n]Out arguments represents a list
32 modification condition. Each row in listModParameterOnesOut
33 contains one of the constants ame_util.anyApprover and
34 ame_util.finalApprover. Each row in listModParameterTwosOut
35 contains the wf_roles.name of a target approver. the See
36 “getHandlerRules1” above for further details.
37 setRuleApplied
38 Syntax
40 ruleIndexIn in integer);
1
1 Description
2 This procedure marks the given rule as applicable for the current
3 transction.
4 getHandlerLMApprovers
5 Syntax
6 procedure getHandlerLMApprovers(
7 listModParameterOneIn in varchar2,
8 listModParameterTwoIn in varchar2,
9 includeFyiApproversIn in boolean,
10 includeApprovalGroupsIn in boolean,
11 returnForwardeesIn in boolean,
12 approverIndexesOut out nocopy ame_util.idList,
13 lastForwardeeIndexesOut out nocopy
14 ame_util.idList);
15 Description
16 Only a listmodification actiontype handler may call this
17 procedure. It returns the indexes of the approvers in
18 ame_engine.engStApprovers that satisfy the following
19 requirements:
20 1. The approver has the wf_roles.name value
21 listModParameterTwoIn.
22 2. The approver is in a position consistent with
23 listModParameterOneIn (which can be
24 ame_util.anyApprover or ame_util.finalApprover).
25 3. If includeFyiApproversIn is false, the approver’s
26 approver category is
27 ame_util.approvalApproverCategory.
28 4. If includeApprovalGroupsIn is false, the approver is in a
29 chain of authority.
30 The procedure returns matching approver occurrences’ indexes
31 (in ame_engine.engStApprovers) in approverIndexesOut. If
32 returnForwardeesIn is true, lastForwardeeIndexesOut(i) contains
33 the index of the approver at the end of a succession of
34 forwardings, starting with a forwarding from the approver at the
35 index approverIndexesOut(i). (If there are no forwardings, the
36 two values are the same.)
37 Use getHandlerLMApprovers in conjunction with
38 getHandlerRules3 (see “getHandlerRules3” above).
39 getHeaderAttValues1
40 Syntax
1
1 procedure getHeaderAttValues1(
2 attributeIdIn in integer,
3 attributeValue1Out out nocopy varchar2,
5 attributeValue3Out out nocopy varchar2);
6 Description
7 This procedure returns the values of the headerlevel attribute
8 with the ID attributeIdIn. The procedure returns null in
9 attributeValue2Out and attributeValue3Out unless attributeIdIn
10 identifies a currency attribute. Typically a handler uses this
11 procedure to fetch a currency attribute’s values. However, the
12 handler would typically first have to fetch the attribute’s ID,
13 starting with its name, using
14 ame_engine.getAttributeIdByName. The direct route is typically
15 to use getHeaderAttValues2 (see “getHeaderAttValues2” below).
16 getHeaderAttValues2
17 Syntax
18 procedure getHeaderAttValues2(
19 attributeNameIn in varchar2,
22 attributeValue3Out out nocopy varchar2);
23 Description
24 This procedure returns the values of the headerlevel attribute
25 with the name attributeNameIn. The procedure returns null in
26 attributeValue2Out and attributeValue3Out unless
27 attributeNameIn identifies a currency attribute. Typically a
28 handler uses this procedure to fetch a currency attribute’s values.
29 getRuntimeGroupMembers
30 Syntax
31 procedure getRuntimeGroupMembers(
32 groupIdIn in integer,
33 approverNamesOut out nocopy
35 approverOrderNumbersOut out nocopy
36 ame_util.idList,
37 approverDisplayNamesOut out nocopy
39 origSystemIdsOut out nocopy ame_util.idList,
40 origSystemsOut out nocopy ame_util.stringList);
41 Description
42 This procedure returns the members of the approval group with
43 ID groupIdIn. The members’ order numbers within the group
44 (corresponding to the member_order_number field of an
1
1 ame_util.approverRecord2) are in approverOrderNumbersOut.
2 Typically a preapproval, postapproval, or approvergroup
3 chainofauthority action type uses this procedure to fetch an
4 approval group’s membership, so the handler can add the group
5 to the approver list.
6 insertApprover
7 Syntax
9 indexIn in integer,
11 adjustMemberOrderNumbersIn in boolean default
12 false);
13 Description
14 This procedure inserts the approver represented by approverIn
15 at index indexIn of the current approver list (in
16 ame_engine.engStApprovers). indexIn must be between one and
17 one more than the number of approvers already in the list
18 (inclusive). If adjustMemberOrderNumbersIn is true,
19 insertApprover performs the insertion and then adjusts the
20 member_order_number values of the approvers at and above
21 indexIn, in the same group or chain as approverIn.
22 insertApprovers
23 Syntax
24 procedure insertApprovers(
25 firstIndexIn in integer,
26 approversIn in ame_util.approversTable2);
27 Description
28 This procedure inserts the list of approvers in approversIn into
29 consecutive positions in the current approver list, starting at the
30 index firstIndexIn, which must be between one and one more
31 than the number of approvers already in the list. Unlike
32 insertApprover, insertApprovers does not adjust the member
33 order numbers of any approvers following the inserted
34 approvers. For this reason you should only use insertApprovers
35 in cases where you’re confident no such adjustment could be
36 appropriate.
37 substituteApprover
38 Syntax
39 procedure substituteApprover(
40 approverIndexIn in integer,
42 actionTypeIdIn in varchar2,
1
1 ruleIdIn in integer);
2 Description
3 This procedure replaces the wf_roles.name of the approver in
4 ame_engine.engStApprovers at index approverIndexIn with the
5 nameIn. It also appends ruleIdIn to the ruleID list in the target
6 approver’s source field.
7 truncateChain
8 Syntax
9 procedure truncateChain(
10 approverIndexIn in integer,
11 ruleIdIn in integer);
12 Description
13 Only a listmodification action type’s handler may call this
14 procedure. The procedure truncates the chain of authority
15 containing the approver at index approverIndexIn of
16 ame_engine.engStApprovers, so that this approver becomes the
17 final approver in the chain. If the allowFyiNotifications
18 configuration variable is set to yes, the approvers that would
19 otherwise be truncated remain in the approver list, but their
20 approver category becomes ame_util.fyiApproverCategory. The
21 procedure also appends ruleIdIn to the truncated approvers’
22 source value.
23
24
25
26 Appendix D
27 Sample AME Objects
1
1Overview
2 This chapter illustrates how to create a variety of AME objects that a
3 development team would typically create, in the process of seeding a
4 transaction type:
5 • a transaction type proper
6 • mandatoryattribute usages
7 • an itemclass usage
8 • a headerlevel attribute and a usage for it
9 • a lineitemlevel attribute and a usage for it.
10 The chapter includes sample code for each object, where
11 appropriate. It generally assumes that it describes the activities
12 of the development team for a fictitious Oracle Applications
13 product Some Application.
14Transaction Type
15 Before actually creating a transaction type, the team reviews and
16 documents the following decisions:
17 1. How many transaction types to create
18 2. What usages to give the mandatory attributes
19 3. What itemclass usages to create
20 4. How to configure the itemclass usages.
21 The following subsections describe these decisions.
22Number of Transaction Types
23 Suppose an originating application wants to integrate AME. The
24 application has historically included its own approvals
25 functionality. The approvals functionality applies the same
26 approvals logic to all transactions generated by the application.
27 The logic interprets its decision variables the same way for all
28 transactions. In the development team’s experience, their
29 customers generally implement a modest number of rules in the
30 old approvals functionality. For all these reasons the
31 development team concludes that it only needs to seed one
32 transaction type.
2 Index 127
1
1MandatoryAttribute Usages
2 Next, the development team reviews the mandatory attributes to
3 decide what values or usages to seed for each. Their guiding
4 principle is to preserve or improve upon their old approvals
5 logic in their AME seed data. Here are their decisions:
6 • The old approvals logic never allowed an end user to
7 suppress approvers required by the application’s approvals
8 logic, so the development team gives
9 ALLOW_DELETING_RULE_GENERATED_APPROVERS a
10 static false usage.
11 • Likewise, the old approvals logic never allowed an end user
12 to approve the transactions they submit, so the development
13 team gives ALLOW_REQUESTOR_APPROVAL a static false
14 usage.
15 • In the old logic, all transactions having a total value over a
16 userconfiguration threshold must have someone’s approval.
17 The application owns a PL/SQL package named
18 some_app_package that contains a public function
19 getApprovalThreshold; this function returns the threshold.
20 Therefore the development team gives
21 AT_LEAST_ONE_RULE_MUST_APPLY the dynamic usage
22 select decode(sign(sum(line_item_amount) –
23 some_app_package.getApprovalThreshold),
24 1, ‘true’, ‘false’)
25 from some_app_line_items
26 where transaction_id = :transactionId;
27 Note that this usage assumes that the lineitem amounts are in
28 the same currency as the threshold.
29 • The old logic always evaluates its rules as of sysdate; so the
30 development team gives EFFECTIVE_RULE_DATE a static
31 null usage.
32 • The old logic does not have a rulepriority construct, so the
33 team gives EVALUATE_PRIORITIES_PER_ITEM a static
34 false usage.
35 • The old logic is able to request approval per line item, and it
36 stops a transaction’s approval process when any line item is
37 rejected. So the team gives REJECTION_RESPONSE a static
38 usage having the value ame_util.stopAllItems.The old logic
39 never does perlineitem rule evaluation, so the team gives
40 USE_RESTRICTIVE_ITEM_EVALUATION a static false
41 usage.
2 Index 128
1
1 • The team will integrate AME API calls into its application’s
2 Workflow process, so it gives USE_WORKFLOW a static
3 true usage.
4 • The team uses its transactions’ Workflow item keys as
5 transaction IDs, so it gives WORKFLOW_ITEM_KEY the
6 dynamic usage
8 select :transactionId from dual
10 • The team will give its master Workflow approvals process
11 the item type the named ‘OSA’, so it gives
12 WORKFLOW_ITEM_TYPE the static usage ‘OSA’.
13ConfigurationVariable Values
14 The development team chooses its seeded configurationvariable
15 values according to the same principle by which it chose its
16 mandatoryattribute usages: preserving or improving upon their
17 application’s preAME functionality. Here are their decisions:
18 • Each customer organization will have its own administrative
19 approver, so the team does not seed a value for
20 adminApprover.
21 • The team plans to seed a new approver type based on the
22 (imaginary) ‘ORG’ originating system in Workflow Directory
23 Services. So the team seeds the value ‘yes’ for
24 allowAllApproverTypes.
25 • The old functionality uses line items, so the team seeds the
26 value ‘true’ for allowAllItemClassRules.
27 • The team plans to enable FYI notifications in their approvals
28 Workflow process, so the team sets allowFyiNotifications to
29 ‘yes’.
30 • The old functionality limits currency conversions to a two
31 month period, so the team sets currencyConversionWindow
32 to 60 (days).
33 • The team decides not to seed values for
34 forwardingBehaviors, assuming that their customers will
35 generally already have created appropriate default values for
36 this variable.
37 • The team will not use AME’s production functionality, so it
38 sets productionFunctionality to ‘no’.
39 • The old approvals functionality clears and restarts a
2 Index 129
1
1 transaction’s approval process if it does not finish within two
2 weeks, so the team sets purgeFrequency to 14 (days).
3 • The old functionality does not suppress repeated approvers,
4 so the team sets repeatedApprovers to ‘each occurrence’.
5 • The old functionality does not have a rulepriority construct,
6 so the team disables rule priorities for all rule types in
7 rulePriorityModes.
8ItemClass Usage
9 Next the team prepares to create an itemclass usage for the line
10 item item class.
11 ItemClass Order Number
12 The old approvals functionality created an approver list for each
13 line item. It ordered all approvers serially, with line items’
14 approver lists following the header’s approver list.
15 Consequently the team assigns the lineitem item class the item
16 class order number two.
17 Parallelization Mode
18 Per the above, the team assigns the lineitem item class the serial
19 parallelization mode.
20 Sublist Mode
21 Per the above, the team assigns the lineitem item class the serial
22 sublist mode.
23 LineItemID Query
24 The application’s line items apear in the table
25 some_app_line_items; their IDs are in the line_item_id column of
26 that table. That table joins the application’s some_app_headers
27 table via the transaction_id column. So the itemclass usage
28 must have the lineitemID query
29 select to_char(line_item_id)
30 from some_app_line_items
31 where transaction_id = :transactionId
32 order by line_item_id asc;
33 Note that the orderby clause orders the item IDs in ascending
34 numerical order, rather than in ascending characterset order.
35 Characterset ordering would force the transaction type’s line
36 itemlevel attributes’ usages to order by to_char(line_item_id),
2 Index 130
1
1 which would be inefficient and easy to forget.
2Action Parameters.............................13 50getItemClasses...................................73

3Action Type.......................................11 51getItemClassId...................................74
4action_type_id...................................93 52getItemClassName............................74
5AME Security..................................7, 8 53getItemStatus1...................................60
6appendRuleIdToSource...................108 54getItemStatus2...................................61
7approval_status..................................91 55getItemStatuses.................................61
8chain of authority.....11, 13, 16, 19, 23, 56getNextApprover...............................83
9 43, 65, 85, 91, 92, 93, 94, 97, 102, 57getNextApprovers1...........................62
10 105, 120, 121, 123, 126 58getNextApprovers2...........................62
11clearAllApprovals.......................55, 81 59getNextApprovers3...........................63
12clearInsertion.....................................69 60getNextApprovers4...........................63
13clearInsertions...................................69 61getOldApprovers.........................74, 84
14clearSuppression...............................68 62getPendingApprovers........................64
15Configuration-Variable Values.......129 63getRuleDescription....68, 77, 78, 79, 80
16Creating a Transaction Type...............8 64getRuleDetails1.................................75
17Define an Item Class.........................37 65getRuleDetails2.................................75
18deleteApprover..................................81 66getRuleDetails3.................................75
19deleteApprovers................................81 67getTransactionProductions................64
20Exception Handling...........................41 68group_or_chain_id............................93
21fieldDelimiter..................................107 69initializeApprovalProcess..................65
22final (signing) authority.....................43 70insertApprover.............................76, 84
23getActionTypeChainOrderMode.....112 71List-Editing-Handler.........................22
24getActionTypeVotingRegime.........112 72list–modification...............................11
25getAdminApprover...........................55 73parseApproverSource........................76
26getAdminName...............................107 74PL/SQL Exceptions...........................23
27getAllApprovalGroups......................69 75post-approval.........11, 15, 19, 105, 125
28getAllApprovers..........................56, 82 76pre-approval................11, 19, 105, 125
29getAllApprovers1..............................55 77production...............11, 13, 56, 65, 129
30getAllApprovers3..............................57 78recordDelimiter...............................107
31getAllApprovers4..............................57 79setFirstAuthorityApprover..........65, 84
32getAllApprovers5..............................58 80suppressApprover..............................77
33getAllApprovers6..............................58 81suppressApprovers............................77
34getAllApprovers7..............................59 82Suppressing Approvers.....................42
35getAllItemApprovers.........................59 83the Default Approver List.................41
36getAllItemApprovers2.......................60 84Unresponsive Approvers...................42
37getAndRecordAllApprovers.............60 85updateApprovalStatus.................66, 85
38getApplicableRules1.........................69 86updateApprovalStatus2...............66, 85
39getApplicableRules2.........................70 87updateApprovalStatuses....................67
40getApplicableRules3.........................70 88updateApprovalStatuses2..................67
41getApprovalGroupId.........................71 89validateApprover.........................54, 80
42getAttributeValue..............................71 90Workflow Directory Services............29
43getAvailableInsertions.......................82
44getAvailableOrders...........................83
45getConditionDetails...........................72
46getGroupMembers1...........................72
2 Index 131
1
2 Index 132

AME B DeveloperGuide

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

AME B DeveloperGuide

Uploaded by

Copyright:

Available Formats

1

2 Oracle Approvals Management Developers Guide 1

1 Oracle Approvals Management Release R11i

2 Oracle Approvals Management Developers Guide 2

1 Discoverer, Oracle Web Customers, Oracle Web Employees,

2 Oracle Approvals Management Developers Guide 3

2 Integrating AME into an Application 6

2 Integrating AME into an Application 7

2 Integrating AME into an Application 8

2 Integrating AME into an Application 9

handler. Special callable engine routines are

1 • Migrate/code the new custom handler on this

2 Defining an Item Class 36

2 Defining an Item Class 37

2 Defining an Item Class 38

1 itemSourcesOut out nocopy ame_util.longStringList,

3 productionIndexesOut out nocopy ame_util.idList,

30 productionIndexesOut out nocopy ame_util.idList,

1 transactionTypeIn in varchar2 default null,

1 conditionIdsOut out nocopy ame_util.idList,

1 memberUserIdsOut out nocopy ame_util.idList);

26 Same as ClearItemClassApprovals1 but the item

1 memberOrderNumbersOut out nocopy ame_util.idList,

Purpose Name Description

approval status approveAndForwardStatus The approver approved and

Purpose Name Description

approver approvalApproverCategory The approver’s response is

API insertion apiAuthorityInsertion The approver is an inserted chain­

attribute names allowAutoApprovalAttribute ALLOW_REQUESTOR_APPROVA

Purpose Name Description

Purpose Name Description

authority authorityApprover The approver is a member of a

insertion order absoluteOrder The approver should be inserted at

Purpose Name Description

item­class names costCenterItemClassName the cost­center item class

originating fndRespOrigSystem the FND_RESP originating system

pseudo­boolean booleanAttributeFalse the false value for boolean

REJECTION_RES continueAllOtherItems Only the rejected item’s approval

Purpose Name Description

2Action Parameters.............................13 50getItemClasses...................................73

You might also like

API insertion apiAuthorityInsertion The approver is an inserted chain

itemclass names costCenterItemClassName the costcenter item class

pseudoboolean booleanAttributeFalse the false value for boolean