Inbound EDI
There are two ways that you can invoke a transformer to convert inbound X12 documents to XML or JSON format.
-
Invoking
StartTransformerJob
API. With this approach, you create an inbound transformer that is configured to transform a specific transaction set and version into JSON or XML. You then invoke theStartTransformerJob
action, which requires a Transformer ID, the absolute file path in Amazon S3 for the input EDI document, and the output directory path in Amazon S3 for the transformed JSON/XML file.Acknowledgements are stored in a generated ACK folder in the output directory. Subscribe to status updates using events emitted to Amazon EventBridge or invoke the
GetTransformerJob
API to poll for status updates from the invoking orchestration engine (such as AWS Step Functions).Note
The Transformer only option only works for when you are transforming incoming X12 documents to JSON/XML, and needs to be invoked.
-
Monitoring specified locations in Amazon S3. With this approach, you configure a transformer, trading capability, and partnership. You then drop EDI input documents into the input directory specified in the attached trading capability and B2B Data Interchange listens for Amazon S3 events to automatically transform the documents to JSON or XML files and stores the files in the specified output directory. The input and output directory used are those specified in your trading capability with your trading partner's ID added to the prefixes. As part of the partnership configuration, you specify one or more trading capabilities to use.
For each of the trading capabilities specified in the Partnership, a trading partner ID is added as a new prefix to the input and outbound directories specified in each of the respective trading capabilities. For example, assume that you specify the following directories in your trading capability:
-
Capability input directory:
s3://EDI-bucket/input-EDI/
-
Capability output directory:
s3://EDI-bucket/output-JSON/
When you associate your trading capabilities with your partnership, the service adds a prefix to both the input and output directory, changing them to the following:
-
Input directory to drop incoming X12 files becomes
s3://EDI-bucket/input-EDI/
<trading-partner-id>
/ -
Output directory containing the transformed JSON/XML files becomes
s3://EDI-bucket/output-JSON/
<trading-partner-id>
/ -
The acknowledgement is stored in
s3://EDI-bucket/output-JSON/
<trading-partner-id>
/ACK/
You then drop files into the trading-partner-ID prefix in the input directory to transform EDI for that specific partner. The transformed JSON output is then written to the trading-partner-ID prefix in the output directory. Using these prefixes ensures that your EDI documents are properly transformed for each individual trading partner.
Note
You can associate one trading capability with multiple partnerships, and a partnership can be associated with multiple trading capabilities. Using the folder structure specified, you can use the same trading capability for multiple partners. The trading partner ID makes sure that you have clear delineation as to where the transformed EDI data for a specific partner should be stored.
-
Topics
Transforming inbound EDI documents
Typically, you perform the following steps to transform X12 EDI documents into JSON or XML data
-
Test your transformation workflow. For details, see the Testing end-to-end
topic from our EDI document exchange with AWS B2B Data Interchange workshop.
Create a profile
You can use profiles to store contact information and details about your own business and specify a unique name to easily identify this profile A profile contains the following types of information.
-
Profile details: This section contains the profile name, the name of the business, a contact email address, and a phone number.
Note
These details are all your characteristics, not those describing your trading partner. The latter are described as part of the partnership resource.
-
Logging: This section describes the logging configuration. You can also opt out of logging (not recommended).
-
Tagging: Tag your profiles to easily organize, search, and filter your profiles globally.
To create a profile
-
Open the AWS B2B Data Interchange console at https://console.aws.amazon.com/b2bi/
and select Profiles from the navigation pane, then choose Create profile. -
Enter the profile details, the name of the profile, the name of the business represented, and the contact information (email and phone number).
-
Logging is selected by default. Clear the box to turn off logging (not recommended). The log group is based on the profile ID, for example,
/aws/vendedlogs/b2bi/p-ABCDE111122223333
. -
Optionally, add tags as needed.
Create an inbound transformer
A transformer describes how to process the incoming EDI documents and extract the necessary information to the output file.
Note
If an EDI input file contains more than one transaction, each transaction must
have the same document and version, for example
214
/4010
. If not, the transformer
cannot parse the file.
To create a transformer
-
Open the AWS B2B Data Interchange console at https://console.aws.amazon.com/b2bi/
and select Transformers from the navigation pane, then choose Create transformer. -
Select a transformer name (for example edi-214-json), the direction, the EDI doc number, and version. Then, provide a sample document by selecting a document from Amazon S3. The sample document can preview how your EDI documents get converted.
-
Enter a name (no spaces).
-
Ensure that Inbound EDI is selected.
-
For Input Details, select an EDI document number and X12 version from the dropdown menus.
-
For Input Details, select JSON or XML.
-
Select Split by transaction to split processed EDI document by transaction set, or Do not split. For more information about EDI splitting, see EDI splitting.
-
Optionally, in the Sample documents pane, provide the bucket and prefix in Amazon S3 for the sample input and output files. This is useful for making sure the transformer functions correctly.
-
Optionally, add tags as needed.
-
Select Next to proceed to the next step in the wizard.
-
-
The Mapping configuration screen is displayed. If you provided a sample input document in the previous step, the default representation for your sample is displayed. For more information about AI-assisted mapping, see the generative AI-assisted mapping section.
If you chose not to customize the output format using the Mapping template editor, AWS B2B Data Interchange transforms EDI document inputs using the default, service-defined format shown on the left side of your screen.
You can also use the Mapping template editor to only include certain pieces of your EDI documents.
The pieces you select are previewed in the mapping preview pane.
The items in your mapping editor are the only items that are extracted from the input EDI document, and that are then saved to your output file, located in your Amazon S3 output location.
This example shows ref ID, shipment ID, and b of lading number, from and to city, and the shipment status code.
-
When you are happy with your mappings, choose Next, which takes you to the review page. Note that newly created transformers are inactive.
Note
A status of Inactive indicates that the transformer is not used in any trading capabilities: it is essentially in edit mode. When you are finished editing and updating the transformer, you change the status to Active. Then, you can associate the transformer with a trading capability. At this point, the transformer is essentially locked, and in production mode.
-
After your review is complete, choose Save to create the transformer.
Create a trading capability for inbound EDI
Trading capabilities contain the information required to build your event-driven EDI workflows. To create a trading capability, specify the EDI direction, add details about the EDI document number and version, choose the transformer to use to transform or generate your EDI, and specify the input and output directories used to source and store documents. Based on the EDI direction selected and the transformer attached to the trading capability, you can use the capability to automatically:
-
Transform incoming EDI documents into JSON or XML outputs.
-
Transform XML or JSON data stored in Amazon S3 into EDI documents.
To create an inbound trading capability
-
Open the AWS B2B Data Interchange console at https://console.aws.amazon.com/b2bi/
and select Trading capabilities from the navigation pane, then choose Create trading capability. -
In the Trading capability settings section, enter the following information.
-
Enter a descriptive, unique name for the trading capability.
-
Select an EDI direction, either Inbound or Outbound.
-
Choose an X12 version and X12 transaction set from the corresponding dropdown menus.
-
In the Apply transformer field, choose a transformer to apply to this trading capability.
-
-
In the Configure directories section, you configure both the input and output directories that are used to source and store documents.
-
In the Input directory area, enter an Amazon S3 bucket.
-
Choose Browse S3 to navigate to your available Amazon S3 buckets, where you can select a bucket (and optionally a prefix) to specify your input directory.
Note
B2B Data Interchange will continuously monitor all of the prefixes of your input directory for new files. It attempts to transform every file placed into any prefix of your input directory.
Avoid placing files that you do not want to be transformed into your input directory or any of its prefixes.
-
Choose Copy policy to copy a policy that you can then paste into your input directory's bucket policy.
-
Configure your output directory in the Output directory area, similarly to how you configured the input directory.
Note
B2B Data Interchange will automatically create prefixes in the specified output directory to store the transformed X12 documents.
Don't set your output directory as a subdirectory of your input directory: this configuration directs B2B Data Interchange to attempt processing output files as input files.
-
-
Optionally, add tags as needed.
-
After you have configured all of the settings, choose Create capability.

Note
-
For your input and output directories, update the bucket policy (Configure your Amazon S3 bucket policies). If your input or output buckets use SSE-KMS encryption, you also need to update the policy for your AWS KMS key. For details, see Example bucket policies.
-
Enable EventBridge notifications for the Amazon S3 buckets used by the trading capability. For details, see (Configure your Amazon S3 bucket EventBridge setting).
Create a partnership for inbound EDI
A partnership represents the connection between you and your trading partner. It incorporates a profile and one or more trading capabilities. It is also where you define the interchange control header and functional group header information necessary to generate outbound EDI documents.
To create a partnership
-
Open the AWS B2B Data Interchange console at https://console.aws.amazon.com/b2bi/
and select Partnerships from the navigation pane, then choose Create partnership. -
In the Partnership details section, provide the following information.
-
Enter a descriptive name for the partnership.
-
Enter an email address to associate with the partnership. Provide the trading partner's email address.
-
Choose a profile from the dropdown menu.
-
Select one or more trading capabilities from the Trading capabilities list.
-
-
In the Inbound EDI configuration section. choose which acknowledgments, if any, to generate.
-
For TA1 Technical Acknowledgments, choose whether or not to generate.
-
For Functional (997 and 999) Acknowledgments, choose whether or not to generate, and whether or not to include AK2 loop.
For more information about EDI acknowledgements, see EDI acknowledgements.
-
-
Unless you intend to perform outbound EDI processing with this partner, you can skip the Outbound EDI configuration section.
-
Optionally, add tags as needed.
-
After you have configured all of the settings, choose Create partnership.

After you create a partnership, you can observe a new sub-directory, within your Amazon S3
input directory, beginning with tp-
.