Author: Aaradhana Sridharan <aaradhana.sridharan@softwareag.com>
Supported versions: webMethods.io B2B 1.2 and above
Please refer to webMethods.io B2B - Getting started article for an overview of the product and how to achieve a simple use case of receiving a document.
Use case
Let us consider a use case where a hotel chain, Tastilicious, would like to use webMethods.io B2B to enable exchange of business documents between its partners - NutriFoods (a supplier of organic food items) and QualityEnsure (a food quality check firm).
On a daily basis, the following sequence of events take place:
- Tastilicious receives a predefined set of food items from NutriFoods
- Along with the food items, it also receives invoices which contain the details - Item id, type, received time, weight, amount, etc.
- Tastilicious performs some processing on these invoices.
- Tastilicious then sends the food items and the invoices to QualityEnsure.
As an enterprise, Tastilicious should configure webMethods.io B2B to enable the exchange of business documents between its partners. This involves creation of:
- Enterprise profile (A profile that represents Tastilicious)
- Partner profile for NutriFoods
- Partner profile for QualityEnsure
- Partner user
- Communication channels (Inbound and Outbound)
- Processing rule
Design time Configuration
Setting up enterprise and partner profiles
Step 1: Create enterprise profile
To setup a profile for the enterprise (Tastilicious), Click Set up my B2B Enterprise on the welcome screen to open the guided wizard.
Enter the Name and Organization Unit of the enterprise.
In order to recognize the enterprise profile in a unique manner, identities need to be provided. There are different types of identities available. Here, we choose the DUNS number as the identity type.
Click Add Identity to add information on identities.
The next screens request you to add information about contacts and addresses. This information is necessary for the partner to communicate the enterprise.
Once the enterprise profile is created, you will see that it is set to Active by default.
Step 2: Create partner profile for NutriFoods
To create a new partner, click Add Partner in Partner profiles section.
Create a partner NutriFoods with DUNS number as the identity type with value 123456789.
Step 3: Create partner profile for QualityEnsure
To create a new partner, click Add Partner in Partner profiles section.
Create a partner QualityEnsure with DUNS number as the identity type with value 987654321.
Step 4: Create partner user
Only authorized users of a partner can send documents to webMethods.io B2B.
To create a partner user, click Add Partner User in Partner users section.
Create a partner user sam along with password information.
Creating channels
A channel forms the basis of communication in webMethods.io B2B and facilitates document exchange.
There are two types of channels - Inbound (to receive documents) and Outbound (to send documents).
Step 5: Create inbound channel
In Channels section, click Add Channel and choose Inbound Channel.
Choose the Channel type as HTTP-IN and provide the name and description.
Once the channel is created, you will see that the channel is Active by default. Also, note the HTTP endpoint URL which will be used by the partner (NutriFoods) to send documents.
Step 6: Create outbound channel
In Channels section, click Add Channel and choose Outbound Channel.
Choose the Channel type as HTTP-OUT and provide the name and description.
In the next screen, details about the outbound channel endpoint needs to be provided.
Host is the base URL and Location is the relative path. If the endpoint is protected, username and password needs to be specified.
"Use SSL" needs to be enabled in case of HTTPS endpoints. We will not enable it for our use case.
Once the channel is created, you will see that the channel is Active by default. Also, note the HTTP endpoint URL which will be used by the partner (QualityEnsure) to receive documents.
For testing purpose:
In order to test the use case of outbound channel, we can host an HTTP server with a service which accepts the documents that we send. A much easier way is to use REST API mocking services available online. Here, we have used https://beeceptor.com/.
Once you create a mock API at https://beeceptor.com/, you can intercept the requests that reach this API and also view the document content that we send (Make sure no sensitive document content is sent).
Associations
Step 7: Associate partner user with NutriFoods
To send a document to webMethods.io B2B, a partner must have at least one partner user associated with it.
Let us now associate the user sam with partner NutriFoods.
Go the Users section of the profile page of NutriFoods, click Associate User and add the user "sam".
Step 8: Associate inbound channel with NutriFoods
You should associate an inbound channel with a partner to enable it to send business documents through the configured endpoint.
Here, we need to associate the inbound channel HTTP-Inbound-Channel with partner NutriFoods.
Go the Inbound channels section of the profile page of NutriFoods, click Associate Inbound Channel and add the channel "HTTP-Inbound-Channel".
Step 9: Associate outbound channel with QualityEnsure
You should associate an outbound channel with a partner to enable it to receive business documents through the configured endpoint.
Here, we need to associate the outbound channel HTTP-Outbound-Channel with partner QualityEnsure.
Go the Outbound channels section of the profile page of QualityEnsure, click Associate Outbound Channel and add the channel "HTTP-Outbound-Channel".
Note that the first outbound channel associated with a partner becomes the preferred outbound channel, by default. When you have multiple outbound channels associated, you can choose the preferred outbound channel.
Step 10: Activate partner profiles
Activate the partner profiles of NutriFoods and QualityEnsure by enabling the Active toggle in the partner profile Summary page.
Processing rules
Processing rules specify how you want webMethods.io B2B to process the inbound documents and the specific actions to take after a document matches with the specified criteria. They get executed in the order of precedence.
Step 11: Create processing rule
In order to place the new rule first in the sequence, click on the first rule in the list, click Add Processing Rule and choose Above.
Enter the Name and Description of the rule. Note that the Sequence of the rule is First.
Step 12: Configure criteria
The criteria defines who the sender and receiver should be, the type of document allowed, etc.
Choose the sender as NutriFoods and the receiver as QualityEnsure.
Step 13: Configure pre-processing options
These options are used for performing operations prior to the actual processing actions.
Let us continue with the default selection that is present. The selection Defer to business document means the value provided in the business document will be considered.
Step 14: Configure action
These are actions that will be executed once the criteria is met and the pre-processing is completed.
We shall configure the action Deliver document. This action enables webMethods.io B2B to send the incoming document to the receiver's preferred outbound channel.
Step 15: Activate processing rule
By default, any newly created processing rule is not activated. Activate the processing rule High Priority Rule by enabling the Active toggle in the Summary page.
Sharing details to NutriFoods
You need to share the inbound channel endpoint details with NutriFoods in order for them to send documents.
Step 16: Share endpoint and user details to partner
Details that need to be shared are - Endpoint URL and Partner User Credentials.
You will find the endpoint URL of the inbound channel and user credentials in the partner profile summary page of NutriFoods.
In our example, the endpoint URL is https://tastilicious-int-aws-us.webmethods.io/b2b/routes/channel/ebf06578-f698-4675-aeaa-1b6d8742bbf4 and partner user is sam.
Run-time invocation
Sending document to an inbound channel
Now that we have configured an inbound channel and associated it with NutriFoods, NutriFoods will now be able to send an EDI document to this channel's endpoint.
Step 17: Send an EDI document to an inbound channel endpoint
- Open Postman client.
- Select HTTP POST method.
- Specify the HTTP request URL as the inbound channel's endpoint URL.
- Under Authorization, set the Authorization to Basic Auth and specify the username and password configured as the partner user credentials.
- Under Headers, set Content-Type header as application/edi.
- Under Body, choose the type as raw and paste the below document content.
ISA*00* *00* *01*123456789 *01*987654321 *031008*1040*U*00401*000000001*1*P*>~
GS*IN*123456789*987654321*20030627*1304*1*X*004010~
ST*810*01403001~
BEG*00*SA*548177**20030627~
REF*AN*547794~
PER*BD*JOHN JONES*TE*5552225555~
FOB*PB~
DTM*002*20030705~
DTM*118*20030704~
PKG******01~
TD5****H*OUR CR/T~
N9*AH*548177~
MSG*THIS PURCHASE ORDER IS SUBJECT TO THE SAME TERMS AND~
MSG*CONDITIONS AS SAFEWAY PURCHASE ORDER FORM 1030~
MSG*PICKUP NO. E450562
N1*ST*SAFEWAY INC*9*0091372092527~
N2*Tracy Produce~
N3*16900 West Schulte Road~
N4*Tracy*CA*95376~
N1*BT*SAFEWAY INC*9*0091372091700~
N2*NATIONAL SERVICES CENTER~
N3*P.O. BOX 29093~
N4*PHOENIX*AZ*85038~
N1*VN*BEST SUPPLIER INC.*9*1234567890000~
N3*P.O. BOX 11111~
N4*LOS ALAMITOS*CA*90001~
PO1**10*CA*12.5**UA*042040304101*IN*20403041*VN*22222~
CTP*RS*FCP*12.5~
PID*F*08***ITEM DESCRIPTION 1/10 LB~
SAC*A*B280***20.00***2.00****02~
CTT*1**120*LB~
SE*29*01403001~
GE*1*1~
IEA*1*000000001~
Note that the sender identity is highlighted in green and receiver identity is highlighted in blue.
Send or submit the request. You should receive a 200 OK response.
Receiving document via an outbound channel
Now that we have configured an outbound channel and associated with QualityEnsure, QualityEnsure will now be able to receive an EDI document via the outbound channel's endpoint.
Step 18: Receive an EDI document via an outbound channel endpoint
When the document is sent by NutriFoods, webMethods.io B2B receives it and executes the action configured in the processing rule. In our case, the action is "Deliver the document using receiver's preferred outbound channel" (i.e. to the outbound channel of QualityEnsure).
Remember, we used the https://beeceptor.com to create a mock endpoint. We can visit the URL https://beeceptor.com/console/test-out-channel (where test-out-channel is our mock domain) to see the incoming requests.
As shown in the above image, we can see that the document is received as part of the request body. For testing purpose, a mock response is returned.
In a real-time use case, a partner who receives the document via its outbound channel can perform operations based on their use case.
Transaction Monitoring
Information about documents exchanged in webMethods.io B2B is available in the Transactions page.
For the document that we sent using Postman client, we see the above 4 entries in the transactions list.
For each transaction, we can view the transaction summary and course of transaction by clicking on the value of "Date received" column.
Click on the "Date received" column of the transaction with the "Business document" column value "X12 4010 810".
In the Course of transaction, you will see 2 entries:
- One with the prefix as "SND" which denotes the document being sent via the outbound channel by NutriFoods
- One with the prefix as "REC" which denotes the document being received via the outbound channel by QualityEnsure.
Troubleshooting
In case of errors during document delivery, you will see error entries in the course of transaction.
Case 1
The outbound channel endpoint is not reachable.
Case 2
The outbound channel endpoint expects a username/password and endpoint is not configured with username/password.
Case 3
The outbound channel configuration is SSL enabled, but the certificates are not sent as part of the request.
References
For more information on webMethods.io B2B, please refer the documentation.
For creating mock APIs - https://beeceptor.com/
Downloadable Artifacts
You can find the export of the above Postman transaction as a JSON file (Send_EDI_Document.json) as part of attachments.
Send_EDI_Document.json (2.05 KB)