Release 12.1
Part Number E12169-06
Contents
Previous
Next
| Oracle E-Business Suite Integrated SOA Gateway Implementation Guide Release 12.1 Part Number E12169-06 | Contents | Previous | Next |
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 (except for Java APIs for Forms subtype) 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, 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 together with Oracle seeded ones through the Integration Repository user interface based on the interface type they belong to. Hence, 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, generating and deploying Web services.
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.
Enabling Custom Integration Interface Process Flow
The entire process flow described here can be illustrated in the following diagram:
A system integration developer annotates a custom integration interface definition based on the Integration Repository annotation standards for the supported interface types.
An integration repository administrator validates 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.
An integration repository administrator uploads the generated iLDT file to Oracle Integration Repository.
The integration repository administrator then creates necessary security grants for the custom integration interfaces if needed.
The administrator generates Web services if the custom interfaces can be service enabled.
The administrator deploys the Web services from Oracle Integration Repository to the application server.
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.
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:
Linux x86/x86-64: Intel C/C++ Compiler (icc) version 7.1.032
Oracle Solaris on SPARC (64-bit): Oracle Studio 11 (5.8)
Microsoft Windows Server (32-bit): Microsoft Visual Studio 2005 (VC 8.0)
HP-UX Itanium: HP ANSI C B3910B A.0.06.05
HP-UX PA-RISC (64-bit): HP92453-01 B.11.11.10 HP C Compiler
IBM AIX on Power Systems (64-bit): XL C Enterprise 8.0
Prerequisites for Installing Perl Modules on Windows
It is necessary to create a manifest file for perl.exe in the 10.1.3Home\perl\5.8.3\bin\MSWin32-x86-multi-thread directory if your installation is on Windows.
To create a manifest file for perl.exe:
Log on to the Oracle E-Business Suite middle-tier server.
Change directories to c:\WINDOWS\WinSxS.
Verify if there is a file that starts with x86_Microsoft.VC80.CRT. For example, x86_Microsoft.VC8.CRT_1fc8b3b9a1e18e3b_8.0.50727.42_x-ww_0de06acd.
Record this filename.
Change directories to where the perl.exe resides in the 10.1.3 Home.
For example,
cd e:\PROD\apps\tech_st\10.1.3\perl\5.8.3\bin\MSWin32-x86-multi-thread
Open a file with text editor (such as Notepad) to create a manifest file.
Enter the following statements, for example, with the 'version' and 'publicKeyToken' taken from the x86_Microsoft.VC80.CRT file name:
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<assembly xmlns='urn:schemas-microsoft-com:asm.v1' manifestVersion='1.0'>
<dependency>
<dependentAssembly>
<assemblyIdentity type='win32' name='Microsoft.VC80.CRT'
version='8.0.50727.42' processorArchitecture='x86'
publicKeyToken='1fc8b3b9a1e18e3b'/>
</dependentAssembly>
</dependency>
</assembly> Save the file with the name perl.exe.manifest.
To install Perl modules:
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.
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.
Add directory $FND_TOP/perl to environment variable PERL5LIB:
Find physical path of $FND_TOP/perl.
Add this physical path in PERL5LIB variable.
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.
Use the following steps for installation on different platforms:
On Unix
Find the value of $IAS_ORACLE_HOME/perl in your environment, for example /slot/ems1340/appmgr/apps/tech_st/10.1.3/perl.
Locate the $IAS_ORACLE_HOME/perl/lib/5.8.3/i686-linux-thread-multi/Config.pm.
Take backup of this file. Replace all occurrences of /ade/smayer_perl58_main_linux/perl58/bin/Linux/Opt with value of $IAS_ORACLE_HOME/perl. For example, /slot/ems1340/appmgr/apps/tech_st/10.1.3/perl.
On Windows
Search for all Config.pm files underneath %IAS_ORACLE_HOME%\perl, and record their location, such as:
%IAS_ORACLE_HOME%\perl\5.8.3\bin\Config.pm%IAS_ORACLE_HOME%\perl\5.8.3\lib\MSWin32-x86-multi-thread\Config.pm
For each Cofing.pm file, modify all parameters that point to perl with the correct location of %IAS_ORACLE_HOME%\perl. For example, in the %IAS_ORACLE_HOME%\perl\5.8.3\bin\Config.pm file, modify archlibexp from '%ORACLE_HOME%\perl\5.8.3\lib\MSWin32-x86-multi-thread to e:\PROD\apps\tech_st\10.1.3\perl\5.8.3\lib\MSWin32-x86-multi-thread.
For each Cofing.pm file, modify all parameters that point to Visual C++ with the correct location of Visual C++.
The location of Visual C++ is identified through the msdevdir parameter in the context file at %INST_TOP%\apps\admin\<CONTEXT_NAME>.xml.
For example, in the %IAS_ORACLE_HOME%\perl\5.8.3\lib\MSWin32-x86-multi-thread\Config.pm file, modify libpth to the correct location of Visual C++:
libpth=d:\VC8\VC\lib (d:\VC8\VC is an example).
Search and download the following perl modules that are required to be installed manually from CPAN:
Compress-Raw-Zlib-2.009
(http://search.cpan.org/~pmqs/Compress-Raw-Zlib-2.009)
Compress-Zlib-2.009
(http://search.cpan.org/~pmqs/Compress-Zlib-2.009 )
Class-MethodMaker-1.12
(http://search.cpan.org/~fluffy/Class-MethodMaker-1.12)
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
On Unix
perl Makefile.PL
make
make install
Note: Ignore any warning in make command.
On Windows
perl Makefile.PL
nmake
nmake install
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:
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.
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 (except for Java APIs for Forms subtype) 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.
.java: All Java files are completely parsed.
.p(kh?ls): PL/SQL package specs are processed.
If and when a package body is detected, the parser aborts processing and the file is ignored.
.ldt: It processes the LDT file for annotated concurrent programs. Most LDT files will fail and be ignored right away because they are not concurrent program loader files (i.e. not created with afcpprog.lct).
.xgm: It processes the XML Gateway map file, looking for an annotated map.
.xml: It processes the XML file, scanning for signature contents indicating various kinds of Business Service Object data since the filename pattern is so generic.
.wfx: It processes the Business Event file, looking for annotated events.
Files Specifications
Argument filespec tokens can have the following formats:
pathname: A simple pathname argument directly indicates the file to be processed. Since path information is not included, the output iLDT can not be generated. For example, only validation is supported. See -development flag (This is backwards compatible with previous validation only usage.)
product:relative_path[:name[:version]]=pathname: Specify the product and relative path from product top (and optionally file name and version) in addition to the physical location of the file to process.
Please note that the source file information on the left-hand side of the ?=? sign is imported varbatim into the output iLDT, and otherwise not examined. The pathname on the right-hand side must refer to a real file, which can be located anywhere.
The product and relative_path correspond to file location on APPL_TOP.
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:
-generate: It generate iLDT (Interface Repository Seed Data) files if possible. The file is created in either the current directory or the directory designated by -outdir.
The generated file name is derived from the file name by replacing all periods with underscores, and then appending the suffix ?.ildt?.
Note: Use of the -generate flag requires that the command line filespecs to have (at least) the source product and path. For more information, see prod:path[:name[:version]]=pathname and the -development flag.
-force: If the -generate flag is used to request iLDT generation, and if the file is an incorrect file type for annotations or has no significant annotation contents (no annotation at all, or no @rep:scope tag in any master-level annotation), then an empty file is created anyway. If a file of the same name existed from a previous run, it is clobbered to be a zero-length file.
The net effect is that only files that had actual errors (parsing, validation, and incomplete for generation) will not be represented in the creation of (at least) in an empty iLDT file.
-development: It is a special flag for developers. It is equivalent to using the both -generate and the -verbose flags. It also supplies a default prod:path (of ?nul:relative/path/unknown?) to all plain-file filespecs that marks the resulting iLDT as a test file.
This allows to generate test iLDTs using a simple list of filenames.
-outdir=directory: It designates an alternate directory (other than the working directory) for generated output to be placed in.
-username=username: It designates a FND username (other than the default SEED username).
-logfile=file: It writes all verbose tracing and validation error messages in a log file instead of printing to standard output. It is mutually exclusive with -append-logfile.
-append-logfile=file: It is similar to -logfile, append all verbose tracing and validation error messages in a log file instead of printing to standard output. It is mutually exclusive with -logfile.
-verbose: It provides chatty information about files processed and other internals; non-fatal warning messages, etc. This is in addition to any error messages generated.
It is useful for querying the parser version, if used without any filespec arguments.
-java-source=version: It informs the parser what language version (via. JDK version number) to support for Java parses. A minor change was introduced in 1.4 (the assert facility), and major changes were introduced in 1.5 (generics, enhanced for loop, autoboxing/unboxing, enums, varargs, static import and annotations). If it is not supplied, then 1.5 is assumed.
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:
$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl *s.pls
$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -v -g itg:patch/115/sql:12.0=fndav.pls
Environment
The following environment variables affect parser operation:
CLASSPATH: It is used when parsing Java files. This is required to be properly set up (as if for a compile) when performing -generate with such files.
If parser is not able to find a particular class, check for its availability in CLASSPATH.
On a Linux machine, CLASSPATH can be set like setenv CLASSPATH classpath1:classpath2.
For others, check your platform documentation on how to set classpath variable.
JAVA_HOME: It is used to find the Java runtime if it is set. Otherwise, /local/java/jdk1.5.0 is used instead (For example, the application session server setup). Typical location of Java in Oracle E-Business Suite Release 12 environment is $IAS_ORACLE_HOME/appsutil/jdk.
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:
Use Telnet to have command access to the Oracle E-Business Suite Release 12 instance.
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
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.
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.
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:
For Custom Integration Interfaces of Interface Types
In addition to verifying if the uploaded custom interfaces can be successfully retrieved from the Integration Repository, to let appropriate users actually use these custom files, the administrators can create security grants to grant appropriate interface methods access privileges to an appropriate user, a user group, or all users.
Similar to the native integration interfaces, these custom interfaces can become WSDL-based Web services if the interface types they belong to can be service enabled.
Deploying, Undeploying, and Redeploying Web Services
Once the custom interfaces become Web services, integration repository administrators can deploy the generated Web services to Oracle Application Server. The administrators can also redeploy or undeploy the Web services if needed.
Subscribing to Custom Business Events
This task allows the administrators to subscribe to selected custom business events and create subscriptions for the selected events.
For Custom Composite Integration Interface
Viewing and Downloading Custom Composite Services
Integration repository administrators can view a custom composite service details, and download the .ZIP file for a composite service if it is available for download.
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:
From the Interface List page, select 'Custom' from the Interface Source drop-down list along with a value for the Scope field to restrict the custom integration interface display.
Viewing from Interface List Page
From the Search page, click Show More Search Options to select 'Custom' from the Interface Source drop-down list along with any interface type, product family, or scope if needed as the search criteria.
For example, select 'Custom' as the Interface Source and 'PL/SQL' as the Interface Type to locate the custom interfaces for PL/SQL type.
Viewing from Interface Search Page
For more information on how to search for custom integration interfaces, see Oracle E-Business Suite Integrated SOA Gateway User's Guide.
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 Creating Grants.
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 of the details page.
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:
Regenerate WSDL
This lets you regenerate the WSDL if necessary.
Deploy
Before deploying a service that is service enabled through SOA Provider, you must select at least one authentication type in the Authentication Type field for the selected service. The selected authentication type(s) will be used by SOA Provider to secure Web service content and authenticate Web service operation. Clicking Deploy in the Web Service - SOA Provider region lets you deploy the generated service from Oracle Integration Repository to the application server.
For detailed information on how to generate Web services on native integration interfaces, see Generating 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 Web Services.
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.
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.
Copyright © 2008, 2010, Oracle and/or its affiliates. All rights reserved.