This chapter covers the following topics:
There are ten setup steps for the XML Gateway as shown in the following table:
Step | Completed | Task |
---|---|---|
1 | Define System Profile Options | |
2 | Assign XML Gateway Responsibility | |
3 | Define the utl_file_dir parameters (performed by a DBA) | |
4 | Define Hubs | |
5 | Define XML Standards | |
6 | Define Transactions | |
7 | Define Lookup Values | |
8 | Define Trading Partners | |
9 | Set up Trading Partner Code Conversion | |
10 | Define Standard Code Conversion |
Note: Additional setup steps are required for Web services. See the Web Services chapter for details.
There are seven forms in the XML Gateway that you will use to complete the setup steps:
The XML Gateway uses profile options to define the following for your system:
The directory path for XML messages and log files
The directory path for XSLT style sheets
The XML Gateway System Administrator's e-mail address
The sender's information system
The time zone for the database server
The maximum size an outbound document may reach before validating whether parsing should be continued
The maximum memory available for the database session running the Java portion of the XML transformation
The option of either purging all XML Gateway data along with workflow data or only purging workflow data
The continuation of parsing XML document if an outbound document reaches its maximum size
The Trading Partner user security feature for inbound transactions
To define these profile options, you must sign on to Oracle E-Business Suite as the System Administrator responsibility. Navigate to the System Profile Values form using the path (N) Profile > System.
For additional information on setting profile options and profile categories, see the Oracle E-Business Suite System Administrator's Guide - Maintenance.
The following table lists the XML Gateway system profile options:
Profile Option | Description | Category | Required | Default Value |
---|---|---|---|---|
ECX: Log File Path | Log File Path where the XML messages and runtime log are stored | Deployment | YES | None |
ECX: XSLT File Path | XSLT Path where XSLT style sheets are stored | Deployment | YES | None |
ECX: System Administrator Email Address | XML Gateway System Administrator e-mail address | Administrator Setup | YES | None |
ECX: OAG_LOGICALID | Identifier for Sender's Information System | Administrator Setup | NO | None |
ECX: Server Time Zone | The time zone in which the database server is running. See Important below. | Administrator Setup | YES | Null |
ECX: Maximum XML Size | This profile option specifies the maximum size of an outbound XML document (in bytes). For more information on how this profile option works, see Note below. |
XML Processing | NO | 2 MB |
ECX: XML Validate Flag | This profile option specifies whether an outbound document should continue to be parsed by the engine after the maximum size defined in the 'ECX: Maximum XML Size' profile option has been reached. This profile option works together with the 'ECX: Maximum XML Size' profile option. For more information on how this profile option works and how to disable the XML parsing and validation, see Note below. |
XML Processing | NO | Y |
Enable User Security | This profile option controls whether an inbound transaction can be enabled based on the value set in the profile option and the association between a user and Trading Partner. | Security/Compatibility | NO | NO |
ECX: Notification Timeout | This profile option sets the timeout period for a notification that is waiting for a response. If the notification timeout value is exceeded, XML Gateway execution engine will automatically reprocess the erred transaction if it does not exceed the maximum retries limit. | XML Processing | NO | NO |
ECX: Maximum Retries | This profile option governs the number of times that XML Gateway execution engine will automatically reprocess the erred transaction after the notification timeout period. | XML Processing | NO | NO |
ECX: Purge ECX data with WF | This profile controls purging of XML Gateway data when Purge Obsolete Workflow Runtime Data concurrent program is submitted to purge XML Gateway transactions attached to workflow.
See Purge Obsolete Workflow Runtime Data Concurrent Program. |
Exportable | NO | Y |
ECX: Java Memory Limit | This profile option allows you to increase the maximum memory (in megabytes) available for the database session running the Java portion of the XML transformation at the site level.
Note: With the increase of maximum memory while processing XML messages, it not only helps avoid Java out of memory errors (Java heap space exception), but also helps smooth XSLT transformation and XML message processing. |
XML Processing/Exportable | NO | 1024 MB
Note: It can range from 256 MB up to all the available database server memory. |
Important: The valid values for ECX: Server Time Zone are listed in Appendix E. If this profile option is not set, the time zone ID will default to Greenwich Mean Time (GMT).
Note: While parsing the outbound document, XML engine will check the following two profile options to determine if the outbound document will continue to be parsed:
The 'ECX: Maximum XML Size' profile value to obtain the maximum size that an outbound XML document should be parsed.
If the maximum size is not set, the default maximum value will be used.
The 'ECX: XML Validate Flag' profile value only if the outbound document size is greater than the maximum size.
If the document is less than the maximum size, then the parsing will be continued regardless of the profile value set in the 'ECX: XML Validate Flag'.
If the document is greater than the maximum size and the 'ECX: XML Validate Flag' profile value is also set to 'Y', then the parsing will be continued.
For example, while parsing the outbound document, if an outbound XML document has size greater than the maximum 2MB, then the 'ECX: XML Validate Flag' profile value will be checked. If the validate flag is also set to 'Y', then the document will continue to be parsed. However, if the document reaches the maximum size, but the validate flag is set to 'N', then the parsing will not be continued.
Disabling XML Parsing and Validation: Because the 'ECX: XML Validate Flag' profile option works together with the 'ECX: Maximum XML Size' profile option, to disable XML parsing and validation for outbound messages, you not only need to set the 'ECX: XML Validate Flag' profile value to 'N', but also need to set the 'ECX: Maximum XML Size' profile to a value that is low enough so that your outbound document size can easily surpass it. This way, when the document size is greater than the maximum size you defined, and you have the 'ECX: XML Validate Flag' profile set to 'N', then the parsing and validation will be disabled. The XML engine will not parse the document and perform the XSL transformation.
Setting the 'ECX: XML Validate Flag' profile value to anything other than 'Y' will turn off parser validation for a document once the maximum size has been parsed. Turning off the validation avoids Out of Memory errors for large documents. If validation is turned off, the XSLT Transformation action cannot be performed. For more information on the XSLT Transformation action, see perform_xslt_transformation.
For additional information on setting profile options and profile categories, see the Oracle E-Business Suite System Administrator's Guide - Maintenance.
Use the System Administrator responsibility to assign the Oracle XML Gateway responsibility to a user to access the Oracle XML Gateway database and forms. Use standard procedures to assign the responsibility.
For additional information on defining responsibilities, see the Oracle E-Business Suite System Administrator's Guide - Security.
Perform this step in cooperation with a Database Administrator (DBA).
To use Oracle XML Gateway, you must first create directories where the XML message process log and XSLT style sheets will be stored. Oracle XML Gateway uses the UTL_FILE package to read and write to the server.
UTL_FILE can only write to accessible directories. The directories are defined by the utl_file_dir parameter in the init<SID>.ora file. This file is usually found in the $ORACLE_HOME/dbs directory. Within this file, each accessible directory is indicated by a line such as
utl_file_dir=<directory_name>
The specification of directory_name will vary, depending on the operating system. If the operating system is case-sensitive, then directory_name is case sensitive.
The value for directory_name must be a physical directory. It cannot be a variable, a logical, or an alias. In addition, the value for directory_name must match the value defined in the Oracle XML Gateway profile for ECX_UTL_LOG_DIR File Path (ECX: Log File Path) and ECX_UTL_XSLT_DIR File Path (ECX: XSLT File Path).
Refer to Define Profile System Values for details.
Unix Operating System
The following is an example of an entry for a UNIX operating system:
utl_file_dir=/d1/XML/logs/d1/XML/xslt
In addition to this form of database security, operating system security must also be considered. The file I/O operations performed with UTL_FILE will be done by the Oracle user (the Oracle user is the owner of the files that are used to run the database, and also the owner of the processes that make up a database instance). Consequently, the Oracle user has to have operating system privileges to read from and write to all of the accessible directories. If the Oracle user does not have privileges for an accessible directory, then any operations in that directory will be prohibited by the operating system.
To ensure that operating system security allows the Oracle user to create, delete, rename, read, and write files in the specified directories, the DBA must grant directory and file access privileges by issuing the CHMOD 777 command at the operating system level. This is a UNIX example only, so use appropriate operating system commands for your environment.
The Oracle instance must be brought down and back up for the changes in the init<SID>.ora file to be effective.
Before defining a hub, you must first complete these setup steps:
Define the utl_file_dir parameters (performed by a DBA)
Navigate to the Hub Definitions form from the XML Gateway Responsibility by selecting Setup > Define Hubs.
A hub is an integration point within your network (either your intranet or the internet). Hubs are typically used to route documents to and from trading partners. Oracle Exchange is an example of a hub. You may also decide to create a private hub within your intranet through which all your ERP systems communicate.
The Hub Definitions form is used to define the hub and the authorized users conducting business via the hub. The hub users entered in this form will appear on the Trading Partner Setup form.
Enter the Hub name.
Protocol Type is the communication protocol associated with the hub, such as SMTP or HTTP. Select a value from the seeded list of values. The description for the protocol type is displayed.
When protocol type is HTTP or HTTPS, protocol address is prompted.
Protocol Address is the complete URL (including service/servlet) where the Transport Agent will attempt to post the XML Document.
If the Protocol type is SMTP, the protocol address is an e-mail address.
Enter the user name of the trading partner conducting business via the hub.
Enter the password for this user. The encrypted password is stored in the database. The password is not echoed when it is entered. You will be prompted on the same field to confirm the password.
Enter the hub entity code for this user.
Hub Entity Code has the same function as the Source Trading Partner Location Code in the Trading Partner Setup form. It is the code found in the XML envelope to identify the source of the message.
If you are sending and receiving messages from a trading partner, you will have a mixture of your location codes and your trading partner's location codes depending on the direction of the message. For example, if you are sending messages out, the Source Trading Partner Location Code is your location code because you are the source of the XML message. If you are receiving messages, the Source Trading Partner Location Code is your trading partner's location code because they are the source of the XML message.
This code is examined for inbound messages during Trading Partner validation. When placed on an outbound message, the recipient will validate it as a valid source location code.
The Hub Entity Code is placed in the PARTY ID field in the XML Gateway envelope.
Before defining XML standards, you must first complete these setup steps:
Define the utl_file_dir parameters (performed by a DBA)
Navigate to the Define XML Standards form from the XML Gateway Responsibility by selecting Setup > Define XML Standards.
This form defines standards bodies for XML messages, such as OAG.
The Standard Code entries made in this form will appear in a list of values for the Standard Code field in the following forms:
Trading Partner Code Conversion form (accessed through the Trading Partner Setup form)
The Define Transactions form identifies the creating organization of the DTD, and hence, the XML message structure. The values entered in the Define XML Standards form will be the list of values for the Standard Code field in the Define Transactions form.
In the Trading Partner Code Conversion form and the Standard Code Conversion form, this value is used as part of the search key to access the code conversion tables.
Standard Code will also be the default standard code used in Standard Code Conversion table searches, when the Standard Code is assigned to the entries in the Define Transactions form.
This field is the name or code for the standard's body for the XML messages.
Only XML Standards are entered in this form with the exception of the value UNIVERSAL. The seeded value UNIVERSAL is needed for the Standard Code Conversion form to identify universally used codes, such as ISO codes.
Standard Type is any appropriate value that you choose.
Enter a description of the standard.
Navigate to the Define Transactions form from the XML Gateway Responsibility by selecting Setup > Define Transactions.
Use the Define Transactions form to define the transactions that will be used by the XML Gateway Execution Engine. You will then associate these transactions with a trading partner in the Trading Partner Setup form.
The Define Transactions form provides the following:
A cross-reference between the external transaction identifiers and the internal Oracle transaction identifiers.
Identification of the queue from which to retrieve inbound messages
This form provides a cross-reference between internal Oracle transaction identifiers, represented by the Transaction Type and Transaction Subtype, and External Transaction Types and External Transaction Subtypes.
Note: The data element pair of External Transaction Type and External Transaction Subtype, and the data element pair of Transaction Type and Transaction Subtype are not a one-to-one cross-reference by similar data element names. It is the combination of each pair that is significant to identify the external representation of the XML message, or the internal representation to identify the transaction to the Oracle E-Business Suite.
For example: The following is an inbound message with a Party Type of "CUSTOMER": OAG PROCESS_INVOICE_003. The message has the External Transaction Type "PROCESS" and External Transaction Subtype "INVOICE." The inbound direction is determined by the XML Gateway.
The External Transaction Type "PROCESS" and External Transaction Subtype "INVOICE" will be matched to Transaction Type and Transaction Subtype equal to AP and INI as they are defined in the Define Transactions form. For this trading partner, the message map defines on which tables in Oracle Payables to place the inbound data.
Another example is an outbound message with a Party Type of "SUPPLIER":
Invoice transaction from Oracle Receivables has the Transaction Type "AR" and the Transaction Subtype "INO." The outbound direction is determined by the XML Gateway.
This Transaction Type and Transaction Subtype will be matched to the External Transaction Type "INVOICE" and External Transaction Subtype "PROCESS" as defined in the Define Transactions form for the specified trading partner. For this trading partner, the message map identifies what data to extract from Oracle Receivables.
The Party Type, Transaction Type, and Transaction Subtype are key codes used by Oracle E-Business Suite to integrate with the Workflow Business Event System (BES) to trigger message creation or message consumption.
Different queues can be defined for various transactions from the application, or for XML messages to be transmitted. The queue names are assigned to the transactions via this form.
See Message Queues.
Party Type defines the type of trading partner, such as Supplier, Customer, Bank, or internal locations (such as warehouses). Select a value from the list of values.
Transaction Type is the product short name for the base Oracle E-Business Suite application associated with the transaction, such as "AR" for Oracle Receivables. Refer to Transaction Type and Transaction Subtype Naming Conventions.
If you are using OAG standards, refer to Setting VERB and NOUN in OAG Standards.
Transaction Subtype is a code for a particular transaction within the application specified by the Transaction Type. The last position of the code represents the direction of the transaction: "I" for inbound, "O" for outbound.
See Transaction Type and Transaction Subtype Naming Conventions.
The combination of the Transaction Type and the Transaction Subtype identifies an Oracle transaction with which to associate this message. This data will appear on the Trading Partner Setup form.
If you are using OAG standards, refer to Setting VERB and NOUN in OAG Standards.
Enter a description for the transaction.
You can optionally enter a transaction owner's user name. A transaction owner is considered as an expert for a specified transaction type defined in this form.
When an error occurs during a transaction, in addition to the XML Gateway system administrator for system or process errors and Trading Partner contact for data errors, Oracle Workflow can send a notification to a transaction owner if it is specified here based on the transaction type of an erred inbound transaction. For example, if an inbound transaction error occurs in Purchasing transaction type, then the transaction owner of the Purchasing if defined here will receive a notification in addition to the XML Gateway system administrator or Trading Partner contact depending on the error type.
When notifications are sent to the XML Gateway system administrator and the transaction owner if specified, both of them can take actions in response to the error notifications if necessary. See: XML Gateway Error Processing Item Type.
The XML standard to be used for this transaction. The Standard Codes are set up in the Define XML Standards form. Choose the code from the list of values.
Direction indicates if the message is inbound or outbound. Select "IN" for inbound messages, or "OUT" for outbound messages from the list of values.
External Transaction Type is the primary external identifier for the XML message.
The combination of the External Transaction Type and the External Transaction Subtype should cross-reference this message to the Oracle internal transaction identified by the Transaction Type and the Transaction Subtype.
External Transaction Subtype is the secondary external identifier for the XML message.
The combination of the External Transaction Type and the External Transaction Subtype should cross-reference this message to the Oracle internal transaction identified by the Transaction Type and the Transaction Subtype.
A queue is a table in a database where transactions are staged for processing. Default queues are defined during installation. Select a queue from the list of values.
The field is disabled for outbound messages.
See Message Queues.
Note: Only queues with a prefix of ECX will display in the list of values.
Naming conventions for Transaction Type and Transaction Subtype are necessary to facilitate the reading of audit trails and for troubleshooting across applications.
The Transaction Type and Transaction Subtype codes should not focus on naming conventions based on the standard XML message that is implemented. A given transaction from an application may be mapped to several XML standards based on the trading partner agreements, likewise for inbound messages.
The following naming conventions are recommended:
The Transaction Type is the product short name for the base Oracle E-Business Suite application. Examples of Oracle E-Business Suite application product short names are shown in the following table:
Transaction Type | Application |
---|---|
AP | Payables |
AR | Receivables |
OM | Order Management |
PO | Purchasing |
SS | Supplier Scheduling |
RLM | Release Management |
CUSTOM | (for user-defined messages) |
The Transaction Subtype is a code for a particular transaction within the application specified by the Transaction Type. The last position of the subtype code represents the direction of the transaction: "I" for inbound, "O" for outbound.
The naming convention is XXXXI or XXXXO where XXXX is significant to the application and its function, such as invoicing to Receivables and Payables.
For custom transactions, add a prefix to distinguish custom transactions from the Oracle supplied transactions.
The table below lists common combinations of Transaction Type and Transaction Subtype:
Transaction Type (Application) | Transaction Subtype (Transaction) | Transaction Type's Processing Application | Transaction Type's Processing Application (Transaction Code plus Direction) |
---|---|---|---|
PO | POCO | Purchasing | Purchase Order Change, Outbound |
PO | POO | Purchasing | Purchase Order, Outbound |
PO | POAI | Purchasing | Purchase Order Acknowledgment, Inbound |
OM | POI | Order Management | Purchase Order, Inbound |
OM | POCI | Order Management | Purchase Order Change, Inbound |
OM | POAO | Order Management | Purchase Order Acknowledgment, Outbound |
OM | POCAO | Order Management | Purchase Order Change Acknowledgment, Outbound |
AR | INO | Receivables | Invoices, Outbound |
AP | INI | Payables | Invoices, Inbound |
The actual transaction detail is therefore recognized by its unique combination of the Transaction Type and Transaction Subtype. The Transaction Subtype does not have to be unique across applications, but only within the application specified by the Transaction Type.
Consequently, both the Purchasing and the Order Management application can use the same Transaction Subtype (for example, POI) because they may both import some type of purchase order. For example, Order Management will load orders from its customers; Purchasing may load from another purchasing application.
If different database views are used to extract different types of transaction data, such as a blanket order versus a standard order, or different XML messages are needed for transactions such as a blanket order versus a standard order, then you can create different message maps using the Message Designer. You may also need to define different Transaction Subtypes to distinguish between such transactions in the Transaction setup.
When appropriate, a suffix can be attached to the base Transaction Subtype following the XXXXI or XXXXO naming convention to further distinguish a transaction in the XML Gateway. For queries in a form, it is recommended to keep the same base Transaction Subtype XXXXI or XXXXO, so the Transaction Subtypes will follow each other in queries.
The suffix naming convention is therefore XXXXI-yyyy and XXXXO-yyyy where yyyy is the suffix.
The following table illustrates the Transaction Subtype naming convention using a suffix:
Transaction Type (Application) | Transaction Subtype (Transaction) | Transaction Type's Processing Application | Transaction Type's Processing Application (Transaction Code plus Direction) |
---|---|---|---|
PO | POO-BLK | Purchasing | Blanket Purchase Order, Outbound |
PO | POO-REL | Purchasing | Purchase Order Release, Outbound |
PO | POO-STD | Purchasing | Standard Purchase Order, Outbound |
For example in a Purchasing application, all types of outbound purchase orders can be initiated under the general subtype POO with qualifiers for the various types of purchase orders such as blanket, standard, and release. Their subtype codes can be recognized as POO-BLK, POO-STD, and POO-REL respectively by the process. Avoid using long suffixes such as -BLANKET, -STANDARD, and -RELEASE to keep the naming convention simple. This sample is for illustration only.
The following topic discusses sources of data for the OAG CNTROLAREA.
The VERB and NOUN are key values required in the OAG CNTROLAREA data type. XML Gateway provides a database view that provides key data from the transaction table, while the attribute values are default values from the DTD used to create the outbound message map.
The purpose of the database view is to populate the VERB and NOUN elements illustrated below.
The Verb and Noun in OAG's CNTROLAREA
<NOUN value = "INVOICE"> INVOICE </NOUN>
<VERB value = "PROCESS"> PROCESS </VERB>
When the External Transaction Type and External Transaction Subtype are entered into the transaction table through the Define Transactions form, they can be mapped to the NOUN and VERB value fields respectively by using the database view ECX_OAG_CONTROLAREA_TP_V (formerly ECX_OAG_CONTROLAREA_V). See Transaction Map - Element Mapping.
Note: The ECX_OAG_CONTROLAREA_TP_V view is an upgraded version of the ECX_OAG_CONTROLAREA_V view. Oracle XML Gateway supports both versions of the database view. For a detailed description of the differences, see the Note, in the Message Designer chapter.
Important: Within the OAG CNTROLAREA, the sequence of fields is VERB then NOUN in the message. In the Define Transactions form, the sequence of fields is NOUN in the External Transaction Type, then VERB in the External Transaction Subtype. Be careful not to reverse the order of the data.
To navigate to the Oracle XML Gateway Lookups form from the XML Gateway Responsibility select Setup > Define Lookup Values.
The Oracle XML Gateway Lookups form allows both entry and display of seeded data. This is a standard Oracle Application Object Library form.
Once a Type is selected in the upper section, its seeded values are displayed in the Lookup Details section of the form.
Type is the key code for the element stored in the seeded table.
The XML Gateway seeded lookup types are listed in the following table:
Type | Description | Sample Values |
---|---|---|
COMM_METHOD | Communications Method | HTTP, HTTP-ATTCH, HTTP-OXTA, HTTP-WM, HTTPS, HTTPS-ATTCH, HTTPS-OMB, HTTPS-OXTA, HTTPS-WM, IAS, ITG03, SMTP, OTAH-ATCH, OTAHS-ATCH, NONE, SOAP, JMS |
CONFIRMATION_CODE | Confirmation Code | 0, 1, 2 |
DOCUMENT | Documents/Transactions | CBODI and CBODO are seeded by Oracle XML Gateway. CBODI is OAG's inbound confirmation. CBODO is OAG's outbound confirmation. |
MESSAGE_STANDARD | XML Message Standard | OAG, ORCL, RN, UNIVERSAL, PESC |
MESSAGE_TYPE | Message Type | XML, EDI, FF (for flat file) |
PARTY_TYPE | Party Types | B (for bank), C (for customer), S (for supplier), I (for internal location), E for Exchange, CARRIER (for Carrier) |
TRANSACTION_CODE | Transaction Code | CBOD for confirmation BOD is the XML Gateway seeded transaction code. |
User name is defined by the user when data is entered.
The text name for the application responsible for this Type.
Description of the Type.
The Access Level restricts changes that are possible to a lookup type. The possible levels are:
System - No changes to the lookup codes are allowed.
Extensible - New lookup codes can be added. However, you cannot modify seeded lookup codes.
User - You can change any lookup code.
The seeded code for the lookup.
The meaning of the lookup code.
Description of the lookup code.
Not used.
The starting effective date for the lookup code.
The expiration date for the lookup code. The ending date is optional.
Check the box if the Code is enabled. Remove the check to disable the Code.
Navigate to the Define Trading Partner Setup form from the XML Gateway Responsibility by selecting Setup > Define Trading Partners.
The Trading Partner Setup form is used to:
Set up trading partners for multiple operating units.
Enable messages for the trading partner by identifying the internal and external transaction type and transaction subtype codes, and the XML standard associated with the message.
Access the Trading Partner User Setup form.
Access the Trading Partner Code Conversion form.
Select a message map for the trading partner.
Identify the communications protocol and address for a message. Optionally, the user can be selected from a hub.
For example, if JMS messages are used in the transactions, then you must select JMS as the Protocol Type and appropriate JMS queues in the Protocol Address fields.
This is the component that will enable a message to be processed through the XML Gateway engine. In the XML Gateway, the term "Trading Partner" refers to an entity such as a customer, supplier, bank branch, or internal locations at a particular address with which you exchange messages. Since a given entity may have several locations, you must define one Trading Partner for each customer address, supplier site, or bank branch as required for processing transactions by the Oracle XML Gateway.
During message processing, Trading Partner data is used to:
Link a particular address location in Oracle E-Business Suite to the Trading Partner definition in the Gateway.
Provide a means of telling the Execution Engine which Trading Partner message map to use.
Enable specific transactions for Trading Partners.
Determine how to deliver the message.
This form defines the parameters for the Trading Partner setup. The setup includes the identification of the operating unit, trading partner site, the messages enabled for that site, and the delivery mechanism.
The Trading Partner Setup form requires an entry for each Transaction Type and Transaction Subtype associated with this trading partner.
Trading Partners for Multiple Organizations
To support multiple organization functionality, Oracle XML Gateway allows you to set up Trading Partners for all operating units associated with your responsibility.
All Trading Partner related data, including Trading Partner Types, Trading Partner Names, and Trading Partner Sites, is associated with the specified operating unit. You can select an operating unit that is linked to your responsibility while defining a Trading Partner using the Trading Partner Setup form.
Multiple Organization Access Control
To secure data access, Oracle XML Gateway uses security profiles that are linked to your responsibility to control access to one or more operating units. The security profile concept allows system administrators to predefine the scope of access privileges as a security profile and then associate the security profile with responsibility for a user.
Multiple operating units are associated with a security profile and the security profile is in turn associated with a responsibility. Therefore, through the access control of security profiles, users can access data in multiple operating units without changing responsibility.
Security profiles are defined based on organization hierarchies. For example, a sales company consists of USA and UK operating units; each operating unit also contains sub-level operating units for various regions. These top or sub level operating units can be defined as security profiles based on the organization hierarchy. Sales managers, supervisors, and representatives are responsible for their designated sales units or regions. System administrators can then associate those predefined security profiles with appropriate sales people through their responsibilities. Therefore, sales supervisors can easily access sales data in different sales regions without changing their responsibilities.
See Trading Partner chapter, Oracle e-Commerce Gateway Implementation Manual for details.
The Trading Partner Setup Header includes the following fields:
The Operating Unit field displays the default operating unit that is restricted by the security profile linked to your logon responsibility. You can change the default by selecting other operating unit from the list of values if you are associated with more than one operating units.
Trading Partner Type is tied to the operating unit; that is, once the operating unit is selected, only the associated Trading Partner Type, such as Supplier, Customer, Bank, or internal location, will be displayed in the list of values.
Trading Partner Type defines the type of trading partner, such as Supplier, Customer, Bank or internal location. Once the Trading Partner Type is selected from the list of values, the Trading Partner Names and Trading Partner Sites associated with the Trading Partner Type are displayed in the Trading Partner Name and Trading Partner Site lists of values below.
Given the selection in the Trading Partner Type, the appropriate Trading Partner Names are displayed in the Trading Partner Name list of values. For example, if Partner Type is Customer, then customer names will be displayed. These Trading Partners are limited to those trading partners associated with the organization of your logon responsibility. Select the appropriate Trading Partner Name.
Given the selection in the Trading Partner Name, the appropriate Trading Partner Sites are displayed in the list of values. Select the appropriate Trading Partner Site.
This is the e-mail address of the administration contact to receive e-mails regarding warnings and errors. These notifications may be initiated by Oracle Workflow or by an action defined in the message map using the Message Designer. Users should check the error log.
Use the Code Conversion button to access the Trading Partner Code Conversion form. See:
The combination of Party Type (Trading Partner Type), Trading Partner Name, Trading Partner Site, Transaction Type, and Transaction Subtype uniquely identify an outbound transaction.
The combination of External Transaction Type, External Transaction Subtype, Standard Code, and Source Trading Partner Location Code uniquely identify an inbound transaction.
The Trading Partner Setup form includes the following detail for each message:
Transaction Type is the standard product short code for the base Oracle E-Business Suite application. These values are defined in the Define Transactions form. The list of values will display the available combinations of Transaction Type, Transaction Subtype, Standard Code, External Transaction Type, External Transaction Subtype, and Direction. Select the desired combination.
These values are only used internally to the XML Gateway. Refer to the Define Transactions Form for details.
Transaction subtype is a code for a particular transaction within the application specified by the Transaction Type. The last position represents the direction of the transaction: I for inbound, O for outbound.
The combination of Party Type (Trading Partner Type), Transaction Type, and Transaction Subtype should identify an Oracle transaction with which to associate this message. These values are defined in the Define Transactions form.
These values are only used internally to the XML Gateway. Refer to the Define Transactions Form for details.
The Standard Code associated with the Transaction Type selected above is displayed.
Standard Codes are set up in the Define XML Standards form.
The External Transaction Type associated with the Transaction Type selected above is displayed.
The External Transaction Type is the primary external identifier for the XML message. These values are defined in the Define Transactions form and they are found in the XML Gateway envelope.
The combination of the External Transaction Type and the External Transaction Subtype should identify this external message to the Oracle E-Business Suite.
The External Transaction Subtype associated with the Transaction Type selected above is displayed.
The External Transaction Subtype is the secondary identifier for the XML message. These values are defined in the Define Transactions form and they are found in the XML Gateway envelope.
The combination of the External Transaction Type and the External Transaction Subtype should identify this external message to the Oracle E-Business Suite.
The Direction associated with the Transaction Type selected above is displayed.
This code identifies the direction of the transaction. The value IN identifies an inbound message, and the value OUT identifies an outbound message.
(Message) Map is the name of the map created using Message Designer.
Select the appropriate map from the list of values.
The naming convention for message maps consists of the four components: Transaction Type, Transaction Subtype, Standard and Release, and Direction. For example: "PO_POO_OAG70_OUT" is the outbound Oracle Purchasing Purchase Order in the OAG standard, release 7.0. The direction code OUT makes the message direction more apparent in any list.
Refer to Message Designer for more details on the naming convention.
If the desired map does not appear in the list of values, then the map has not been loaded into the XML Gateway database. Refer to the How to Load Message Maps and DTDs.
A DIRECT connect and a hub are the methods by which the message can be communicated. The XML message can be sent directly to a trading partner, or sent to a trading partner via a hub. The hub will then communicate the message to the trading partner.
Select DIRECT to conduct business directly with a trading partner, or select a hub from the list of values. If a hub is selected, then select a trading partner from that hub.
See the Hub Definition form to define hubs.
Requirements for the entries for Protocol Type, Username, Password, and Protocol Address depend on whether you select DIRECT or a hub.
If you select DIRECT, complete these fields as follows:
Each message enabled for a Trading Partner includes a protocol type (also known as communication method). The associated correlation ID is determined internally and is associated with the message enqueued onto the agent (queue). Listeners defined for the agent will dequeue messages based on the correlation ID defined for it. For example, Oracle Transport Agent will only dequeue messages with a correlation ID of OXTA.
The following table shows the Protocol Type, Correlation ID, and Message System.
Protocol Type | Correlation ID | Message System |
---|---|---|
NONE | N/A | Message disabled |
HTTP-WM, HTTPS-WM | WebMethods | Third party system |
HTTP, HTTP-OXTA, HTTPS, HTTPS-OXTA, SMTP | OXTA | Oracle Transport Agent without attachments |
OTAH-ATCH, OTAHS-ATCH | OXTA | Oracle Transport Agent with attachment using standard OTA envelope |
HTTP-ATCH, HTTPS-ATCH | OXTA | Oracle Transport Agent with attachment and no OTA envelope |
ITG03 | ITG03 | Oracle iProcurement Connector |
IAS | IAS | Oracle Integration Server |
SOAP | N/A | Web Service Agent |
JMS | N/A | JMS Provider |
Select the protocol type from the list of values. This data is seeded by the XML Gateway.
Protocol type NONE will disable the outbound message for this trading partner.
Username
Enter the destination Username used to log in to the receiving server for the server that is identified in the server address.
For protocol types HTTP and HTTPS, Username and Password are required fields.
Password
Enter the Password for the destination Username. The password is not echoed when it is entered. You will be prompted on the same field to confirm the password.
For protocol types HTTP and HTTPS, Username and Password are required fields.
Protocol Address
Protocol Address is the complete URL (including service/servlet) where the Transport Agent will attempt to post the XML Document.
For protocol type SMTP, the Protocol Address is an e-mail address, and is required.
For protocol type JMS, the Protocol Address is a JMS queue.
If you select a Hub, complete these fields as follows:
Protocol Type
Protocol Type defaults from the Hub definition.
Username
Select the Username from the list of values supplied by the Hub definition. If the Protocol Type is SMTP, the Username is not required. For all other Protocol Types, this field is required.
Password
This field defaults to the password that is associated with the Username selected. The username and password combination is supplied from the Hub definition. If the Protocol Type is SMTP, this field is not required.
Protocol Address
Protocol Address defaults from the Hub definition.
Source Trading Partner Location Code is the code found in the XML Gateway envelope to identify the source of the message. This is the code for the source trading partner of the message.
If you are sending and receiving messages from a trading partner, you will have a mixture of your location codes and your trading partner's location codes depending on the direction of the message. For example, if you are sending messages out, the Source Trading Partner Location Code is your location code because you are the source of the XML message. If you are receiving messages, the Source Trading Partner Location Code is your trading partner's location code because they are the source of the XML message.
This code is examined for inbound messages for Trading Partner validation. When placed on an outbound message, the recipient will validate it as a valid source or sending location.
This field is placed in the PARTY SITE ID in the XML Gateway envelope.
See: XML Gateway Envelope.
There are two types of routing in the XML Gateway: Static Routing and Dynamic Routing. Dynamic Routing allows the message to be rerouted by the first recipient of the message to the final destination recipient. Refer to the Routing field below for Static Routing.
Destination Trading Partner Location Code is the code for the final recipient of the XML message. This code is not needed by the XML Gateway creating this message, but needed by the hub or the first trading partner receiving the message to identify their final trading partner to receive the message. It is the hub's or the first trading partner's code for that final destination trading partner.
For outbound messages, the final intended recipient location code identified by the Destination Trading Partner Location Code will be placed in ATTRIBUTE3 in the XML Gateway envelope.
For inbound messages, this code is found in ATTRIBUTE3 in the XML Gateway envelope. Refer to Static and Dynamic Routing for an illustration that explains how ATTRIBUTE3 is populated.
Document Confirmation is the indicator for the confirmation level that this Trading Partner would like to send or receive a confirmation.
0 (Default value) means Never send a confirmation
1 means Send a confirmation only if there are errors
2 means Always send a confirmation
It defines the condition under which a confirmation XML message is generated or received. Outbound messages receive inbound confirmations. Inbound messages generate outbound confirmations.
Use the Routing field to identify another trading partner to whom messages will be routed. You select a trading partner for outbound transactions from the list of values. The inbound message is forwarded as an outbound message to the trading partner identified in the Routing field.
The XML Gateway provides both Static Routing and Dynamic Routing. Routing is the address to route the outbound message to when using the Static Routing method. Refer to the Destination Trading Partner Location Code field above for Dynamic Routing.
See: Static and Dynamic Routing for more information.
Different data is required depending on whether DIRECT or a trading partner is selected from a hub.
If DIRECT is selected, the following data fields are entered by the user depending on the protocol type for outbound messages:
Protocol Type (required)
Protocol Address (required)
User Name (depends on Protocol Type)
Password (depends on Protocol Type)
Source Trading Partner Location Code to identify the recipient of the message (required)
If the message is sent via a hub, select the hub, then select a Username from the presented list. The following data fields are retrieved for outbound messages:
The following data fields are copied from the Username in the hub definition:
Protocol Type
Protocol Address
Hub Entity Code (acts like the Source Trading Partner Location Code for DIRECT communication)
Password (optional and depends on Protocol Type)
If the message will be rerouted to another trading partner by the hub using Dynamic routing, then the following data is needed. It will be placed in ATTRIBUTE3 in the XML Gateway envelope:
Destination Trading Partner Location Code
See: XML Gateway Envelope.
Inbound messages require the following:
Source Trading Partner Location Code to identify the sender of the message
Messages can be passed through a middle trading party by using the static routing or dynamic routing feature. This method is also called a pass-through.
The following figure shows the routing flow of messages using the dynamic or static routing feature. The process starts with the review of the Trading Partner detail associated with the inbound message.
If data is found in the ATTRIBUTE3 field of the XML Gateway envelope, then the transaction is processed under the rules of Dynamic Routing. First the message is processed according to the inbound message map for the trading partner, then the message is rerouted to another trading partner who is the final recipient of the message. The trading partner detail for the final recipient is found in the Trading Partner Detail as an outbound message for the trading partner identified in the ATTRIBUTE3 field.
If there is no data in the ATTRIBUTE3 field of the XML Gateway envelope and there is data in the Routing field in the Trading Partner Detail for the inbound message, then the transaction is processed under the rules of Static Routing.
In Static Routing the message is processed according to the inbound message map for the trading partner, then the message is rerouted to another trading partner who is the final recipient of the message. The trading partner detail for the final recipient is found in the Trading Partner Detail as the trading partner identified in the Routing field for that inbound message.
If there is data in the ATTRIBUTE3 field of the XML Gateway envelope and there is data in the Routing field in the Trading Partner Detail for the inbound message, ATTRIBUTE3 will be used for the routing data.
If there is no data in the ATTRIBUTE3 field of the XML Gateway envelope and there is no data in the Routing field in the Trading Partner Detail for the inbound message, the message is not rerouted to another trading partner.
In both dynamic and static routing, data in the message may have code conversion applied at the trading partner level before constructing the outbound message for the final recipient. The retrieved code conversion values will be substituted into the XML message so the final trading partner receives the values that apply to them.
To explain Static and Dynamic routing for pass through messages, the following three trading partners are defined:
Party 1: Initiator of the Message
Party 2: First Recipient of the Message (This may be a hub)
Party 3: Final Destination of the Message
Party 1 will send the message to Party 2. Then Party 2 will reroute it to Party 3.
Static routing allows you to select another XML Gateway Trading Partner detail record from all your entries in the Trading Partner Setup form. You can select a trading partner within the same trading partner or from any other displayed trading partner. Every time a message is received for that trading partner and that transaction, it will automatically be routed to the trading partner defined in the "Routing" column.
Static Routing occurs under the following conditions:
The originator of the message (Party 1) does not include the final Destination Trading Partner Location Code in the message.
For the given transaction and trading partner, the first recipient of the message (Party 2) has selected a trading partner in the Routing field to automatically forward that message to.
In order for this to happen, the following is necessary:
Proper trading partner setup for the final recipient must be entered in the Trading Partner Setup in Party 2's environment.
The following illustration reviews the required trading partner setup for each party in the example.
Party 1: Initiator of the Message:
In Static Routing, the first initiator of the message does not indicate the final Destination Trading Partner Location Code in their setup. No data should appear in ATTRIBUTE3 of the XML Gateway envelope. This is illustrated in the following table:
Entry | Trading Partner | Direction | External Transaction Type | External Transaction Subtype | Protocol | Source TP Location Code | Routing | Destination TP Location Code (in ATTRIBUTE3) |
---|---|---|---|---|---|---|---|---|
(1) | Party 2 | OUT | INVOICE | ADD | HTTP | Party 1 | N/A | N/A |
Party 2: First Recipient of the Message:
PARTY 2 must define the message for both the inbound trading partner and the outbound trading partner to whom the message will be rerouted.
(2) Party 2 received the message from Party 1. The message was an inbound invoice to Party 2. See entry (2) of the table below.
(3) Party 2 will reroute the message to Party 3, because the trading partner setup for Party 3 was stored under the Routing field for Party 2's trading partner setup for Party 1. The trading partner setup data for the trading partner in the Routing field is used to create the new message and the XML Gateway envelope. See entry (3) of the table below.
Entry | Trading Partner | Direction | External Transaction Type | External Transaction Subtype | Protocol | Source TP Location Code | Routing | Destination TP Location Code |
---|---|---|---|---|---|---|---|---|
(2) | Party 1 | IN | INVOICE | ADD | N/A | Party 1 | (points to Party 3 for the outbound message) | N/A |
(3) | Party 3 | OUT (will be set to out) | INVOICE (use the same External Transaction Type) | ADD (use the same External Transaction Subtype) | HTTP | Party 2 | N/A | N/A |
The following method is dynamic because the first party originating the message indicates the Destination Trading Partner Location Code for the final destination trading partner to receive the message.
Dynamic Routing occurs under the following conditions:
The originator of the message (Party 1) includes the final Destination Trading Partner Location Code in ATTRIBUTE3 in the XML Gateway envelope.
The first recipient of the message (Party 2) can identify the trading partner code in ATTRIBUTE3 in their own Trading Partner setup.
In order for this to happen the following is necessary:
Party 1's XML process must be set up to write the final trading partner to ATTRIBUTE3 of the XML Gateway envelope. The XML Gateway uses the Destination Trading Partner Location Code field in the Trading Partner Setup form.
The proper trading partner setup must be entered in Party 2's process to act on ATTRIBUTE3. For the XML Gateway, this is in the Source Trading Partner Location Code field in the Trading Partner Setup form.
The following illustration reviews the required trading partner setup for each party in the example.
Party 1: Initiator of the Message:
(1) In Dynamic Routing, the first initiator of the message (Party 1) passes a Destination Trading Partner Code in ATTRIBUTE 3 to the first message recipient (Party 2).
This code is defined by the first recipient of the message, so they can identify the trading partner to whom the message will be forwarded. The Destination Trading Partner Code will be copied to ATTRUBUTE3 in the XML Gateway envelope. See the table below:
Entry | Trading Partner | Direction | External Transaction Type | External Transaction Subtype | Protocol | Source TP Location Code | Routing | Destination TP Location Code (in ATTRIBUTE3) |
---|---|---|---|---|---|---|---|---|
(1) | Party 2 | OUT | INVOICE | ADD | HTTP | Party 1 | N/A | Party 3 |
Party 2: First Recipient of the Message:
This second party must define the message for both the inbound trading partner and the outbound trading partner.
(2) Party 2 received the message from Party 1. The message was an inbound invoice to Party 2. See entry (2) in the Trading Partner Setup for Party 2 table.
Party 2 will validate Party 1 as a trading partner for that inbound message. The data is shown in the following table
Direction | External Transaction Type | External Transaction Subtype |
---|---|---|
IN | INVOICE | ADD |
(3) Party 2 will reroute the message to Party 3. The message becomes an outbound invoice from Party 2. See entry (3) below.
Party 2 will also perform a trading partner lookup for the trading partner to whom the message is to be forwarded. The direction is changed to OUT. External Transaction Type and External Transaction subtype are copied from the inbound message. The lookup involves the data shown in the following table:
Direction | External Transaction Type | External Transaction Subtype |
---|---|---|
OUT | INVOICE | ADD |
The Trading Partner Setup for Party 2, is shown in the following table:
Entry | Trading Partner | Direction | External Transaction Type | External Transaction Subtype | Protocol | Source TP Location Code | Routing | Destination TP Location Code (in ATTRIBUTE3) |
---|---|---|---|---|---|---|---|---|
(2) | Party 1 | IN | INVOICE | ADD | N/A | Party 1 | N/A | N/A |
(3) | Party 3 | OUT (set to OUT) | INVOICE (use the same External Transaction Type) | ADD (Use the same External Transaction Subtype) | HTTP | Party 2 | N/A | N/A |
Party 3: Final Recipient of the Message:
(4) Party 3 received the message from Party 2. The message was an inbound invoice. The data is shown in the following table:
Entry | Trading Partner | Direction | External Transaction Type | External Transaction Subtype | Protocol | Source TP Location Code | Routing | Destination TP Location Code (in ATTRIBUTE3) |
---|---|---|---|---|---|---|---|---|
(4) | Party 3 | IN | INVOICE | ADD | N/A | Party 2 | N/A | N/A |
To ensure that only an authorized user is allowed to perform inbound XML transactions on behalf of any Trading Partner, Oracle XML Gateway provides the Trading Partner user security feature through the association of authorized users with specific Trading Partners using the Trading Partner User Setup form.
Important: Each Trading Partner can have one or more authorized users associated with it, but each user can be authorized for only one Trading Partner.
What's the Impact?
Oracle Transaction Agent (OTA) and Web Services use internal APIs to validate the Trading Partner and authorize a user for a Trading Partner to perform XML transactions on behalf of a Trading Partner.
Existing Users will have to authorize an Oracle E-Business Suite user by associating a user with a Trading Partner using the Trading Partner User Setup form to perform XML transactions on behalf of a Trading Partner.
For backward compatibility, Oracle XML Gateway uses the Enable User Security profile option to turn the user security feature on or off.
If the value is set to "No" (default) which turns the security OFF, the transaction will be enabled regardless of the association between the user and the Trading Partner.
If you change the value from "No" to "Yes" which turns the user security ON, Oracle XML Gateway will validate the Trading Partner user against the Trading Partner user setup data to determine if the inbound transaction can be enabled.
If the user is linked to the Trading Partner, then the transaction is enabled for the Trading Partner.
If the user is not linked to the Trading Partner, then the transaction is not enabled. An error message will be shown in the transition monitor indicating that the user is not enabled in the XML Gateway Server. Please check your setup.
The Trading Partner User Setup form allows you to associate authorized users with a Trading Partner. The same user cannot be associated with more than one Trading Partner.
Navigate to this form by clicking the User Setup button on the Define Trading Partner Setup form (XML Gateway Responsibility > Setup > Define Trading Partners).
The Trading Partner Type, Trading Partner Name, and Trading Partner Site values are entered in the Trading Partner Setup form and displayed here as read-only fields. You can update Company Admin Email address as needed. The address of the administration contact is to receive e-mail notifications regarding warnings and errors.
Note: If the Trading Partner Header information is not saved in the Trading Partner Setup form before selecting the User Setup button, an error message will occur.
Select valid Oracle E-Business Suite user names to be associated with the Trading Partner from the drop-down list. An error message appears if the selected user has been assigned to any other Trading Partner.
Note: To update a selected user name, you need to first delete the selected name and then add a new one selected from the drop-down list so that the new user is also a valid Oracle E-Business Suite user.
This field populates automatically once the User Name field is selected.
The Oracle XML Gateway code conversion function provides a method to cross-reference the codes defined in Oracle E-Business Suite to codes used by trading partners, the XML standard, or other standard codes in the transactions.
For example, assume that the ABC Corporation transmits a purchase order to the XYZ Corporation. The XYZ Corporation processes the incoming data using its own Oracle values (for example, unit of measure, currency, or freight carriers), but XYZ is required to return ABC's codes. In this way, the trading partner that created the original transaction receives response transactions that use their own values.
The Code Conversion features include the following:
.Define XML standard code conversion values defined by the XML standard. These codes are used by all trading partners.
Define universally used code conversion values that are defined by other standard organizations such as ISO, X12, and EDIFACT. These codes are used by all trading partners.
Define trading partner-specific code conversion values. The trading partner-specific code may override an XML standard or the other universally used code conversion values.
In the Define XML Standards form, Standard Codes such as OAG are entered to represent a message standard. There is a special purpose Standard Code called "UNIVERSAL" that is described below. See: Define XML Standards Form.
Entries from the Define XML Standards form appear in a list of values in the Define Transactions form that defines transactions to the XML Gateway. In this form, one Standard Code is associated with each transaction listed under External Processes. See: Define Transactions Form.
The actual code conversion values are entered in the Standard Code Conversion form and the Trading Partner Code Conversion form. The code conversion form provides a one-to-one code conversion from the Oracle values to an external value. The external code may be the XML standard codes such as OAG's code, the universal code such as ISO codes, or trading partner-specific codes. These are discussed below.
The trading partner code conversion values are accessed through the Trading Partner Setup form. Refer to Trading Partner Setup for details. Press the Code Conversion button to access the Trading Partner Code Conversion form from the Trading Partner Setup form.
The values associated with the trading partner's code values are the first set of codes to be examined during code conversion.
Before making entries in the trading partner specific table, first update the Standard Code Conversion values if necessary. This is important because the entries in the Standard Code Conversion tables are displayed and potentially overridden in the Trading Partner Code Conversion form.
The following table illustrates the linking of a Trading Partner's message maps to Code Conversion:
Trading Partner | Message Map | Code Conversion Values are created for the Trading Partner? | The Message Map has a Unit of Measurement (UOM) field? | Accessed Trading Partner Code Conversion Values when the Message is Processed |
---|---|---|---|---|
Acme Corp, Atlanta | PROCESS_PO | Yes, for Acme, Atlanta | Yes, So Category UOM is entered for Code Conversion on the field | For UOM Category Code, the Acme, Atlanta code conversion values are accessed for the message map PROCESS_PO |
Acme Corp, Chicago | PROCESS_PO | Yes, for Acme, Chicago | Yes, So Category UOM is entered for Code Conversion on the field | For UOM Category Code, the Acme, Chicago code conversion values are accessed for the message map PROCESS_PO |
Acme Corp, Atlanta | ADD_INVOICE | Yes, for Acme, Atlanta | Yes, So Category UOM is entered for Code Conversion on the field | For UOM Category Code, the Acme, Atlanta code conversion values are accessed for the message map ADD_INVOICE |
Acme Corp, Chicago | ADD_INVOICE | Yes, for Acme, Chicago | Yes, So Category UOM is entered for Code Conversion on the field | For UOM Category Code, the Acme, Chicago code conversion values are accessed for the message map ADD_INVOICE |
Message Map is assigned to this trading partner site in the Trading Partner Setup form (under Trading Partner Details)
Access Code Conversion through the Trading Partner Setup form
Data field is assigned the Category Code when the message map is created in the Message Designer
Since duplicate Oracle Values cannot be entered into the code conversion tables, the trading partner must always use the same "To Trading Partner Value" for all the transactions that it has enabled. The following table illustrates this rule:
Oracle Value | Description | From Trading Partner Value | To Trading Partner Value |
---|---|---|---|
Each | Each | EA | EA |
Piece | Piece | PC | PC |
Each | Each | PC | PC |
Oracle Value - Cannot key on multiple occurrences of the value "EACH"
From Trading Partner Value - Cannot key on multiple occurrences of the value "PC"
To Trading Partner Value - Cannot key on multiple occurrences of the value "PC"
Given the Code Conversion setup discussed above, there is a standard code associated with each message. The standard code is the source organization for the code value, such as OAG for the given XML message to be processed.
The values associated with that standard organization's code values are the second set of codes to be examined during code conversion.
All other standards except the one that defined the XML message are marked collectively as UNIVERSAL. The XML Gateway does not store the other code conversion values under each standard such as the ISO codes or the X12 codes. It does not know which order the user wishes to access those code sets. For example, should the ISO codes be accessed before the X12 Codes, or the reverse? Hence, they are stored under a generic name.
The values associated with the UNIVERSAL code values are the third set of codes to be examined during code conversion.
The table below displays samples of ISO Country Codes that can be used across all trading partners and entered only once in the Standard Code Conversion forms.
Standard Code | Oracle Value | Description | From Trading Partner Value | To Trading Partner Value |
---|---|---|---|---|
UNIVERSAL | United States | United States | US | US |
UNIVERSAL | United Kingdom | United Kingdom | UK | UK |
If there is a conflict between two codes that must be entered as UNIVERSAL, it may be resolved by entering the conflicting codes under the Trading Partner code conversion for each trading partner needing that code.
Only the conflicting or duplicate code values need to be entered under each trading partner. The entries that do not cause conflicts can be entered under UNIVERSAL at the same time.
A Category Code is a label for a set of entries in the code conversion table. For example, CARRIER is the category code for code conversion values associated with the carrier.
During transaction processing, only the code conversion table entries with an assigned category code are accessed for the given data element.
See Seeded Code Categories for the seeded list.
Outbound and inbound transactions use different keys in the code conversion tables to access the codes.
For outbound transactions, "Oracle Value" and the Standard Code are keys to access this table to determine the "To Trading Partner Value" to write in the transaction.
For inbound transactions, "From Trading Partner Value" and the Standard Code are keys to access the table to determine the "Oracle Value" to pass to Oracle E-Business Suite application tables.
The following table search order is performed for all transactions until a code conversion value table entry is found:
Access the Trading Partner code conversion table.
If the code is not found in this table, perform a second search.
Access the Standard code conversion table using the XML message's Standard Code, such as OAG. This Standard Code is associated with the transaction in the transaction table as defined via the Define Transactions form.
If the code is not found in this table, perform a third search.
Access the Standard code conversion table using the Standard Code UNIVERSAL. The universal entries may represent ISO codes or other standards.
For inbound transactions: If the code is not found in the tables after the three searches described above, then the "From Trading Partner Value" is copied to the target field in the message map.
For outbound transactions: If the code is not found in the tables after the three searches described above, then the "Oracle Value" is copied to the target field in the message map.
Important: If a code conversion value is not found in the table, it is not an error. There may be cases where only select values for a data element need code conversion. To require all values to have a code conversion table entry may cause you to do an excessive number of code conversion entries that are not necessary.
The following table illustrates the order that the tables and Standard Code Values are searched:
Search Order | Code Conversion Form | STANDARD CODE | Purpose |
---|---|---|---|
1 | Trading Partner Code Conversion | CUSTOM | Define the trading partner-specific code conversion values. This includes any overrides to any standard's or universal code conversion values that are displayed from the Standard Code Conversion form. The trading partner code conversion values are used by all transactions for that trading partner. |
2 | Standard Code Conversion | For example: OAG ROSETTANET (ROS) | Define standard code conversion values for a given XML standard that are used across all trading partners. These values can be overridden for a specific trading partner in the Trading Partner Code Conversion form. The Standard Code field is the default XML standard associated with the XML message. |
3 | Standard Code Conversion | UNIVERSAL | Define standard code conversion values that are used across all trading partners and not associated with an XML Standard. These values can be overridden for a specific trading partner in the Trading Partner Code Conversion form. Those entries accommodate universally used code lists such as ISO, X12, EDIFACT, that can be used by all XML Messages. |
For outbound transactions, the "Oracle Value" and the Standard Code in the code conversion tables are keys to retrieve the "To Trading Partner Value" to place it in the transaction. First the trading partner codes are searched. If an entry is not found, then the Standard code conversion table is searched for the standard codes and the universal codes.
If the code is not found in the tables after the three searches described above, then the Oracle Value is copied to the target field in the message map. Otherwise, the "To Trading Partner Value" will be copied to the target field in the message map.
The following table illustrates the code conversion concepts for outbound transactions using the category code UOM. The Outbound Search Key is comprised of the values for Conversion Table, Standard Code, and Oracle Value. The To Trading Partner Value is the data retrieved.
Conversion Table | Standard Code | Oracle Value | Description | From Trading Partner Value | To Trading Partner Value |
---|---|---|---|---|---|
Trading Partner or Standard | Appropriate Code for the first, second, third search | Each | Each | (ignore the value here - not relevant for Outbound Transactions) | EA (derive this code to place in the transaction) |
The following table illustrates a sample outbound transaction code conversion for the category code UOM. The Outbound Search Key is comprised of the values for Conversion Table, Standard Code, and Oracle Value. The To Trading Partner Value is the data retrieved.
Conversion Table | Standard Code | Oracle Value | Description | From Trading Partner Value | To Trading Partner Value |
---|---|---|---|---|---|
Trading Partner | Box | Box | (ignore the value here) | BX | |
Trading Partner | CUSTOM | Each | Each | (ignore the value here) | EA |
Standard | OAG | Box | Box | (ignore the value here) | BX |
Standard | OAG | Each | Each | (ignore the value here) | EA |
Standard | UNIVERSAL | Box | Box | (ignore the value here) | BX |
For inbound transactions, the "From Trading Partner Value" and the Standard Code in the code conversion tables are keys to retrieve the "Oracle Value." First the trading partner codes are searched. If an entry is not found, the Standard code conversion table is searched for the standard codes and then the universal codes.
If the code is not found in the tables after the three searches described above, then the "From Trading Partner Value" is copied to the target field in the message map. Otherwise, the "Oracle Value" will be copied to the target field in the message map.
The following table illustrates the code conversion concepts for inbound transactions using the category code UOM. The Inbound Search Key-1 is comprised of the values for Conversion Table and Standard Code. The Oracle Value is the retrieved data. The From Trading Partner Value is the Inbound Search Key-2.
Conversion Table (Inbound Search Key-1) | Standard Code (Inbound Search Key-1) | Oracle Value (Retrieve) | Description | From Trading Partner Value (Inbound Search Key-2) | To Trading Partner Value |
---|---|---|---|---|---|
Trading Partner or Standard | Appropriate Code for the first, second, third search | Each (Derive this code to place in the Oracle table) | Each | EA | (Ignore the value here - Not relevant for Inbound Transactions) |
The following table illustrates a sample inbound transaction code conversion for the category code UOM. The Inbound Search Key-1 is comprised of the values for Conversion Table and Standard Code. The Oracle Value is the data retrieved. The From Trading Partner Value is the Inbound Search Key-2.
Conversion Table (Inbound Search Key-1) | Standard Code (Inbound Search Key-1) | Oracle Value (Retrieve) | Description | From Trading Partner Value (Inbound Search Key-2) | To Trading Partner Value |
---|---|---|---|---|---|
Trading Partner | Box | Box | BX | (Ignore the value here) | |
Trading Partner | CUSTOM | Each | Each | EA | (Ignore the value here) |
Standard | OAG | Box | Box | BX | (Ignore the value here) |
Standard | OAG | Each | Each | EA | (Ignore the value here) |
Standard | UNIVERSAL | Box | Box | BX | (Ignore the value here) |
Standard | UNIVERSAL | Each | Each | EA | (Ignore the value here) |
You can use the Action Assign Variable Value in Message Designer to assign multiple external codes given the single Oracle internal code by using conditions on the internal code. You must update the message in Message Designer as new codes are needed.
For example, the single Oracle internal carrier code stored in the SHIP_VIA column may need to cross-reference to two external codes: the carrier and the transportation mode. For example,
If SHIP_VIA = 'TRUCK-LAND'
move 'TRUCK' to the CARRIER.
If SHIP_VIA = 'TRUCK-LAND'
move 'L' to the TRANSPORTATION_METHOD.
If SHIP_VIA = 'TRUCK-AIR',
move 'TRUCK' to the CARRIER.
If SHIP_VIA = 'TRUCK-AIR'
move 'A' to the TRANSPORTATION_METHOD.
Note: For Outbound Transactions:
If you have the SHIP_VIA source data written twice to the file, then code conversion could be performed to convert the two fields separately: Once to derive the carrier code and once to derive the transportation method.
Navigate to the Standard Code Conversion form from the XML Gateway Responsibility by selecting Setup > Define Code Conversion.
The Standard Code Conversion form displays a list of code values that are used by all trading partners unless the codes are overridden by trading partner specific code values. For a discussion of trading partner specific codes see Trading Partner Code Conversion Form.
To read more about Code Conversion features and concepts see Code Conversion.
Select a category code to view its list of values in the Category Values portion of the form. A category code cannot be added or deleted.
Description of the category code.
A Standard Code identifies one of the following:
The source organization for the code value, such as OAG, for the given XML message to be processed.
The word UNIVERSAL, the seeded code to identify any other organizations such as ISO, X12, EDIFACT.
Note: Only XML standards and the single non-XML standard UNIVERSAL should be defined in the Define Transactions form. The process would not recognize standard codes such as ISO or EDIFACT though they can be entered into this form.
Select a standard code from the list of values.
Use the Define XML Standards form to add new standard codes as needed.
The Oracle Value is a code defined in the Oracle E-Business Suite, regardless if it is an inbound or outbound transaction. The Oracle Value is case-sensitive.
Description of the Oracle Value.
The "From Trading Partner Value" is a code in the message that represents data from the trading partner's perspective. This code is found in the inbound source transaction.
The "To Trading Partner Value" is a code to be written in the outbound message. It represents data that the trading partner is expecting to receive. You cannot enter data in this field. This code value is always equal to and copied from the "From Trading Partner Value."
The Standard check box is enabled for all entries made in the Standard Code Conversion form.
If a code conversion value table entry has the Standard check box checked, and the code conversion value is later overridden in the Trading Partner Code Conversion table, this check box is switched "off" (made blank) in the Trading Partner Code Conversion form.
The system controls setting this check box off and on.
Data can be seeded into the database by the XML Gateway. Seeded data is indicated by a check mark in this check box. If data is marked as seeded, it cannot be modified in the forms.
The Revert All Button is disabled in this form. It is used in the Trading Partner Code Conversion form to revert all codes back to the standard code value found in the standard Code Conversion table up to the last saving of the entries.
All fields except the Standard check box, Data Seeded check box, and the To Trading Partner Value can be changed.
The Revert Button is disabled in this form. It is used in the Trading Partner Code Conversion form to revert the codes back to the standard code value found in the standard Code Conversion table up to the last saving of the entries.
The Trading Partner Code Conversion form allows the entry and display of code values for a specific trading partner.
Navigate to this form by clicking the Code Conversion button on the Define Trading Partner Setup form (XML Gateway Responsibility > Setup > Define Trading Partners).
The Trading Partner Code Conversion form contains data from the following sources:
All trading partner-specific code values entered in this form
All codes entered in the Standard Code Conversion form. The Standard check box on the form indicates if the data was entered in the Standard Code Conversion form. The standard code conversion values can be changed.
To read more about Code Conversion features and concepts see Code Conversion.
Select a category code to view its list of values in the Category Values portion of the form. A code category cannot be added or deleted.
Description of the category code.
The following fields are found in the Category Values region:
When adding Trading Partner-specific code conversion values, this field defaults to CUSTOM.
The Oracle Value is a code defined in the Oracle E-Business Suite, regardless if it is an inbound or outbound transaction. The Oracle Value is case-sensitive.
Description of the Oracle Value.
The "From Trading Partner Value" is a code in the message that represents data from the trading partner's perspective. This code is found in the inbound source transaction.
The "To Trading Partner Value" is a code to be written in the outbound message. It represents data that the trading partner is expecting to receive. You cannot enter data in this field. This code value is always equal to and copied from the "From Trading Partner Value."
The Standard check box is enabled for all entries made in the Standard Code Conversion form.
If a code conversion value table entry has the Standard check box checked, and the code conversion value is later overridden in the Trading Partner Code Conversion table, this check box is switched "off" (made blank) in the Trading Partner Code Conversion form.
The system controls setting this check box off and on.
Data can be seeded into the database by the XML Gateway. Seeded data is indicated by a check mark in this check box. If data is marked as seeded, it cannot be modified in the forms.
The Revert All Button in the Trading Partner Code Conversion form reverts all codes back to the standard code value found in the standard Code Conversion table up to the last saving of the entries.
All fields except the Standard check box, the Data Seeded check box, and the To Trading Partner Value can be changed.
The Revert Button in the Trading Partner Code Conversion form reverts the codes back to the standard code value found in the standard Code Conversion table up to the last saving of the entries.
Note: The Revert Button applies to only the selected entry for this specific trading partner.
If you are adding a Custom code, all fields except the Standard check box, and Data Seeded check box can be changed.
If the Standard Code is not "CUSTOM" then only the From Trading Partner Value and the To Trading Partner Value can be changed. The Standard check box will be enabled.