X12 EDI Converter AWS Lambda Function

Overview

You can install the EDI converter as an AWS Lambda function.

With Lambda, you receive identical capabilities as our EDI CLI tool plus the scalability advantages of AWS Lambda.

The Lambda function ingests X12 EDI files from an S3 bucket and writes converted files to another S3 bucket.

You can invoke the converter Lambda with a custom event containing object keys.

You can also configure a trigger on an S3 bucket so the converter automatically processes all new files in that bucket. This approach ensures that all uploads are handled immediately without manual intervention.

Current release: 2.14.9.

Installation and Configuration

Installation using AWS Console UI and AWS CLI

Within the AWS console, create a Lambda function using the Java 25 runtime (Java 21 is also compatible).

Assign the function the permissions to read objects from the input bucket and write to the output bucket by modifying the function’s role in the IAM console. For example, to grant read/write access to all buckets, add the following fragment to the policy:

{
    "Sid": "AllowS3Access",
    "Effect": "Allow",
    "Action": "s3:*",
    "Resource": "*"
}

Configure the “General Configuration” for the Lambda to allocate sufficient ephemeral storage. The converter first downloads files to the ephemeral storage. For this reason, ensure the storage is large enough to accommodate your largest EDI file. If your EDI files are small, the default 512-MB storage should suffice. In this case, enable “SnapStart” for faster startups.

Install the function’s code. You can install the code from our public S3 bucket or by running the following AWS CLI command:

aws lambda update-function-code --function-name EdiConverter \
 --s3-bucket ediconverter --s3-key ediconvert-lambda-2.14.zip

All examples in this document assume macOS or Linux. Replace EdiConverter with your function name if different.

You need a license key to run the converter. Request your trial license key here and then define the EDI_LICENSE_KEY environment variable with the value of the key.

Set the function’s event handler based on your use case (Runtime Settings/Handler). For custom events, use the default handler: hdi.aws.ConverterEventHandler::handleRequest. For S3 trigger events (when you want the function to respond automatically to new files in a bucket), use hdi.aws.ConverterTriggerEventHandler::handleRequest.

You may want to create two different functions, each with its own event handler, to handle different use cases.

Increase the function’s timeout to 2 minutes. If your EDI files are large, set it to 5 minutes.

Installation using Terraform

You can find the Terraform project for the converter here.

The project contains two Terraform modules:

• edi-convert-lambda - Lambda function for custom events
• edi-convert-lambda-trigger - Lambda function for S3 trigger events

Clone the github repo or download Terraform files. Update function names and bucket names as needed.

After that, run terraform apply to install the functions.

Testing the Installation

To quickly test the installation, submit the following event (hdi.aws.ConverterEventHandler::handleRequest event handler must be set):

{
  "isAboutOnly": true
}

You’ll see the response containing the version of the converter and the license information.

The function can be configured using several environment variables, see the list here.

Invoking the Converter’s Lambda Function

You need to set the function’s event handler to hdi.aws.ConverterEventHandler::handleRequest.

You can use the command below to set the event handler:

aws lambda update-function-configuration \
--function-name EdiConverter \
--handler hdi.aws.ConverterEventHandler::handleRequest

The event handler accepts custom events in this format.

Simple event with a single input object key:

{
  "inBucket": "edi-in",
  "inKey": "837p.dat",
  "outBucket": "edi-out"
}

To invoke the function using AWS CLI:

aws lambda invoke --function-name EdiConverter --cli-binary-format raw-in-base64-out \
--payload '{ "inBucket": "edi-in",  "inKey": "837p.dat", "outBucket": "edi-out" }' edi-converter-response.json && cat edi-converter-response.json

It is also possible to provide a list of input object keys to convert multiple files and to specify the output key:

{
  "inBucket": "edi-in",
  "inOutKeys": [
    {
      "inKey": "837p.dat",
      "outKey": "837p-converted"
    },
    {
      "inKey": "837i.dat",
      "outKey": "837i-converted"
    }
  ],
  "outBucket": "edi-out"
}

Convert one file at a time to benefit from the Lambda’s scalability; each file is converted in a separate process.

You can find event examples in the converter’s GitHub repo.

Request Object

You can provide directory names as part of your input or output keys, e.g., prof-edi/edi-1.dat.

In/Out Key Pair Object

Function’s Response Object

The function returns a list of converted input object keys and corresponding output object keys, e.g.:

[
  {
    "inBucket": "edi-in",
    "inKey": "837p.dat",
    "outBucket": "edi-out",
    "outKey": "837p-converted",
    "outFormat": "JSON"
  },
  {
    "inBucket": "edi-in",
    "inKey": "837i.dat",
    "outBucket": "edi-out",
    "outKey": "837i-converted",
    "outFormat": "JSON"
  }
]

Running the Converter’s Lambda Function from an S3 Trigger

You can create a trigger on an input S3 bucket to invoke the function whenever a new file arrives.

Switch the event handler to hdi.aws.ConverterTriggerEventHandler::handleRequest in Runtime Settings/Handler for use with S3 triggers. Also, define the OUT_BUCKET environment variable so the function knows where to write outputs. This event handler accepts standard S3 events.

You can use the command below to set the event handler:

aws lambda update-function-configuration \
--function-name EdiConverter \
--handler hdi.aws.ConverterTriggerEventHandler::handleRequest

The function’s response is the same as for the custom event handler.

Error Handling

The converter throws an exception on any error. The response object is created by AWS and looks like this:

{
  "errorMessage": "File 837x.dat does not exist, or the bucket edi-in does not exist",
  "errorType": "hdi.aws.AwsConverterException",
  "stackTrace": [
    "hdi.aws.S3EdiClient.downloadFile(S3EdiClient.java:90)",
    "hdi.aws.AwsConverter.convertFiles(AwsConverter.java:120)",
    "hdi.aws.ConverterEventHandler.handleRequest(ConverterEventHandler.java:28)",
    "java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(Unknown Source)",
    "java.base/java.lang.reflect.Method.invoke(Unknown Source)"
  ]
}

The error information is also logged in the function’s logs.

For asynchronous invocations, configure a dead-letter queue or an error destination. The message in the queue will contain the request object with the failed file’s key.

Environment Variables Reference

We recommend updating environment variables using Terraform or AWS CLI.