Setting up the EDI environment

As mentioned in the previous section, you can specify many attributes that pertain to the exchange of EDI interchanges. For example, you can change the system-supplied envelope profiles, you can define specific envelopes to be used for certain connections, you can set up control numbers that are assigned to the various parts of an interchange, and you can set connection profiles so that the same interchange can be delivered in a different way. These tasks are described in this section.

Enveloper

The Enveloper is the component that gathers a set of transactions to be sent to a participant, wraps them in an envelope, and sends them. You schedule the Enveloper (or accept the default schedule) to indicate to WebSphere Partner Gateway when you want the Enveloper to look for transactions waiting to be sent. You can also update the default values for the lock time, queue age, and batch mode.

Note: Setting up the Enveloper is optional. If you do not change any of the values for the Enveloper, the system-supplied default values are used.

Locking

Each instance of the Document Manager has its own Enveloper. If you have two Document Managers installed on your system, you have two Envelopers. It is possible, therefore, for two (or more) instances of an Enveloper to attempt to poll transactions waiting to be enveloped. To ensure that a given transaction is polled by exactly one Enveloper, locks are used. Locks make sure that if multiple Envelopers are involved, only one Enveloper polls and processes a given transaction. Envelopers poll simultaneously but work on different transactions.

A time limit is set on the lock. The default value for an instance of the Enveloper to hold the lock is 240 seconds.

If the Enveloper has to wait for the lock, it is placed in a queue. The maximum queue age (the length of time the Enveloper should wait) is 740 seconds.

Typically, you will not need to change any of the default values for locking.

Batch mode

Multiple documents that arrive in one file are split, according to the splitter handler you have set up for that type of document. (Configuring splitter handlers, which is part of defining targets, is described in Modifying configuration points.) One of the attributes of the splitter handler is BCG_BATCHDOCS. When BCG_BATCHDOCS is set to on (the default value), the splitter adds batch IDs to the documents after the documents are split.

The Enveloper has an attribute for batch mode, which is related to the BCG_BATCHDOCS attribute. If batch IDs were assigned to the individual documents, and if you accept the default value (on) for batch mode, the Enveloper makes sure that all documents that arrive together in the same file are processed before it envelopes and sends them, to ensure that the transactions are enveloped together. For example, suppose five XML documents arrive in the same file. The XML documents are to be transformed into EDI transactions and are intended to be delivered to the same recipient. After only three of the documents have been transformed, the Enveloper begins its scheduled polling for transactions. If batch mode is selected, the Enveloper does not process (envelope) the three transactions that are ready. Instead, it waits until all five transactions have finished processing before it envelopes and sends them. The transactions are placed in the same envelope, unless the applicable EDI standard prevents this.

Modifying the default values

To modify any of the default values for the Enveloper, perform the following steps:

  1. Click Hub Admin > Hub Configuration > EDI > Enveloper.
  2. Click the Edit icon.
  3. Enter new values for Maximum Lock Time (Seconds) and Maximum Queue Age (Seconds) if you want more or less time assigned to these attributes.
    Note: Typically, you will not need to change any of the default values.
  4. If you want to turn off batch mode, remove the check next to Use Batch Mode.
  5. If you want to change how often the Enveloper checks for transactions waiting to be sent, perform one of the following sets of tasks:
  6. Click Save.

Envelope profiles

An envelope profile determines values that are placed in specific elements of the envelope. You assign the envelope profile to EDI transactions in the document flow definition Envelope Profile attribute. WebSphere Partner Gateway provides a predefined envelope profile for each supported standard (X12, EDIFACT, or UCS). You can use these predefined envelopes directly, you can modify them, or you can copy them into new envelope profiles. The steps for modifying an envelope profile or creating one are described in Modifying the default values.

The Envelope profiles have one field for each element in the envelope standard. The profiles provide literal or constant data for building header or trailer segments for transaction sets, messages, functional groups, and interchanges. You supply only the values that need to be populated and for which a value is not provided by another source.

The field names are designed to make cross-referencing easy. For example, the field UNB03 is the third data element in the UNB segment.

As described in Envelope attributes, attributes set anywhere else take precedence over the values you set in the envelope profile. Some of the attributes can be overridden in document flow definition-related attributes or maps.

Envelope attributes

Envelope attributes can be set at several different points during the configuration process, and they can also be set in the transformation map associated with the documents. For example, the Data Interchange Services client mapping specialist can specify the CtlNumFlag property when defining a map. This property can also be set as part of the envelope profile (in the Control Numbers by Transaction ID field). Any attributes set in the transformation map override the related values set at the Community Console. For example, if CtlNumFlag is set in the transformation map as N (no) and you enter a value of Y (yes) in the Control Numbers by Transaction ID field, the value of N is the one that is used.

Other envelope profiles can be set at the protocol level (from the Manage Document Flow Definitions page or from the B2B capabilities page associated with a participant), or they can be set as part of the connection. The order of precedence is outlined in the following list:

  1. Properties set in the transformation map take precedence over the associated attributes set in the Community Console.
  2. Attributes set at the connection level take precedence over those set at the B2B capabilities level.
  3. Attributes set at the B2B capabilities level take precedence over those set at the document flow definition level.
  4. Attributes set anywhere (either in the transformation map or at the document flow definition, B2B capabilities, or connection level) take precedence over the values set in the envelope profile.

For a list of transformation map properties and their associated Community Console attributes, see Data Interchange Services client properties.

Modifying the default values

Envelope profile attributes provides a table showing the default values used for each EDI standard envelope attribute if you do not enter a value in the profile or if you do not create a profile. Make sure the envelope profiles you are using supply any mandatory elements that are not provided by the system at runtime.

To set up an envelope profile, perform the following steps:

  1. Click Hub Admin > Hub Configuration > EDI > Envelope Profile.
  2. Perform one of the following sets of steps:
  3. The General button is chosen by default. You can enter a value for any field except ENVTYPE, which is prefilled with the standard you chose in step 2d.

    You can add values for the following fields:

    The fields for the General envelope profile are the same across all three standards, except that EDIFACT has an additional field: Create Groups for EDI.

    If you have made any changes to the General page, click Save.

  4. To specify values for the interchange, click Interchange. A new set of fields is displayed on the page. The fields vary, depending on the EDI standard. Note that some of the values are already filled in or will be filled in at run time.

    If you have made any changes to the Interchange page, click Save.

  5. To specify values for the groups within the interchange, click Group. A new set of fields is displayed. The fields vary, depending on the EDI standard.

    The fields on this page generally define the sender and receiver of the group.

    If you have made any changes to the Group page, click Save.

  6. To specify values for the transactions within a group, click Transaction or, in the case of EDIFACT, Message. A new set of fields is displayed. The fields vary, depending on the EDI standard.

    If you have made any changes to the Transaction page, click Save.

  7. Click Save.
  8. Repeat steps 2 through 7 for any other envelope profiles you want to define or change.

After an envelope profile is defined, it is listed on the Envelope Profiles list. From the list, you can select the profile and then click the Where Used icon to determine the connections using the profile.

Connection profiles

You use connection profiles with de-enveloped transactions and with EDI interchanges created by the Enveloper. For transactions, the connection profile determines how the transaction is processed after it is de-enveloped. For interchanges, the connection profile determines how the interchange is delivered.

The following table shows the connection profile attributes, their corresponding field names on the Connection Profile details page, and whether they apply to interchanges or to transactions:

Table 14. Connection profile attributes
Attribute Field name EDI interchange EDI transaction
Connection Profile Qualifier1 Qualifier1 X
Interchange usage indicator EDI Usage Type X
Group application sender identifier Application Sender ID X
Group application receiver identifier Application Receiver ID X
Group application password Password X

Transactions

When an EDI Interchange comes into WebSphere Partner Gateway, the first action is typically to de-envelope the interchange into the individual transactions. When the transactions are created, the De-envelope action sets the Interchange usage indicator and group information (Group application sender identifier, Group application receiver identifier, and Group application password) in the transaction metadata. Each transaction is then re-processed by WebSphere Partner Gateway in its own workflow.

Suppose you have two transactions of the same type (for example, 850) that need to be handled differently, depending on the group they were in or the values of their Interchange usage indicators. If the Usage Indicator is Production (P), for example, you might want one map (A) to be used, and if the Usage Indicator is Test (T), you want a second map (B) to be used. Two similar connections are required for this 850 transaction, with the only difference being that one connection uses map A and the other connection uses map B.

Because the transactions are otherwise the same (they have the same source and target participant, package, protocol, and document type), the Document Manager needs a way to determine which connection to use. It does this by matching the connection profile attribute you set to the transaction metadata. In this example, if you create two connection profiles -- one (CPProduction) with the EDI Usage Type set to P and the other (CPTest) with the EDI Usage Type set to T, the Document Manager matches the transaction with the Usage Indicator of P with the CPProduction profile. It then knows to use map A to translate the transaction.

The example in this section used the Interchange usage indicator attribute, but you can also use the Group sender application identifier, Group receiver application identifier, and Group application password attributes as the distinguishing factor for a transaction.

Interchanges

For interchanges, you use the Connection Profile Qualifier 1 attribute.

For example, suppose you are in the midst of migrating your company from using a VAN (None packaging) or the Internet (AS2 packaging). You want 840 (Request for Quote) transactions to use the VAN and 850 (Purchase Order) transactions to use the Internet. You set up two participant connections, both with the same source interchange but with different targets (one with None packaging and the other with AS2 packaging). The connection profiles help distinguish between the two connections.

Setting up the connection profile for interchanges involves several steps. These are the steps you would perform to create two connection profiles for the example:

  1. Create two connections for the transactions. Set the Connection Profile Qualifier 1 attribute on the "To" side of both connections. The value should be meaningful (for example, ConNone and ConAS2).
  2. Define two connection profiles (for example, CPNone and CPAS2), each with the Qualifier1 value set to match the Connection Profile Qualifier1 attributes you set in step 1 (ConNone and ConAS2).
  3. Create two connections for the interchange. Each connection has the same source packaging (N/A) but different target packaging (None and AS2). The participant connection with the connection profile CPNone will have the target gateway set to the FTP Scripting gateway that can connect to the VAN. The participant connection with the connection profile CPAS2 will have the target packaging set to AS.
  4. Associate the appropriate connection profile with each one.

The Enveloper uses the Connection Profile Qualifier 1 attribute on the "To" side of the participant connection as an envelope break point. Therefore, transactions having different values for the Connection Profile Qualifier 1 attribute will be enveloped in different envelopes. When you set different values for the transactions, the Enveloper will never envelope the 840 and 850 transactions in the same interchange.

When the Document Manager looks up the connection, the two possible connections are found, but the one with the matching connection profile is used.

Setting connection profiles

Setting connection profiles is optional. If you have no need to have more than one connection for each type of document you will be exchanging for a participant, skip this section.

To set up a connection profile:

  1. Click Hub Admin > Hub Configuration > EDI > Connection Profiles.
  2. Click Create Connection Profile.
  3. On the Connection Profile Details page, type a required name for this connection profile.
  4. Type an optional description of the profile.

    The name and description (if you enter a description) will appear on the Connection Profile List page.

  5. Optionally, enter a value for Qualifier 1 to indicate the value that determines which connection to use for an EDI interchange. See Interchanges for an example of using Qualifier 1.
  6. Optionally, enter a value for EDI Usage Type to indicate whether this is a test, production, or information interchange. See Transactions for an example of using EDI Usage Type.
  7. Optionally, enter a value for Application Sender ID to indicate the application or company division associated with the sender of the group.
  8. Optionally, enter a value for Application Receiver ID to indicate the application or company division associated with the recipient of the group.
  9. Optionally, enter a value for Password if a password is required between the application sender and application receiver.
  10. Click Save.

For those transactions that you want to put into certain interchange envelopes, you can specify the Connection Profile Qualifier 1 attribute value that corresponds to the connection profile with the same value for attribute Qualifier 1. The Connection Profile Qualifier 1 attribute can be set at the protocol level of a document flow definition (for example, you could edit the attributes of the X12V5R1 protocol on the Manage Document Flow Definitions screen to indicate which connection profile to use by clicking the corresponding Connection Profile Qualifier 1 attribute value). Then when you activate the interchange connection, associate the connection profile by clicking the Connection Profile button and selecting the profile from the list.

Control numbers

The Enveloper uses control numbers to provide unique numbering for interchanges, groups, and transactions within an envelope. Control numbers are established for the Community Manager and for participants. When the exchange of documents takes place, control numbers are also generated for the pair of participants.

For each participant that has EDI B2B Capabilities, there is a set of seed initialization values for control numbers. These values are used the first time an EDI interchange is created and sent between a participant pair. The initialization values apply to the participant to whom the interchange is sent. After a document has been sent from one participant to another, the last numbers used can be viewed in the Current Control Numbers page. There can be several entries for a given participant pair if Control Numbers by Transaction Id is set to Y. After an entry exists, it is used to generate new control numbers.

As part of control number initialization, you can use masks to modify the normal control number creation by the Enveloper. Masks are used to base the control number on either the interchange or group control number. The mask descriptions follow. Replace the n in the edit mask with the number of bytes you wish to use to create the control number value. See Table 15 for descriptions of the available codes:

Table 15. Control number masks
Code Control Number Description
G Transaction The transaction control number is the same as the group control number. Only one transaction for each group is allowed.
Gn Transaction n bytes are taken from the group control number. The remainder of the transaction control number is padded with zeros to its maximum size. Only one transaction for each group is allowed.
C Group, Transaction The remaining bytes in the group or transaction control number field are used to maintain a control number for this participant.
V Group, Transaction An incrementing value is used so that the first group or transaction has a value of 1, the second a value of 2, and so on.
Vn Transaction An incrementing value n bytes long is used so that the first transaction has a value of 1, the second a value of 2, and so on.
GnC Transaction n bytes are taken from the group control number and the remaining bytes in the transaction control number field are used to maintain a control number. The number of positions left determines the maximum value of the control number. For example, G5C leaves four positions; therefore the maximum value is 9999. The control number cycles from the maximum value to 1.
GnV Transaction n bytes are taken from the group control number. For the remaining bytes in the transaction control number field, an incrementing value is used so that the first transaction has a value of 1, the second a value of 2, and so on.
GnVm Transaction n bytes are taken from the group control number. For the remaining bytes, up to m bytes in the transaction control number field, an incrementing value is used so that the first transaction has a value of 1, the second a value of 2, and so on.
I Group, Transaction The group or transaction control number should be the same as the interchange control number. Only one group is allowed for the interchange, and only one transaction is allowed for the group or interchange.
In Group, Transaction n bytes are taken from the interchange control number. The remainder of the group or transaction control number field is padded with zeros to its maximum size. Only one group is allowed for each interchange, and only one transaction is allowed for each group.
InC Group, Transaction n bytes are taken from the interchange control number. The remaining bytes in the group or transaction control number field are used to maintain a control number. The number of positions left determines the maximum value of the control number. For example, I5C leaves four positions; therefore the maximum value is 9999. The control number cycles from the maximum value to 1.
InV Group, Transaction n bytes are taken from the interchange control number. For the remaining bytes in the group or transaction control number field, an incrementing value is used so that the first group or transaction has a value of 1, the second a value of 2, and so on.
InVm Transaction n bytes are taken from the interchange control number. For the remaining bytes, up to m bytes in the transaction control number field, an incrementing value is used so that the first transaction has a value of 1, the second a value of 2, and so on.
InGm Transaction n bytes are taken from the interchange control number, and a maximum of m bytes are taken from the group control number. If n plus m is greater than 9, only 9 - n bytes are taken from the group control number. For example, using I4G6, 4 bytes are taken from the interchange
InGmC Transaction n bytes are taken from the interchange control number, and m bytes are taken from the group control number. The remaining bytes in the transaction control number field are used to maintain a control number. The number of positions left determines the maximum value of the control number. For example, I2G4C leaves three positions; therefore the maximum value is 999. The control number cycles from the maximum value to 1.
InGmV Transaction n bytes are taken from the interchange control number, and m bytes are taken from the group control number. For the remaining bytes in the transaction control number field, an incrementing value is used so that the first transaction has a value of 1, the second a value of 2, and so on.
InGmVo Transaction n bytes are taken from the interchange control number, and m bytes are taken from the group control number. For the remaining bytes, up to o bytes in the transaction control number field, an incrementing value is used so that the first transaction has a value of 1, the second a value of 2, and so on.

Control number initialization

To configure control numbers that the Enveloper will use, perform the following steps:

  1. Click Hub Admin > Hub Configuration > EDI > Control Number Initialization.
  2. Type a participant's name and click Search or click Search without entering a name to display all participants. If you leave EDI-capable checked, you limit the search to those participants that have EDI document B2B capabilities. If you remove the check, you search all participants.
  3. Click the View details icon next to the participant.
  4. The participant's current control number assignments (if any) are listed on the Control Number Configuration Details page. Click the Edit icon to add or change the values.
  5. Type (or change) the value next to Interchange to indicate the number you want to use to initialize control number generation for interchanges.
  6. Type (or change) the value next to Group to indicate the number you want to use to initialize control number generation for groups. Alternatively, you can click Mask and type a mask to be used instead of a fixed value.
  7. Type (or change) the value next to Transaction to indicate the number you want to use to initialize control number generation for transactions. Alternatively, you can click Mask and type a mask to be used instead of a fixed value.
  8. Click Save.

Current control numbers

For a given participant-pair that already has data in the control table, you can change the control number generation. You can:

Note: Resetting control number generation or editing a group or mask should be done with caution so that numbers out of sequence or duplicate control number problems do not occur. You might want to perform either of these actions during test phase or if a partner specifically requests different control numbers.

To determine which participants have control numbers assigned (and to determine what those numbers are), you use the Current Control Numbers feature.

  1. Click Hub Admin > Hub Configuration > EDI > Current Control Numbers.
  2. Perform one of the following sets of steps:

Copyright IBM Corp. 2003, 2005