Running the Purchase Order Sample

The WebLogic Integration software includes a purchase order sample designed to illustrate the basic techniques of creating message format definitions for binary data using Format Builder. The purchase order sample consists of DTD, MFL, and DATA files. These samples can be used to test your installation of the data integration component of WebLogic Integration.

The following topics are discussed in this section:

• What Is Included in the Purchase Order Sample

• Prerequisite Considerations

• Performing Binary-to-XML Translation

• Performing XML-to-Binary Translation

 

---

What Is Included in the Purchase Order Sample

The following table describes the files provided with the purchase order sample application. All directory names are relative to the WebLogic Integration samples directory (SAMPLES_HOME\integration) where SAMPLES_HOME is the samples directory in your WebLogic Platform installation..

Table C-1 List of Purchase Order Sample Application Files

Directory	File	Description
samples\di\po	po_01.data	Purchase order data in binary format.
	po_02.data	Additional purchase order data in binary format.
	po.dtd	Purchase order document type definition.
	po.mfl	Prebuilt message format description of purchase order data.

 

 

---

Prerequisite Considerations

Before you can run the purchase order sample, you must make sure that certain software applications are installed and certain tasks are complete. For more information, see BEA WebLogic Integration Release Notes.

To understand how the Format Builder is used, it helps to understand the data formats used by the data integration tools provided by WebLogic Integration: binary data, XML, and MFL. If you have not already done so, please review Understanding Data Formats.

 

---

Performing Binary-to-XML Translation

The following sections provide information about building a sample purchase order format definition and testing the translation of binary data into XML format:

• Analyzing the Data to Be Translated

• Creating the Format Definition and Testing the Translation

You can build format definitions that provide the information required to translate binary data to or from XML. Format definitions are the metadata used to parse the content of a binary data file.

Analyzing the Data to Be Translated

The key to translating binary data to and from XML is to create an accurate description of the binary data. For binary data (data that is not self-describing), you must identify the following elements:

• Data fields

• Data field attributes, such as name, data type, length/termination, optional, repeating

• Groups of related fields

• Group attributes, such as name, optional, repeating, delimited

• Hierarchical structure (groups of fields and/or other groups)

Listing  C-1 shows sample binary data that is included on the WebLogic Integration CD-ROM (and the download) and is called \samples\di\po\po_01.data. In this sample, the data is taken from a fictitious purchase order on a proprietary system used by the XYZ Corporation. XYZ wants to exchange information with another system that accepts XML data.

Listing C-1 Sample Purchase Order in Binary Format

1234;88844321;SUP:21Sprockley's Sprockets01/15/2000123 Main St.;
Austin;TX;75222;555 State St.;Austin;TX;75222;PO12345678;
666123;150;Red Sprocket;

To analyze the purchase order data:

1. Generate a definition of the data. To do so, you may need to use printed specifications or internal documentation. For this sample, we have described the purchase order format in Table  C-2.

   Table C-2 Purchase Order Master Record  

   Category	Field Name	Data Type	Length	Description
   Basic Information	Purchase Request Number	Numeric	Delimited by semicolon	The Purchase Request number assigned by the Purchasing department. This number is used to track the status of an order from requisition through delivery and payment.
   	Supplier ID	Numeric	Delimited by semicolon	The identification of the assigned supplier as defined in the corporate Supplier Data Base. Assignment of an approved supplier is made by the buyer when creating a Purchase Request from a requisition.
   	Supplier Name	Character	Prefixed by a literal "SUP:". Following this literal is a two digit numeric length field.	The name of the assigned supplier as defined in the corporate Supplier Data Base. This field is prefixed with a literal to indicate that it is present.
   	Requested Delivery Date	Date MM/DD/YYYY	10 characters	The delivery date specified by the requisitioner.
   Shipping Address	Street	Character	Delimited by semicolon	The street address to be used in shipping the requested items.
   	City	Character	Delimited by semicolon	The city to be used in shipping the requested items.
   	State	Character	Delimited by semicolon	The state to be used in shipping the requested items.
   	Zip	Numeric	Delimited by semicolon	The zip code to be used in shipping the requested items.
   Billing Address	Street	Character	Delimited by semicolon	The street address to be used for billing.
   	City	Character	Delimited by semicolon	The city to be used for billing.
   	State	Character	Delimited by semicolon	The state to be used for billing.
   	Zip	Numeric	Delimited by semicolon	The zip code to be used for billing.
   Payment Terms	Supported payment terms may be either Purchase Order or Company Credit Card. A literal preceding the payment information identifies the type.
   	PO Type	Character	Literal "PO"	Indicates PO payment terms.
   	PO Number	Numeric	Delimited by semicolon	Purchase Order number.
   	Credit Card Type	Character	Literal "CC"	Indicates Credit Card payment terms.
   	Credit Card Number	Numeric	Delimited by semicolon	Credit card number.
   	Credit Card Expiration Month	Numeric	Delimited by semicolon	Expiration month for credit card.
   	Credit Card Expiration Year	Numeric	Delimited by semicolon	Expiration year for credit card.
   Purchase Items	The following fields identify the items to be purchased. This information may be repeated for each item that is part of this Purchase Request. At least one item must be present.
   	Part Number	Numeric	Delimited by semicolon	The supplier's part number of the requested item.
   	Quantity	Numeric	Delimited by semicolon	The quantity requested. Must be greater then zero.
   	Description	Character	Delimited by semicolon	Description of the requested item.

   
    

2. Identify fields.

   A field is a sequence of bytes that is meaningful to an application. For example, in Table  C-2, Purchase Request Number, Supplier ID, Supplier Name, and so forth, are all fields.

3. Identify field attributes.

   Field attributes include the name of the field, the type of data stored in the field, the length of the field, and the delimiter that indicates the end of the field. For example, the Supplier ID field is delimited by a semicolon (;) indicating the end of the field data, but the Requested Delivery Date has an implied length of 10 characters.

4. Identify hierarchical groups.

   Groups are collections of fields, comments, and other groups or references that are related in some way. In Table  C-1, notice that the sample data defines a number of distinct groups: Shipping Address, Billing Address, Payment Terms, and Purchase Items.

5. Identify group attributes.

   You must define the attributes of the hierarchical groups. Group attributes include the name of the group, whether the group is optional, repeating, or delimited, or whether it is defined as a reference to another group. For example, because the same fields are required to define both a Shipping Address and a Billing Address (Street, City, State, Zip), you can define an Address group within the Shipping_Address group and set up a reference to it from within the Billing_Address group.

After you complete the preceding procedure, you may want to put the data into a spreadsheet, as shown in the example in Figure  C-1. This spreadsheet can then serve as a guide when you create your purchase order message definition.

Figure C-1 Analysis of Purchase Order Data

 

Creating the Format Definition and Testing the Translation

This section walks you through the process of creating a message format for translating the binary data described in yeah to XML. To make sure you create your purchase order message format correctly, you can compare the file you create with the \samples\di\po\po.mfl file on the product CD-ROM.

Step 1. Start the Format Builder and Create a Message Format

To start Format Builder and create a message format:

1. Choose Start—>Programs—>BEA WebLogic Platform 7.0—>WebLogic Integration 7.0—>Format Builder. The Format Builder main window is displayed.

2. Choose File—>New.

   A new message format root node is created and displayed in the navigation tree.

3. Enter PurchaseRequest in the Name/XML Root field.

4. Click Apply.

   The name of the message format root node is updated.

Step 2. Create the Basic Information Fields

To create the fields required to capture the basic identifying information for the purchase order:

1. To create the PR_Number field, choose Insert—>Field—>As Child.

   A new field is added to the navigation tree. The default field properties are displayed in the detail window.

2. Define the properties for the field as described in the following table.

   In this section . . .	Do the following . . .
   Field Description	Enter PR_Number in the Name field.
   	Select Numeric from the Type drop down list.
   Field Occurrence	Verify that the Once option button is selected.
   Field Attributes: Termination	Select the Delimiter option button
   	Enter a semi-colon (;) in the Value field on the Delimiter tab.
   Field Attributes: Code Page	Select the desired code page from the Code Page drop down list. A code page specifies the character encoding of the binary data in the field.

   
    

   Note: These values are determined by the analysis of the raw purchase order data shown in Figure  C-1.

3. Click Apply.

   The properties of the field are updated.

   Note: Because the only difference between the PR_Number field and the Supplier_ID field is the name you can use the Format Builder Duplicate feature to create the Supplier_ID field.

4. Right click the PR_Number field.

5. Select Duplicate from the shortcut menu.

   A duplicate field (NewPR_Number) is added as a sibling and becomes the current selection in the navigation tree.

6. Enter Supplier_ID in the Name field and click Apply to update.

7. To save your changes to the message format document, do the following:

   1. Choose File—>Save As to display the Save As dialog box.

   2. Navigate to the samples/di/po directory.

   3. Enter the desired filename. For example enter my_po.mfl.

      Note: The Format Builder automatically assigns the .mfl extension to message format files if no extension is specified.

   4. Click Save As.

8. To add a the Supplier_Name field, choose Insert—>Field—>As Sibling.

   A new field is added to the navigation tree. The default field properties are displayed in the detail window.

9. Define the properties for the Supplier_Name field as described in the following table.

   In this section . . .	Do the following . . .
   Field Description	Enter Supplier_Name in the Name field.
   	Select the Optional checkbox.
   	Select String from the Type drop down list.
   Field Occurrence	Verify that the Once option button is selected.
   Field Attributes	Select the Field is Tagged checkbox.
   	Enter the following in the Field is Tagged field: SUP:
   Field Attributes: Termination	Select the Embedded Length option button.
   	Select Numeric from the Type drop down list on the Description tab.
   	Verify that the Length option button is selected, and then enter 2 in the Length text box.

   
    

10. Click Apply.

    The properties of the field are updated.

    Note: The dotted-line box around the field icon in the navigation tree indicates that this field is optional.

11. To add the Requested_Delivery_Date field, choose Insert—>Field—>As Sibling.

    A new field is added to the navigation tree. The default field properties are displayed in the detail window.

12. Define the properties for the Requested_Delivery_Date field as described in the following table.

    In this section . . .	Do the following . . .
    Field Description	Enter Requested_Delivery_Date in the Name field.
    	Select Date: MM/DD/YYYY from the Type drop down list.
    Field Occurrence	Verify that the Once option button is selected.
    Field Attributes	Verify that String is selected in the Data Base Type drop down list.

    
     

    Note: The contents of the detail window for a field is determined by the Type setting. When you select a date type from the drop down list, the length is implicitly determined. Therefore, the Field Attributes: Termination properties are no longer displayed.

13. Click Apply.

    The properties of the field are updated.

14. Choose File—>Save to save your changes.

Step 3. Create the Shipping Address and Billing Address Groups

To create the shipping address and billing address groups:

1. Select any field in the navigation tree and choose Insert—>Group—>As Sibling.

   A new group is added to the navigation tree. The default group properties are displayed in the detail window.

2. Define the properties for the Shipping_Address group as described in the following table.

   In this section . . .	Do the following . . .
   Group Description	Enter Shipping_Address in the Name field.
   Group Occurrence	Verify that the Once option button is selected.
   Group Attributes	Verify that the None option is selected for Group Delimiter.

   
    

   Note: These values are determined by the analysis of the raw purchase order data shown in Figure  C-1.

3. Click Apply.

   The properties of the group are updated.

   Note: Because the only difference between the Shipping_Address group and the Billing_Address group is the name, you can use the Format Builder Duplicate feature to create the Billing_Address group.

4. Right click the Shipping_Address group.

5. Select Duplicate from the shortcut menu.

   A duplicate group (NewShipping_Address) is added as a sibling and becomes the current selection in the navigation tree.

6. Enter Billing_Address in the Name field and click Apply to update.

   Because the Shipping_Address and Billing_Address groups contain the same fields with the same attributes, we can define an Address group within the Shipping_Address group and set up the Address group within the Billing_Address group as a reference.

7. Select the Shipping_Address group in the navigation tree and choose Insert—>Group—>As Child.

8. Use the data in Figure  C-1 to create the Address group and click Apply to update the group properties.

9. Follow the steps outlined in Step 2. Create the Basic Information Fields and the data provided in Figure  C-1, to create the Street, City, State, and Zip fields as children of the Address group.

   Note: Once the Street field is created, you can use the Duplicate button to create the City and State fields.

10. To create a reference to the Address group, right-click the Address group under Shipping_Address, and then select Copy from the shortcut menu.

    The Address group properties (including the child fields) are copied and placed on the clipboard.

11. Right-click the Billing_Address group and select Paste As Reference from the shortcut menu.

    The Address reference, is pasted immediately after the Billing_Address group. The arrow in the icon is identifies the group as a reference group:

    
     

12. To make the Address group reference a child of the Billing_Address group, select the reference, and then choose Edit—>Demote.

    The Address reference becomes a child of the Billing_Address group.

13. Choose File—>Save to save your changes.

Step 4. Create the Remaining Items

Repeat the process of creating or duplicating fields and groups as required to complete the purchase order message format document. Use the analysis of the raw purchase order data presented in Figure  C-1 to determine the values you need to enter for each item. For assistance, refer to the \samples\di\po\po.mfl file.

When you finish entering the required items, your navigation tree should look similar to the one shown in Figure  C-2.

Figure C-2 Completed Navigation Tree for Purchase Order Sample

 

Step 5. Save the Completed Message Format

Choose File—>Save to save your completed message format.

The completed MFL document is saved. Depending on the Format Builder options currently set, the DTD and/or XML Schema that describes the content model captured in the MFL document are also saved.

To set up the Format Builder to automatically generate a DTD and/or XML Schema for your message format documents:

1. Choose Tools—>Options to display the Format Builder Options dialog box.

2. In the XML Content Model section at the bottom of the dialog box, check Auto-generate DTD and/or Auto-generate Schema, as required.

3. Click OK to update the options.

Now, whenever you save message format documents, Format Builder generates the specified file(s) for each message format document.

Step 6. Test the Message Format

To test the message format to identify any errors before using it to translate data:

1. Choose Tools—>Test to display the Format Tester dialog box.

2. Choose File—>Open Binary to display the Open dialog box.

3. Navigate to the samples/di/po directory.

4. Select the PO_01.DATA file and click Open.

   The binary data is displayed in the Binary window.

5. Click Translate—>Binary To XML.

   The content of the PO_01.DATA file is translated to XML based on the active MFL document. The XML output is displayed in the XML window.

   Note: To view a description of each translation step, choose Display—> Debug to open the Debug window, and then choose Translate—>Binary To XML. A message is displayed for each step of the process.

6. If the translated data appears to be correct, choose File—> Save XML.

7. Type the name PO.XML in the File name field, and then click Save to save the XML output.

 

---

Performing XML-to-Binary Translation

You can also use the Format Builder to create message definitions and test the translation of XML data to binary. The steps required to do this are essentially the same as those you follow to translate binary data to XML. To translate XML data to binary, first create an MFL description for the binary format. The purchase order sample files can be used to test the process as described in the following procedure.

1. Choose File—>Open from the Format Builder menu.

2. Select the purchase order message format document.

3. Click Open.

   The message format document is displayed in the navigation tree.

4. Choose Tools—>Test to display the Format Tester dialog box.

5. Choose File—>Open XML from the Format Tester menu.

6. Navigate to the samples\di\po directory.

7. Select the po.xml file and click Open. The XML data is displayed in the right pane.

8. Choose Translate—>XML to Binary.

   The XML data is translated, and the purchase order data is displayed, in binary format, in the left pane.

   Note: To view a description of each translation step, choose Display—> Debug to open the Debug window, and then choose Translate—>XML to Binary. A message is displayed for each step of the process.

9. If the translated data appears to be correct, choose File—> Save Binary.

10. Type the name (for example test_po.data) in the File name field, and then click Save to save the binary output.