GISBReceiver Component

Properties   Methods   Events   Config Settings   Errors  

The GISBReceiver component is used to process EDI messages and generate receipts.

Syntax

nsoftware.IPWorksEDI.GISBReceiver

Remarks

The GISBReceiver implements server-side processing of EDI messages, as specified in versions 1.4 and 1.6 of the GISB/NAESB specification. It can be used to decrypt and verify incoming messages; in version 1.6, it may additionally be used to generate signed receipts. The component is designed to be easily incorporated into an HTTP server, and features custom functionality for server environments such as ASP.NET.

Basic Operation

The ProcessRequest method is used to process incoming messages and generate responses. ProcessRequest will parse the form data, determine DataFrom and DataTo, and then attempt to process any signed or encrypted data using PGP.

The following table defines possible values that may be passed to the SetPGPParam.

Finally, the component will generate a Response which you may send to the client with SendResponse.

The most important part of the Response is the RequestStatus; this property will contain either "ok" or an error message to be returned to the requesting client. By default the component will accept any post that conforms to the standard. If you want to be more restrictive you should first invoke ParseRequest to determine the sender, check the message security used, and extract the EDI data. If there is a problem you may then set RequestStatus to an error before calling CreateResponse. Please see the RequestStatus property for a list of standard error messages.

If you use version 1.4 of the GISB/NAESB protocol, the response will be a simple HTML reply. If you use version 1.6 the sender has the option of requesting a signed receipt. In all cases the response may be created with CreateResponse and sent with SendResponse.

To create log files, set LogDirectory prior to invoking ProcessRequest. This will log all incoming and outgoing data, and will also write the received EDI files to disk.

Additional Server-Side Functionality

When used in a server environment such as ASP, ASP.NET, etc., the component may be used to interface directly with the underlying HTTP context. If Request is not set by the user ParseRequest and ProcessRequest will first get the request from the underlying HTTP environment, if possible. SendResponse will send the reply in this environment if able; otherwise the reply will be directed to standard out.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

DataElements Property (GISBReceiver Component)

Collection of data elements for the client's request.

Syntax

• C#
• VB.NET

public GISBElementList DataElements { get; }

Public Property DataElements As GISBElementList

Remarks

Data elements will include required elements such as "to", "from", "input-format", etc., and may contain other elements as sent by your trading partner.

This property is not available at design time.

DataFrom Property (GISBReceiver Component)

The identity of the sending system.

Syntax

• C#
• VB.NET

public string DataFrom { get; }

Public ReadOnly Property DataFrom As String

Default Value

""

Remarks

Will generally be the DUNS number of the sending trading partner.

This property is read-only.

DataTo Property (GISBReceiver Component)

The identity of the receiving system.

Syntax

• C#
• VB.NET

public string DataTo { get; }

Public ReadOnly Property DataTo As String

Default Value

""

Remarks

Will generally be the DUNS number of the receiving trading partner.

This property is read-only.

ErrorMessage Property (GISBReceiver Component)

If the client sent an error notification, the error message.

Syntax

• C#
• VB.NET

public string ErrorMessage { get; }

Public ReadOnly Property ErrorMessage As String

Default Value

""

Remarks

ErrorMessage will be set in case the Request is an error notification rather than a post. The ErrorMessage will contain the entire contents of the error notification.

For example, the following might be returned:

orig-from=123456789*
orig-to=234567890*
orig-input-format=X12*
resp-time-c=11960619102855*
resp-server-id=coolhost*
resp-trans-id=234423897*
request-status=EEDM601: Public Key Invalid*
comments=Please contact 1-800-555-1212 for correct public key*

This property is read-only.

GISBData Property (GISBReceiver Component)

The EDI Payload of the message.

Syntax

• C#
• VB.NET

public GISBData GISBData { get; }

Public ReadOnly Property GISBData As GISBData

Remarks

The EDI Payload of the message.

This property is read-only.

GISBVersion Property (GISBReceiver Component)

The version of the GISB/NAESB protocol used.

Syntax

• C#
• VB.NET

public string GISBVersion { get; }

Public ReadOnly Property GISBVersion As String

Default Value

"1.4"

Remarks

The version of the GISB/NAESB protocol used. Note that when receiving documents the version will be determined automatically.

This property is read-only.

LogDirectory Property (GISBReceiver Component)

The path to a directory for logging.

Syntax

• C#
• VB.NET

public string LogDirectory { get; set; }

Public Property LogDirectory As String

Default Value

""

Remarks

Setting LogDirectory will instruct the component to log the details of each transmission to unique files in the specified directory. For each request processed, the component will log the complete text of the incoming request, the EDI data (if it was able to be determined), and the outgoing response.

Two files will be written for each transmission. The diagnostic log will have the extension ".log" and will log the complete text of the incoming request, the EDI data (if it was able to be determined), and the outgoing response. The data file will have the extension ".dat" and will store the EDI data only. In case of error an additional file with extension ".err" file will be written, and the error information will also be written to the ".log" file.

The filenames will be chosen automatically by the component. Each filename will be the system time, in the format YYYY-MM-DD-HH-MM-SS-MMMM, with extensions "-2", "-3", used in case files of those names already exist. After each transaction is processed LogFile will contain the name of the files just written, minus the extension ".log" or ".dat".

If either log cannot be written an exception will be thrown; server applications should ensure that the server has the appropriate write permissions.

LogFile Property (GISBReceiver Component)

The log file written.

Syntax

• C#
• VB.NET

public string LogFile { get; }

Public ReadOnly Property LogFile As String

Default Value

""

Remarks

In case LogDirectory is specified two log files will be written in the specified directory and LogFile will contain the path. A diagnostic log will be written with filename LogFile + ".log" and the EDI data will be written with filename LogFile + ".dat". In case of error an additional file will be written with filename LogFile + ".err".

This property is read-only.

PublicKeyringData Property (GISBReceiver Component)

Public keyring data.

Syntax

• C#
• VB.NET

public string PublicKeyringData { get; set; }
public byte[] PublicKeyringDataB { get; set; }

Public Property PublicKeyringData As String
Public Property PublicKeyringDataB As Byte()

Default Value

""

Remarks

This property allows the public keyring data to be specific in the form of a byte array. Use this in conjunction with SecretKeyringData and the keyring will be loaded from this data instead of the homedir.

ReceiptSigningProtocol Property (GISBReceiver Component)

The protocol used to sign the receipt, if any.

Syntax

• C#
• VB.NET

public string ReceiptSigningProtocol { get; set; }

Public Property ReceiptSigningProtocol As String

Default Value

""

Remarks

After you invoke ParseRequest this property will contain the signing protocol requested by the client (either an empty string or "pgp-signature"; other values are not supported). When you invoke CreateResponse this protocol will be used to sign the receipt.

ReceiptType Property (GISBReceiver Component)

The type of receipt to be returned, if any.

Syntax

• C#
• VB.NET

public string ReceiptType { get; }

Public ReadOnly Property ReceiptType As String

Default Value

""

Remarks

The type of receipt to be returned. If this property is empty a simple HTML response will be returned. For a value of "GISB-Acknowledgement-Receipt" a more detailed receipt will be generated.

Other values are not supported and will cause the component to throw an exception. You may, if you wish, catch this exception, generate your own Response, and send it using SendResponse.

This property is read-only.

Request Property (GISBReceiver Component)

The HTTP request to be processed.

Syntax

• C#
• VB.NET

public string Request { get; set; }
public byte[] RequestB { get; set; }

Public Property Request As String
Public Property RequestB As Byte()

Default Value

""

Remarks

The body of the request to be processed. You may include the HTTP headers or specify them separately in RequestHeaders.

Typically the request may be read directly from the HTTP context, without setting this property.

This property is not available at design time.

RequestHeaders Property (GISBReceiver Component)

The HTTP headers in the request.

Syntax

• C#
• VB.NET

public string RequestHeaders { get; set; }

Public Property RequestHeaders As String

Default Value

""

Remarks

The entire list of HTTP and MIME headers.

RequestStatus Property (GISBReceiver Component)

The status of the request.

Syntax

• C#
• VB.NET

public string RequestStatus { get; set; }

Public Property RequestStatus As String

Default Value

"ok"

Remarks

RequestStatus will be determined by ParseRequest or ProcessRequest, and will contain the string "ok" or an error message to be returned in the Response.

Errors relating to message processing (e.g., "EEDM104: Missing Data File") will automatically be discovered and reported by the component. Other types of errors are by mutual agreement. In particular the use of message security is not enforced by the component by default. To require encryption or signing set RequireEncryption or RequireSignature and specify error EEDM602 or EEDM604 as appropriate.

It is recommended that you set RequestStatus to one of the standard errors listed below. The specification additionally allows for a supplemental error message; separate this from the standard error with a semicolon. For example, "EEDM107: Invalid input format; expected X12."

The following is the complete list of error codes defined by the GISB 1.4 and NAESB 1.6 specification. Error codes only defined in version 1.6 are notated with "1.6" below, and errors that will be detected and reported automatically by the GISBReceiver component are indicated with an asterisk.

The following is the complete list of error codes defined by the GISB 1.4 specification.

EEDM100*: Missing From Common Code Identifier Code

EEDM101*: Missing To Common Code Identifier Code

EEDM102*: Missing Input Format

EEDM103*: Missing Data File

EEDM104: Missing Transaction Set

EEDM105: Invalid From Common Code Identifier

EEDM106: Invalid To Common Code Identifier

EEDM107: Invalid Input Format

EEDM108: Invalid Transaction Set

EEDM109: No Parameters Supplied

EEDM110: (1.6) Invalid "version"

EEDM111: (1.6) Missing "version"

EEDM112: (1.6) "receipt-security-selection" not mutually agreed

EEDM113*: (1.6) Invalid "receipt-security-selection"

EEDM114: (1.6) Missing "receipt-disposition-to"

EEDM115: (1.6) Invalid "receipt-disposition-to"

EEDM116: (1.6) Missing "receipt-report-type"

EEDM117: (1.6) Invalid "receipt-report-type"

EEDM118: (1.6) Missing "receipt-security-selection"

EEDM119: (1.6) Mutually agreed element, refnum, not present

EEDM601: Public Key Invalid

EEDM602: File Not Encrypted

EEDM603: Encrypted File Truncated

EEDM604*: Encrypted File Not Signed Or Signature Not Matched

EEDM699: Decryption Error

EEDM701: EDM Party Not Associated With EDI Party

EEDM702: Data Structure Error

EEDM703: Data Set Exchange Not Established For Trading Partner

EEDM999: System Error

WEDM100: Transaction Set Sent Not Mutually Agreed

WEDM102: (1.6) "receipt-security-selection" not mutually agreed

WEDM103: (1.6) Missing "receipt-security-selection"

WEDM104: (1.6) Element refnum received; not mutually agreed; ignored

Response Property (GISBReceiver Component)

The response generated by the component.

Syntax

• C#
• VB.NET

public string Response { get; }
public byte[] ResponseB { get; }

Public ReadOnly Property Response As String
Public ReadOnly Property ResponseB As Byte()

Default Value

""

Remarks

The response generated by the component after invoking ProcessRequest or CreateResponse. The format of the response may range from a simple HTML response to a signed GISB-Acknowledgement-Receipt, depending on the client's request. In any case it will report success or failure as appropriate. If you wish to reject the request you may set RequestStatus to an appropriate value before invoking CreateResponse.

This property is read-only.

ResponseHeaders Property (GISBReceiver Component)

The response headers generated by the component.

Syntax

• C#
• VB.NET

public string ResponseHeaders { get; }

Public ReadOnly Property ResponseHeaders As String

Default Value

""

Remarks

The response headers generated by the component after invoking ProcessRequest or CreateResponse. In general ResponseHeaders will consist of a single "Content-Type" header or an empty string.

This property is read-only.

SecretKeyringData Property (GISBReceiver Component)

Secret keyring data.

Syntax

• C#
• VB.NET

public string SecretKeyringData { get; set; }
public byte[] SecretKeyringDataB { get; set; }

Public Property SecretKeyringData As String
Public Property SecretKeyringDataB As Byte()

Default Value

""

Remarks

This property allows the secret keyring data to be specific in the form of a byte array. Use this in conjunction with PublicKeyringData and the keyring will be loaded from this data instead of the homedir.

ServerId Property (GISBReceiver Component)

The ID of your server.

Syntax

• C#
• VB.NET

public string ServerId { get; set; }

Public Property ServerId As String

Default Value

""

Remarks

The ID of your server, as it will be described in the response. If you do not specify ServerId the component will attempt to determine it when you call ProcessRequest or CreateResponse.

TransactionId Property (GISBReceiver Component)

The transaction ID of the message.

Syntax

• C#
• VB.NET

public string TransactionId { get; set; }

Public Property TransactionId As String

Default Value

""

Remarks

A unique ID for the transaction. In GISB a TransactionId will generated by the server whenever you process a request. You may either allow the component to generate unique values for TransactionId, or devise your own scheme and set TransactionId before invoking CreateResponse.

If you devise your own scheme you should set TransactionId after invoking ParseRequest as ParseRequest will generate a new ID for the request.

Config Method (GISBReceiver Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateResponse Method (GISBReceiver Component)

Creates the response.

Syntax

• C#
• VB.NET

public void CreateResponse();

Async Version
public async Task CreateResponse();
public async Task CreateResponse(CancellationToken cancellationToken);

Public Sub CreateResponse()

Async Version
Public Sub CreateResponse() As Task
Public Sub CreateResponse(cancellationToken As CancellationToken) As Task

Remarks

Creates a response to the incoming request. The format of the request (signed receipt or simple HTML, for example) will depend on the request of the client.

ParseFormData Method (GISBReceiver Component)

Processes the form data, and populates the appropriate properties.

Syntax

• C#
• VB.NET

public void ParseFormData();

Async Version
public async Task ParseFormData();
public async Task ParseFormData(CancellationToken cancellationToken);

Public Sub ParseFormData()

Async Version
Public Sub ParseFormData() As Task
Public Sub ParseFormData(cancellationToken As CancellationToken) As Task

Remarks

Invoking ParseFormData scans the form data, allowing you to determine the identity of the sender. The following properties will be populated: DataFrom, DataTo, EDIType, GISBVersion, and ReceiptType. ParseRequest may be used to read the entire message.

If RequestHeaders is empty and Request contains both the headers and the message, Request will be split and stored in Request and RequestHeaders as described in the Request's description.

ParseRequest Method (GISBReceiver Component)

Processes the EDI data.

Syntax

• C#
• VB.NET

public void ParseRequest();

Async Version
public async Task ParseRequest();
public async Task ParseRequest(CancellationToken cancellationToken);

Public Sub ParseRequest()

Async Version
Public Sub ParseRequest() As Task
Public Sub ParseRequest(cancellationToken As CancellationToken) As Task

Remarks

Invoking ParseRequest parses the incoming request and attempts to determine the GISBData sent by the client. The method will first parse the form data unless you have already called ParseFormData.

The method will throw an exception if any errors are found. Regardless of success or failure the method will determine an appropriate value for RequestStatus. It is recommended that you catch any exceptions and invoke CreateResponse and SendResponse in case of either success or failure.

Invoking ProcessRequest is equivalent to invoking ParseRequest and then CreateResponse. Calling the methods separately allows you to change the value of RequestStatus before generating the response; for example, you may choose to feed GISBData to an EDI translator before generating a positive response.

ProcessRequest Method (GISBReceiver Component)

Processes the EDI data, and generates the receipt.

Syntax

• C#
• VB.NET

public void ProcessRequest();

Async Version
public async Task ProcessRequest();
public async Task ProcessRequest(CancellationToken cancellationToken);

Public Sub ProcessRequest()

Async Version
Public Sub ProcessRequest() As Task
Public Sub ProcessRequest(cancellationToken As CancellationToken) As Task

Remarks

Invoking ProcessRequest automates the entire server process. The method scans the request, determines the EDIData, and generates the Response and ResponseHeaders. The method's functionality is the same as the combined functionality of ParseFormData, ParseRequest, and CreateResponse.

The method will throw an exception if any errors are found. However, the Response will still be generated and will contain information about any errors. It is recommended that you catch any exceptions and invoke SendResponse in case of either success or failure.

The component will populate EDIData if possible.

ReadRequest Method (GISBReceiver Component)

Reads the AS2 request from the given HTTP servlet request.

Syntax

• C#
• VB.NET

public void ReadRequest();

Async Version
public async Task ReadRequest();
public async Task ReadRequest(CancellationToken cancellationToken);

Public Sub ReadRequest()

Async Version
Public Sub ReadRequest() As Task
Public Sub ReadRequest(cancellationToken As CancellationToken) As Task

Remarks

In the Java edition, reads the request from the specified HttpServletRequest. The request will be stored in Request and the headers in RequestHeaders. ParseRequest may then be invoked.

In versions other than Java, this method has no effect.

Reset Method (GISBReceiver Component)

Resets the state of the control.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

Reset resets the state of the component. All properties will be set to their default values.

SendResponse Method (GISBReceiver Component)

In a server environment, responds to the requesting client.

Syntax

• C#
• VB.NET

public void SendResponse();

Async Version
public async Task SendResponse();
public async Task SendResponse(CancellationToken cancellationToken);

Public Sub SendResponse()

Async Version
Public Sub SendResponse() As Task
Public Sub SendResponse(cancellationToken As CancellationToken) As Task

Remarks

When called from within a server environment, SendResponse will respond to the requesting client with the Response. The Response may be a simple HTML block (this will always be the case in version 1.4) or a GISB-Acknowledgement-Receipt, if requested by the client.

The exact behavior of the method is specific to the environment. In ASP or ASP.NET, the receipt will be sent within the current HTTP context. In Java, the receipt will be sent within the provided HttpServletResponse. Otherwise, the receipt will be directed to stdout. If this is impossible an exception will be thrown.

This method should only be invoked after Response has been generated by CreateResponse or ProcessRequest.

SetPGPParam Method (GISBReceiver Component)

Sets a parameter in the PGP provider.

Syntax

• C#
• VB.NET

public void SetPGPParam(string name, string value);

Async Version
public async Task SetPGPParam(string name, string value);
public async Task SetPGPParam(string name, string value, CancellationToken cancellationToken);

Public Sub SetPGPParam(ByVal Name As String, ByVal Value As String)

Async Version
Public Sub SetPGPParam(ByVal Name As String, ByVal Value As String) As Task
Public Sub SetPGPParam(ByVal Name As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

Invoke SetPGPParam to set parameters of your PGP provider. Please refer to the documentation provided with the PGP provider for the parameters required.

The following table defines possible values that may be passed to the SetPGPParam.

Error Event (GISBReceiver Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, GISBReceiverErrorEventArgs e);

public class GISBReceiverErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As GISBReceiverErrorEventArgs)

Public Class GISBReceiverErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (GISBReceiver Component)

Fired with log information while processing a message.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, GISBReceiverLogEventArgs e);

public class GISBReceiverLogEventArgs : EventArgs {
  public string LogType { get; }
  public string LogMessage { get; }
  public byte[] LogMessageB { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As GISBReceiverLogEventArgs)

Public Class GISBReceiverLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogType As String
  Public ReadOnly Property LogMessage As String
  Public ReadOnly Property LogMessageB As Byte()
End Class

Remarks

This event fires once for each log message generated by the component. The verbosity is controlled by the LogLevel setting.

Log messages available through this event correspond to log files written to LogDirectory. This event provides a way to obtain log messages without relying on files on disk. This event fires regardless of the value of LogDirectory (i.e. when LogDirectory is empty the event will still fire).

The LogMessage event parameter holds the raw log data.

The LogType event parameter indicates the type of log. Possible values are:

GISBData Type

The EDI payload of the message.

Remarks

The EDI payload of the message.

Fields

Constructors

• C#
• VB.NET

public GISBData();

Public GISBData()

• C#
• VB.NET

public GISBData(byte[] data, string EDIType);

Public GISBData(ByVal Data As Byte(), ByVal EDIType As String)

• C#
• VB.NET

public GISBData(string fileName, string EDIType);

Public GISBData(ByVal FileName As String, ByVal EDIType As String)

GISBElement Type

A name-value pair for extra data to be sent with a GISB message.

Remarks

A name-value pair for extra data to be sent with a GISB message.

Fields

Constructors

• C#
• VB.NET

public GISBElement();

Public GISBElement()

• C#
• VB.NET

public GISBElement(string name, string value);

Public GISBElement(ByVal Name As String, ByVal Value As String)

Config Settings (GISBReceiver Component)

GISBReceiver Config Settings

Base Config Settings

Trappable Errors (GISBReceiver Component)

GISBReceiver Errors

MIME Errors