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:

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:

TPA field TPA 1 TPA 2
Partner that represents the sender A B
Partner that represents the receiver B A
Type of TPA (Agreement ID) EDITPA EDITPA

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:

TPA Definition

TPA definitions are also of two types:

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

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 icon > 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 icon > 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 affect.
    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

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:

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:

Scenario Action
A partner-specific EDI TPA exists webMethods.io B2B uses the values specified in the partner-specific EDITPA.
A partner-specific EDI TPA does not exist, but a sender-specific EDITPA exists webMethods.io B2B uses the values specified in the sender-specific EDITPA.
Neither a partner-specific EDITPA nor a sender-specific EDI TPA exists webMethods.io B2B uses the values specified in the receiver-specific EDITPA.
Partner-specific EDI TPA, a sender-specific EDI TPA, or a receiver-specific EDI TPA do not exist webMethods.io B2B uses the value from the default EDITPA.

Ways to create an partner-specific EDITPA:

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). MEP defines how messages are exchanged between two trading partners. AS4 supports the following ebMS MEPs for both the sender and the receiver:

One-Way/Push MEP

This MEP is used to send (push) a user message to a trading partner. The user message can be carried over a one-way or a two-way underlying protocol.

Step Description
1 The initiating MSH sends the data packaged as a user message to the responding MSH.
2 The responding MSH receives and processes the user message.

One-Way/Pull MEP

This MEP is used to send 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 diagram.

Step Description
1 The initiating MSH sends a pull signal message to the responding MSH.
2 The responding MSH sends the message data packaged as a user message to the initiating MSH.
3 The initiating MSH receives the user message for processing.

When using One-Way/Pull, AS4 can play 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 you to pull a subset of messages posted on an 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 the requestSM parameters to match the messages present in the MPC and sends back the first matching message as a response using requestUM. Selective pull can be initiated by a business application by providing simple selection item or complex selection item parameters in the service.

Simple selection, complex selection or both can be used to pull messages from an MPC. Following are the two types of selection:

AS4 acting as Initiating MSH

When AS4 plays 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, the module uses the requestUM leg of the TPA to process the user message.

AS4 acting as Responding MSH

When using the 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 fetch 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 module 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.

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:

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