Sunteți pe pagina 1din 23

What is AME? Note: Setup and Application Screenshots at the end AME by definition is a Approval Management Engine that Builds a list of approvers for a specific transaction using business rules. However in simple words, AME is a "IF THEN....ELSE....END IF" condition - wrapped into an API. That's exactly what AME is. It is a IF THEN ELSE CONDITION wrapped up into a lets say Function Call to produce a list of approvers. The complexities are taken care of by the Approval Management Engine itself. However this "IF CONDITION" definition holds true when talking about the simplest possible definition of AME. Therefore if you can understand "IF Condition", then you can understand AME. Further to that, if you know how to write IF Conditions and how to write SQL, then you will be able to implement most of the AME Business requirements with ease. Lets have a look into IF CONDITION from another perspective. The example below is for explanation purpose only, not the exact definition of AME. Imagine there is a FUNCTION that returns the approver FUNCTION get_requisition_approver_id (transaction_id IN INTEGER ) RETURN INTEGER IS BEGIN IF get_requisition_amount(transaction_id) < 1000000 THEN return 1000 ;-- calculated from person_id from the supervisor_id of the person that created requisition ELSE return 1001,1003 ; --person_id from a static approver group that contains list of people, like Director followed by a CEO to approve orders over 1Million END IF ; END get_requisition_approver_id ; The above function builds a list of approvers for a specific transaction using business rules, and returns one of more approvers.

AME consists of certain building blocks that are

Building Block Name Purpose

AME Transaction Type

An application that uses AME to govern its transactions approval processes is termed an Integrating application. An integrating application may divide its transactions into several categories where each category requires a distinct set of approval rules. Each set of rules is called a Transaction Type.
e.g. Oracle Self Service Human Resources, Learning Management etc.

AME Attributes

Attributes are variables used to hold business facts of interest for the transaction in progress. Most attributes are dynamic, meaning they will be evaluated at run time, thus, they can change for each transaction. Oracle provides over 50 seeded attributes for SSHR which can be used directly or as the basis of creating the users own. These Attributes can be used for building the AME Conditions. Attributes are used in Conditions. Conditions are the IF part of rule. Conditions evaluate the Attribute and return a value of True or False. All Conditions must be true for a rule to fire. Action Types provide two important aspects of the generated approval chain. Action Types, by their nature, indicate HOW approvers are generated, i.e., whether by utilizing an existing hierarchy, or by a user specified list of persons. The second aspect is regarding the order in which approvers are notified. Pre-chain Action Types will be triggered before Chain of Authority action

AME Conditions

AME Action Type

types, which are triggered before Post-chain type. AME provides many Action Types. Three of most common include: 1) Pre-chain of authority approvals, 2) Supervisory level, and 3) Post-chain of authority approvals. Chain of Authority Action Types are typically those which include authority figures who are dependent upon the person initiating the transaction, for example, the employees immediate supervisor, the next immediate supervisor, and so on. Pre- and Post Chain Action Types are normally used for approvers in functional areas who have an interest in the transaction because of the type of change being done, not because of the specific employee. An example of typical pre- and post-chains are Human Resource personnel. Users will not generally create new Action Types. It may be necessary, however, to ensure that the desired Action Type is made available to Oracle Self-Service Human Resources. It is strongly suggested that at least the three types mentioned above have been selected for use by SSHR. If they do not appear in the Action Types screen, add them with the Use Existing Action Type button. If Action Types give the HOW to generate a list of approvers, Approval Groups specify the WHO to include. Approval Groups are not needed for Chain of Authority Action Types, since these are implicit as should already be assigned in your database, i.e., if using a supervisor level action, AME assumes that supervisors have been assigned to all employees via normal data processing. Pre- and Post-chain Action Types do require the user to specify a list of persons, since these are normally not reliant on the employee making the transaction. The simplest way to identify the approvers in the group is to just list them by name. A list of HR and Benefit personnel who must approve the transaction is static enough that changes to the Approver Group definition can be made as they occur. However, if approval is needed by, say, the chairperson of a specific department, and this changes each academic year, a user may want to set up the Approver Group as dynamic. Dynamic group definitions require a SQL query which is executed at run-time. A dynamic Approval Group which returns the current Biology Chairperson would not require a change to the Approval Group definition itself as individuals move in and out of this position, but would rely on a change made to position codes on the Assignment screen. Actions are combinations of Action Types and Approver Groups, and are the THEN statement of a rule. Actions are automatically generated for Pre- and Post-chain Action Types. For example, if an Approver Group of HR personnel, named MUSS Benefit Specialists is created, Oracle automatically creates Actions called Require pre-approval from MUSS Benefit Specialists and Require post-approval from MUSS Benefit Specialists. Many seeded Actions for Chain of Authority Action Types are available. For the Action Type supervisor_level, Actions exist to specify from 1- to 10-up supervisor levels. Other chain actions involve job or position hierarchies again, information that should already be recorded in your database. Combines the "AME Condition" and "AME Approval Groups". Indirectly though it references all the building blocks of AME. You can say that every piece of AME building block is glued together in an "AME Rule". There are six different types of Rules. The most commonly used ones would

AME Approval Groups


AME Rules

include List-Creation (based on Chains of Authority Actions), Pre-List Approver Group, and Post-List Approver Group. Substitution Rules are used to replace a specific approver, however generated, with another person. A Combination Rule can be used to combine pre-chain, chain, and post-chain actions as long as conditions and the rule category are the same

Profile option "AME:Installed" must be set to Yes, at application level to the calling application to be able to use AME. The "AME Transaction Type" can be defined using a responsibility named "Approvals Management Administrator". Remainder of the building blocks can be defined and configured using responsibility named "Approvals Management Business Analyst".

Back end Package: hr_ameutil_ss

AME Concepts (For Reference)

AME Concepts.pdf

How AME relates to Self Service HR? In Self Service Oracle Human Resources there is a workflow named "HR". The short code of this workflow is HRSSA. This workflow is initiated as soon as any business activity is initiated in Self Service HRMS. Steps within this Workflow process can be mapped to specific screens in OA Framework. Therefore the HR workflow guides which screen the user navigates through when making changes to data in self-service HRMS.

Well there is no official explanation from Oracle for usage of a workflow to drive the flow of the screens. However prior to using OA Framework in Self Service HRMS, SSHR was built using PL/SQL Web Cartridges and latter AK Developer was included. Those days OA Framework did not exist in the current form. When the very first version of SSHR was built by Oracle, back then the methodology of transaction state management of web based applications was not standardised across e-Business Suite modules. Use this link to understand how OA Framework evolved. Therefore Oracle HRMS Product Development team decided to use a "Workflow process" to keep all the loose bits of screens tied together into one single transaction. If you open the HR [HRSSA] workflow, you will notice that there are many Workflow Activities that are mapped to PL/SQL Function named HR_WORKFLOW_SERVICE.BLOCK. These activity/steps in workflow correspond to a screen. This is how user navigation from one screen to other is controller in Self Service HRMS. The image shown above uses a workflow process named Person Information. However, for each distinct menu item in Self Service HRMS, there exists a corresponding Workflow Process. Thus there are numerous processes within this HRSSA workflow. For example there is another workflow process that starts when user navigates to "Extra Information Types" screen How does Oracle know which workflow process to initiate when a user enters "Person Information" screen in SSHR When user clicks on SSHR Menu Item, the name of the workflow process is passed as a parameter to the form function. Therefore, the sequence of events are

User clicks on a menu in SSHR responsibility Form Function attached to Menu is invoked. This Form Function invokes AK Region HR_CREATE_PROCESS_TOP_SS [See Web HTML of Form Function HR_PERINFO_SS]

This AK region is mapped to OAF Page /oracle/apps/per/selfservice/workflowservice/webui/CreateProcessPG In some cases SSHR Function directly invokes an OA Framework page, specifically holds true for pages developed post-AK-Developer era

Parameter pProcessName is read and the Workflow Process named "Personal Information" is initiated All these steps are illustrated in image below

How does Oracle know which AME Transaction Type to use for that screen As shown in image above, two parameters named pAMETranType and pAMEAppId are passed as parameter to the Form Function. This tells which AME Transaction Type will be used by the SSHR screen. However the decesion of whether AME is switched ON or OFF is decided by a Wokflow Activity named "Review Page". Every SSHR Workflow Process as a step named "Review Page". As shown in image below, when you double click on activity Review Page you will notice that this Workflow Function is passed a parameter named HR_APPROVAL_REQ_FLAG. If this WF Activity parameter is Yes or "Yes - Dynamic Approval" then the AME is called for Approval processing. To change the standard Approval processing in Oracle Self Service HRMS, you can customize this property to enable or disable the Approval Processing for specific screen in HRMS.

Further details of how you can implement differing AME logic for different SSHR screens will be covered in a future article. Note- It is in Self Service HR [HRMS] that the AME Trx Type is passed as passed as parameter to the screen function. Every calling module can have its own specific way using which the AME Trx Type to be used is configured. For example, in iRecruitment we have the following profile options that dictate the AME Transaction Type being used IRC: Vacancy Approval Transaction Type -Identifies the vacancy approvals transaction type to be is used. IRC: Offer Details Approval Transaction Type -Offer Details Approval Transaction Type IRC: Extend Offer Duration Transaction Type -Extend Offer Duration Transaction Type

Do we directly customize the Workflow Process to change the AME behaviour for a screen? Not really. You will copy the existing workflow process and create a new workflow process. For example a new workflow process named XX will be created. The review page property within this workflow process will be modified to use/remove AME. Thereafter you will create a new custom Form Function and attach that Custom Form Function to the Menu. This Custom Form function will be passed in the parameter pProcessName with Custom Workflow Process Name. This function must also be included within the menu named "HR_GLOBAL_SS_FUNCTIONS_CUSTOM". This will facilitate usage of the custom Form Function in SSHR.

Firstly, what is the purpose of this workflow in Self Service HRMS ? There is a historic reason for usage of Workflow named HRSSA in Self Service HRMS. Self Service HRMS product development was done slightly ahead of OA Framework. In the early days of Self Service HRMS, OA Framework did not exist in its current form, and therefore PL/SQL web Cartridges were used for developing the initial set of pages in SSHR. Thereafter AK Developer was used to configure the components of the pages in SSHR. However, Self Service HRMS team was looking for a framework that could give State Management for the data in Web Application. OA Framework was not quite ready by then, therefore Oracle Workflow was hooked onto the Self Service HRMS screens to manage user sessions. Given that workflow instance is persistent in the database tables, therefore the HRMS team was able to leverage the persistency offered by Oracle Workflow for managing the state of Web Pages in Self Service HRMS. Some further info When a user makes changes to the data via SSHR, the following tables are populated. HR_API_TRANSACTIONS HR_API_TRANSACTION_STEPS HR_API_TRANSACTION_VALUES The table HR_API_TRANSACTION_VALUES contains the old and the new values of the each possible column/attribute that was changed by the user.

Steps to Access AME functionality in Apps 1. Add Responsibilities to user SUBSINGH: Approvals Management Administrator Approvals Management Business Analyst No functions will however be visible when accessed through the responsibilities. This is resolved using RBAC (Role Based Access Control) Go to User Management Users Search for SUBSINGH Update Click on Assign Role. Search for Roles with name %Approval% and assign all the roles found to SUBSINGH. Apply Changes. Now the functions will be visible. However NO DATA will be visible as of yet. For data to be visible go to Functional Administrator Create Grant. Grantee Type = Single User and then enter SUBSINGH as user. Select Object = AME Transaction Type. Click Next. Select All Rows as context type. Click Next. Set = AME Calling Applications. Save the Grant. Clear cache to see DATA.

2. 3. 4. 5. 6. 7. 8. 9.

Self Service HRMS Workflow Explained In this article, we will continue with the HRSSA workflow, and see how it integrates with the AME. You will also see the best practices steps to customize this workflow in an upgrade safe manner. In all the HRSSA processes, there is a Workflow activity named "Review Page..." as shown below. If you double click to open the properties of this WF Activity, you will find that Node Attributes tab contains a two Attributes i.e. HR_DYNAMIC_APPROVAL_LEVEL and HR_APPROVAL_FLAG. In the context of our example, the Special Information Type WF process has AME Approvals switched off, because HR_APPROVAL_FLAG is set to NO. However as per our requirements we need to enable AME for our Holiday Rejection Complaint screen. Effectively, we are trying to achieve a result whereby our custom workflow process is kicked off from the screen we created, and this custom workflow process will ensure that AME is invoked. In order to enable AME approval for our custom screen, you must not modify the standard HRSSA workflow process. Instead you should adhere to some best practices as detailed in this article

Why am I not allowed to change the HR_APPROVAL_FLAG in WF Builder? There are two reasons for this 1. If you change the AME Flag in WF Process HR_SIT_JSP_PRC, then subsequent patches from Oracle will override your change, and all of a sudden your Approval process will stop working 2. Oracle have developed these items at Access Level 20, whereas your Workflow access level as an implementer is 100+. Therefore you will not be allowed to change the WF Attribute, unless you decide to set the access level to 20 for your development as well. Reducing the access level below 100 is not recommended, because such changes are not upgrade safe. To learn about Workflow access levels, see the presentation in this link

How do I change the AME Flag, without modifying the standard workflow process? In order to do so, you must implement the following steps. We will latter see these steps in detail 1. In WF Builder, set your Workflow Access Level to 100 2. Make a custom copy of the WF process HR_SIT_JSP_PRC and name it as XXFT_HR_SIT_JSP_PRC 3. Within Workflow process XXFT_HR_SIT_JSP_PRC, open Review activity, and in Node Attribute tab set the HR_APPROVAL_REQ_FLAG to "Yes-Dynamic Approval" 4. Save this workflow file as XXFT_SSHRA.wft 5. Upload this workflow in UPGRADE Mode using the WFLOAD command. 6. Change the AOL Function that you created in Part 1/2 of this article. In the parameter field of AOL Function, ensure that the value of pProcessName is changed as below

Old Value pProcessName=HR_SIT_JSP_PRC New Value pProcessName=XXFT_HR_SIT_JSP_PRC

By implementing the above steps, you will notice that our custom screen will now be calling the custom workflow process named XXFT_HR_SIT_JSP_PRC. This workflow process name can be used in AME Set to build the desired approval logic.

Now, the steps in detail.... Open the HRSSA workflow in workflow builder, and set your access level to 100 or above.

Right click on the Workflow Process that you wish to customize and click "Copy" as shown below

Give this newly copied WF process a name, as shown below. Internal Name=XXFT_HR_SIT_JSP_PRC Display Name=XXFT SIT Holiday Complaint

For the "Review Page 4.0" activity, set the HR Approval required property to "Yes - Dynamic Approval"

Preserve Customizations to Oracle Workflows

Preserve_Customizat ions_in_Oracle_Workflow.ppt

Self Service HRMS and AME Part 5 - Understanding HR_API_TRANSACTIONS

When a Self Service HRMS user creates any data from the screens, such data goes and resides in some temporary tables. This data is retained within the temporary tables until the transaction is Completed. A transaction in this example gets completed when Holiday Rejection complaint is either Rejected or Approved. These temporary table names begin with name HR_API%. In reality, the data entered by the user is either stored within just one table i.e. HR_API_TRANSACTIONS or within HR_API_TRANSACTION_VALUES. When the data is stored in just the HR_API_TRANSACTIONS then the entire data entered by the user is captured in a CLOB column. This feature was introduced couple of years ago, whereby for performance reasons the temporary data is captured in a clob column named HR_API_TRANSACTIONS within HR_API_TRANSACTIONS. This CLOB column contains XML contents. By now, you might have the following questions 1. What exactly is captured in CLOB column hr_api_transactions.transaction_document

2. How does Self Service HRMS decide whether the transaction data which is in-transit goes into CLOB or HR_API_TRANSACTION_VALUES. 3. How is this temporary data used by AME 4. How is the data transferred from temporary tables to base tables in HRMS.

In this article I will answer these questions, so that you can proceed with the AME bits that depends upon this information. In addition to this, you will also learn how the "SAVE FOR LATTER" feature works in HRMS.

As soon as you enter any data in Self Service HRMS screens and navigate to the next page, an entry is created in HR_API_TRANSACTIONS. Of course, the AME API's are called "during" the approval process which happens after the data has been submitted for approval. This means at the time of "AME Engine processing" the data entered by the Self Service HRMS Screen is in-transit, i.e. in temporary tables. In fact, within the AME, you will be passed the transaction_id from hr_api_transactions. Therefore the AME engine has a handle to the entire in-transit data via hr_api_transactions.transaction_id. Using this TransactionId handle, you can either query the CLOB XML in SQL or you can query HR_API_TRANSACTION_VALUES.

1. What exactly is captured in CLOB column hr_api_transactions.transaction_document In this column the entire state of the Application Module is captured. Application Module in OA Framework manages the transaction state and also serves as a cache of the data in the memory. In this example, when the user enters a Holiday Rejection Complaint and submits for approval, then entry is created in table HR_API_TRANSACTIONS, HR_API_TRANSACTION_STEPS and HR_API_TRANSACTION_VALUES. This also serves the purpose of SAVE FOR LATTER. When you save a transaction for latter, effectively the entire data in the cache is dumped into temporary tables. If the self service user wants to restart the transaction after few hours/days, then entered data is requeried from these HR_API temporary tables

2. How does Self Service HRMS decide whether the in-transit transaction data goes into XML CLOB HR_API_TRANSACTIONS.TRANSACTION_DOCUMENT or into HR_API_TRANSACTION_VALUES. In the old version of Self Service HRMS, all the temporary information is captured in the following tables. HR_API_TRANSACTIONS HR_API_TRANSACTION_STEPS HR_API_TRANSACTION_VALUES 3. How is this temporary data used by AME Inside AME, you usually write SQL statements against AME Attributes and AME Approval Groups. In those SQL statements, you can reference HR_API_TRANSACTIONS.TRANSACTION_ID by using convention :transactionId

4. How is the data transferred from temporary tables to base tables in HRMS. Oracle executes an API named hr_transaction_swi.commit_transaction which takes the transaction_id as parameter. This transfers the data from temporary tables to the base tables. DECLARE

v_trans_api_result VARCHAR2(1); BEGIN v_trans_api_result := hr_transaction_swi.commit_transaction ( p_transaction_id => n_hr_api_transaction_id --pass the transaction_id here ,p_validate => hr_api.g_false_num

,p_effective_date => sysdate ); END;

The above API is usually called when Self Service HRMS Transaction is completed, for example when Approved. This is executed via one of the activities in HRSSA workflow after AME processing is completed. In the event AME approval is not required, hr_transaction_swi.commit_transaction is called immediately after the user submits the data from Self Service HRMS screen

Self Service HRMS - Design and Unit test AME Understanding AME Concepts (Already covered above. These are just the links.) How will the AME calculate the Manager's manager? In AME, the approver list is calculated using something known as Approver Group. The approver group can be a static list of people or a dynamic list of people. The dynamic list of approvers is calculated by executing a SQL statement. This SQL statement and its unit testing will be shown as a video demo in the next article. In this case, we will write a SQL Statement that returns the name of the Manager's Manager of the person that created the Holiday Rejection Complaint record. The AME is called from a specific screen, i.e. in this case Special Information Types screen. How will the AME get a handle to the original transaction/records for which AME is being called? In AME, each AME Flow can be considered as an "AME Transaction Type". The SSHR screens pass a parameter to the AME Transaction Type. The name of the parameter passed by Self Service HRMS to AME is called TransactionId. This Transaction Id gives a handle back to the original transaction, which in this case is data entered via Holiday Rejection Complaint screen. Therefore by using the TransactionId, the AME Engine/AME SQL's can reference the originating transaction for which Approver List is being calculated.

While the Approval is in progression, the data remains in temporary tables named HR_API_TRANSACTION_VALUES [in case of SIT. Some other screens use XML CLOB in hr_api_transactions.transaction_document]. Therefore if your custom logic within the AME wants to access the original transaction data, that can be done by either querying HR_API_TRANSACTION_VALUES or by parsing the XML within the CLOB column. The primary key for table HR_API_TRANSACTIONS is Transaction_id. This Transaction Id is passed as a parameter to the AME Engine for SSHR AME Transaction Type. Therefore AME Trx Type will be passed the TransactionId using which it can get the handle to contents of HR_API_TRANSACTIONS

How do we know which AME Transaction Type will be called by our Custom Screen? If you revisit Part-2 of this article, you will notice that the AME Transaciton Type and AME Trx Type ApplicationId are passed as parameters to the AOL Form Function. The parameters field in AOL Function definition contains AMETranType=SSHRMS&pAMEAppId=800 How do we build the logic for our solution? We will be building a logic in AME that is similar to below IF WORKFLOW_PROCESS_NAME='XXFT_HR_SIT_JSP_PRC' THEN Return Approver Name from AME Attribute XXFT_MANAGERS_BOSS_GROUP END IF ;

What is XXFT_MANAGERS_BOSS_GROUP? XXFT_MANAGERS_BOSS_GROUP will be a custom defined AME Approval Group that you can define. To this AME Approver Group, you can attach the following SQL Statement. This SQL statement returns the FND_USER.USER_ID of the Manager's manager for the employee that created a record in "Holiday Rejection Complaint" screen.

select 'user_id:' || fu.user_id from hr_api_transactions per_all_assignments_f per_all_assignments_f hat, paaf, paaf2,


where hat.transaction_id = :transactionId and hat.selected_person_id = paaf.person_id and paaf.effective_start_date <= sysdate and nvl(paaf.effective_end_date, sysdate) >= sysdate and paaf.primary_flag = 'Y' and paaf.assignment_status_type_id = past.assignment_status_type_id and past.user_status = 'Active Assignment' and paaf.supervisor_id = paaf2.person_id and paaf2.effective_start_date <= sysdate and nvl(paaf2.effective_end_date, sysdate) >= sysdate and paaf2.primary_flag = 'Y' and paaf2.assignment_status_type_id = past2.assignment_status_type_id and past2.user_status = 'Active Assignment' and paaf2.supervisor_id = fu.employee_id

What are the AME Implementation Steps for this solution? These are listed below 1. Create AME Condition that checks if the workflow process name = XXFT_HR_SIT_JSP_PRC 5. Create AME Approver Group XXFT_MANAGERS_BOSS_GROUP returns the name of Manager's Manager FND_USER.USER_ID 2. Create an AME Rule named "XXFT Holiday Rejection Complaint" 3. Attach this rule to the condition of Step 1 4. Add an action to this rule get the approver from XXFT_MANAGERS_BOSS_GROUP 6. When the end user initiates a "Holiday Rejection Complaint", then the custom HRSSA workflow process is instantiated. This calls the AME Engine to get next approver. The condition of Step (2) above is evaluated to be TRUE. Therefore the approver is returned by executing the SQL Statement against XXFT_MANAGERS_BOSS_GROUP

Creating the AME Rule in Self Service HRMS - Part 7

See Presentation

Setup and Concepts and Testing

Approval Process Setup
1. 2. Select the transaction type Define the components Approvals Management uses these components within the approval rules. a. Attributes - Define attributes to fetch business facts for a specific transaction. b. Conditions - Define conditions to evaluate attributes within rules. If all conditions in a rule are true then the rule is active for the transaction. c. Action Types - Enable action types to specify the action to take if a rule is active for a transaction. d. Approver Groups - Define approver groups to contain approvers who are usually members of peer groups such as payroll or expenses department. Define the approval rules (AME Rule) - Approval Rules determine the approvers or FYI notification recipients required for a business transaction. Test Workbench - Define test cases or test real transactions to verify the approval setup, rules and associated approvers.

3. 4. 5.

Approvals Management Business Analyst Responsibility Attribute + Conditions + Action Type + Approver Group AME Rule Approvals Management Administrator Responsibility AME Rule AME Transaction Type

Attributes Screen

It can be any package.function in the query with transactionId being the parameter. This transaction ID is from the table HR_API_TRANSACTIONS. Against the transactionId we can get several other values like person_id etc.

Condition Screen

Approver Group Screen

Action Type Screen There are several Rule Types here e.g. (Chain of Authority, Substitution, Pre List Approval Group etc.). For regular supervisory approval, we choose Rule Type = Chain of Authority. Now this has got 2 Action Types in it. Chains of authority approval-group chain of authority

Based on number of supervisory levels Chain of authority includes an approval group

Actions within Chain of Authority action type are Require approvals up to the first superior, at most, Require approvals up to the first two superiors, at most etc. Actions within approval-group chain of authority action type are Require approval from XXHR First Approver where XXHR First Approver is the Approver Group created.

Rule Creation Screen Step1: Define Name of AME Rule, Rule Type etc.

Step 2: Add Conditions

Step 3: Add Action. Select action type as Chains of authority or approval-group chain of authority and add the appropriate action.

Step 4: Review and Submit the rule.

Test Screen Screen 1: Landing Page. Create a new test case here.

Screen 2: Test case creation screen

Approval Management Administrator Responsibility - Dashboard Page