# 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 the `StartTransformerJob` 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//`
+ Output directory containing the transformed JSON/XML files becomes `s3://EDI-bucket/output-JSON//`
+ The acknowledgement is stored in `s3://EDI-bucket/output-JSON//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](#edi-inbound-process)
+ [Create a profile](#getting-started-profile)
+ [Create an inbound transformer](#getting-started-transformer)
+ [Create a trading capability for inbound EDI](#getting-started-capability)
+ [Create a partnership for inbound EDI](#getting-started-partnership)
+ [EDI acknowledgements](edi-ack.md)
+ [EDI splitting](edi-split-overview.md)
## Transforming inbound EDI documents
Typically, you perform the following steps to transform X12 EDI documents into JSON or XML data
1. [Create a profile](#getting-started-profile).
1. [Create an inbound transformer](#getting-started-transformer).
1. [Create a trading capability for inbound EDI](#getting-started-capability).
1. [Create a partnership for inbound EDI](#getting-started-partnership).
1. Test your transformation workflow. For details, see the [Testing end-to-end](https://catalog.workshops.aws/getting-started-b2b-data-interchange/en-US/030-testing) topic from our [EDI document exchange with AWS B2B Data Interchange](https://catalog.workshops.aws/getting-started-b2b-data-interchange/en-US) 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**
1. Open the AWS B2B Data Interchange console at [https://console.aws.amazon.com/b2bi/](https://console.aws.amazon.com/b2bi/) and select **Profiles** from the navigation pane, then choose **Create profile**.
1. Enter the profile details, the name of the profile, the name of the business represented, and the contact information (email and phone number).
1. 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`.
1. Optionally, add tags as needed.
![\[The AWS B2B Data Interchange console Profiles page, showing an example profile.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/profile-configure.png)
## 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**
1. Open the AWS B2B Data Interchange console at [https://console.aws.amazon.com/b2bi/](https://console.aws.amazon.com/b2bi/) and select **Transformers** from the navigation pane, then choose **Create transformer**.
1. 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.
1. Enter a name (no spaces).
1. Ensure that **Inbound EDI** is selected.
1. For **Input Details**, select an EDI document number and X12 version from the dropdown menus.
1. For **Input Details**, select **JSON** or **XML**.
1. 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](edi-split-overview.md).
1. Optionally, configure custom validation rules to support partner-specific EDI formats that deviate from standards. For more information about custom validation rules, see [Custom validation rules](edi-validation.md#custom-validation-rules).
1. 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.
1. Optionally, add tags as needed.
1. Select **Next** to proceed to the next step in the wizard.
1. 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.
1. 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.
1. 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**
1. Open the AWS B2B Data Interchange console at [https://console.aws.amazon.com/b2bi/](https://console.aws.amazon.com/b2bi/) and select **Trading capabilities** from the navigation pane, then choose **Create trading capability**.
1. In the **Trading capability settings** section, enter the following information.
+ Enter a descriptive, unique name for the trading capability.
+ For **EDI direction**, select **Inbound**.
+ 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.
1. In the **Configure directories** section, you provide full S3 path to both the input and output directories.
+ You can use **Browse S3** to navigate to your available Amazon S3 buckets, where you can select a bucket (and optionally a prefix) to specify your preferred directories.
+ You can validate that your S3 buckets setup meets the prerequisites ([Prerequisites for using AWS B2B Data Interchange](b2bi-prereq.md)) for AWS B2B Data Interchange using **Validate input S3 setup** and **Validate output S3 setup**.
+ You can use **Copy policy** to copy a policy that you can then paste into your input/output directory's bucket policy to provide AWS B2B Data Interchange the necessary access.
![\[An example capability, showing the settings, the associate partnership, input and output directories, and an example tag.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/capability-example-inbound.png)
1. Optionally, add tags as needed.
1. After you have configured all of the settings, choose **Create capability**.
**Important considerations to avoid failed transformation attempts and unnecessary charges**
B2B Data Interchange monitors all prefixes of your input directory for new files and attempts to transform every file placed in any prefix. Don't place files you don't want transformed into your input directory or its prefixes.
Don't set your output directory as a subdirectory of your input directory. This configuration causes B2B Data Interchange to attempt processing output files as input files.
B2B Data Interchange will automatically create prefixes in the specified input and output directories. Don't delete or edit these prefixes.
## 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**
1. Open the AWS B2B Data Interchange console at [https://console.aws.amazon.com/b2bi/](https://console.aws.amazon.com/b2bi/) and select **Partnerships** from the navigation pane, then choose **Create partnership**.
1. In the **Partnership details** section, provide the following information.
1. Enter a descriptive name for the partnership.
1. Enter an email address to associate with the partnership. Provide the trading partner's email address.
1. Choose a profile from the dropdown menu.
1. Select one or more trading capabilities from the **Trading capabilities** list.
1. In the **Inbound EDI configuration** section. choose which acknowledgments, if any, to generate.
1. For **TA1 Technical Acknowledgments**, choose whether or not to generate.
1. 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](edi-ack.md).
1. Unless you intend to perform outbound EDI processing with this partner, you can skip the **Outbound EDI configuration** section.
1. Optionally, add tags as needed.
1. After you have configured all of the settings, choose **Create partnership**.
![\[The AWS B2B Data Interchange console Partnerships page, showing an example partnership.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/partnership-outbound.png)
After you create a partnership, you can observe a new sub-directory, within your Amazon S3 input directory, beginning with `tp-`.
# EDI acknowledgements
B2B Data Interchange automatically generates acknowledgements that you can return to your trading partner to communicate that the file was received and to report errors. The generated acknowledgement is stored in your Amazon S3 bucket alongside the transformed EDI, and an event is emitted by the B2B Data Interchange service to Amazon EventBridge.
The service generates the following types of acknowledgements:
+ *TA1 interchange acknowledgements*: A TA1 is an interchange acknowledgement used to confirm the receipt of X12 EDI interchanges and to report syntactical errors. It reports the status of the processing of an interchange header and trailer by the addressed receiver or the non-delivery by a network provider. TA1 interchange acknowledgements are generated for all interchanges.
+ *997 functional acknowledgements*: the 997 is a functional acknowledgement used to confirm receipt of X12 EDI transactions and to report transactional errors. A 997 acknowledgement serves as a response to an individual EDI message or group of messages. It contains information about the receipt of the upstream transaction, such as whether it has been accepted, accepted with errors or rejected. Most finance, transportation, supply chain, and communication & control transactions generate a 997 functional acknowledgement.
+ *999 functional acknowledgements*: there are two types of 999 functional acknowledgement, as follows:
+ 999 functional acknowledgement for HIPAA transactions: the service generates *999 X231* acknowledgements for all X12 version 5010 HIPAA transactions.
+ 999 functional acknowledgement for non-HIPAA transactions: the service generates *999* acknowledgements for all other healthcare-related X12 transactions.
You have the option to disable acknowledgement generation for processed inbound EDI documents. To do this, choose **Do not generate** in the **Generated Acknowledgments Documents** section of your partnership configuration. For functional acknowledgements, you can also opt to generate acknowledgments without the AK2 loop by selecting **Generate without AK2 loop** in the **Functional (997 and 999 Acknowledgements)** box. These acknowledgement settings are configured at the partnership level and apply to all inbound EDI documents processed within that partnership.
**Note**
The service generates either a 999 or 997 acknowledgement, but never both.
For details of the generated events, see [AWS B2B Data Interchange events detail reference](events-detail-reference.md).
One example use case is as follows: Retailer B responds with an EDI 997 Functional Acknowledgement, which communicates to Vendor A that their EDI 810 Invoice was received and is syntactically valid.
1. Retailer B receives X12 EDI 810 Invoice from Vendor A.
1. Retailer B responds with an EDI 997 Functional Acknowledgement, which communicates to Vendor A that their EDI 810 Invoice was received and is syntactically valid.
B2B Data Interchange creates events when generating acknowledgements (for both successful and failed scenarios). The primary value of generating these events is for returning the acknowledgement to the trading partner. You can use AWS Transfer Family (or any other data transfer service) to send these acknowledgements to your trading partner.
To learn more about using B2Bi acknowledgement events to return acknowledgements to your trading partner, see [Details fields for transformation events](events-detail-reference.md#detail-fields-transform).
## Acknowledgement output paths
This section describes the output paths for acknowledgement files saved to Amazon S3.
Let's assume that a customer configures their EDI trading capability to have the following input and output directories.
+ Input: s3://amzn-s3-demo-bucket/IN/
+ Output: s3://amzn-s3-demo-bucket/OUT/
In this example, the absolute paths for the EDI input document and the transformed JSON or XML output are as follows:
+ Inbound EDI: s3://amzn-s3-demo-bucket/IN/TP\$1ID/edi214xml-test83.txt
+ Transformed output: s3://amzn-s3-demo-bucket/OUT/TP\$1ID/edi214xml-test83.txt.2023-11-21T19:26:49.774Z.xml
The path of the acknowledgement depends on whether the inbound X12 EDI document is transformed using a trading capability or transformed by directly invoking the `StartTransformerJob` API operation.
When using a trading capability, the format for the acknowledgement files is s3://amzn-s3-demo-bucket/OUT/TP\$1ID/ACK/*filename*.*timestamp*.997 (.TA1 for TA1 acknowledgements).
When invoking the `StartTransformerJob` API directly, acknowledgements will be written into a dedicated ACK prefix within the output location specified in the request. See the following example paths.
**Acknowledgement use case example**
The following are examples for the acknowledgement output filenames:
+ 997 acknowledgement: `s3://amzn-s3-demo-bucket/OUT/TP_ID/ACK/edi214xml-test83.txt.2023-11-21T19:26:49.774Z.997`
+ 999 X231 acknowledgement: `s3://amzn-s3-demo-bucket/OUT/TP_ID/ACK/edi835x221.xml-test83.txt.2023-11-21T19:26:49.774Z.999x231`
+ TA1 acknowledgement: `s3://amzn-s3-demo-bucket/OUT/TP_ID/ACK/edi214xml-test83.txt.2023-11-21T19:26:49.774Z.TA1`
For direct transformer API calls, the format is `s3://amzn-s3-demo-bucket/OUT/ACK/filename.timestamp.997` (`.TA1` for TA1 acknowledgements).
# EDI splitting
AWS B2B Data Interchange supports splitting of inbound X12 EDI documents that contain multiple transactions into individually processed single-transaction documents. This capability increases the maximum supported file size for multi-transaction EDI documents from 150MB to 5GB and enables independent processing of each transaction, even when trading partners send them batched in a single EDI file.
With EDI splitting, each resulting single-transaction document is independently validated and processed, emitting its own set of logs and EventBridge events. This enables individual post-processing and downstream business-system ingestions. For example, you can use the "Split Transformation Completed" events to trigger AWS Glue ETL jobs to automatically ingest valid transactions into your purpose-built data lake, while using the "Split Transformation Failed" events to notify your trading partner of issues with individual transactions of their EDI document.
## How EDI Splitting Works
When EDI Splitting is enabled, AWS B2B Data Interchange processes each X12 EDI file as follows:
1. The service parses and validates the EDI file, generates acknowledgement documents for the entire original document (if requested), and identifies the individual transactions within the EDI interchange
1. The service generates individual, temporary EDI files for each transaction, maintaining all header and trailer-level information from the original EDI interchange within each separated transaction.
1. The service processes each split file individually, applying validation and any configured transformations.
1. Individual EventBridge events are published for each post-split file processing, enabling automated downstream workflows.
When splitting is enabled, validation errors are handled as follows:
+ If an inbound EDI document fails validation because of issues in its interchange or functional group header/trailer segments, it will not be split and will fail processing altogether.
+ If an inbound EDI document fails validation because of issues in segments contained in one of its transactions, the document will still be split, and individual post-split documents will be processed by the service.
## Key Benefits
EDI Splitting offers several key benefits:
+ *Increased File Size Support*: With splitting enabled, AWS B2B Data Interchange can handle X12 EDI files up to 5GB, compared to the standard 150MB limit for non-split files.
+ *Independent Transaction Processing*: Each transaction is processed independently, allowing valid transactions to proceed even if others in the batch contain errors.
+ *Granular Event-Driven Workflows*: Individual EventBridge events for each transaction enable fine-grained control over downstream processing.
+ *Improved Error Handling*: Transaction-level validation provides more precise error reporting and enables targeted reprocessing of failed transactions.
+ *Simplified Integration*: Individual transaction processing simplifies integration with downstream business systems that expect single-transaction inputs.
## Limits and Considerations
AWS B2B Data Interchange has the following limits for EDI Splitting:
+ Maximum of 100 transactions per split file
+ Increased file size limit of 5GB for split-enabled files (compared to 150MB for non-split files)
+ Splitting is only available by transaction, not by functional group or other criteria
When implementing EDI splitting, consider the following:
+ *Acknowledgments*: AWS B2B Data Interchange currently generates only a single functional and technical ACK document for the original inbound X12 EDI document, not individual ACK documents for each post-split document.
+ *API Limitations*: Direct invocation of a Transformer via `StartTransformerJob` API does not support splitting. Attempting to use `StartTransformerJob` to launch a Transformer that is configured to split input documents will result in an error.
+ *Billing*: There are no extra charges for splitting an inbound X12 EDI document. You will be billed based on the original inbound X12 EDI file and not the individual post-split X12 EDI files.
+ *Exceeding Transaction Limits*: X12 EDI documents that contain more than 100 transactions will not be split, and AWS B2B Data Interchange will fail an attempt to process such documents, recording a relevant error message into your CloudWatch logs and emitting a relevant error event to EventBridge.
If you have an EDI file that contains more than 100 transactions, we recommend that you pre-process the file and break it down into multiple EDI files, each containing no more than 100 transactions.
For more information about service quotas, see [Quotas for AWS B2B Data Interchange](b2bi-quotas.md).