Skip Headers
JD Edwards EnterpriseOne Tools Interoperability Guide
Release 8.98 Update 4

Part Number E14711-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Understanding XML

This chapter contains the following topics:

5.1 XML and JD Edwards EnterpriseOne

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.
XMLDispatch 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:

If you can create XML documents on the interoperability server, you can use XML for the interoperability solution.

5.2 XML JAR Files

For XML interoperability to function properly, you must add the following jar files to the classpath on the machine that is running XML requests:

You can find these jar files in the <JD Edwards EnterpriseOne Windows client installation directory>system\classes folder.

5.3 XML Document Format

This section provides an overview of formatting XML documents for JD Edwards EnterpriseOne and discusses these elements:

5.3.1 Formatting XML Documents

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

5.3.2 Type Element

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:
  • Callmethod

  • List

  • Trans

  • xapicallmethod

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.

5.3.3 Establish Session

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. This example is for starting a new session.

5.3.4 Expire Session

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>

5.3.5 Explicit Transaction

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>

5.3.6 Implicit Transaction

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 will be 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>

5.3.7 Prepare/Commit/Rollback

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.

5.3.8 Terminate Session

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>

5.4 XML Standards

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:

5.4.1 Decimal and Comma Separators

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.

5.4.2 Date Usage

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

5.4.3 Industry Standards for Special Characters

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 & &amp; &#38;
Left angle bracket (less than) < &lt; &#60;
Right angle bracket (greater than) > &gt; &#62;
Straight quotation mark " &quot; &#34;
Apostrophe ' &apos; &#39;
Percent % Not Applicable &#37;

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.

5.5 System Environment Configuration

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:

5.5.1 UNIX

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.

5.5.1.1 HPUX

Verify these environment variable configurations for a HPUX platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/PA_RISC/server:
$SYSTEM/jre/1.4/lib/PA_
RISC:${LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/PA_RISC/server:
$SYSTEM/jre/1.4/lib/PA_RISC:${SHLIB_PATH}

5.5.1.2 AIX

Verify these environment variable configurations for an AIX platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/bin:
$SYSTEM/jre/1.4/lib/bin/classic:${LD_LIBRARY_PATH}
export LIBPATH=$SYSTEM/jre/1.4/lib/bin:$SYSTEM/jre/1.4/lib/bin/classic:
${LIBPATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/bin:
$SYSTEM/jre/1.4/lib/bin/classic:${SHLIB_PATH}

5.5.1.3 SUN

Verify these environment variable configurations for a SUN platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/sparc/server:
$SYSTEM/jre/1.4/lib/sparc:${LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/sparc/SERVER:
$SYSTEM/jre/1.4/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.

5.5.1.4 LINUX

Verify these environment variable configurations for a LINUX platform:

export LD_LIBRARY_PATH=$SYSTEM/jre/1.4/lib/i386/server:
$SYSTEM/jre/1.4/lib/i386L:{LD_LIBRARY_PATH}
export SHLIB_PATH=$SYSTEM/jre/1.4/lib/i386/server:
$SYSTEM/jre/1.4/lib/i386:S{SHLIB_PATH}

5.5.2 IBM i

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:

System Directory: B9_S

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.

5.5.3 WIN32

For WIN32 systems, the ICU_DATA path is set when the ICU 1.6 conversion function is first called. This logic is used on WIN32:

  1. The system looks up the environment variable JDE_B9_ICU_DATA. If this environment is found, it becomes the path for the conversion files.

  2. 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.

  3. 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.

5.6 XML Kernel Troubleshooting

If one or more XML kernels are not working properly, use these troubleshooting guidelines to ensure that your system is set up correctly: