External integration

External integrations allow you to push received EDI files and/or their JSON converted copies, into external systems for further processing.

You can enable and configure an integration from the External Integration section of your Organization settings page.

An integration configured at organization level, can then be selectively enabled on a per-partner basis, so that you can choose to receive content for only a chosen set of partners that you are interested to perform further processing. When enabling an integration, EDIG will also prompt you to select a set of partners for whom the integration should be enabled. You can change this setting later for individual partners, using the Enable External Integration options under Processing (for all document types) or Document Types sections of each partner’s settings.

EDI Generator currently offers following options as integrations:

• HTTP endpoint (webhook)
• SFTP endpoint (upload)

HTTP endpoint

For each incoming EDI file, EDIG invokes a HTTP endpoint that you define/manage, with one or both of:

• received/original EDI file content
• JSON-converted EDI content

For details of the JSON format, refer this section.

Authentication

To prevent malicious parties from invoking your webhook with bogus requests resembling EDIG, it is recommended to implement authentication on your webhook receiver endpoint. Following auth mechanisms are supported:

• Basic Authentication: base-64 encoded username:password; e.g. Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
• API Key/Token: a static token, under a preferably named header; e.g. X-API-Token: {token value}
• Bearer Token: a standard bearer token (such as OAuth2); e.g. Authorization: Bearer {token value}
• JSON Signature: provide a private key for EDIG to sign the payload, and verify the signature on your end using the corresponding public key; check this reference for more details

For each scheme, EDIG allows you to choose a name for the HTTP request header to embed the auth details (which would generally be “Authorization”). It is the responsibility of your (recipient) system to process the auth details delivered in this header, to verify the authenticity of the request, before accepting or processing it further.

HTTP auto-retry

Auto-retry works as described in Dispatch auto-retry section. Following are some possible failure scenarios that could cause an auto-retry:

• your endpoint is unreachable, or does not speak valid HTTP
• your endpoint is HTTPS, but does not have a trusted certificate, or does not comply with strong SSL/TLS standards
• your endpoint times out (does not return a valid response within 1 minute)
• your endpoint does not return a “successful” HTTP response code (within range 200-300)

SFTP endpoint

For each incoming EDI file, EDIG uploads its JSON-converted content into a SFTP server/endpoint that you define/manage.

For details of the JSON format, refer this section.

Authentication

EDIG offers following auth options commonly used by SFTP servers:

• key based: provide a (possibly passphrase-protected) key file that EDIG will use when connecting/authenticating to the server
• password based: provide a direct password that can authenticate the configured SFTP user account

Key based authentication is generally considered as the safer approach.

Uploading configuration

EDIG requires following settings when configuring a SFTP endpoint as the integration:

• SFTP server hostname (address) and port number
• SFTP Username for the user account to connect/authenticate to
• credentials for authenticating as above user (explained previously)
• Upload path: target location to upload JSON files within the SFTP user’s folder structure

The path must be a directory, specified relative to the configured SFTP user’s home directory.

You can use placeholder expressions in the path, to dynamically decide the location at upload time:

• ${txnNo}: transaction number (ST02) from the incoming file (or comma-separated list if document has multiple transactions)
• ${txnType}: numeric transaction type (ST01, e.g. 856 for ASN) from the incoming file
• ${displayType}: 2-letter functional identifier code (GS01, e.g. “PO” for PO) from the incoming file
• ${date}: file received date, in ISO yyyy-MM-dd format
• ${timestamp}: file received timestamp, in ISO yyyy-MM-dd'T'HH-mm-ss.SSS'Z' format (with : characters replaced with -)
• ${partner.<fieldName>}: a desired field of the partner entry representing the EDI’s sender; see this section for supported fields
• ${tenant.<fieldName>}: a desired field of your (recipient’s) tenant/organization details; see this section for supported fields

The actual file will be saved under this path, as {original filename}.json (“.json” suffix appended to the original filename taken verbatim); if original file had an extension, it would be preserved and appear before the new “.json” suffix.

SFTP auto-retry

In case of error scenarios like the following, EDIG will auto-retry the SFTP upload as described in Dispatch auto-retry section. The same/original path will be used for all retries, so the upload is idempotent.

• your endpoint is unreachable, or does not speak valid SFTP
• a filesystem permission issue arises when uploading the file or creating any of the necessary parent directories
• the connection times out or otherwise faces some interruption, during the upload/transaction

EDIG will ignore some known “harmless” failure scenarios, such as “connection reset” (ECONNRESET) errors at connection closure after a successful upload completion (commonly seen among some Windows-based SFTP servers).

Dispatch auto-retry

If your endpoint fails to properly handle/acknowledge a dispatched file, EDIG will retry the dispatch for 3 more times (i.e. 4 total attempts), with a constant back-off interval of 5 minutes, before giving up and marking the corresponding inbox entry as “dispatch failed” along with the last failure description/message.

After rectifying the issue, you can retry such a failed dispatch from EDIG inbox list; it will retry the dispatch once, and move to one of “successfully dispatched” or “failed to dispatch” states based on the result.