        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
EDI Connect User's Guide
CHAPTER 4
In Composer, an action is similar to a programming statement in that it takes input in the form of parameters and performs a specific task. The actions you can create using the EDI component editor include not only the standard actions available in all Composer components (Map, Function, etc.) but special EDI-related actions. These are the subject of this chapter. (For information on standard actions, please see the chapters in the Composer User's Guide devoted to Actions.)
Within the EDI Component Editor, a set of instructions for processing XML documents or communicating with non-XML data sources is created as part of an Action Model. The Action Model contains all of your component's actions. It implements the logic of your component, performing all data mapping, data transformation, data transfer between (for example) mainframes and XML documents, and data transfer within and between components and services.
An Action Model is made up of a list of actions. For example, one EDI Action Model might process inbound data (in the form of an EDI transmission) into XML, optionally perform mappings on the XML, and then convert the XML data for outbound processing.
The Action Model mentioned above might be composed of several actions, including:
Inbound Actions:
Outbound Actions:
See further below for the complete list of EDI actions and their appearance in the menu tree.
Before getting into the details of EDI objects, their methods, it's helpful to know something about the structure of an EDI transmission. The contents of an EDI transmission can vary from a single EDI document type inside a single interchange format, to multiple document types inside multiple interchange formats. The more complex scenario is represented in the graphic below.
For maximum flexibility, exteNd Composer provides three EDI objects and eight Actions (four Inbound and four Outbound) for manipulating the various levels of EDI objects. In addition, each object exposes a variety of ECMAScript methods, which can be seen in the Expression builders available in various exteNd Composer actions. The ECMAScript objects allow easy manipulation of EDI elements.
The various EDI-related actions are described in more detail in the next section.
The Connect for EDI includes several actions that are specific to the EDI and are not included with a standard Composer install. From the Action Menu, you may select Inbound or Outbound Actions. The menu commands for the Inbound Actions are as follows:
The Outbound Actions are in their own submenu as shown below:
The following table explains the purpose of each of the Inbound and Outbound Actions.
The Input to an EDI Component must be a DOM containing the inbound EDI transmission in an XML CDATA section. The purpose of the Process EDI Transmission action is to extract the inbound transmission from the DOM and put it into the Transmission where more powerful actions and methods can be applied. To extract the transmission, you must supply the Source XPath of the CDATA section and a name with which others can refer to the Transmission. The easiest way to specify the XPath is to click on the XPath expression builder, open the tree elements of the DOM containing the transmission, and double-click the appropriate node.
Alternatively, you can write an ECMAScript expression that conditionally selects different DOM nodes depending on some other non-EDI criteria that might be present as data in the DOM or PROJECT Variables.
The Interchange Metadata tab on this dialog (see illustration below) has a list-builder to allow you to specify a list of different metadata templates that Composer can consult when attempting to parse the EDI transmission. The metadata definitions come from the EDI Interchange Metadata resources in your resource list. (See "Creating EDI Interchange Metadata" in the chapter on getting started with the EDI Connect.)
Once a Transmission has been created, you can perform a Get Next EDI Interchange action against it. The purpose of the Get Next EDI Interchange action is to extract an interchange from the Transmission and create an Interchange object. Then you can query the properties of the interchange such as its EDI Standard, SenderID 
UsageIndicator to determine additional processing paths in your Action Model. To extract the Interchange, you must supply the name of the target Transmission and a name to give to the extracted interchange. You cannot have more than one Interchange instantiated at a time from a Transmission. If you perform two Get Next EDI Interchange actions in a row, you will have one Interchange instance to work with, that being the second one from the Transmission.
Some EDI transmissions encapsulate groups of documents. For example, there may be a business process in which batches of documents move in parallel, analogous to "carbon copies" of a form being handed off to different departments: "The yellow copy goes to Accounting, the pink copy goes to Legal . . ." and so on. An interchange might contain groups of documents representing the various copies/versions of a transaction record that need to be passed through the system.
Not all EDI transmissions use this metaphor. Many times, an EDI transmission will merely wrapper one batch of documents, with all documents in the batch being of the same type.
The Get Next EDI Group action allows you to fetch groups one-by-one, presumably in advance of a loop operation where you'd perform some kind of processing on each document within the fetched group.
The setup dialog for this action is shown below.
Once an interchange object has been created, you can perform a Get Next EDI Document action against it. The purpose of the Get Next EDI Document action is to extract a Document from an Interchange and create a Document object. Then you can query the properties of the Document such as its Document Type, EDI Standard, Standard Version, SenderID and UsageIndicator to determine additional processing paths in your Action Model. To extract the Document, you must supply the name of the target Interchange and a name to give to the extracted Document. You cannot have more than one Document instantiated at a time from an Interchange. If you perform two Get Next EDI Document actions in a row, you will have one Document instance to work with, that being the second one from the interchange.
Once a Document object has been created, you can perform a Transform EDI to XML action against it. The purpose of the Transform EDI to XML action is to apply a Document Transform Resource against the document and create an XML representation of the document in a target DOM you specify. To perform a transform, you must supply the name of the EDI Document object you wish to transform, a target DOM and XPath, and the name of the Document Metadata to apply. You may also conditionally apply different Transform Resources by writing an ECMAScript expression for the Document Metadata. After executing this action, an EDI Document will be in XML format and can be shuttled to other exteNd Composer Components for backend processing such as inserting records into a CICS system or database.
To read EDI files off a disk or network, create an EDI File Read action and supply a URL for the source file:
Also specify an XPath or ECMAScript statement that will resolve to the destination where you want the EDI file placed. You may optionally specify that the file contents be wrappered in a CDATA section.
Before you can dispatch one or more EDI Interchanges from an EDI component, it must be contained in a Transmission. The purpose of the Create EDI Transmission action, is to create a Transmission (an Interchange Set object) into which you can subsequently insert EDI Interchanges. To create a Transmission, you must only supply a name for it.
In creating an outbound EDI Transmission, you will typically start with the transmission data in XML format. Before you can transform an EDI Document in XML format to its EDI Document representation, you must create an Interchange object to contain the EDI Document. The purpose of the Create EDI Interchange action, is to create an interchange object into which you can subsequently insert EDI Documents. To create an interchange, you must supply a name for it, a Source XPath identifying where to find the Interchange data, and an Interchange Metadata that identifies the EDI Standard (i.e. ANSIX.12 or EDIFACT) you wish to create. In determining the Interchange Resource, you can specify an ECMAScript expression that queries other sources of data to conditionally apply the appropriate standard.
As explained above (under Get Next EDI Group), some EDI transmissions support the notion of documents being aggregated into groups. If you are creating an outbound transmission and you want to be able to collect related documents into groups, this action will let you do it.
The setup dialog for the Create EDI Group action is depicted below.
Once an outbound Interchange object has been created, you can perform a Transform XML to EDI action against it. The purpose of the Transform XML to EDI action is to apply a Document Metadata against the XML, you specify and create an EDI representation of it in an Interchange you specify. To perform a transform, you must supply the name of the Source of the XML you wish to transform, a target EDI Interchange object, and the name of the Document Metadata to apply. If the Source XPath you specify returns more than one node, each of which contains EDI document data, then all the documents will be put into the target Interchange.
You may also conditionally apply different Transform Resources by writing an ECMAScript expression for the Document Metadata based on the data in the other DOMSs or PROJECT Variables.
Once an Outbound Interchange Set object has been created, you can perform a Put EDI Interchange action against. The purpose of the Put EDI Interchange action is to insert an Interchange into a Transmission in preparation for an outbound dispatch. To create a Put EDI Interchange action, you must supply the name of the Source Interchange and the name of the Transmission. Once you have added one or more Interchanges to a Transmission, it is ready to be dispatched from the EDI Component. Dispatching an EDI Transmission is usually accomplished by a Map Action from the Transmission to the Output DOM. The Map Action source is defined as an ECMAScript expression (i.e. theTransmissionName.getValue() ) and the target of the Map action specifies the Output DOM and an XPath that creates a CDATA section. Alternatively, you can Map the Interchange Set data to a temp DOM and dispatch it via an XML Interchange action.
If your outbound transmission will contain grouped documents, you can use this action to insert groups into the outgoing transmission. The setup dialog is shown below.
This action implements file writing (disk I/O). You specify the target location as a URL.
NOTE: Currently, only the file:// protocol is supported.
The setup dialog asks for an XPath (or optionally, an ECMAScript) expression pointing to the data source, and a URL and encoding algorithm for writing the output file. See below.
The Connect for EDI exposes a number of EDI-specific ECMAScript globals and object extensions, which are visible in Expression Builder picklists. The items are listed under the node labelled "EDI." There are three child nodes: Transmission, Interchange and Document and they are shown in the following screen.
In addition, you can obtain more complete online help by clicking Help in the lower left corner of the dialog.
An entire EDI transmission is represented by an Interchange Set object. For inbound processing, it will be the first EDI object created and holds the contents of the transmission. A Transmission, (or Interchange Set object) is referenced by a user-supplied name and provides the following two methods.
An Interchange object represents a collection of EDI documents of the same EDI Standard type, such as ANSI X.12. An Interchange object is referenced by a user-supplied name and provides the following methods:
A Document object represents an EDI message of a particular type, such as an ANSI 850 Purchase Order. A Document object is referenced by a user-supplied name and provides the following methods:
On occasion your EDI application may call for sending out an EDI Transmission wrapped in a CDATASection node in an XML document, the same way it currently must arrive in an inbound document. Below is a Custom Script function that will take the contents of an EDI Transmission and place it into an Output node of your choice.
/********************************************************************/
// function name: EDIintoCDATA( sourceData, targetEDINode )
// Description: creates a CDATA section on the specified XPath
// sourceData: (Required) A string that is data to put into the CDATA
// e.g. theTransmissionOjbect.getValue()
// targetEDINode: (Required) The XPath location to contain the CDATA
// section.
// The CDATASection will be appended to this element.
// Note: this must be a single node object and not a
// nodelist (i.e. use the item() method on the NodeList
// object:
// Output.XPath("rootelement/somechild").item(0)
// Returns: Nothing. The CDATASection containing the sourceData
// is appended to the specified targetEDINode
/******************************************************************/
function EDIintoCDATA( sourceData, targetEDINode )
{
// get the owner document of the targetEDINode to create a CDATASection
var theDoc = targetEDINode.getOwnerDocument();
// create the CDATASection
var theCDATASection = theDoc.createCDATASection( sourceData );
// attach the CDATASection
targetEDINode.appendChild( theCDATASection );
}
As noted previously, it's possible for a single EDI Transmission to contain a heterogeneous mix of documents encoded per different EDI Standards (such as ANSI X.12 and EDIFACT). The Connect for EDI provides four actions and three objects designed to handle both simple and complex Interchange Sets. To process an inbound EDI transmission, the following key activities need to be performed:
Create a Process EDI Transmission action with which to extract EDI Interchanges
Create an interchange object from which to extract EDI Documents
Transform a Document object into XML which can be fed to other exteNd Composer -Components or Services
To Process an Inbound EDI Transmission
Create an EDI component according to the instruction in "To create a new EDI Component" in Chapter 3 of this manual. Once created, the new EDI component editor appears.
On the Menu bar, click the Action menu and select New Action>Inbound>Process EDI Transmission. The Process Transmission dialog appears.
On the Action Parameters Tab, specify an XPath or ECMAScript expression that identifies the location of the Inbound EDI in a DOM. Then specify a name for the Target Transmission Name to be created.
Optionally, you may select the Interchange Metadata Tab and control which Interchanges within the Transmission are processed by placing Interchange Resources you created in the Active list. To ignore an interchange, place its Resource in the Inactive list. The result of a Process EDI Transmission action is to create an EDI Transmission with a name you specify.
Next create a Repeat While action. Since the Transmission may contain more than one Interchange, the Repeat While action allows you to iterate through the Transmission and extract Interchanges one at a time. Enter the While condition as theTransactionSet.hasMoreInterchanges() and click OK to close the dialog. The While condition will take advantage of the hasMoreInterchanges() method available on the Interchange Set object. Inside the While action you will create a Get Next Interchange action, which when executed will increment a pointer in the Transmission for the hasMoreInterchanges() method. Click OK to close the dialog.
With focus on the Loop Action node of the While action, click the Action menu and select New Action>Inbound>Get Next EDI Interchange. The Get Next EDI Interchange dialog appears. Enter the name of the Source Transmission created in the previous EDI action. Then specify a name for the Target Interchange that this action will extract from the interchange Set. Click OK to close the dialog.
Determine, at this point, whether your EDI transmission contains groups of documents, or just documents. The next steps assume that you are iterating over documents in an EDI interchange that contains only one type of document. If you are iterating over groups (and documents within groups), you will naturally have to create one more nested loop, utilizing the Get Next EDI Group action to loop over groups. You'd use exactly the same procedures outlined below, only looping on groups first, before dropping down to the loop-over-documents level.
Next create another Repeat While action. Since an Interchange may contain more than one Document, the Repeat While action allows you to iterate through an interchange and extract Documents one at a time. Similar to the Interchange Set object, an Interchange has a hasMore Documents() method. Enter the While condition as myInterchange.hasMoreDocuments() and click OK to close the dialog.
NOTE: If there is an error while processing a set of documents due to a "bad" document, exteNd Composer allows you to automatically skip that document and continue processing. You can accomplish this by wrapping the Get Next Document action in a Try/OnError action as shown in the illustration below.
If you want to see that an error has occurred, you must add a Function action that, for example, displays an alert message or writes to System.out. You would insert this action in the OnError branch of your Try/OnError clause. Do this by highlighting OnError in the action model, RMB, click on New Action>Function. Enter the appropriate ECMAScript expression, such as alert("My error message"), and click OK. The new Function action is added at that point in the action model when it executes, you will see an error dialog (alert) pop up. Obviously, this is a design-time-only tactic, since alert dialogs are not useful on the server at runtime. To write to System.out instead, enter the following expression in the Function action dialog:
java.lang.System.out.println("My error msg.");
This line of code will write a message to the Log pane of the Composer UI at design time and to the system output on the server at runtime.
Note that you can also insert a Log action (one of the standard Composer actions) inside the OnError branch in order to issue log messages. The advantage of this technique is that priority filtering of messages can be applied. (That is, only messages with an assigned priority above a certain threshold level will be logged. See the Composer User Guide for details.)
With focus on the Loop Action node of the While action, click the Action menu and select New Action>Inbound>Get Next EDI Document. The Get Next EDI Document dialog appears. Enter the name of the Interchange object created previously. Then specify a name for the Target EDI Document that this action will extract from the Interchange. Click OK to close the dialog.
Now that you have separated an Interchange from the Interchange Set and a Document from the Interchange, you are ready to transform the EDI into XML using a Transform EDI to XML action. With focus on the Loop Action node of the While action, click on the Action menu and select New Action>Inbound>Transform EDI to XML. The Transform EDI to XML dialog appears. Enter the name of the extracted Document you wish to transform, a Target XPath for the results and the name of a Document Transform Resource to use.
NOTE: The Interchange Transform Resource can be an ECMAScript expression allowing you to conditionally pick a transform resource based on other related information.
There is an Options Section which allows you to select additional criteria by clicking on the checkbox.
Format numeric fields to include decimal point - If checked, Inbound Implied Decimal Fields have a decimal point added to them at the appropriate spot. For example, a format of N2 and a data value of "100" yields "1.00." If unchecked, the decimal point is not added.
NOTE: Please refer to Appendix D on Data Type Validation Rules for more information as well as Appendix C on Metadata and Inbound Processing.
The preceding steps have now gotten a single EDI document into XML which can now be supplied to other exteNd Composer Components or Services before the next EDI document/Interchange is extracted in your loop processing. With focus on the Loop Action node of the inner While action, create a Component action and pass in the results of your EDI transform. Your action model should resemble the one below.
NOTE: The Map action in the second While loop uses the getInterchangeInfo() method of the Interchange object to transform Interchange related information and map it to the DOM that will eventually hold the transformed document.
As noted in the previous section, it's possible for a single EDI Transmission to contain a complex mixture of documents encoded in different EDI Standards. exteNd Composer provides four simple actions and three objects designed to handle both simple and complex Interchange Sets. To process an Outbound EDI, the following key activities need to be performed:
To Process an Outbound EDI Transmission
Create an EDI component according to the instruction in "To create a new EDI Component" in Chapter 3 of this manual. Once created, the new EDI component editor appears.
On the Menu bar, click the Action menu and select New Action>Outbound>Create EDI Transmission. The Create EDI Interchange Set dialog appears. Enter a name for the Transmission. The Transmission is the container for an entire EDI transmission that may contain multiple Interchanges and Documents. Click OK to close the dialog.
On the menu bar, click the Action menu and select New Action>Outbound>Create EDI Interchange. The Create EDI Interchange dialog appears. Enter the name you wish to give the Interchange object. Then enter the Source XPath where exteNd Composer will find the information to construct the Interchange. Finally, enter the name of the EDI Transform Resource in the Metadata field for the Interchange object.
NOTE: The Transform Resource can be an ECMAScript expression allowing you to conditionally pick a transform resource based on other related information. Click OK to close the dialog.
On the Menu bar, click the Action Menu and select New Action>Outbound>Transform XML to EDI. The Create Transform XML to EDI dialog appears. Enter the Source XPath of the XML data to transform into an EDI Document object. The XPath location you specify and all its descendants will be transformed into a Document object. Enter the name of the Target Interchange to insert the Document object into. Finally, Enter the name of the Document Transform Resource in the Metadata field to use in creating the Document object.
There is an Options Section which allows you to select additional criteria by clicking on the checkbox. It includes the following choices:
Auto pad/truncate alphanumeric fields - If checked, AN Field processing includes padding with blanks on the right to match MinLength attribute and truncating from right to match MaxLength attribute, If unchecked, no padding or truncating is performed.
Auto pad/truncate numeric fields - If checked, N*Field processing includes padding with zeroes on the left to match MinLength attribute and truncating fields from left to match MaxLength attribute. If unchecked, no padding or truncating is performed.
Treat numeric fields as requiring implied decimal point fixup - If checked, N* Field processing assumes XML input field has a decimal point in the correct place and uses that information to properly format EDI. For example, an N1 formatted field with a value of "1.0" results in "10.". If unchecked, the data is moved into EDI unchanged.
NOTE: Please refer to Appendix D on Data Type Validation Rules for more information.
Now that you have a Document object inside a Interchange object, you are ready to insert the Transmission. On the Menu bar, click the Action menu and select New Action>Outbound>Put EDI Interchange. The Put EDI Interchange dialog appears. Enter the name of the Interchange to insert. Then Enter the name of the Transmission. Click OK to close the dialog.
The preceding steps have now gotten a single EDI Document into a single Interchange and the Interchange into the Transmission. All it takes now is a single Map Action to extract all the EDI data from the Transmission and put it into an XML DOM which can then be supplied to other exteNd Composer Components or Services for final outbound processing. The Map action as shown, uses the getValue() method available on the Transmission (an Interchange) object. Your action model should follow the general pattern of the one shown.
In addition to the Map Screen, you have all the standard Basic and Advanced Composer actions at your disposal as well. The complete listing of Basic Composer Actions can be found in Chapter 7 of the Composer User's Guide. Chapter 8 contains a listing of the more Advanced Actions available to you.
This section describes common errors you may see while executing the animation tools.
Warning: Error Executing Component. Can't Extract Next Interchange from the Set
One cause of this error may be that the wrong Interchange Resource is being used to extract an Interchange from an Inbound EDI. The Process EDI Transmission action allows you to control which EDI Standards are applied against an EDI when extracting interchanges. These options are set on the Interchange Metadata tab of the Process EDI Transmission action. If the Inbound EDI is in EDIFACT format, but the Interchange Resource being applied is ANSIX12 then this error can occur. Change the Applied list of standards to include the one needed by the Inbound EDI.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
