|Oracle Fusion Middleware Adapter for Oracle Applications User's Guide|
11g Release 1 (11.1.1)
Part Number E10537-02
This chapter covers the following topics:
Applications context is required for secured transaction processing into and out of Oracle Applications.
Applications context is a combination of Username, Responsibility, Responsibility Application, NLS Language, Security Group, and Organization ID. These elements are used in passing values that may be required in a business activity or to complete a BPEL process.
To establish applications context, the Organization ID is implicitly derived from the Oracle Applications setup data.
To understand applications context, you need to first understand how Organization ID and multiple organizations are related.
You can define multiple organizations and the relationships between them in a single installation of Oracle Applications. These organizations can be sets of books, business groups, legal entities, operating units, or inventory organizations.
Multilevel organization hierarchies can be defined with a business group at the top of each hierarchy. When you define new organizations, they are automatically assigned to the business group associated with your current session. Each organization is part of a business group. The business group is usually the top box on an enterprise organization chart.
Business Group Hierarchy
Example of a Multiple-Organization Setup
Using the accounting, distribution, and materials management functions in Oracle Applications, you define the relationships among inventory organizations, operating units, legal entities, and sets of books to create a multilevel company structure, as shown in the following diagram.
A Multiple-Organization Transaction
Consider two different organizations in your company: One is a French sales office and the other is a German warehouse. There is a sales order transaction with the customer, and this illustrates how the entire Order-to-Deliver process would work:
The customer places a sales order with the French sales office.
The German warehouse delivers the product shipment to the customer.
The German warehouse issues an inter-company invoice to the French sales office.
The French sales office makes the inter-company payment to the German warehouse.
The French sales office sends the customer invoice to the customer.
The customer makes payment to the French sales office.
The database architecture is the same for a multiple-organization and non-multiple-organization installation, and uses the standard install tools feature that automatically creates synonyms in the APPS schema for each base product table and defines these synonyms with the same name as the base product tables. For example, the PO Oracle schema has a table named PO_HEADERS_ALL and the APPS schema has a corresponding synonym of the same name, PO_HEADERS_ALL. The PO_HEADERS_ALL synonym can be used to access unpartitioned data.
Multi-Organization Access Control (MOAC) Security by Operating Units
While setting up the system profile values, the username and responsibility are tied up with the organization or operating units.
Multiple-Organization System Profiles
To have a secured way for users to only access or report on data for the operating units they have access to, Adapter for Oracle Applications uses the MOAC security feature to determine the operating unit access privileges and derive the Organization ID based on relevant profile values.
With MOAC, a system administrator can predefine the scope of access privileges as a security profile, and then use the profile option MO: Security Profile to associate the security profile with a responsibility. By using this approach, multiple operating units are associated with a security profile and that security profile is then assigned to a responsibility. Therefore, through the access control of security profiles, users can access data in multiple operating units without changing responsibility.
Security profiles are defined based on organization hierarchies. For example, a sales company consists of USA and UK operating units; the USA operating unit has Western Region Sales and East Region Sales. Sales managers are responsible for both USA and UK sales, supervisors are responsible for either USA or UK, and sales representatives are only responsible for their designated sales regions. The Sales organization hierarchy can be illustrated as follows:
Sales Organization Hierarchy
To secure sales data within the company, relevant operating units can be associated with predefined security profiles. For example, all sales data access privileges are grouped into the Vision Sales security profile. A USA Sales security profile is created for USA related data, and a regional security profile is created for designated regional data. The system administrator can associate these security profiles containing multiple operating units with users through appropriate responsibilities. Therefore, sales supervisors can easily access sales data in the Eastern or Western region without changing their responsibilities. The following diagram illustrates the relationship between security profiles, responsibilities, and operating units for this sales company:
Relationship Diagram Between Security Profiles, Responsibilities, and Operating Units
Responsibility Determines Operating Units
Because responsibilities are associated with security profiles that linked to operating units, your responsibility is the key in determining which operating units you will have the access privileges.
The following diagram illustrates how Oracle Applications use the profile options in a multi-organization environment:
Building Applications Context for Multiple Organizations
When the system integrator runs, the process achieves the integration with Oracle Applications using PL/SQL APIs.
Applications context is set, taking into account the values passed for the header properties Username, Responsibility, Responsibility Application, Security Group, and NLS Language. If the values for the new header properties Responsibility Application, Security Group, and NLS Language are not passed, context information will be determined based on Username and Responsibility.
With these parameters, a lookup on all System Profile Values assigned to that responsibility is done to determine the Operating Unit within a multi-organization environment.
The Operating Unit is modeled as Organization ID derived from the security profile value.
The data is read and written into the Oracle Applications with the parameters of Username, Responsibility, Responsibility Application, Security Group, NLS Language, and Organization ID.
To integrate business processes or invoke BPEL processes, it is essential to propagate these applications context values or messages through a flexible mechanism that allows you to effectively set each individual context value if needed and pass them to complete a BPEL process and meet integration needs.
The following topics are discussed in this section:
To effectively set applications context values required in a BPEL process or to populate mandatory header variables for XML Gateway inbound transactions to be completed successfully, Adapter for Oracle Applications provides a flexible mechanism that allows each context value and header variable to be set and passed in the adapter user interface directly through the Invoke activity. This message normalization feature not only provides a flexible solution on header support, but also simplifies the design-time tasks without using an Assign activity to pass header values.
Setting Message Properties for Applications Context
The following header message properties are used in setting applications context required in a business activity or to complete a BPEL process:
Note: Existing header property jca.apps.Responsibility used in the earlier releases can now take Responsibility Key as well as Responsibility Name as input. If the header property jca.apps.NLSLanguage is set, and Responsibility Name is passed, the value passed for jca.apps.Responsibility is expected to be in the same language. However, Responsibility Key as well as all other header properties are language independent.
All these header properties would be used together to set the application context. Alternatively, passing just the Username and Responsibility would work as it did in the earlier releases.
In the case of a null or empty value, the default Username is SYSADMIN, the default Responsibility is System Administrator, the default Security Group Key is Standard, and the default NLS Language is US.
Since the NLS Language and Organization ID property values are included in message normalization for supporting applications context, Adapter for Oracle Applications also supports the following features based on the concept of application context:
Setting Message Properties for XML Gateway Inbound Transactions
The following header message properties are used in setting XML Gateway information required for XML Gateway inbound/enqueue transactions:
Adapter for Oracle Applications uses the following procedures to complete the design-time tasks to support message normalization:
Note: At run time, the XML Gateway message properties should be processed before invoking AQ Adapter.
Create a new BPEL project
Create a partner link
Configure an Invoke Activity
This activity involves the following tasks:
Configure basic information in the General tab:
Configure an Invoke activity by linking the activity to the partner link you just created. This opens the General tab in the Edit Invoke dialog box with Partner Link and Operation information populated.
You can create an Input Variable and a Output Variable for the Invoke activity.
For detailed instructions, see Configure basic information in the General tab
Set the Header Message Properties in the Properties tab:
This is to set the necessary message properties for the following purposes:
To set XML Gateway header variables for an inbound transaction.
For example, locate XML Gateway header property jca.apps.ecx.TransactionType first and then enter a value (such as 'PO') for the selected property.
Entering a Selected Property Value
For detailed instructions, see Setting ECX Header Message Properties.
To set applications context for Oracle Applications to identify the application user, responsibility, and the user's associated organization information.
For example, locate the jca.apps.Username property from the property list and then enter 'OPERATIONS' as the property value.
Header Property Values
For detailed instructions, see Setting the Header Properties for Application Context.
Instead of implicitly deriving organization information from a profile value during the Oracle Applications setups, based on message normalization feature, Adapter for Oracle Applications allows Organization ID information to be directly entered through the Properties tab of an Invoke activity during the design time to support multiple organization setups.
Adapter for Oracle Applications uses the header properties to include Username, Responsibility, Responsibility Application, NLS Language, Security Group, and Organization ID, the essential elements for applications context. Once you set the message properties contained in the header for a business activity through a PL/SQL API or an interface which requires the applications context to be set, these values in the header will be passed and used as an input to the rest of activities in the BPEL process.
Note: Integration interface types that require applications context to be set are PL/SQL APIs, concurrent programs, and EDI programs.
Setting Header Message Properties
The advantage of having this header message properties mechanism in supporting multiple organization setups is that with only one single BPEL process, organization information can be easily placed into multiple organizations within the Oracle E-Business Suite if the Organization ID value has been specified in the header. While in the past, since Organization ID is implicitly derived from the profile value based on an application logon user's username and responsibility; therefore, only that associated organization for the invocation of the deployed BPEL process can be inserted.
With the example described earlier in the Multiple Organization Setup section, when a change order is placed within the French sales office, a sales manager from the French office logs on to the system to update the order which invokes a PL/SQL API for that change. If the Organization ID contained in the header has been assigned with a property value, such as 207 for the French sales office, the Organization ID associated with the sales manager will be set to French sales office for the invocation of the API.
Note: For Oracle E-Business Suite Release 12, Organization ID is automatically included in the header along with other applications context elements. For Release 11.5.10, you must apply 11i.ATG_PF.H.delta.5 (RUP5) (patch 5473858) to Oracle Applications instance in order to have Organization ID displayed in the header.
By leveraging the message normalization feature addressed earlier and the Multiple Language Support (MLS) feature from Oracle E-Business Suite, Adapter for Oracle Applications provides a comprehensive language support mechanism that allows an appropriate language to be dynamically set at run time.
NLS Language Property Value Takes the Priority
When an application user retrieves data from the system for a transaction or receives error messages while executing APIs, the session language of data or error messages can be determined based on the following conditions:
The NLS Language value can be set by using the header property jca.apps.NLSLanguage. If a valid language value is passed (i.e. language is enabled in Oracle E-Business Suite instance), the session language is set to the corresponding language.
In case the NLS Language header property is not passed, Adapter for Oracle Applications will use the default language of the user, based on the user preferences, to set the session language.
If the user's default language is not found or set, NLS Language (jca.apps.NLSLanguage) property value would be set to 'US' (American).
This mechanism allows an appropriate session language to be dynamically set at run time first based on the passed NLS Language property value, then the user's default language, and last determined by the default NLS Language property value 'US'.
For more information about how to set NLS Language property value by using jca.apps.NLSLanguage, see Supporting for Normalized Message Properties.
Determining a User's Default Language
To identify the default language used in the database session for data query and retrieval, Adapter for Oracle Applications will first examine the ICX: Language profile value at all levels including user, responsibility, application, and site. If it is not set at any of those levels, Adapter for Oracle Applications then takes NLS_LANGUAGE parameter from the database instance National Language Support (NLS) parameters. The NLS parameters initialized in the session are:
For example, when a user with a default language Japanese logs into the system and performs a transaction through the execution of an API that the user defined in the Partner link of the BPEL process, Adapter for Oracle Applications will first examine if the NLS Language property value is passed. If it is passed with a valid language, then the session language will be set based on the passed value regardless of the default language. If the NLS Language property is not passed, Adapter for Oracle Applications will set the session language to the preferred / default language of the user. In case that cannot be found, the language would be set to 'US' (American). The default language is set in the General Preferences page of Oracle Applications.
Note: The default language set in the General Preference page updates the ICX: Language profile option.
When the applications context is set, user preferences like date formats, time zone information, etc. would be taken care automatically.
Please refer to the Set Preferences section, Getting Started with Oracle Applications chapter, Oracle Applications User’s Guide for the information on how to set the user preferences.
Security is the most critical feature that is designed to guard application content from unauthorized access. By leveraging Oracle User Management function security, Adapter for Oracle Applications provides a security feature which only allows users with authorized privileges to execute APIs that they are exposed through the BPEL process to update Oracle Applications. This protects application programming interfaces (APIs) from unauthorized access or execution without security checks.
Please note that Adapter for Oracle Applications provides this security support as an optional feature. If you want all the login users to access and execute APIs without security checks, you can turn the security feature off using the "EBS Adapter for BPEL, Function Security Enabled" (EBS_ADAPTER_FUNCTION_SEC_ENABLED) profile option.
If it is set to 'Y', then the function security feature is enabled and all API calls for PL/SQL APIs, Oracle e-Commerce Gateway, and concurrent programs will be checked for user security before they are invoked.
If it is set to 'N' (default value), then the function security feature is disabled. No security check is implemented during the invocation of all API calls.
Note: For more information about this feature, see "Oracle Fusion Middleware Adapter for Oracle Applications, Release 11g", My Oracle Support Knowledge Document 787637.1 for details.
This section includes the following topics:
Function security is the basic access control in Oracle Applications. It restricts user access to individual menus and menu options within the system regardless of which application data in the row. Since APIs are stored procedures that enable you to insert and update data in Oracle Applications, when having the function security layer enforced on the access to an API, it actually implicitly restricts the data access to the application.
To allow appropriate users with right privileges to execute APIs, Adapter for Oracle Applications leverages Oracle User Management Role-Based Access Control security (RBAC) to reinforce the function security through user roles and whether a user can access an API is determined by the roles granted to the user. A role can be configured to consolidate the responsibilities, permissions, permission sets, and function security policies that users require to perform a specific function. This simplifies mass updates of user permissions because changes can be done through roles which will inherit the new sets of permissions automatically. Based on the job functions, each role can be assigned a specific permission or permission set if needed. For example, a procurement organization may include 'Buyer', 'Purchasing Manager', and 'Purchasing Support' roles. The 'Purchasing Manager' role would include a permission set that contains all Purchase Order (PO) Creation, PO Change, and Contract PO related APIs allowing the manager role to perform a job function while the Buyer or Support role may not have the access privileges.
In Adapter for Oracle Applications, all annotated APIs resided in Oracle Integration Repository are registered on the FND_FORM_FUNCTIONS table so that the function security (FND_FORM_FUNCTIONS) can be applied. This allows the creation of a secured function for each API.
By leveraging the concept of permission sets, Adapter for Oracle Applications allows related APIs to be grouped and sequenced under one permission set; each permission set can be associated with a function role and then assigned to users through security grants. When a user logs in to Oracle E-Business Suite and tries to access an API exposed through the BPEL process, if the security feature is enabled, the function security API will be invoked to validate whether the user is authorized to have the execution privileges on the API.
For example, if a user does not have the access privileges for a PL/SQL API exposed through a BPEL process, the execution of that BPEL process will fail while trying to invoke the PL/SQL API.
Without the authorized privileges, the Function Security Validation Exception message will be raised indicating that the user does not have the privilege for a specific PL/SQL API.
For more information on Function Security and RBAC security models, see Oracle Applications System Administrator's Guide - Security for details.
To secure the API invocation only to a user with appropriate execution privileges, Adapter for Oracle Applications uses the following steps to create security grants to users through user roles:
Creating a Permission Set
Creating a User Role
Granting a Permission Set to a User Through a Role
Use the following steps to create a permission set:
Log in to Oracle E-Business Suite using the System Administrator responsibility.
Select Application: Menu from the Navigator to access the Menus window.
Enter the following menu information:
Menu: Enter an appropriate menu name (such as 'OE_PROCESS_LINE_PS').
User Menu Name: Enter an appropriate user menu name (such as 'Order Manager Process Line Permission Set').
Menu Type: Permission Set
Description: Enter description information for this menu.
Add all the functions that you want to group on this Permission Set by entering values for Seq and Function.
Enter the Seq field.
In the Function column, search for the functions you want to assign to this permission set.
Select an appropriate function name by performing a search in the Functions window. For example the syntax for searching public PL/SQL APIs is:PLSQL:<package name>:<procedure name>. You can enter %PLSQL:OE% in the Find field and click Find to execute the search.
Searching for Functions
Based on your BPEL process, select appropriate functions and then grant the permissions to the APIs that you will be invoking from the BPEL process.
For example, for a sales order line change BPEL process, you select sales order line change related functions contained in the order change PL/SQL API and group them as a permission set, and then grant the permission set to an appropriate user through a role.
See: Creating a User Role.
Permission Set Menu
Save the Permission Set.
Permission sets are granted through user roles. Therefore, you must first create a role and then assign the role to a user.
Use the following steps to create a user role:
Log in to Oracle E-Business Suite using the User Management responsibility.
Select Roles & Role Inheritance from the Navigator to access the Roles & Role Inheritance page.
Click Create Role to access the Create Role page.
Enter the following information to create a role:
Category: Select Miscellaneous from the drop-down list.
Role Code: Enter an appropriate role code (such as 'EBS_ADAPTER_ROLE').
Display Name: Enter appropriate information for the display name (such as 'EBS Adapter Role').
Description: Enter appropriate information for the description (such as 'EBS Adapter Role').
Application: Select an appropriate application (such as 'Application Object Library').
Active Date: Enter an appropriate date which is earlier than or equal to today's date so that the role can become valid right away.
Save the information and click Create Grant.
Enter the following information in the Create Grant: Define Grant page:
Name: Enter an appropriate name (such as 'EBS_ADAPTER_GRANT').
Description: Enter description information for this grant.
In the Create Grant: Define Object Parameters and Select Set page, select the Permission Set you created earlier in the Creating a Permission Set section and click Next.
Use the following steps to grant a permission set to a user through a role:
Log in to Oracle E-Business Suite using the User Management responsibility.
Select Users from the Navigator to access the User Maintenance page.
Search for the user you want to assign the role and click Go.
Select the Update icon next to the user name that you want to assign the role.
In the Update User page, click Assign Roles to have the Search window populated which allows you to search for the role that you created earlier.
Select the role (such as 'EBS_ADAPTER_ROLE') and save your update.
By implementing the J2EE Data Source for secured connection between Oracle E-Business Suite and Oracle SOA Suite, two distinct advantages can be leveraged. Firstly, to get the secured connection to the Oracle E-Business Suite's application database you do not require the database administrator's username and password, just FND username and password (concept of Oracle Applications username and password) is sufficient. Secondly, since the password is not stored in the middleware, not only this eliminates the security risk, but also does away the need to keep the password in-sync between Oracle E-Business Suite and SOA Suite.
Oracle Adapter for Oracle Applications uses a new mechanism to authenticate users at run time and get the connection to Oracle E-Business Suite databases through the use of J2EE data sources. This approach is native to Oracle E-Business Suite in defining the connection pool to access the application database.
With this new mechanism, account details information including application login user name and password that was required as part of the configuration for database connection is now added together with the dbc file location as input parameters during the J2EE data source creation.
To accomplish this process, the following steps are used to define J2EE data source connection to the Oracle E-Business Suite database:
Register your Service-Oriented Architecture (SOA) suite middle tier node on the Oracle E-Business Suite environment and generate the dbc file used by the data source implementation to instantiate the connections.
Copy the dbc file to the middle tier server where your SOA suite server runs, and place it on a location in the file system to which the SOA suite owner has access.
Create a connection pool where you need to enter the application login user name, password, and dbc file location as the connection factory properties.
Create an application data source. This is the step that you associate the application data source with the Java Naming and Directory Interface (JNDI) name for the application database connection for Oracle Adapter for Oracle Applications.
To enable the native Oracle E-Business Suite connectivity using J2EE data sources feature,
Note: To have this feature available, the minimum requirement for Oracle E-Business Suite Release 11i is 11i.ATG_PF.H.Delta.6 (RUP6) and for Oracle E-Business Suite Release 12 is 12.0.4 release.
Additionally, you must apply necessary patches to enable the connectivity between Oracle E-Business Suite and an external application server. See "Oracle Fusion Middleware Adapter for Oracle Applications, Release 11g" My Oracle Support Knowledge Document 787637.1 for details.
In addition to the interfaces that are made available through Oracle Integration Repository, Adapter for Oracle Applications enables you to use business events, customized PL/SQL APIs, customized XML Gateway maps, and selected concurrent programs, all of which you can explore using the Oracle Applications Module Browser.
Oracle Applications Module Browser
The Oracle Applications Module Browser is a key component of Adapter for Oracle Applications. You use the Module Browser to select the interface needed to define a partner link. The Module Browser combines interface data from Oracle Integration Repository with information about the additional interfaces supported by Adapter for Oracle Applications, organized in a tree hierarchy as follows:
ProductFamilies |-[product_family] | |-[product] | |-[business_entity] | |-XML Gateway ([n]) | |-EDI ([n]) | |-PLSQL ([n]) | | |-[package_name] | |-OpenInterfaces ([n]) | |-[OpenInterface_name] | |-Tables ([n]) | |-Views ([n]) | |-ConcurrentPrograms ([n]) |-Other Interfaces |-Business Events |-Custom Objects |-PLSQL APIs | |-[package_name] |-XMLGateway Maps |-Inbound |-Outbound
The items under Other Interfaces, as well as certain PL/SQL APIs and concurrent programs under the [product family] hierarchy, are available through Adapter for Oracle Applications, but not through Oracle Integration Repository.
The number of interfaces indicated by [n] only appears in the case of an Oracle E-Business Suite 11.5.10 instance is used. It will not be displayed if you are connecting to an Oracle E-Business Suite pre-11.5.10 or Release 12 instance.
The Oracle Integration Repository interface data populates the [product_family] sections, grouped according to the products and business entities to which they belong. Each interface type heading is followed by a number [n] indicating how many of that type are listed in that section.
Business events appear under Other Interfaces. Customized XML Gateway maps appear under Other Interfaces > Custom Objects, categorized as either inbound or outbound.
Customized PL/SQL APIs appear in two places:
Procedures within a package that's already exposed via Oracle Integration Repository appear under the package name within a product family hierarchy.
Procedures within a completely new package appear under the package name, under Other Interfaces > Custom Objects.
Copyright © 2005, 2009, Oracle and/or its affiliates. All rights reserved.