Oracle E-Business Suite Integrated SOA Gateway allows you to create custom business events in the Business Event System, download the events that you have created, annotate the event source codes, validate the source files, and then upload the files back to the event system using Workflow XML Loader.
The Workflow XML Loader is a command line utility that lets you upload and download XML definitions for Business Event System objects between a database and a flat file. When you download Business Event System object definitions from a database, Oracle Workflow saves the definitions as an XML file. When you upload object definitions to a database, Oracle Workflow loads the definitions from the source XML file into the Business Event System tables in the database, creating new definitions or updating existing definitions as necessary.
XML files uploaded or downloaded by the Workflow XML Loader should have the extension .wfx to identify them as Workflow object XML definitions.
Use the following steps to create custom business events:
After creating custom business events in the Oracle Workflow Business Event System, you first locate them and then download them using Workflow XML Loader.
To download XML definitions for Business Event System objects between a database and a flat file, run the Workflow XML Loader by running Java against oracle.apps.fnd.wf.WFXload with the following command syntax:
jre oracle.apps.fnd.wf.WFXload -d{e} <user> <password> <connect string> <protocol> <language> <xml file> <object> {<key>} {<OWNER_TAG>} {<owner>}
For example, you can download either a single event or a group of events:
Use the following command to download a single business event, such as wfdemoe.wfx. In the filename, the first two or three characters refer to the product and the last character 'e' refers to Event.
java oracle.apps.fnd.wf.WFXLoad -d apps_read_only password hostdb:12345:sid100 thin US wfdemoe.wfx EVENTS abc.apps.wf.bes.demo.event
Use the following command to download a group of business events with wildcard:
java oracle.apps.fnd.wf.WFXLoad -d apps_read_only password hostdb:12345:sid100 thin US wfdemoe.wfx EVENTS abc.apps.wf.bes.%
After successfully downloading the event XML definitions, open the .wfx file in any text editor. You will find the content of a wfdemoe.wfx file, for example, containing one event shown as follows:
<?xml version = '1.0' encoding = 'UTF-8'?> ... <oracle.apps.wf.event.all.sync><ExternalElement> <OraTranslatibility> <XlatElement Name="WF_EVENTS"> <XladID> <Key>NAME</Key> </XladID> <XlatElement Name="DISPLAY_EVENTS" MaxLen="80" Expansion="50"/> <XladID> <Key Type="CONSTANT">DISPLAY_EVENTS</Key> </XladID> <XlatElement Name="DESCRIPTION" MaxLen="2000" Expansion="50"/> <XladID> <Key Type="CONSTANT">DESCRIPTION</Key> </XladID> </XlatElement> </OraTranslatibility> </ExternalElement> <WF_TABLE_DATA> <WF_EVENTS> <VERSION>1.0</VERSION> <GUID>#NEW</GUID> <NAME>abc.apps.wf.demo.event</NAME> <TYPE>EVENT</TYPE> <STATUS>ENABLED</STATUS> <GENERATE_FUNCTION/> <OWNER_MAME>Oracle Workflow</OWNER_MAME> <OWNER_TAG>FMD</OWNER_TAG> <CUSTOMIZATION_LEVEL>U</CUSTOMIZATION_LEVEL> <LICENSED_FLAG>Y</LICENSED_FLAG> <JAVA_GENERATE_FUNC/> <DISPLAY_NAME>Demo Business Event</DISPLAY_NAME> <DESCRIPTION>Business event created for annotation demo.</DESCRIPTION> <IREP_ANNOTATION> /*# * Business event created for annotation demo. * * @rep:scope public * @rep:displayname Demo Business Event * @rep:product FND * @rep:category BUSINESS_ENTITY */ </IREP_ANNOTATION> </WF_EVENTS> </WF_TABLE_DATA> </oracle.apps.wf.event.all.sync>
The Workflow XML Loader automatically creates a template for integration repository annotation as highlighted in bold between <IREP_ANNOTATION> and </IREP_ANNOTATION>. This is where appropriate annotations need to be placed or modified for a business event based on the business event annotation standards.
To download business events XML definitions:
Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility. Select the Business Events link from the Navigator to open the Events page.
Enter search criteria in the Search region to locate your business events.
Change your directory to the same environment where your application is running.
For example, if your application is running on seed100, then change your directory to seed100 where your business events exist.
/slot/ems3404/appmgr/apps/apps_st/appl . ./APPSseed100.env
Download the events from the database using oracle.apps.fnd.wf.WFXload with the following syntax:
jre oracle.apps.fnd.wf.WFXload -d{e} <user> <password> <connect string> <protocol> <language> <xml file> <object> {<key>} {<OWNER_TAG>} {<owner>}
Open the .wfx file in any text editor and notice that one business event has been placed there.
After successfully downloading the XML definition file from a database, you should open the .wfx file containing one business event in any text editor and modify the annotation appropriately based on Integration Repository business event annotation standards.
The appropriate annotation includes:
Enter meaningful description.
Enter conditions under which the business event is raised.
Enter UI action that invokes the business event if applicable.
Verify scope. By default, the Workflow XML Loader annotates scope as 'public'.
Verify display name. By default, the Workflow XML Loader uses the same display name as that mentioned in business event definition.
Verify product. By default, the Workflow XML Loader uses Owner Tag as the Application Short Name.
Make sure that the Owner Tag corresponds to Application Short Name in FND_APPLICATION. Owner Name typically corresponds to Application Name, but if your product is part of a larger application, you may enter an appropriate name in Owner Name.
Enter BUSINESS_ENTITY code that your respective business event belongs to.
Enter additional annotation properties if needed.
Please note that the IREP properties should not be blank. For example, the Workflow XML Loader only adds the template for Business Entity as rep:category BUSINESS_ENTITY, but you should add an appropriate business entity to which the event belongs. Similarly, other @rep properties cannot be left blank either.
The following is a sample business event annotation for Oracle Workflow:
* Business Event created to demonstrate using WFXLoad to annotate Business Events. * * @rep:scope internal * @rep:displayname Demo Business Event * @rep:product OWF * @rep:lifecycle active * @rep:category BUSINESS_ENTITY WF_EVENT */
Attention: If you decide not to annotate or publish the event in Oracle Integration Repository, you should remove the annotation only but leave the following tags unchanged. Presence of these tags is an indication that the event was reviewed for annotation.
<IREP_ANNOTATION/>
or
<IREP_ANNOTATION></IREP_ANNOTATION>
If the Loader sees these empty tags, it interprets that the business event was reviewed for annotation and it does not need to be published to the Integration Repository. Next time, when the user downloads these events, the Loader will insert empty IREP_ANNOTATION tags as shown in the following example.
However, if you remove the entire IREP_ANNOTATION tags for the business event and upload it, then on subsequent download, the Loader will insert partially filled annotation template for the business event.
<WF_TABLE_DATA> <WF_EVENTS> <VERSION>1.0</VERSION> <GUID>#NEW</GUID> <NAME>oracle.apps.wf.demo.event.noannotate</NAME> <TYPE>EVENT</TYPE> <STATUS>ENABLED</STATUS> <GENERATE_FUNCTION/> <OWNER_MAME>Oracle Workflow</OWNER_MAME> <OWNER_TAG>FMD</OWNER_TAG> <CUSTOMIZATION_LEVEL>U</CUSTOMIZATION_LEVEL> <LICENSED_FLAG>Y</LICENSED_FLAG> <JAVA_GENERATE_FUNC/> <DISPLAY_NAME>Demo Business Event with no annotation</DISPLAY_NAME> <DESCRIPTION>Business second event created for annotation demo.</DESCRIPTION> <IREP_ANNOTATION>/*# * Business event created for annotation demo. * * @rep:scope public * @rep:displayname Demo Business Event * @rep:product FND * @rep:category BUSINESS_ENTITY */ </IREP_ANNOTATION> </WF_EVENTS> </WF_TABLE_DATA>
For more information on Integration Repository Business Event Annotation Standards, see Business Event Annotations.
Integration Repository Parser is a standalone design-time tool. It can be executed to validate the annotated custom interface definitions against the annotation standards and to generate an iLDT file if no error occurs.
After annotating the XML definition for a business event, execute the standalone Integration Repository Parser (IREP Parser) using the following command syntax to validate whether the annotation in .wfx file is valid:
Command 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 owf:patch/115/xml/US:wfdemoe.wfx:12.0=./wfdemoe.wfx
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 occurred in the annotated interface file, an iLDT (*.ildt) file would be generated. An integration administrator needs to upload the generated iLDT file to the Integration Repository where the custom business events can be exposed to all users. See Step 5: Uploading iLDT Files to Integration Repository.
Integration Repository Parser (irep_parser.pl)
The irep_parser is a design-time tool. It 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. Any validation errors will be reported, usually along with file name and line number, like the result of grep -n.
Additionally, it 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.
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.
However, before executing the Integration Repository Parser, you need to install perl modules and apply necessary patches. For setup information, see Setting Up and Using Integration Repository Parser.
For information on the Integration Repository Parser (irep_parser.pl) usage details including supported file types and options, files specifications, and environment, see Integration Repository Parser (irep_parser.pl) Usage Details.
After validating the annotated source file .wfx, upload the file back to the database where you downloaded it earlier so that the annotated file can be stored in the appropriate tables in business event system for future references.
Note: To view custom business events through the Integration Repository browser window, an integration administrator needs to upload the generated iLDT files to the Integration Repository. For information on uploading iLDT files, see Step 5: Uploading iLDT Files to Integration Repository.
The Workflow XML Loader lets you upload business event system XML definitions in either normal upload mode (-u) or force upload mode (-uf):
Normal upload mode (-u): If you created an event with a customization level of Core or Limit, the Workflow XML Loader will be able to update IREP_ANNOTATION into the Business Event System WF_EVENTS table in the database. This normal mode will not make any updates to events or subscriptions with a customization level of User.
Use the following command to upload the annotated .wfx file back to a database:
java oracle.apps.fnd.wf.WFXLoad -u apps_read_only password hostdb:12345:sid100 thin US wfdemoe.wfx
Force upload mode (-uf): The Workflow XML Loader loads the object definitions from the source XML file into the Business Event System tables in the database and overwrites any existing definitions, even for events or subscriptions with a customization level of User.
Therefore, if you created an event with a customization level of User, use the following force upload option to make sure the IREP_ANNOTATION can be uploaded back into the database.
java oracle.apps.fnd.wf.WFXLoad -uf apps_read_only password hostdb:12345:sid100 thin US wfdemoe.wfx
For more information on how to use Workflow XML Loader, see Using the Workflow XML Loader.
After the validation using the Integration Repository Parser, an iLDT file will be generated if no error occurred during the iLDT generation. In order for users to view the custom business events through the Integration Repository, an integration administrator needs to manually upload the generated iLDT file to the Integration Repository using FNDLOAD command.
$FND_TOP/bin/FNDLOAD <APPS username> 0 Y UPLOAD $fnd/patch/115/import/wfirep.lct <ildt file> ORACLE Password:
For example,
FND_TOP/bin/FNDLOAD apps @instance_name 0 Y UPLOAD $FND_TOP/patch/115/import/wfirep.lct SOAIS_pls.ildt
ORACLE Password: password
For detailed information on how to upload the iLDT files, see Uploading ILDT Files to Integration Repository.
Searching and Viewing Custom Interfaces
Annotated custom interface definitions, once they have been successfully uploaded, are merged into the interface types they belong to and displayed together with Oracle seeded interfaces from the Integration Repository browser window. To easily distinguish custom interface definitions from Oracle interfaces, the 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.
To search for custom integration interfaces, you can use either one of 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 interfaces display.
From the Search page, click Show More Search Options to select 'Custom' from the Interface Source drop-down list along with any interface type (such as 'Business Event'), product family, or scope if needed as the search criteria.
After executing the search, all matched custom integration interfaces will be displayed. For more information on how to search and view custom integration interfaces, see Searching Custom Integration Interfaces and Viewing Custom Integration Interfaces.
Performing Administrative Tasks
Once custom business events have been successfully uploaded and displayed from the Integration Repository browser window, an integration administrator can perform the same administrative tasks on these custom events as they are for the native events. These administrative tasks including creating security grants for newly created custom events if needed, and subscribing to custom business events. See Administering Custom Integration Interfaces and Services.