Getting started with AWS B2B Data Interchange (B2Bi)

To use AWS B2B Data Interchange, you create profiles, transformers, capabilities, and partnerships. This topic describes how to create and configure these basic building blocks for this service.

To build and run your EDI-based workflows on AWS B2B Data Interchange, you need to create a profile, transformer, trading capability, and partnership. Follow the instructions below or use the quick setup guide to easily create each of these resources, which enable you to connect with your trading partners and start transforming EDI data into JSON and XML to simplify your downstream integrations.

Setting up

Before you can use B2Bi, you must sign up for an AWS account.

Topics

• Sign up for an AWS account
• Create a user with administrative access
• Configure an Amazon S3 bucket

Sign up for an AWS account

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

   When you sign up for an AWS account, an AWS account root user is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform tasks that require root user access.

AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to https://aws.amazon.com/ and choosing My Account.

Create a user with administrative access

After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.

Secure your AWS account root user

1. Sign in to the AWS Management Console as the account owner by choosing Root user and entering your AWS account email address. On the next page, enter your password.

   For help signing in by using root user, see Signing in as the root user in the AWS Sign-In User Guide.

2. Turn on multi-factor authentication (MFA) for your root user.

   For instructions, see Enable a virtual MFA device for your AWS account root user (console) in the IAM User Guide.

Create a user with administrative access

1. Enable IAM Identity Center.

   For instructions, see Enabling AWS IAM Identity Center in the AWS IAM Identity Center User Guide.

2. In IAM Identity Center, grant administrative access to a user.

   For a tutorial about using the IAM Identity Center directory as your identity source, see Configure user access with the default IAM Identity Center directory in the AWS IAM Identity Center User Guide.

Sign in as the user with administrative access

• To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.

  For help signing in using an IAM Identity Center user, see Signing in to the AWS access portal in the AWS Sign-In User Guide.

Assign access to additional users

1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.

   For instructions, see Create a permission set in the AWS IAM Identity Center User Guide.

2. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see Add groups in the AWS IAM Identity Center User Guide.

Configure an Amazon S3 bucket

You need to have an Amazon S3 bucket set up and ready to use. B2Bi requires buckets for storing input, output, and instruction documents. For details, see Getting started with Amazon S3.

• Maximum EDI (electronic data interchange) file size is 5 MB.

• The Amazon S3 bucket must be in the same AWS account as the B2Bi user.

• The Amazon S3 bucket must be in the same region as the B2Bi user.

Quick setup

This section details a quick setup. From the B2Bi landing page (https://console.aws.amazon.com/b2bi/), you can choose Quick setup. Additionally, we provide a self-contained, AWS CloudFormation template to quickly create a B2Bi configuration. For details, see Configure AWS B2B Data Interchange using a AWS CloudFormation template.

The quick setup makes it easy for you to create the resources needed to build and run your EDI-based workflows on AWS B2B Data Interchange. Follow the steps below to connect with your trading partners and start transforming EDI data in JSON and XML to simplify your downstream integrations.

Note

If you don't see the landing page, select AWS B2B Data Interchange at the top of the left navigation menu.

1. The Create profile screen appears. Fill in your details as described in Step 1 Create a profile, then select Next.

2. The Create transformer screen appears. Fill in your details as described in Step 2 Create a transformer, then select Next.

3. The Create trading capability screen appears. Fill in your details as described in Step 3 Create a trading capability, then select Next.

   Note

   Make sure to choose Copy policy, for both your input and output directory, save the policy code, and then paste the policies into your input and output directory's bucket policy.

4. The Create partner screen appears. Fill in your details as described in Step 4 Create a partnership, then select Next.

5. The Review and create screen appears, showing all the details you've entered. You can select Cancel, or Previous if anything needs to be changed, or Complete setup to create your profile, transformer, capability and partnership.

Step 1 Create a profile

A profile is the mechanism used to create the concept of a private network. 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 characteristics for the customer, not the trading partner.

• Logging: This section describes the logging configuration. You can also opt out of logging (not recommended).

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.

Step 2 Create a 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 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. Select an EDI document number and X12 version from the dropdown menus.

      

   3. Provide the bucket and prefix in Amazon S3 for a sample document. This is useful for making sure the transformer functions correctly.

      

3. For the template configuration, choose the document format, JSON or XML. This populates the mapping editor, which shows the representation.

   

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

Step 3 Create a trading capability

A trading capability contains the information required to transform incoming EDI documents into JSON or XML outputs.

To create a 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 capability.

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

     Note

     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.

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

   • For your input and output directories, update the bucket policy (Configure your Amazon S3 bucket policies) and turn on EventBridge notifications (Configure your Amazon S3 bucket EventBridge setting).

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

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.

   

Example bucket policies

You need to update your Amazon S3 bucket policies to include the appropriate permissions so that the B2Bi service can access EDI documents and store transformed JSON / XML outputs. When you create a capability, you have the option to copy a bucket policy that contains the correct permissions to work with your input and output Amazon S3 buckets.

The following are policies copied from the Create trading capability page. You can select View to view your bucket. Then, from your bucket page, choose Permissions > Bucket policy > Edit, and then paste this policy into the Policy field.

Note

In these examples, replace each user input placeholder with your own information.

Example Amazon S3 input bucket policy

Example Amazon S3 input bucket policy copied from the Trading capabilities page.

{
    "Version": "2012-10-17",
    "Id": "B2BIEdiCapabilityInputPolicy",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "b2bi.amazonaws.com"
            },
            "Action": [
                "s3:GetObject",
                "s3:GetObjectAttributes"
            ],
            "Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/input-folder*",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "account-id"
                }
            }
        }
    ]
}

Example Amazon S3 output bucket policy

Example Amazon S3 output bucket policy copied from the Trading capabilities page.

{
    "Version": "2012-10-17",
    "Id": "B2BIEdiCapabilityOutputPolicy",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "b2bi.amazonaws.com"
            },
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:AbortMultipartUpload"
            ],
            "Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/output-folder/*",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "account-id"
                }
            }
        }
    ]
}

If you have SSE-KMS encryption enabled on your input or output bucket, you need to update the key policy in AWS KMS. You need to add the B2Bi service principal and the appropriate permissions to the policy.

Example Amazon S3 input AWS KMS key policy

The following example policy is for use with an encrypted input/source bucket. It includes the permission needed to decrypt an encrypted file.

{
    "Version": "2012-10-17",
    "Id": "B2BIEdiCapabilityInputKeyPolicy",
    "Statement": [
        {
            "Sid": "Allow administration of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::account-id:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow B2Bi access",
            "Effect": "Allow",
            "Principal": {
                "Service": "b2bi.amazonaws.com"
            },
            "Action": "kms:Decrypt",
            "Resource": "*"
        }
    ]
}

Example Amazon S3 output AWS KMS key policy

The following example policy is for use with an encrypted output bucket. It includes the permission needed to encrypt a file for storing into the bucket.

{
    "Version": "2012-10-17",
    "Id": "B2BIEdiCapabilityOutputKeyPolicy",
    "Statement": [
        {
            "Sid": "Allow administration of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::account-id:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow B2Bi access",
            "Effect": "Allow",
            "Principal": {
                "Service": "b2bi.amazonaws.com"
            },
            "Action": "kms:GenerateDataKey",
            "Resource": "*"
        }
    ]
}

If you are using the same bucket for input and output, you can use either example key policy, and add in the other permission. In this case, the policy is as follows.

{
    "Version": "2012-10-17",
    "Id": "B2BIEdiCapabilityOutputKeyPolicy",
    "Statement": [
        {
            "Sid": "Allow administration of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::account-id:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow B2Bi access",
            "Effect": "Allow",
            "Principal": {
                "Service": "b2bi.amazonaws.com"
            },
            "Action": [
                 "kms:GenerateDataKey",
                 "kms:Decrypt"
             ],
            "Resource": "*"
        }
    ]
}

Configure your Amazon S3 bucket policies

You can copy example policies as described in the preceding section. If one or both of your buckets use SSE-KMS encryption, you also need to update your AWS KMS key policy, as described in Example bucket policies.

Note

For details on temporary files and directories, see Temporary files and Amazon S3 permissions.

Perform this procedure for both your input and output directories.

Configure your bucket policy

1. Sign into the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/ and navigate to your bucket.

2. After you open the detail page for your bucket, choose the Permissions tab.

3. In the Bucket policy panel, choose Edit.

4. Paste in the appropriate bucket policy, depending on whether this is your input or output bucket.

5. Choose Save to save the policy.

Configure your Amazon S3 bucket EventBridge setting

You need to turn on Amazon EventBridge for your input and output Amazon S3 buckets.

Turn on EventBridge notifications

1. Sign into the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/ and navigate to your bucket.

2. After you open the detail page for your bucket, choose the Properties tab.

3. Scroll down to the Amazon EventBridge panel. If notifications are off, proceed to the next step. If they are on, you can skip the remainder of this procedure.

4. To turn on EventBridge notifications, choose Edit.

5. Select On, and choose Save changes.

Temporary files and Amazon S3 permissions

For your output bucket policies, you need to have the s3:GetObject and s3:DeleteObject permissions. These permissions are required so that B2Bi read and then remove temporary files that the service uses to transform your EDI documents.

The service uses s3:DeleteObject to delete temporary files, which can be ten times as large as the X12 input file. If your bucket policy doesn't include s3:DeleteObject, the service continues to work as expected. However, B2Bi would not be able to delete these temporary files: they would then remain in Amazon S3 (and incur charges).

The service adds a new prefix to your output directory, customerOutputDirectory/parsed, for its use, and customerOutputDirectory/tradingPartnerId/parsed for use by Amazon S3 (if you have a partnership). These locations are used exclusively for holding temporary files. If your bucket policy includes the s3:DeleteObject permission, you should never see these folders. If you don't have that permission, then the temporary files continue to be written and remain in these folders.

Step 4 Create a partnership

A partnership represents the connection between you and your trading partner. It ties together a profile and one or more trading capabilities.

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. Enter a descriptive name for the partnership.

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

4. Choose a profile from the dropdown menu.

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

6. Optionally, add tags as needed.

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

Next steps

Your trading partners can use AWS Transfer Family or any connectivity option to route incoming EDI documents to the configured input folder, where they will be picked up and transformed by B2Bi. You and your partners can see recent activity in CloudWatch Logs. Additionally, inbound EDI files automatically create a return acknowledgement to the trading partner, in the form of an Amazon EventBridge event. For details, see AWS B2B Data Interchange acknowledgements.