Working with Trading Partner Agreements

Trading Partner Agreements

Trading Partner Agreement (TPA) definitions are a set of parameters that help you tailor how documents are exchanged between two trading partners. These can be any two partners, not necessarily the hub and a spoke.

TPAs contain transaction-dependent information that are specific to transactions between two trading partners. TPAs augment profiles and offer a flexible way to process and manage the documents exchanged between two trading partners.

Each TPA contains specific information about how documents must be exchanged between two trading partners:

• The partner that represents the sender of the documents.
• The partner that represents the receiver of the documents.
• An agreement ID that identifies the type of TPA (for example, TPAs for EDI business documents use the agreement ID EDITPA).

You can have multiple TPAs for a pair of trading partners. For example, the following two TPAs for partners A and B are used by the EDI business document type. TPA 1 is used when partner A is the sender and partner B is the receiver and TPA 2 is used when the partner B is the sender and partner A is the receiver:

webMethods.io B2B does not use TPAs when determining the processing rules to use for a document. Rather the parameters that you specify in the TPA are available for your own use. For example, you can access the TPA information from integrations called by a processing rule. Accessing this information allows you to build a document exchange application that uses the TPA to tailor the exchange of documents between partners.

Define the parameters in the TPA based on the document exchange processing that you want to design. The set of parameters can be different for different types of TPAs. For example, you might use TPAs for partners that exchange documents using RNIF-PIP that contain the parameters defined by the RNIF-PIP documents. Other partners might exchange documents using EDI, and for those partners you create EDITPAs that contain parameters defined by the EDI documents.

TPA Statuses

When you define a TPA, you set the agreement status. This status indicates the status of the TPA agreement between the receiver and sender. The status can be proposed, agreed, or disabled. For example, if RNIF-PIP document tries to use a TPA whose status is disabled, it acts as if there is no TPA. If you create an application that uses TPAs, it should check and honor the disabled status.

TPA Data

The TPA data contains application-specific variables to tailor the processing of documents exchanged between the sender and receiver. Specify the values for the required parameters when you create a user-defined TPA.

TPA Templates

TPA Templates are configuration structures that are used as references to create a TPA definition by reusing configurations. There are two types of TPA templates:

• System TPA Templates. A few predefined templates are available with webMethods.io B2B by default. These templates enable the partners using certain types of business documents to function as intended. These templates cannot be modified. For example, RNIFV1, EDIV1 and so on.
• Custom TPA Templates. You can also create your TPA templates based on specific document exchange parameters. The templates can be created in one of the following ways: By referring to a document type in webMethods.io Integration under the specific project, or by referring to document type in Cloud Container under the specific solution.

TPA Definition

TPA definitions are also of two types:

• System TPA. These TPAs enable partners using certain types of business documents to make them function as intended. The TPA data is editable, but the TPA definition cannot be altered.
• User-defined TPA. These TPAs are created by users in webMethods.io B2B and completely modifiable.

webMethods.io B2B lets you create the following TPA types:

• Partner-specific TPA. It is specific to the sender and the receiver. A partner-specific TPA contains partner-specific variables used by only the particular pair of trading partners (sender and receiver) that are defined in the TPA. For example, for trading partners A and B, you might have one TPA where trading partner A is the sender and B is the receiver and for trading partners C and D, you might have one TPA where trading partner C is the sender and D is the receiver.

  The same partner-specific TPA can be used even when the sender acts as a receiver and the receiver acts as a sender.

• Sender-specific TPA. Specifies a sender but leaves the receiver defined as unknown. The value unknown equates to any, thus allowing any partner to be a receiver.

• Receiver-specific TPA. Identifies the receiver but leaves the sender defined as unknown. The value unknown equates to any, thus allowing any partner to be a sender.

Creating Trading Partner Agreement Templates

Trading Partner Agreement (TPA) Templates are configuration structures that are used as references to create a TPA definition by reusing configurations. You can also create a custom template to suit your business needs.

To create a TPA template

1. In webMethods.io B2B, go to Agreements > TPA Templates > Add Template.

2. In the Create TPA template dialog box, specify the following values:

   Fields	Description
   Name	Specify a unique name for the template.
   Description	(Optional). Type a short description.
   Refer to	Select the system through which you want to access the document type of the TPA.
   	webMethods.io Integration. Specify the Project name and the Document type for which you want to create the TPA template. Note: Based on the type of selection in the Refer to field, the template structure from webMethods.io Integration appears as a preview, so you can be aware of the input fields in the template before creating a template.

3. Click Create.
   Related definitions indicate how many TPAs utilize this template for document exchange.
   

When you create a custom TPA with system templates (such as EDIV1), the fields are set with the corresponding default values from the system templates. Although those default values do not appear on the UI, the TPA definition will work based on the preset values. However, the default value will be overwritten when you set a new value for any of the parameters. For example, if you create a custom TPA EDITPA between two partners and do not set the value for splitOption, the field is set with Transactions which is the default value.

Next Steps

Edit Template Reference

You can update all the values in a template and reuse it for a different set of configurations.

Delete Template

You can delete only the custom templates. You cannot delete system templates such as EDIV1 and RNIFV1.

Caution You will lose the reference to the custom template you delete, if least one TPA definition refers to it, leading to transaction failures. Ensure that the TPA definitions referring to the custom template are not in Agreed state to avoid a runtime failure of this configuration. Examine the Related Definitions column to see the TPA Definitions that refer to this template.

Creating Trading Partner Agreement Definitions

You can create Trading Partner Agreement (TPA) definitions in webMethods.io B2B.

To create a TPA definition

1. In webMethods.io B2B, go to Agreements > TPA Definitions > Add Definition.

2. In the Add TPA definition dialog box, specify the following values:

   Fields	Description
   Agreement name	Name of the Trading Partner Agreement. To create an agreement between business partners that exchange:
   	EDI business documents, ensure that you select EDITPA as the agreement name.
   	RNIF-PIP business documents, ensure that you select the document type name as the agreement name.
   Status	Status of the TPA. The possible values are:
   	Proposed. When the agreement status is proposed, a TPA is in a draft status. You can modify the TPA fields and data input.
   	Agreed. An agreed status means that the TPA is final. When the agreement status is agreed, the data statuses take effect.
   	Disabled. The disabled status means the TPA should not be used. If you are using a TPA and no longer want to use it, you can disable it. When you disable a TPA, the TPA remains in the webMethods.io B2B, but is considered inactive. Later, if you decide that you need the TPA, you can change the agreement status to proposed or agreed.
   Sender	Select the sender from a list of partners. For EDI, to create a template that you will duplicate to create other TPAs, use the default value Unknown.
   Receiver	Select the receiver from a list of partners. For EDI, to create a template that you will duplicate to create other TPAs, use the default value Unknown.
   Description	(Optional). Type a short description.
   Template structure	Select a TPA template as reference while creating the TPA definition. TPA template defines the TPA data specific to the business-document type or a processing that is specific to a sender-receiver pair. Depending on the template structure you select, the input form for that template structure appears, so you can specify the values in the TPA definition as shown in the image.
   Data Status	When the TPA’s agreement status is Agreed, it indicates whether the values for the TPA data that are defined in the TPA template can be modified. The possible values are:
   	Mutable. You can modify the values of TPA data when the TPA is in proposed and disabled states.
   	Immutable. You can modify the values of TPA data only when it is in the proposed state.

3. Click Create.

You can copy the system-defined TPA definitions and the user-defined TPA definitions to create new ones. And import and export the TPA definitions along with the referenced templates.

Next steps

• Go to Monitoring > Document submission.
• Test the TPA by submitting an appropriate business document type.
• Track the processing of the transaction from the Course of transaction section.
  You can also modify the TPA definition after creating one or delete those that you do not use. To load and save the TPA data, see How Do I Load and Save Trading Partner Agreement Data?

How Do I Load and Save Trading Partner Agreement Data?

This use case explains how to load and save the TPA data.

The use case starts when you have the TPA data to either load or save. The use case ends when you either load the TPA data from your instance using a file, or when you download the TPA data on your local instance.

You can load and save data in JSON format but can only load the XML data and not save the data in XML format.

Before You Begin

Ensure that you have:

• An existing project in webMethods.io Integration.
• TPA data to load or TPA data in the product instance that you can save.

To Upload the TPA data

1. In webMethods.io B2B, go to TPA > TPA definitions.
2. Click Upload TPA data to load the TPA data from a file.
3. Click Upload.

To save the TPA data

1. In webMethods.io B2B, go to TPA > TPA definitions.
2. Click Save to disk to save the TPA data to a file.
3. Click Save.

Next Steps

When you load the TPA data in JSON format, if the values mentioned for any of the TPA data variables are not supported in webMethods.io B2B, then you must handle the errors in your business logic at the time you create the integration.

How Does the EDI TPA Work?

An EDI trading partner agreement (EDI TPA) definition is a set of variables designed specifically to handle EDI document exchange between two trading partners. EDITPA is interpreted by webMethods.io B2B to process certain agreements used by the partners. It can also be used in the getTPA operation in webMethods.io Integration.

When there is no partner-specific EDI TPA, a default EDI TPA is used. A Default EDI TPA. has a sender and receiver set to unknown. webMethods.io B2B uses the values in the default EDI TPA if a partner-specific EDITPA does not exist, or if the value in the partner-specific EDI TPA is null or empty.

webMethods.io B2B follows a precedence to select the EDITPA type during EDI business document processing:

Ways to create a partner-specific EDITPA:

• Copy the default EDI TPA and change variable values.
• Copy a similar partner-specific EDI TPA and change variable values.
• Create an EDI TPA from scratch.

See EDI TPA Parameters for a complete list.
For an example tutorial on how to tune the EDITPA parameters, see here.

How Does the RNIF TPA Work?

RosettaNet is an implementation of the RosettaNet Implementation Framework (RNIF) 2.0. RNIF enables you to implement open and common e-business Partner Interface Processes (PIPs) and exchange RosettaNet documents with your partners. Business partners use RosettaNet PIPs to execute business-to-business transactions and processes.

PIPs are organized into one of seven categories according to their high-level business area, such as, product information, order management, or inventory management. Subcategories further define the business segments and process category. Each of these processes define the specific flow of the process model and structure of the business document.

RosettaNet TPA definition contains process model templates for the different types of PIPs that you can implement. RNIFTPA is interpreted by webMethods.io B2B to process certain agreements used by the partners. You can use webMethods.io Integration to modify these process model templates as needed to create the PIPs.

See RNIF TPA Parameters for a complete list.

How Does the AS4 TPA Work?

The ebXML Messaging Services (ebMS) specification was developed to provide organizations a standard to exchange business messages over the Internet. AS4 is a simplified subset of ebMS 3.0 specification that provides guidelines for payload independent exchange of documents using web services.

AS4 is an implementation of the AS4 ebHandler conformance profile specified in the AS4 Profile. Using AS4 , you can exchange messages, independent of payload type, across your trading network.

For the list of all the AS4 TPA parameters, see Working with AS4 TPA Parameters.

AS4 TPA includes Message Exchange Patterns (MEP). For details see Message Exchange Patterns.

Message Exchange Patterns

AS4 includes Message Exchange Patterns (MEP). An MEP defines how you can exchange messages between two trading partners.

AS4 supports the following ebMS MEPs for both the sender and the receiver:

• One-Way/Push: Sends a user message to a trading partner.
• One-Way/Pull: Sends a pull signal to a trading partner to receive a user message.
• Two-Way/Sync: Synchronously exchanges messages between two trading partners.
• Two-Way/PushPull: Pushes a request user message to a trading partner and uses a pull signal to receive a reply user message.
• Two-Way/PushPush: Asynchronously exchanges messages between two trading partners.

One-Way/Push MEP

The One-Way/Push MEP sends (push) a user message to a trading partner. The user message is carried over a one-way or a two-way underlying protocol.

One-Way/Pull MEP

The One-Way/Pull MEP sends a pull signal to a trading partner to receive a user message. The initiating MSH sends a pull signal message to the responding MSH, as illustrated in the following diagram:

In One-Way/Pull, AS4 plays the role of initiating MSH or responding MSH. The role played by the MSH depends on whether you want to send or receive a user message.

Selective-Pull

Selective pull feature allows to pull a subset of messages posted on Message Partition Channels (MPC). The initiating Messaging Service Handler (MSH) sends a pull signal to the responding MSH along with a pull criteria using requestSM. The responding MSH uses requestSM parameters to match the messages present in the MPC and sends back the first matching message as a response using requestUM. A Selective pull mechanism is initiated by a business application by providing simple selection item or complex selection item parameters in the service.

Simple selection, complex selection or both are used to pull messages from an MPC.

Following are the two types of selection:

• Simple selection: Use this option to select messages using any of the following parameters: RefToMessageId, ConversationId, AgreementRef, Service, and Action.
• Complex selection: Use this option to select messages using any of the following parameters: From, To, and MessageProperties.

AS4 acting as Initiating MSH

When you want AS4 to play the role of initiating MSH, webMethods.io B2B uses the mpc and pmodeId input parameters that are passed to constructSubmitInput service to fetch the appropriate TPA and identify the messaging parameters for the transfer.

The parameters specified in the requestSM leg of the TPA are used to generate the pull signal and identify the address of the responding MSH. When the user message is received as a response to the pull signal, webMethods.io B2B uses the requestUM leg of the TPA to process the user message.

AS4 acting as Responding MSH

In One-Way/Pull MEP, use the constructSubmitInput service to package the submitted payload(s) as a user message and submit it to an MPC. The service uses the values of the ReceiverID, ReceiverIDType, SenderID, SenderIDType, and pmodeID. If pmodeID is empty, then a tuple of ReceiverID, toRole, SenderID, fromRole, service, action, and agreementRef input parameters to retrieve the appropriate TPA. The values in the TPA are then used to identify the messaging parameters. Instead of transferring the message to the initiating MSH, the webMethods.io B2B stores the message in the MPC specified in the legs/businessInfo/mpc TPA parameter of the requestUM leg.

When a pull signal is received, AS4 determines which TPA to use to process the pull signal by matching the MPC named in the pull signal with the MPC named in the requestSM leg of each TPA that is configured in webMethods.io B2B. The matching MPC is used to process the pull signal. AS4 retrieves the user message from the MPC specified in the pull signal and sends it to the initiating MSH. If no MPC is specified in the pull signal, AS4 uses the default MPC to pull the user message.

AS4 uses the webMethods.io B2B database as the MPC queue. When a user message is queued, the message is stored in webMethods.io B2B with a UserStatus of QUEUED, and the corresponding bizDocId is cached. When a pull signal is received, the module first retrieves the bizDocId from the cache First In - First Out, and then retrieves the user message that corresponds to this bizDocId from webMethods.io B2B. The retrieved message is then sent to the initiating MSH.

Important: When purging the transaction analysis in webMethods.io B2B, do not delete user messages in the QUEUED state.

Two-Way/Sync MEP

The Two-Way/Sync MEP synchronously exchanges messages between two trading partners. The initiating MSH sends a user message as a request to the responding MSH. The responding MSH replies with a user message to the initiating MSH.

In Two-Way/Sync, AS4 plays the role of initiating or responding MSH. The role played by the MSH depends whether you want to send a user message as a request or reply.

AS4 acting as Initiating MSH

When you want AS4 to play the role of initiating MSH, the Two-Way/Sync transfer is initiated by webMethods.io B2B.

The parameters specified in the requestUM leg of the TPA are used to generate the user message and identify the address of the responding MSH. After webMethods.io B2B receives a reply, it uses the replyUM leg of the TPA to process the user message.

If webMethods.io B2B does not receive a response within the time-period defined in AS4 configuration, an error message is generated by the initiating MSH.

AS4 acting as Responding MSH

When you want AS4 to play the role of responding MSH, use the constructSubmitInput service to submit a reply user message to the corresponding request user message by setting sync flag to true. The refToMessageId of the reply user message should be set to the request user message’s MessageId value. AS4 uses the requestUM leg of the TPA to process the request user message and sends the reply to the initiating MSH.

Two-Way/PushPull MEP

The Two-Way/PushPull MEP sends (pushes) a request user message to a trading partner followed by a pull signal to receive a reply user message as shown in the diagram. Both the user message and the pull signal are sent by the initiating MSH.

The pulled user message refers to the user message that was pushed.

Two-Way/PushPush MEP

The Two-Way/PushPush MEP asynchronously exchanges messages between two trading partners. The initiating MSH sends a user message as a request to the responding MSH. The responding MSH replies with a user message to the initiating MSH.

The reply must refer to the request.

In Two-Way/PushPush, AS4 plays the role of an initiating or a responding MSH. The role played by MSH depends on whether you want to send a user message as a request or reply.

How do I Configure Functional Acknowledgments for an Existing EDI document?

A functional acknowledgment (FA) is a transaction set sent by the receiver of an EDI transmission to the sender, acknowledging that the message has been received, and its syntax is acceptable. Functional acknowledgments do not indicate that the document has been processed by the receiver.

Enabling Automatic FA Generation

This use case explains how to configure functional acknowledgments for an EDI document transactions, segments or elements.

The use case starts when the generate FA for EDI document is enabled and ends when you successfully generate functional acknowledgment for EDI document.

In this example, you can generate functional acknowledgment for the X12 standards 4010 version 850 transaction EDI inbound document.

Before You Begin

Ensure that you have:

• Added specific document type which you want to send or process.
• Configured the partner profiles for the sender and receiver.
• Added the respective transaction document types.
• Setup enterprise and partner profile (including inbound and outbound channel, partner users, certificates).
• Added X12 4010 850 document type and set it as Active.
• Added X12 4010 997 document type and set it as Active.

Basic Flow

To define X12 4010850 transaction EDI document

1. In webMethods.io B2B, go to Agreements > TPA Definition > Add Document.
2. Select the Agreement name as EDITPA.
3. Select the Sender and Receiver.
4. Select the Template structure as EDIV1.
5. Under the FAGeneration from template structure, select autoGenerateFA as On.
6. Click Create.

Next Steps

• Receive EDIINT communication from a partner.
• Go to Monitoring > Transactions. Observe the new transaction logged in the Transactions page.
• Click on the X12 Envelop transaction sent from the receiver to sender.
• Go to Content > EDI data. Observe the functional acknowledgment data in X12 4010 997.