This chapter contains the following topics:
Oracle's JD Edwards EnterpriseOne XML solution supports well-formed XML documents. The XML solution supports both UTF-8 and UTF-16 Unicode standards for receiving information into JD Edwards EnterpriseOne. The XML solution supports UTF-8 Unicode standard for sending information from JD Edwards EnterpriseOne. The JD Edwards EnterpriseOne XML solution includes:
| XML Solution | Description |
|---|---|
| XML Transformation System (XTS) | Transforms an XML document that is not in the JD Edwards EnterpriseOne format into an XML document that can be processed by JD Edwards EnterpriseOne, and then transforms the response back to the original XML format. |
| XML Dispatch | Provides a single point of entry for all XML documents coming into JD Edwards EnterpriseOne and for responses. |
| XML CallObject | Enables you to call business functions. |
| XML Transaction | Enables you to use a predefined transaction type (such as JDEOPIN) to send information to or request information from JD Edwards EnterpriseOne. XML transaction uses interface table functionality. |
| XML List Kernel | Enables you to request and receive JD Edwards EnterpriseOne database information in chunks. |
| XML Service Kernel | Enables you to request events from one JD Edwards EnterpriseOne system and receive a response from another JD Edwards EnterpriseOne system. |
Some of the benefits of using XML include:
Scalable XML models that enable you to open multiple connections.
Ability to use JD Edwards EnterpriseOne messaging adapters, providing a reliable connection and acknowledging operations.
Exposure of business functions and interface tables.
Ability to aggregate business function calls into one document, which reduces network traffic.
Ability to manage session creation, validation, and tracking.
If you can create XML documents on the interoperability server, you can use XML for the interoperability solution.
For XML interoperability to function properly, you must add jar files to the classpath on the machine that is running XML requests. JD Edwards EnterpriseOne Tools Release 9.2 Update 4 requires a different set of jar files.
You can find the jar files in the <JD Edwards EnterpriseOne Windows client installation directory>system\classes folder.
XML JAR Files for Releases Prior to Tools Release 9.1 Update 4
If your system is prior to JD Edwards EnterpriseOne Tools Release 9.1 Update 4, add these jar files to the classpath on the machine that is running XML requests:
Base_JAR.jar
commons-httpclient-3.0.jar
commons-logging.jar
JdeNet.JAR.jar
jmxremote_optional.jar
jmxri.jar
ManagementAgent_JAR.jar
System_JAR.jar
xalan.jar
xerces.jar
xmlparserv2.jar
XML JAR Files for Tools Release 9.1 Update 4 and Later Releases
If you are using JD Edwards EnterpriseOne Tools Release 9.1 Update 4 or later release, add these jar files to the classpath on the machine that is running XML requests:
Base_JAR.jar
commons-logging.jar
httpclient.jar
httpcore.jar
JdeNet_JAR.jar
jmxremote_optional.jar
This section provides an overview of formatting XML documents for JD Edwards EnterpriseOne and discusses these elements:
Type Element
Establish Session
Expire Session
Terminate Session
Explicit Transaction
Implicit Transaction
Prepare/Commit/Rollback
Terminate Session
When you send an XML document to JD Edwards EnterpriseOne for processing, the document must be in the XML format that is defined by JD Edwards EnterpriseOne. After the document reaches the JD Edwards EnterpriseOne server, the system processes the document based on the document type. All XML documents must contain these elements:
One of these types:
jdeRequestType
jdeResponseType
Establish Session
Expire Session
Terminate Session
In addition, you can use these optional elements:
Explicit Transaction
Implicit Transaction
Prepare/Commit/Rollback
The type element, which can be jdeRequest or jdeResponse, is the root element for all request documents coming into the XML infrastructure. This element contains basic information about the execution environment. These attributes form the jdeRequest and jdeResponse type element:
| Attribute | Description |
|---|---|
| Type | Specifies the type of XML document request. Depending on the operation to be performed, the jdeRequest type can be one of the these:
The jdeResponse type indicates an XML document coming from another JD Edwards EnterpriseOne system. The operation for jdeResponse is realTimeEvent. Note: The xapicallmethod and realTimeEvent types are discussed in the Events section of this document. |
| User | Specifies the user name for user identification and validation. |
| Pwd | Specifies the user password for user identification and validation. |
| Role | Specifies the user role. If left blank the default value is *ALL |
| Environment | Specifies the system environment. |
| Session | Specifies the session ID. This attribute is optional. |
| Sessionidle | Specifies the session time-out time. This attribute is optional. |
You establish a session by setting the session attribute of the standard jdeRequest element. When the session attribute is an empty string, a new session is started. On the server, the SessionManager singleton class creates a new instance of a session object given the user name, password, and environment name. The session can be reused before it expires to avoid the overhead of session initialization. You can specify the session ID in the session attribute for an already established session in an earlier request.
<?xml version='1.0' ?> <jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' role='*ALL' session='' sessionidle='1800'> </jdeRequest>
Note:
If you do not want to start a new session, then remove the session=' ' tag.Session expiration is addressed by the sessionidle attribute of the standard jdeRequest element. This attribute, when given on a session creation request, specifies the amount of time in seconds that this session is allowed to be idle. If the SessionManager determines that a session has not had any requests processed in this amount of time, it terminates the session and frees all associated resources. The session idle default value is 30 minutes. The session idle time is defined in the XML document.
<?xml version='1.0'?> <jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' role='*ALL' session='' sessionidle='1800'> </jdeRequest>
Explicit database transactions are supported by another element, the startTransaction tag. The startTransaction tag specifies whether transactions are to be manually or automatically committed. The startTransaction tag element is an empty element, which means that all of the information is in the attributes.
<?xml version='1.0'?> <jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' role='*ALL' session=''> </jdeRequest>
An XML request is included in a transaction set when the name of a transaction set is referenced in its trans attribute. Implicit start transactions can be included in the request by specifying the name of a transaction set that has not previously been created. For an implicit start, the transaction set is a manual commit set.
<?xml version='1.0'?> <jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' role='*ALL' session=''> <callMethod name='myfunc' app='P42101' trans='t1'> <params> <param name='CostCtr'> 1001</param> </params> </callMethod> </jdeRequest>
Manual transaction sets can be committed or rolled back. As part of a two-phase commit, they can be prepared to commit. Prepare, commit, and rollback requests to the database are made by using the endTransaction element. The transaction set is identified by the trans attribute. The action attribute indicates the action to take on the transaction set. The value can be prepare, commit, or rollback. This element is always an empty element, as indicated by the forward slash.
It is recommended that you manage the session ID when doing manual commits and terminate the session after the transaction is complete.
<?xml version='1.0'?> <jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' role='*ALL' session='' <endTransaction trans='t1' action='commit'/> </jdeRequest>
Note:
If startTransaction and endTransaction are in separate documents, one of these scenarios occurs:The session attribute is not sent in the second document. In this case, the system uses the user ID, password, and environment to match the previous session.
The session number from the response of the first document is sent in the session attribute of the documents associated with the same transaction.
Session termination is done by submitting an XML document to explicitly terminate the session. You must specify the session to be terminated in the jdeRequest element tag.
<?xml version='1.0' ?> <jdeRequest type='callmethod' user='steve' pwd='xyz' environment='prod' role='*ALL' session=5665.931961929.454'> <endSession/> </jdeRequest>
In addition to ensuring that your XML documents have the required format elements (jdeRequest or jdeResponse Type, Establish Session, Expire Session, and Terminate Session), JD Edwards EnterpriseOne has standards for XML documents that are different from industry standards. Also, some special characters are reserved for XML and can't be used directly.
This section discusses:
Decimal and comma separators.
Data usage.
Industry standards for special characters.
JD Edwards EnterpriseOne uses the decimal and thousands separators differently than XML industry standards. The decimal and thousands separators do not depend on use profile settings, jde.ini settings, or regional settings for the computer. When you write XML documents to interface with JD Edwards EnterpriseOne, you must always use the decimal character (.) (period) as a decimal separator, and a comma (,) as a thousands separator. The purpose of the separator standards is to achieve consistent interoperability policy and to prevent data corruption.
Different components of the XML foundation use different format codes and APIs to format these dates:
to XML date
from XML date
to JDEDATE
from JDEDATE
This table explains the formats that are used by each XML component supported by JD Edwards EnterpriseOne:
| Component | Inbound Format | Inbound Outcome | Outbound Format | Outbound Outcome |
|---|---|---|---|---|
| XMLCallObject | F | YYYYMD | ESOSA | YYYY/MM/DD |
| XMLTransaction | F* | User Preference | ESOSA | YYYY/MM/DD |
| XMLList | B* | User Preference | NULL | User Preference |
* Component ignores the format code
In XML, some special characters are reserved for internal use, and to use these characters in data, you must replace them with entity or numeric references. This table shows the special characters that are reserved for XML along with the entity and numeric references that enable you to use a special character in your XML documents:
| Character Name | Character | Entity Reference | Numeric Reference |
|---|---|---|---|
| Ampersand | & | & | & |
| Left angle bracket (less than) | < | < | < |
| Right angle bracket (greater than) | > | > | > |
| Straight quotation mark | " | " | " |
| Apostrophe | ' | ' | ' |
| Percent | % | Not Applicable | % |
Another way to use special characters in your XML documents is to use the CDATA section. Any text inside a CDATA section is ignored by the parser.
Before you can use XML with JD Edwards EnterpriseOne, you must ensure that the ICU_DATA system environment variable is correctly defined on your JD Edwards EnterpriseOne system. If the ICU_DATA variable is not correctly defined, JD Edwards EnterpriseOne produces this error message:
The default Unicode converter could not be found within the jdenet_n.log on the OneWorld Enterprise Server.
For JD Edwards EnterpriseOne, the ICU conversion table, icu_data.dat, is generally located in system/locale/xml. Use the appropriate setting for your platform.
This section discusses:
UNIX
IBM i
Microsoft Windows
For UNIX systems, the ICU_DATA path is based on the ICU_DATA environment variable. The UNIX JD Edwards EnterpriseOne user login script sets the ICU_DATA environment variable to the directory location of the ICU resource file, incudata.dat. If the user login script does not set the ICU_DATA environment variable, you must define the ICU_DATA variable with a trailing slash, for example:
Export ICU_DATA=$SYSTEM/locale/xml/
Where $SYSTEM represents your JD Edwards EnterpriseOne install directory.
To support the loading of the JVM, verify the environment variable configuration for your platform.
Verify these environment variable configurations for an AIX platform:
export LD_LIBRARY_PATH=$SYSTEM/jre/1.6/lib/bin:
$SYSTEM/jre/1.6/lib/bin/classic:${LD_LIBRARY_PATH}
export LIBPATH=$SYSTEM/jre/1.6/lib/bin:$SYSTEM/jre/1.6/lib/bin/classic:
${LIBPATH}
export SHLIB_PATH=$SYSTEM/jre/1.6/lib/bin:
$SYSTEM/jre/1.6/lib/bin/classic:${SHLIB_PATH}
Verify these environment variable configurations for a Solaris platform:
export LD_LIBRARY_PATH=$SYSTEM/jre/1.6/lib/sparc/server:
$SYSTEM/jre/1.6/lib/sparc:${LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.6/lib/sparc/SERVER:
$SYSTEM/jre/1.6/lib/sparc:${SHLIB_PATH}
Note:
Make sure that the server directory is first. The sparc directory has a libjvm.so just like the server directory, and the libjvm.so in the server directory is the directory you want to use.Verify these environment variable configurations for a Linux platform:
export LD_LIBRARY_PATH=$SYSTEM/jre/1.6/lib/i386/server:
$SYSTEM/jre/1.6/lib/i386L:{LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.6/lib/i386/server:
$SYSTEM/jre/1.6/lib/i386:S{SHLIB_PATH}
For IBM i systems, the ICU_DATA path is set when the ICU 1.6 conversion function is first called by the system. The system looks up Data Area BUILD_VER in the system library for the System Directory setting. For example:
The system appends locale/xml to the path specified in the BUILD_VER, and then uses this path as the ICU_DATA path. You must ensure the BUILD_VER data area is properly set to reflect the system directory setting.
For Microsoft Windows systems, the ICU_DATA path is set when the ICU 1.6 conversion function is first called. This logic is used on Microsoft Windows:
The system looks up the environment variable JDE_B9_ICU_DATA. If this environment is found, it becomes the path for the conversion files.
The system looks for this section in the jde.ini file:
[XML]
ICUPath=<<install>>/system/locale/xml
If the ICUPath setting is found, it becomes the path for the conversion files.
If the system cannot find the ICUPath setting in the jde.ini file, the ICU_Path is:
EXECUTABLE_DIRECTORY/./system/locale/xml
The EXECUTABLE_DIRECTORY must be <<install>>/system/bin32.
Based on this logic, you usually do not need to set the JDE_B9_ICU_DATA ENVIRONMENT variable or the jde.ini file. You need to set the jde.ini ICUPath only when the location of the icudata.dat is different from system/locale/xml.
Note:
The JD Edwards EnterpriseOne client install sets the environment variable JDE_B9_ICU_DATA.If one or more XML kernels are not working properly, use these troubleshooting guidelines to ensure that your system is set up correctly:
Check the kernel definition in the server jde.ini file.
Also check that the library name is correct for the platform on which you are running. Check the entry function name.
Check that the kernel is allowed to start.
Check the maxNumberOfProcesses and numberOfAutoStartProcesses values for the kernel in the server jde.ini file. It is not necessary to auto start kernels. To work with a particular kernel, the allowed number of processes should be one or more.
If you have a large number of simultaneous requests that are made to a particular kernel type, increase the number of allowed processes for that kernel.
This will not only reduce the turnaround time for requests but will also eliminate any Queue Full errors.
If you are using XMLList kernel, check that the LREngine section is correctly set up in the server jde.ini file and that the specified path exists.
Also, check that the JD Edwards EnterpriseOne user has write permission to this location.
Check that the XML document is a well-formed XML document.
To do this, use any XML editor or open the document in Microsoft Internet Explorer and check for errors.
Check that the root of the input XML document is jdeRequest.
All input XML documents should have jdeRequest as their root element.
Check that valid user ID, password, and environment are provided in the XML document.
Check that the request type in the XML document is correct. The allowed request types are callmethod, list, and trans for XMLCallObject, XMLList, and XMLTransaction kernels, respectively.