EDI Generator can convert your flat EDI files into a more versatile, tree-like structure. With transforms, you can convert this tree structure into any other format that you prefer - such as XML, JSON, CSV, or even plain text.
After receiving an EDI file, EDIG converts and saves it as a hierarchical structure of loops and segments. Using a transform, you can convert this data structure to another format; removing/ignoring parts, combining fields, adding custom data elements, changing layout/ordering, and so forth. For example you can generate a CSV from the item details in a PO (850) EDI.
The transformation facility is available as a standalone service/API; it is not related to any incoming/outgoing documents. Even if you do not transact (receive, generate or send) EDI files through our platform, you can still use the transform API to convert EDI files into other formats using stateless HTTP/REST API calls.
Before you can start a conversion, you have to define a corresponding transform on your EDIG account. This is a schema or a set of rules, that can transform an input of a specific format into another specific format.
EDIG currently supports XML stylesheets (XSLT) based transforms. While XSLT can be relatively complex to write, they can generate outputs of any format, including non/XML like JSON or CSV.
This largely depends on the input/source EDI document that you intend to transform, and the rule format (XSLT, JSON-to-JSON, etc.). However the following basic points apply:
For example, in XSLT mode, you can use the following “identity” transform to obtain an exact copy of the originally mentioned tree structure, in XML format:
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output omit-xml-declaration="yes" indent="yes"/>
<xsl:strip-space elements="*"/>
<xsl:template match="node()|@*">
<xsl:copy>
<xsl:apply-templates select="node()|@*"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
The Transforms page of EDIG has a Try Out button, which allows you to interactively develop and test a transform rule-set.
During testing, EDIG will:
If any step fails, instead of the output, you will receive a pop-up indicating the error. You can immediately modify the EDI input and/or the logic to fix the issue, and re-run the test to verify it.
Once you are satisfied with the transformation output, you can directly proceed to save the transform by clicking Save.
You should save each developed transform with a unique name, so that it can be later used to perform conversions; either through the REST API, or from the web UI itself.
You can test/try-out, modify and re-save a created transform any time, using the corresponding action buttons on the transform list/table.
After you have developed and saved a transform, you can directly submit EDI files to the REST API, to convert them using that transform.
API endpoint:
https://us-central1-edigateway-prod.cloudfunctions.net/convert
Authentication:
use the access token (see below) as an Authorization: Bearer {token value} request header
Request headers:
Authorization: bearing the API access token as aboveContent-Type: format of the source EDI file, usually application/x12Request query parameters:
transformName: name of the transform, from the saving step aboveediDefinitionName: name of the EDI definition to use, to parse the input documentpartnerAS2ID: AS2 identifier of the partner that the EDI belongs to; EDIG will try to automatically find the correct EDI definitionRequest body:
content of the raw EDI file (e.g. for X12, beginning with ISA.. and ending with ..IEA..)
A sample request using curl would look like:
curl -X POST "https://us-central1-edigateway-prod.cloudfunctions.net/convert?transformName={transform to use}&ediDefinitionName={definition matching EDI file}" \
-H "Content-Type: application/x12" \
-H "Authorization: Bearer {access token}" \
--data-binary "{EDI*file*content~}"
Response code:
Response headers:
Content-Type:
application/xml for XSLTtext/plainResponse body:
The transform API uses bearer-token authentication. You can obtain tokens from the Get API Tokens button of the transforms list page.
The API token generation pop-up will provide sample requests for the API calls, as well as the renewal of the API access token upon expiry.
This is the only credential to be used directly with the API. It will be issued for the currently logged-in EDIG user’s identity.
The token should be included as an Authorization request header, with a Bearer prefix:
Authorization: Bearer {value of the token string}
The token is short-lived (usually with 1-hour validity time) and should be renewed periodically using the refresh token. You can find the expiration timestamp (in seconds) of an existing token by JWT-decoding it, e.g. via Javascript:
JSON.parse(atob(token.split('.')[1])).exp
Do not pass this to actual API calls; instead, use it only to obtain a new access token when the current token has expired.
You can obtain a new token using a request similar to the following:
curl -X POST "https://us-central1-edigateway-prod.cloudfunctions.net/refreshToken" \
-H "Content-Type: text/plain" \
--data-binary "{refresh token value}"
The response will be JSON, of format (possibly including more fields):
{
"access_token": "herebe.accesstoken.whichisalongJWTstring",
"expires_in": "3600"
}
where access_token is the new token and expires_in is its validity duration (seconds, from the issuing time).