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 B2Bi 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 partnership 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 partnership 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/<partnership-id>/

  • Output directory containing the transformed JSON/XML files becomes s3://EDI-bucket/output-JSON/<partnership-id>/

  • The acknowledgement is stored in s3://EDI-bucket/output-JSON/<partnership-id>/ACK/

  You then drop files into the partnership-ID prefix in the input directory to transform EDI for that specific partner. The transformed JSON output is then written to the partnership-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 partnership ID makes sure that you have clear delineation as to where the transformed EDI data for a specific partner should be stored.

Transforming inbound EDI documents

Typically, you perform the following steps to transform X12 EDI documents into JSON or XML data

1. Create a profile.

2. Create an inbound transformer.

3. Create a trading capability for inbound EDI.

4. Create a partnership for inbound EDI.

5. 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

1. 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.

2. Enter the profile details, the name of the profile, the name of the business represented, and the contact information (email and phone number).

3. 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.

4. 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

1. 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.

2. 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).

   2. Ensure that Inbound EDI is selected.

   3. For Input Details, select an EDI document number and X12 version from the dropdown menus.

   4. For Input Details, select JSON or XML.

   5. 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.

   6. Optionally, add tags as needed.

   7. Select Next to proceed to the next step in the wizard.

3. 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. You can use generative AI-assisted EDI mapping to expedite the mapping configuration. For details, see Generative AI-assisted EDI mapping.

   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.

4. 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.

5. 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 a trading capability

1. 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.

2. 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.

3. 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

     B2Bi will create and monitor prefixes in your input directory for input X12 documents (for inbound X12) or for input JSON/XML documents (for generating X12).

   • 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

     B2Bi will create prefixes in the specified output directory to store the transformed X12 documents (in the case of inbound X12) or storing the generated X12 documents (in the case of outbound X12).

4. Optionally, add tags as needed.

5. 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

1. 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.

2. In the Partnership details section, provide the following information.

   1. Enter a descriptive name for the partnership.

   2. Enter an email address to associate with the partnership. Provide the trading partner's email address.

   3. Choose a profile from the dropdown menu.

   4. Select one or more trading capabilities from the Trading capabilities list.

3. Unless you intend to perform outbound EDI processing with this partner, you can skip the Outbound EDI configuration section.

4. Optionally, add tags as needed.

5. 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-.

EDI acknowledgements

B2Bi 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 B2Bi 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.

Note

The service generates either a 999 or 997 acknowledgement, but never both.

For details of the generated events, see Details fields for acknowledgement events.

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.

2. 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.

B2Bi 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.

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_ID/edi214xml-test83.txt

• Transformed output: s3://amzn-s3-demo-bucket/OUT/TP_ID/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_ID/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).