Skip Headers

Oracle Fusion Middleware Adapter for Oracle Applications User's Guide
11g Release 1 (11.1.1.7.0)
Part Number E10537-05		Go to Table of Contents
Contents 		Go to previous page
Previous 		Go to next page
Next

Adapter for Oracle Applications Concepts

Overview

This chapter discusses some essential concepts for Adapter for Oracle Applications. It provides basic understanding about how applications context, security, logging, and flexfields are used or supported as well as how errors and exceptions are handled. Detailed concepts described in this chapter are:

Understanding Applications Context

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.

Applications Context in Multiple Organizations

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

the picture is described in the document text

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

the picture is described in the document text

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:

  1. The customer places a sales order with the French sales office.

  2. The German warehouse delivers the product shipment to the customer.

  3. The German warehouse issues an inter-company invoice to the French sales office.

  4. The French sales office makes the inter-company payment to the German warehouse.

  5. The French sales office sends the customer invoice to the customer.

  6. 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.

Schema Synonyms

the picture is described in the document text

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

the picture is described in the document text

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

the picture is described in the document text

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

the picture is described in the document text

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.

  1. 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.

  2. 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.

  3. 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:

Support for Normalized Message Properties

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:

Design-Time Tasks for Message Properties Support

Adapter for Oracle Applications uses the following procedures to complete the design-time tasks to support message normalization:

  1. Create a new SOA Composite application with BPEL process

  2. Create a partner link

  3. Configure an Invoke Activity

    This activity involves the following tasks:

Support for Multiple Organization Access Control (MOAC)

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

the picture is described in the document text

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.

Support for Multiple Languages

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:

  1. 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.

  2. 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.

  3. 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.

Understanding Adapter for Oracle Applications Security

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

the picture is described in the document text

To better understand how the security works for Oracle Adapter for Oracle Applications, the following topics are included in this section:

Function Security Support for Overloaded Functions

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

the picture is described in the document text

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.

Function Security Support through Profile Option

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.

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.

Creating Security Grants through User Roles

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:

  1. Creating a Permission Set

  2. Creating a User Role

  3. Granting a Permission Set to a User Through a Role

Creating a Permission Set

Use the following steps to create a permission set:

  1. Log in to Oracle E-Business Suite using the System Administrator responsibility.

  2. Select Application: Menu from the Navigator to access the Menus window.

  3. Enter the following menu information:

  4. Add all the functions that you want to group on this Permission Set by entering values for Seq and Function.

    1. Enter the Seq field.

    2. 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

      the picture is described in the document text

      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

      the picture is described in the document text

  5. Save the Permission Set.

Creating a User Role

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:

  1. Log in to Oracle E-Business Suite using the User Management responsibility.

  2. Select Roles & Role Inheritance from the Navigator to access the Roles & Role Inheritance page.

  3. Click Create Role to access the Create Role page.

  4. Enter the following information to create a role:

  5. Save the information and click Create Grant.

  6. Enter the following information in the Create Grant: Define Grant page:

  7. Click Next.

  8. 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.

  9. Click Finish.

Granting a Permission Set to a User Through a Role

Use the following steps to grant a permission set to a user through a role:

  1. Log in to Oracle E-Business Suite using the User Management responsibility.

  2. Select Users from the Navigator to access the User Maintenance page.

  3. Search for the user you want to assign the role and click Go.

  4. Select the Update icon next to the user name that you want to assign the role.

  5. 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.

  6. Select the role (such as 'EBS_ADAPTER_ROLE') and save your update.

Flexfield Support for PL/SQL APIs

Oracle Adapter for Oracle Applications provides flexfield support for PL/SQL APIs. If a PL/SQL interface is configured with flexfields, flexfield information including flexfield data and mapping will not only be displayed at design time, but also be included in the XSD. Additionally, this feature allows Adapter for Oracle Applications runtime to work in the context of flexfields.

Note: Please note that flexfield information was not displayed at design time in earlier releases, but generic API parameter names were displayed instead. The XSD for the payload also showed the generic parameter names instead of the flexfield information.

This feature is available for PL/SQL APIs only and is for Oracle E-Business Suite Release 12 and above.

What is a Flexfield?

Flexfield is one of the essential features in Oracle E-Business Suite. It provides a flexible way to represent objects or to implement context-sensitive fields that appear only when needed. It is a field made up of sub-fields, or segments. Two flexfield types (key and descriptive flexfields) are used to let you customize Oracle E-Business Suite features without additional programming. To provide the unique, customized information that conforms to your business needs, Adapter for Oracle Applications provides flexfield support for PL/SQL APIs that contain flexfields.

How Flexfield Data is Configured at Design Time

At design time during the partner link creation, if a PL/SQL interface is configured with flexfields, appropriate flexfield information is displayed along with the API parameters in the right pane of the Oracle Application Module Browser. You can optionally modify or create a new flexfield mapping for the selected API, or proceed with the partner link creation without configuring the PL/SQL API with flexfields.

To configure flexfield data, Adapter for Oracle Applications allows you to either use an existing flexfield mapping that has been created earlier, or to create a new mapping if desired. In the case of creating a new mapping, a mapping flexfield wizard appears guiding you through each configuration page where you can add key and descriptive flexfields with desired mapping for the selected API.

Key Features

Flexfield feature provided in Oracle Adapter for Oracle Applications includes the following key features:

Understanding Key Elements in Flexfield Configuration

Oracle Adapter for Oracle Applications supports both key flexfields and descriptive flexfields referenced by an API.

Generally, use key flexfields to define your own structure for many of the identifiers required by Oracle E-Business Suite; use descriptive flexfields to gather additional information about your business entities beyond the information required by Oracle E-Business Suite.

For more information about flexfields, see the Oracle E-Business Suite Flexfields Guide.

Flexfield Mapping Concepts

Each flexfield regardless of its type has its owner application. For example, an Accounting Flexfield is owned by Oracle General Ledger application. During the flexfield configuration, you need to first select an application to which a flexfield belongs, and then select a flexfield name (such as Accounting Flexfield) contained in the selected application (such as General Ledger).

The following diagram illustrates the high level flexfield mapping concepts for key flexfields:

the picture is described in the document text

In this diagram, Flexfield 2 (Accounting Flexfield) belongs to General Ledger application, and it contains multiple segments (segment 1 to segment n) which can be grouped by data type.

The main part of flexfield configuration is mapping. Once a flexfield with a desired application is selected, the matching segments (segment 1 to segment n) are derived from Application Object Library (AOL) flexfield table along with the related interface parameters based on the flexfield metadata for your mapping.

API parameters are displayed based on the selected data type (parent type or record type). API parameters and the flexfield table columns can be mapped either manually or automatically by using Auto Map.

Note: Automapping feature maps all the table columns to the parameters which have the column name as part of the parameter name. For examples, parameter P_ATTRIBUTE1 would be mapped to a column name called ATTRIBUTE1, and parameter P_ATTRIBUTE2 would be mapped to a column name called ATTRIBUTE2.

Once mapping is completed, you will need to select a flexfield structure for a key flexfield.

Note: A flexfield structure is a specific configuration of segments. If you add or remove segments, or rearrange the order of segments in a flexfield, you get a different structure. The segments that make up a particular structure are logically or functionally related.

For descriptive flexfields, an additional mapping is required for the context column. All the table columns including the context column should be mapped to the scalar parameters within one record type or parent type. Once mapping is completed, select at least one context value for the selected context column for a descriptive flexfield.

For example, Chile uses 'Region' and 'Comuna' in addition to 'State' and 'County' to represent subdivision or relatively small location geographically. Similarly, Ecuador uses 'Zona' and 'Parroquia' in geography to describe different boundaries. This is a perfect example using a descriptive flexfield to customize the application to meet your business needs. Chile and Ecuador are the context values when defining the descriptive flexfield 'TCA Location Information'. Parameter1 (or Parameter2) is mapped to ATTRIBUTE1 (or ATTRIBUTE2) whose value depends on the selected context value (either 'Chile' or 'Ecuador').

Note: For descriptive flexfields, context value should be available to the runtime through an API parameter.

the picture is described in the document text

Adapter for Oracle Applications uses the flexfield mapping defined from the Application Module Browser to generate the enhanced XSD. This XSD will contain flexfield segment names based on the mapping chosen at design time. Adapter for Oracle Applications will then work in conjunction with Oracle Database Adapter to handle the enhanced schema file for runtime processing.

Guidelines for Defining Flexfield Structure and Context Values

You will not be able to select a context value for a descriptive flexfield or a structure for a key flexfield if one of the following conditions are met:

Flexfield mapping will be used to generate an enhanced schema or XSD file.

Flexfield Configuration Guidelines and Constraints

Accessing Flexfield Configuration User Interface

While creating a partner link at design time, if a selected PL/SQL interface is configured with flexfields, Application Module Browser will display flexfield information in the right pane of the browser window.

For example, a PL/SQL API SYNC_ACCT_ORDER can be retrieved from a search or selected from HZ_AIA_CUSTOM_PKG listed under the Other Interfaces > Custom Objects > PLSQL APIs node. The flexfield data if configured in this API is displayed in the Oracle Application Module Browser.

API with Flexfield Information

the picture is described in the document text

Understanding Flexfield Data in Oracle Application Module Browser

The flexfield information associated with the selected API can be populated and configured in the following regions of the Oracle Application Module Browser:

Note: Alternatively, Adapter for Oracle Applications allows you to bypass the flexfield configuration or modification for your selected API by simply clicking OK in the browser to proceed with the partner link creation.

Reviewing Flexfield Configuration Files

Once a partner link is created, an enhanced XSD file along with flexfield configuration and mapping files are generated. You can review these files for flexfield details. See: Reviewing Flexfield Configurations.

Adding or Configuring a New Mapping

After performing a search or browsing through the list of APIs available in Oracle Application Module Browser, if a selected PL/SQL interface is configured with flexfields, then flexfield information in the API will be displayed in the right pane of the window.

To add or configure a new mapping for the selected API, click Add Mapping in the Configure Flexfields region. A series of flexfield selection pages in the wizard appear guiding you to configure a new mapping for your selected API.

Flexfield Subflow - Welcome

the picture is described in the document text

After clicking Next in the Welcome page, the Select Flexfield Type page appears where you can choose either a key or descriptive flexfield to be configured or added for your flexfield.

Flexfield Subflow - Select Flexfield Type

the picture is described in the document text

Select either the Key Flexfield or Descriptive Flexfield radio button for your flexfield configuration.

Please note that you can configure more than one key or descriptive flexfield for the selected API to meet your business needs.

See:

Configuring Key Flexfields

Sample Business Scenario

Take the INV_EBI_ITEM_PUB.PROCESS_ITEM_LIST API as an example to explain the inbound web service creation with flexfield data.

When a request is placed for processing inventory item list from a third party application, the key flexfield data as part of the input payload is routed and the PL/SQL API INV_EBI_ITEM_PUB.PROCESS_ITEM_LIST is invoked to update the item list in Oracle E-Business Suite. The updated data will be passed to the client as the response message.

The following diagram illustrates the service invocation process flow:

the picture is described in the document text

After deploying the service, you can validate the process by querying inventory item list directly from Oracle E-Business Suite application. The retrieved item data should be the same as input from the payload.

Configuring a Key Flexfield As Part of the Partner Link Creation

To configure key flexfields for the selected API INV_EBI_ITEM_PUB.PROCESS_ITEM_LIST, click Add Mapping in the Configure Flexfields region. A series of flexfield selection pages in the wizard appear guiding you to configure a new mapping for your selected API.

Click Next in the Welcome page. The Select Flexfield Type page is displayed.

Flexfield Subflow - Select Flexfield Type

the picture is described in the document text

Perform the following steps to configure a key flexfield:

  1. Select the Key Flexfield radio button in the Select Flexfield Type page. Click Next. The Select Flexfield Application page appears.

  2. To locate your desired application name, enter keyword search (such as '%App%') and click Query to execute the search. All the entries that match your search criteria will be displayed. For example, select the Inventory radio button as the application name to which the flexfield belongs.

    Flexfield Subflow - Select Flexfield Application

    the picture is described in the document text

    Alternatively, click Query directly to execute the blank search without keyword search. This displays all flexfield application names for your selection.

    Click Next.

  3. In the Select Flexfield page, enter keyword search if desired and click Query to execute the search. All the matched key flexfields are displayed for your selection. Select your desired key flexfield radio button.

    Flexfield Subflow - Select Flexfield

    the picture is described in the document text

    Click Next to continue.

  4. The Select Datatype and Configure Mapping page appears where you can choose desired mapping for your key flexfield. Notice that your selected key flexfield name is automatically populated as the Flexfield name.

    Flexfield Subflow - Select Datatype and Configure Mapping

    the picture is described in the document text

    To configure flexfield mapping, select the <Parent_type> from the Select the Datatype drop-down list if it's a simple API which does not have record types. This retrieves all needed flexfield metadata from Oracle E-Business Suite database and populates parameters at the parent level for your mapping.

    Note: Parent_type is a pseudo type to allow all the scalar parameters at the procedure level to participate in the mapping.

    You can also select record type if it's for a complex API. When a record type occurs multiple times in the API, the list of paths is displayed for reference. If the parameters from a record type are mapped to the flexfield table columns, then the same mapping would be applicable to all the paths it occurs.

    In this mapping page, you have the option to do the mapping manually or use automapping feature.

    Note: If a parameter has already mapped to a table column, you cannot remap the parameter to other column. In this situation, 'Already Mapped' appears instead for the mapped parameter.

    Click Clear Mapping to clear current mapping you have. All previously mapped columns marked with 'Already Mapped' will not be removed from the system.

    Click Next to continue.

  5. The configuration of the flexfield will not be complete without a structure for a key flexfield and at least one context value for a descriptive flexfield.

    In the Configure Flexfields page, enter keyword search if desired in the Structure field or simply click Query to execute a blank search. All the matched structures for the selected key flexfield are displayed.

    Select only one structure (such as SYSTEM_ITEMS).

    Please note that there are certain criteria need to be met in order to have your desired structures displayed in the wizard for selection. See: Guidelines for Defining Flexfield Structure and Context Values.

    Flexfield Subflow - Configure Flexfields

    the picture is described in the document text

    Note: Only one structure for a key flexfield can participate in flexfield mapping. In the case of a descriptive flexfield, multiple context values can participate in the mapping.

    Click Finish.

  6. The Application Module Browser window appears. The newly added key flexfield structure and mapped parameters are displayed in the Parameters with Corresponding Flexfield Mappings region.

    The key flexfield information is also displayed in the Flexfield Definitions section.

    Displaying Selected Key Flexfield Information

    the picture is described in the document text

    Click OK.

  7. The Application Interface page appears with the selected API.

    the picture is described in the document text

    Click Next and then click Finish.

    The wizard generates the WSDL file corresponding to the partner link. An enhanced XSD file, for example ProcessItem_KFF_flex.xsd, is also created. This XSD file contains the schema describing the procedure arguments with the elements representing the parameters that have been replaced with flexfield segment names.

    Click Apply and then OK.

  8. Additionally, configuration file and flexfield mapping file are created. For more information on these files, see Reviewing Flexfield Configurations.

To add descriptive flexfields for the selected API, see Configuring Descriptive Flexfields.

Displaying Mapped Key Flexfields at Design Time

The key flexfield mapping data configured earlier during the partner link creation can be shown at design time.

A Composite Example with Key Flexfields

Here is an example describing the key flexfield mapping in the BPEL process of a SOA composite:

Constructing BPEL Process in SOA Composite

the picture is described in the document text

For more information on how to create design time tasks, see Design-Time Tasks for PL/SQL APIs.

Flexfield Validation in Oracle E-Business Suite

When defining key flexfield segments for a key flexfield 'System Items' in Oracle Inventory application (Application Developer responsibility), only SEGMENT1 is specified as 'Item' in the Segments Summary - System Items window.

Key Flexfield Segments Summary for System Items

the picture is described in the document text

The following table explains the relationship between the key flexfield mapping data and the actual segments defined in Oracle E-Business Suite:

Segment Summary for Key Flexfield 'System Items'
Key Flexfield Segments Mapped During Flexfield Configuration Key Flexfield Segments Defined in Oracle E-Business Suite
SEGMENT1 Item
SEGMENT2 Not defined
SEGMENTn Not defined

Mapped segment column names for the key flexfield 'System Items' are displayed in the Oracle Application Module Browser once the mapping is complete. In this case, only 'Item', the corresponding column name in SEGMENT1, is shown here.

Displaying Mapped Segment Column Name 'Item'

the picture is described in the document text

For information on how to define key flexfields and key flexfield segments, refer to the Planning and Defining Key Flexfields chapter, Oracle E-Business Suite Flexfields Guide.

Flexfield Validation in the Schema File

Select the enhanced XSD file (for example ProcessItem_KFF_flex.xsd) in Oracle JDeveloper and notice that the mapped key flexfield column (Item) is displayed with type 'flex' under the flexfield name System_Items.

the picture is described in the document text

Assigning Parameters with Key Flexfields in the Assign Activity

In the Assign activity of the BPEL process diagram within the SOA composite application, the mapped key flexfield can be displayed and used to pass an input variable from payload to the second Invoke activity for service invocation.

Displaying Mapped Key Flexfields in the Assign Activity

the picture is described in the document text

Use Assign activity to provide input payload information to the Item object of the target parameter.

Note: The target parameter ns2:SEGMENT1 mapped to the column name SEGMENT1 during the key flexfield configuration earlier is now translated into ns3:Item (under ns2:System_Items) and displayed in the Assign activity.

Drag the source node (ns3: Item) to connect to the target node (ns3: Item) that you just specified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

Click Apply and OK to complete the Assign activity.

Note: Alternatively, since 'ns2:InputParameters' variables contained in the Source and Target are identical, you can simply drag the source node (ns2:InputParameters) to connect to the target node (ns2:InputParameters) and complete the Assign activity.

Assigning Input Variables to the Invoke Activity

the picture is described in the document text

Please note that the datatype INV_EBI_ITEM_MAIN_OBJ shown here is exact the same datatype (INV_EBI_ITEM_PUB:INV_EBI_ITEM_MAIN_OBJ) specified earlier from the drop-down list in the Select Datatype and Configure Mapping page. P_ITEM is listed as the paths for the selected datatype.

the picture is described in the document text

Displaying Mapped Key Flexfields at Runtime

After deploying the BPEL process contained in a SOA Composite application (FlexfieldKFF) to the Oracle WebLogic managed server (for example 'soa-server1'), the key flexfields we configured earlier are displayed in the soa-server1 server (http://<servername>:<portnumber>/soa-infra) allowing you to specify payload data and test the service invocation.

Note: Please note that you can also test and manage the process from the Oracle Enterprise Manager Fusion Middleware Control Console. In this example, the mapped key flexfield used as part of the input payload happens to be located or nested within multiple sub-levels down from the top. This means that we need to drill down to the mapped key flexfield Item by expanding the parameter nodes multiple times from the top level (Payload > P_ITEM > P_ITEM_ITEM > MAIN_OBJ_TYPE > System_Items > Item). However, Oracle Enterprise Manager Fusion Middleware Control Console has certain limitations on displaying payload parameters if they are nested too deeply.

the picture is described in the document text

Therefore, in this case we access the mapped key flexfield directly from the soa-infra in the soa-server1 server.

For information on how to test the service invocation from the Oracle Enterprise Manager Fusion Middleware Control Console, see Test the deployed SOA Composite application with BPEL process.

the picture is described in the document text

Click the FlexfieldKFF project (the 'Test_bpelprocess2_client_ep' link) to display the payload information in HTML:

the picture is described in the document text

In the Payload section, expand the P_ITEM > P_ITEM_ITEM > MAIN_OBJ_TYPE > System_Items. Mapped key flexfield 'Item' is displayed as part of the payload.

the picture is described in the document text

Enter appropriate data as payload and then click Invoke to invoke the service.

Configuring Descriptive Flexfields

Sample Business Scenario

Take the HZ_AIA_CUSTOM_PKG.SYNC_ACCT_ORDER API as an example to explain the inbound web service creation with flexfield data.

When a request is placed for synchronizing customer information from a third party application, the descriptive flexfield data as part of the payload is routed and the PL/SQL API HZ_AIA_CUSTOM_PKG.SYNC_ACCT_ORDER is invoked to update the organization and customer accounts in Oracle E-Business Suite. The synchronized customer data will be passed to the client as the response message.

The following diagram illustrates the service invocation process flow:

Invoking an Inbound Service with Flexfield Data

the picture is described in the document text

After deploying the service, you can validate the process by querying customer data directly from Oracle Customer Online application. The retrieved customer data should be the same as input from the payload.

Configuring a Descriptive Flexfield As Part of the Partner Link Creation

To configure descriptive flexfields for the selected API HZ_AIA_CUSTOM_PKG.SYNC_ACCT_ORDER, click Add Mapping in the Configure Flexfields region. A series of flexfield selection pages in the wizard appear guiding you to configure a new mapping for your selected API.

Click Next in the Welcome page. The Select Flexfield Type page is displayed.

Flexfield Subflow - Select Flexfield Type

the picture is described in the document text

Perform the following steps to configure a descriptive flexfield:

  1. Select the Descriptive Flexfield radio button in the Select Flexfield Type page, and then use the similar approach as described earlier for key flexfields in the flexfield mapping wizard.

  2. Click Next in the Select Flexfield Type page. The Select Flexfield Application page is displayed.

  3. To locate your desired application, enter keyword search (such as '%App%') or simply click Query to execute the search. All the matched applications for descriptive flexfield are displayed. For example, select the Receivables radio button as the application name to which the descriptive flexfield belongs.

    Flexfield Subflow - Select Flexfield Application

    the picture is described in the document text

    Click Next.

  4. In the Select Flexfield page, enter keyword search (such as 'HZ%') if desired and click Query to execute the search. All the matched descriptive flexfields are displayed for your selection.

    Select your desired descriptive flexfield (such as HZ_LOCATIONS) and click Next.

    Flexfield Subflow - Select Flexfield

    the picture is described in the document text

  5. The Select Datatype and Configure Mapping page appears where you can choose desired mapping for your descriptive flexfield.

    Notice that your selected descriptive flexfield name HZ_LOCATIONS is automatically populated as the Flexfield name.

    Flexfield Subflow - Select Path and Configure Mapping

    the picture is described in the document text

    To configure flexfield mapping, select a desired data type from the Datatype drop-down list. This retrieves all needed flexfield metadata from Oracle E-Business Suite database and populates parameters at the parent level for your mapping.

    Selecting Context Column for Descriptive Flexfield Mapping

    For descriptive flexfields, you need to perform an additional mapping for the context column. This is because flexfield mapping cannot span across record types. All the table columns including the context column should be mapped to the scalar parameters within one record type or parent type.

    In the Map Context Column ATTRIBUTE_CATEGORY field, select a desired category name that you want to view the mapping information from the drop-down list. For example, select ATTRIBUTE_CATEGORY from the drop-down list.

    Note: If a parameter has already mapped to a table column, you cannot remap the parameter to other column. In this situation, 'Already Mapped' appears instead for the mapped parameter.

    Similar to key flexfields, the mapping can be performed manually or assisted with the automapping feature by clicking Auto Map.

    Automapping feature maps all the table columns to the parameters, which have the column name as part of the parameter name. For example, table column names from ATTRIBUTE1 to ATTRIBUTE20 are automatically displayed and mapped to parameters from ATTRIBUTE1 to ATTRIBUTE20 respectively through automapping.

    If there are multiple sets of parameters and the table column names, then the prefix needs to be specified for automapping. This would map the potential parameters which need to be considered for the mapping. Enter parameter prefix (such as 'INDUSTRY_') to first locate your desired parameters that you want the automapping to be performed. Next, click Auto Map. All the parameters with prefix 'INDUSTRY_' are automatically displayed along with the automapped table column names. Parameter 'INDUSTRY_ATTRIBUTE1' is mapped to column ATTRIBUTE1, and parameter 'INDUSTRY_ATTRIBUTEn' is mapped to column ATTRIBUTEn.

    Instead of using automapping feature, you can manually select a desired table column name from the drop-down list for a corresponding parameter for your flexfield mapping.

    Click Clear Mapping to clear current mapping you have in the table column only. All previously mapped columns marked with 'Already Mapped' will not be removed from the system.

    Click Next to proceed to the next page.

  6. In the Configure Flexfields page, select at least one context value for the selected descriptive flexfield. For example, select desired context values (such as Chile and Ecuador).

    You can either enter keyword search in the Context field or simply click Query to execute the search before selection.

    For descriptive flexfields, context value should be available to the runtime through an API parameter.

    Please note that there are certain criteria need to be met in order to have your desired context values displayed in the wizard for selection. See: Guidelines for Defining Flexfield Structure and Context Values.

    Flexfield Subflow - Configure Flexfields

    the picture is described in the document text

    Click Finish to complete the flexfield configuration.

  7. The Application Module Browser window appears. The newly added descriptive flexfield information including the segment values for the selected context value is displayed in the right pane of the window.

    Displaying Selected Descriptive Flexfield Information

    the picture is described in the document text

    Click OK.

  8. The Application Interface page appears with the selected API.

    the picture is described in the document text

    Click Next and then click Finish.

    The wizard generates the WSDL file corresponding to the partner link. An enhanced XSD file, for example SynAccOrder_flex.xsd, is also created. This XSD file contains the schema describing the procedure arguments with the elements representing the parameters that have been replaced with flexfield segment names.

    Click Apply and then OK.

  9. Additionally, configuration file and flexfield mapping file are created. For more information on these files, see Reviewing Flexfield Configurations.

Once a new flexfield mapping has been configured or added, if modification is needed, you can make updates by first selecting desired flexfield type that you want to modify and then make needed changes. For more information on how to modify the selected mapping details, see Modifying Your Flexfield Mapping.

Displaying Mapped Descriptive Flexfields at Design Time

Similar to key flexfields, the descriptive flexfield mapping data configured earlier during the partner link creation can be shown at design time along with the following activities orchestrated in the BPEL process within in a SOA composite:

A Composite Example with Descriptive Flexfields

Here is an example describing the descriptive flexfield mapping in the BPEL process of a SOA composite:

Constructing BPEL Process in SOA Composite

the picture is described in the document text

For more information on how to create design time tasks, see Design-Time Tasks for PL/SQL APIs.

Flexfield Validation in Oracle E-Business Suite

When defining descriptive flexfield attributes for 'TCA Location Information' (HZ_LOCATIONS) in Oracle Receivables application (Application Developer responsibility), the following attributes are specified based on context values:

Descriptive Flexfield Segment Summary for TCA Location Information
Context Value ATTRIBUTE1 ATTRIBUTE2
Chile Region Comuna
Ecuador Zona Parroquia

Descriptive Flexfield Segments Summary for System Items

the picture is described in the document text

Flexfield Validation in the Schema File

Select the enhanced XSD file (such as SynAccOrder_flex.xsd) in Oracle JDeveloper and notice that the mapped descriptive flexfields are displayed with type 'flex' under the HZ_LOCATIONS flexfield as part of the schema.

Additionally, the mapped table column names (Region, Comuna, Zona, and Parroquia) are grouped by context value (Chile and Ecuador) listed in a tree structure. Context value nodes are connected with the <choice> icon in between indicating that only either one of the context values and its associated table columns can be selected.

the picture is described in the document text

Assigning Parameters with Descriptive Flexfields in the Assign Activity

In the Assign activity of the BPEL process diagram within the SOA composite application, the mapped descriptive flexfields can be displayed and used to pass an input variable received from payload to the Invoke activity for SynAccOrder service invocation.

Mapped Descriptive Flexfields Displayed in the Assign Activity

the picture is described in the document text

Use Assign activity to provide input payload information to the TCA Location object of the target parameter.

The target parameters ns2:ATTRIBUTE1 was mapped to the following descriptive flexfield columns during the flexfield configuration earlier:

The target parameters ns2:ATTRIBUTE2 was mapped to the following descriptive flexfield columns during the flexfield configuration earlier:

These descriptive flexfield columns grouped by context value are displayed in the Assign activity.

To assign the parameters with descriptive flexfields in the Assign activity, drag the source node (ns3:Region) to connect to the first target node (ns3:Region) that you just specified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

Repeat the procedure to assign the second parameter by dragging the same source node (ns3:Comuna) to connect to the second target node (ns3:Comuna). The second copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

Click Apply and OK to complete the Assign activity.

Note: Alternatively, since 'ns2:InputParameters' variables contained in the Source and Target are identical, you can simply drag the source node (ns2:InputParameters) to connect to the target node (ns2:InputParameters) and complete the Assign activity.

the picture is described in the document text

Displaying Mapped Descriptive Flexfields at Runtime

After deploying the BPEL process contained in a SOA Composite application to the Oracle WebLogic managed server (such as 'soa-server1'), the descriptive flexfields we configured earlier are displayed in the soa-server1 server (http://<servername>:<portnumber>/soa-infra) allowing you to specify payload data and test the service invocation. Please note that you also test and manage the process from the Oracle Enterprise Manager Fusion Middleware Control Console.

Note: Please note that you can also test and manage the process from the Oracle Enterprise Manager Fusion Middleware Control Console. In this example, the mapped descriptive flexfields used as part of the input payload happen to be located or nested within multiple sub-levels down from the top. This means that we need to drill down to the mapped descriptive flexfields (Region and Comuna) by expanding the parameter nodes multiple times from the top level (Payload > P_ORG_CUST_OBJ > ORGANIZATION_OBJ > PARTY_SITE_OBJS > PARTY_SITE_OBJS_ITEM > LOCATION_OBJ > HZ_LOCATIONS > ATTRIBUTE_CATEGORY > HZ_LOCATIONS_1 to view descriptive flexfields). However, Oracle Enterprise Manager Fusion Middleware Control Console has certain limitations on displaying payload parameters if they are nested too deeply.

the picture is described in the document text

Therefore, in this case we access the mapped descriptive flexfields directly from the soa-infra in the soa-server1 server.

For information on how to test the service invocation from the Oracle Enterprise Manager Fusion Middleware Control Console, see Test the deployed SOA Composite application with BPEL process.

the picture is described in the document text

Click the DescFlex project (the 'Test_bpelprocess1_client_ep' link) to display the BPEL process information in HTML:

the picture is described in the document text

In the Payload section, expand the P_ORG_CUST_OBJ node and navigate to ORGANIZATION_OBJ > PARTY_SITE_OBJS > PARTY_SITE_OBJS_ITEM > LOCATION_OBJ > HZ_LOCATIONS > ATTRIBUTE_CATEGORY > HZ_LOCATIONS_1.

Two sets of descriptive flexfields configured earlier at the design time are now displayed at the runtime.

  1. HZ_LOCATIONS_1_0 (This is the default selection we configured in the Assign activity at the design time.)

  2. HZ_LOCATIONS_1_1

the picture is described in the document text

Enter appropriate data as payload and then click Invoke to invoke the service.

Importing an Existing Flexfield Mapping

Instead of configuring a new mapping, you can simply import an existing mapping for your selected API. By using a previously configured mapping, you can quickly establish the flexfield mapping for your API or use it as a base with proper modification if needed.

To import an existing mapping, click Import from File in the Configure Flexfields region. The Open window appears where you can select a desired flexfield mapping.

Selecting a desired flexfield mapping

the picture is described in the document text

After selecting the desired mapping to be imported, click Open. The selected mapping file is automatically displayed in the Import Flexfield Data into the project field.

For example, select 'OE_ORDER_PUB_PROCESS_LINE_mapping.xml' file and the imported mapping for the selected API is automatically displayed in the Parameters with Corresponding Flexfield Mappings region along with the selected mapping file name.

Displaying Imported Flexfield Mapping File

the picture is described in the document text

When a desired mapping is imported for the selected API, you will need to select the structure for a key flexfield and context values for a descriptive flexfields.

First, select the key or descriptive flexfield in the Flexfield Definitions section that requires modification, and then click Edit. The Flexfield Subflow - Welcome page is displayed. Click Next to select the desired flexfield context values if it's for a descriptive flexfield.

Selecting the Context Values for Imported Mapping

the picture is described in the document text

Click Finish to complete the descriptive flexfield mapping information. The updated descriptive flexfield context value (SSE_Country) is now added both in the Parameters with Corresponding Flexfield Mappings region and Flexfield Definitions section.

the picture is described in the document text

Use the same approach to update the key flexfield that requires structure information before clicking OK.

For more information on how to modify the selected mapping details, see Modifying Your Flexfield Mapping.

Modifying Flexfield Definitions

Oracle Adapter for Oracle Applications allows you to modify flexfield definition for both key and descriptive flexfields as often as needed. However, modification is only limited to context values for a descriptive flexfield or flexfield structure for a key flexfield. If further update is needed in addition to modifying structure or context values, you should delete the flexfield mapping first and configure a new one.

Modifying Flexfield Data

To modify flexfield data, select either the Key Flexfield or Descriptive Flexfield in the Flexfield Definitions section that you want to modify and then click Edit. Appropriate flexfield pages corresponding to your selected flexfield type appear where you can modify the flexfield details.

Modifying Flexfield Mapping Data

the picture is described in the document text

For example, modify the structure of the descriptive flexfield (HZ_LOCATIONS). The Configure Flexfields window appears after you click Next in the Flexfield Subflow Welcome wizard.

Flexfield Subflow - Configure Flexfields

the picture is described in the document text

Click Query and select the 'Ecuador' check box only as the context value. Click Finish to complete the modification. The updated flexfield information should be reflected in the Flexfield Definitions section.

Validating Modified Flexfield Mapping Data

the picture is described in the document text

You can also validate the changes in the flexfield configuration xml file (<projectname>_flex-config.xml). See: Reviewing Flexfield Configurations.

For more information on how to configure or add each Flexfield Subflow window, see Adding or Configuring a New Flexfield Mapping.

Deleting Flexfield Data

To delete flexfield data, select either the Key Flexfield or Descriptive Flexfield that you want to delete and then click Delete. This removes the selected flexfield data and the associated structure or values from the database.

Alternatively, use [Control] and [Shift] keys to select multiple flexfields before the deletion.

Reviewing Flexfield Configurations

After creating a partner link with flexfield information, from Oracle JDeveloper, expand the SOA Content folder and select the enhanced XSD file, for example ProcessItem_KFF_flex.xsd, to validate the flexfield information you configured or updated earlier.

The enhanced schema information is displayed with flexfield segment names based on the mapping chosen at the design time.

Viewing an Enhanced XSD File

the picture is described in the document text

Additionally, two xml files are created along with the XSD file:

Logging

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.

Enabling Logging for Adapters

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.

Message Type Level Description
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:

  1. Navigate to http://<servername>:<portnumber>/em.

    The Oracle Enterprise Manager Fusion Middleware Control Console home page is displayed.

  2. Enter username and password to log on to the console.

  3. Right-click soa-infra from the SOA Folder in the Navigator tree.

  4. 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.

    the picture is described in the document text

    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

    the picture is described in the document text

  5. Select the Log Levels tab.

  6. Select one of the following values from the View drop-down list:

    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.

  7. 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)'.

  8. Click Apply.

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.

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.

Automatic FND Logging for PL/SQL APIs and Concurrent Programs Using oracle.soa.adapter Runtime Logger

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
INCIDENT_ERROR LEVEL_UNEXPECTED
ERROR LEVEL_ERROR
WARNING LEVEL_EXCEPTION
NOTIFICATION 1, 16, 32 LEVEL_EVENT
TRACE 1 LEVEL_PROCEDURE
TRACE 16, 32 LEVEL_STATEMENT

Searching and Viewing Adapter Logs

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.

Steps to Search and View Adapter Logs Using Oracle Enterprise Manager Fusion Middleware Control Console

Use the following steps to search Adapter Logs through the Oracle Enterprise Manager Fusion Middleware Control Console:

  1. Navigate to http://<servername>:<portnumber>/em.

    The Oracle Enterprise Manager Fusion Middleware Control Console home page is displayed.

  2. Enter username and password to log on to the console.

  3. There are two ways to access the Log Messages page from the Navigator tree in the left pane:

    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

    the picture is described in the document text

  4. Enter the following search criteria for searching the log messages for Oracle Adapter for Oracle Applications:

  5. 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.

    the picture is described in the document text

  6. 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.

  7. 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.

  8. 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

    the picture is described in the document text

    1. 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

      the picture is described in the document text

    2. 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.

    3. 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.

Correlating Messages Across Log Files and Components

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 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.

Enhanced Error and Exception Handling

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.

Handling Functional Errors

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"/>

Secured Connection Between Oracle E-Business Suite and Oracle Fusion Middleware SOA Suite Using J2EE Data Source Implementation

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:

  1. 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.

  2. 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.

  3. Create a connection pool where you need to enter the application login user name, password, and dbc file location as the connection factory properties.

  4. 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.

Understanding the Oracle Applications Module Browser

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:

Searching Interfaces

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

the picture is described in the document text

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 picture is described in the document text

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
       |-Concurrent Programs
			   |-[concurrent program name]

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

the picture is described in the document text

Browsing Business Events and Custom Interfaces Under 'Other Interfaces'

Business events and custom interfaces are displayed under the Other Interfaces note.

Browsing Other Interfaces

the picture is described in the document text

Contents   |   Previous   |   Top of Page   |   Next

Oracle Logo
Copyright © 2005, 2013, Oracle and/or its affiliates. All rights reserved.