B Using Classic Real-Time Events
This appendix contains the following topics:
Note:
This chapter is applicable only if you use classic events delivery. Classic event delivery is available when you use JD Edwards EnterpriseOne Tools 8.93 or earlier releases, or if you use JD Edwards EnterpriseOne Tools 8.94 with JD Edwards EnterpriseOne Applications 8.10.Refer to the Guaranteed Events chapters if you use JD Edwards EnterpriseOne Tools 8.94 with JD Edwards EnterpriseOne Applications 8.11 or JD Edwards EnterpriseOne Tools 8.95 and later tools releases with JD Edwards EnterpriseOne Applications 8.10 and later Applications releases.
B.1 Understanding Real-Time Events - Classic
A real-time event is notification that a business transaction has occurred in JD Edwards EnterpriseOne. You can generate real-time events on the JD Edwards EnterpriseOne server using an interface, such as HTML, WIN32, and terminal servers. You can use real-time events for either synchronous and asynchronous processing.
An example of synchronous processing is an auction site that uses JD Edwards EnterpriseOne as a back-end solution that can use real-time events to immediately update the database. For example, a user enters a new item for auction, which triggers a transaction into JD Edwards EnterpriseOne. The system captures the transaction and sends a notification to an interoperability server, such as a Java connector, that communicates the information to a web engine to update HTML pages so that all of the auction users can see the new item.
You can also use real-time event generation for asynchronous processing. For example, an online store sends orders to different vendors (business to business), captures the transactions, and enters the orders into the vendors' systems. A user buys a book. Vendors enter a purchase order to the book publisher and send a notification to the shipping company to pick up the book and deliver it. The book order itself can be completed as a purchase order transaction with JD Edwards EnterpriseOne, but the shipping request requires that the data is packaged into a commonly agreed-upon format for the shipping company to process.
B.1.1 Prerequisites
Before you complete the tasks in this section:
-
Enable security for the JD Edwards EnterpriseOne server.
-
Ensure that the default user under the [SECURITY] section of the JD Edwards EnterpriseOne server jde.ini file has a valid security record (that is, that the user is a valid JD Edwards EnterpriseOne user).
B.2 Processing Real-Time Events
Real-time events use system calls that receive data from business functions that use JD Edwards EnterpriseOne data structures. Each real-time event has a unique ID that includes the JD Edwards EnterpriseOne session ID.
Real-time event generation from a client consists of client business functions that call APIs and interfaces with the server interoperability event observer (a kernel). Real-time event generation on the server side includes an event observer interface (a set of system APIs) that triggers real-time events and an interoperability event observer (a kernel). Then, the event observer kernel generates XML documents of the triggered real-time events and sends them to an event distribution component. The event distribution component is the same one that the system uses to send XML document notification to subscribers.
This diagram is a logical representation of the processes and data for real-time event generation:
In summary:
-
Event generation is triggered by business functions.
You use the Object Configuration Manager (OCM) to map business functions to run on the JD Edwards EnterpriseOne server or to run locally. When a business function is mapped to run on the JD Edwards EnterpriseOne server, the business function calls the Interoperability Event Interface within the CallObject kernel. The CallObject kernel sends the information to the Interoperability Event Observation (IEO). When a real-time event is generated from a client, the client business function calls the appropriate API. The API performs OCM lookup to determine where the IEO kernel is located, validates, filters, and formats the data, and then sends the information to the IEO kernel.
-
The IEO kernel creates the real-time event and produces an XML document when the real-time event is finalized.
-
The IEO kernel packages the XML document and passes the document to the Event Notification (EVN) kernel.
-
The EVN kernel determines which transport driver should handle the event.
-
The transport driver distributes the event.
Note:
If you use IBM WebSphere MQ or MSMQ transports, the transport drive writes system and function errors to the JDE error log. The driver writes error messages and adds the error codes if available.
B.3 Defining Real-Time Events
You use the Interoperability Event Definition program (P90701) to define real-time events. After you define your real-time event, be sure to activate the event by changing the status to active. If the event is not defined in the F90701 table, the system call returns an error message.
B.4 Using Event Sequencing
When you define your real-time events, you indicate whether the event is reliable or volatile. If you define the event as volatile, the system automatically provides event sequencing to guarantee that events are delivered in the correct order. Volatile events are stamped using JD Edwards EnterpriseOne Next Numbers features.
For sequencing of real-time events, the system call, jdeIEO_EventFinalize, retrieves the event number from the real-time events sequencing bucket, and sends the number to the IEO kernel. The IEO kernel includes the event number as part of the generated event. The IEO kernel sends the event to the EVN kernel. The EVN kernel remembers the last shipped event and bases sequencing on the event number that is contained in the received event.
Event sequencing does impact performance. You can clear events sequencing. You can also define a timeout value to tell the system to stop looking for a missed event when events are out of sequence. The flag and timeout settings are in the [INTEROPERABILITY] section of the jde.ini file.
B.5 Using Journaling
Real-time events are journaled using the trace feature for the JDEDEBUG log files. You can select journaling in the jde.ini file. Journaling occurs in two instances:
-
A system call logs the parameter received and the APIs called.
-
During the interoperability event observer process, the kernel logs additional debugging information.
The logging is controlled with the LEVEL key in the [INTEROPERABILITY] section.
B.5.1 [INTEROPERABILITY]
These are some possible values for the LEVEL key:
| Key | Section | Description |
|---|---|---|
| LEVEL= | N/A | The system writes specified interoperability event data to the debug log file. You can specify one or more of the allowable logging settings. Separate multiple values with a comma. For example:
[INTEROPERABILITY] LEVEL=EVENTS,DATA Note: As with any logging operation, enabling any of these settings can impact performance and cause extensive amounts of data to be written. |
| N/A | EVENTS | Use this value to log the flow of events in the IEO kernel. Receiving event data and sending events are logged, but the values of the event data are not logged. This is the default level. If the LEVEL key is not present, it is identical to LEVEL= EVENTS. |
| N/A | DATA | Log values of the event data and flow of the events in the IEO kernel. This level also includes all data logged with the EVENTS switch. |
| N/A | PERF | Log statistics about the number of events received and the time period in which they are processed. |
| N/A | DOC | Outbound XML documents are written in the temporary file on disk. If the debug log is enabled, the document location is written in the debug log. The location of the document depends on the key value:
|
| N/A | TRACE | This switch traces execution of the IEO kernel and writes data in the debug log. Because of the large amount of data that is logged, use this level only for debugging purposes. |
Note:
The LEVEL=DOC setting is not affected by whether debug logs are enabled or disabled. All other values under the LEVEL key (for example, TRACE) are affected by the debug log enable or disable setting.You can also journal EVN documents by setting the SaveEVNDoc key in the [INTEROPERABILITY] section of the jde.ini file. SaveEVNDoc is similar to LEVEL=DOC but applies to the EVN kernel instead of the IEO kernel. The default value for SaveEVNDoc is zero (0), which means that EVN documents are not saved. To save EVN documents, change the value to one (1). EVN documents are saved to the directory where JDE logs and debug logs are written unless you specify a different directory. You can use TempFileDir to specify a directory.
B.5.2 [INTEROPERABILITY]
You can configure these settings to log documents:
SaveEVNDoc=1 TempFileDir=C:\XML_Documents
B.6 Configuring the jde.ini for Real-Time Events
To generate real-time events, these sections of the JD Edwards EnterpriseOne server jde.ini file must be configured:
-
[JDENET_KERNEL_DEF19]
-
[JDENET_KERNEL_DEF20]
-
[JDEITDRV]
-
[JDENET]
-
[INTEROPERABILITY]
Note:
The settings for the kernels, [JDEITDRV], and [JDENET] are defined in the Using Events - Classic section of the Interoperability Guide.
B.6.1 [INTEROPERABILITY]
Configure these settings:
SequenceTimeOut=XX XMLElementSkipNullOrZero=x
The SequenceTimeOut setting is for sequencing of volatile events. The default value is 10 seconds.
Null strings and zeros are trimmed from real-time events. You can clear this feature by entering a value of 0 (zero) for the XMLElementSkipNullOrZero settings.
B.7 Generating Real-Time Events
This section provides overview of real-time event generation, real-time event APIs, and example code for events, and discusses how to set up the OCM for real-time events.
B.7.1 Understanding Real-Time Event Generation
-
Contains one partial event. Single events are useful if the receiver requires that events be generated per system call. Can also be used with different event types.
-
Contains multiple partial events. Aggregate events are useful if the receiver requires a document that contains multiple events. For example, a supply chain solution might want to provide the complete sales order as one event that contains multiple partial events.
-
Contains only single events. Aggregate events are useful if the customer has multiple receivers, some that require single events and some that require a complete event that is similar to an aggregate event.
B.7.2 Real-Time Event APIs
The system APIs are able to determine whether a system call is from a server or client. These APIs are available for you to generate real-time events:
-
jdeIEO_EventInit()
-
jdeIEO_EventAdd()
-
jdeIEO_EventFinalize()
-
jdeIEO_CreateSingleEvent()
-
jdeIEO_IsEventTypeEnabled()
B.7.3 Example: Interoperability Event Interface Calls
This sample code illustrates how to create a single event:
-
Design the data structure to decide what values to provide to the real-time event.
typedef struct tagDSD55RTTEST { char szOrderCo[6]; char szBusinessUnit[13]; char szOrderType[3]; MATH_NUMERIC mnOrderNo; MATH_NUMERIC mnLineNo; JDEDATE jdRequestDate; char szItemNo[27]; char szDescription1[31]; MATH_NUMERIC mnQtyOrdered; MATH_NUMERIC mnUnitPrice; MATH_NUMERIC mnUnitCost; char szUserID[11]; } DSD55RTTEST, *LPDSD55RTTEST; -
Define the data structure object in the business function header file.
-
Modify the business function source to call jdeIEO_CreateSingleEvent.
JDEBFRTN(ID) JDEBFWINAPI RealTimeEventsTest (LPBHVRCOM lpBhvrCom, LPVOID lpVoid, LPDSD55REALTIME lpDS) { /* Define Data Structure Object */ DSD55RTTEST zRTTest = {0}; IEO_EVENT_RETURN eEventReturn = eEventCallSuccess; IEO_EVENT_ID szEventID ={0}; ()Populate required members /* Now call the API */ szEventID = jdeIEO_CreateSingleEvent { lpBhvrCom, "RealTimeEventsTest", "JDERTOUT", "SalesOrder", "D55RTTEST", &zRTTest, sizeof(zRTTest), 0, &eEventReturn }; /* Error in jdeFeedCallObjectEvent is not a critical error and should only be treated as a warning */ if( eEventReturn != eEventCallSuccess ) { /* LOG the Warning and return */ return ER_WARNING;
This sample code illustrates how to create an aggregate event:
DSD55RTTEST zD55TEST01 = {0};
DSD55RTTEST zD55TEST02 = {0};
DSD55RTTEST zD55TEST03 = {0};
IEO_EVENT_RETURN eEventReturn = eEventCallSuccess;
IEO_EVENT_ID szEventID;
szEventID = jdeIEO_EventInit (lpBhvrCom, eEventAggregate, "MyFunction1",
"JDESOOUT", "EventScope1", 0, &eEventReturn);
eEventReturn = jdeIEO_EventAdd (lpBhvrCom, szEventID, "MyFunction2", NULL,
"D55TEST01", &zD55TEST01, sizeof(zD55TEST01),0);
eEventReturn = jdeIEO_EventAdd (lpBhvrCom, szEventID, "MyFunction3", NULL,
"D55TEST02", &zD55TEST02, sizeof(zD55TEST02),0);
eEventReturn = jdeIEO_EventAdd (lpBhvrCom, szEventID, "MyFunction3", NULL,
"D55TEST03", &zD55TEST03, sizeof(zD55TEST03),0);
eEventReturn = jdeIEO_EventFinalize (lpBhvrCom, szEventID,"MyFunction4",0);
This sample code illustrates how to create a composite event:
IEO_EVENT_RETURN eEventReturn = 0;
IEO_EVENT_ID szEventID;
eEventReturn = eEventCallSuccess;
szEventID = jdeIEO_EventInit (lpBhvrCom, eEventComposite, "MyFunction1",
"JDESOOUT","EventScope1",0,&eEventReturn,0);
eEventReturn = jdeIEO_EventAdd ( lpBhvrCom, szEventID, "MyFunction2",
"SODOCBEGIN", "D55TEST01", &zD55TEST01, sizeof(zD55TEST01),0);
eEventReturn = jdeIEO_EventAdd ( lpBhvrCom, szEventID, "MyFunction3",
"SOITEMADD", "EventScope3", "D55TEST02", &zD55TEST02, sizeof(zD55TEST02),0);
eEventReturn = jdeIEO_EventFinalize (lpBhvrCom, szEventID, "MyFunction4",0);
Errors that are returned by the system calls might not be critical enough to stop the business process. The system flags non-critical errors as warnings and logs them in the log file. If the business function is on the server, the warning is logged in the CallObject kernel log. If the business function is on a client, the warning is logged in the client log file.
This sample code illustrates an XML file that shows a composite real-time event that consists of a call to the business function F4211FSEditLine on 12/31/2000, arriving about noon, with the real-time event generated at 12:00:01.000:
<?xml version='1.0' encoding='utf-8' ?>
<jdeResponse type='realTimeEvent' user='JDE1214225' session='1234.786321234'
role='*ALL' environment='XDEVNIS2'>
<header>
<eventVersion>1.0</eventVersion>
<type>JDESOOUT</type>
<scope>SalesOrder</scope>
<user>JDE1214225</user>
<application>P0101</application>
<version>XJDE101</version>
<sessionID>1234.786321234</sessionID>
<environment>XDEVNIS2</environment>
<host>HP9000B</host>
<eventID>HP9000B-1234-1231200012000100-JDE1214225-FFA123ECBBA123EC</eventID>
<date>12312000</date>
<time>120001000</time>
</header>
<body elementCount='1'>
<PartialEvent name='F4211FSEditLine' type='SOEDITLINE' executionOrder='1'
parameterCount='12'>
szOrderCo type='String'>JD Edwards</szOrderCo>
<szBusinessUnit type='String'>Mountain Region</szBusinessUnit>
<szOrderType type='String'>SO</szOrderType>
<mnOrderNo type='MATH_NUMERIC'>13209847</mnOrderNo>
<mnLineNo type='MATH_NUMERIC'>122</mnLineNo>
<jdRequestedDate type='Date'>12312000</jdRequestedDate>
<szItemNo type='String'12243234</szItemNo>
<szDescription type='String'>Bicycle</szDescription>
<mnQtyOrdered type='MATH_NUMERIC'>1</mnQtyOrdered>
<mnUnitPrice type='MATH_NUMERIC'>249.99</mnUnitPrice>
<mnUnitCost type='MATH_NUMERIC'>213.23</mnUnitCost>
<szUserID type='String'>JDE1214225</szUserID>
</PartialEvent>
</body>
</jdeResponse>
B.8 Setting Up the OCM for Real-Time Events
This section provides an overview about OCM for real-time events and discusses how to set up the OCM.
B.8.1 Understanding the OCM for Real-Time Events
You configure the Object Configuration Manager (OCM) so that the system call can find the IEO kernel. If the business function is mapped to a client, an error is returned to the client by the system call if the IEO kernel is not found. If the business function is mapped to the server, the error is logged in the Callobject kernel jde.log.
When you configure the OCM, include a specific environment and ensure that no two duplicate mappings are in active status at the same time.
If the OCM mapping is not correctly configured on the client, this message is written in the jde.log, and the event is not be generated:
RT0000011 jdeIEO_EventInit: Unable to find the server
If the OCM mapping is not correctly configured on the server, no error message is generated. The system call uses the local server as the location of the IEO kernel.
If the IEO kernel is not found on the machine that is configured in the OCM, this error might occur:
RT0000004 jdeIEO_EventInit: ReceiveMsg failed. Error = <error test>
B.8.2 Forms Used to Set Up OCM
| Form Name | FormID | Navigation | Usage |
|---|---|---|---|
| Machine Search and Select | W986110D | Enter OCM in the Fast Path Command Line. | Select the appropriate machine name. |
| Work With Object Mappings | W986110B | On Machine Search and Select, select the appropriate active environment. | Find and select the appropriate environment. |
| Object Mapping Revisions | W986110C | On Work With Object Mappings, select the appropriate active environment in the detail area. | Enter RTE in the Object Type field. |
B.8.3 Setting Up the OCM for Real-Time Events
Access the Object Mapping Revisions form.
- Environment Name
-
A name that uniquely identifies the environment.
- Object Name
-
The JD Edwards EnterpriseOne object that you want to map. To create a default map for all of an object type, enter the literal value DEFAULT into this field and then enter an object type into the Object Type field.
- Primary Data Source
-
The name that identifies the data source.
Data sources are the building blocks that you use to set up a JD Edwards EnterpriseOne configuration. Data sources define all of the required databases (where your tables reside) and all of the logic machines (where JD Edwards EnterpriseOne executes logic objects for your enterprise).
If JD Edwards EnterpriseOne cannot find your primary data source or cannot find the data item I your primary data source, it attempts to connect to your secondary data source.
- System Role
-
A profile that classifies users into groups for system security purposes. You use group profiles to give the members of a group access to specific programs.
On this form you can enter an individual user, a group name or the literal value *PUBLIC.
- Object Type
-
The type of object with which you are working. For real-time events, the object type is RTE. For XAPI events the object type is XAPI.
- Data Source Mode
-
Indicates whether to use the primary or secondary data source.
- Allow QBE
-
Use this flag to select row-level record locking for the data source.
You should have this flag turned on to help prevent database integrity issues.
JDEBASE middleware uses this flag to determine whether to use row-level record locking.