P. 1


|Views: 713|Likes:
Published by Mohamed Nabil

More info:

Published by: Mohamed Nabil on Apr 18, 2011
Copyright:Attribution Non-commercial


Read on Scribd mobile: iPhone, iPad and Android.
download as DOC, PDF, TXT or read online from Scribd
See more
See less






  • Overview
  • Audience
  • Notifications
  • ame_api2
  • ame_api3
  • ame_api4
  • ame_api5
  • ame_api6
  • ame_api
  • ame_util
  • ame_util2






5 6 7

Oracle® Approvals  Management  Developers Guide


Oracle Approvals Management Developers Guide 1


Oracle Approvals Management Release R11i

2 3
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62

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


Oracle Approvals Management Developers Guide 2

1 2 3 4 5 6 7

Discoverer, Oracle Web Customers, Oracle Web Employees, Oracle Workflow, Oracle Work in Progress, PL/SQL, Pro*C, SmartClient, SQL*, SQL*Forms, SQL*Loader, SQL*Menu, SQL*Net, SQL*Plus, and SQL*Reports are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners.


Oracle Approvals Management Developers Guide 3

.....................................................................................................................................................................................................................................13 Registering an Action Type.....................................................................................................53 Calling AME API Routines...............37 When to Define an Item Class.................................6 4 5 6 7 8 9 Overview..............40 The Basic Algorithm..........................29 Registering an Approver Type...............................................................................................11 Deciding Whether to Create an Action Type......................................25 193 20Defining an Approver Type.....................................................................................................................................29 Approver Types in AME................................................................................................................................29 244 25Defining an Item Class..................................8 102 11Building an Action Type................11 Creating an Action Type...........24 Major changes in the Engine/ Handler Interface since R11i9.................................................................8 Creating a Transaction Type................................52 39 40 41 42 43 44 2 Overview ......................................................................................................................................78 Oracle Approvals Management Developers Guide 4 ..........................................................................................36 26 27 28 Overview............................................................................................................................................................................40 Notifications................41 Frequently Asked Questions..............................37 How to Define an Item Class........................37 295 30Integrating AME with Workflow...................54 ame_api3..................................................................................................................................................................................................................................................10 12 13 14 15 16 17 18 Overview.....................................44 37Appendix A 38API Functional Specifications.................................................................................................28 21 22 23 Overview ...............................................................................................................53 ame_api2 ..........................................12 Coding an Action-Type Handler........................................43 Sample Workflow................................................................................................................................................................................................................................................................................................................................................................................................................................7 AME Security................................................7 Audience .............................................................................................................40 Modifications to the Basic Algorithm.................................................................11 Important – Changes from 11i9 version of AME.........................................................................7 Steps Required to Integrate AME into an Application................................39 31 32 33 34 35 36 Overview........................................................................................................................................................................................68 ame_api4...8 Deciding how Many Transaction Types to Create...............................................................................................77 ame_api5...................................................................................................................................1 1Table of Contents 21 3Integrating AME into an Application............................................................

..............................................................112 Engine Functions...............................................................................................................126 18 19 20 Overview .112 The ame_engine............112 Engine Procedures....................................................................89 Data Types.......................................................................................9 APIs?..............................................................................................1 1 2 3 ame_api6............................................111 12 13 14 15 Overview ...............................................................5..................80 What New APIs Map to the 11...............................................................................................79 ame_api......................................................109 10Appendix C 11The Action-Type-Handler Programming Interface.............................................................127 2 Oracle Approvals Management Developers Guide 5 ......127 Transaction Type........................................86 4Appendix B 5ame_util and ame_util2 Packages........................................................................88 6 7 8 9 Overview .................................................................................................89 ame_util...................................................................................................119 16Appendix D 17Sample AME Objects...........................................................................................................................................................................................................89 ame_util2...........................................................................................................engStApprovers Data Structure..............................................................................................................

1 1 2 3 4 1 Integrating AME into  an Application 2 Integrating AME into an Application 6 .

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

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

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

1 1 2 3 4 2 Building an Action  Type 2 Building an ActionType 10 .

There are six categories of action type: • • • • • • chain of authority list–modification  substitution pre­approval post­approval production An action type except for production category is implemented as a PL/SQL  package called an action­type handler. AME’s attribute and approval­group architecture is more stable.A. To determine whether you need to create a custom action type. 20Deciding Whether to Create an Action Type 21 22 23 24 25 26 27 28 29 30 31 The programming interface between the AME engine and action­type  handlers has changed several times.5. Please review the section at the end of this chapter on changes to the handler  interface.  Please study that chapter carefully before  reading this one. follow these  steps: 2 Building an ActionType 11 .5. we encourage you to create a custom action  type only when you have no alternative.  For these reasons.10. and is likely to continue evolving.10 / AME.9 will have to be  modified before it can be called in AME 11.   As  such the old custom handlers created and used in AME 11.  These facts make custom action types more difficult to maintain than other  approaches to expressing an organization’s business rules in AME.1 1Overview 2 3 4 5 6 7 8 9 10 11 12 13 Note: Chapter 5 of the Oracle Approvals Management Implementation Guide  explains actions and action types.  Even  when you understand the action­type­handler programming interface.  coding an action­type handler that is both correct and efficient can be a  challenge. 14Important – Changes from 11i9 version of AME 15 16 17 18 19 The engine/handler interface has changed in AME 11.5.  In  contrast.

) Code the action type’s handler. 3. 2 Building an ActionType 12 . Identify the approver types that the action type is based on. 1.  Its usage could fetch a  function that ascended the hierarchy until it found an approver with  sufficient signing authority. If you need to use a hierarchy of approvers not supported by a seeded  action type.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 5. and then it could return the number of  approvers it ascended. and give the APPS account execute  privileges on it. Remember to create the  2. Review the seeded action types’ descriptions in Chapter 5 of the  implementation guide. and the hierarchy does not exist outside AME. consider using dynamic  approval groups to access the hierarchy. 4. If the above approaches don’t meet your needs. If TRANSACTION_SUPERVISORY_LEVELS = 4 then require approvals up to the first four supervisors.  Make sure you can’t express the approvals logic  you require with one or more existing action types. consider  using nested approval groups to create the approver hierarchy you need  in AME.   2.  For example. If the approvers you want to use reside in a hierarchy supported by an  AME action type. but their signing limits reside elsewhere. the custom attribute might  be TRANSACTION_SUPERVISORY_LEVELS. and referencing that attribute in your rules’  conditions.   NOTE:  AME development and Oracle Support offer best effort support for  custom action types. If none of the above approaches meets your needs. and the approval­group chain­ of­authority action type to generate chains of authority from the dynamic  approval groups. and then using the approval­group chain­of­authority action  type to generate chains of authority from the nested approval groups.  (See Chapter  3 of this guide for details about approver types. Register the action type in AME using the action typess tab and clicking  on “Use Existing Action Type” in the AME UI. contact AME  development and request that we consider building the action type. If you need to use an approver hierarchy that resides outside of AME  (say in the schema of an originating application).  The rules would then have the form. consider  defining an attribute whose dynamic usage indicates the number or  levels of approvers required.  The rules’ actions would then be of an action type using the  supported approver hierarchy. 32Creating an Action Type 33 34 35 36 37 38 39 Creating an action type takes five steps: 1. 3. you may elect to build a  custom action type.

) Test the action  type.  (See Chapter 10 of the implementation guide for  details.000 transactions of the same type per day.  In contrast.   Efficient PL/SQL architecture is far beyond the scope of this chapter.  24Coding an Efficient Handler 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 AME may call your action­type handler very frequently. for example changes that reflect non–uniformities in an  organization’s signing–authority rules.  (See Chapter 5 of the  implementation guide for details. for example.  Recall that list­ modification and substitution rules apply to an entire transaction’s approver  list. AME’s engine may invoke an authority action  type’s handler 50 times for the transaction. and each action has a set of (zero.1 1 2 3 4 5 6 7 4. a  transaction has 50 line items.  AME’s engine may invoke the handlers of the  action types used by these rules once per item.  Before you code your handler. Create actions for the new action type.000 times per day.) 5.  or two) parameters defined for it.  The parameters of  approver–group action types’ actions typically identify approval groups.  The parameters of an  authority action type’s actions typically represent requirements for certain  levels of authority. and the handler typically generates a chain of authority  satisfying the most stringent of such requirement. The other rules types  (ignoring the production rule type) can apply to each item in a transaction’s  lists of subordinate items.  The parameters of list–editing actions represent specific types of alterations  to an approver list. and interpret the  parameters of several actions.  The rules should make  it easy for your handler efficiently to sort. AME’s engine might  invoke the handler 50.  As a result. config for  that action type in your transaction type to use it after  creating.  So if. aggregate. you should define the syntax and semantics  rules for the parameters of your action type’s actions. The remainder of this chapter explains how to do steps 2 and 3.  How the action type’s handler interprets  an action’s parameters varies with the action type. AME’s engine invokes the handlers of the action types used  by these rules once per transaction.  If the originating application  generates 1.  We  recommend you do at least three things to make your handler efficient: 2 Building an ActionType 13 . it is critical that you  make your handler efficient. one.  So if the number of transactions  and items that use your action type may be substantial.   8Coding an Action­Type Handler 9Defining Action Parameters 10 11 12 13 14 15 16 17 18 19 20 21 22 23 Most action types have several actions.

 change the rules using the  seeded action type to use your action type instead.)  The  2 Building an ActionType 14 .  The results should be comparable. and run the test procedure. a test set of a few thousand transactions suffices to  measure asymptotic performance. Package Specification Package Name An action­type handler’s package name should be of the form  ame_actionType_handler where actionType suggests the name of the action type. Set up your rules to use a seeded action type (and not use the action type  you’re testing). In our experience. using  dbms_utility. if your handler ascended an approver custom hierarchy  called the “functional” hierarchy.  (The AME  engine calls the handler procedure to invoke the handler.get_time to measure the execution time to the nearest  hundredth of a second.   20Programming Interface 21 22 23 24 25 26 27 28 29 30 31 32 33 34 Appendix C of this guide documents AME’s action­type­handler  programming interface.   Compare your handler’s asymptotic (long run) performance to that of  one of the seeded handlers. Tune your handler’s database queries. 3. Calculate and output the mean execution time per transaction ID.   2.   Entry­Point Procedure Each handler must have a public entry­point procedure named  ‘handler’.getAllApprovers7 once for each ID.  Code a PL/SQL test procedure that  follows these steps: 1.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 1.  The procedure should take no arguments.  Then. 3. calling  ame_api2. Loop through the test­transaction IDs.  For  example. 2. Bulk fetch a set of several thousand test­transaction IDs into a local  PL/SQL table. and re­run the test  procedure.  Please review it carefully after reading this chapter. Minimize the number of database queries your handler executes per  transaction using language features such as bulk fetches. the handler package could be  named ‘ame_functional_handler’.

  attribute usages. List­editing handlers modify the approver list when a target  approver is in it. While  writing an AME action–type handler. or for the header item. and configuration­variable values all decisions  about the general structure of a transaction’s approval process.  AME’s  fundamental architectural principle is to encode in approval rules. Authority­Handler Architecture An authority handler translates required­attribute and action­ parameter values into one or more chains of authority. Authority handlers generate chains of authority for action types  used by list­creation and exception rules.  Thus your entire package specification might be: create or replace package ame_functional_handler as procedure handler. 3. for action types used by list­modification or  substitution rules. Package Body An action­type handler alters a transaction’s approver list in  response to a combination of required­attribute values and action­ parameter values. so please avoid the practice.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 handler procedure should be the only public feature of your handler  package.  For each approver  that the handler adds to the item’s approver list.approverRecord2. the handler must  populate all but one of the fields in the approver’s  ame_util.   end ame_function_handler.  (AME’s engine calculates the value of  the record’s approver_order_number field. Approval­group handlers add approval groups to an approver  list for action types used by pre­ or post­approval rules. it is possible to violate this  principle by hard­coding business rules into the handler. The following subsections describe the architecture appropriate for each type  of handler.   2.    Handler­Procedure Architecture There are three different kinds of action­type handler architectures: 1.  Doing so  hides business logic from the end users whose responsibility it is to  define it.)  The handler procedure  should implement the following pseudocode to generate the chains  of authority: 2 Building an ActionType 15 .  It should use AME­engine routines to fetch these  values as necessary (see Appendix C for details). either for a  given subordinate item.

Call one of the engine’s attribute­value­fetching routines to fetch  any required attributes. Fetch the chain’s first approver. e. 4. Make the first approver the current approver. it should  override the default value. j. make them the current approver  and go to step 4c f.getHandlerCOAFirstApprover).1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 Notes: 1. iterate at step 4. If an insertion exists. 1. Make the next approver the current approver. 2. Try to fetch the chain­of­authority insertion following  the current approver (by calling  ame_engine. but if you do.getHandlerRules2 to fetch the applicable rules’  IDs and action parameters. At step 3.   Analyze the action parameters to determine how many chains of  authority the rules require. you may eliminate duplicate action parameters. i. loop.addApprover().  you should keep track of the IDs of all rules requiring a given parameter. g. d. h. and the approver categories that the  rule usages assign them. Call ame_engine.  An inserted starting point  should override all others. Check whether the current approver has final authority. c.  If  the required attribute has a non­null value. Go to step 4d. 2 Building an ActionType 16 .getHandlerCOAInsertion). and when to end each chain. If final authority was found at step 4d. Fetch the next approver in the chain of authority. Populate the approver’s ame_util.  Check for a non­default  first approver identified by a required attribute (in  analogy with the  JOB_LEVEL_NON_DEFAULT_STARTING_POINT_PER SON_ID attribute for the seeded absolute­job­level action  type).approverRecord2 and  add it to the engine’s approver list using  ame_engine.  Also check for an inserted first approver (by  calling ame_engine. 3.  For each required chain. a.  for use in populating each approver’s source field. b.

 the handler should set  this value to ame_util.e.apiAuthorityInsertion. The handler calculates this value from data  returned by ame_engine.h.  getWfRolesNameAndDisplayName to fetch the  other values. it should follow the instructions in this  table:   Value The handler fetches these values at steps 4.  and incrementing the value once for each  iteration of the loop at step 4.c. For rule­generated approvers.name value.getHandlerRules2 in  step 1. and then use  ame_approver_type_pkg.getHandlerApprovalStatus once  per approver to fetch this value.authorityApprover.  Or. The handler should always set this value to  ame_util.getHandlerActionTypeId once per  handler cycle to fetch this value.  and 4.h.fyiApproverCategory.  getOrigSystemIdAndDisplayName to fetch the  other fields’ values. 4. When a handler populates an approver’s ame_util. 4.a. otherwise the value is  ame_util. 4. the handler may start  by fetching the approver’s orig_system_id value  (such as a per_all_people_f. orig_system. depending on which rules require the  approver.e.person_id value). Field name. The handler should call  ame_engine.  orig_system_id approver_category api_insertion authority approval_status action_type_id group_or_chain_id 2 Building an ActionType 17 .1 1 2 3 2.  The handler may start by fetching an  approver’s wf_roles.  For inserted approvers.  and then use ame_approver_type_pkg.approvalApproverCategory if any of  the rule usages requiring the approver is this  value. the handler  should set this value to ame_util. and 4.  The value is  ame_util. The handler should calculate this value by  setting it to once for the first chain it generates.a.approverRecord2  fields at steps 4. The handler should call  ame_engine.oamGenerated.

  getActionTypeChainOrderMode once per  handler cycle to fetch the chain­ordering mode  of its action type. The handler should call  ame_engine.  For inserted  approvers. The handler should call  ame_engine. The handler should call  ame_engine. the ame_engine.getHandlerSublistOrderNum once  per handler cycle to fetch this value.1 Field occurrence Value The handler should call  ame_engine. The handler should call  ame_engine.getHandlerOccurrence once per  approver to fetch this value.  If the mode is  ame_util.getHandlerItemId once per handler  cycle to fetch this value. you  should use ame_util.getHandlerItemClassOrderNumber  once per handler cycle to fetch this value. the source value  should be a list of the IDs of the rules requiring  the approver. separated by  ame_util.  getHandlerCOAFirstApprover or  ame_engine.getHandlerItemClassName once  per handler cycle to fetch this value. The handler should call  ame_engine. The handler should call  ame_engine.appendRuleIdToSource to  build a valid source value.getHandlerItemOrderNumber once  per handler cycle to fetch this value. The handler should call ame_engine.getHandlerActionTypeOrderNum  once per handler cycle to fetch this value. For rule­generated approvers.serialChainsMode.getHandlerCOAInsertion  procedure outputs the correct source value for  each inserted approver.fieldDelimiter.  In this case. the  source item_class item_id item_class_order_number item_order_number sub_list_order_number action_type_order_numb er group_or_chain_order_n umber 2 Building an ActionType 18 .

2 Building an ActionType 19 .  (AME’s engine calculates the value of the  record’s approver_order_number field. member_order_number The handler should call  ame_engine. and calling the functions that return a constant value  for the handler’s cycle just once each at the start of the handler  cycle.   If the handler only needs to generate one chain of authority.) approver_order_number 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 1. or for the header  item.)  The handler procedure should  implement the following pseudocode to generate the approval groups: Call ame_engine.serializedVoting. either for a given subordinate item. eliminate the  loop at step 4. and simply do invidual steps contained 4 once. the  member_order_number should be one for the  first approver in each chain.1 Field Value group_or_chain_order_number should have the  same value as the group_or_chain_id. to populate the constant fields of the current­approver  record.  If the regime is  ame_util. the  group_or_chain_order_number should always  be one.consensusVoting or  ame_util.3. You can help make your handler code efficient by re­using a  local ame_util.  If the  mode is ame_util.  If the regime is ame_util. parallelChainsMode.approverRecord2 variable for the current  approver. Call one of the engine’s attribute­value­fetching routines to fetch the  2.approverRecord2.  the handler must populate all but one of the fields in the approver’s  ame_util. Approver­Group­Handler Architecture An approval­group handler translates required­attribute and action­ parameter values into one or more pre­approval or post­approval  approval groups.getActionTypeVotingRegime once  per handler cycle to fetch the voting regime of  its action type.getHandlerRules to fetch the applicable rules’ IDs and  action parameters (which are the IDs of the approval groupsthat the rules  require). and the approver categories that the rule usages assign them. the  member_order_number should always be one. 3. and should  increment at step 4. The handler should leave this field null (AME’s  engine populates this field.firstApproverVoting.  For each approver that the handler adds to the item’s approval list.

 but if you do. When a handler populates an approver’s ame_util.oamGenerated.approverRecord2. depending on which rules require the  approver. for use in populating each approver’s source field.  (Note that this procedure sorts  the group IDs in place by group order number first.addApprover. • Call ame_engine.getHandlerRules2 in  step a.  The value is  ame_util. 5.getApprovalGroupConfigs.  orig_system_id approver_category api_insertion authority 2 Building an ActionType 20 .approverRecord2  fields at step 5b.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 Notes: 1. values of any required attributes.   Remove any duplicate approver­group IDs from the list of action  parameters.approvalApproverCategory if any of  the rule usages requiring the approver is this  value.preApprover or  3.fyiApproverCategory. At step 3. Field name. orig_system. you may eliminate duplicate action parameters.  4. For each approver returned by getRuntimeGroupMembers. Fetch the group’s membership by calling  ame_engine. loop • Set the values of the fields of the approver’s  ame_util. a.getRuntimeGroupMembers  procedure returns all of these values.) For each required approval group. otherwise the value is  ame_util. The handler calculates this value from data  returned by ame_engine.getRuntimeGroupMembers. loop. 2. b.  The handler should set this value to  ame_util.   Fetch the required groups’ order numbers and ordering modes by calling  ame_engine. it should follow the instructions in this table:   Value The ame_engine. The handler should always set this value to  ame_util. then by group ID.  you should preserve in your rule­ID list the IDs of all the applicable  rules.

approval_status The handler should call  ame_engine.   You should use  ame_util. The handler should call  ame_engine. The loop at step 5 iterates  through the group IDs (typically after any  duplicates have been removed).getHandlerOccurrence once per  approver to fetch this value. The handler should call  ame_engine. The handler should call  ame_engine. The handler should call  ame_engine.getHandlerItemOrderNumber once  per handler cycle to fetch this value.getHandlerItemClassName once  per handler cycle to fetch this value.getHandlerApprovalStatus once  per approver to fetch this value.postApprover.getHandlerActionTypeId once per  handler cycle to fetch this value.appendRuleIdToSource to build a  valid source value.getHandlerItemClassOrderNumber  once per handler cycle to fetch this value. separated by  ame_util. The handler should call  ame_engine. The parameters returned by  ame_engine. The handler should call  ame_engine.getHandlerItemId once per handler  cycle to fetch this value. The handler should call  action_type_id group_or_chain_id occurrence source item_class item_id item_class_order_number item_order_number sub_list_order_number 2 Building an ActionType 21 . The source value should be a list of the IDs of  the rules requiring the approver.getHandlerRules at step 1 are  approver­group IDs.fieldDelimiter.1 Field Value ame_util.

 and substitute one approver for  another. and calling the functions that return a constant value  for the handler’s cycle just once each at the start of the handler  cycle. The handler should leave this field null (AME’s  engine populates this field.getRuntimeGroupMembers. action_type_order_numb er The handler should call  ame_engine.1 Field Value ame_engine. the third is for substitution rules.  If the regime is ame_util. the  member_order_number should be the member  order number in the  approverOrderNumbersOut argument of  ame_engine.serializedVoting. they all modify the approver list only when a  target approver appears in an appropriate context in the list.  If the  regime is ame_util.    List­Editing­Handler Architecture AME seeds three list­editing handlers. one each to reduce an  approver’s authority.getHandlerSublistOrderNum once  per handler cycle to fetch this value. the  member_order_number should always be one.firstApproverVoting. to populate the constant fields of the current­approver  record. the  member_order_number should be the index of  the approver in the approverNamesOut output  argument of  ame_engine.approverRecord2 variable for the current  approver.getApprovalGroupConfigs at step  4 fetches each group’s order number.orderNumberVoting.  The first two of these operations are for list­modification  rules.getApprovalGroupConfigs at step  4 fetches each group’s voting regime.consensusVoting or  ame_util.getHandlerActionTypeOrderNum  once per handler cycle to fetch this value. The call to  ame_engine.  If the  regime is ame_util.getRuntimeGroupMembers.) group_or_chain_order_n umber member_order_number approver_order_number 1 2 3 4 5 6 7 8 9 10 11 12 13 You can help make your handler code efficient by re­using a  local ame_util.   The call to  ame_engine. extend it.  The architectural feature  these handlers share is.  Here is  2 Building an ActionType 22 .

 loop. 5. c.getHandlerLMApprovers to fetch the  approvers that match the current list­modification  condition.truncateChain to truncate a chain of authority  after a target approver. A list­modification handler that removes approvers from the  approver list should not change the ame_util. 2. Call ame_engine.substituteApprover to effect substitututions. a. loop.substituteApprover sets all of the fields  values. Call ame_engine.getHandlerRules3.approverRecord2 field values as the approvers they  replace. followed by a raise  statement or raise_application_error call. 2 Building an ActionType 23 . Notes: 1.runtimeException.getHandlerRules3 to fetch the list of applicable  rules. For each (remaining) row in the output variables of  ame_engine.getHandlerRules3 to eliminate duplicates and leave  the values in an order that is meaningful to your handler. If your handler extends a chain of authority. PL/SQL Exceptions Every routine in your handler should include an exception block.approverRecord2 fields according  to note 2 under “Authority­Handler Architecture” above. Call ame_engine. b.approverRecord2  fields of any remaining approvers. 2.getHandlerLMApprovers. 3. it should populate  the new approvers’ ame_util. Call ame_engine.  The  last two statements in each exception handler for an unhandled exception  should always be a call to ame_util.  The  exception block should at least have a when­others exception handler.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 the basic algorithm: 1.  The ame_engine. Perform some operation on the approver list targeting  the approver identified by the current approver. your handler code should not change any of them. 4. 3.  In the latter case it is idiomatic in  AME coding to have the enclosing routine declare the local variables errorCode integer.   Optionally sort the values returned by  ame_engine. For each row in the output variables of  ame_engine. Substituted approvers should have the same  ame_util.

2. exceptionNumberIn => sqlcode. exceptionStringIn => errorMessage). you need to register it with AME using the  actions tab. 2 Building an ActionType 24 .getMessage( applicationShortNameIn => 'PER'. exceptionNumberIn => errorCode. when others then ame_util.   To create an action type. errorMessage := ame_util. enter a dynamic action  description query. rather than their values.1 1 errorMessage ame_util.  Then the last two statements in the exception handler  can reference these variables.runtimeException( packageNameIn => 'ame_absolute_job_level_handler'. messageNameIn => AME_400448_AJHA_JOB_NOT_ASSD'). 3.longestStringType and then begin your exception handler by setting these variables’  values.runtimeException( packageNameIn => 'ame_absolute_job_level_handler'. exceptionStringIn => sqlerrm). raise. Such a query can refer the bind variables  “:parameterOne” and (for list editing action types)  Once your handler is ready. 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30Registering an Action Type 31 32 33 34 35 36 37 38 39 40 41 42 43 44 For a dynamic Action Description. ame_util. errorMessage). Select  “Business Analyst Dashboard”and click on “Action Types” after  selecting your transaction type in the conten container.  The  following example illustrates both kinds of exception handlers: exception when jobLevelException then errorCode := -20001. follow these steps: 1. Click on “Create” button to navigate to the “Create New Action Type”  page. raise_application_error(errorCode. routineNameIn => 'getJobLevelAndSupervisor'.  Note that this tab requires administrative or developer  privileges. routineNameIn => 'getJobLevelAndSupervisor'. Click on “Use Existing Action Type” to navigate to “Use Existing Action  Type: Select Action Types” page.

) Here. The approver record is of type ame_util. The approver recovered is of type ame_util. The engine makes multiple calls to a handler in order to get all the approvers.which AME binds to an action’s parameter values. The engine calls the handler once.10 / AME. Select :parameterOne || ‘/’ || :parameterTwo from dual might be a dynamic action description for a list modification action  type.approverRecord The approver list being maintained by the engine is stored in public tables which can be directly accessed by the AME 11. you can  create actions for this action type using “Create” button. 2. It is: handler() The handler does not have any arguments being passed IN or OUT. getNextApprover() and hasFinalAuthourity() The handler returns at most one approver back to the engine. See Chapter 5 of the implementation guide for additional information about  an action type’s properties and configuration values. As discussed at the start of this chapter there has been some  major changes to the way custom action type handlers are  required to be coded. They are: getFirstApprover().9 The handler has 3 public routines which are called by the engine. The relevant information is passed in as arguments. All approvers are processed by this one call. Enter all the relevant details and click on “Apply” to create the new  action type. 4. 6.approverRecord2 The approver list being maintained by the engine is private and cannot be directly accessed by the handler.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14Major changes in the Engine/ Handler Interface since R11i9 15 16 17 18 19 20 Step 1. Now create a config for this action type in your  transaction type(Using “Use Existing Action Type.  The conversion steps to move handlers  developed on R11i9 and earlier and preceeding the patchset  AME. 5. 3.  that was released in early Dec 2005. “:parameterTwo”.5.A The handler has only one public routine which is called by the engine. AME 11. Special callable engine routines are available to set handler context. No special routines needed to define the handler context.A.5. 2 Building an ActionType 25 . For Example.

9. The handler transaction state needs to Temporary tables/ global engine be maintained in temporary tables/ variables are not needed to maintain global engine variables.10 instance only. if possible or will set the approvers approval_status to ame_util. 10. transaction state. 1 2 3 4 5 6 7 8 Environment to Migrate Custom Handler The new custom handler code can be written and tested on an  AME 11. This can be done by using private handler package variables. 2 Building an ActionType 26 . approvers resides in the approver type object layer.10.suppressedStatus. The approver record is passed between No serialization of the approver record the handler and the engine after is necessary. ame_util. 14. 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. the approver list are mentioned in the source column of the approver record. 11. insertions resides in the handler.fyiApproverCategory.5. Only rules which rules are included in the source require the approver to be included in column of the approver record. The logic to take into account COA The logic to take into account COA insertions resides in the engine. only. 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.1 handler. L” is processed in the respective handlers. serialization. The logic to identify surrogate The logic to identify surrogate approvers resides in the handler. All applicable accurately identified. 12. 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. Special callable engine routines are defined to do this.  Hence it is recommended  • Upgrade a test instance to 11. The attribute The attribute “ALLOW_REQUESTOR_APPROVA “ALLOW_REQUESTOR_APPROVA L” is processed in the engine.5. 8. 7.

1 1 2 3 4 5 6 7 8 9 • Migrate/code the new custom handler on this test instance • System test the new custom handler on this test instance • Upgrade production instance to 11. • Implement new custom handler on the production instance 2 Building an ActionType 27 .5.10.

1 1 2 3 4 3 Defining an  Approver Type 2 Defining an Approver Type 28 .

 for  Defining an Approver Type 29 . the HRMS application exports employees from its  per_all_people_f table to the PER Directory Services originating system so an  HR employee can be an approver in AME. rather than registering it yourself. it must be be registered with AME (not  merely Workflow Directory Services).)  If you need to use an approver type that AME does not yet seed. 3. The rest of this chapter explains how to perform each of these steps.  For each  such action type. and you must customize several runtime  routines in AME code. 2. Identify the action types that can use the new approver type. 22Registering an Approver Type 23 24 25 26 27 28 29 30 31 32 33 Coding an Approver­Query Procedure 34 35 2 Registering an approver type takes four steps:   1. you will have to modify an AME PL/SQL package each time  you patch AME. AME’s user interface includes an approver­query wizard.   Note:  Unless AME development provides support for an approver type in  this fashion.  AME uses the  wizard in various contexts where an end user must identify an approver. Insert a row into ame_approver_types for the approver type.  Rather.  Currently there is no user interface to  register an approver type. we  strongly encourage you to request that AME development release a patch  supporting the approver type. one must execute a set of SQL statements  that insert rows into the ame_approver_types and  ame_approver_type_usages tables. Code a PL/SQL procedure that AME users can invoke to query for  approvers of the new type.1 1Overview  2 3 4 5 6 An approver type is any Workflow Directory Services originating system that  defines entities that can receive Workflow notifications requesting approval.   7Approver Types in AME 8 9 10 11 12 13 14 15 16 17 18 19 20 21 For AME to use an approver type. Update certain routines in ame_approver_type_pkg that AME uses at  runtime. 4. insert a row into ame_approver_type_usages.  Oracle Support and AME development do not support  custom approver types other than through best effort.  (AME enhancement request 32767685 requests  eliminating the need to customize AME code when adding an approver  type.  For example.

 etc. criterion5In in varchar2 default null. criterion4In in varchar2 default null.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 example while populating an approval group or creating a list­modification  condition. which the wizard passes to the query procedure. 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43  Functionality When you register your approver type with AME.  The  wizard can prompt end users to provide up to five query criteria (first name.perApproverQuery. approverNamesOut out nocopy varchar2. approverDescriptionsOut out nocopy varchar2). criterion2In in varchar2 default null.   Argument List Your approver­query procedure’s signature should be: procedure approverTypeApproverQuery( criterion1In in varchar2 default null. the first five arguments contain the query criteria  that the end user entered or selected on the approver­query form  of the approver­query wizard.  The  cursor’s argument list should match exactly the input argument  list of the query procedure. so that the  approver type’s approver­query procedure is  ame_approver_type_pkg.  For example.  Each approver type registered with AME must provide an  approver­query procedure that the approver­query wizard can invoke.  The integer excludeListCountIn  sets appropriately the the number of rows that the procedure  may output. to account for a set of excluded approvers known to  the approver­query wizard at run time. excludeListCountIn in integer.  The simplest way to  accommodate such null query criteria is to have your cursor  define a cursor that encapsulates your approver query.). Procedure Signature Procedure Name The name of your approver­query procedure should have the  following form: [approverType]ApproverQuery where approverType suggests the approver type.  so that your procedure may receive null values in any  combination of its criterion[n]In arguments.  last name.  The two output  arguments identify approvers that match the query criteria.  ‘PER’ is the originating system for HR employees. criterion3In in varchar2 default null. At run time.  The cursor’s where clause should  2 Defining an Approver Type 30 . you provide a  set of query criteria that the approver­query wizard should  present when an end user queries for approvers of your  approver type.  The end user may leave any or all of these blank.

tooManyApproversException.serializeApprovers( approverNamesIn => approverNames. after  filtering out the approvers to exclude. your  procedure should serialize the lists of approver names and  descriptions selected by the query.1 1 2 3 4 5 6 7 accommodate null query criteria like this: where (criterion1In is null some_column like ‘%’ (criterion2In is null some_column like ‘%’ . approverNamesOut := null. 8 9 10 Your procedure should limit the number of rows it returns by  including the following line in its main cursor’s where clause: rownum < 52 + rowsToExcludeIn The approver­query wizard checks your procedure’s output  values for a set of approvers to exclude. approverDescriptionsOut := null.count . and return the serialized lists  in the procedure’s output arguments.zeroApproversException. end if. approverDescriptionsOut => approverDescriptionsOut). as  follows (assuming the procedure fetches the cursor into a local  approverNames variable):  if(approverNames. approverNamesOut := null.  Your  code should check for this condition and raise an exception. like this: ame_util. . If the cursor does not select too many rows.  The value 52 lets the cursor return one row too many. approverNamesOut => approverNamesOut. approverDescriptionsIn => approverDescriptions. If the cursor selects an apprpriate number of rows. approverDescriptionsOut := null. end if.  So worst case. the set of approvers  that the approver­query wizard presents to the end user.longestStringTypeLength. return. should have 50 approvers  in it.count = 0) then raise ame_util. your procedure  should check that it returns at least one: if(approverNames. or || criterion1In || ‘%’) and or || criterion2In || ‘%’) and .  This set has  rowsToExcludeIn members. maxOutputLengthIn => ame_util. return.rowsToExcludeIn > 50) then raise ame_util. 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45Inserting a Row into ame_approver_types 46 47 48 Use the following insert statement to register the new approver type with  AME: insert into ame_approver_types( 2 Defining an Approver Type 31 .

variable_4_lov_query. execute the  following query: select 1 + max(approver_type_id) from ame_approver_types. creation_date. lastUpdatedBy. queryVariable3Label. endDate). variable_2_lov_query. last_updated_by. Below are descriptions of the values you must supply in the  above insert statement. Defining an Approver Type 32 .  You can view all of the  available orig_system values by executing the following query: select distinct orig_system from wf_directory_partitions.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 approver_type_id. 42 43 44 45 46 47 approverTypeId To determine the appropriate approverTypeId value. variable1LovQuery. queryVariable2Label. variable5LovQuery. query_variable_1_label. variable_3_lov_query. queryVariable1Label. origSystem. creationDate. queryProcedure. variable3LovQuery. startDate. query_variable_4_label. orig_system. variable2LovQuery. variable_5_lov_query. query_variable_2_label.orig_system value that  approvers of the new approver type have. lastUpdateLogin. query_procedure. last_update_login. createdBy. queryVariable4Label. last_update_date. variable_1_lov_query. query_variable_3_label. end_date) values( approverTypeId. start_date. lastUpdateDate. variable4LovQuery. queryVariable5Label. 48 49 50 51 52 2 origSystem The origSystem value should be the wf_roles. query_variable_5_label. created_by.

 the ith query criterion will be a text­ entry input.  If  variable[I]LovQuery is null. and should not include a terminating semi­colon.  Each label may be  up to 50 bytes long. variable[n]LovQuery If you want the ith query criterion to be a select list. and null in the  remaining 5 – k queryVariable[n]Label columns. lastUpdateDate Use sysdate for this value. creationDate Use sysdate for this value. lastUpdatedBy This value should be the same as the createdBy value.user_id value of the user that  inserts the row.  variable[i]LovQuery should be an SQL query that returns the values  you want to appear in the select list. prepend the package name and a  period to the procedure’s name. lastUpdateLogin This value should be the same as the createdBy value. createdBy This value should be the fnd_user. queryProcedure This value should be the name of your query procedure. 2 Defining an Approver Type 33 .1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 queryVariable[n]Label If you want the approver­query wizard to present k query criteria for  your approver type. startDate Use sysdate for this value.  The query may be up to 4000  bytes long.  If the  procedure resides in a package. you must supply user­friendly labels for these  criteria in the first k queryVariable[n]Label columns. endDate The endDate value should be null.

1 1Identifying the Action Types that can use the new Approver Type 2 3 4 5 6 7 8 9 10 11 Once you have inserted a row into ame_approver_types for your approver  type. getSurrogate The ame_approver_type_pkg. you do not need to modify the procedure (because  in this case no subordination relations exist among your approver type’s  approvers). the procedure  checks whether the one is a subordinate of the other. Select the ‘Add Approver Types’ button at the bottom of the ‘Edit Action  Type’ form. and remember that you will have to repeat your additions  each time you install an AME patch. 3. you do not need to modify the  procedure (because in this case no subordination relations exist among your  approver type’s approvers).  The procedure raises  the exception by default. and false  otherwise. 12Updating ame_approver_type_pkg Runtime Routines  13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 2 There are three runtime ame_approver_type_pkg routines that you must  modify to accommodate your new approver type. so if your approver type does not represent an  organizational hierarchy. and  then select the ‘Add’ button. you must modify the procedure so  that if the two input approvers belong to your approver type. the procedure returns the  input approver’s superior. Select the new approver type from the ‘Approver Type’ select list. Select the action tab. so  your code should be as efficient as possible. 2.   getSuperior The procedure ame_approver_type_pkg.  The function returns false by default. 4.  If your approver type does  not represent an organizational hierarchy.getSuperior returns in superiorOut  the superior of the input approver approverIn.  For each action type in  your list.isASubordinate returns true if the  approver possibleSubordApproverIn is a subordinate of the approver  approverIn (presumably within a common approver hierarchy). you must modify the procedure so that when the  input approver belongs to your approver type.  AME’s engine calls these procedures.   isASubordinate The function ame_approver_type_pkg.  Otherwise.   Select the action type on the list of action types.  Otherwise. raising the procedure’s  noSurrogateException exception if no superior exists. follow these steps: 1. you must tell AME which custom action types may use the approver  type.  Be very careful not to alter  the existing code.  Do not include seeded action types in your list.getSurrogate procedure outputs the surrogate  approver that AME should substitute for the unresponsive approver  Defining an Approver Type 34 .

 the procedure returns the input approver’s  surrogate.   The current way to identify surrogate approver is based on the orig_system  of the approver. so if your approver type does not admit surrogate­ approver functionality. raising the local exception  noSurrogateException if no surrogate exists.  The procedure raises the  exception by default. you must modify the procedure so that when the input approver  belongs to your approver type. then the  surrogate is the approvers manager/or the position which is one above the  current approvers position in the relevant hierarchy.  Otherwise.1 1 2 3 4 5 6 7 8 9 10 11 12 13   identified by the procedure’s input arguments. you do not need to modify the procedure.  2 Defining an Approver Type 35 . If the approver is of type 'PER' and 'POSITION'.

1 1 2 3 4 4 Defining an Item  Class 2 Defining an Item Class 36 .

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

1 1 2 Defining an Item Class 38 .

1 1 2 3 4 5 Integrating AME  with Workflow 2 Integrating AME with Workflow 39 .

   26The Basic Algorithm 27 28 29 30 31 32 33 2 Here is the basic algorithm that an application should implement in its  Workflow processes.   Integrating AME with Workflow 40 .getNextApprovers[n] procedures to get the  wf_role. AME will raise an exception.   7Notifications 8Information to Include in Notifications 9 10 11 12 13 14 15 16 17 18 19 AME’s APIs provide a variety of information you can include in the  notifications you send the approvers in a transaction’s approver list: • • • • • whether the notification should be informational or should  request the approver’s approval which subordinate items require the approver’s attention which approval rules required that the approver receive the  notification which productions appy to the approver which productions apply to the transaction. to let AME manage the approval processes of a  transaction type that the application owns. Call one of the ame_api2. 1. and to determine whether the transaction’s approval  process is complete.  If you try to pass any other approval_status  value to AME’s APIs.name values of any approvers that currently require  notification.1 1Overview 2 3 4 5 6 AME’s basic design imperative is to locate all approvals–related logic in a  single module.  This chapter explains how you can integrate AME into your  application’s Workflow processes.  20Encoding Responses to Notifications Requesting Approval 21 22 23 24 25 Appendix B’s description of the approval_status field of the  ame_util. rather than having each application provide its own  approvals logic.approverRecord2 data type lists and describes the ame_util  constants your code may use to represent an approver’s response to a  notification requesting approval.)  Your application should interpret the  productions before presenting them to an end user in a notification. (See Appendix A for details.

 communicate the  response to AME by calling ame_api2. Call ame_api2.1 1 2 3 4 5 6 7 8 9 2.  To learn about other ways to enhance the basic algorithm. 4.updateApprovalStatus or  ame_api2. 23Modifications to the Basic Algorithm 24 25 26 There are several ways to enhance the basic algorithm.  without issuing a rollback.   2 Integrating AME with Workflow 41 . and wait for a response from each approver who  must approve.  In the event of a rejection. When an approver who must approve responds. Notify any approvers output by ame_api2. 31Inserting Approvers into the Default Approver List 32 33 34 35 36 37 38 In the basic algorithm.booleanTrue in approvalProcessCompleteYNOut.   15Exception Handling 16 17 18 19 20 21 22 AME complies with the Workflow exception­handling model by raising all  runtime exceptions to the originating application’s Workflow processes.updateApprovalStatus2.  It leaves all such decisions to AME. 10 Telling AME that an Approver has been Notified 11 12 13 14 Usually you should pass ame_util.  It does not  affect the transaction’s status in its Workflow process. stop (the  transaction is approved).  Note that  this only clears the transaction’s exception status within AME. 27Handling Rejections 28 29 30 The basic algorithm does not terminate if one of the approvers rejects the  transaction.getNextApprovers[n] outputs the value  ame_util.getAllApprovers[n] to get a transaction’s default  approver list.notifiedStatus upon notifying the approver at  step three.getNextApprovers[n] at  step two above.  To clear an exception from a  transaction’s  approval­process state in AME. you need to pass the status  ame_util.  If your  application needs to let an end user insert approvers into the approver list  that AME generates for a given transaction. you may wish to stop at step four to  make sure the algorithm terminates.  This section describes  some of them. modify the basic algorithm as  follows: 1.booleanTrue in  flagApproversAsNotifiedIn. and go to step one above. If ame_api2.  review the API specifications in Appendix A.  Otherwise you must update each notified  approver’s status to ame_util.   3. your application does not determine the membership  of a transaction’s approver list.clearExceptionsStatus at step four in the basic algorithm.

If the user chooses to stop. but you should track internally  the indexes of the approvers you display.validateApprover to validate the approver chosen at  step seven above.  To do so.getAllApprovers[n] to get a transaction’s default  approver list. 2. 5. 6.insertApprover to perform the insertion. or to stop. call  ame_api2. If the user chooses to stop. call ame_api3. 5.  Include suppressed and  repeated approvers.  Otherwise.suppressApprover to suppress the approver.updateApprovalStatus or  2 Integrating AME with Workflow 42 . Call ame_api2. Call ame_api3. If the approver is invalid. Prompt the user to choose a location (index) in the approver list at  which to perform the insertion. 30Accounting for Unresponsive Approvers 31 32 33 34 35 You may wish to account for notification timeouts in your  application’s Workflow process. modify step three of the  basic algorithm by timing each notification. 4. and to pass  ame_util.  3. 6.getAvailableInsertions for that location. Display the approver list to the end user. 9. 3. If the insertion type is ame_util.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 2. 7. stop. or to stop.setFirstAuthorityApprover to perform the insertion. but flag them as such (perhaps by greying out  their names).  Modify step four to  catch timeouts as well as responses. stop. modify the basic  algorithm as follows: 1.firstAuthority.   Display the approver list to the end user.)  Prompt the user to choose an approver to suppress. 10.noResponseStatus to ame_api2.   17Suppressing Approvers in the Default Approver List 18 19 20 21 22 23 24 25 26 27 28 29 If your application needs to let an end user suppress approvers in the  approver list that AME generates for a given transaction. 8. Call ame_api3. 11. Prompt the user to query for an approver to insert. 4. Display the resulting list of available insertions. Call ame_api2.  (You don’t need to include  suppressed or repeated approvers. Prompt the user to choose one of the available insertions. go to step 8 above. Go to step one.

  Each chain  of authority has at least one approver with final (signing) authority  (arriving at such an approver is how AME decides to end the chain). A currency conversion rate can change.1 1 2 ame_api2.  AME determines final  authority internally. no single approver has final authority for the overall  approver list.  So  the temporal order of notifications does not generally reveal which  approver is a final approver.  It does not use Workflow to determine which approver  has final or signing authority (in any sense).  Each approver list can have several chains of authority. The rules that apply to a transaction can change.updateApprovalStatus2 in the event of an unresponsive  approver. AME’s parallel­approvals functionality  makes it possible for an approver having signing authority to be  notified along with previous approvers in the chain of authority.   6Frequently Asked Questions 7What does final (signing) authority mean in AME? 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 The basic algorithm only uses Workflow to send and receive  notifications.  So in general.   24Why call AME each time an approver responds to a notification requesting  25approval? 26 27 28 29 30 31 32 33 34 35 36 Calling ame_api2.  Several  phenomena can cause the approver list to change: • • • • • • An attribute value can change.   1. An organizational hierarchy can change.getNextApprovers[n] each time an approver  responds to a notification requesting is natural in several ways.  Furthermore.  3Forcing an Approver who has Already Approved an Item to Approve it Again 4 5 If you want to force a single approver to re­approve an item they  have already approved. update the approver’s status to null.  Your application’s Workflow process knows  that a transaction has been approved when AME so indicates (at step  two of the basic algorithm). It accounts for the possibility that a transaction’s approver list  will change during the transaction’s approval process. An approval group can change.   AME can generate an approver list for each item in a transaction. The relevant transaction type’s configuration­variable  2 Integrating AME with Workflow 43 .

   It is efficient with respect to performance overhead in the sense  that the least upper bound on the number of different  approver_order_number values is the number of approvers. 2 Integrating AME with Workflow 44 . you need to do three things: 1.  AME determines whether it has been called from within a workflow  by checking the value of the useWorkflow configuration variable. the only transaction  management that AME performs at runtime is to commit inserts into  its exception log within autonomous transactions.  3. It checks for more approvers to notify at the exact moment when  their existence becomes likely. 2. Create a Workflow item type to manage your transaction type’s  approval processes. This section explains how to implement the basic algorithm in Workflow. 4.)  If  the calling application does not use Workflow. Create the following things within your item type: • Create an item attribute of type text (say ‘Approver’) to  contain notification performer data. 5.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 2. and AME may  stop those items’ approval processes while continuing the  approval processes of remaining items. if an  application integrates AME without using Workflow. it must commit  or rollback AME’s work within the code that calls AME’s APIs. 19 Does AME do transaction management? 20 21 22 23 24 25 26 27 28 29Sample Workflow 30 31Overview 32 33 34 35 36 37 To implement the basic algorithm in Workflow.  Thus. • values can change. in  which case AME will add the approver’s surrogate to the  approver list. the  number of approver responses is the same as the number of  approvers. An approver may reject some but not all items.  (Where necessary. and  in the typical scenario (where each approver approves). The relevant transaction type’s mandatory­attribute  values can change.   AME does not perform any commits or rollbacks while responding  to an API call originating within a workflow. An approver may be unresponsive long enough for your  application to tell AME that the approver was unresponsive.

4.  Here are descriptions of each  node: Start Node The first node is a standard function activity that simply marks the  start of the process.   2 Integrating AME with Workflow 45 .getNextApprovers4. and the lookup type ‘Approval Status’. 2. • Create two processes. so indicate to the master  process. 2. When the response arrives. process the  response and go to step one above.  (See ‘Encoding Responses to Notifications  Requesting Approval’ above. wait for a  response from the approver. Create a lookup type (say ‘Approval Status’).  When a child process receives a response. 3. one each for master and detail. and add to  it the approval_status values that your item type will  use. Fetch the next approvers to notify (if any) using  ame_api2. If the notification requests a response.   For each approver fetched. Wait for a response from at least one child process to  continue. Send a notification to the approver. 3.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15Workflow Processes  16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 The master process essentially does the following: 1.) Create a PL/SQL package whose procedures call AME’s API  routines on behalf of your Workflow. • • Create an item attribute of type text (say ‘Master Item  Key’) to contain the master process’ item­key value.) Create a message of type response (say ‘Response  Message’) by attaching the result to its result tab. The Master Process The master process has four nodes. with  the display name ‘Result’. 3. spawn a child process. the description ‘Response  Result’.  (See below  for details. The child process essentially does the following: 1. 4.

createProcess(   itemType => <itemType>. Call your ame_api2. If approvalProcessCompleteYN = ame_util. the node creates and starts a child process for each  approver requiring notification.1 1 2 3 4 5 6 7 Function WF_STANDARD.   Function <package_name>. 2. subsequently waits  for the response from the notified approver at the third node) Item Attributes Set by Function none Item Attributes Retrieved by Function none The following pseudocode describes this node’s logic: 1.getNextApprovers4.booleanTrue.<procedure_name> Result Type yes/no (determines whether the transaction is  completed or not) Required yes Prerequisite Activities none (initially none. 3.  The node also checks whether the  transaction’s approval process is complete.  Follow  these steps for each approver: • A ­ Create a child processes by calling wf_engine. 2 Integrating AME with Workflow 46 . Loop through the approvers returned at step one. end  the process.NOOP Result Type none Required yes none Prerequisite Activities Item Attributes Set by Function none Item Attributes Retrieved by Function none 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Is­Approval­Complete Node The second node fetches the next set of approvers (if any) by calling  your PL/SQL package’s wrapper procedure for  ame_api2.  If the process is  incomplete.   itemKey => <childItemKey>.getNextApprovers4 wrapper procedure  to get the next set of approvers to notify (if any).

  itemKey => <childItemKey>. D .BLOCK none Prerequisite Activities Approver Response) Item Attributes Set by Function none Item Attributes Retrieved by Function none 2 Integrating AME with Workflow 47 .   aName => ‘Approver’.StartProcess(   <itemType>.Start the child processes by calling wf_engine.   aValue => <itemKey>).   aValue => <approver’s wf_roles. C .   11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 Wait­for­Approver­Response Node The third node is a customized standard function activity that  waits for a response from the child processes.   aName => ‘Master Item Key’.name value by calling wf_engine.SetItemAttrText(   itemType => <itemType>.1 1 2 3 4 5 6 7 8 9 10   process => <childProcessName>). Each child process’ item key must be unique. Function Result Type Required yes third node of child process (Get  WF_STANDARD. • B ­ Set the item Approver attribute to the approver’s  wf_roles.   itemKey => <childItemKey>.    <childItemKey>).Set the item Master Item Key attribute to the master item’s item key by calling wf_engine.name>).SetItemAttrText(   itemType => <itemType>.

Function Result Type Required yes node two.NOOP none Prerequisite Activities Item Attributes Set by Function none Item Attributes Retrieved by Function none Send­Notification Node The send­notification node is a standard notification activity that  notifies the approver.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 End Node This is a standard function activity that marks the end of the  process. Function Result Type Required yes none WF_STANDARD. 2 Integrating AME with Workflow 48 .BLOCK none Prerequisite Activities Item Attributes Set by Function none Item Attributes Retrieved by Function none The Child Process Start Node The start node is a standard function activity that marks the start  of the process.name value. Function Message Result Type Required yes none none response message Approval Status Prerequisite Activities Item Attributes Set by Function Set the performer attribute to  the approver’s wf_roles. if result type = Y WF_STANDARD.

Function Result Type Required yes none <package_name>.   itemKey => <childItemKey>.   Communicate the response to the master process’  waiting node by setting masterItemKey := wf_engine.GetItemAttrText(  itemType => <itemType>.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 4.   aName => ‘Approver’). passes it to AME. Get approver attribute’s value by calling wf_engine. and then calling 2 Integrating AME with Workflow 49 .updateApprovalStatus2.<procedure_name> none Prerequisite Activities Item Attributes Set by Function none Item Attributes Retrieved by Function none The following pseudocode describes this node’s logic:  1.updateApprovalStatus or  ame_api2. 3. Get the approver’s response notification response for the  above approver Update the approver’s status calling ame_api2. Item Attributes Retrieved by Function none Get­Approver­Response Node This activity node should call a procedure in your PL/SQL  package that gets the approver’s response.GetItemAttrText(   itemType => <itemType>.  aName => 'Master Item Key').  itemKey => <childItemKey>. and  then completes the master process’ waiting activity (its Wait for  Approver Response node). 2.

 result => null).BLOCK none wf_engine. Prerequisite Activities Item Attributes Set by Function none Item Attributes Retrieved by Function none 2 Integrating AME with Workflow 50 .  activity => <Wait for Approver Response>.  itemKey => <masterItemKey>.CompleteActivity(  itemType => <itemType>.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 End Node This is a standard function activity that marks the end of the  process. Function Result Type Required yes none WF_STANDARD.

1 1 2 Integrating AME with Workflow 51 .

1 1 2 3 4 Appendix A API Functional  Specifications 2 Appendix A API Functional Specifications 52 .

  while ame_api3 contains ancillary routines. within a given  originating application.  Its  value must not contain white­space characters. ame_util2. 8Calling AME API Routines 9Arguments  10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 Many of AME’s API routines share certain arguments.  For ame_api2 and ame_api3.completeNoApprovers – This means that there are no  approvers for this transaction. ame_util2. ame_util2.1 1Overview  2 3 4 5 6 7 AME provides three runtime API packages. and must not be  the character representation of a negative integer. use ame_api2 and ame_api3 only.completePartiallyApproved –  This means that the  approval process is completed but the transaction is partially  approved/rejected.completeFullyRejected –This means that the approval  process is complete and the transaction is rejected. approverIn is an ame_util.  If you are integrating AME into  your product for the first time.application_id value of  the originating application calling the AME API routine.  The ame_api package is  available for backwards compatibility only. when  they appear at all. approvalProcessCompleteYNOut is an out parameter which  returns any of the following values.approverRecord2 (or an  ame_util.  The ame_api2 package contains  routines that a typical workflow uses to process a typical approval process. This  chapter explains how to call AME API routines. 2 Appendix A API Functional Specifications 53 .  It identifies a transaction within a transaction type.  transactionIdIn is a string up to 50 bytes  long.  It  distinguishes one transaction type from another. ame_util2. applicationIdIn is the fnd_application.   transactionTypeIn is a string up to 50 bytes long.completeFullyApproved ­ This means that the  approval process is complete and the transaction is approved. the above four arguments always  appear at the top of a procedure’s input in the above order.  Here are  brief descriptions of each.approverRecord in ame_api) that represents an  approver.

  (AME always validates approvers before  returning them via its APIs.  This lets AME  development add default­null arguments to an API routine  without breaking pre­existing code that references the routine.  Use this API to check whether an  ame_util. especially before passing an ame_util.1 1 2  ame_util2.approverRecord2 to  an AME API routine.notCompleted – This means that the transaction is not  yet completed and still in progress.approverRecord2) return boolean.  The two records represent the same occurrence of the approver if  and only if all of these fields have the same values.approverRecord2 records represent the same  occurrence of an approver in a given transaction’s approver list. 27 28 29 30 31 32 33 34 Description The validateApprover function returns true if the approver  represented by approverIn has a current wf_roles entry.  otherwise returns false. so your code need not do so)   2 Appendix A API Functional Specifications 54 .   validateApprover Syntax function validateApprover( approverIn in ame_util.  it compares the following fields:   • • • • • • item_class item_id name action_type_id group_or_chain_id occurrence.   When AME must determine whether two  ame_util. 3Passing Arguments by Name 4 5 6 7Approver Comparisons 8 9 10 11 12 13 14 15 16 17 18 19 20 21 ame_api2  22 23 24 25 26 Always pass arguments by name to AME’s APIs.approverRecord2 that your application generates is  valid.

21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 Description The getAdminApprover procedure outputs in  adminApproverOut an ame_util. getAllApprovers1 Syntax procedure getAllApprovers1( applicationIdIn in number. itemIndexesOut out nocopy ame_util.).stringList.1 1 2 3 4 5 6 clearAllApprovals Syntax procedure clearAllApprovals( applicationIdIn in number.  Use this  API to restart a transaction’s approval process from scratch. including both rule– 2 Appendix A API Functional Specifications 55 . transactionIdIn in varchar2).   getAdminApprover Syntax procedure getAdminApprover( applicationIdIn in number. 7 8 9 10 11 12 13 14 15 16 17 18 19 20 Description The clearAllApprovals procedure clears a transaction’s approval­ process state.approverRecord2). transactionTypeIn in varchar2. etc. approvalProcessCompleteYNOut out varchar2. itemSourcesOut out nocopy ame_util. transactionIdIn in varchar2. itemClassesOut out nocopy ame_util. transactionTypeIn in varchar2. adminApproverOut out nocopy ame_util. transactionTypeIn in varchar2. suppressions. forwardings. itemIdsOut out nocopy ame_util.stringList.  undoing any operations that have already modified the approval  process. approversOut out nocopy ame_util.  An  originating application may wish to notify this approver when  AME raises an exception.approversTable2.longStringList).idList. 40 41 42 Description The getAllApprovers1 procedure Outputs in approversOut a  transaction’s current approver list.  Restores the default approver list (removing  approver insertions.approverRecord2 representing  the input transaction type’s administrative approver.

  The approvers’ indexes in  approversOut are consecutive ascending integers starting at one.stringList.  If an approver’s item_id value is null. and itemSourcesOut. several items  require the approver. approversOut out nocopy ame_util. transactionIdIn in varchar2.  Several  productions can be assigned a single approver. the  transaction’s approval process is complete. itemClassesOut(i) is the  item’s item class. approval rules. but it also returns per­approver productions  stored in variableNamesOut and variableValuesOut.)   Use this API to fetch and display the entire approver list. otherwise it is  incomplete. itemClassesOut out nocopy ame_util. variableNamesOut out nocopy ame_util. GetAllApprovers2 Syntax procedure getAllApprovers2( applicationIdIn in number. itemIndexesOut out nocopy ame_util. assuming the originating  application has communicated such responses to AME via  ame_api2.  The  approvers’ approval_status values reflect the approvers’ latest  responses to requests for approvals.idList.  organizational structures. itemIdsOut out nocopy ame_util. variableValuesOut out nocopy ame_util.  (There will be at least two such entries in itemIndexesOut. productionIndexesOut out nocopy ame_util. transactionTypeIn in varchar2. for an  approver in approversOut required by multiple items. then itemIdsOut(j) is  the ID of an item requiring the approver.  If such an approver is at index i in  approversOut. and itemIndexesOut(j) = i.stringList).  itemIdsOut.longStringList. 44 45 46 47 48 49 2 Description The getAllApprovers2 procedure has the same functionality as  getAllApprovers1.  The order induced by the indexes is consistent with the ordering  inducd by the approvers’ approver_order_number values (which  AME’s parallel­approval­process functionality generates).stringList. and itemSourcesOut(j) is the source field  indicating which rules required the approver for the same item. approvalProcessCompleteYNOut out varchar2. and then iterating through that list in  your application.approversTable2. so  productionIndexesOut contains for each production the index of  Appendix A API Functional Specifications 56 . storing  its output approver list.updateApprovalStatus or  ame_api2. either  for information or to prompt for approver insertions or  suppresions.stringList. itemSourcesOut out nocopy ame_util.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 generated and inserted approvers.booleanTrue.   If approvalProcessCompleteYNOut is ame_util.  Doing so would risk inaccuracies in the  approver list introduced by changes in transaction values.  Do not use getAllApprovers1 by calling it.idList. etc.updateApprovalStatus2. itemClassesOut.

stringList. transactionTypeIn in varchar2. approvalProcessCompleteYNOut out varchar2. productionIndexesOut out nocopy ame_util.approversTable2. transVariableNamesOut out nocopy ame_util.stringList. variableNamesOut out nocopy ame_util.  See also  ame_api2.stringList.getAllApprovers2. but it also returns per­transaction  productions.getAllApprovers1 and ame_api2. transactionTypeIn in varchar2.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 the approver in approversOut to which the production is  assigned.  Use getAllApprovers2 as you  would getAllApprovers1.stringList. transVariableValuesOut out nocopy ame_util. approversOut out nocopy ame_util. transactionIdIn in varchar2.  That is.stringList).stringList. itemIndexesOut out nocopy ame_util.longStringList. itemClassesOut out nocopy ame_util. approversOut out nocopy ame_util.approversTable2. getAllApprovers3 Syntax procedure getAllApprovers3( applicationIdIn in number. if productionIndexesOut(i) = j. itemClassesOut out nocopy ame_util. ruleIdsOut out nocopy ame_util.idList. ruleIndexesOut out nocopy ame_util.longStringList.idList. itemSourcesOut out nocopy ame_util.  Use getAllApprovers3 as you would  getAllApprovers2.idList). 2 Appendix A API Functional Specifications 57 . when you need to display per­ approver productions with the approvers. when you need to display per­transaction  productions as well as the approver list.idList.  See also  ame_api2. itemSourcesOut out nocopyame_util. then the  production in variableNamesOut(i) and variableValuesOut(i) is  assigned to approversOut(j). itemIdsOut out nocopy ame_util. sourceTypesOut out nocopy ame_util.  getAllApprovers4 Syntax procedure getAllApprovers4( applicationIdIn in number.idList. transactionIdIn in varchar2. variableValuesOut out nocopy ame_util.stringList.stringList.stringList.getAllApprovers1. itemIndexesOut out nocopy ame_util. itemIdsOut out nocopy ame_util. approvalProcessCompleteYNOut out varchar2. 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 Description The getAllApprovers3 procedure has the same functionality as  getAllApprovers2.

  getAllApprovers5 Syntax procedure getAllApprovers5( applicationIdIn in number. 39 40 41 42 43 44 45 46 47 Description The getAllApprovers5 procedure has the same functionality as  getAllApprovers4. sourceTypesOut out nocopy ame_util.  More particularly:  every  approver in approversOut has at least one row in  ruleIndexesOut. transactionIdIn in varchar2.stringList.idList.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 Description The getAllApprovers4 procedure has the same functionality as  getAllApprovers1. ruleIndexesOut out nocopy ame_util. ruleDescriptionsOut out nocopy ame_util. sourceTypesOut and ruleIdsOut.  Some source values  indicate that an approver is not required by any rules.stringList.  See also ame_api2.  Note that getAllApprovers4  requires significantly more performance overhead than some of  its sibling getAllApprovers[n] procedures.approversTable2.  Every  approver in approversOut has only one source value.stringList.  That is. then the values in sourceTypesOut(i) and  ruleIdsOut(i) pertain to the approver in approversOut(j). but it returns rule descriptions rather than  rule IDs. if  ruleIndexesOut(i1) = j and ruleIndexesOut(i2) = j for i1 ¹ i2.getAllApprovers1. along with the rules requiring each approver.stringList). but is  present for other reasons. but it also classifies the approvers in  approversOut according to the reasons for their occurrence in the  approver list. itemClassesOut out nocopy ame_util.idList.getAllApprovers4.  If  ruleIndexesOut(i) = j.  In such cases.longStringList. no matter  how many rules required the approver.  sourceTypesOut(i1) = sourceTypesOut(i2).  Use getAllApprovers4 when you need to display the approver  list. itemIdsOut out nocopy ame_util. itemIndexesOut out nocopy ame_util. if the approver is at  index i. transactionTypeIn in varchar2. itemSourcesOut out nocopy ame_util.  ruleIdsOut identifies the rules.  When one or more rules require an approver. transactionTypeIn in varchar2. 2 Appendix A API Functional Specifications 58 . approversOut out nocopy ame_util.  See also  ame_api2. approvalProcessCompleteYNOut out varchar2. then if sourceTypesOut(j) = i. then ruleIdsOut(j) = null.   getAllApprovers6 Syntax procedure getAllApprovers6( applicationIdIn in number.

  getAllApprovers7 Syntax procedure getAllApprovers7( applicationIdIn in number.idList.stringList. approvalProcessCompleteYNOut out varchar2.stringList. itemIdIn in varchar2.stringList. transactionIdIn in varchar2. approvalProcessCompleteYNOut out varchar2.  See also  2 Appendix A API Functional Specifications 59 . transactionIdIn in varchar2.approversTable2.  This is the  lowest­overhead getAllApprovers[n] procedure.longStringList. Description The getAllItemApprovers1 procedure has the same functionality  as getAllApprovers1.  See also  ame_api2. itemSourcesOut out nocopy ame_util. itemIndexesOut out nocopy ame_util.approversTable2). 25 26 27 28 29 30 31 32 33 34 35 36 37 38 Description The getAllApprovers7 procedure has the same functionality as  getAllApprovers1.stringList). itemClassesOut out nocopy ame_util. approversOut out nocopy ame_util. ruleDescriptionsOut out nocopy ame_util. 13 14 15 16 17 18 19 20 21 22 23 24 Description The getAllApprovers6 procedure has the same functionality as  getAllApprovers4.  See also ame_api2. sourceTypesOut out nocopy ame_util. but for the single item with ID itemIdIn of  the item class with the ID itemClassIdIn. ruleIdsOut out nocopy ame_util. transactionTypeIn in varchar2.approversTable2).getAllApprovers1. but omitting the per­item outputs.   getAllItemApprovers Syntax procedure getAllItemApprovers1( applicationIdIn in number. but it returns both rule IDs and rule  descriptions.idList. approversOut out nocopy ame_util.getAllApprovers4.1 1 2 3 4 5 6 7 8 9 10 11 12 transactionIdIn in varchar2. itemIdsOut out nocopy ame_util. itemClassIdIn in number. 39 40 41 42 43   approversOut outnocopy ame_util.idList. approvalProcessCompleteYNOut out varchar2. ruleIndexesOut out nocopy ame_util. transactionTypeIn in varchar2.

transactionTypeIn in varchar2. transactionIdIn in varchar2. itemSourcesOut out nocopy ame_util.idList. 2 Appendix A API Functional Specifications 60 .   getAndRecordAllApprovers Syntax procedure getAndRecordAllApprovers( applicationIdIn in number. 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 Description The getAndRecordAllApprovers procedure has the same  functionality as getAllApprovers1.getAllApprovers1.getAllApprovers1  and ame_api2. approvalProcessCompleteYNOut out varchar2.stringList. approversOut out nocopy ame_util. itemIdsOut out nocopy ame_util. but it also updates the state of  the transaction’s approval process in AME (in particular  accounting for any approver insertions or suppressions made via  the API since the last AME engine cycle). calling getAndRecordAllApprovers is generally not  necessary.  Otherwise. itemIdIn in varchar2. transactionIdIn in varchar2. itemClassNameIn in varchar2.longStringList).  You can call this API  to make sure AME has accounted for an approver insertion or  suppression before calling ame_api3. 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Description The getAllItemApprovers2 procedure has the same functionality  as getAllItemApprovers1.  See also ame_api2. approvalProcessCompleteYNOut out varchar2. itemIndexesOut out nocopy ame_util.getAllApprovers1. approversOut out nocopy ame_util.1 1 2 3 4 5 6 7 8 9 10 11 ame_api2.   getAllItemApprovers2 Syntax procedure getAllItemApprovers2( applicationIdIn in number.  See also ame_api2.getOldApprovers. transactionTypeIn in varchar2.approversTable2. but it identifies the input item class by  name in itemClassNameIn.approversTable2).   getItemStatus1 Syntax procedure getItemStatus1( applicationIdIn in number. transactionTypeIn in varchar2.getAllItemApprovers1.

36 37 38 39 40 41 42 Description The getItemStatuses procedure outputs the statuses of the  approval processes of the input transaction’s items. itemIdIn in varchar2.  If  approvalProcessesCompleteYNOut(i) is ame_util. transactionIdIn in varchar2.stringList. 2 Appendix A API Functional Specifications 61 .charList). getItemStatus2 Syntax procedure getItemStatus2( applicationIdIn in number. itemClassNameIn in varchar2. approvalProcessCompleteYNOut out varchar2). itemClassNamesOut out nocopy ame_util.   getItemStatuses Syntax procedure getItemStatuses( applicationIdIn in number. approvalProcessCompleteYNOut out varchar2). the  item has been approved.booleanTrue.stringList. itemIdIn in varchar2. transactionIdIn in varchar2. transactionTypeIn in varchar2. itemIdsOut out nocopy ame_util.  See also  ame_api2.booleanTrue.getItemStatus1.  If  approvalProcessCompleteYNOut is ame_util.  the item with ID itemIdsOut(i) of the item class  itemClassNamesOut(i) has been approved. otherwise the item’s approval process is  incomplete. otherwise the item’s  approval process is incomplete. 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 Description The getItemStatus2 procedure outputs the status of the approval  process of the item identified by itemIdIn for the item class  identified by its name in itemClassNameIn. transactionTypeIn in varchar2. 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 Description The getItemStatus1 procedure outputs the status of the approval  process of the item identified by itemIdIn of the item class  identified by itemClassIdIn for the input transaction. approvalProcessesCompleteYNOut out nocopy ame_util.1 1 2 3 4 transactionIdIn in varchar2. itemClassIdIn in integer.

1 1 2
3 4 5 6 7 8 9 10 11 12 13 14 15

getNextApprovers1 Syntax

procedure getNextApprovers1( applicationIdIn in number, transactionTypeIn in varchar2, transactionIdIn in varchar2, flagApproversAsNotifiedIn in varchar2 default ame_util.booleanTrue, approvalProcessCompleteYNOut out varchar2, nextApproversOut out nocopy ame_util.approversTable2, itemIndexesOut out nocopy ame_util.idList, itemClassesOut out nocopy ame_util.stringList, itemIdsOut out nocopy ame_util.stringList, itemSourcesOut out nocopy ame_util.longStringList)

16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
38 39 40 41 42 43 44 45 46 47 48 49

The getNextApprovers1 procedure outputs in  nextApproversOut the approvers requiring notification for the  current stage of the input transaction’s approval process.  Once  an originating application updates an approver’s status to  ame_util.notifiedStatus, getNextApprovers1 excludes the  approver from nextApproversOut.  An originating application  can update an approver’s status to ame_util.notifiedStatus by  passing ame_util.booleanTrue as flagApproversAsNotifiedIn to  a call to getNextApprovers1 that includes the approver in  nextApproversOut.  Or the originating application can pass  ame_util.booleanFalse in flagApproversAsNotifiedIn, and  instead call updateApprovalStatus or updateApprovalStatus2 to  update the approver’s status independently of a call to  getNextApprovers.   (See getAllApprovers1 above for an explanation of  itemIndexesOut, itemClassesOut, itemIdsOut, and  itemSourcesOut.)  Use getNextApprovers1 to iterate through a  transaction’s approval process one stage at a time.  See also  ame_api2.getAllApprovers1. 

getNextApprovers2 Syntax

procedure getNextApprovers2( applicationIdIn in number, transactionTypeIn in varchar2, transactionIdIn in varchar2, flagApproversAsNotifiedIn in varchar2 default ame_util.booleanTrue, approvalProcessCompleteYNOut out varchar2, nextApproversOut out nocopy ame_util.approversTable2, itemIndexesOut out nocopy ame_util.idList, itemClassesOut out nocopy ame_util.stringList, itemIdsOut out nocopy ame_util.stringList,


Appendix A API Functional Specifications 62

1 3 4 5

itemSourcesOut out nocopy ame_util.longStringList, productionIndexesOut out nocopy ame_util.idList, variableNamesOut out nocopy ame_util.stringList, variableValuesOut out nocopy ame_util.stringList);

6 7 8 9 10 11 12 13 14 15
16 17 18 19 20 21 22 23 24 25 26 27 28 30 31 32 33 34 35 36

The getNextApprovers2 procedure has the same functionality as  as getNextApprovers1, but it also returns per­approver  productions.  Use getNextApprovers2 to iterate through a  transaction’s approval process one stage at a time when your  application enables per­approver productions, for example to  track per­approver eSignature requirements.  See also  ame_api2.getAllApprovers2 and ame_api2.getNextApprovers1.  

getNextApprovers3 Syntax

procedure getNextApprovers3( applicationIdIn in number, transactionTypeIn in varchar2, transactionIdIn in varchar2, flagApproversAsNotifiedIn in varchar2 default ame_util.booleanTrue, approvalProcessCompleteYNOut out varchar2, nextApproversOut out nocopy ame_util.approversTable2, itemIndexesOut out nocopy ame_util.idList, itemClassesOut out nocopy ame_util.stringList, itemIdsOut out nocopy ame_util.stringList, itemSourcesOut out nocopy ame_util.longStringList, productionIndexesOut out nocopy ame_util.idList, variableNamesOut out nocopy ame_util.stringList, variableValuesOut out nocopy ame_util.stringList, transVariableNamesOut out nocopy ame_util.stringList, transVariableValuesOut out nocopy ame_util.stringList);

37 38 39 40 41 42 43 44 45 46

The getNextApprovers3 procedure has the same functionality as  getNextApprovers2, but it also returns per­transaction  productions.  Use getNextApprovers3 when your application  enables per­approver and per­transaction productions, for  example to track eSignature requirements per approver and  transaction.  See also ame_api2.getAllApprovers3 and  ame_api2.getNextApprovers2.  

getNextApprovers4 Syntax
procedure getNextApprovers4(


Appendix A API Functional Specifications 63

1 2 3 4 5 6 7 8

applicationIdIn in number, transactionTypeIn in varchar2, transactionIdIn in varchar2, flagApproversAsNotifiedIn in varchar2 default ame_util.booleanTrue, approvalProcessCompleteYNOut out varchar2, nextApproversOut out nocopy ame_util.approversTable2);

9 10 11 12 13 14 15
16 17 18 19 20 21

The getNextApprovers4 procedure has the same functionality as  getNextApprovers1, but it omits per­item outputs.  This is the  lowest­overhead getNextApprovers[n] procedure.  See also  ame_api2.getAllApprovers7 and ame_api2.getNextApprovers1.  

getPendingApprovers Syntax

procedure getPendingApprovers( applicationIdIn in number, transactionTypeIn in varchar2, transactionIdIn in varchar2, approvalProcessCompleteYNOut out varchar2, approversOut out nocopy ame_util.approversTable2);

22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
37 38 39 40 41 42

The getPendingApprovers procedure outputs in approversOut  the approvers with approver_category  ame_util.approvalApproverCategory and approval_status  ame_util.notifiedStatus.  These are the approvers who must  approve before the input transaction’s approval process will  continue to the next stage.  If approvalProcessCompleteYNOut is  ame_util.booleanTrue, the transaction’s approval process is  complete.  If approvalProcessCompleteYNOut is  ame_util.booleanFalse and approversOut.count is zero, the  application should call one of the getNextApprovers[n]  procedures, and notify the approvers returned by that  procedure.  

getTransactionProductions Syntax
procedure getTransactionProductions( applicationIdIn in number, transactionTypeIn in varchar2, transactionIdIn in varchar2, variableNamesOut out nocopy ame_util.stringList, variableValuesOut out nocopy ame_util.stringList);

43 44

The getTransactionProductions procedure outputs all per­

Appendix A API Functional Specifications 64

  This API does not clear the state of the approval  process. transactionIdIn in varchar2.  If  clearChainStatusYNIn is ame_util. transactionIdIn in varchar2. transactionTypeIn in varchar2.   2 Appendix A API Functional Specifications 65 .approverRecord2.  This  procedure succeeds only if the approval_status field of  approverIn is null.  Calling initializeApprovalProcess  guarantees that subsequent calls to getAllApprovers1 will be  read only.1 1 2 3 4 5 6 7 8 9 10 transaction productions for the input transaction. transactionTypeIn in varchar2. recordApproverListIn in boolean default false).getAllApprovers3.  Use this API  when your application uses AME as a general­purpose  production­rule engine. the engine sets the approval process’ start  date to sysdate. use clearAllApprovals for that.booleanTrue. 29 30 31 32 33 34 35 36 37 38 39 40 41 Description The setFirstAuthorityApprover procedure sets the approver  represented by approverIn as the first chain­of­authority  approver in the chain of authority identified by the  action_type_id and group_or_chain_id fields of approverIn. if it has not already  done so.  setFirstAuthorityApprover Syntax procedure setFirstAuthorityApprover( applicationIdIn in number. AME clears the  target chain of authority’s approval status before making  approverIn the chain’s new first approver. approverIn in ame_util.   initializeApprovalProcess Syntax procedure initializeApprovalProcess( applicationIdIn in number.  See also ame_api2. clearChainStatusYNIn in varchar2). this API has the same effect as  getAndRecordAllApprovers.  Use this API to force  AME to generate a chain of authority that satisfies a given set of  rules. but that starts from an unusual first approver.  In particular.  When  recordApproverListIn is true. and all the approvers in the target chain of  authority also have null approval statuses. 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Description The initializeApprovalProcess procedure causes AME’s engine to  prepare a transaction’s approval process.

 and the same authority value as the  forwarder. the forwardee is also a chain–of–authority approver.approverRecord2 fields  as you care to specify. forwardeeIn in ame_util.  When you leave one or more of the fields  2 Appendix A API Functional Specifications 66 .emptyApproverRecord2). approverIn in ame_util. updateItemIn in boolean default false).apiInsertion.approverRecord2 default ame_util.approval_status.  When a chain­of­authority approver  forwards. approvalStatusIn in varchar2.approverRecord2 default ame_util.emptyApproverRecord2. occurrenceIn in number default null. transactionTypeIn in varchar2. the forwardee has the api_insertion value  ame_util. transactionTypeIn in varchar2.name value.  If the  approval_status value is ame_util.clearExceptionsStatus.approverRecord2. actionTypeIdIn in number default null.  Otherwise. transactionIdIn in varchar2. itemIdIn in varchar2 default null. and as many  other approver­distinguishing ame_util. forwardeeIn in ame_util. but it lets you identify  the target approver by their wf_roles. the  procedure clears the transaction’s exception log in AME without  changing any approver’s status.   updateApprovalStatus2 Syntax procedure updateApprovalStatus2( applicationIdIn in number. regardless of the approver  identified by approverIn. groupOrChainIdIn in number default null. transactionIdIn in varchar2.1 1 2 3 4 5 6 7 8 9 10 updateApprovalStatus Syntax procedure updateApprovalStatus( applicationIdIn in number.  If the approval­status value  indicates that the approver forwarded (with or without  approving). itemClassIn in varchar2 default null.  Use this API to update the state of a transaction’s  approval process when an approver responds to a notification  requesting approval. 42 43 44 45 46 47 Description The updateApprovalStatus2 procedure has the same  functionality as updateApprovalStatus. forwardeeIn identifies the forwardee. approverNameIn in varchar2. 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 Description The updateApprovalStatus procedure updates the approval  status of the approver identified by approverIn to  approverIn.

stringList default ame_util.emptyStringList.stringList default ame_util. forwardeesIn in ame_util. approverIn in ame_util.emptyStringList. itemClassIn in varchar2 default null. occurrenceIn in number default null.stringList default ame_util.approverRecord2. and  has no present functionality. updateApprovalStatuses2 Syntax procedure updateApprovalStatuses2( applicationIdIn in number.approversTable2 default ame_util.updateApprovalStatus. transactionTypeIn in varchar2.  updateApprovalStatuses Syntax procedure updateApprovalStatuses( applicationIdIn in number. itemIdsIn in ame_util. and  has no present functionality. 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Description The updateApprovalStatuses procedure is currently a stub.emptyStringList. 45 46 47 Description The updateApprovalStatuses2 procedure is currently a stub.emptyApproversTable2). transactionTypeIn in varchar2. itemIdIn in varchar2 default null.stringList default ame_util. approvalStatusIn in varchar2. itemClassesIn in ame_util. groupOrChainIdIn in number default null.  Do not use it.stringList default ame_util. forwardeesIn in ame_util.emptyApproversTable2). itemIdsIn in ame_util. AME matches updates the status of the first occurrence of  the approver having an approval status that does not indicate  approval or forwarding. transactionIdIn in varchar2.emptyStringList. approvalStatusesIn in ame_util.stringList default ame_util.approversTable2 default ame_util.  Do not use it.emptyStringList. actionTypeIdIn in number default null.  See also  ame_api2. approverNameIn in varchar2. approvalStatusesIn in ame_util.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 null. transactionIdIn in varchar2.emptyStringList. 2 Appendix A API Functional Specifications 67 . itemClassesIn in ame_util. approvalStatusIn in varchar2.

suppressApprovers. 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Description The clearSuppression procedure clears an approver suppression  previously submitted by a call to suppressApprover or  suppressApprovers. 9 10 11 12 13 14 15 16 17 18 19 Description The getRuleDescription function returns the description of the  rule with ID ruleIdIn.suppressApprover and  ame_api3. transactionIdIn in varchar2).approverRecord2). transactionIdIn in varchar2. clearSuppression Syntax procedure clearSuppression( applicationIdIn in number.  2 Appendix A API Functional Specifications 68 .   clearSuppressions Syntax procedure clearSuppressions( applicationIdIn in number.  Use this API to reactivate an AME­generated  approver who has been suppressed from the input transaction’s  approver list.  Rule descriptions are at most 100 bytes  long.  See also ame_api3. as long as approverIn is an AME generated  approver. approverIn in ame_util. transactionTypeIn in varchar2.1 1 2 3ame_api3 4 5 6 7 8 getRuleDescription Syntax function getRuleDescription( ruleIdIn in varchar2) return varchar2. transactionTypeIn in varchar2. 34 35 36 Description The clearSuppressions procedure has the effect of  clearSuppression for all suppressed AME­generated approvers.

idList. groupNamesOut out nocopy ame_util. transactionTypeIn in varchar2.  ame_api3. 2 Appendix A API Functional Specifications 69 . transactionIdIn in varchar2).   getAllApprovalGroups Syntax procedure getAllApprovalGroups( groupIdsOut out nocopy ame_util.  Use this API to remove all previously inserted approvers from a  transaction’s approver list.approverRecord2).clearSuppression.   getApplicableRules1 Syntax procedure getApplicableRules1( applicationIdIn in number.stringList).  See also ame_api3.suppressApprovers. transactionTypeIn in varchar2. 20 21 22 23 24 25 26 27 28 29 Description The clearInsertions procedure has the effect of clearInsertion for  all inserted approvers in the input transaction’s approver list.suppressApprover. 30 31 32 33 34 35 36 37 Description The getAllApprovalGroups procedure outputs all current AME  approval groupsin ascending order of their names. approverIn in ame_util. and ame_api3.   clearInsertion Syntax procedure clearInsertion( applicationIdIn in number.1 1 2 3 4 5 6 7 8 9 See also ame_api3.clearInsertion.  clearInsertions Syntax procedure clearInsertions( applicationIdIn in number. transactionIdIn in varchar2.  Use this API to remove an  inserted approver from a transaction’s approver list. 10 11 12 13 14 15 16 17 18 19 Description The clearInsertion procedure removes the input approver from  the input transaction’s approver list. transactionTypeIn in varchar2.

transactionIdIn in varchar2.   transactionTypeIn in varchar2.stringList). Description The getApplicableRules2 procedure outputs in  ruleDescriptionsOut the descriptions of the rules that apply to  the input transaction.idList. transactionTypeIn in varchar2.  This procedure is useful to  construct a displayable list of descriptiosn of applicable rules. getApplicableRules3 Syntax procedure getApplicableRules3(   applicationIdIn in number.  See also ame_api3.   getApplicableRules2 Syntax procedure getApplicableRules2( applicationIdIn in number.getApplicableRules3.  Use this API  when you only need the rule IDs.1 1 2 transactionIdIn in varchar2.  where each rule description hyperlinks to a more detailed  description of the rule (generated by one of the  2 Appendix A API Functional Specifications 70 .idList).getApplicableRules2 and getApplicableRules3. 3 4 5 6 7 8 9 10 11 12 13 Description The getApplicableRules1 procedure outputs in ruleIdsOut the  IDs of the rules that apply to the input transaction.   transactionIdIn in varchar2. 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35   ruleDescriptionsOut out nocopy ame_util.stringList). ruleIdsOut out nocopy ame_util.getApplicableRules1 and  ame_api3.  Use this API when you only need the rule  descriptions.   ruleIdsOut out nocopy ame_util. Description The getApplicableRules3 procedure outputs in ruleIdsOut and  ruleDescriptionsOut the IDs and descriptions of the rules that  apply to the input transaction.  See also  ame_api3.   ruleDescriptionsOut out nocopy ame_util.

  An attribute is always  associated with an item classes. so it is not necessary to input the item class.  For all attribute types  other than currency attributes. 9 10 11 12 13 14 15 16 17 18 19 20 21 22 Description The getApprovalGroupId procedure outputs in groupIdOut the  ID of the approval group with the name groupNameIn. transactionTypeIn in varchar2.getRuleDetails[n] procedures). attributeNameIn in varchar2.   getApprovalGroupId Syntax procedure getApprovalGroupId( groupNameIn ame_util. attributeValue1Out out varchar2. and attributeValue2Out and  attributeValue3Out are null.  See also  ame_api3.  For currency attributes.  If the attribute pertains to the header item class. 2 Appendix A API Functional Specifications 71 . 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 Description The getAttributeValue procedure outputs in attributeValue1Out.getApplicableRules1. attributeValue2Out is the  General Ledger currency code. ame_api3. for the input transaction. attributeValue1Out contains the  attribute’s value.   Note: Do not call this api from within a function which is likely  to be called from an attribute which could itself be interrogated  by the called function otherwise a loop condition will exist.  attributeValue1Out is the amount. itemIdIn in varchar2.1 1 2 3 4 5 6 7 8 ame_api3. itemIdIn should  have the same value as transactionIdIn.  and the three ame_api3.  attributeValue2Out. and attribute names are unique  across item classes. groupIdOut out nocopy number). attributeValue2Out out varchar2. and attributeValue3Out the values of the  attribute with the name attributeNameIn for the item with ID  itemIdIn. attributeValue3Out out varchar2). and attributeValue3Out is the  General Ledger conversion type.stringType. getAttributeValue Syntax procedure getAttributeValue( applicationIdIn in number.getRuleDetails[n] procedures.getApplicableRules1. transactionIdIn in varchar2.

longStringList.longestStringList). 2 Appendix A API Functional Specifications 72 . groupIdIn in number. lowerLimitOut out nocopy varchar2. memberDisplayNamesOut out nocopy ame_util. and transactionTypeIn default  null. attributeh4 DescriptionOut out nocopy varchar2. transactionIdIn in varchar2 default null.longStringList). 15 16 17 18 19 20 21 22 23 24 25 26 Description The getConditionsDetails procedure outputs various descriptive  details about the condition with ID conditionIdIn.  If the group is  dynamic. these three inputs must identify the transaction for  which AME should calculate the group’s membership.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 getConditionDetails Syntax procedure getConditionDetails( conditionIdIn in number.   getGroupMembers2 Syntax procedure getGroupMembers2( applicationIdIn in number default null. the ID must be for a static approval group. attributeNameOut out nocopy varchar2. memberDisplayNamesOut out nocopy ame_util. transactionIdIn in varchar2 default null. currencyCodeOut out nocopy varchar2. getGroupMembers1 Syntax procedure getGroupMembers1( applicationIdIn in number default null. memberNamesOut out nocopy ame_util. groupIdIn in number.longStringList). 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 Description The getGroupMembers procedure outputs the display names of  the members of the AME approval group with ID groupIdIn. transactionTypeIn in varchar2 default null. includeUpperLimitOut out nocopy varchar2. upperLimitOut out nocopy varchar2. transactionTypeIn in varchar2 default null.  If  applicationIdIn. allowedValuesOut out nocopy ame_util. includeLowerLimitOut out nocopy varchar2. transactionIdIn. attributeTypeOut out nocopy varchar2.

stringList).idList.orig_system and wf_roles.  getGroupMembers3 Syntax procedure getGroupMembers3( applicationIdIn in number default null. 2 Appendix A API Functional Specifications 73 . memberOrigSystemIdsOut out nocopy ame_util.  See  also ame_api3. transactionIdIn in varchar2 default null. memberOrderNumbersOut out nocopy ame_util.getGroupMembers1. but it also outputs the members’ order  numbers. memberNamesOut out nocopy ame_util. transactionIdIn in varchar2 default null. but it also outputs the group members’  wf_roles. groupIdIn in number.  See also ame_api3.longStringList. 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Description The getGroupMembers3 procedure has the same functionality as  getGroupMembers2. 34 35 36 37 38 39 40 41 42 Description The getGroupMembers4 procedure has the same functionality as  getGroupMembers3.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Description The getGroupMembers2 procedure has the same functionality as  getGroupMembers.  See also ame_api3. memberNamesOut out nocopy ame_util.orig_system_id values. memberDisplayNamesOut out nocopy ame_util.getGroupMembers2.name values.idList. but it also outputs the members’  wf_roles. transactionTypeIn in varchar2 default null. memberOrigSystemsOut out nocopy ame_util.longStringList.longStringList). transactionTypeIn in varchar2 default null.   getItemClasses Syntax procedure getItemClasses( applicationIdIn in number default null.longStringList.idList. memberDisplayNamesOut out nocopy ame_util. memberOrderNumbersOut out nocopy ame_util. groupIdIn in number.getGroupMembers3.   getGroupMembers4 Syntax procedure getGroupMembers4( applicationIdIn in number default null.

  That is. itemClassNameOut out varchar2). itemClassIdsOut out nocopy ame_util. 21 22 23 24 25 26 27 28 29 30 31 32 Description The getItemClassName procedure outputs in  itemClassNameOut the name of the item class with the ID  itemClassIdIn. transactionIdIn in varchar2 default null. oldApproversOut out nocopy ame_util.approversTable2). 33 34 35 36 37 38 Description The getOldApprovers procedure outputs in oldApproversOut  the approver list that AME calculated most recently for the input  transaction. getOldApprovers Syntax procedure getOldApprovers( applicationIdIn in number.stringList). transactionTypeIn in varchar2. itemClassIdOut out number). itemClassNamesOut out nocopy ame_util. getItemClassId Syntax procedure getItemClassId( itemClassNameIn in varchar2.1 1 2 3 4 transactionTypeIn in varchar2 default null. 13 14 15 16 17 18 19 20 Description The getItemClassId procedure outputs in itemClassIdOut the  item­class ID of the item class with the name itemClassNameIn.  This approver list may not be the transaction’s  current list. transactionIdIn in varchar2.idList. 5 6 7 8 9 10 11 12 Description The getItemClasses procedure outputs the IDs and names of the  item classes used by the input transaction. simultaneous calls to getAllApprovers1 and  getOldApprovers could return different approver lists (and the  2 Appendix A API Functional Specifications 74 . getItemClassName Syntax procedure getItemClassName( itemClassIdIn in number.

actionTypeDescriptionsOut out nocopy ame_util.stringList. ruleDescriptionOut out nocopy varchar2.longestStringList.  See  also the getApplicableRules[n] procedures.stringList. Description The getRuleDetails1 procedure outputs various descriptive  details about the rule with ID ruleIdIn. ruleTypeOut out nocopy varchar2.  This  API is a deprecated routine available only for the sake of  backwards compatibility. conditionIdsOut out nocopy ame_util. getRuleDetails2 Syntax procedure getRuleDetails2( ruleIdIn in number. 31 32 33 34 35 36 37 38 39 40 41 Description The getRuleDetails2 procedure has the same functionality as  getRuleDetails1.idList. actionTypeNamesOut out nocopy ame_util.1 1 2 3 4 5 6 7 8 9 10 11 12 13 list returned by getOldApprovers would then be outdated).stringList. ruleDescriptionOut out nocopy varchar2. but it outputs condition descriptions rather than  condition IDs.   actionDescriptionsOut out nocopy ame_util. actionTypeNamesOut out nocopy ame_util. ruleTypeOut out nocopy varchar2.stringList).getRuleDetails1. actionTypeDescriptionsOut out nocopy ame_util.stringList).   getRuleDetails1 Syntax procedure getRuleDetails1( ruleIdIn in number. conditionDescriptionsOut out nocopy ame_util. getRuleDetails3 Syntax procedure getRuleDetails3( ruleIdIn in number.  See also ame_api3. ruleTypeOut out nocopy varchar2.stringList. ruleDescriptionOut out nocopy varchar2. 2 Appendix A API Functional Specifications 75 . 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30   actionDescriptionsOut out nocopy ame_util.  Use getRuleDetails1 in  connection with one of the getApplicableRules procedures.

conditionDescriptionsOut out nocopy ame_util. but it outputs condition ID and descriptions.   2 Appendix A API Functional Specifications 76 . it contains the  IDs of the rules requiring the approver having the input source  value.approverRecord2 source field in approverSourceIn into  a source designator in sourceTypeOut and a possibly empty rule­ ID list in ruleIdsOut. 34 35 36 37 38 39 40 41 Description The parseApproverSource procedure parses the  ame_util. approverIn in ame_util. insertApprover Syntax procedure insertApprover( applicationIdIn in number. sourceTypeOut out varchar2.getRuleDetails2.  Use this API to determine (and optionally display) the  reason an approver occurs in a transaction’s approver list.1 1 2 3 4 5 6 7 conditionIdsOut out nocopy ame_util. conditionHasLOVsOut out nocopy ame_util.stringList.   actionDescriptionsOut out nocopy ame_util.idList. 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 Description The getRuleDetails3 procedure has the same functionality as  getRuleDetails1. transactionIdIn in varchar2.stringList.  See also ame_api3.charList.   parseApproverSource Syntax procedure parseApproverSource( approverSourceIn in varchar2.longestStringList. actionTypeNamesOut out nocopy ame_util. insertionIn in ame_util.stringList).idList). positionIn in number.  and indicates whether each condition has a list of allowed values. transactionTypeIn in varchar2. ruleIdsOut out nocopy ame_util.getAvailableInsertions. actionTypeDescriptionsOut out nocopy ame_util. 23 24 25 26 27 28 29 30 31 32 33 Description The insertApprover procedure inserts approverIn into the input  transaction’s approver list at the approver­list index positionIn  using the insertion parameter and order relation in insertionIn.  See also ame_api3.  When the list is non­empty.insertionRecord2).approverRecord2.

 the target approver’s status is set to  ame_util.idList. approverIn in ame_util.  If  approverIn matches a rule­generated approver from the  transaction’s approver list and the mandatory boolean attribute  ALLOW_DELETING_RULE_GENERATED_APPROVERS has  the value ’true’. 27 28 29 30 31 32ame_api4 33 34 35 36 37 38 39 40 41 Description The suppressApprovers procedure has the same effect as  suppressApprover. 2 Appendix A API Functional Specifications 77 .   suppressApprovers Syntax procedure suppressApprovers( applicationIdIn in number. the approver is deleted (undoing the insertion  entirely).idList. memberPersonIdsOut out nocopy ame_util. groupIdIn in number. transactionTypeIn in varchar2. approverIn in ame_util. memberOrderNumbersOut out nocopy ame_util.  See  also ame_api3.suppressedStatus.1 1 2 3 4 5 6 7 suppressApprover Syntax procedure suppressApprover( applicationIdIn in number.approverRecord2).approversTable2). transactionIdIn in varchar2. transactionIdIn in varchar2.  If approverIn matches an inserted  approver. transactionIdIn in varchar2. but for each approver in approversIn. 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 Description The suppressApprover procedure suppresses approverIn from  the input transaction’s approver list.suppressApprover.  The approver must match  an approver in the transaction’s approver list according to the  comparison rules explained earlier in this appendix. transactionTypeIn in varchar2.   getGroupMembers Syntax getGroupMembers( applicationIdIn in number. transactionTypeIn in varchar2.

transactionTypeIn in varchar2.1 1 memberUserIdsOut out nocopy ame_util.idList). transactionIdIn in varchar2. transactionTypeIn in varchar2.   ClearItemClassApprovals2 Syntax clearItemClassApprovals2 (applicationIdIn in number.groupNameOut out nocopy ame_util. itemIdIn in varchar2 default null). transactionIdIn in varchar2. clearItemClassApprovals1 Syntax clearItemClassApprovals1 (applicationIdIn in number. itemClassNameIn in varchar2. 2 3 4 5ame_api5 6 7 8 9 10 11 12 13 Description  The API will return the approval group members' person id or  user id and their corresponding order numbers. 14 15 16 17 18 19 20 21 22 23 24 Description The clearItemClassApprovals1 procedure clears a  transaction’s approval­process state for the given item id. 29 30 31 32 33 34 getApprovalGroupName Syntax getApprovalGroupName (groupIdIn in number .stringType). 25 26 27 28 Description  Same as ClearItemClassApprovals1 but the item class name has to be passed instead of item class id. 2 Appendix A API Functional Specifications 78 . itemClassIdIn in number. itemIdIn in varchar2 default null).

availableInsertionsOut out nocopy ame_util2.booleanFalse . transactionIdIn in varchar2.getAvailableInsertions.updateApprovalStatus except that  it stores the user comments and the notification ids in the history  Appendix A API Functional Specifications 79 .notificationRecord default ame_util2. 22 23 24 25 26ame_api6 27 28 29 30 31 32 33 34 35 36 37 38 Description  The API will return the approvers and the corresponding  available insertions for these approvers for a given transaction. updateApprovalStatus  Syntax UpdateApprovalStatus (applicationIdIn in number. approverIn in ame_util. forwardeeIn in ame_util.activeApproversYNIn in varchar2 default ame_util. transactionTypeIn in varchar2.approversOut out nocopy ame_util.emptyApproverRecord2.  For more details see ame_api2.booleanFalse .insertionsTable3 ).emptyNotificationRecord. notificationIn in ame_util2.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 Description  The API will return the approval group’s name for a given  approval group id.coaInsertionsYNIn in varchar2 default ame_util.approversTable2 .transactionTypeIn in varchar2 .approverRecord2 default ame_util. 39 40 41 42 2 Description This is similar to the ame_api2.transactionIdIn in varchar2 . getAllApproversAndInsertions Syntax procedure getAllApproversAndInsertions (applicationIdIn in number .approverRecord2.approvalProcessCompleteYNOut out nocopy varchar2 . updateItemIn in boolean default false) .

 so you don’t need to validate approvers returned by  AME.approverRecord2 default ame_util.   2 Appendix A API Functional Specifications 80 . notificationIn in ame_util2.validateApprover. approverNameIn in varchar2. 31 32 33 34 35 36 37 Description The validateApprover function returns true if the approver is  valid. actionTypeIdIn in number default null.  AME’s APIs always return valid  approvers. itemClassIn in varchar2 default null.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 table. updateItemIn in boolean default false). approvalStatusIn in varchar2. updateApprovalStatus2 Syntax updateApprovalStatus2 (applicationIdIn in number. transactionIdIn in varchar2.  You should call validateApprover to validate an approver  you plan to insert into a transaction’s approver list.notificationRecord default ame_util2. occurrenceIn in number default null. forwardeeIn in ame_util. groupOrChainIdIn in number default null.approverRecord) return boolean. Consumer Teams using the AME Approval History table  should use this api.  See also  ame_api2.emptyNotificationRecord. 21 22 23 Description  Same as updateApprovalStatus but the approver details are  passed instead of the approver record as such. 24 25ame_api 26 27 28 29 30 validateApprover Syntax function validateApprover( approverIn in ame_util. itemIdIn in varchar2 default null. transactionTypeIn in varchar2. otherwise false.emptyApproverRecord2.

transactionTypeIn in varchar2 default null). 29 30 31 32 33 34 35 36 37 38 Description The deleteApprovers procedure suppresses the approvers  represented by approversIn in the input transaction’s approver  list.1 1 2 3 4 5 6 clearAllApprovals Syntax procedure clearAllApprovals( applicationIdIn in integer.  See also  ame_api2. transactionTypeIn in varchar2 default null). approversIn in ame_util. 2 Appendix A API Functional Specifications 81 . adminApproverOut out ame_util. transactionTypeIn in varchar2 default null).approverRecord. transactionIdIn in varchar2. 18 19 20 21 22 23 24 25 26 27 28 Description The deleteApprover procedure suppresses the approver  represented by approverIn in the input transaction’s approver  list.clearAllApprovers. transactionIdIn in varchar2.approversTable.suppressApprover. transactionIdIn in varchar2.approverRecord). 7 8 9 10 11 12 13 14 15 16 17 Description The clearAllApprovals procedure has the same functionality as  ame_api2.  See also ame_api3.  See also ame_api3.   getAdminApprover Syntax procedure getAdminApprover( applicationIdIn in integer default null. approverIn in ame_util.suppressApprovers.   deleteApprovers Syntax procedure deleteApprovers( applicationIdIn in integer.clearAllApprovers. transactionTypeIn in varchar2 default null.   deleteApprover Syntax procedure deleteApprover( applicationIdIn in integer.

 but  assigns them one of the approval_status values  ame_util.  See also  ame_api3. including rule–generated.9. transactionTypeIn in varchar2 default null. and repeated approvers. this behavior has changed.5. transactionTypeIn in varchar2 default null.  suppressed.  In AME 11.approverRecord identifying the administrative  administrator for the input transaction type.   getAvailableInsertions Syntax procedure getAvailableInsertions( applicationIdIn in integer. transactionIdIn in varchar2.  Your  code should treat these statuses as logically equivalent to  ame_util. approversOut out ame_util.   getAllApprovers Syntax procedure getAllApprovers( applicationIdIn in integer.  In AME  11. 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 Description The getAllApprovers procedure outputs the input transaction’s  current approver list.suppressedStatus and ame_util.approversTable).insertionsTable).getNextApprover will  skip approvers with either status when it iterates through the  approver list to find the first approver that has not yet approved. the AME engine  excluded from the approver list any approvers deleted by calls to  ame_api. positionIn in integer.deleteApprover(s). transactionIdIn in varchar2.1 1 2 3 4 5 6 7 8 9 10 11 12 Description The getAdminApprover procedure outputs an  ame_util. 2 Appendix A API Functional Specifications 82 .10.getAdminApprover. availableInsertionsOut out nocopy ame_util.  The approver list in  approversOut now includes deleted and repeated approvers.getAllApprovers[n] procedures.  The rows in approversOut  are indexed by consecutive ascending integers starting at one. or suppressed to account for the  value of the repeatedApprovers configuration variable. assuming the originating application has passed  such responses to AME via updateApprovalStatus or  updateApprovalStatus2.  See also the ame_api2.5.  The approval_status values in approversOut reflect each  approver’s most recent response to any request for approval they  have received.approvedStatus.repeatedStatus. inserted.  The ame_api.

  Unlike the  ame_api2.insertionRecord records representing the approver  insertions possible at the index positionIn in the transaction’s  current approver list.1 1 2 3 4 5 6 7 8 9 10 11 12 13 Description The getAvailableInsertions procedure outputs a list of  ame_util.getAvailableInsertions. transactionIdIn in varchar2. Description The getNextApprover procedure outputs the next approver that  should approve the input transaction. positionIn in integer.getNextApprover outputs the same approver each time  the procedure is called for a given transaction. transactionTypeIn in varchar2 default null.  Each orderType record indicates a  possible order type for an approver insertion at the index  positionIn in the transaction’s current approver list.  This  procedure is deprecated. 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41   nextApproverOut out ame_util. transactionIdIn in varchar2.  ame_api.  See also ame_api3. groupIdIn in number.  Use getAvailableInsertions instead. until the approver  approves the input transaction. transactionIdIn in varchar2.   getAvailableOrders Syntax procedure getAvailableOrders( applicationIdIn in integer.  See also ame_api3.approverRecord).ordersTable).   getNextApprover Syntax procedure getNextApprover( applicationIdIn in integer.orderType records.  getGroupMembers Syntax procedure getGroupMembers( applicationIdIn in integer. transactionTypeIn in varchar2 default null. availableOrdersOut out ame_util.getAvailableInsertions. 14 15 16 17 18 19 20 21 22 23 24 25 26 Description The getAvailableOrders procedure outputs a list of  ame_util. 2 Appendix A API Functional Specifications 83 . transactionTypeIn in varchar2.getNextApprovers[n] procedures.

 See also  ame_api3.  See also  ame_api3.  See also ame_api3. transactionIdIn in varchar2.orderRecord.   getOldApprovers Syntax procedure getOldApprovers( applicationIdIn in integer. memberUserIdsOut out nocopy ame_util.approversTable). positionIn in integer. transactionTypeIn in varchar2 default null. 15 16 17 18 19 20 21 22 23 24 25 26 27 Description The getOldApprovers procedure outputs the approver list that  AME calculated the last time it generated the input transaction’s  approver list.idList. 4 5 6 7 8 9 10 11 12 13 14 Description The getGroupMembers procedure outputs the members of the  approval group with ID groupIdIn. transactionTypeIn in varchar2 default null).approverRecord.approverRecord.getOldApprovers. 28 29 30 31 32 33 34 35 36 37 38 39 Description The insertApprover procedure inserts approverIn into the input  transaction’s approver list at the index positionIn using the  insertion parameter and order relation in insertionIn. transactionTypeIn in varchar2 default null).   insertApprover Syntax procedure insertApprover( applicationIdIn in integer. oldApproversOut out ame_util. transactionIdIn in varchar2.1 1 2 3 memberOrderNumbersOut out nocopy ame_util. transactionIdIn in varchar2 approverIn in ame_util.idList.   setFirstAuthorityApprover Syntax procedure setFirstAuthorityApprover( applicationIdIn in Integer. orderIn in ame_util.idList). 2 Appendix A API Functional Specifications 84 .insertApprover. approverIn in ame_util. memberPersonIdsOut out nocopy ame_util.getGroupMembers.

1 1 2 3 4 5 6 7 8
9 10 11 12 13 14 15

The setFirstAuthorityApprover procedure sets the first approver  for each chain of authority in the input transaction’s approver  list.  Thus if the approver list includes several chains of authority,  they will all start with approverIn.  See also  ame_api2.setFirstAuthorityApprover.  

updateApprovalStatus Syntax

procedure updateApprovalStatus( applicationIdIn in integer, transactionIdIn in varchar2, approverIn in ame_util.approverRecord, transactionTypeIn in varchar2 default null, forwardeeIn in ame_util.approverRecord default ame_util.emptyApproverRecord);

16 17 18 19 20 21 22 23 24 25 26 27
28 29 30 31 32 33 34 35

The updateApprovalStatus procedure updates the status of the  approver approverIn in the input transaction’s approver list.  A  given person ID or user ID can appear several times in a  transaction’s approver list, so AME uses all of the approver­ comparison fields that occur in ame_util.approverRecord to  match approverIn to an ame_util.approverRecord in the input  transaction’s approver list.  See also  ame_api2.updateApprovalStatus and  ame_api.updateApprovalStatus2.  

updateApprovalStatus2 Syntax
procedure updateApprovalStatus2( applicationIdIn in integer, transactionIdIn in varchar2, approvalStatusIn in varchar2, approverPersonIdIn in integer default null, approverUserIdIn in integer default null, transactionTypeIn in varchar2 default null, forwardeeIn in ame_util.approverRecord default     ame_util.emptyApproverRecord);

36 37 38 39 40 41 42 43

The updateApprovalStatus2 procedure has the same  functionality as updateApprovalStatus, except that it updates the  first ame_util.approverRecord in the input transaction’s  approver list that matches whichever of approverPersonIdIn and  approverUserIdIn is non­null, if the record’s status is not already  an approving or forwarding response.  See also 


Appendix A API Functional Specifications 85

1 1 2
ame_api2.updateApprovalStatus2 and  ame_api.updateApprovalStatus. 

3What New APIs Map to the 11.5.9 APIs? 4 5 6 7 8
Most of the ame_api routines are essentially wrappers for  ame_api2 or ame_api3 routines, with modifications to preserve  pre­existing ame_api functionality.  The following table tells you  which ame_api routine serves as a wrapper for a given ame_api2  or ame_api3 routine. ame_api Routine Equivalent ame_api2 or ame_api3  Routine  ame_api3.getRuleDescription ame_api2.validateApprover ame_api2.clearAllApprovals ame_api3.clearSuppression ame_api3.clearSuppressions ame_api3.clearInsertion ame_api3.clearInsertions ame_api3.suppressApprover ame_api3.suppressApprovers ame_api2.getAdminApprover ame_api2.getAllApprovers7 ame_api2.getAndRecordAllApprovers ame_api3.getApplicableRules1 ame_api3.getApplicableRules2 ame_api3.getApplicableRules3 ame_api2.getAllApprovers4

getRuleDescription validateApprover clearAllApprovals clearDeletion clearDeletions clearInsertion clearInsertions deleteApprover deleteApprovers getAdminApprover getAllApprovers getAndRecordAllApprovers getApplicableRules1 getApplicableRules2 getApplicableRules3 getApproversAndRules1


Appendix A API Functional Specifications 86


ame_api Routine

Equivalent ame_api2 or ame_api3  Routine 

getApproversAndRules2 getApproversAndRules3 getAvailableInsertions getAvailableOrders getConditionDetails getGroupMembers getNextApprover getOldApprovers getRuleDetails1 getRuleDetails2 getRuleDetails3 initializeApprovalProcess insertApprover setFirstAuthorityApprover updateApprovalStatus updateApprovalStatus2

ame_api2.getAllApprovers5 ame_api2.getAllApprovers6 ame_api3.getAvailableInsertions Not  available anymore ame_api3.getConditionDetails ame_api3.getGroupMembers4 ame_api2.getNextApprovers4 ame_api3.getOldApprovers ame_api3.getRuleDetails1 ame_api3.getRuleDetails2 ame_api3.getRuleDetails3 ame_api2.initializeApprovalProcess ame_api3.insertApprover ame_api2.setFirstAuthorityApprover ame_api2.updateApprovalStatus ame_api2.updateApprovalStatus2



Appendix A API Functional Specifications 87

1 1 2 3 4 Appendix B ame_util and  ame_util2 Packages 2 Appendix B ame_util Package 88 .

All of the AME data types your code requires are declared in  ame_util’s package specification (in the package­header file  ameoutil. and routines in ame_util can  be useful to originating applications. 2 Appendix B ame_util Package 89 . so that  changes to AME functionality do not break your code.   display_name varchar2(360). data types.  This section describes the data types you may  find useful.   orig_system varchar2(30).   approval_status varchar2(50).   group_or_chain_id integer.   action_type_id integer.   occurrence integer. it’s important that  you use appropriate ame_util features in your code.   authority varchar2(1).pkh). Many of the constants.   approver_category varchar2(1).   source varchar2(500).  In fact.   api_insertion varchar2(1).  This  appendix documents the ame_util features that your code should  incorporate where appropriate.1 1Overview  2 3 4 5 6 7 8Data Types 9 10 11 12 13ame_util 14approverRecord2 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 The ame_api2 and ame_api3 packages use the approverRecord2  record to represent an approver.  This type has the declaration type approverRecord2 is record(   name varchar2(320).   orig_system_id number.

   • ame_util.fyiApproverCategory indicates that this  • 2 Appendix B ame_util Package 90 .orig_system_id value.name%type.   action_type_order_number integer. display_name  This is the approver's wf_roles.   approver_category This field may contain either of two constants. ame_util.approvalApproverCategory indicates that this  occurrence of the approver must approve one or more items  of the transaction in whose approver list the record occurs. which essentially  identifies the approver uniquely in wf_roles.   item_order_number integer.   member_order_number integer. the orig_system ‘PER’ is for approvers originating in  the HRMS per_all_approvers_f table (that is.orig_system value.   group_or_chain_order_number integer.   approver_order_number integer).display_name value.   item_class_order_number integer.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32   item_class ame_item_classes.item_id%type.   item_id ame_temp_old_approver_lists. orig_system This is the approver's wf_roles.name value.   name This is the approver’s wf_roles. which  represents the system in which the approver originates.  The  combination of the approver's orig_system and orig_system_id  values also essentially identifies the approver uniquely in  wf_roles. Here are explanations of the allowed values and semantics of the  record’s fields.   orig_system_id This is the approver's wf_roles.  For  example. HR employees).   sub_list_order_number integer.

apiAuthorityInsertion indicates that the approver  was inserted into a chain of authority as a chain­of­authority  approver.)   • • authority This field may contain any of three constants: • • ame_util.oamGenerated indicates that the rules applying to  the transaction in whose approver list the approver occurs.  In this case the approver’s source field  contains a value that includes the requiring rules’ IDs. so that the chain should continue with the  superior of the inserted approver.  Others must be  generated by AME.postApprover identifies a post–approver.parseApproverSource in Appendix A.  The inserted approver  must be from an originating system consistent with the  action type that generated the chain of authority.authorityApprover identifies an authority  approver.preApprover identifies a pre–approver.getAllApprovers[n] and getNextApprovers[n]  2 Appendix B ame_util Package 91 .  required the approver’s presence in the transaction’s  approver list. • approval_status This field may contain any of twelve constants.  Some of these  represent possible approver responses to notifications requesting  approval. ame_util. ame_util.apiInsertion indicates that the approver was  inserted into a transaction’s approver list as an ad hoc  approver—that is. ame_util.  (See  ame_api3. and does not need to  approve any of the transaction’s items.  The items within the relevant transaction to  which the approver’s approval_status value applies are  identified by certain output arguments of the  ame_api[n].updateApprovalStatus and  ame_api2. an approver who is not part of a chain of  authority (even if the approver occurs between two chain­of­ authority approvers who belong to the same approver list).1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 occurrence of the approver should just receive an  informational notification describing the transaction in  whose approver list the record occurs. and so are allowed values in the approval­status input  arguments of the ame_api2.updateApprovalStatus2 procedures.  This  situation often arises when one chain­of­authority approver  forwards a request for approval to the inserted approver. api_insertion This field may contain any of three constants: • ame_util. ame_util.

updateApprovalStatus  and ame_api2.)  AME generates this status when the first­responder­ wins voting regime is in force for the group or chain  containing the approver. ame_util.   • ame_util.   ame_util.  (The originating  application decides what "timely" means.  (In the latter case.)  In this case. ame_util.clearExceptionsStatus should be passed to  ame_api[n]. or responded after  the first responder in the approval group or chain of  authority containing the approver.  You can pass this status to  ame_api2.updateApprovalStatus2.updateApprovalStatus and  ame_api2.exceptionStatus is sometimes returned by the  API routines when AME raises an unhandled exception  in the process of calculating a transaction’s approver list.updateApprovalStatus2.updateApprovalStatus2. ame_util.)  You can pass  this status to ame_api2.approvedStatus means the approver approved  one or more of the relevant transaction’s items. and also forwarded the notification  requesting approval. but the approver did not respond to the  notification in a timely fashion. the  originating application may wish to stop the  transaction’s workflow.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 procedures.updateApprovalStatus2 to clear a  transaction’s exception log when the transaction’s  workflow is restarted.updateApprovalStatus or  ame_api[n]. without approving  the items identified in the notification. without  forwarding the notification requesting approval.approveAndForwardStatus means the  approver approved one or more of the relevant  transaction’s items. ame_util.updateApprovalStatus2.  You can pass this  status to ame_api2.noResponseStatus means the originating  application sent the approver a notification requesting  approval.forwardStatus means the approver forwarded  the notification requesting approval. ame_util.  AME logs the approver's response and otherwise ignores  it.updateApprovalStatus2.  This is necessary when the  approver's status is ame_util.updateApprovalStatus and  ame_api2.  You  can pass this status to ame_api2.updateApprovalStatus and  • • • • • • 2 Appendix B ame_util Package 92 .beatByFirstResponderStatus means the  approver either has not responded.updateApprovalStatus or  ame_api2.  You cannot pass this status to  ame_api2.  (You cannot pass this status to  ame_api2.exceptionStatus.updateApprovalStatus or  ame_api2.

  For  inserted chain­of­authority approvers. and so never  output approvers with this status.  • • • • action_type_id For AME­generated approvers.  You can pass this status to  ame_api2. or  that their previous approval_status value was cleared.updateApprovalStatus and  ame_api2. the approver's action_type_id value would be 456.  For inserted ad­hoc approvers.nullInsertionActionTypeId.  The  ame_api2.  group_or_chain_id This field's semantics depend on whether the approver belongs  to an approval group or a chain of authority.  (See the documentation of  the repeatedApprovers configuration variable in Chapter  11 of the Oracle Approvals Management Implementation  Guide for details. immediately after the approver. ame_util. and that action type has the action­type ID  456.approvedStatus.suppressApprover(s) routines. this field contains the  same value that AME assigns to the AME­generated approvers  in the same chain.  Appendix B ame_util Package 93 .notifiedStatus means the originating  application has told AME that it has sent the approver a  notification. • ame_util.  In the former case.repeatedStatus means this occurrence of the  approver has been aggregated with one or more other  occurrences of the same approver.  For  example. a null approval_status  value) means the approver has not yet been notified. this field  contains the constant ame_util.  the field contains the ID that AME assigns to the approval group. ame_util.suppressedStatus means this occurrence of the  approver has been suppressed.updateApprovalStatus2. and—if the notification requested approval —the approver has not yet responded to it. this field contains the ID that  AME assigns to the action type that generated the approver.updateApprovalStatus2.getNextApprovers[n]  routines treat this status as equivalent to  ame_util. in the relevant  transaction's approver list.getNextApprovers[n] routines treat this status  as equivalent to ame_util.  ame_util. typically by a call to one  of the ame_api3.approvedStatus. and so never output approvers  with this status. ame_util.nullStatus (or better yet.  AME responds to it  by inserting the approver’s surrogate into the approver  list.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 2 ame_api2.)  The ame_api2. if a rule using the absolute­job­level action type  requires an approver.rejectStatus means the approver rejected one  or more of the items in the approver list of the relevant  transaction.

   item_id When an approver must approve or be notified about a single  item. this field contains the constant  ame_util.  For  example.   item_order_number AME uses this field internally to calculate the approver's  approver_order_number value.parseApproverSource to do so.nullInsertionGroupOrChainId. and  the second the value two. For example.  item_class This field contains the name of the item class of the item ID  identified by the approver's item_id field.getNextApprovers1  documentation in Appendix A for details.  occurrence The occurrence field indicates how many times the approver's  wf_roles. this field contains the ID of the item. use  ame_api3. this field contains the same value that AME assigns to  rule­generated approvers in the same chain.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 In the latter case. the action type generating the chain of  authority assigns its chains ascending positive integer  group_or_chain_id values.  AME development  will not support any code you write to parse the source field.  For inserted chain­of­authority  approvers. the dual­ chains­of­authority approval type generates two chains of  authority.   item_class_order_number AME uses this field internally to calculate the approver's  approver_order_number value.  When the approver  must approver or be notified about several items.   source This field's semantics may vary over time.name value has occurred in the approver's approval  group or chain of authority. starting at one. if an approver occurs twice in a given chain of  authority.  Approvers in the first chain have a group_or_chain_id  value of one.  Instead. and approvers in the second chain have a  group_or_chain_id value of two. including the approver proper. 2 Appendix B ame_util Package 94 . the first occurrence has the occurrence value one. and the list of items appears in certain API routines’ output  arguments instead. this field is  null.  For ad hoc inserted  approvers.  You should never  parse or interpret this field yourself.  See the ame_api2.

  AME uses the  approver_order_number to determine which approvers to return  in successive calls to the ame_api2.  See Chapter 11 of the implementation guide for details.   action_type_id integer. approver_order_number AME uses the six other order­number fields to calculate the  approver_order_number value by treating them as a six­tuple  and sorting them in lexicographic order.name%type.  approversTable2 AME’s API represents approver lists as arguments of type  approversTable2.   group_or_chain_id integer. insertionRecord2 The ame_api3.   item_id ame_temp_old_approver_lists. member_order_number AME uses this field internally to calculate the approver's  approver_order_number value.getAvailableInsertions procedure uses the  insertionRecord2 record to represent a possible approver  insertion.  Objects of this type should always be indexed by  consecutive ascending integers starting at one.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 sub_list_order_number AME uses this field internally to calculate the approver's  approver_order_number value. action_type_order_number AME uses this field internally to calculate the approver's  approver_order_number value. which is a PL/SQL table of approverRecord2  records. This type has the declaration. 2 Appendix B ame_util Package 95 .getNextApprovers[n]  routines. group_or_chain_order_number AME uses this field internally to calculate the approver's  approver_order_number value.item_id%type. type insertionRecord2 is record(   item_class ame_item_classes.

 the parameter should be ’3’.afterApprover means the insertee should  immediately follow the approver that the insertion parameter  identifies. with accompanying syntax and semantics rules  for the parameter and description fields.  ' where n is the index at which the insertion should take place.item_id || ame_util.  Here are brief explanations of each possible value for the  order_type field. action_type_id.fieldDelimiter || || || || || 2 Appendix B ame_util Package 96 .action_type_id ame_util. Fields that also Occur in approverRecord2 The item_class.item_class || ame_util. item_id.  api_insertion.  Here are explanations  of the other fields.fieldDelimiter approver. and description Fields The order_type field indicates the order relation that AME uses  to determine the insertion’s index in an approver list.   After an Approver The value ame_util.   Absolute Order The value ame_util.  In this case the parameter should be the string  representation of a positive integer between one and one more  than the number of approvers already in the approver list.name || ame_util. The order_type.fieldDelimiter approver.parameter%type.  For example. if the insertee should always be third in the  transaction's approver list.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40   order_type varchar2(50).absoluteOrder means the insertionRecord’s  parameter field should be interpreted as an absolute order  number.  The  description should have the syntax ame_util. group_or_chain_id. and authority fields have the same semantics here  as they do for the approverRecord2 type.  AME  recalculates the location each time it generates the approver list.absoluteOrderDescription || n || '. parameter.  In this case the parameter should have the syntax approver.   authority varchar2(1).   parameter ame_temp_insertions.fieldDelimiter approver.   api_insertion varchar2(1).   description varchar2(200)).

action_type_id || ame_util.item_id || ame_util.  In this case the parameter should  have the syntax ame_util.fieldDelimiter || approver.  In this case the parameter should have the syntax approver.item_id || ame_util.group_or_chain_id and the description should have the form ame_util.name || ame_util.firstAuthorityParameter || ame_util.occurrence and the description should have the form ame_util.firstPostApprover means the insertee should  be the first post–approver in the approver list for the item  identified by the parameter.fieldDelimiter || approver.display_name First Authority The value ame_util.action_type_id || ame_util.fieldDelimiter || approver.fieldDelimiter || approver.firstPostParameter || ame_util.fieldDelimiter || approver.item_class || ame_util.group_or_chain_id || ame_util.firstAuthorityDescription First Post­Approver The value ame_util.fieldDelimiter || approver.fieldDelimiter || approver.afterApproverDescription || approver.fieldDelimiter || approver.item_class || ame_util.  In this case the parameter should  have the syntax ame_util.fieldDelimiter || approver.firstAuthority means the insertee should be  the first chain–of–authority approver in the chain of authority  identified by the parameter.fieldDelimiter || approver.item_class || ame_util.fieldDelimiter || 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 2 Appendix B ame_util Package 97 .group_or_chain_id || ame_util.afterApproverDescription || approver.fieldDelimiter || approver.display_name Before an Approver The value ame_util.beforeApprover means the insertee should  immediately precede the approver that the insertion parameter  identifies.occurrence and the description should have the form ame_util.1 1 2 3 approver.

  In this case the parameter should  have the syntax ame_util.fieldDelimiter || approver.firstPreApproverDescription Last Post­Approver The value ame_util.  The getAvailableInsertions  procedure uses an argument of this type to represent the set of  possible approver insertions at a given index in an approver list.insertionRecord2 records.item_id and the description should have the form ame_util.  Objects of this type should always be indexed by consecutive  ascending integers starting at one.firstPostApproverDescription First Pre­Approver The value ame_util.  In this case the parameter should  have the syntax ame_util.item_class || ame_util.  In this case the parameter should  have the syntax ame_util.1 1 2 3 approver.item_id and the description should have the form ame_util.fieldDelimiter || approver.firstPreApprover means the insertee should  be the first pre–approver in the approver list for the item  identified by the parameter.lastPreApproverDescription 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 insertionsTable2 The insertionsTable2 type is a PL/SQL table of  ame_util.fieldDelimiter || approver.item_id and the description should the form ame_util.item_class || ame_util.item_class || ame_util.lastPostApproverDescription Last Pre­Approver The value ame_util.lastPreParameter || ame_util.lastPreApprover means the insertee should  be the last pre–approver in the approver list for the item  identified by the parameter.lastPostApprover means the insertee should  be the last post–approver in the approver list for the item  identified by the parameter.fieldDelimiter || approver.fieldDelimiter || approver.item_id and the description should have the form ame_util.   2 Appendix B ame_util Package 98 .fieldDelimiter || approver.firstPreParameter || ame_util.lastPostParameter || ame_util.

  person_id per_all_people_f.   authority varchar2(1).person_id value.10 the approverRecord type  represented an approver in an approver list.   last_name per_all_people_f. the first_name field contains the  approver's fnd_user.  If the person_id field is not null. it must contain a valid  per_all_people_f.) user_id  The user_id field is null if and only if the person_id field is not  null.approverRecord2  type.   first_name per_all_people_f. Below are explanations of the allowed values and semantics for  each field that does not occur in the ame_util.   first_name  If the person_id field is null.   group_or_chain_id integer.first_name value.   approval_type_id integer.   source varchar2(500)).   person_id The person_id field is null if and only if the user_id field is not  null. it must contain a valid  fnd_user.   approval_status varchar2(50).user_id%type.first_name%type.person_id%type.last_name%type.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 approverRecord  In AME versions prior to 11.  This data type is  available for backward compatibility.  If the user_id field is not null.  It has the declaration type approverRecord is record(   user_id fnd_user.user_id value.  Otherwise the first_name  field contains the approver's per_all_people_f.   occurrence integer.   api_insertion varchar2(1).  (The rules for the other fields are the same here as there.5. 2 Appendix B ame_util Package 99 .user_name value.

)  insertionRecord In AME versions prior to 11.  This type is  available for backward compatibility.  Below are explanations of the syntax  and semantics rules for each order type’s parameter and  description values.  parameter.5.  Absolute Order The absolute­order order relation has the same order_type. the last_name field is also null.   authority varchar2(1).  The ame_api package represents approver lists as  approversTable objects.   2 Appendix B ame_util Package 100 .parameter%type.  Otherwise the last_name field contains the approver's  per_all_people_f.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 last_name  If the person_id field is null.  See  “approverRecord2” above.   api_insertion varchar2(1).   approval_type_id The approval_type_id field has the same semantics as the  action_type_id field in an approverRecord2.insertionRecord  record represented a possible approver insertion. and description values here as for the  insertionRecord2 type.  It has the declaration.last_name value.10 the ame_util.description%type).  (This  type is available for backward compatibility.   description ame_temp_insertions.   parameter ame_temp_insertions. approversTable This data type is a PL/SQL table of approverRecord records.  Objects of this type should always be  indexed by consecutive ascending integers starting at one.  See the  description above of the insertionOrder2 type for explanations of  the available order types. type insertionRecord is record(   order_type varchar2(50). The api_insertion and authority fields have the same  interpretation here as for the approverRecord type.

1 1 2 3

After an Approver
The after­approver order type requires parameters with the  syntax {person_id,user_id}:n The string preceding the colon indicates the semantics of n,  where n is the person or user ID of the approver that the insertee  should follow.  For example, ’person_id:123’ indicates that the  insertee should follow the approver with the person ID 123.  The  description should have the form ame_util.afterApproverDescription || first_name || ‘ ‘ ||  last_name where first_name and last_name are the values that you would  assign to the first_name and last_name fields of an  approverRecord representing the inserted approver.   

5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

Before an Approver
The before­approver order type requires parameters of the same  form as those for the after­approver order type.  The description  should have the form ame_util.beforeApproverDescription || first_name || ‘ ‘ ||  last_name where first_name and last_name are the values that you would  assign to the first_name and last_name fields of an  approverRecord representing the inserted approver.  See “After  an Approver” above.  

First Authority
The first­authority order type does not use the parameter field.  The description should be ame_util.firstAuthorityDescription

First Post­Approver
The first post­approver order relation does not use the parameter  field.  The description should be  ame_util.firstPostApproverDescription

First Pre­Approver
The first pre­approver order relation does not use the parameter  field.  The description should be ame_util.firstPreApproverDescription

Appendix B ame_util Package 101

1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17Constants 18 19 20
Purpose approval status Name approveAndForwardStatus Description The approver approved and  forwarded. The approver approved without  forwarding. The approver’s approval group or  chain of authority had the first­ responder­wins voting regime, and  the approver was not the first  responder. When passed to  ame_api[n].updateApprovalStatus[ n], tells AME to clear an exception  raised by the transaction’s approval  process.  The following table lists and describes frequently used ame_util  constants, sorted first by purpose and then by alphabetical order.

Last Post­Approver
The last post­approver order relation does not use the parameter  field.  The description should be ame_util.lastPostApproverDescription

Last Pre­Approver
The last pre­approver order relation does not use the parameter  field.  The description should be ame_util.lastPreApproverDescription

The insertionsTable type is a PL/SQL table of insertionRecord  records. The ame_api.getAvailableInsertions procedure uses an  argument of this type to represent the set of possible approver  insertions at a given index in an approver list.  Objects of this  type should always be indexed by consecutive ascending  integers starting at one.  (This type is available for backward  compatibility.) 





Appendix B ame_util Package 102



Name exceptionStatus

Description The transaction’s approval process  raised an exception. The approver forwarded. The approver did not respond in  the time allowed by the originating  application.   The approver has been notified, and —if the approver must approve— has not yet responded. The approver has not yet been  notified.  The approver rejected. AME aggregated the approver with  another occurrence of the same  approver in the transaction's  approver list.   The originating application  suppressed the approver from the  transaction’s approver list.  The approver’s response is  required. The approver’s response is not  required. The approver is an inserted chain­ of­authority approver.  The approver is an ad hoc approver.  The approver is generated by  approval rules. ALLOW_REQUESTOR_APPROVA L.

forwardStatus noResponseStatus



rejectStatus repeatedStatus


approver  category



API insertion


apiInsertion oamGenerated

attribute names



Appendix B ame_util Package 103

1 Purpose Name allowEmptyGroupAttribute Description ALLOW_EMPTY_APPROVAL_GR OUPS EFFECTIVE_RULE_DATE FIRST_STARTING_POINT_PERSO N_ID JOB_LEVEL_NON_DEFAULT_STA RTING_POINT_PERSON_ID INCLUDE_ALL_JOB_LEVEL_APP ROVERS LINE_ITEM_STARTING_POINT_P ERSON_ID NON_DEFAULT_STARTING_POI NT_POSITION_ID NON_DEFAULT_POSITION_STR UCTURE_ID SECOND_STARTING_POINT_PER SON_ID SIMPLE_POS_NON_DEFAULT_ST ARTING_POINT_PERSON_ID SUPERVISORY_NON_DEFAULT_ STARTING_POINT_PERSON_ID TOP_POSITION_ID TOP_SUPERVISOR_PERSON_ID TRANSACTION_DATE TRANSACTION_REQUESTOR_PE RSON_ID TRANSACTION_REQUESTOR_US ER_ID effectiveRuleDateAttribute firstStartingPointAttribute jobLevelStartingPointAttribute includeAllApproversAttribute lineItemStartingPointAttribute nonDefStartingPointPosAttr nonDefPosStructureAttr secondStartingPointAttribute simplePosStartPointAttribute supStartingPointAttribute topPositionIdAttribute topSupPersonIdAttribute transactionDateAttribute transactionRequestorAttribute transactionReqUserAttribute 2 Appendix B ame_util Package 104 .

The approver should be inserted  right after the approver specified by  the insertion parameter. The approver should be inserted  right before the approver specified  by the insertion parameter.1 Purpose Name transactionOrgAttribute transactionGroupAttribute transactionReqPositionAttr Description TRANSACTION_ORG_ID TRANSACTION_GROUP_ID TRANSACTION_REQUESTOR_PO SITION_ID TRANSACTION_SET_OF_BOOKS_ ID The approver is a member of a  chain of authority. The approver should be the first  post­approver for the item_class  and item_id specified by insertion  parameter.  The approver should be the first  pre­approver for the item_class and  item_id specified by insertion  parameter. The approver should be inserted at  the approver­list index identified by  the insertion parameter. transactionSetOfBooksAttribute authority authorityApprover postApprover preApprover insertion order absoluteOrder afterApprover beforeApprover firstAuthority firstPreApprover firstPostApprover 2 Appendix B ame_util Package 105 . The approver should be the first  approver in the target chain of  authority. The approver is a member of a post­ approval approval group. The approver is a member of a pre­ approval approval group.

1 Purpose Name lastPreApprover Description The approver should be the last  pre­approver for the item_class and  item_id specified by insertion  parameter. the cost­center item class the header item class the line­item item class the FND_RESP originating system lastPostApprover item­class names costCenterItemClassName headerItemClassName lineItemItemClassName originating  system names fndRespOrigSystem fndUserOrigSystem perOrigSystem posOrigSystem pseudo­boolean  constants booleanAttributeFalse the FND_USR  originating system the PER originating system the POS originating system the false value for boolean  attributes the true value for boolean attributes a varchar2(1) pseudo­boolean  constant for false a varchar2(1) pseudo­boolean  constant for true the false value for boolean  configuration variables the true value for boolean  configuration variables Only the rejected item’s approval  booleanAttributeTrue booleanFalse booleanTrue no yes REJECTION_RES PONSE possible  continueAllOtherItems 2 Appendix B ame_util Package 106 . The approver should be the last  post­approver for the item_class  and item_id specified by insertion  parameter.

  recordDelimiter Syntax function recordDelimiter return varchar2.  Other items’  approval processes continue.1 Purpose values  Name Description process stops. continueOtherSubItems The header and rejected  subordinate items’ approval  processes stop. All items’ approval processes stop. 2 Appendix B ame_util Package 107 .  You  should only call this function in action­type handlers. 17 18 19 20 21 22 23 Description This function returns the field delimiter used by AME. StopAllItems 1 2Routines 3 4 5 6 7 8 Here are some frequently used ame_util routines. 9 10 11 12 13 14 15 16 Description This function returns the default value of the the adminApprover  configuration variable.  You should only call this function in  action­type handlers.  fieldDelimiter Syntax function fieldDelimiter return varchar2.   getAdminName Syntax function getAdminName( applicationIdIn in integer default null) return varchar2.

  copyApproversTable2 Syntax procedure copyApproversTable2( approversTable2In in approversTable2.1 1 2 3 4 5 6 7 8 Description This function returns the record delimiter used by AME. routineNameIn in varchar2. approverRecord2Out out nocopy approverRecord2).  You  should only call this function in action­type handlers. sourceInOut in out nocopy varchar2).   copyApproverRecord2 Syntax procedure copyApproverRecord2( approverRecord2In in approverRecord2. 27 28 29 30 31 32 33 34 35 36 Description This procedure copies the input approversTable2 to the output  approversTable2. and outputs the source value in place. exceptionNumberIn in integer. exceptionStringIn in varchar2). 19 20 21 22 23 24 25 26 Description This procedure copies the input approverRecord2 to the output  approverRecord2. 2 Appendix B ame_util Package 108 . 9 10 11 12 13 14 15 16 17 18 Description This procedure appends the input rule ID to the input source  value.  appendRuleIdToSource Syntax procedure appendRuleIdToSource( ruleIdIn in integer.  Use this function in  an action­type handler to build an approverRecord2’s source  value.  runtimeException Syntax procedure runtimeException( packageNameIn in varchar2. approversTable2Out out nocopy approversTable2).

user_comments varchar2(4000)).1 1 2 3 4 5 6ame_util2 7notificationRecord 8 9 10 11 12 Description All code that extends AME functionality should call  runtimeException.  The ame_api6 uses the notificationRecord This type has the  declaration type notificationRecord is record( notification_id number.  This routine logs runtime exceptions in the  AME exception log.insertionRecord2 except the position  2 Appendix B ame_util Package 109 . Objects of this  type should always be indexed by consecutive ascending  integers starting at one. type notificationTable is table of notificationRecord index by binary_integer. They are only to be used as default arguments where empty defaults are required. 13 14 15 16 17 18 19notificationTable 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 notification_id This is the notification id of the notification . */ emptyNotificationRecord notificationRecord. This datatype is pl/sql table of notificationRecord. and in the Workflow exception stack as  appropriate. user_comments       This is the comment made by the user while responding to a  notification . /* 38insertionRecord3 39 This is same as ame_util. emptyNotificationTable notificationTable. None of the empty[whatever] variables below should ever be overwritten.

30 completeNoApprovers constant varchar2(1) := 31 'X'. authority varchar2(1). item_class ame_item_classes. 26 completeFullyRejected constant varchar2(1) := 27 ame_util. 14 15 16insertionsTable3 17 18 19 20 21 position This denotes the position in the approval list. This datatype is pl/sql table of insertionRecord3. type insertionsTable3 is table of insertionRecord3 index by binary_integer. 32 notCompleted constant varchar2(1) := 33'W'. description varchar2(200)). 34 35     This is the new approval status introduced. 28 completePartiallyApproved constant varchar2(1) := 29 'P'. 2 Appendix B ame_util Package 110 . item_id ame_temp_old_approver_lists. api_insertion varchar2(1).parameter%type.booleanFalse. 36 reassignStatus constant varchar2(20) := 'REASSIGN'. This record is used to return the value in ame_api5. order_type varchar2(50). action_type_id integer. parameter ame_temp_insertions.name%type. Objects of this  type should always be indexed by consecutive ascending  integers starting at one.item_id%type.1 1 2 3 4 5 6 7 8 9 10 11 12 13 field. 22Constants 23      New constants added to denote the status for “approvalProcessCompleteYNOut”. group_or_chain_id integer.  getAllApproversAndInsertions type insertionRecord3 is record( position integer.booleanTrue. 24 completeFullyApproved constant varchar2(1) := 25 ame_util.

1 1 2 3 4 5 6 Appendix C The Action­Type­ Handler  Programming  Interface 2 Appendix C The Action­Type­Handler Programming Interface 111 .

  This section refers to the  data structure for convenience only.  9The ame_engine.approversTable2.) getActionTypeChainOrderMode Syntax function getActionTypeChainOrderMode( actionTypeIdIn in integer) return varchar2.  This appendix documents  the relevant ame_engine routines. which  is of type ame_util.engStApprovers. 23 24 25 26 27 28 29 30 31 32 33 34 Description Returns the chain­ordering mode of the action type with ID  actionTypeIdIn. ame_engine.1 1Overview  2 3 4 5 6 7 8 The ame_util and ame_engine PL/SQL packages define a  programming interface for action­type handlers. breaking your  code’s references to ame_engine.parallelChainsMode and ame_util.serialChainsMode.engStApprovers Data Structure 10 11 12 13 14 15 16 17Engine Functions 18 19 20 21 22 The engine stores and manipulates a transaction’s approver list  in a private data structure.engStApprovers.  The  ame_engine package provides a collection of routines that it uses  to exchange data with action­type handlers.  See Appendix B of  this guide for details about ame_util.  The ame_util  package defines a set of datatypes and utility routines.  The possible values are  ame_util.  You should not modify the  engine to access this data structure directly.  An authority handler typically uses this function to calculate the  group_or_chain_order_number values of the approvers it  generates. 2 Appendix C The Action­Type­Handler Programming Interface 112 .  getActionTypeVotingRegime Syntax function getActionTypeVotingRegime( actionTypeIdIn in integer) return varchar2. the  engine’s internal implementation may change.  (For one thing.

getAttributeIdByName Syntax function getAttributeIdByName( attributeNameIn in varchar2) return integer.firstApproverVoting.  The possible values are  ame_util.  An authority handler typically uses  this function to calculate the member_order_number values of  the approvers it generates. getAttributeName Syntax function getAttributeName( attributeIdIn in integer) return varchar2.  getHandlerActionTypeId Syntax function getHandlerActionTypeId return integer. ame_util.serializedVoting. and  ame_util. 13 14 15 16 17 18 19 Description Returns the name of the attribute with the ID attributeIdIn.consensusVoting.1 1 2 3 4 5 6 7 8 9 10 11 12 Description Returns the voting regime of the action type with ID  actionTypeIdIn. 20 21 22 23 24 25 Description Returns the ID of the attribute with the name attributeNameIn. 2 Appendix C The Action­Type­Handler Programming Interface 113 . 26 27 28 29 30 31 32 Description Returns the value of the RULE_EFFECTIVE_DATE attribute for  the transaction that the engine is currently processing. getEffectiveRuleDate Syntax function getEffectiveRuleDate return date.

  Typically a handler  calls this function to populate an ame_util.  It returns the  ID of the action type that uses the handler. 10 11 12 13 14 15 16 17 18 19 20 Description Only an action­type handler may call this function.approverRecord2  record’s action_type_id field.approverRecord2 record’s approval_status field. getHandlerAuthority Syntax function getHandlerAuthority return varchar2. getHandlerApprovalStatus Syntax function getHandlerApprovalStatus( approverIn in ame_util.approverRecord2 record’s action_type_order_number  field.1 1 2 3 4 5 6 7 8 9 Description Only an action­type handler may call this function.  Typically a handler calls this function to populate an  ame_util.  Typically  a handler calls this function to populate an  ame_util.  It returns the  order number of the action type that uses the handler.  A handler should only call this function if it  always generates approvers in a fixed sub­list.approverRecord2 record’s authority field.  It returns the  current approval status of the approver identified by approverIn. 30 31 32 33 34 35 36 Description Only an action­type handler may call this function.  It returns the  ame_util sub­list (authority) constant of the approvers that the  handler generates.  getHandlerActionTypeOrderNum Syntax function getHandlerActionTypeOrderNum return integer. 2 Appendix C The Action­Type­Handler Programming Interface 114 .approverRecord2) return varchar2. 21 22 23 24 25 26 27 28 29 Description Only an action­type handler may call this function.  Typically a  handler calls this function to populate an  ame_util.

34 35 36 37 38 39 40 Description Only an action­type handler may call this function.approverRecord2 record’s item_class field (using  ame_engine. and their item classes.)  A handler  might call this function when preparing to populate an  am_util.getItemClassName) or item_class_order_number  field (using ame_engine.  See also getHandlerItemClassId  above. when per­item evaluation is enabled. getHandlerItemClassName Syntax function getHandlerItemClassName return varchar2.  It returns the  name of the item class of the item whose approver list the engine  is currently constructing.getHandlerItemClassOrderNumber directly.  getHandlerItemClassOrderNumber Syntax function getHandlerItemClassOrderNumber return integer. differ for  header­level rules with conditions on subordinate­item­class  attributes.  It returns the  order number of the item class of the item whose approver list  the engine is currently constructing.  Typically a handler calls  this function to populate an ame_util.  It is  usually more efficient simply to call  ame_engine.  These items.  See also getHandlerItemClassId above.getHandlerItemClassName or  ame_engine.1 1 2 3 4 getHandlerItemClassId Syntax function getHandlerItemClassId return integer.  2 Appendix C The Action­Type­Handler Programming Interface 115 .approverRecord2 record’s item_class  field.getItemClassOrderNumber).  Typically a handler calls this function  to populate an ame_util.  It returns the  ID of the item class of the item whose approver list the engine is  currently constructing.  (This is not necessarily the ID of the item  class of the item that satisfies the rule that uses the handler’s  action type. 24 25 26 27 28 29 30 31 32 33 Description Only an action­type handler may call this function.approverRecord2 record’s  item_class_order_number field. 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 Description Only an action­type handler may call this function.

 the function  returns the occurrence value appropriate for adding the  approver to the end of the approver list in  ame_engine.1 1 2 3 4 getHandlerItemId Syntax function getHandlerItemId return integer.approverRecord2 record’s item_id field.  It returns the  ID of the item whose approver list the engine is currently  constructing.  Typically a handler calls this  function to populate an ame_util.approverRecord2 record’s  item_order_number field. 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 Description Only an action­type handler may call this function.  It returns the  occurrence value of the approver identified by the input  arguments (which should have the values of the corresponding  fields in the approver’s ame_util. groupOrChainIdIn in integer default null) return integer.  Typically a handler calls this function to populate  an ame_util.  Typically a handler calls this function to  populate an ame_util. actionTypeIdIn in integer default null.approverRecord2 record). itemIdIn in varchar2 default null.   2 Appendix C The Action­Type­Handler Programming Interface 116 .  getHandlerItemOrderNumber Syntax function getHandlerItemOrderNumber return integer.  getHandlerOccurrence Syntax function getHandlerOccurrence( nameIn in varchar2.approverRecord2 record’s  occurrence field.engStApprovers. 5 6 7 8 9 10 11 12 13 14 Description Only an action­type handler may call this function.  It returns the  order number of the item whose approver list the engine is  currently constructing. itemClassIn in varchar2 default null.  See also getHandlerItemClassId  above.  If  any of the default­null input arguments is null. 31 32 33 34 35 36 37 38 39 40 41 Description Only an action­type handler may call this function.  See also  getHandlerItemClassId above.

  It returns the  order number of the sub­list that the engine is currently  populating.) getHeaderAttValue2 Syntax function getHeaderAttValue2( attributeNameIn in varchar2) return varchar2 34 35 36 37 38 39 40 41 2 Description This function returns the value of the header­level attribute with  the name attributeNameIn.getHeaderAttValue2 (see below) instead.  For header­level currency  attributes.approverRecord2 record’s sub_list_order_number field.1 1 2 3 4 getHandlerSublistOrderNum Syntax function getHandlerSublistOrderNum return integer. but it would have to fetch the  attribute’s ID (using ame_engine. for the transaction that the engine is  currently processing. 5 6 7 8 9 10 11 12 13 14 Description Only an action­type handler may call this function.  getHeaderAttValue1 Syntax function getHeaderAttValue1( attributeIdIn in integer) return varchar2.  A handler could call this function to fetch the value of  one of its required attributes.  The function only works for attributes that  are not of the currency attribute type.  (See  “Creating an Action Type” below for details.  The function only works for attributes that  are not of the currency attribute type. use one of the getHeaderAttValues[n] procedures (see  below).  Typically a handler calls this function to fetch the value  of one of its required attributes.  Typically a handler calls this function to populate an  ame_util.  For header­level currency  attributes.  Typically a handler would take the direct route by calling  ame_engine.  Note that  any attribute referenced by your handler must be listed among  the corresponding action type’s required attributes. for the transaction that the engine is  currently processing.  Note that any attribute  Appendix C The Action­Type­Handler Programming Interface 117 . 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Description This function returns the value of the header­level attribute with  the ID attributeIdIn. use one of the getHeaderAttValues[n] procedures (see  below).getAttributeIdByName) first.

1 1 2 3 4 5 6 7 8 referenced by your handler must be listed among the  corresponding action type’s required attributes. 25 26 27 28 29 30 31 32 33 34 35 36 Description This function returns the order number of the item class with ID  itemClassIdIn. 2 Appendix C The Action­Type­Handler Programming Interface 118 .) getItemClassId Syntax function getItemClassId( itemClassNameIn in varchar2) return integer.   getItemClassName Syntax function getItemClassName( itemClassIdIn in integer) return varchar2. itemIdIn in varchar2) return integer.approverRecord2 record’s  item_class_order_number field. 17 18 19 20 21 22 23 24 Description This function returns the name of the item class with ID  itemClassIdIn. for the transaction type of the transaction that the  engine is currently processing. 9 10 11 12 13 14 15 16 Description This function returns the ID of the item class with the name  itemClassNameIn. getItemClassOrderNumber Syntax function getItemClassOrderNumber( itemClassIdIn in integer) return integer.  (See “Creating  an Action Type” below for details.  Typically a handler calls this  function to populate an ame_util.   getItemOrderNumber Syntax function getItemOrderNumber( itemClassNameIn in varchar2.

31 32 33 34 35 Description This procedure appends the record approverIn to the end of the  approver list in ame_engine.  Typically a  handler calls this procedure to add an approver to the end of the  approver list.  Typically a handler calls this function to populate an  ame_util.  getSublistOrderNum Syntax function getSublistOrderNum( itemClassNameIn in varchar2. for the item class with the name itemClassNameIn.  Typically a handler calls this function to populate populate an  ame_util.   getRuntimeGroupCount Syntax function getRuntimeGroupCount( groupIdIn in integer) return integer.  26Engine Procedures 27 28 29 30 addApprover Syntax procedure addApprover( approverIn in ame_util. 11 12 13 14 15 16 17 18 19 Description This function returns the number of static members of the  approval group with ID groupIdIn.approverRecord2).engStApprovers. 2 Appendix C The Action­Type­Handler Programming Interface 119 . authorityIn in varchar2) return integer.approverRecord2 record’s item_order_number field. 20 21 22 23 24 25 Description This function returns the sub­list order number for the sub­list  identified by the ame_util sub­list (authority) constant  authorityIn.1 1 2 3 4 5 6 7 8 9 10 Description This function returns the order number for the item with the ID  itemIdIn in the item class with the name itemClassNameIn.approverRecord2 record’s sub_list_order_number field.

sourceOut out nocopy varchar2). votingRegimesOut out nocopy ame_util. origSystemOut.  (For details about approver­group voting regimes. 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Description This procedure sorts the approver­group IDs groupIdsInOut in  place by group order number first and then by group ID. the output  arguments’ values are null.  If the  originating application has inserted a starting point (first  approver) for the chain of authority that the engine is currently  constructing. see Appendix  C of the implementation guide. orderNumbersOut out nocopy ame_util.  Typically an approver­group handler uses this  procedure to populate the group_or_chain_order_number and  member_order_number fields of the ame_util.  getHandlerCOAInsertion Syntax procedure getHandlerCOAInsertion( nameIn in varchar2. origSystemIdOut. origSystemOut out nocopy varchar2. actionTypeIdIn in integer. displayNameOut out nocopy varchar2. itemIdIn in varchar2.  If no starting point has been inserted. groupOrChainIdIn in integer. itemIdIn in varchar2. this procedure returns the inserted approver in  nameOut.charList). 2 Appendix C The Action­Type­Handler Programming Interface 120 . and it returns the appropriate source­field  value for the returned approver’s ame_util.  It then  returns the groups’ order numbers and voting regimes in a  consistent order. 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Description Only an action­type handler may call this procedure.) getHandlerCOAFirstApprover Syntax procedure getHandlerCOAFirstApprover( itemClassIn in varchar2. itemClassIn in varchar2. origSystemIdOut out nocopy integer.idList. nameOut out nocopy varchar2.idList.approverRecord2  record.1 1 2 3 4 5 6 getApprovalGroupConfigs Syntax procedure getApprovalGroupConfigs( groupIdsInOut in out nocopy ame_util. and  displayNameOut.approverRecord2  records representing the approvers in the input approval groups.

approverRecord2 record.  If no such  insertion has occurred. and displayNameOut. origSystemIdOut out nocopy integer.idList.  Second. origSystemIdOut. and the action parameters of the  rule’s action in parametersOut and parameterTwosOut.  For  each rule ID.   getHandlerRules Syntax procedure getHandlerRules( ruleIdsOut out nocopy ame_util. sourceOut out nocopy varchar2). 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 Description Only an action­type handler may call this procedure. parameterTwosOut out nocopy ame_util.1 1 2 3 4 5 6 7 8 9 actionTypeIdIn in integer.)  Typically a handler uses getHandlerRules for several purposes. the approver_category field of the  approver’s ame_util. the output arguments’ values are null. origSystemOut out nocopy varchar2.stringList).approverRecord2.approverRecord2). and it  returns the appropriate source­field value for the returned  approver’s ame_util. groupOrChainIdIn in integer. this  procedure returns the inserted approver in nameOut.  It returns  in ruleIdsOut the IDs of the rules that apply to the transaction  the engine is currently processing. approverCategoriesOut out nocopy ame_util. parametersOut out nocopy ame_util. it uses the action parameters to compute the set of  approvers the rules require.   Use getHandlerRules2 if the actions processed by the handler  2 Appendix C The Action­Type­Handler Programming Interface 121 .  If the  originating application has inserted a chain­of­authority  approver into the chain of authority immediately after the input  approver (identified by all of the input arguments). it uses the rule usages’  approver categories to determine each required approver’s  approver category (that is.  First.  origSystemOut. approvalStatusIn in varchar2. displayNameOut out nocopy varchar2.  (If an  applicable rule has several actions of the same action type.stringList. nameOut out nocopy varchar2.  Third. the procedure also returns in  approverCategoriesOut the approver category of the transaction  type’s rule usage for the rule. which use the action type.charList. they  appear in separate rows in the output arguments. 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 Description Only an action­type handler may call this procedure. occurrenceIn in integer. it uses the rule  IDs to populate the source field of each approver’s  ame_util.

name of a target approver. listModParameterOnesOut out nocopy ame_util.  Otherwise.  Each row in listModParameterOnesOut  contains one of the constants ame_util.  Each row in listModParameterTwosOut  contains the wf_roles. setRuleApplied Syntax procedure getHandlerRules3( ruleIndexIn in integer).1 1 2 3 4 5 6 7 8 only have one parameter each. Each row in the  two listModParameter[n]Out arguments represents a list­ modification condition.finalApprover.idList. ruleIndexesOut out nocopy ame_util.charList. this procedure functions just like  getHandlerRules.longStringList).anyApprover and  ame_util. getHandlerRules2 Syntax procedure getHandlerRules2( ruleIdsOut out nocopy ame_util. parametersOut out nocopy ame_util. listModParameterTwosOut out nocopy ame_util.idList. parametersOut out nocopy ame_util.  The  ruleIndexesOut  contains the indeces of the rule ids (ruleIdsOut)  in the rules data structure used by the engine.stringList.stringList.stringList). 2 Appendix C The Action­Type­Handler Programming Interface 122 .  It functions in much the same way as  getHandlerRules1.  the See  “getHandlerRules1” above for further details. 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 Description The handlers of action types whose actions only have one  parameter should use getHandlerRules2 instead of  getHandlerRules (which a handler expecting two parameters per  action should use). 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 Description Only a handler for an action type used by list­modification rules  may call this procedure.  See “getHandlerRules” above for details.idList. approverCategoriesOut out nocopy ame_util. getHandlerRules3 Syntax procedure getHandlerRules3( ruleIdsOut out nocopy ame_util. but for list­modification action types.

4. getHandlerLMApprovers Syntax procedure getHandlerLMApprovers( listModParameterOneIn in varchar2.idList. returnForwardeesIn in boolean. The approver has the wf_roles.  If includeFyiApproversIn is false. includeFyiApproversIn in boolean.engStApprovers) in approverIndexesOut. the  two values are the same.  If  returnForwardeesIn is true.idList). listModParameterTwoIn in varchar2.1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 Description This procedure marks the given rule as applicable for the current  transction.anyApprover or ame_util.  (If there are no forwardings.finalApprover). The procedure returns matching approver occurrences’ indexes  (in ame_engine. lastForwardeeIndexesOut out nocopy ame_util. 3. the approver’s  approver category is  ame_util.  It returns the indexes of the approvers in  ame_engine. starting with a forwarding from the approver at the  index approverIndexesOut(i).name value  listModParameterTwoIn. includeApprovalGroupsIn in boolean. 2. 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 Description Only a list­modification action­type handler may call this  procedure.approvalApproverCategory.engStApprovers that satisfy the following  requirements: 1.) Use getHandlerLMApprovers in conjunction with  getHandlerRules3 (see “getHandlerRules3” above). approverIndexesOut out nocopy ame_util.   If includeApprovalGroupsIn is false.   The approver is in a position consistent with  listModParameterOneIn (which can be  ame_util. lastForwardeeIndexesOut(i) contains  the index of the approver at the end of a succession of  forwardings. getHeaderAttValues1 Syntax 2 Appendix C The Action­Type­Handler Programming Interface 123 . the approver is in a  chain of authority.

  starting with its name.getAttributeIdByName. using  ame_engine.  The members’ order numbers within the group  (corresponding to the member_order_number field of an  Appendix C The Action­Type­Handler Programming Interface 124 . approverOrderNumbersOut out nocopy ame_util. attributeValue2Out out nocopy varchar2.  However.  Typically a  handler uses this procedure to fetch a currency attribute’s values. approverDisplayNamesOut out nocopy ame_util. origSystemsOut out nocopy ame_util.  The procedure returns null in  attributeValue2Out and attributeValue3Out unless attributeIdIn  identifies a currency attribute.  The direct route is typically  to use getHeaderAttValues2 (see “getHeaderAttValues2” below).  The procedure returns null in  attributeValue2Out and attributeValue3Out unless  attributeNameIn identifies a currency attribute. attributeValue1Out out nocopy varchar2. attributeValue2Out out nocopy varchar2. 41 42 43 44 2 Description This procedure returns the members of the approval group with  ID groupIdIn.  Typically a handler uses this  procedure to fetch a currency attribute’s values. 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 Description This procedure returns the values of the header­level attribute  with the name attributeNameIn. the  handler would typically first have to fetch the attribute’s ID. 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 Description This procedure returns the values of the header­level attribute  with the ID attributeIdIn.longStringList. attributeValue3Out out nocopy varchar2). attributeValue3Out out nocopy varchar2).  getRuntimeGroupMembers Syntax procedure getRuntimeGroupMembers( groupIdIn in integer.1 1 2 3 4 5 procedure getHeaderAttValues1( attributeIdIn in integer.longStringList. origSystemIdsOut out nocopy ame_util. attributeValue1Out out nocopy varchar2.idList.stringList).idList. getHeaderAttValues2 Syntax procedure getHeaderAttValues2( attributeNameIn in varchar2. approverNamesOut out nocopy ame_util.

  Typically a pre­approval.   insertApprover Syntax procedure insertApprover( indexIn in integer. or approver­group  chain­of­authority action type uses this procedure to fetch an  approval group’s membership. approverIn in ame_util.approverRecord2.   insertApprovers Syntax procedure insertApprovers( firstIndexIn in integer. nameIn in varchar2. adjustMemberOrderNumbersIn in boolean default false).   substituteApprover Syntax procedure substituteApprover( approverIndexIn in integer. 2 Appendix C The Action­Type­Handler Programming Interface 125 .approverRecord2) are in approverOrderNumbersOut.  insertApprover performs the insertion and then adjusts the  member_order_number values of the approvers at and above  indexIn.engStApprovers). in the same group or chain as approverIn.1 1 2 3 4 5 6 7 8 9 10 11 12 ame_util. 13 14 15 16 17 18 19 20 21 22 23 24 25 26 Description This procedure inserts the approver represented by approverIn  at index indexIn of the current approver list (in  ame_engine.  indexIn must be between one and  one more than the number of approvers already in the list  (inclusive). starting at the  index firstIndexIn.  If adjustMemberOrderNumbersIn is true. approversIn in ame_util. actionTypeIdIn in varchar2. 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 Description This procedure inserts the list of approvers in approversIn into  consecutive positions in the current approver list. so the handler can add the group  to the approver list.  For this reason you should only use insertApprovers  in cases where you’re confident no such adjustment could be  appropriate. which must be between one and one more  than the number of approvers already in the list.  Unlike  insertApprover. post­approval.approversTable2). insertApprovers does not adjust the member  order numbers of any approvers following the inserted  approvers.

  24 25 26 27 Appendix D Sample AME Objects 2 Appendix C The Action­Type­Handler Programming Interface 126 .name of the approver in  ame_engine. 12 13 14 15 16 17 18 19 20 21 22 23 Description Only a list­modification action type’s handler may call this  procedure. the approvers that would  otherwise be truncated remain in the approver list. ruleIdIn in integer).1 1 ruleIdIn in integer). so that this approver becomes the  final approver in the chain.  The  procedure also appends ruleIdIn to the truncated approvers’  source value. truncateChain Syntax procedure truncateChain( approverIndexIn in integer.  It also appends ruleIdIn to the rule­ID list in the target  approver’s source field.  The procedure truncates the chain of authority  containing the approver at index approverIndexIn of  ame_engine.engStApprovers.engStApprovers at index approverIndexIn with the  nameIn. 2 3 4 5 6 7 8 9 10 11 Description This procedure replaces the wf_roles.fyiApproverCategory.  If the allowFyiNotifications  configuration variable is set to yes. but their  approver category becomes ame_util.

1 1Overview  2 3 4 5 6 7 8 9 10 11 12 13 14Transaction Type 15 16 17 18 19 20 21 Before actually creating a transaction type.  The  application has historically included its own approvals  functionality.  In the development team’s experience. the team reviews and  documents the following decisions: 1.  The logic interprets its decision variables the same way for all  transactions. in the process of seeding a  transaction type:   • • • • • a transaction type proper mandatory­attribute usages an item­class usage a header­level attribute and a usage for it a line­item­level attribute and a usage for it. This chapter illustrates how to create a variety of AME objects that a  development team would typically create. How many transaction types to create What usages to give the mandatory attributes What item­class usages to create How to configure the item­class usages. 22Number of Transaction Types 23 24 25 26 27 28 29 30 31 32 Suppose an originating application wants to integrate AME. 2 Index 127 . where  appropriate.  The following subsections describe these decisions. 4.  It generally assumes that it describes the activities  of the development team for a fictitious Oracle Applications  product Some Application. 2. 3. their  customers generally implement a modest number of rules in the  old approvals functionality.  For all these reasons the  development team concludes that it only needs to seed one  transaction type. The chapter includes sample code for each object.  The approvals functionality applies the same  approvals logic to all transactions generated by the application.

 and it  stops a transaction’s approval process when any line item is  rejected.  So the team gives REJECTION_RESPONSE a static  usage having the value ame_util.  Therefore the development team gives  AT_LEAST_ONE_RULE_MUST_APPLY the dynamic usage • • select decode(sign(sum(line_item_amount) –                     some_app_package. The old logic is able to request approval per line item. so the team gives  USE_RESTRICTIVE_ITEM_EVALUATION a static false  usage. • The old logic always evaluates its rules as of sysdate.getApprovalThreshold). ‘true’. this function returns the threshold. The old logic does not have a rule­priority construct.                1. the old approvals logic never allowed an end user  to approve the transactions they submit.  so the development team gives  ALLOW_DELETING_RULE_GENERATED_APPROVERS a  static false usage.  The application owns a PL/SQL package named  some_app_package that contains a public function  getApprovalThreshold. ‘false’)    from some_app_line_items   where transaction_id = :transactionId.  Here are their decisions: • The old approvals logic never allowed an end user to  suppress approvers required by the application’s approvals  logic.  Their guiding  principle is to preserve or improve upon their old approvals  logic in their AME seed data. Note that this usage assumes that the line­item amounts are in  the same currency as the threshold. so the  team gives EVALUATE_PRIORITIES_PER_ITEM a static  false usage. the development team reviews the mandatory attributes to  decide what values or usages to seed for each.  • • 2 Index 128 . so the development  team gives ALLOW_REQUESTOR_APPROVAL a static false  usage.1 1Mandatory­Attribute Usages 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 Next. so the  development team gives EFFECTIVE_RULE_DATE a static  null usage. Likewise. In the old logic.stopAllItems.The old logic  never does per­line­item rule evaluation. all transactions having a total value over a  user­configuration threshold must have someone’s approval.

The old functionality limits currency conversions to a two­ month period. so the team sets currencyConversionWindow  to 60 (days).  Here are their decisions: • Each customer organization will have its own administrative  approver.1 1 2 3 4 5 6 7 8 9 10 11 12 • The team will give its master Workflow approvals process  the item type the named ‘OSA’. The team will not use AME’s production functionality. select :transactionId from dual • The team will integrate AME API calls into its application’s  Workflow process. The team decides not to seed values for  forwardingBehaviors. The old approvals functionality clears and restarts a  • • • • • • • 2 Index 129 . assuming that their customers will  generally already have created appropriate default values for  this variable. so the team does not seed a value for  adminApprover. The team uses its transactions’ Workflow item keys as  transaction IDs. so it gives USE_WORKFLOW a static  true usage. so it gives  WORKFLOW_ITEM_TYPE the static usage ‘OSA’. so it gives WORKFLOW_ITEM_KEY the  dynamic usage • 13Configuration­Variable Values 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 The development team chooses its seeded configuration­variable  values according to the same principle by which it chose its  mandatory­attribute usages:  preserving or improving upon their  application’s pre­AME functionality. The old functionality uses line items. so the team seeds the  value ‘true’ for allowAllItemClassRules. so the team sets allowFyiNotifications to  ‘yes’. so it  sets productionFunctionality to ‘no’.  So the team seeds the value ‘yes’ for  allowAllApproverTypes. The team plans to enable FYI notifications in their approvals  Workflow process. The team plans to seed a new approver type based on the  (imaginary) ‘ORG’ originating system in Workflow Directory  Services.

 rather than in ascending character­set order.  Sublist Mode Per the above.  so the team sets repeatedApprovers to ‘each occurrence’. so the team sets purgeFrequency to 14 (days). • • The old functionality does not suppress repeated approvers. with line items’  approver lists following the header’s approver list.  So the item­class usage  must have the line­item­ID query select to_char(line_item_id)    from some_app_line_items    where transaction_id = :transactionId   order by line_item_id asc. Parallelization Mode Per the above.1 1 2 3 4 5 6 7 8Item­Class Usage 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 2 transaction’s approval process if it does not finish within two  weeks. Next the team prepares to create an item­class usage for the line­ item item class.  Character­set ordering would force the transaction type’s line­ item­level attributes’ usages to order by to_char(line_item_id). the team assigns the line­item item class the serial  sublist mode.  so the team disables rule priorities for all rule types in  rulePriorityModes.  Consequently the team assigns the line­item item class the item­ class order number two.  Line­Item­ID Query The application’s line items apear in the table  some_app_line_items. The old functionality does not have a rule­priority construct.  That table joins the application’s some_app_headers  table via the transaction_id column.   Item­Class Order Number The old approvals functionality created an approver list for each  line item.  Index 130 .  It ordered all approvers serially. their IDs are in the line_item_id column of  that table. Note that the order­by clause orders the item IDs in ascending  numerical order. the team assigns the line­item item class the serial  parallelization mode.

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

1 1 2 Index 132 .

You're Reading a Free Preview

/*********** DO NOT ALTER ANYTHING BELOW THIS LINE ! ************/ var s_code=s.t();if(s_code)document.write(s_code)//-->