Inbound EDI - AWS B2B Data Interchange
Transform EDI documents: overviewCreate a profileCreate an inbound transformerCreate a trading capabilityCreate a partnership

Inbound EDI

There are two ways that you can invoke a transformer.

  • Transformer only. 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.

  • Transformer with Trading Capability and Partnership. 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 and write the converted JSON or XML files or generated X12 into the 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:

    • Input directory: s3://EDI-bucket/input-EDI/

    • Output directory is 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 becomes s3://EDI-bucket/input-EDI/<partnership-id>/

    • Output directory 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.

Transform EDI documents: overview

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

  4. Create a partnership

  5. Test your outbound transformation workflow.

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. The AWS B2B Data Interchange console Transformers wizard Select input page, showing the source document options.

    6. Optionally, in the Sample documents pane, provide the bucket and prefix in Amazon S3 for the sample input document and sample output data file. This is useful for making sure the transformer functions correctly.

      The Choose an archive in S3 page, listing available buckets and documents.

    7. Optionally, add tags as needed.

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

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

    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

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 EDI document number and version from the corresponding dropdown menus.

    • Choose a transformer to determine how the incoming EDI documents should be transformed.

  3. In the Configure directory section, you configure both the input and output directories that are used to source and store documents. The input directory is the location form where we source EDI document input, and the output directory is where we store the translated JSON or XML output files.

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

    • For Add permissions, 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. In the Reference - optional panel, choose one or more files to share with your trading partner. Provide instructions and sample documents that can be accessed by your trading partners, so that they can align their EDI document formats with your transformation processes. You can directly enter the Amazon S3 path to a file, or choose Browse S3 to navigate to one or more files.

  5. Optionally, add tags as needed.

  6. After you have configured all of the settings, choose Create capability.

Note

Create a partnership

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