Firstly, download the right version from Oracle here.  I downloaded the file “sqldeveloper-2.1.1.64.39-no-jre.zip”

Once the program has downloaded, unzip the file into a temporary location.  I unzipped mine into /home/Downloads where it created a new subdirectory called “sqldeveloper” for me.

Move the sqldeveloper folder into /opt (you may need root privileges to do this, so either do this as root or use sudo to move the folder).

Navigate to /opt/sqldeveloper and change the privileges on the sqldeveloper.sh file using chmod:

sudo chmod 755 sqldeveloper.sh

Create a new file called “sqldeveloper” in /usr/local/bin/sqldeveloper which contains the following line:

/opt/sqldeveloper/sqldeveloper.sh

Change the permissions on this new file using chmod again:

sudo chmod 755 /usr/local/bin/sqldeveloper

Finally, you can run the program just by typing “sqldeveloper” at the command prompt window.  Run this now from a terminal window, and you will be prompted to confirm the location of the JDK:

Oracle SQL Developer
Copyright (c) 1997, 2009, Oracle and/or its affiliates.All rights reserved.

Type the full pathname of a J2SE installation (or Ctrl-C to quit), the path
will be stored in ~/.sqldeveloper/jdk

In my instance, the JVM is located at /usr/lib/jvm/java-6-sun so enter that path and SQL Developer should start.  Because the path to ~/.sqldeveloper does not exist yet (it will be created the first time the program runs), you will see errors.  Close SQL Developer down and run the command again – you will be prompted to enter the path a second time, which will then be saved to ~/.sqldeveloper/jdk.  If you ever change the location of the JVM, you will need to modify this file or SQL Developer will fail.

The last thing that I did was to create a new shortcut in my Ubuntu menu – if you are doing this, then the icon file can be found at /opt/sqldeveloper/icon.png.  Now when I click on the icon, SQL Developer starts fine:

Using the “Approvals Management Business Analyst” responsibility, in the “Approval Process Setup” panel on the right hand side of the dashboard, choose the “iRecruitment Vacancy Approval” transaction type again:

Click on the “Approver Groups” link, and we will modify the existing group from static to dynamic.  Click on the “Update” icon for the Approver Group we created earlier, and then change the usage type from Static to Dynamic.  As soon as the change is made, you will be shown a warning, indicating that the static approvers will be removed from the group:

Since we are going to be redefining the group completely, this is fine, so click on the “Yes” button and you will be returned to the group definition with no static approvers shown.

As a simple example, my approver group requires approval from two people – the user MATT and the HR person Tim Cleary.  The SQL code required to retrieve the two records in the same query is

SELECT 'user_id:'||user_id
FROM   fnd_user
WHERE  user_name = 'MATT'
UNION ALL
SELECT 'person_id:'||person_id
FROM   per_all_people_f  papf
WHERE  papf.full_name = 'Cleary, Mr. Timothy'

In the SQL above, we need to tell AME exactly what kind of approver we are retrieving – by prefixing the user record with “user_id:” and prefixing the person record with “person_id:”, AME then knows where the records are being retrieved from.  Enter the SQL into the Query box, and then hit the Apply button. You can also use the Validate button, which checks that the query is structurally sound, but does not seem to check much more than that (for example, if you prefix the user record with “usssssser_id:”, it is still classed as a valid query).

That’s all there is to it – if we now go and create a new vacancy (using the same BJOSPEH user that we did in the last post), when we review the vacancy, we see that AME has added the two approvers to the bottom of the approval list:

In this example, we will implement the following approval rules for creating a new job vacancy within iRecruitment:

• When a vacancy is created, the vacancy must be approved by the supervisor of the person creating the vacancy.
• Once the supervisor has approved the vacancy, it must then be sent to a different user for final approval.

In my example, I have picked two random users within Vision – BJOSEPH (Joseph, Brian) and his supervisor, RJAMES (James, Robert).

The first rule (that the vacancy must be approved by the supervisor) is standard behaviour within iRecruitment, so there is nothing that we need to do with that. So – what do we need to do to meet the second requirement?

Firstly, we’ll create a new static AME Approval Group and add the Recruiting Administrator to that group. An Approval Group can return either a static or a dynamic list of users. Once we have created the Approval Group, we will then add the Group to the AME Rule that is used by the standard Vacancy Creation process.

Before we start, run through the standard Vacancy Creation process and see who the notification is sent to. Log in as the first user to create the vacancy – in my example, I will use the BJOSEPH user. Using the “iRecruitment Recruiter – VC” responsibility, navigate to the iRecruitment Home page, and click on the “New Vacancy” link in the sidebar:

In the “New Vacancy” window, enter a name for the vacancy and then click on the “Review” button. At this stage, we could enter more information about the vacancy, but since this is just a quick test to see the default functionality, there is nothing additional required here. The bottom of the vacancy summary shows the default approver that has been found – the supervisor of the person creating the vacancy:

As I said above – the default functionality meets our first requirement, so all we need to do is to add the additional requirements. Firstly, we need to find out what AME Transaction Type is used by the Vacancy Creation process. To do this, we need to examine the function for “Irc Vacancy Details – Create”, as shown in the screenshot below:

Navigate to the “Form” tab and open the Parameters to see the parameters which are passed to the form:

The parameter that we are interested in is “pAMETranType=IRCVACAPPROVAL”. Now that we know the name of the internal name for the transaction type (or Transaction Type Key), switch responsibility to “Approvals Management Administrator” – I will switch user completely to the AMEADMIN user we created in the last post. Navigate to the Admin Dashboard and query the IRCVACAPPROVAL Transaction Type Key:

Now that we know the name of the Transaction Type (iRecruitment Vacancy Approval), switch responsibility to “Approvals Management Business Analyst” and enter the Transaction Type in the right hand side in Step 1 of the “Approvals Setup Process”:

If you click on the “Rules” link, you can view the existing approval rules in place. Click on the link and then locate the “iRecruitment Create Vacancy” rule in the list of rules. When you open the rule, you are presented with the default rule:

Return to the dashboard, and we’ll create our custom Approval Group to add to the Rule. Under “Step 2” of the Process Setup, there is a link to “Approver Groups”. Click on the link to navigate to setup a new Approver Group, and then click on the “Create” button. The screenshot below shows the values that I have entered for my Approver Group:

The “Approver Type” can be an Applications User (FND User), a group of people (Nested Group) or an HR person (HR People). Multiple users can be added to the approval hierarchy here – I have only added one person, a user called MATT who will act as the final approver for vacancies. Click on the “Apply” button and then return to the dashboard to add this new Approval Group to the rule.

As before, click on the “Rules” link on the right hand side of the screen and locate the rule for iRecruitment Create Vacancy. Click on the update icon to open the rule details. At the bottom of the page, you will see the default action type, which seeks approval from the supervisor of the person creating the vacancy. Click on the Add Action button to add our Approval Group to the rule, as shown below:

If the “approval-group chain of authority” option is not available, this is because it has not been enabled. Click on the “Setup” tab and choose the “Action Types” submenu. You will be presented with a list of suitable action types – typically only the default “Supervisory level” one will be enabled. Click on the “Use Existing Action Type” button and navigate through the list of available types until you see the “approval-group chain of authority” type. Tick the box next to the action type and then click on the Continue button, then click on the Finish button. Now return to the rule and add the Approval Group as above.

Once you have added the action type, click on the Apply button. That’s all there is to it – now let’s check it again by logging out and creating a new vacancy. The final screenshot below shows that the new vacancy will be sent to MATT for approval as well as the originators supervisor:

Firstly, we’ll create a new user for this demonstration, and assign them the two responsibilities, thus:

If I now log into the eBusiness Suite as that user and try to switch to either of those responsibilities, the system indicates that there are no functions available for the user (see screenshot below).  As I said above, this is because role based access control ensures that only users with the right roles as well as responsibilities can access the functions.

So, now we need to modify the user to give them the right roles to administer AME properly.  As a system administrator, open the “User Management” responsibility, as shown below.

If you do not have any functions assigned to the responsibility, then you will need to use the SYSADMIN user and assign the “Security Administrator” role to your user. Select the “Users” option to continue.

Search for the user that you want to add the functions to (in my case, the AMEADMIN user I created earlier), open the user details and then click on the “Assign Roles” button. You are then presented with a search window, where you should search for all Roles beginning “Approval”:

You are then returned to the user screen, where you should complete a justification for granting the roles to the user – if you don’t then the screen will prevent you from continuing.  Once you have entered the justification, you should then hit the Apply button.

Log out as this user, and when you log in as the AME user, you now have functions associated with the two responsibilities:

Now that we have granted the roles to the user, they can access the functions correctly.  However, RBAC means that when we open the Dashboard, the data is still protected and cannot be viewed:

Again, we need to grant some RBAC roles to allow the user to access the different transaction types. The main principle behind this is to enable organizations to split the Transaction Type maintenance between different roles – for example to allow HR Super Users to maintain only the HR rules.

Using a different user, navigate to the Functional Administrator responsibility and click on the “Create Grant” button to create the new grant. In this example, we will create a specific grant for the AMEADMIN user, however in the real world it is more likely that you will create the grant for a group of users. The Object is set to “AME Transaction Types”, thus:

In the second step, accept the default data context type of “All Rows” and continue to the third step. Define the “Set” to be “AME Calling Applications” as shown in the following screenshot:

Finally, review the settings that you have entered and click on the “Finish” button. In order to ensure that the changes are replicated, now flush the cache by clicking on the “Core Services” tab then choose the “Caching Framework” sub-menu. Choose “Global Configuration” from the sidebar and then click on the “Clear All Cache” button. You will be presented with a warning message (see below) which you can ignore and click on the “Yes” button.

Log out of this user and log back in as the AMEADMIN user, and navigate to one of the AME responsibilities – you are now given a list of the AME Transaction Types that are configured in the system:

In the next blog post, I’ll be providing a practical example of customizing AME within iRecruitment.

Before you start using AME, it is important that you understand exactly what the different parts of the Engine are, what you need to configure, and how they all work together. There is frequently a requirement to modify the seeded components or to create new ones for an organization, in order to develop their business rules.

Transaction Types

A Transaction Type defined the type of transaction for which the business rules and approval routes will be based. This is an eBusiness Suite transaction, for example creating a new vacancy in iRecruitment or creating purchase orders. There are many different Transaction Types seeded within the application to meet the requirements of the most common transactions which occur within the eBusiness Suite that would require an approval to take place. If you are integrating a bespoke application with AME, then new Transaction Types can be defined within AME. However, the creation of new Transaction Types is not a straightforward task, and Oracle discourage this because of the amount of programming effort that is required to integrate a new Transaction Type with AME.

Attributes

Within AME, Attributes can be defined as business variables which represent the value of an element in a transaction. For example, in the case of an invoice approval, a typical attribute would be the supplier name, or the invoice value. When defining the business rule, the attributes that are available to you will help define the rule itself and it’s implementation within AME. The reason for this is that the value of an Attribute for a transaction is usually evaluated as part of the rule in order to determine whether the condition has been met or not – for example, is this invoice worth more than £500? Within AME, Attributes can be created as static (where they have a constant value which remains the same for every transaction associated with the Attribute), or as dynamic (where they use a SQL query to determine the value of the Attribute at run time). Most Attributes that are used within AME are dynamic.

Within AME, there are different types of Attribute available to you:

• Strings can be alphanumeric and have a maximum length of 100 characters.
• Numeric attributes can have any numeric value that is acceptable in PL/SQL, including decimals and negative numbers. When using a numeric Attribute within AME, the number must be converted to a canonical form – within the FND_NUMBER package there is a function NUMBER_TO_CANONICAL which will do the conversion for you.
• Currency Attributes are used when the organization is using multiple currencies. This allows Oracle to perform currency conversions when retrieving the Attribute value. If currency Attributes are used, the SQL query which retrieves the value must include the numeric column, currency and conversion method. Additionally, any AME conditions which use currency Attributes must include a condition for EACH CURRENCY that the transaction might use.
• Boolean Attributes can only have a valid value of true or false. Any dynamic Attributes which are defined as Boolean MUST return one of these two states – NULL is not a valid value in an AME Boolean Attribute. When using Boolean Attributes, AME provides a format string which should be used – AME_UTIL.BooleanAttributeTrue and AME_UTIL.BooleanAttributeFalse.
• Date Attributes are commonly used within AME – for example the invoice date, shipping date, and so forth. Again, AME is particular with the format and requires all date Attributes to be in the format YYYY:MON:DD:HH24:MI:SS. There is a format string again provided in the AME_UTIL package – AME_UTIL.versionDateFormatModel which can be used to return a date in the required format.

Every Transaction Type that is defined in AME as standard uses several mandatory Attributes which can be considered runtime parameters, since they are commonly used to determine the behaviour of AME during execution. The mandatory attributes which are defined for all Transaction Types are:

• ALLOW_DELETING_RULE_GENERATE_APPROVERS
• ALLOW_REQUEST_APPROVAL
• AT_LEAST_ONE_RULE_MUST_APPLY
• REJECTION_RESPONSE
• USE_RESTRICTIVE_ITEM_EVALUATION
• EFFECTIVE_RULE_DATE
• EVALUATE_PRIORITIES_PER_ITEM
• USE_WORKFLOW
• WORKFLOW_ITEM_KEY
• WORKFLOW_ITEM_TYPE
• REPEAT_SUBSTITUION

For more information of the mandatory Attributes and how AME interprets them, you should consult the AME Implementation Guide.

In addition to mandatory Attributes, AME also includes the concept of a required Attribute. These are similar to mandatory Attributes (in that they must be populated), the only difference being that required Attributes are defined for a specific Transaction Type rather than for all Transaction Types.

Requires and mandatory Attributes are seeded with default values, which can be modified to meet the exact requirements of a specific Transaction Type.

Conditions

The next component to look at within AME is Conditions. These are used to evaluate the value of an Attribute (or Attributes) for a particular transaction – this is where the “IF” part of each business rule is defined.

Each Condition returns either a true or false flag, and the result is then used by AME to determine whether the business rule has been met or not. If the approvals code were to be written in plain PL/SQL, then this would be an IF statement.

In the example from the last post of “if the invoice value is over £500 then additional approval is required”, AME would retrieve the value of the invoice total Attribute and determine whether the Condition “> 500″ was met or not.

There are three different types of Condition within AME – Ordinary-Regular, Ordinary-Exception and List Modifier:

• Ordinary-Regular Conditions associate an Attribute with a value or range of values – for example, SELLER_NAME = ‘Smith Widgets Ltd’, or 20000 > INVOICE_AMOUNT > 1000 (i.e. invoice amount is greater than 500 and less than 20000).
• Ordinary-Exception Conditions are similar to Ordinary-Regular Conditions, but are limited to the types of rules to which they can be applied. When we look at Rules later in the post, I will go into more detail.
• List-Modifier Conditions are used to modify the approval list based on the contents of the existing approval list. For example, “If Bob is the last approver, then include his supervisor”

Action Types and Actions

Within AME, Actions define what should the Engine do when a transaction satisfies a particular Condition. It is these Actions which helps to determine which approvers are included in or excluded from the list being generated.

Action Types are collections of Actions which have similar functionality, such as the approval hierarchy that should be used when generating an approver list. For example, the Actions which relate to building an approval list based on the HR hierarchy would be grouped together as one Action Type – all Actions for this Action Type are all related to using the same hierarchy, but would differ based on the number of levels that need to be retrieved. Each of the Actions within the Action Type would typically describe the number of levels used by the common hierarchy, and they are then collected together in one Action Type based on the hierarchy used.

As standard, a range of different, common Action Types are provided by AME, which generally meet the requirements of most organizations, but custom Action Types can be defined if necessary. The different seeded Action Types can be grouped into four different hierarchy types that they support:

• Chain of Authority
  • These Action Types typically use the position or supervisor hierarchy from HR to generate the approver list. These Action Types typically use the position or supervisor hierarchy from HR to generate the approver list. Depending on your patch set, you may not have all of the following Action Types (or, conversely, you may have additional Action Types not listed here!):

• List Modification
  • As with the Chain of Authority Action Type, the List-Modification uses the HR supervisor hierarchy to generate the approver list. However, the List Modification (as the name suggests!) is used to modify the generated list to either include additional approvers, or to exclude approvers that have been identified from the hierarchy. For example, if there is a business rule that stipulates that for all IT purchases, the most appropriate final approver is the IT Manager rather than the Finance Manager (who normally approves the transactions), then a List Modification would be applied to modify the generated list of approvers. There are two types of List Modification Action Type:

• Substitution
  • Substitution Action Types allow for one approver to be substituted for another whenever the approval chain involves them. For example, in the absence of one person, route the approval to a different person.

• Approver Groups
  • Approver Group Action Types allow either a static or dynamic approver list to be generated. If the list is static, then the names of specific individuals responsible for the transactions is included when the group is defined; if the list is dynamic then the name(s) included in the list are returned by a SQL statement.

Rules

As with Actions and Action Types, Rules also use Rule Types to determine the list to build if the results of the Rule are true. Depending on the Transaction Type, different Rules are available – the following table discusses the Rule Types that are available for iRecruitment Vacancy Approval in Release 12.1.1:

Configuration Variables

One final component of AME which I have not mentioned so far are Configuration Variables. Configuration Variables are normally set during the initial AME build / configuration, as they impact every AME transaction – in the same way that profile options can be set at different levels, AME Configuration Variables can be set on a system-wide or a Transaction Type basis.

The Configuration Variables for AME in Release 12.1.1 are as follows:

Matt

AME is an “easy” way for a business analyst / functional consultant to define business rules for transaction approvals within eBusiness Suite. Not all applications modules support AME, however, in which case you are back to the age-old bespoke method of identifying approvers and including custom logic to ensure that the right people are included within the approvals process. Note that I have used inverted commas for the word “easy” – AME provides the opportunity to include business rules which can vary widely in complexity.

In this post, I’ll be looking at the components of AME which are required for configuration, and in later posts I’ll move onto some practical examples from within iRecruitment and Financials.

AME Basics

As I said earlier, the purpose of using AME is to implement specific business rules within the framework of the application to manage the approval of a transaction. This can always be done outside of AME (and for some modules, this is still a requirement!), but if the approvals process can be captured within AME then this makes for a more straightforward implementation which (theoretically at least) is easier to maintain over the long-term. When approval is sought, AME uses Workflow notifications to inform the approver that they need to action the request, and to capture their response.

AME (as I said earlier) allows you to implement rules of differing complexity – for example, any invoices which are over £500 must be approved by the requester’s supervisor; all vacancies created in iRecruitment must be approved by Bob in HR; and so forth. Many organizations, however, have much more complicated – for example, any invoice which is matched to a purchase order and has any lines which are over £5000 and include heavy machinery must be approved by the Operations Manager and his immediate supervisor (or the next available supervisor with the appropriate authorization limit). The flexibility that AME brings means that the same method can be adopted for any of these requirements.

So, why bother with AME?

As I said earlier, you can already build all of this through custom code – and in versions of the eBusiness Suite that were availably prior to AME, that is what most organizations did. However, there are some clear advantages of managing the approvals process using AME over using bespoke software.

Firstly, in many cases, business rules can be defined and implemented without the need for any code. Now that’s a big one, so I’ll say it again – IN MANY CASES, BUSINESS RULES CAN BE IMPLEMENTED WITHOUT THE NEED FOR ANY CODE. Less code means less things to maintain, and less things to go wrong (assuming that the functional configuration is correct and the code is always the thing to go wrong, but we’ll not go there in this post!!).

Secondly, if there are already hierarchical structures defined in the application, then AME can leverage these as standard – again, there is no need to write custom code to find the next available approver, since AME does it automatically.

Another advantage of using AME is that if there are specific requirements to route an approval to a specific group of people or an individual, then AME provides the person making the functional configuration with the ability to setup specific hierarchies or approval groups which can be used to determine where to route the approval.

The last main benefit (and it’s a good one!) is that AME has the ability to respond to any changes in the approvals process whilst the process is still going on. This includes, for example, a change in the approvals hierarchy (which can be included fairly easily within custom code) but also if the business rules themselves are modified during the process, or even if the values of the transaction themselves change during the process – now that’s clever! Every time an approver for a transaction responds with an approval, AME checks the rules as they stand at that point in time, and rebuilds the approver list to determine who the next approver should be. So, let’s take the simple example above where if the invoice is over £500 then the supervisor must approve the invoice. An invoice for £1500 is created, AME checks the business rules and notifies the supervisor. The business analyst then decides that if the invoice is over £1000, it requires three levels of approval, and so makes the change within AME. When the supervisor responds to the notification, AME rebuilds the approval list using the new rules, identifies who the next approver should be, and then routes the transaction to them for approval.

That’s the end of my very quick overview of what AME is and why you should use it – in the next post, I’ll go into the components of AME and how they work together.

So now that I have VMWare running, here’s my version – Linux running Linux

There is some degree of official guidance on what you need to do now, contained in Metalink note 754993.1 – “How can you Avoid Bouncing the Database after Changing a WF Package”.  The advice is, to be honest, perhaps a little Draconian and unwieldy, but the guidance from Oracle is that all you need to do is:

1. Shut down the concurrent managers
2. Flush the shard pool
3. Update the package
4. Restart the concurrent managers

Now, that certainly will do it (so would bouncing the database, though!) – the likelihood of a developer shutting down the managers, then flushing the pool, and THEN compiling their code is probably quite low, though

ps -ef
UID   PID  PPID C    STIME TTY TIME CMD
oracle    4325  5180 0 12:00:04 ?   0:00 sqlplus system/manager
appluser  3118  3012 0 12:00:03 ?   0:00 sqlldr scott/tiger
appluser 26332 24101 0 11:00:15 ?   0:00 imp matt/matt full=y

As you can see – if you pass in the username and password, then anyone can easily find it out using ps!

So, how go you get round it?  If you can’t connect from within the tool (as you can in SQL*Plus), you can use a password file, which you should then delete once you have done the job, e.g. “sqlldr parfile=$PWDFILE….” where the file contains “userid=matt/matt”.

In order to make it even more secure, then you could use temporary files for your password file, e.g.

PWDFILE=$(mktemp)
echo "userid=matt/matt" > $PWDFILE
sqlldr parfile=$PWDFILE ....
rm $PWDFILE

mktemp is a utility which will create a temporary file with a unique name.

Now, following my PEMDAS (I had two years in an American school when I was younger – for those in the UK, think BODMAS) – the sum would be calculated as (1/3) * 3 so would give 1 as the result – try it in any calculator and you should get the same result.

Try it in Oracle, and you get the same:

SQL> SELECT 1/3*3 FROM DUAL;
1/3*3
-----
1

That’s all fine – now try a slight variation:

SQL> SELECT 'OK' FROM DUAL WHERE 1/3*3 = 1;
no rows selected

Hmmmm – so even though it returns 1, it doesn’t equal 1….  Is it true for all values?

SQL> SELECT * FROM DUAL WHERE 1/3*3=1;
no rows selected

SQL> SELECT level, CASE WHEN 1/level*level = 1 THEN 'OK' END ok FROM DUAL CONNECT BY level <= 20;
L O
———- -
1 OK
2 OK
3
4 OK
5 OK
6 OK
7 OK
8 OK
9
10 OK
11
12
13
14
15 OK
16 OK
17 OK
18 OK
19
20 OK

So, there you have it – a handful (and there are more) of examples where 1 !=1 in Oracle!!