|Oracle Fusion Middleware Adapter for Oracle Applications User's Guide|
11g Release 1 (22.214.171.124.0)
Part Number E10537-04
This chapter covers the following topics:
Applications context is required for invoking interfaces within Oracle Applications. Applications context is a combination of Username, Responsibility, Responsibility Application, and Security Group. These elements may be required for executing an interface successfully within Oracle Applications.
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 allow access or report on data for the operating units they have access to, many of the interfaces within Oracle Applications make use of the MOAC security feature to determine the operating unit access privileges and derive the Organization ID based on relevant profile values. Adapter for Oracle Applications can implicitly perform the requisite MOAC setup. If ORG_ID is passed, data access would be set to the passed Organization ID.
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.
When integrating with Oracle Applications using PL/SQL APIs or Concurrent Programs, applications context is set based on the values passed for the header properties Username, Responsibility, Responsibility Application and Security Group.
Note: For backward compatibility reasons, no context related exceptions or errors would be thrown if none of the following header properties are passed - Responsibility Application, Security Group, and NLS Language.
MOAC setup is done based on the Responsibility Application to which the user belongs. If Organization ID is passed, the Organization access would be set to the passed Organization.
If the user needs the invocation of the interface to happen in a desired language, then the header property NLS Language can be passed. Default value for NLS Language would be the language specified in the user's preference in Oracle Applications.
To integrate business processes with Oracle Applications, it is essential to propagate these applications context values through a flexible mechanism, which is provided by Adapter for Oracle Applications through the header properties.
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 properties are used in setting applications context for PL/SQL and Concurrent Program interfaces:
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.
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:
Create a new SOA Composite application with BPEL process
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 Applications Context.
Adapter for Oracle Applications allows Organization ID to be passed as a header property which is available as jca.apps.ORG_ID within the Properties tab of an Invoke activity during the design time.
On Oracle Applications subsequent to Release 12.0, MOAC setup is automatically done using the call MO_GLOBAL.INIT(<Application Name>). Subsequently, if ORG_ID is passed, the call to MO_GLOBAL.set_policy_context('S', <ORG_ID>) would be made to set the Organization access to the specified ORG_ID.
Setting Header Message Properties
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.
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 Support 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 E-Business Suite chapter, Oracle E-Business Suite 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 security mechanism, 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.
Function Security with Role-Based Access Control (RBAC)
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.
Building on function security, data security provides another layer of security control to model or enforce security authorizations of specific data records. In other words, data security further refines the security of accessing application records down to the data level.
To provide granular security control and allow only 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. Whether a user can access an API is determined by the roles granted to the user. This approach builds upon data security and function security, but it goes beyond both of them.
Function Security with Role-Based Access Control
To better understand how the security works for Oracle Adapter for Oracle Applications, the following topics are included in this section:
Adapter for Oracle Applications now provides a way to handle access control for overloaded PL/SQL APIs. This feature works in conjunction with the grants created from the Integration Repository user interface, and it does not depend on any profile options.
Note: This security support would work with all interfaces which are available in the Integration Repository. For other interfaces, you need to enable the function security through the profile option mentioned in the section Function Security Support through Profile Option.
For this purpose, two new JCA properties are introduced:
If a user wants the Function Security Authorization check to be performed, the following property information needs to be added in the WSDL file (XX_apps.jca):
<property name="DataSecurityCheck" value="yes"/>
However, the other property IRepOverloadSeq is derived automatically by Adapter for Oracle Applications at the design time during creation of the partner link. Based on these two properties, the function security check would be done for the username, which is passed as a header property.
Creating Security Grants through Integration Repository
This type of data security check for overloaded functions works in conjunction with security grants created through the Integration Repository user interface. This security grant can be performed in the Create Grant page for a given interface type to control the method at a very granular level.
An integration repository administrator can select one or more methods in a PL/SQL API and then authorize a user, user group, or all users to execute the selected method(s) by creating appropriate security grants.
Creating Grants in Integration Repository
In the Integration Repository user interface, each overloaded function contained in an interface can be uniquely granted to a specific user, user group, or all users through the create grant feature. If you select more than one overloaded function in the Procedures and Functions region (or the Methods region), in the Create Grant page an Overloaded column appears in the selected methods table indicating more than one overloaded function is selected for the grant.
For more information on how to create security grants using the Integration Repository user interface, see Managing Security Grants, Administering Native Integration Interfaces and Services chapter, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide for details.
Based on the function security with Role-Based Access Control (RBAC), security access control is defined 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 that reside 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.
Enabling Function Security
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.
Note: Using "DataSecurityCheck" described in the earlier section for overloaded functions is the preferred way for interfaces listed in the Integration Repository because it is easy to create the security grants and doesn't depend on any profile options.
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.
When a user tries to invoke an API within the Oracle E-Business Suite through a BPEL process, if the function security profile is enabled, the invocation of the API would happen only after validation of the authorization 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 about this feature, see "Oracle Fusion Middleware Adapter for Oracle Applications, Release 11g", My Oracle Support Knowledge Document 787637.1 for details. For more information on Function Security and RBAC security models, see Oracle E-Business Suite System Administrator's Guide - Security for details.
To secure the API invocation only to a user with appropriate execution privileges, the following steps need to be performed on Oracle Applications to create security grants for the user using 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 Composite application, select appropriate functions and then grant permissions to the API that you will be invoking from the BPEL process or Mediator.
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.
Oracle Fusion Middleware Adapter for Oracle Applications implements the Oracle SOA Suite's logging framework to write the diagnostic log files in text format. Therefore, whenever the Oracle E-Business Suite services are invoked using Oracle Adapter for Oracle Applications, the log messages are recorded which can be accessed by system administrator. This enriches the problem identification mechanism to track any issues during service invocations at run time for Oracle Adapter for Oracle Applications.
Oracle Adapter for Oracle Applications and technology adapters implement the LogManager interface of JCA Binding Component, which redirects the log files for both inbound and outbound interactions to the soa-diagnostic.log file in the Oracle Diagnostic Logging (ODL) format. These log files record all types of events including startup and shutdown information, errors and warning messages, access information on HTTP requests, and additional information. It provides a quick, inside-out view about the invocation process which greatly helps administrators identify and resolve potential issues efficiently. With proper log-level configuration in Oracle Enterprise Manager Fusion Middleware Control Console, you can view ODL level log files written to a single file at run time for Oracle Adapter for Oracle Applications as well as technology adapters.
To better understand how the logging mechanism work, the following topics are discussed in this chapter:
For more information about SOA Suite, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.
All logs of Oracle Adapter for Oracle Applications and technology adapters are redirected to the soa-diagnostic.log file in the Oracle Diagnostic Logging (ODL) format. To be able to view logs for Oracle Adapter for Oracle Applications, you need to set or enable an appropriate message type and its associated log level for the logger oracle.soa.adapter using the Oracle Enterprise Manager Fusion Middleware Control Console. This enables the log settings at the Oracle SOA Suite level.
Note: The logger configuration is under $FMWHOME/user_projects/domains/soainfra/config/fmwconfig/servers/soa_server1/logging.xml and the corresponding logger name for all Oracle JCA Adapters is called oracle.soa.adapter.
The following table lists the diagnostic message types and log levels:
Note: For each message type, possible values for message level are from 1 (highest severity) through 32 (lowest severity). Some components support only some of the levels for each message type. Generally, you need to specify only the type; you do not need to specify the level.
The default message type for each logger is set to NOTIFICATION, level 1.
|INCIDENT_ERROR||1||A serious problem that may be caused by a bug in the product and that should be reported to Oracle Support.|
Examples are errors from which you cannot recover or serious problems.
|ERROR||1||A serious problem that requires immediate attention from the administrator and is not caused by a bug in the product. |
An example is if Oracle Fusion Middleware cannot process a log file, but you can correct the problem by fixing the permissions on the document.
|WARNING||1||A potential problem that should be reviewed by the administrator.|
|NOTIFICATION||1||A major lifecycle event such as the activation or deactivation of a primary subcomponent or feature.|
|NOTIFICATION||16||A finer level of granularity for reporting normal events.|
|TRACE||1||Trace or debug information for events that are meaningful to administrators, such as public API entry or exit points.|
|TRACE||16||Detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem.|
|TRACE||32||Very detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem.|
To set the diagnostic message type and log level for Oracle Adapter for Oracle Applications in SOA Suite:
Use the following procedures to set the message type and its associated log level:
Navigate to http://<servername>:<portnumber>/em.
The Oracle Enterprise Manager Fusion Middleware Control Console home page is displayed.
Enter username and password to log on to the console.
Right-click soa-infra from the SOA Folder in the Navigator tree.
Select Logs > Log Configuration from the pop-up menu.
Note: You can also access the Log Configuration page by clicking the SOA Infrastructure Menu and selecting Logs > Log Configuration from the drop-down menu.
This opens the Log Configuration page where you can view a list of loggers (persistent or active run time) and configure the Oracle Diagnostic Logging (ODL) level for setting the amount and type of information to write to a log file and the log level state.
Configuring Log Level for Adapters
Select the Log Levels tab.
Select one of the following values from the View drop-down list:
Runtime Loggers (default): Runtime loggers are automatically created during run time and become active when services are getting executed. For example, oracle.soa.b2b or oracle.soa.bpel are runtime loggers. Log levels for runtime loggers are not persistent across component restarts.
Loggers with Persistent Log Level State: Persistent loggers are loggers that are saved in a configuration file and become active when the component is started. The log levels for these loggers are persistent across component restarts.
Note: By default, the log level is set for Runtime Loggers. Runtime loggers do not persistent across when a component restarts. To ensure that log levels persist across component when it restarts, select Loggers With Persistent Log Level State from the View list.
Expand the oracle.soa node to locate oracle.soa.adapter runtime logger in the Logger Name list. Select the logging level from the Oracle Diagnostic Log Level drop-down list. For example, select 'TRACE:32 (FINEST)'.
Creating and Editing Log File in the Log Files Tab
You can edit a specific log file by clicking the log handler link displayed in the Log File column. This opens the Log Files tab where you can configure the basic and advanced log configuration settings. These settings include handler’s name, the log file in which the log messages are logged, the format of the log messages, the rotation policies used, and other parameters based on the log file configuration class.
For example, select the log handler from the table and click Edit Configuration. The Edit Log File dialog box is displayed.
To change log file location, enter a new path in the Log Path field.
To configure message levels, select the logging level from the Log Level drop-down list. For example, select 'TRACE:32 (FINEST)'.
To configure log file rotation, in the Rotation Policy section, select either Size Based or Time Based log file with appropriate information.
Fore more information on how to configure log file, see the Managing Log Files and Diagnostic Data Chapter, Oracle Fusion Middleware Administrator's Guide.
For more information about SOA Suite, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.
Based on the log level set for oracle.soa.adapter runtime logger in Oracle SOA Suite, logging can be automatically controlled or enabled for PL/SQL APIs and Concurrent Programs while these interfaces are invoked during run-time execution. There is no need to enable the FND logging framework on the Oracle E-Business Suite side separately.
Note: This automatic FND logging would be available in Oracle E-Business Suite releases 12.1.3 and above only.
The following table lists the log level mapping between oracle.soa.adapter runtime logger and the corresponding Oracle E-Business Suite:
|Runtime Logger oracle.soa.adapter Log Level||Oracle E-Business Suite Log Level|
|NOTIFICATION 1, 16, 32||LEVEL_EVENT|
|TRACE 16, 32||LEVEL_STATEMENT|
Oracle Adapter for Oracle Applications and technology adapters implement the LogManager interface of JCA Binding Component, which redirects the log files written to a single file at run time in the Oracle Diagnostic Logging (ODL) format.
For both outbound and inbound interactions, the log files are redirected to the single file soa-diagnostic.log.
The log files for Oracle SOA Suite that is deployed to the server-soa managed server are located in MW_HOME/user_projects/domains/<domain_name>/servers/server-soa/logs/soa-diagnostic.log.
To search and view Oracle Adapter for Oracle Applications log files, you can use Oracle Enterprise Manager Fusion Middleware Control Console, the WLST displayLogs command-line tool, or you can download log files to your local client and view them using another tool (for example a text editor, or another file viewing utility). For information on how to use WLST command-line tool to search and view log files, see the Managing Log Files and Diagnostic Data Chapter, Oracle Fusion Middleware Administrator's Guide.
Use the following steps to search Adapter Logs through the Oracle Enterprise Manager Fusion Middleware Control Console:
Navigate to http://<servername>:<portnumber>/em.
The Oracle Enterprise Manager Fusion Middleware Control Console home page is displayed.
Enter username and password to log on to the console.
There are two ways to access the Log Messages page from the Navigator tree in the left pane:
From the SOA folder, right-click soa-infra.
Navigating from SOA Folder
From the WebLogic Domain folder, right-click soainfra.
Navigating from WebLogic Domain Folder
Select Logs > View Log Messages from the pop-up menu. The Log Messages page is displayed with the Search section and a table that shows a summary of the messages with default search criteria.
Log Messages Page: Search
Enter the following search criteria for searching the log messages for Oracle Adapter for Oracle Applications:
Date Range: Select your value from the drop-down list and enter an appropriate number. For example, 'Most Recent' 6 hours.
If 'Time Interval' is selected from the drop-down list, select the calendar icon for Start Date and then select the date and time. Similarly, select the calendar icon for End Date and then select the date and time.
Message Types: Select one or more of the message types. For example, select the Trace check box if it is the message type configured earlier for Oracle Adapter for Oracle Applications.
Message: Select 'Contains' from the list of values and then enter 'Oracle Applications Adapter' in the text box.
Specify more search criteria if needed in the Search section.
You can optionally add more search criteria by clicking Add Fields. This action allows you to add more criteria, such as Host, which lets you narrow the search to particular hosts. Then click Add.
Execute the search by clicking Search. All messages that match your search criteria will be retrieved and displayed in the table. These messages can be displayed as messages, or can be grouped by message type or message ID depending on the selected value in the Show field.
Click one of the log messages from the table. The selected message details, such as message level, component, ECID (Execution Context ID), Relationship ID, actual message, are displayed below the table of messages.
Clicking the ECID link retrieves related messages with the same ECID in the Related Messages by ECID page. For more information on related messages, see Correlating Messages Across Log Files and Components.
Select an appropriate output option from the Export Messages to File drop-down list if you want to export log messages as a Oracle Diagnostic Log Text file (.txt) XML file (.xml), or Comma-Separated List (.csv) file.
Click Target Log Files to open the Log Files page where you can view a list of log files related to the managed server (server-soa).
Log Files Page
Select a file and click View Log File. The View Log File page is displayed for the selected log file where you can view a list of messages contained in this log.
View Log File Page
To view the details of a message, select the message. The message details, such as message level, component, ECID, Relationship ID, actual message, are displayed below the table of messages.
To view messages that are related by time or ECID, click View Related Messages and select 'by Time' or by 'ECID (Execution Context ID)'.
Alternatively, clicking the ECID link directly from the message details also retrieves related messages with the same ECID in the Related Messages by ECID page.
Oracle Fusion Middleware components provide message correlation information for diagnostic messages. Message correlation information helps those viewing diagnostic messages to determine relationships between messages across components. Each diagnostic message contains an Execution Context ID (ECID) and a Relationship ID.
An ECID is a globally unique identifier associated with the execution of a particular request. An ECID is generated when the request is first processed. A Relationship ID distinguishes the work done in one thread on one process from the work done by any other threads on this and other processes on behalf of the same request.
While viewing log messages in the Oracle Enterprise Manager Fusion Middleware Control Console, you can view correlated messages by selecting a log message first, and then selecting one of the following values from the View Related Messages drop-down list:
Note: The View Related Messages selection is available only when 'Messages' is chosen in the Show field when displaying all matching messages based on search criteria. If 'Group by Message Type' or 'Group by Message ID' is selected in the Show field, then all matching messages are displayed by groups based on message type or message ID. In this situation, the View Related Messages field is not available.
by Time: This displays the Related Messages by Time page where all messages with the same timestamp as the selected message are displayed in this page.
Related Messages by Time Page
by ECID (Execution Context ID): This displays the Related Messages by ECID page where all messages with the same ECID as the selected message are displayed in this page.
Related Messages by ECID Page
By searching for related messages using the message correlation information, multiple messages can be examined and the component that first generates a problem can be identified. Message correlation data can help establish a clear path for a diagnostic message across components, within which errors and related behavior can be understood.
In order to identify the root cause of an issue or error which might occur during invocation of an Oracle E-Business Suite interface, Adapter for Oracle Applications now provides user-friendly, descriptive exceptions and error messages. Especially, these would be available during invocation of any PL/SQL APIs or Concurrent Programs.
Apart from handling errors during adapter preprocessing and the run-time execution by Database Adapter and AQ Adapter, it also provides a way to retrieve the functional errors raised by PL/SQL APIs at run time, without the need for an extra call to retrieve them. These messages would guide you to pinpoint the cause of failures at run time.
Additionally, based on the common logging framework used by other JCA Adapters, all errors and exceptions pertaining to Adapter for Oracle Applications and debug information will be logged. This allows administrators or developers to better understand what happened during the execution and take necessary actions to solve the issue.
During the invocation of an integrated interface supported by Adapter for Oracle Applications, in case of issues or errors occurred (such as the entered order number does not exist while invoking OE_ORDER_PUB.CHANGE_ORDER API), an exception (ORA-20100: Order number does not exist) would be thrown and such exception consists of functional errors. This type of exception is used extensively to report functional problems while executing the API.
For most PL/SQL APIs, functional errors can be thrown as SQLException caught by Adapter run-time engine along with code and message or as part of API output parameters. However, certain PL/SQL APIs do not throw functional errors during execution, but they keep on accumulating them in the memory stack. The responsibility of fetching the errors is deferred to the caller of the APIs.
For example, HRMS APIs put functional errors in FND_MESSAGE stack using FND_MSG_PUB.put package. Upon completion of the API call, the caller must explicitly fetch the errors from this stack using FND_MSG_PUB.GET() methods.
Note: Error messages can only be retrieved from the stack FND_MSG_PUB in this release.
For such APIs that require explicit handling, a new JCA property called APIErrorHandler is introduced to fetch functional errors from the FND_MESSAGE memory stack. This property serves as an error-fetching indicator so that the caller can retrieve the errors without the need for an explicit call to retrieve them. During run-time execution, Adapter for Oracle Applications checks for the presence of the JCA property APIErrorHandler. If it is present, the error handler would be invoked right after the execution of the PL/SQL API.
Please note that the following functional error handling parameter needs to be added to the WSDL file (XX_apps.jca) for fetching the functional errors for such APIs:
<property name="APIErrorHandler" value="FND_MSG_PUB.GET_DETAIL"/>
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 Apps/Apps-equivalent schema'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.
The Oracle Applications Module Browser is a key component of Adapter for Oracle Applications. In addition to the interfaces that are made available through Oracle Integration Repository, Adapter for Oracle Applications enables you to use business events and event groups, custom PL/SQL APIs, and custom XML Gateway maps, all of which you can explore using the Oracle Applications Module Browser.
Use the Module Browser to select the interface needed to define a partner link. It can be used in the following ways to locate desired interfaces:
Locating interfaces by Search
Locating interfaces by Browse
Enter desired interface name or partial values containing wildcard characters in the Object Name field and click Search to locate the desired interface in the Module Browser.
Searching Interfaces Through Oracle Applications Module Browser
Browsing Interfaces Through Tree Structure
The Module Browser combines interface data from Oracle Integration Repository along with additional interfaces supported by Adapter for Oracle Applications.
Browsing Interfaces by Expanding Tree Structure
The supported interfaces are 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 |-Inbound |-Outbound |-Groups |-[business event name] |-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 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 release 11.5.9 or release 12 instance.
Browsing Interfaces by Product Family
The Oracle Integration Repository interface data populates the [product_family] sections, grouped according to the products and business entities to which they belong.
Browsing Interfaces by Product Family
Browsing Business Events and Custom Interfaces Under 'Other Interfaces'
Business events and custom interfaces are displayed under the Other Interfaces note.
Browsing Other Interfaces
Business Events and Business Event Groups
Business events and business event groups appear under the Other Interfaces node from the Oracle Applications Module Browser.
A business event group is a type of event containing a set of individual business events. Clicking the Other Interfaces > Business Events > Outbound > Groups node displays the business event groups.
Custom interfaces are displayed under the Other Interfaces > Custom Objects node from the Oracle Applications Module Browser.
Browsing Custom Interfaces
The supported custom interfaces are listed as follows:
Custom PL/SQL APIs
Custom 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.
Custom XML Gateway Maps
Custom XML Gateway maps are categorized as either Inbound or Outbound. Select either one of the nodes to display custom XML Gateway maps.
Copyright © 2005, 2011, Oracle and/or its affiliates. All rights reserved.