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:
|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.
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.
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 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 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
any, thus allowing any partner to be a receiver.
Receiver-specific TPA. Identifies the receiver but leaves the sender defined as
unknown. The value
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
- In webMethods.io B2B, go to Agreements > TPA Templates > Add Template.
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.
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.
Edit Template Reference
You can update all the values in a template and reuse it for a different set of configurations.
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
- In webMethods.io B2B, go to Agreements > TPA Definitions > Add Definition.
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.
agreedstatus means that the TPA is final. When the agreement status is
agreed, the data statuses take affect.
disabledstatus 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
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.
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.
- 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
- In webMethods.io B2B, go to TPA > TPA definitions.
- Click Upload TPA data to load the TPA data from a file.
- Click Upload.
To save the TPA data
- In webMethods.io B2B, go to TPA > TPA definitions.
- Click Save to disk to save the TPA data to a file.
- Click Save.
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:
|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:
- 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.
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: Used to send a user message to a trading partner.
- One-way/Pull: Used to send a pull signal to a trading partner to receive a user message.
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.
|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.|
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.
|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 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:
- 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 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:
- 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.
To define X12 4010850 transaction EDI document
- In webMethods.io B2B, go to Agreements > TPA Definition > Add Document.
- Select the Agreement name as EDITPA.
- Select the Sender and Receiver.
- Select the Template structure as EDIV1.
- Under the FAGeneration from template structure, select autoGenerateFA as On.
- Click Create.
- 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.