Accessing Oracle B2B metadata from your application

For some time now, Oracle B2B has exposed several methods of accessing it's partner and message metadata from a custom application. This has been improved even further with B2B 12c.
In this post I'll guide you through the 2 most common ways of accessing B2B's metadata programmatically and some news of the 12c version.

The 2 main ways of accessing the metadata stored in B2B are:

• Web Services exposed by B2B
• Java API 

Web Services exposed by B2B

You can access the WSDL's for the available web services at the following URL:

http://host_name:port_number/b2b/services/

The most common services are:

• Outbound Web Service - Works as an internal Listening Channel. Based on the details and headers in the soap:body, the agreement identification is done and the message is routed to the partner.
• Translation Web Service - Allows to translate documents such as EDI and HL7 from Native to XML format (NativeToXMLService) and from XML to Native format (XMLToNativeService)
• Query API (GetTPAConfigService) - Allows for retrieval of different metadata such as active agreements for a Trading Partner or checking if a Trading Partner has an agreement for a specific Document.

For more information on Oracle B2B Web Services take a look at:

Using the Oracle B2B Web Services

Java API

Using the Java API you have a range of choices for different metadata information that you can retrieve from B2B.

The new Partner Metadata API (oracle.tip.b2b.utility.MetadataUtil) provides you access to Trading Partner metadata such as:

• Contact Information - This method returns a Key-Value pair (Map) of Contact Information Type and its Value/s for a given Trading Partner.  If a Contact Information Type has multiple values, retrieved map will contain the whole list of values.  Individual values can be extracted by iterating through this map.
  public Map<String, List<String>> getContactInfo(String tpName)
• Trading Partner Identifiers - This method returns a Key-Value pair (Map) of Identifier Type and its Value/s for a given Trading Partner.  If an Identifier Type has multiple values, retrieved map will contain the whole list of values. Individual values can be extracted by iterating through this map. If provided TP name is nonexistent, an exception will be thrown with message: “Trading Partner does not exist”.
  public Map<String, List<String>> getIdentifiers(String tpName)
• Trading Partner Parameters - This method returns a Key-Value pair (Map) of Parameter Name and its Value for a given Trading Partner. Individual values can be extracted by iterating through this map. If provided TP name is nonexistent, an exception will be thrown with message: “Trading Partner does not exist”
  public Map<String, String> getTradingPartnerParameters(String tpName)

There was already available other metadata APIs such as the Instance Message API which provides multiple ways to access an Instance Messages and it's associated metadate. For more information on this API as well as other APIs available on Oracle Fusion Middleware take a look at:

Oracle Fusion Middleware 12c - Reference and APIs

Note: The new Partner Metadata API and other 12c features are available for the  11g version of SOA Suite by installation of patch SOA bundle Patch 19190139 11.1.1.7.5

Oracle B2B Message States

After some difficulties trying to obtain details on the different possible states that a B2B message can have, I could get the following information valid for the B2B Business Message states:

MSG_COMPLETE: Business message state after completion of message transfer (and after receiving acknowledgment of the transmission in case of Ack/FA). Wire message state is moved to MSG_COMPLETE state as well.

MSG_WAIT_ACK: Business message state when an outbound message is sent to trading partner and B2B waits for Ack to be received.

MSG_ERROR: Business message state after a problem occurs in B2B or a negative acknowledgement is received from the trading partner. Wire message state is moved to
MSG_ERROR state as well.

MSG_WAIT_TRANSMIT: Business message state while B2B is sending message to trading partner. This state is also observed for the messages when they are queued in case of sequencing.

MSG_WAIT_FA: Business message state when an outbound message is sent to trading partner and B2B waits for Functional Ack to be received.

MSG_SEND_FA: Business message state when B2B is sending Functional Ack to a trading partner.

MSG_WAIT_BATCH: Business message state while messages are batched up during the interval before batch expiration. After the batch expires, the entire batch of messages are sent out, and business and wire message states move to MSG_COMPLETE (or MSG_ERROR if a problem occurs).

MSG_WAIT_STACK: Business message state when there is any transport error in case of sequencing.

MSG_WAIT_TA1: Business message state while waiting for TA1 Message for EDI-X12.

MSG_SEND_TA1: Business message state while sending TA1 Message for EDI-X12.

MSG_CONTINUE_PROCESS: Business message state when message is being processed in B2B(engine).

MSG_COLLAB_WAIT: Business message state when message is waiting for Collaboration.

MSG_PROCESS_ACK: Business message state while processing an Acknowledgement.

MSG_SEND_ACK: Business message state when an inbound message is received from trading partner and B2B is sending an Acknowledgement.

MSG_SEND_EXP: Business message state while sending an Exception message.

MSG_PROCESS_EXP: Business message state while Processing an Exception Message

MSG_INVALID: This state the default/first state when the message processing begins in B2B. This state should not be encountered while monitoring the Message states in B2B.

I'm hoping Oracle introduce this information in the official documentation and extends it to cover both wire and application messages.

Note: This information is valid for the 11.1.1.7 version of SOA Suite.

Oracle Document Editor - Defining a custom message (Part 3 of 3)

When your definition is ready you may test it in the Analyzer/Data tab as follows. You may also generate a test sample with the Analyzer.

After testing a sample you can see the value of each element in the message structure and the errors (if any) to correct.

The final step is to generate the XSD. To do that just navigate in the main menu to File -> Export and select "Oracle 2.0".

You can generate the xsd with default configuration or check the box "Show Advanced Option", in which you may, for example, set the namespace and the structure of the field names. In the example below I'm specifying the field names as NodeID_NodeName.

In the following window of the wizard it's recommended to check the option "Suppress Enumeration in XSD" if you have code lists, otherwise they would be included in the XSD, since the ECS is used for validating and translating this information is not needed in the XSD and reduces it's size considerably.

After finishing your document definition and generating the schema you are ready to create your B2B document definition. However have in mind that for Positional Flat File documents, as in this example, you also need to generate the Parser ECS.

For information on how to generate the parser schema check out the post Oracle B2B 12c Positional Flat File and Charset Configuration

Oracle BPM 12c - Issues with BPM Composer when running on Solaris

I have recently been facing several issues with BPM 12.1.3.0.1 running on Solaris when using the BPM Composer.
Two of those issues are easily fixed by adding a couple of extra Java properties to the respective environments set files.

1. Error when creating a Space or a project in the BPM Composer
   
   If you receive one of the following errors when creating a Space or a project in the Composer check Doc Id 1917397.1
   
   svn: E160004: Can't read length line from file /opt/oracle/products/fmw_1213/user_projects/domains/_dev/bpm/bac/_server1/repositories/da5fcb6a-ecd1-4fe3-9e9c-210870402281/db/fs-type: /opt/oracle/products/fmw_1213/user_projects/domains/_dev/bpm/bac/_server1/repositories/da5fcb6a-ecd1-4fe3-9e9c-210870402281/db/fs-type (Permission denied)...
   oracle.bpm.bac.subversion.server.repository.exceptions.RepositoryException: org.tmatesoft.svn.core.SVNException: svn: E200030: CANTOPEN
   
   This issue only occurs on Solaris and can be fixed by adding the following property:
   -Dsvnkit.useJNA=false
   to the JAVA_OPTIONS in commENV.sh under oracle_common/common/bin
   
   
2. Error when creating Webforms on the Composer or deploying a BPM project with Webforms
   
   If you receive the following error when creating Webforms on the Composer or deploying a BPM project with Webforms:
   
   java.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment
   
   Add the following property:
    -Djava.awt.headless=true
    to the JAVA_OPTIONS in setDomainEnv.sh under <domain_home>/bin

Oracle Document Editor - Defining a custom message (Part 2 of 3)

In the 1st part I focused on the Message Segments, now I will start populating the first segment.

A Segment can have, as seen below, three types of child nodes: Field, Composite (group of fields) and Union (of fields/composites)

When creating a Field there are a couple of properties to define.

In the case of a PFF document you have extra properties, namely Justification, Padding and Format, as seen above.

This will define how an element will be presented on the PFF document since each field needs to be fully populated.

When the field is a String, the common values for Justification and Padding are Left and Space respectively, whereas if the element is a number (Type "Display") the Justification should be Right and Padding of Zeros as to have, for example, "001". 

For the Min Length value it's a good practice to set it to "1" to avoid errors, unless you know the exact size of the values that will/can be in that field (not counting with padding since padding is added automatically to fill the Max Lenght size when B2B transforms a message to your PFF document).

After creating a field you will see a Property window similar to the following.

In the above picture, on the top right there is a textbox for the position of the node in the tree, you can press the round button where the mouse is pointing to automatically set/update the position of the existing nodes.

To change the position of nodes you can either use Cut/Copy + Paste or click on right mouse button and use the Move options.

In the properties window of a Field you can define the level of requirement or even "hardcode" a value.

However there are some properties like type and size, which are defined when creating a field, that cannot be modified in this properties view. To modify them you have to change the view from Guideline to Dictionary in the View menu.

In the Dictionary view you can see all the nodes in your document and edit the properties defined upon creation of each node.

In case you want to validate the content of a field from a list of possible elements you can create a Code List.

And populate it as below.

You may also change the list after creation in the properties tab.

In the final part I will focus on testing and generating the files needed by B2B.

Oracle Document Editor - Defining a custom message (Part 1 of 3)

Oracle Document Editor is an application used for creating and testing document definitions for Oracle B2B.

The document definition (ECS) file is required in B2B for translating and validating documents.

With Document Editor you are able to create new guideline documents or use a template from the comprehensive library of standards available for download. You can download Document Editor and the standard definitions available here.

The available document guideline templates include EDI, HL7, positional flat file (which includes some SAP iDocs), XMLSchema and so on, as seen below.

Thanks to the countless templates available you can easily and quickly create a message definition (ECS) and respective XSD to import to B2B. Making the necessary changes if needed.

Below is an example of a message definition from the template library.

However, specially with Positional Flat File (PFF) messages, you might have to create a custom definition.

In this post I will go through the steps needed to create a custom PFF document definition in Document Editor. This post will be divided in 3 parts, in the first part I will focus on Message Segments', afterwards I'll cover the Field's types and properties, finalizing with testing and XSD generation.

Let's start by creating an empty definition.

The first step will be to create the Message segment, which constitutes the root node.

After defining the root you are able to add two type of child nodes: Segment and Group (of segments).

 I will start by creating the first Segment of the message.

And defining it's properties.

As can be seen above you can define the level of requirement and the number of usages of Segments and Groups. There are various possibilities as for example Mandatory & Must use or Optional & Used.

In the picture below I am creating a Group

And defining it as Optional with the possibility of appearing numerous times.

In the next part I will focus on a Segment's child nodes.

Oracle B2B 12c Positional Flat File and Charset Configuration

Oracle B2B supports the processing of various protocols and types of messages, however, sometimes extra configurations are needed to support special cases. For each protocol type there is a charset file associated to it, containing the allowed characters.

In my case, we were receiving Position Flat File (PFF) messages with the German char “ß” in it, which is not part of the default PFF charset. Fortunately B2B is flexible enough to allow the modification of said charsets.

In this post I will tackle the two tasks needed to able to add this PFF document to Oracle B2B 12c, namely Generating the ECS parser schema and modifying, if needed, the default PFF charset on B2B.

Oracle Document Editor is an indispensable tool to create message definitions for Oracle B2B documents and will have an important part in both tasks.

First I will quickly describe how to generate the parser schema for your PFF document on Document Editor and add it to B2B and, afterwards, I will describe the steps required to modify the default PFF charset used by B2B.

1. Generate ECS parser schema

When you define a PFF document you need to create a parser schema and add it to the XEngine.

To do that start by opening your message definition on Oracle Document Editor and navigate in the menu to Edit -> Generate Parser Schema and generate the parser as seen bellow.

If you receive more than one message per file and want to process them as one just remove the check from "First record in the guideline starts a new message".

Next navigate in your server’s folder structure to {Middleware_home}/soa/soa/thirdparty/edifecs/XEngine/config and:

1. Add your parser ecs file in the “schema” folder;


2. Edit the XERegistry.xml file and add an entry as shown below under “Positional flat parser schemas”

To conclude restart the SOA server.

2. Modify the PFF charset

In case the PFF messages going through your B2B system use characters not included in the default charset, you will have to add them to the list of allowed characters. This is done by creating a custom charset for the specified Guideline Type (you can also specify the Standard and Version) which will override the default charset for the corresponding documents.

To accomplish this you will need to create a custom charset on Oracle Document Editor as follows:

1. Open Oracle Document Editor and navigate in the menu to Tools -> Environment -> Character Set Registry as seen here bellow

2. Duplicate or Create a charset, in this case I duplicated the Delimited Flat File CS as it had almost everything I needed and changed the Guideline Type combo box “Positional”


3. Make the needed changes, as for example in the picture bellow

4. Export your newly created charset.

Afterwards, navigate in your server’s folder structure and:

1. Add your custom charset to {Middleware_home}/soa/soa/thirdparty/edifecs/XEngine/config/charsets
   


2. Add an entry on {Middleware_home}/soa/soa/thirdparty/edifecs/Common/Modules/XEngine.dat as seen bellow

Finally, restart the SOA server.