Struct ipworksedi::GISBReceiver

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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 struct is designed to be easily incorporated into an HTTP server, and features custom functionality for server environments such as ASP.NET.

Basic Operation

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

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

Finally, the struct will generate a response which you may send to the client with send_response.

The most important part of the response is the request_status; this property will contain either "ok" or an error message to be returned to the requesting client. By default the struct will accept any post that conforms to the standard. If you want to be more restrictive you should first invoke parse_request to determine the sender, check the message security used, and extract the EDI data. If there is a problem you may then set request_status to an error before calling create_response. Please see the request_status 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 create_response and sent with send_response.

To create log files, set log_directory prior to invoking process_request. 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 struct may be used to interface directly with the underlying HTTP context. If request is not set by the user parse_request and process_request will first get the request from the underlying HTTP environment, if possible. send_response will send the reply in this environment if able; otherwise the reply will be directed to standard out.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksEDI. Due to this, the GISBReceiver struct cannot be disposed of automatically. Please, call the dispose(&self) method of GISBReceiver when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

data_element_count property (GISBReceiver Struct)

The number of records in the DataElement arrays.

Syntax

fn data_element_count(&self) -> Result<i32, IPWorksEDIError> 
fn set_data_element_count(&self, value : i32) ->  Option<IPWorksEDIError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• data_element_name
• data_element_value

The array indices start at 0 and end at data_element_count - 1.

Data Type

i32

data_element_name property (GISBReceiver Struct)

The name of the current data element.

Syntax

fn data_element_name(&self, ElementIndex : i32) -> Result<String, IPWorksEDIError> 
fn set_data_element_name(&self, ElementIndex : i32, value : &str) ->  Option<IPWorksEDIError> 
fn set_data_element_name_ref(&self, ElementIndex : i32, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The name of the current data element.

The ElementIndex parameter specifies the index of the item in the array. The size of the array is controlled by the data_element_count property.

Data Type

String

data_element_value property (GISBReceiver Struct)

The value of the current data element.

Syntax

fn data_element_value(&self, ElementIndex : i32) -> Result<String, IPWorksEDIError> 
fn set_data_element_value(&self, ElementIndex : i32, value : &str) ->  Option<IPWorksEDIError> 
fn set_data_element_value_ref(&self, ElementIndex : i32, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The value of the current data element.

The ElementIndex parameter specifies the index of the item in the array. The size of the array is controlled by the data_element_count property.

Data Type

String

data_from property (GISBReceiver Struct)

The identity of the sending system.

Syntax

fn data_from(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

data_to property (GISBReceiver Struct)

The identity of the receiving system.

Syntax

fn data_to(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

error_message property (GISBReceiver Struct)

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

Syntax

fn error_message(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

error_message will be set in case the request is an error notification rather than a post. The error_message 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.

Data Type

String

edi_data property (GISBReceiver Struct)

This property contains the EDI payload of the transmission.

Syntax

fn edi_data(&self) -> Result<Vec<u8>, IPWorksEDIError> 

Default Value

""

Remarks

In a receiver, this property will only be populated if edi_output_stream has not been specified and parse_request finishes without an error. edi_data will contain the full decrypted text of the EDI message.

This property is read-only.

Data Type

Vec<u8>

edi_type property (GISBReceiver Struct)

The EDIType of the EDI message.

Syntax

fn edi_type(&self) -> Result<String, IPWorksEDIError> 

Default Value

"X12"

Remarks

The EDIType of the EDI message. The default value is "X12". edi_type may also be set to "error", in which case the message is an error relating to a previous message. In this case the error_message property and related properties will provide more information.

This property is read-only.

Data Type

String

edi_file_name property (GISBReceiver Struct)

In a sender, if FileName is specified, the file specified will be used for the EDI payload of the transmission.

Syntax

fn edi_file_name(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

In a sender, if edi_file_name is specified, the file specified will be used for the EDI payload of the transmission. edi_name will be populated with the name of the file.

In a receiver, if this property is set prior to calling parse_form_data and parse_request the incoming data will be decrypted and written to the file at the specified path.

Note: When edi_output_stream is set, the data will be written to the stream and this property will not be populated.

This property is read-only.

Data Type

String

edi_name property (GISBReceiver Struct)

Name is the final name to be associated with the contents of either the Data or FileName properties.

Syntax

fn edi_name(&self) -> Result<String, IPWorksEDIError> 

Default Value

"rfc1767.edi"

Remarks

edi_name is the final name to be associated with the contents of either the edi_data or edi_file_name properties. This corresponds to the filename attribute of the Content-Disposition header for the EDI payload.

When constructing EDI data to be sent, edi_name will be set to the same value as edi_file_name, but can be overridden after setting edi_file_name to indicate that another name should be used in the outbound request's Content-Disposition MIME header.

When receiving EDI data, edi_name will be read out of the "filename" attribute of the inbound request's Content-Disposition MIME header.

This property is read-only.

Data Type

String

gisb_version property (GISBReceiver Struct)

The version of the GISB/NAESB protocol used.

Syntax

fn gisb_version(&self) -> Result<String, IPWorksEDIError> 

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.

Data Type

String

log_directory property (GISBReceiver Struct)

The path to a directory for logging.

Syntax

fn log_directory(&self) -> Result<String, IPWorksEDIError> 
fn set_log_directory(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_log_directory_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

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 struct 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 struct. 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 log_file 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.

Data Type

String

log_file property (GISBReceiver Struct)

The log file written.

Syntax

fn log_file(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

public_keyring_data property (GISBReceiver Struct)

Public keyring data.

Syntax

fn public_keyring_data(&self) -> Result<Vec<u8>, IPWorksEDIError> 
fn set_public_keyring_data(&self, value : Vec<u8>) ->  Option<IPWorksEDIError> 
fn set_public_keyring_data_ref(&self, value : &[u8]) ->  Option<IPWorksEDIError> 

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 secret_keyring_data and the keyring will be loaded from this data instead of the homedir.

Data Type

Vec<u8>

receipt_signing_protocol property (GISBReceiver Struct)

The protocol used to sign the receipt, if any.

Syntax

fn receipt_signing_protocol(&self) -> Result<String, IPWorksEDIError> 
fn set_receipt_signing_protocol(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_receipt_signing_protocol_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

After you invoke parse_request 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 create_response this protocol will be used to sign the receipt.

Data Type

String

receipt_type property (GISBReceiver Struct)

The type of receipt to be returned, if any.

Syntax

fn receipt_type(&self) -> Result<String, IPWorksEDIError> 

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 struct to throw an exception. You may, if you wish, catch this exception, generate your own response, and send it using send_response.

This property is read-only.

Data Type

String

request property (GISBReceiver Struct)

The HTTP request to be processed.

Syntax

fn request(&self) -> Result<Vec<u8>, IPWorksEDIError> 
fn set_request(&self, value : Vec<u8>) ->  Option<IPWorksEDIError> 
fn set_request_ref(&self, value : &[u8]) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

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

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

Data Type

Vec<u8>

request_headers property (GISBReceiver Struct)

The HTTP headers in the request.

Syntax

fn request_headers(&self) -> Result<String, IPWorksEDIError> 
fn set_request_headers(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_request_headers_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The entire list of HTTP and MIME headers.

Data Type

String

request_status property (GISBReceiver Struct)

The status of the request.

Syntax

fn request_status(&self) -> Result<String, IPWorksEDIError> 
fn set_request_status(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_request_status_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

"ok"

Remarks

request_status will be determined by parse_request or process_request, 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 struct. Other types of errors are by mutual agreement. In particular the use of message security is not enforced by the struct 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 request_status 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 struct 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

Data Type

String

response property (GISBReceiver Struct)

The response generated by the struct.

Syntax

fn response(&self) -> Result<Vec<u8>, IPWorksEDIError> 

Default Value

""

Remarks

The response generated by the struct after invoking process_request or create_response. 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 request_status to an appropriate value before invoking create_response.

This property is read-only.

Data Type

Vec<u8>

response_headers property (GISBReceiver Struct)

The response headers generated by the struct.

Syntax

fn response_headers(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

The response headers generated by the struct after invoking process_request or create_response. In general response_headers will consist of a single "Content-Type" header or an empty string.

This property is read-only.

Data Type

String

secret_keyring_data property (GISBReceiver Struct)

Secret keyring data.

Syntax

fn secret_keyring_data(&self) -> Result<Vec<u8>, IPWorksEDIError> 
fn set_secret_keyring_data(&self, value : Vec<u8>) ->  Option<IPWorksEDIError> 
fn set_secret_keyring_data_ref(&self, value : &[u8]) ->  Option<IPWorksEDIError> 

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 public_keyring_data and the keyring will be loaded from this data instead of the homedir.

Data Type

Vec<u8>

server_id property (GISBReceiver Struct)

The ID of your server.

Syntax

fn server_id(&self) -> Result<String, IPWorksEDIError> 
fn set_server_id(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_server_id_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The ID of your server, as it will be described in the response. If you do not specify server_id the struct will attempt to determine it when you call process_request or create_response.

Data Type

String

transaction_id property (GISBReceiver Struct)

The transaction ID of the message.

Syntax

fn transaction_id(&self) -> Result<String, IPWorksEDIError> 
fn set_transaction_id(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_transaction_id_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

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

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

Data Type

String

config method (GISBReceiver Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) -> Result<String, IPWorksEDIError>

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, 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.

create_response method (GISBReceiver Struct)

Creates the response.

Syntax

fn create_response(&self) -> Result<(), IPWorksEDIError>

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.

parse_form_data method (GISBReceiver Struct)

Processes the form data, and populates the appropriate properties.

Syntax

fn parse_form_data(&self) -> Result<(), IPWorksEDIError>

Remarks

Invoking parse_form_data scans the form data, allowing you to determine the identity of the sender. The following properties will be populated: data_from, data_to, edi_type, gisb_version, and receipt_type. parse_request may be used to read the entire message.

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

parse_request method (GISBReceiver Struct)

Processes the EDI data.

Syntax

fn parse_request(&self) -> Result<(), IPWorksEDIError>

Remarks

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

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

Invoking process_request is equivalent to invoking parse_request and then create_response. Calling the methods separately allows you to change the value of request_status before generating the response; for example, you may choose to feed gisb_data to an EDI translator before generating a positive response.

process_request method (GISBReceiver Struct)

Processes the EDI data, and generates the receipt.

Syntax

fn process_request(&self) -> Result<(), IPWorksEDIError>

Remarks

Invoking ProcessRequest automates the entire server process. The method scans the request, determines the edi_data, and generates the response and response_headers. The method's functionality is the same as the combined functionality of parse_form_data, parse_request, and create_response.

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 send_response in case of either success or failure.

The struct will populate edi_data if possible.

read_request method (GISBReceiver Struct)

Reads the AS2 request from the given HTTP servlet request.

Syntax

fn read_request(&self) -> Result<(), IPWorksEDIError>

Remarks

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

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

reset method (GISBReceiver Struct)

Resets the state of the control.

Syntax

fn reset(&self) -> Result<(), IPWorksEDIError>

Remarks

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

send_response method (GISBReceiver Struct)

In a server environment, responds to the requesting client.

Syntax

fn send_response(&self) -> Result<(), IPWorksEDIError>

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 create_response or process_request.

set_pgp_param method (GISBReceiver Struct)

Sets a parameter in the PGP provider.

Syntax

fn set_pgp_param(&self, name : &str, value : &str) -> Result<(), IPWorksEDIError>

Remarks

Invoke set_pgp_param 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 set_pgp_param.

on_error event (GISBReceiver Struct)

Fired when information is available about errors during data delivery.

Syntax

// GISBReceiverErrorEventArgs carries the GISBReceiver Error event's parameters.
pub struct GISBReceiverErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// GISBReceiverErrorEvent defines the signature of the GISBReceiver Error event's handler function.
pub trait GISBReceiverErrorEvent {
  fn on_error(&self, sender : GISBReceiver, e : &mut GISBReceiverErrorEventArgs);
}

impl <'a> GISBReceiver<'a> {
  pub fn on_error(&self) -> &'a dyn GISBReceiverErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn GISBReceiverErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

The error_code 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.

on_log event (GISBReceiver Struct)

Fired with log information while processing a message.

Syntax

// GISBReceiverLogEventArgs carries the GISBReceiver Log event's parameters.
pub struct GISBReceiverLogEventArgs {
  fn log_type(&self) -> &String
  fn log_message(&self) -> &[u8]
}

// GISBReceiverLogEvent defines the signature of the GISBReceiver Log event's handler function.
pub trait GISBReceiverLogEvent {
  fn on_log(&self, sender : GISBReceiver, e : &mut GISBReceiverLogEventArgs);
}

impl <'a> GISBReceiver<'a> {
  pub fn on_log(&self) -> &'a dyn GISBReceiverLogEvent;
  pub fn set_on_log(&mut self, value : &'a dyn GISBReceiverLogEvent);
  ...
}

Remarks

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

Log messages available through this event correspond to log files written to log_directory. This event provides a way to obtain log messages without relying on files on disk. This event fires regardless of the value of log_directory (i.e. when log_directory 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:

Config Settings (GISBReceiver Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

GISBReceiver Config Settings

Base Config Settings

Trappable Errors (GISBReceiver Struct)

GISBReceiver Errors

MIME Errors