Skip Headers

Oracle E-Business Suite Integrated SOA Gateway Implementation Guide
Release 12.1
Part Number E12169-08
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, system integration developers can create and annotate custom interface definitions based on Integration Repository Annotation Standards. With appropriate validation, if no error occurred, the validated custom definition sources compiled in a generated iLDT file can be uploaded to Oracle Integration Repository through backend processing.

Note: Please note that custom interface types of EDI, Open Interface Tables, and Open Interface Views 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 together with Oracle seeded ones through the Integration Repository user interface based on the interface type 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 interfaces. 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.

Enabling Custom Integration Interface Process Flow

The entire process flow described here can be illustrated in the following diagram:

the picture is described in the document text

  1. Users who have the System 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.

  2. Users who have the Integration Repository 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 Repository 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 Repository 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 Repository 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 clicking Generate WSDL in the selected custom interface details page. See: Generating Custom SOAP Web Services.

  7. (Optional) Users who have the Integration Repository 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 to the application server. 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 before deploying the service. Additionally, the administrators need to specify HTTP methods for desired service operations contained in the selected interface if it is an interface type of Java Bean Services or Application Module Services.

    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 and perform administrative tasks on these uploaded custom integration interfaces, the following topics are discussed in this chapter:

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. An integration repository administrator uses it to validate and generate the annotated custom interface definitions against the annotation standards. It can read almost all types of application source files. While executing the parser, the annotated source files are validated based on the interface type supported for customization. If no error occurs, an Integration Repository loader file (iLDT) will be created.

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

It is currently tested and certified for Linux, Unix, Oracle Solaris on SPARC, HP-UX Itanium, HP-UX PA-RISC, IBM AIX on Power Systems and Windows.

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:

To install Perl modules:

  1. Set the Oracle E-Business Suite application environment:

    From the Oracle E-Business Suite application instance APPL_TOP, set the environment by running the APPS<CONTEXT_NAME>APPS.env(.cmd) script.

  2. Set 10.1.3 ORACLE_HOME:

    Navigate to the <INST_TOP>/ora/10.1.3 and source the .env/.cmd file to set your 10.1.3 ORACLE_HOME.

  3. Add directory $FND_TOP/perl to environment variable PERL5LIB:

    1. Find physical path of $FND_TOP/perl.

    2. Add this physical path in PERL5LIB variable.

    3. Example: export PERL5LIB=/slot/ems3404/appmgr/apps/apps_st/appl/fnd/12.0.0/perl:/slot/ems3404/appmgr/apps/tech_st/10.1.3/perl/lib/5.8.3:/slot/ems3404/appmgr/apps/tech_st/10.1.3/perl/lib/site_perl/5.8.3:/slot/ems3404/appmgr/apps/apps_st/appl/au/12.0.0/perl:/slot/ems3404/appmgr/apps/tech_st/10.1.3/Apache/Apache/mod_perl/lib/site_perl/5.8.3/i686-linux-thread-multi.

  4. Use the following steps for installation on different platforms:

  5. Search and download the following perl modules that are required to be installed manually from CPAN:

    For example, use the following steps to install Compress-Raw-Zlib-2.009.tar.gz:

    #gzip -d Compress-Raw-Zlib-2.009.tar.gz

    tar -xvf Compress-Raw-Zlib-2.009.tar

    cd Compress-Raw-Zlib-2.009

Using the Integration Repository Parser

Once you have the Integration Repository Parser 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 already 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 that is already 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, the Header version of the target source file needs to be incremented so that the modifications to the object defined in the source file can take effect in the Integration Repository.

How to execute the parser to validate the files and upload them are further discussed in this section:

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:

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>

For example:

$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -g -v -username=sysadmin itg:patch/115/sql:fndav.pls:12.0=/tmp/fndav.pls

Note: If an error message "Java runtime not found" appears while executing the Integration Repository Parser, then set the environment variable JAVA_HOME to variable OA_JRE_TOP which is typically located at $IAS_ORACLE_HOME/appsutil/jdk/jre.

While executing the parser, pay attention to any error messages on the console. Typically 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

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 supported interface types, if files that do not match will be ignored.

Here is the current 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, and Composite Service for BPEL type.

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

Files Specifications

Argument filespec tokens can 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

While executing the Integration Repository Parser to validate the annotated custom interface definitions against the annotation standards and generate iLDT file, if no error occurs during the iLDT generation, an integration repository administrator can upload the generated iLDT file to the Integration Repository where they can be 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. Use Telnet to have command access to the Oracle E-Business Suite Release 12 instance.

  2. Issue the following command to upload the iLDT file:

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

    For example, FND_TOP/bin/FNDLOAD apps/apps@instance_name 0 Y UPLOAD $FND_TOP/patch/115/import/wfirep.lct SOAIS_pls.ildt

  3. Pay attention to any error messages in the generated log file. Typically the error messages 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.

  4. For Business Service Object only: Submit a concurrent request for program FNDIRLOAD.

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

Once these annotated source files are successfully uploaded, they will appear in the Integration Repository user interface based on the interface type together with Oracle seeded integration interfaces. The administrators can perform administrative tasks on these custom integration interfaces including generate, deploy, or redploy Web services.

Administering Custom Integration Interfaces and Services

After being uploaded to the Integration Repository, custom integration interfaces will be embedded into appropriate interface categories where the interfaces belong but with 'Custom' interface source in contrast to Oracle seeded ones with interface source 'Oracle'.

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

These administrative tasks include:

Viewing Uploaded Custom Integration Interfaces From the Integration Repository

Before performing administrative tasks, you must first locate a custom integration interface from the Integration Repository and then access the interface details page.

Note: The custom interface details page shows 'Custom' as the Interface Source value, while the source value of 'Oracle' is for native packaged integration interfaces.

You can find a custom interface in the following ways:

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 actually use these newly uploaded custom integration interfaces, the administrators can create security grants, if needed, by authorizing the access permissions for selected interface methods to an appropriate user, a user group, or all users.

This security grant is performed in the Create Grant page for a selected custom integration interface to control the method at a very granular level.

For more information, see Managing Security Grants for SOAP Services Only.

Generating Custom SOAP Web Services

Once custom integration interfaces are uploaded to Oracle Integration Repository, an integration repository administrator can transform these interface definitions into WSDL descriptions if the interface type they belong to can be service enabled.

To generate a WSDL URL so that a selected interface can become Web service, the administrator who has the privilege must first locate the custom interface that you desire and then generate the Web service by clicking Generate WSDL in the interface details page.

If the Web service is successfully generated, you should notice a WSDL link available along with the 'Generated' Web Service Status field displayed in the Web Service - SOA Provider region (or the SOAP Web Service tab if the interface can be exposed as both SOAP and REST services).

Click the WSDL link to view the WSDL description. See: Reviewing Web Service WSDL Source, Oracle E-Business Suite Integrated SOA Gateway User's Guide.

Note: Because custom integration interface is supported in this release, even if a custom interface is for XML Gateway Map or Business Service Object interface type, there will not be the Web Service - Web Service Provider region in the details page for the backward compatibility.

Additionally, the following buttons are available for further actions on the generated service:

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

Deploying, Undeploying, and Redeploying SOAP Web Services

Once the Web services is successfully generated for custom integration interfaces, like native packaged interfaces, the administrator will perform the same deployment activities if necessary to deploy the generated services to the application server, and redeploy or undeploy them again from the server.

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

Subscribing to Custom Business Events

Similar to the native business events, an integration repository 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 the event subscription has been successfully created, a confirmation message appears in the business event details page.

To consume the business event message, you should register to dequeue the event from Advanced Queue WF_BPEL_Q. If a business event is enabled and if there is at least one subscriber registered to listen to WF_BPEL_Q, then the event message will be enqueued in WF_EVENT_T structure to Advanced Queue WF_BPEL_Q.

The Unsubscribe button becomes available in the details page if the selected event has been subscribed. Clicking the Unsubscribe button removes the event subscription. A confirmation message also appears after the subscription has been successfully removed.

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. If the selected interface type is Java Bean Services or Application Module Services, the administrator also 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

If a custom interface is needed for a composite service - BPEL type, the integration developer will first create a composite service by orchestrating discrete native services into a meaningful process flow using BPEL. Based on the annotation standards specifically for composite service, the developer will then annotate the composite service, and create and unzip the JAR file of the BPEL project.

After appropriate validation on the BPEL project JAR files to ensure the compliance with the composite service annotation standards, the administrators will then upload them to the Integration Repository.

Viewing Custom Composite Services

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

By clicking a custom composite service name link from the search results, you will find the composite service interface details page displaying composite service details for this selected custom interface.

Downloading Custom Composite Services

Similar to downloading native packaged 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.

Note: An integration repository developer can further unzip the BPEL .JAR file and open the BPEL file in Oracle JDeveloper for further modification on service endpoints if needed. Additionally, the integration repository developer can deploy the BPEL process if necessary. Since composite services are typically not deployed within Oracle E-Business Suite, a separate BPEL PM (SOA Suite or a third party BPEL PM server) is needed to deploy the BPEL composite services.

For example, you can deploy the BPEL process to Oracle BPEL server through Oracle BPEL Process Manager. See Oracle E-Business Suite Integrated SOA Gateway Developer's Guide for details.

For more information on how to download a composite service, see Downloading Composite Services.