Skip Headers

Oracle E-Business Suite Integrated SOA Gateway Implementation Guide
Release 12.2
Part Number E20925-15
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Administering Custom Integration Interfaces and Services

Overview

Oracle E-Business Suite Integrated SOA Gateway supports custom integration interfaces and allows them to be published along with Oracle seeded ones through the Oracle Integration Repository where they can be exposed to all users.

Custom interface definitions can be created for various interface types, including custom interface definitions for XML Gateway Map, Business Event, PL/SQL, Concurrent Program, Business Service Object, Java APIs, Java Bean Services, Application Module Services, and Composite Service for BPEL type. Depending on your business needs, integration developers can create and annotate custom interface definitions based on Integration Repository Annotation Standards. The annotated definitions can then be validated and uploaded to Oracle Integration Repository.

Note: Please note that custom interface types of EDI, Open Interface Tables, Open Interface Views, and Java APIs for Forms interfaces are not supported in this release.

Oracle Integration Repository currently does not support the creation of custom Product Family and custom Business Entity.

After the upload, these custom integration interfaces are displayed in the Integration Repository based on the interface types they belong to. To easily distinguish them from Oracle integration interfaces, Interface Source "Custom" is used to categorize those custom integration interfaces in contrast to Interface Source "Oracle" for Oracle seeded interfaces in Oracle E-Business Suite. Custom integration interfaces can now seamlessly leverage the Oracle E-Business Suite Integrated SOA Gateway capabilities. Custom integration interfaces of service enabled interface types can be exposed as Web services. The administrator performs the same administrative tasks for custom integration interfaces as he or she does for native integration interfaces. These tasks include creating security grants, as well as generating and managing services throughout the deployment life cycle.

Usage Guidelines for Custom Web Services

While creating or developing custom Web services for your business needs, consider the following conditions:

Requirement Use
To enable existing or new Oracle E-Business Suite customizations built on native Oracle E-Business Suite technologies (such as PL/SQL, Business Service Objects, and other supported custom integration interface types described earlier), as Web services Oracle E-Business Suite Integrated SOA Gateway
To integrate Oracle E-Business Suite with SOA application that requires rich service infrastructure and integration capabilities such as Business Rules, Business Activity Monitoring (BAM), Web service development and orchestration Oracle SOA Suite in conjunction with Oracle E-Business Suite Integrated SOA Gateway
To develop custom Web services that are not associated with Oracle E-Business Suite Oracle WebLogic Web service stack

Enabling Custom Integration Interface Process Flow

The following diagram illustrates the entire process flow of enabling custom integration interfaces:

the picture is described in the document text

  1. Users with the Integration Developer role annotate custom integration interface definition based on the Integration Repository annotation standards for the supported interface types.

    See: Integration Repository Annotation Standards, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

    Note: For custom PL/SQL APIs (simple data types only) that are created with custom schema, you can publish such custom APIs in Oracle Integration Repository. Additionally, perform the following tasks for such APIs in custom schema:

    1. Grant access to APPS Schema.

      1. Connect to custom schema as sysdba:

        sqlplus '/ as sysdba'

      2. Use the following command to grant access:

        GRANT EXECUTE on <custom_schema>.<custom_package> TO APPS;

    2. Create synonym for the custom stored procedure.

      1. Connect to APPS schema using the following command:

        sqlplus <APPS Username>
        Enter password: <Password>
      2. Use the following command to create a synonym:

        CREATE SYNONYM <custom_package> FOR <custom_schema>.<custom_package>;

  2. Users who have the Integration Administrator role validate the annotated custom interface definitions against the annotation standards. This validation is performed by executing the Integration Repository Parser (IREP Parser), a design time tool, to read the annotated files and then generate an Integration Repository loader file (iLDT ) if no error occurred. For more information, see:

  3. Users who have the Integration Administrator role upload the generated iLDT file to Oracle Integration Repository.

    See: Uploading ILDT Files to Integration Repository.

  4. All users can view the uploaded custom interfaces from the Integration Repository user interface.

  5. (Optional) Users who have the Integration Administrator role then create necessary security grants for the custom integration interfaces if needed.

    This is achieved by first locating the custom interface from the Integration Repository, and then selecting methods contained in the selected custom interface before clicking Create Grant. The Create Grants page is displayed where the administrators can grant the selected method access permissions to a user, user group, or all users.

  6. (Optional) Users who have the Integration Administrator role can generate SOAP Web services if the custom interfaces can be service enabled.

    This is achieved by first locating the custom interface, and then specifying the interaction pattern either at the interface level or the method level before clicking Generate in the selected custom interface details page. See: Generating Custom SOAP Web Services.

  7. (Optional) Users who have the Integration Administrator role deploy the services from Oracle Integration Repository to the application server.

    To deploy generated SOAP Web services, the administrators must first select one authentication type (Username Token or SAML Token) for each selected Web service and then click Deploy in the selected interface details page. This deploys the generated service with 'Active' state to Oracle SOA Suite where Oracle E-Business Suite services can be exposed as standard Web services for service execution at run time. See: Deploying and Undeploying SOAP Custom Web Services.

    If the custom interfaces can be exposed as REST services, the administrators must enter a unique service alias for each selected custom interface, and specify the desired service operations before deploying the service. Additionally, the administrators need to specify HTTP methods for the service operations contained in the selected interface if it is an interface type of Java Bean Services or Application Module Services.

    Note: Although open interface tables and views can be exposed as REST services, custom open interface tables and custom open interface views are not supported in this release.

    REST services are deployed to an Oracle E-Business Suite environment. For more information on how to deploy custom REST services, see Deploying Custom REST Web Services.

To better understand how to use Integration Repository Parser to validate and upload annotated custom interface definitions to Integration Repository, as well as perform administrative tasks on these uploaded custom integration interfaces, the following topics are discussed in this chapter:

For information on how to create and annotate custom integration interfaces, see Creating and Annotating Custom Integration Interfaces, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Setting Up and Using the Integration Repository Parser

Setup Tasks

Integration Repository Parser is a standalone design-time tool used by the integration administrator to validate annotated custom interface definitions against the annotation standards and generate an Integration Repository loader file (iLDT). The generated iLDT files are uploaded to the Integration Repository using the FNDLOAD command so that the custom interfaces can be searched, generated, and deployed from the Integration Repository user interface.

Note: Integration Repository Parser does not support the integration interfaces registered under custom applications.

Before executing the Integration Repository Parser, you need to install Perl modules with the following steps:

Note: It is required to obtain a native C compiler for the platform and operating system version that you are running on to build the Perl modules. The following are the minimum versions of compilers certified for Oracle E-Business Suite platforms:

Microsoft Windows platform is currently not supported in this release.

Installing Perl Modules on all UNIX platforms

Perform the following steps to install Perl modules on all UNIX platforms mentioned above:

  1. Establish the Oracle E-Business Suite application environment.

    From the Oracle E-Business Suite APPS_BASE, establish the run file system APPL_TOP environment by running the EBSapps.env script.

  2. In both the run and patch file systems, locate the Perl configuration files that need to be modified and back up these files.

    For example, on Oracle Solaris, the Config.pm is located in the following directory:

    $FMW_HOME/webtier/perl/lib/5.10.0/sun4-solaris-thread-multi-64

  3. In both the run and patch file systems, modify the Perl configuration file Config.pm to point to the Perl directory in $FMW_HOME/webtier.

    For example, on Oracle Solaris, these are the statements that need to be modified with the absolute path of $FMW_HOME/webtier/perl:

    Note: <FMW_HOME> is the value of $FMW_HOME.

  4. If your system is on Oracle Solaris, modify the Config.pm and Config_heavy.pl files to point to the C compiler installed as a requirement of the Integration Repository Parser. For example:

    Config.pm

    cc =>'/opt/SunProd/studio12u3/solarisstudio12.3/bin/cc',

    libpth =>'/opt/SunProd/studio12u3/solarisstudio12.3/lib /opt/SUNWspro/WS6U1/lib/v9 /usr/lib/sparcv9 /usr/ccs/lib/sparcv9 /usr/local/lib/usr/lib /usr/ccs/lib,

    Config_heavy.pl

    cc='/opt/SunProd/studio12u3/solarisstudio12.3/bin/cc'

    ld='/opt/SunProd/studio12u3/solarisstudio12.3/bin/cc'

  5. Create a directory 'perl' in $APPL_TOP_NE where the new Perl modules will be installed. For example,

    mkdir $APPL_TOP_NE/perl

    chmod 755 $APPL_TOP_NE/perl

  6. In the run file system, set the following environment variables in APPL_TOP environment:

    1. Prepend PATH with the path to the C compiler installed as a requirement of the Integration Repository Parser.

    2. Prepend PERL5LIB with $FND_TOP/perl and $APPL_TOP_NE/perl in that order.

      For example, export PERL5LIB=$FND_TOP/perl:$APPL_TOP_NE/perl:$PERL5LIB.

    3. Add $FMW_HOME/webtier/lib to LIBPATH if it is not present.

      For example, export LIBPATH=$LIBPATH:$FMW_HOME/webtier/lib.

    4. Set $FMW_HOME/webtier as ORACLE_HOME.

      For example, export ORACLE_HOME=$FMW_HOME/webtier.

    5. Prepend LD_LIBRARY_PATH with $ORACLE_HOME/lib32 and $ORACLE_HOME/lib.

      For example, export LD_LIBRARY_PATH=$ORACLE_HOME/lib32:$ORACLE_HOME/lib:$LD_LIBRARY_PATH.

    6. Set JAVA_HOME to the JDK top directory.

      Obtain the path returned by 'which java' and set JAVA_HOME to the current JDK top directory.

      For example, on Oracle Solaris:

      which java 
      		 /prod/EBS122/fs1/FMW_Home/jdk/jre/bin/java
      export JAVA_HOME=/prod/EBS122/fs1/FMW_Home/jdk 
  7. Download and unzip patch 13602850 (p13602850_R12_GENERIC.zip) into a temporary area.

    Patch 13602850 contains the following Perl modules:

    Install these modules in the order shown above using the following commands:

    Note: If Perl command is not found, invoke Perl in $FMW_HOME/webtier/perl/bin/perl.

    For Oracle Solaris, AIX, and HP-UX Itanium platforms Only

    After installing the Compress-Raw-Zlib-2.009 Perl module but before installing Compress-Zlib-2.009, prepend PERL5LIB with $APPL_TOP_NE/perl/lib/5.10.0/<platform thread-multi directory>.

    For example, on Oracle Solaris:

    export PERL5LIB=$APPL_TOP_NE/perl/lib/5.10.0/sun4-solaris-thread-multi-64:$PERL5LIB.

    1. cd $APPL_TOP_NE/perl

    2. Copy the module to be installed into $APPL_TOP_NE/perl.

      For example: cp -r /temp/Compress-Raw-Zlib-2.009 .

    3. cd <Perl module name>

      For example: cd Compress-Raw-Zlib-2.009

    4. perl Makefile.PL

      Note: On HP-UX Itanium, the option CC=cc may be needed when installing Compress-Raw-Zlib-2.009. For example, perl Makefile.PL CC=cc.

      If errors occur, verify your setup and remove the Perl module being installed from $APPL_TOP_NE/perl before copying it into $APPL_TOP_NE/perl to try again.

    5. make

      Note: If the 'cc' compiler is not found, verify the LD parameter in the Makefile contains the correct path to the C compiler executable.

      If the following warning appears on Oracle Solaris, replace -xarch=v9 with -m64 throughout the Makefile, and run make again.

      cc: Warning: -xarch=v9 is deprecated, use -m64 to create 64-bit programs

    6. make install

Using the Integration Repository Parser

Once the Integration Repository Parser has been installed and set up properly, you can execute the parser to generate iLDT files and then upload them to the Integration Repository if no error occurs.

Note: For an object (or class) which is present in the Integration Repository, the Integration Repository Loader program reloads the new definition of that object ONLY if the new version is greater than the current version present in the Integration Repository. If the new file version is the same or lower than the current one in the repository, then the new file will not be uploaded.

Therefore, before executing the parser, you need to increment the Header version of the target source file so that the modifications to the object defined in the source file can take effect in the Integration Repository.

The following sections explain the use of Integration Repository Parser and FNDLOAD utilities in greater detail.

Generating ILDT Files

Prerequisites - Setting Up Environment Variables

Before executing the Integration Repository Parser to generate iLDT files, set the following environment variables which may affect parser operation:

  1. From the Oracle E-Business Suite APPS_BASE, establish the run file system APPL_TOP environment by running the EBSapps.env script.

  2. The following environment variables affect parser operation:

Executing the Integration Repository Parser

To generate an iLDT (*.ildt) file, execute the Integration Repository Parser using the following syntax:

$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -g -v -username=<a fnd username> <product>:<relative path from product top>:<fileName>:<version>=<Complete File Path, if not in currect directory>

Examples of generating iLDT files for custom PL/SQL APIs and custom composites of BPEL type:

Note: If an error message "Java runtime not found" appears while executing the Integration Repository Parser, then set the JRE location to variable OA_JRE_TOP. JRE location could be located at $JAVA_HOME/jre, If JAVA_HOME is not set, source $FMW_HOME/wlserver_10.3/server/bin/setWLSEnv.sh file.

While executing the parser, you need to pay attention to any error messages on the console. These errors would be due to incorrect annotation or some syntax errors in the annotated file. Ensure that the annotations are correct and the file has proper syntax.

If no error occurs in the annotated interface file, an iLDT (*.ildt) file would be generated. This generated iLDT file needs to be uploaded to the Integration Repository.

See: Uploading ILDT Files to Integration Repository.

Integration Repository Parser (irep_parser.pl) Usage Details

The usage for the Integration Repository Parser can be seen from the command prompt using the -manual option:

$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -manual

Name irep_parser.pl Interface Repository Annotation Processor

Synopsis irep_parser.pl [-verbose] [-logfile=file ? -append-logfile=file] [-generate] [-force] [-outdir=directory] [-java-source=version] [-cache-java=oper] [-cache-file=file] [-imports=file] [-username=username] <filespec>...

Description The irep_parser reads interface annotation documentation in program source files and validates it according to its file type.

If the -generate flag is supplied (and other conditions met), then it will generate iLDT files. For more information, see -generate option.

Any validation errors will be reported, usually along with file name and line number, like the result of grep -n.

File Types

The irep_parser can handle almost all types of application source files. While validating the annotated files against the annotation standards of the supported interface types, files that do not match will be ignored.

Here is the list of supported file types:

Note: Integration Repository Parser supports custom interface definitions for XML Gateway Map, Business Event, PL/SQL, Concurrent Program, Business Service Object, Java APIs, Java Bean Services, Application Module Services, and Composite Service for BPEL type.

Custom interface types of EDI, Open Interface Tables, Interface Views, and Java APIs for Forms interfaces are not supported in this release.

Files Specifications

Argument filespec tokens have the following formats:

Options

Options can be abbreviated by the smallest significant number of characters. Often this can be just the first character. Options cannot be combined. Here are the supported options:

Return Value

The parser will return an exit value of 0 if no errors occurred during processing. Otherwise, it will return a count of the number of files that had errors.

Files with incomplete information for generation (class resolution) are considered errors only if the -generate flag is used.

Quick Validation Examples

Use the following statements in validating annotation in PL/SQL specification files during development:

Uploading ILDT Files to Integration Repository

After validation is completed and iLDT files are generated, the integration administrator can upload the generated iLDT files to the Integration Repository using the FNDLOAD command. The custom interfaces can be displayed in the repository and exposed to all users.

Manual Steps for Uploading the iLDT File

Perform the following steps to upload the iLDT file to the Integration Repository:

  1. Log in to the Oracle E-Business Suite Release 12 instance.

  2. Set the Oracle E-Business Suite application environment.

    From the Oracle E-Business Suite APPS_BASE, establish the run file system APPL_TOP environment by running the EBSapps.env script.

  3. Use the following command to upload the iLDT file:

    $FND_TOP/bin/FNDLOAD <APPS username> 0 Y UPLOAD $fnd/patch/115/import/wfirep.lct <ildt file>

    ORACLE Password:

    Examples of uploading iLDT files for custom PL/SQL APIs and custom composites of BPEL type:

  4. Pay attention to any error messages in the generated log file. Error messages mostly would be due to incorrect database connect string or incorrect lct file.

    Look for string "Concurrent request completed successfully" to determine whether the iLDT file was correctly uploaded.

  5. For Business Service Object only - submit a concurrent program called FNDIRLOAD which loads all the iLDT files related to Business Service Object interfaces present on various product tops of the instances.

    Note: Ensure that FNDIRLOAD concurrent program is associated with the user who will execute the concurrent request.

    For example, if the request will be run by a user who has the system administrator responsibility, FNDIRLOAD should be listed as part of the requests for System Administrator Reports group in the Request Groups window.

    Request Groups Window

    the picture is described in the document text

    If you cannot find FNDIRLOAD from the name list, use the following steps to register it with the system administrator responsibility.

    1. Log in to Oracle E-Business Suite with the System Administrator responsibility. Select System Administrator > Security > Responsibility > Define from the navigation menu.

    2. In the Responsibilities window, locate 'System Administrator' as the value in the Responsibility Name field through a search.

      Ensure 'System Administrator Reports' is selected as the Request Group Name.

      Responsibilities Window

      the picture is described in the document text

      Save the change and close the window.

    3. Select System Administrator > Security > Responsibility > Requests from the navigation menu.

      In the Request Group window, locate 'System Administrator Reports' as the value in the Group field through a search.

      In the Requests region, add FNDIRLOAD program to the list and save your entry.

      Request Groups Window

      the picture is described in the document text

    In the Parameters window, enter an appropriate value for APPLTOP_ID.

    Entering Parameter Value

    the picture is described in the document text

    Note: To obtain the APPLTOP_ID parameter value, your system administrator can execute the following query:

    SELECT max(appl_TOP_id)
    FROM ad_appl_tops
    WHERE active_flag = 'Y'

    Click Submit to execute the request.

    Examine the request log file to see if any issues occur while executing the concurrent request.

Once these annotated source files have been successfully uploaded, they will appear in the Integration Repository based on the interface types they belong to. The administrator can perform administrative tasks on these custom integration interfaces.

If the upload is for an updated version of iLDT file, after the upload the administrator needs to perform the following additional tasks to ensure successful invocation of the updated API included in the file:

Administering Custom Integration Interfaces and Services

Custom integration interfaces are annotated based on Integration Repository annotation standards for the supported interface types. The behavior of these interfaces is the same as Oracle seeded interfaces except they are not native packaged, but custom ones. As a result, an integration administrator uses the same approach of managing native interfaces to manage custom interfaces and services.

These administrative tasks include:

Viewing Uploaded Custom Integration Interfaces from the Integration Repository

Use the following ways to locate custom interfaces:

For more information on how to search for custom integration interfaces, see the Oracle E-Business Suite Integrated SOA Gateway User's Guide.

Creating Security Grants for SOAP Services Only

To let appropriate users use these newly uploaded custom integration interfaces, the administrators can select one or more methods contained in a given custom interface and then grant the selected method access permissions to a user, user group, or all users.

For interfaces with the support for SOAP services only, security grants are managed in the Methods region of the interface details page. For more information about managing grants for interfaces with the support for SOAP services only, see Managing Security Grants for SOAP Web Services Only.

Generating Custom SOAP Web Services

Once custom integration interfaces have been uploaded to Oracle Integration Repository, an integration administrator or an integration developer can transform these interface definitions into WSDL descriptions if the interface types they belong to can be service enabled.

To generate a Web service, the administrator must first locate a custom interface, and then specify the interaction pattern either at the interface level or the method level before clicking Generate in the interface details page.

If the Web service has been successfully generated, a WSDL link appears along with the 'Generated' Web service status information displayed in the Web Service region (or the SOAP Web Service tab if the interface can be exposed as both SOAP and REST services). The selected interaction pattern information ('Synchronous', 'Asynchronous', or both Synchronous and Asynchronous) for the selected custom service is also displayed.

For detailed information on how to generate SOAP services on native integration interfaces, see Generating SOAP Web Services.

Deploying and Undeploying Custom SOAP Web Services

Once a Web service has been successfully generated for a custom interface, like native packaged interfaces, the administrator will perform the same deployment activity to deploy the generated service to an Oracle SOA Suite WebLogic environment with Active state. Before deploying the custom service, the administrator must select one authentication type to authenticate the Web service.

The administrator can undeploy the service if needed.

Note: Similar to the native Oracle E-Business Suite services, the deployed WSDL URL for the custom service shows the physical location of service endpoint where the service is hosted in soa-infra in this release. If your system is upgraded from a previous Oracle E-Business Suite release, after the upgrade to Release 12.2, the deployed WSDL URL information for the custom service has already been changed. Therefore, you may need to replace it with the new WSDL URL and service location or address accordingly in Web service clients while invoking the deployed custom service.

For detailed information on how to deploy or undeploy SOAP Web services, see Deploying and Undeploying SOAP Web Services.

Resetting Custom SOAP Web Services

Once a custom service has been successfully generated or deployed, Reset appears in the Web Service region (or the SOAP Web Service tab if the interface can be exposed as both SOAP and REST services) allowing you to reset the 'Generated' or 'Deployed' Web service status to its initial state - 'Not Generated' if needed. This feature clears up the custom service artifact for a given service regardless of its current state.

For more information, see Resetting SOAP Web Services.

Retiring Custom SOAP Web Services

When a custom service has been successfully deployed to Oracle SOA Suite with active state, this deployed custom service is ready to accept new requests.

The administrator can change the active state of a deployed custom service by clicking Retire in the Web Service region (or the SOAP Web Service tab if the interface can be exposed as both SOAP and REST services). This retires a deployed custom service and it will no longer accept new requests.

For a retired custom service, the administrator can activate the retired service so that it can become active again.

For more information on retiring SOAP Web services, see Retiring SOAP Web Services.

Activating Custom SOAP Web Services

For a custom service that has been retired, you can activate it by clicking Activate in the interface details page. This action allows a retired custom service to become active again.

For more information on activating Web services, see Activating SOAP Web Services.

Subscribing to Custom Business Events

Similar to the native business events, the administrator can subscribe to a custom business event by clicking Subscribe from the business event interface details page. Internally, an event subscription is created for that selected event with WF_BPEL_QAGENT Out Agent.

Once an event subscription for that custom event has been successfully created, Unsubscribe appears instead. Clicking Unsubscribe removes the event subscription from the WF_BPEL_Q queue.

For more information on subscribing to business events, see Subscribing to Business Events.

Deploying Custom REST Web Services

After custom interfaces that can be exposed as REST services are uploaded to the Integration Repository, the administrator can deploy the custom REST services.

Before deploying a custom interface as a REST service, the administrator must specify service alias for the selected interface and select one or more methods from the Service Operations table. Additionally, if the selected interface type is Java Bean Services or Application Module Services, the administrator needs to specify HTTP verbs for desired Java or Application Module methods contained in the selected interface before deployment.

If the service has been successfully deployed, the REST Service Status field is updated to 'Deployed' from 'Not Deployed' indicating that the deployed REST service is ready to accept new service requests.

For more information on deploying REST services, see Deploying REST Web Services.

Undeploying Custom REST Web Services

If a custom REST service has been successfully deployed to an Oracle E-Business Suite managed server, Undeploy appears in the REST Web Service tab. Undeploying a REST service not only brings the deployed REST service back to the Integration Repository, but also resets its status to its initial state - 'Not Deployed'.

For more information on undeploying REST services, see Undeploying REST Web Services.

Creating Security Grants for Custom REST Services

Similar to managing grants for the interfaces with the support for SOAP services only, the administrators can create grants by selecting one or more methods contained in a given custom interface and then grant the selected method access permissions to a user, user group, or all users. However, for interfaces that can be exposed as REST services, security grants are managed in the Grants tab instead.

Once an access permission to a procedure is authorized to a grantee, it grants the permission to access the associated SOAP and REST service operations simultaneously. For more information about managing grants for interfaces with the support for SOAP and REST services, see Managing Security Grants for SOAP and REST Web Services.

Viewing and Downloading Custom Composite Services

Viewing Custom Composite Services

To view a custom composite service, from the Search page select 'Composite' from the Interface Type field. Click Show More Search Options and select 'Custom' from the Interface Source drop-down list along with any product family or scope as the search criteria.

click a custom composite service from the search result to display the composite service details.

Downloading Custom Composite Services

The administrators can click Download Service in the interface details page to download the relevant custom composite files aggregated in a .JAR file to your local directory.

For more information on how to view and download a composite service, see: