# Transforming and generating EDI
There are multiple ways to transform or generate X12 EDI in AWS B2B Data Interchange. This topic describes the various ways you can create and configure inbound and outbound transformations.
+ *Inbound EDI*: you receive an X12 EDI document from your trading partner. AWS B2B Data Interchange converts this X12 EDI document into a JSON or XML formatted data file with a service-defined structure. You can optionally apply a mapping—written in JSONata or XSLT—to produce a custom JSON or XML formatted data file.
+ *Outbound EDI*: you have a JSON or XML formatted data file containing information that you wish to incorporate into an X12 EDI document that will be sent to your trading partner. You can align your JSON or XML formatted data file to conform with the service-defined structure directly, or you can apply a mapping in JSONata or XSLT to convert your custom JSON or XML into the service-defined structure necessary to produce an outbound X12 EDI document.
As a prerequisite, you must set up bucket policies for the Amazon S3 buckets that you use with B2B Data Interchange, as described in [Configuring S3 bucket policies](b2bi-prereq.md#bucket-policy-configuration).
**Topics**
+ [Generative AI-assisted EDI mapping](generative-ai-assisted-mapping.md)
+ [Inbound EDI](transform-inbound-variations.md)
+ [Outbound EDI](transform-outbound-variations.md)
# Generative AI-assisted EDI mapping
The AWS B2B Data Interchange generative AI-assisted EDI mapping capability expedites the process of writing and testing bi-directional EDI mappings, reducing the time, effort, and costs associated with migrating your EDI workloads to AWS. This capability leverages your existing EDI documents and transactional data samples to generate mapping code using generative AI. You can then use the generated mapping code as a starting point and further customize it to produce output formats that align with downstream data integration needs.
The following video provides a brief introduction to the AWS B2B Data Interchange generative AI capabilities.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/KUhdqpXEvNg)
**Topics**
+ [Prerequisites for using the AWS B2B Data Interchange generative AI-assisted EDI mapping capability](#ai-assist-prereq)
+ [Notes about generative AI-assisted EDI mapping](#notes-ai-assist)
+ [Using generative AI-assisted EDI mapping in AWS B2B Data Interchange](#use-ai-mapping)
## Prerequisites for using the AWS B2B Data Interchange generative AI-assisted EDI mapping capability
Before you can use this feature, you need to enable the models in Amazon Bedrock.
**Note**
You do not incur additional AWS B2B Data Interchange charges to generate mapping code beyond the standard [Amazon Bedrock Pricing](https://aws.amazon.com/bedrock/pricing).
**To enable models in Amazon Bedrock**
1. Sign in to the AWS Management Console and open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/).
1. From the left-hand navigation menu, choose **Model access** from the **Amazon Bedrock configurations** pane.
1. Enable all Anthropic models (AWS B2B Data Interchange currently uses Claude 3.7 Sonnet, Claude 3.5 Sonnet v1, and Claude 3 Sonnet), then choose **Next**.
In the future, there may be newer models that we will suggest that you enable as well.
1. If prompted, you may provide your use case details for access to the Anthropic models, including your company name, URL, industry, user persona, and description of your use case.
1. Review your selected models, and if you don't need to make any changes, choose **Submit**.
## Notes about generative AI-assisted EDI mapping
Note the following:
+ This feature is available for both inbound and outbound EDI processing.
+ To use this feature, you must upload input and output samples when you configure a transformer.
+ An accuracy score is generated for each mapping, to help you determine whether additional edits are needed.
+ Mapping code is generated during configuration of your transformer resource, and not a transformation runtime.
+ No customer data is stored or used to train the models: each mapping generated is a one-time operation.
+ Currently, the AWS B2B Data Interchange generative AI-assisted EDI mapping capability is only supported in the US East (N. Virginia) and US West (Oregon) regions.
## Using generative AI-assisted EDI mapping in AWS B2B Data Interchange
The transformer configuration wizard has three steps:
1. Transformer configuration
1. Mapping configuration
1. Review and create
For details on creating bi-directional transformers, see [Create an inbound transformer](transform-inbound-variations.md#getting-started-transformer) or [Create an outbound transformer](transform-outbound-variations.md#outbound-transformer).
To use the AWS B2B Data Interchange generative AI-assisted EDI mapping capability, make sure to upload both an input and output sample in the transformer configuration step (*Step 1*) when creating or updating your transformer resource. If you’ve specified both an input and output sample in Step 1, you see the **Generate Mapping** option enabled during the mapping configuration step (*Step 2*).
**To use generative AI-assisted EDI mapping in AWS B2B Data Interchange**
1. Upload your EDI document sample and JSON or XML data file sample to an Amazon S3 bucket (or buckets) with the appropriate policy and permissions. For details, see [Setting up S3 bucket policies and permissions](b2bi-prereq.md#buckets-and-permissions).
1. Navigate to the transformer homepage in the AWS B2B Data Interchange console. Choose **Create transformer** to create a new transformer or select an existing transformer from the list and choose **Edit** to update the configuration. In the **Sample documents** section, specify the input and output samples that you uploaded to Amazon S3 in the previous step.
1. Select **Generate Mapping**. You can view the progress and percentage complete in the progress bar.
In the **Generate Mapping - optional** pane, notice the following note: **By selecting Generate Mapping, you acknowledge that additional charges will be incurred for the use of Amazon Bedrock.**
![\[Screen showing the Mapping configuration panel with a mapping run in progress.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/transformer-ai-001.png)
The **Mapping editor** pane will be empty before you select **Generate Mapping** and while the mapping is being generated.
This screen shows the **Mapping editor** panes before you select **Generate Mapping** and the Mapping pane is empty.
![\[Screen showing the Mapping editor panels where the Mapping panel is blank.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/gen-ai-before.png)
1. When the mapping completes, you see the **Generate Mapping was successful** message. You also see the **Mapping editor** has been populated with mapping code.
![\[Screen showing the Mapping editor panels where the Mapping panel has been populated with the Amazon Bedrock generated code.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/gen-ai-after.png)
After the mapping has been generated, the **Diff and Accuracy details** displays the **Mapping accuracy score** and the **Mapping evaluation**. Note the following:
+ The accuracy score remains active as you continue to make manual edits, and changes based on your editing.
+ The score is determined by how well the provided sample output matches against the output document that is generated by the generative AI-assisted EDI mapping.
+ The generated score is determined by counting the number of matching lines and divides by the total number of lines in the original output document. For example, if 19 of 20 lines match, the accuracy score is 95%.
+ If you are unsatisfied with the mapping, return to Step 1 to specify alternate input and output samples. Then, return to Step 2 and select **Re-generate Mapping**. Using alternate EDI document and JSON or XML data file samples will result in new mapping code.
![\[Screen showing the Diff and Accuracy details panel with an accuracy score of 75.76%.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/transformer-ai-002.png)
1. When your mapping is in a satisfactory state, select **Next** to proceed to step 3, **Review and create**.
Continue to the **Review and create** step, as described in [Create an inbound transformer](transform-inbound-variations.md#getting-started-transformer) or [Create an outbound transformer](transform-outbound-variations.md#outbound-transformer).
# 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).
# Outbound EDI
You can use AWS B2B Data Interchange to generate X12 EDI documents for purposes of sending transactional data to your partners. AWS B2B Data Interchange also automatically generates X12 functional acknowledgements (including TA1s, 997s, and 999s) in response to inbound EDI.
For example, you may need to send an 810 Invoice after receiving an 850 Purchase Order from a manufacturing customer. Similarly, you may need to send an 835 Claim Payment after receiving an 837 Claim from a healthcare provider. Whether responding to or initiating a transaction, there are numerous scenarios where you may need to generate and send X12 EDI outbound to your trading partners. To generate outbound X12 EDI, it is common to use JSON or XML formatted data for your input. This data is typically exported from a downstream application, such as an Enterprise Resource Planning (ERP) solution or Claims Management Software (CMS) system. Now, however, you can use B2B Data Interchange to generate the X12 EDI documents.
You start with an XML or JSON formatted file as input, and use the service to generate the X12 EDI document. B2B Data Interchange then saves it to an Amazon S3 bucket that has been configured to store your output X12 EDI documents. From Amazon S3, you can automatically send it to your trading partner using AWS Transfer Family or any other data connectivity solution.
Currently, there is one way to transform JSON- or XML-formatted data into EDI: **by dropping your JSON or XML files into Amazon S3 locations that you have specified for monitoring**. With this approach, you configure an outbound transformer that is configured to transform JSON or XML data into an X12 EDI document. You then drop JSON or XML 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 and write the generated X12 into the output directory. The input and output directory used are those specified in your trading capability with trading partner ID added to the prefixes. As part of the partnership configuration, you specify one or more trading capabilities to use.
The process is similar to the corresponding inbound process. The difference is that prefixes using the trading capability ID and trading partner ID are added to the directories that you specify in the trading capability.
For example, assume that you specify the following directories in your trading capability:
+ Capability input directory: `s3://EDI-bucket/input-JSON/`
+ Capability output directory: `s3://EDI-bucket/output-EDI/`
When you associate your trading capability with your partnership, the service adds prefixes to both the input and output directory, changing them to the following:
+ Input directory to drop JSON or XML files becomes `s3://EDI-bucket/input-JSON//`
+ Output directory containing the generated X12 documents becomes `s3://EDI-bucket/output-EDI//`
You then drop JSON or XML files into the trading-partner-ID prefix in the input directory to generate EDI. The generated EDI is then written to the trading-partner-ID prefix in the output directory.
Similar to the inbound process, this allows you to associate one trading capability with multiple partnerships, and have partnerships that are associated with multiple trading capabilities. Using the trading capability and trading partner IDs as prefixes gives you clear delineation as to where the EDI documents for a specific partner should be stored.
## Generating outbound EDI documents
Typically, you perform the following steps to generate X12 EDI documents as output.
1. [Create a profile](#outbound-profile)
1. [Create an outbound transformer](#outbound-transformer)
1. Write or import mapping code that the system uses to generate a valid X12 EDI document.
You can start with an EDI document, and then run the [CreateStarterMappingTemplate](https://docs.aws.amazon.com/b2bi/latest/APIReference/API_CreateStarterMappingTemplate.html) operation to create your mapping template.
1. [Create a trading capability for outbound EDI](#create-outbound-capability). Make sure to select **Outbound** for the **EDI direction**.
1. [Create a partnership for outbound EDI](#outbound-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.
**Tip:** These testing instructions are written for testing inbound EDI, so you need to adapt them for testing outbound EDI.
## 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 outbound transformer
An outbound transformer takes in a sample template and produces an EDI, X12-formatted document that you can send to your trading partners.
**To create an outbound 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. On the Transformer configuration page, enter the following information.
1. Enter a name (no spaces).
1. In **Transfer settings**, choose **Outbound EDI**, and select an EDI document number and X12 version from the dropdown menus.
1. For the Input format, select **JSON** or **XML**, depending upon the format for the documents to be converted by this transformer.
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. In the **Sample documents** pane, select a sample input document, and optionally a sample output document from your available Amazon S3 buckets.
Provide the bucket and prefix in Amazon S3 for a sample document. This is useful for making sure the transformer functions correctly.
![\[The Choose an archive in S3 page, listing available buckets and documents.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/s3-bucket-sample-document.png)
1. Choose **Next** to proceed to the next stage of transformer creation.
![\[The AWS B2B Data Interchange console Transformers wizard Select input page, showing the source document options.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/transformer-wizard-outbound-01.png)
1. The **Mapping configuration** screen appears, with the **Mapping editor** panel populated. You can use generative AI-assisted EDI mapping to expedite the mapping configuration. For details, see [Generative AI-assisted EDI mapping](generative-ai-assisted-mapping.md).
![\[The Mapping configuration pane, with the representation of the sample file populated.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/transformer-wizard-outbound-02a.png)
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.
You use the **Mapping template editor** to only include certain pieces of your EDI documents.
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.
The pieces you select are previewed in the mapping preview pane.
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.
![\[The AWS B2B Data Interchange console Transformers wizard review page.\]](http://docs.aws.amazon.com/b2bi/latest/userguide/images/transformer-wizard-outbound-03.png)
1. After your review is complete, choose **Save** to create the transformer.
## Create a trading capability for outbound 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 a 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 **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.
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 outbound 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.
If you intend to perform outbound EDI transformations with this partner, fill in details in the **Outbound EDI configuration** section.
**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. Enter header details in the **Outbound EDI configuration**. The system uses the outbound EDI header information to format the outbound EDI document according to the needs of the partner to whom you are sending these documents.
1. Provide **Interchange control header** information (also known as the ISA segment).
1. Provide **Functional group header** information (also known as the GS segment).
1. Specify starting control numbers. For more information about control numbers, see [Control number configuration](#partnership-control-number-config).
1. Optionally, specify **Delimiters**. When creating or updating a partnership, you must specify all delimiters or leave them all blank. Defining certain delimiters, but not others, is not a valid configuration. Take care when specifying delimiters: for more information, see [Delimiters for outbound EDI](#outbound-delimiters).
1. In the New Lines Formatting section, specify the behavior that you require.
+ Select a new line formatting configuration option. Choose **New line on character count** only when your trading partner specifically requires it, as trading partners might reject your EDI files because of misinterpretation.
+ Choose the character to represent new lines in your generated EDI documents.
1. Optionally, for **EDI validation**, select **Enable outbound EDI** (selected by default).
1. Optionally, add tags as needed.
1. After you have configured all of the settings, choose **Create partnership**.
After you create a partnership, B2B Data Interchange monitors the prefixes containing the trading partner ID using Amazon S3 events.
When EDI documents are written to the partnership ID prefix, they are automatically transformed into JSON/XML files and written to the partnership ID prefix that is nested within the output directory. When JSON or XML data files are written to the partnership ID prefix they are automatically transformed into X12 EDI documents and written to the partnership ID prefix that is nested within the output directory and trading capability ID prefix.
Finally, we highly recommend that you subscribe to events emitted by B2B Data Interchange for status updates on transformation jobs. For more information, see [Inbound transformations](transform-inbound-variations.md#inbound-table) or [Outbound transformations](#outbound-table).
## Control number configuration
You can configure the starting values for control numbers used in EDI documents generated by AWS B2B Data Interchange.
A control number is an integer that is used to identify a specific interchange, functional group, or transaction within a functional group as it pertains to a specific trading partner. AWS B2B Data Interchange generates control numbers for each X12 envelope contained in a generated EDI acknowledgement or outbound EDI document. The control numbers created and maintained by B2B Data Interchange include the following:
+ **Interchange Control Number**: For the ISA (interchange) envelope, B2B Data Interchange generates an interchange control number that is unique to the sender ID and receiver ID pair. For example, the first acknowledgement or outbound EDI document sent from **SEND01** to **RECV01** receives an ICN of 001. The next interchange (whether an acknowledgement or outbound EDI document) sent from **SEND01** to **RECV01** receives an ICN of 002, and so on.
**Note**
Specifically, this number is unique for the I*SA05 and ISA06 (sender)* & *ISA07 and ISA08 (receiver)* combination.
+ **Functional Group Control Number**: For the GS (functional group) envelope, B2B Data Interchange generates a functional group control number that is unique to the sender ID, receiver ID, and functional identifier code combination. For example, the first functional group in an interchange sent from **SEND01** to **RECV01** with a functional identifier code of FA, would be assigned a functional group control number of 001. The next functional group (whether in the same interchange or a new interchange) with the same unique combination of sender ID, receiver ID, and functional identifier code is assigned a functional group control number of 002, and so on.
In the case where there is a functional group with the same sender ID and receiver ID, but a different functional identifier code, the functional group control number would also be 001, as this introduces a new, unique combination of sender ID, receiver ID, and functional identifier code.
**Note**
Specifically, the functional group control number is unique for the *GS01 (functional identifier code)* & *GS02 (sender)* & *GS03 (receiver)* combination.
+ **Transaction Set Control Number**: For ST (transactional level) envelope, B2B Data Interchange generates a unique transaction set control number for every transaction in a functional group. For example, if there are three transactions in a functional group, the transactions are assigned transaction set control numbers of 001, 002, and 003. In the case where there is another functional group in the same interchange with two transactions, the transactions in this functional group are assigned transaction set control numbers of 001 and 002.
The following sample EDI document shows the relationship of the three envelopes (indenting added for readability).
```
ISA*01*0000000000*01*0000000000*ZZ*ABCDEFGHIJKLMNO*ZZ*123456789012345*101127*1719*U*00400*000003438*0*P*>
GS*FA*999999999*4405197800*20111206*1100*1*X*004010VICS
ST*997*0001
AK1*PO*1421
AK9*A*1*1*1
SE*4*0001
GE*1*1
IEA*1*000000001
```
### Migration considerations
When migrating from another EDI system to AWS B2B Data Interchange, you may want to continue the sequence of control numbers from your previous system. Configure the starting control number parameters in your partnership settings to maintain continuity and prevent duplicate interchange and functional group control numbers
For example, if your previous system used interchange control numbers up to 9999, you could configure AWS B2B Data Interchange to start from 10000:
```
{
"controlNumbers": {
"startingInterchangeControlNumber": 10000
}
}
```
## Delimiters for outbound EDI
If your input JSON or XML files contain any delimiters, the service replaces them with a `?` (question mark) character, to ensure that all generated output files have valid EDI format.
Note the following:
+ When you create your partnership and specify delimiters, make sure that none of the delimiter characters are in your input files.
+ If you don't specify delimiters when you create your partnership, the system uses defaults. The default delimiters are `*` (asterisk), `:` (colon), `~` (tilde), and `\n` (newline).
+ Make sure that your mapping template doesn't introduce any delimiter characters into the content that will be transformed to EDI.