How to get and configure the serial key?

To use EDI Tools for .NET, you need a valid serial key. Once you order a plan from EdiFabric, follow the instructions in this article to create an account and get your serial key.

The serial key is used to access the Authentication API to acquire a token. It's up to the consumer to implement exception handling and retry logic.

The serial key is applied programmatically using the following code:

try
{
    EdiFabric.SerialKey.Set("Valid Serial Key");
}
catch(Exception ex)
{
    // implement retry logic or refresh the token like this:
    EdiFabric.SerialKey.Set("Valid Serial Key", true);   
}

If you can't find your serial key or don't know how to apply it, contact us for assistance.

The trial comes with a provisional serial key that is valid for 14 days: c417cb9dd9d54297a55c032a74c87996

How to minimize the number of authentication calls?

Authentication tokens are valid for 30 days, and a distributed cache can be implemented to save the token to a file, Redis, SQL Server, or any other store of your choice. To achieve that, two methods are provided: EdiFabric.SerialKey.GetToken and EdiFabric.SerialKey.SetToken. Internally, EdiFabric.SerialKey.Set does the following:

  if (EdiFabric.SerialKey.DaysToExpiration < 3)
      EdiFabric.SerialKey.SetToken(EdiFabric.SerialKey.GetToken(serialKey));

An example implementation of a distributed file cache is available on GitHub.

The Authentication API has a maximum call rate of 60 API calls per minute. The fair usage daily quota is 10,000 API calls per 24 hours. If your usage exceeds any of these limits, you must implement a token cache.

How to use EdiFabric with no access to the Internet?

You can use EdiFabric in an environment that doesn't have access to the Internet by separating the token retrieval from the Authentication API and setting the token in applications that use EdiFabric. To achieve this, you must not use EdiFabric.SerialKey.Set but EdiFabric.SerialKey.GetToken and EdiFabric.SerialKey.SetToken instead.

A possible implementation of this would be:

• Create a separate application that has access to the Internet to call EdiFabric.SerialKey.GetToken on a scheduled basis. We recommend it runs once daily or weekly (must be less than the token's lifetime of 30 days). 
• Once the token is retrieved successfully (implement any retry/exception handling logic), store it in a cache (file, database, Redis, etc.).
• Your other applications that use EdiFabric and reside on a network without access to the Internet must have access to the cache where the token is stored.
• Each application that uses EdiFabric must first get a token from the cache (you may store as many valid tokens as you like) and set it by calling EdiFabric.SerialKey.SetToken.

We suggest you contact us immediately if you notice repeated failures to get a token from the Authentication API.

How does the serial key work?

The same key can be used across all products with every EdiFabric plan - as the API key when accessing EdiNation or EdiNation InHouse and as the serial key when using EdiFabric EDI Tools.

When EdiFabric.SerialKey.Set is invoked, EdiFabric EDI Tools initiates an HTTPS request to the authentication API to acquire a token. The serial key is used to authenticate the caller with the authentication API.

A call to the authentication API is made only when there is no token or the token has expired. No calls are initiated when EdiFabric.SerialKey.Set is invoked, and a valid token exists in memory.

The token is valid for 30 days, so if your application is constantly running, there will be no additional external calls until the token is valid. Alternatively, you can implement a distributed cache and only refresh the token several days before it is due to expire to avoid hard expiration.

Use the DaysToExpiration static property of EdiFabric.SerialKey to monitor when a token is due to expire.

EdiFabric.SerialKey.DaysToExpiration

Troubleshooting

If you get any of the following errors:

• Can't set token {token}. The token is invalid!
• Token {token} is invalid or has expired!

Consider forcing a token refresh in the exception handler by setting the second parameter of EdiFabric.SerialKey.Set to true:

try
{
    EdiFabric.SerialKey.Set("Valid Serial Key");
}
catch(Exception ex)
{
    EdiFabric.SerialKey.Set("Valid Serial Key", true);   
}

Always ensure the following:

• You are using EdiFabric version > 10.4.3 with the new serial/API keys
• You are using the same EdiFabric version across all your projects, e.g., not mixing multiple EdiFabric versions.
• The token hasn't expired - if EdiFabric.SerialKey.DaysToExpiration == 0, then the token has expired, and you need to refresh it by calling EdiFabric.SerialKey.Set.

What to do if there is no access to the Authentication API?

Ensure that external calls to the Authentication API are not blocked from your environment.

If setting firewall rules, the details of the Authentication API are:

Primary

Host: api.edination.com

IP: 104.211.12.89

Secondary

Host: api.edifabric.com

IP: N/A (floating)

We have prepared multiple servers for the authentication API shared between Microsoft Azure and Amazon AWS, so the servers going down altogether is highly unlikely. EdiFabric EDI Tools first calls the authentication API in Azure when acquiring a new token. If there is no response after the configured timeout/retries, the backup authentication API in AWS is called.

Implement a distributed cache for tokens and try to refresh them ahead of their expiration date. All EdiFabric.SerialKey methods require sufficient exception handling, and it's a good practice to implement a retry or compensation logic when acquiring a token from the Authentication API.

However, in the event that the authentication API is down across the primary and the backup instances or no token can be acquired at all, you need to contact us here or at support@edifabric.com, and we'll provide you with a temporary token that can be installed on your server(s) either as an environment variable or as a parameter to EdiFabric.SerialKey.SetToken.  This way EdiFabric will work in full offline mode until connectivity to the authentication API is restored.

We will also publish the temporary token on our Twitter, so contacting us there is also recommended.