The AS2 standard provides the ability to securely transport EDI (and other data, including binary and XML) to a remote host.
This guarantees that the message has not been changed in-transit and is received and can be read only by the intended trading partner. A Message Disposition Notification receipt (MDN) further guarantees that the intended trading partner has received the message.
AS2 uses the HTTP protocol as its transport mechanism to send files over the Internet. Cleo VersaLex software uses the PUT (HTTP POST) action command to transport the secure data to the remote host.
Cleo VersaLex software supports AS2 versions 1.0, 1.1, 1.2, and 1.3.
AS2 Process Map
This section outlines the configuration necessary to set up the Generic AS2 host.
- AS2 Configuration
- Acquiring your trading partner's signing and encryption certificates
- Determining and providing your URL information
- Creating and providing your signing/encryption certificates
- Complete configuration of:
- Testing Your AS2 Installation
AS2 Configuration
A host describes the remote server of your trading partner to which messages will be sent. The host's parameters specify its location and how it is reached. Your remote trading partner should provide information to you in the form of a URL, which is used to configure the host parameters.
To configure a generic AS2 pre-configured host:
AS2 Host Configuration
A host describes the remote server of your trading partner to which messages will be sent. The host's parameters specify its location and how it is reached. Your remote trading partner should provide information to you in the form of a URL, which you will use to configure the host parameters.
This section describes how to configure a generic AS2 pre-configured host.
AS2 Host: General Tab
- Server Address
- Either a fully qualified name (recommended) or an IP address.
- Port
- The port on the server where your trading partner will receive your messages.
- Connection Type
- The kind of connection you want to use for this host.
- Forward Proxy
- The address of the forward proxy you want to use for this host.
- Default Directories
- Modify the default directories, if necessary. You can use macro variables from the drop-down lists. See Using Macro Variables for a list of the applicable macros (Default Host Directory context) and example usage. For the Cleo VLTrader and Cleo Harmony applications, see URI File System interface overview for information about you can use a Cleo-provided or custom URI for the Inbox and Outbox. See Specifying default host directories for information about setting up system-level directories and custom directory macro variables.
Note: If the host is has an external association, the default directories might be managed outside of the VersaLex application and not shown here.
- Inbox
- Default directory for incoming files. Enter a value directly or click … to navigate to and select a directory.
- Outbox
- Default directory for outgoing files. Enter a value directly or click … to navigate to and select a directory.
- Sentbox
- If specified, default directory for retaining sent files. Files are a copy of the original source file; any file manipulations performed as part of the send are not reflected in the sentbox copies. Enter a value directly or click … to navigate to and select a directory.
- Receivedbox
- If specified, default directory for retaining received files. Files are a copy of the final destination file; any file manipulations performed as part of the receive are reflected in the receivedbox copies. Enter a value directly or click … to navigate to and select a directory.
AS2 Host: AS2 Tab
- Partner Is CEM-Capable
- Specifies whether the trading partner is capable of sending and receiving certificates through Certificate Exchange Messaging (CEM) and allows you to enable Send in Certificate Exchange. See Exchanging certificates with your trading partner.
- Override AS2 Service Filename Preservation MDN Response Settings
-
Use Override AS2 Service Filename Preservation MDN Response Settings to select settings different from the system settings defined in the AS2 Service > AS2 Tab (see Configuring AS2 Service,) and then use Generate Filename Preservation MDN Responses to toggle Filename Preservation for this trading partner.
- Overwrite duplicate file names
- Allows for unique naming of stored files. When this check box is selected, any files that exist in the specified inbox will be overwritten. When cleared, incoming files with the same name as one that already exists will be appended with a unique number beginning with 1 and incremented each time a new file is saved.
- Use default file name
- Allows the incoming file to be given the name specified in its associated field. Use this option to override the file name specified by the sender. This feature is useful in situations where the received file name must be something other than its original file name, and is common for IBM i / iSeries (AS/400) platforms where the file name must be specified with a .mbr extension. This field can also include any of the supported macros allowing for the incoming file to be named, for example, with a date-time stamp. Subdirectory path identifiers (i.e., ‘/’ or ‘\’) can also be used in conjunction with macros to allow filtering of the incoming file to a specific subdirectory under the inbox based on the value of the macro variable. See Using macro variables (Destination File context) for a discussion of all applicable macros.
Note: If a subdirectory path is specified and it does not already exist, it will automatically be created as needed unless the subdirectory path is under an inbox on the AS/400 Native File System. In that case, the physical file denoting the subdirectory path (in the form: DIRECTORY.FILE) must be created under the specified inbox before files can be written to it.
- Add Content-Type Directory to Inbox
- allows for sorting of incoming messages based on content-type to a subdirectory (under the Inbox specified on the Generaltab). Specify each of the Content-Types that you would like directed to specific subdirectories by entering a name in the Directoryfield. Directory entries may be made for Content-Types of: EDIFACT, X12, XML, Binary, Plain Text, EDI Consent and Other (a default catch-all for messages with all other Content-Types you could receive). The same subdirectory can be used for multiple Content-Types. You can also leave Directory entries blank, which will cause any received messages of that Content-Type to be stored in the Inbox specified on the General tab.
For IBM i / iSeries (AS/400) usage, see AS/400 Setup and installation or AS/400 PC network access setup for information on configuring the Content-Type Inbox settings to access the Native File System (NFS).
Note: If you use this feature, incoming messages will be placed in the specified folder based on the content type specified in the HTTP header of the message. The VersaLex application does not check the actual content of the message to determine its content type.
AS2 Host: HTTP Tab
- Outbound
- Indicates whether you use SSL or not for outbound file transfers.
- HTTP
- Do not require use SSL
- HTTP/s
- Require SSL for outbound file transfers.
- Inbound
-
- HTTP/s only
- Require your trading partner to use Secure Socket Layer (SSL) for inbound file transfers.
- Command
- In most cases the CONNECT command is not used and should be left blank. In rare instances, CONNECT is required by the remote server to identify the client, particularly if SSL has not been used.
- Method
- The only valid Method for AS2 commands is PUT ("POST").
- Path
- The server Path for the PUT command.
- Parameters
- By default, no Parameters are specified for sending AS2 messages. If parameters are required, they must be obtained from your trading partner when the trading relationship is established. Given the URL provided by your remote trading partner in the form:
http(s)://remote-host:port/resource-path?optional-parametersEnter the bolded portion in this field (if it was supplied).
- Headers
- At a minimum, the following Headers must always be specified in order to properly send AS2 messages:
- AS2-From - the alias of the sender of the AS2 message.
-
AS2-To - the alias of the receiver of the AS2 message.
Note: The AS2-From / AS2-To fields are determined and agreed upon as part of the initial setup of the trading relationship. These fields could be company-specific, such as DUNS number, or could simply be an agreed-upon identification string. The AS2-From / AS2-To combination is case-sensitive and must be unique across all hosts defined in your system, since this combination is used to determine into which Inbox messages are stored when received from remote hosts.
- Subject - identifies the message and is returned in the human-readable section of an MDN, if requested.
-
Content-Type - specifies the format of the message being sent and is used by the sending and receiving applications to properly assemble and parse the message. Currently supported content types (in the pull-down menu) are:
- EDIFACT
- X12
- XML
- Binary
- Plain Text
- EDI Consent
Note: Entering a value for the Content-Type header is optional. If Content-Type is not specified or if multiple payloads are attached in the message, the Content-Type is detected based first on file content and then the file extension. Detectable types include application/edifact, application/edi-x12, application/edi-tradacoms, application/xml (text/xml),application/pdf, application/msword, application/x-msexcel, application/rtf, application/zip, image/bmp, image/gif, image/tiff, image/jpeg, text/plain, text/html, and video/mpg.
These header fields are filled in at the Mailbox or Action level and specify values to be set in the HTTP headers that precede the body (actual content) of the message to be sent.
AS2 Host: Advanced Tab
The host's Advanced tab contains several property settings fields. These settings typically do not affect your ability to connect to a host. However, you might want to change some of these settings when configuring a runtime environment.
See Setting advanced host properties for information about how to use and set the properties supported in all protocols. Properties available for AS2 include:
- Add Mailbox Alias Directory to Inbox
- Appends a subdirectory at the end of the host's configured inbox directory. This allows files received through different mailboxes to be kept separate.
- Add Mailbox Alias Directory to Outbox
- Appends a subdirectory at the end of the host's configured outbox directory. This allows files to be sent through different mailboxes to be kept separate.
- Add Mailbox Alias Directory to Receivedbox
- Appends a subdirectory at the end of the host's configured receivedbox directory. This allows files that have been sent through different mailboxes to be kept separate.
- Add Mailbox Alias Directory to Sentbox
- Appends a subdirectory at the end of the host's configured sentbox directory. This allows files that have been sent through different mailboxes to be kept separate.
- Allow Actions To Run Concurrently
- Normally, actions and host actions within the same host are allowed to run concurrently. You can use this property to not allow actions and host actions to run concurrently.
Note: This is a Cleo Harmony and Cleo VLTrader option.
- Allow Duplicate Incoming Message IDs
- Ignores messages with duplicate message IDs and allows reprocessing of the message.
- Async MDN Preferred Port
- When non-zero, defines the preferred port on which asynchronous MDNs will be returned from the trading partner.
Note: This setting will always override any port settings defined on the Listener and AS2 Service panels; and VLProxy’s reverse-proxy port, if applicable.
- Async MDN Resends
-
When sending a payload that has requested an asynchronous MDN, specifies the maximum number of attempts that will be made to resend the payload after the specified “Async MDN Timeout” has been exceeded and the MDN has still not been received.
When returning an asynchronous MDN in response to a received payload, specifies the maximum number of attempts that will be made to resend the asynchronous MDN to the trading partner (e.g., when the outbound connection cannot be established).
- Async MDN Retry Delay
- When resending an asynchronous MDN because the initial attempt to send it has failed, specifies the number of seconds to wait in between those resend attempts.
- Async MDN Timeout
- The maximum time (in minutes) to wait for an asynchronous MDN to be received before either resending the payload (if Async MDN Resends > 0 in either the Host or Listener) or logging an error.
- Base64 Encode Content
- Base64 is the encoding format used by Multi-purpose Internet Mail Extension (MIME) for transmitting non-text material over text-only communications channels. Base64 is based on a 64-character subset of US-ASCII, enabling 6 bits to be represented per printable character.
- Canonicalize Inbound Signed Content
- When this option is selected, a canonicalizer is used to ensure that ‘\r’ and ‘\n’ characters always occur together as ‘\r\n’. This option may be used when the inbound signature hash verification fails and the trading partner is using OpenSSL to sign its messages.
- Command Retries
- If an error or exception occurs during a command, the number of times the command should be retried.
Note: Command Retries does not apply to exceptions related to TCP/IP or ISDN dial-up connections. This is because dial-up connections are managed by the framework so that they can be shared across actions.
- Compression- Signing Order
- When both signing and compression are enabled, indicates which is applied first.
- Connection Timeout
- The amount of time allowed for each read operation.
- Delete Zero Length Files
- Indicates whether files received that are zero-length (<= 5 bytes) should be deleted rather than processed.
- Disable TE Headers
- When selected, disables the TE and Transfer Encoding request headers.
- Do Not Send Zero Length Files
- Indicates whether zero length files to be sent to the server should be ignored rather than processed. If the
-DELoption is being used, any zero length file ignored will also be deleted. - Email On Check Conditions Met
- Send an email notification after running a CHECK command where the overall conditions of the check are met. See Configuring email or execute based on results.
Note: This is a Cleo Harmony and Cleo VLTrader option.
- Email On Check Conditions Not Met
- Send an email notification after running a CHECK command where the overall conditions of the check are not met. See Configuring email or execute based on results.
Note: This is a Cleo Harmony and Cleo VLTrader option.
- Email On Fail
- If an error occurs during a command, email the error condition. See Email/Execute Based on Results.
- Email On Flag
- If a flagged event occurs, email the event. See Configuring email or execute based on results.
- Email On Repetitive Action Failures
- When "Email On Fail" is enabled and the same failure occurs each time an action is run for a specific host, leaving this option unchecked suppresses emailing of the same alert multiple times. If the same email alert continues to be suppressed after 24 hours, the suppressed email alert will be sent every 24 hours and after every system restart if the failure occurs again. When the failure is resolved an email alert will be sent.
Note: This feature only suppresses multiple emails if the same failure occurs multiple times in a row. Suppression is not maintained across synchronized hosts.
- Email On Repetitive Listener Failures
- When "Email On Fail" is enabled and the same failure occurs each time an inbound message is processed by the Listener for a specific host, leaving this option unchecked suppresses emailing of the same alert multiple times. If the same email alert continues to be suppressed after 24 hours, the suppressed email alert will be sent every 24 hours and after every system restart if the failure occurs again. If the failure can be associated with a specific host, an email alert will be sent when the failure is resolved. Failure resolution email alerts will not be sent for general Listener failures since it is not possible to determine that these types of failures have been resolved.
Note: This feature only suppresses multiple emails if the same failure occurs multiple times in a row. Suppression is not maintained across synchronized hosts.
- Email On Successful Copy
- Send an email notification after copying a file using LCOPY. See Configuring email or execute based on results.
- Email On Successful Receive
- Send an email notification after successfully receiving a file. See Configuring email or execute based on results.
- Email On Successful Send
- Send an email notification after successfully sending a file. See Configuring email or execute based on results.
- Execute On Check Conditions Met
- After executing a CHECK command where the overall conditions are met, run a system command. See Configuring email or execute based on results.
Note: This is a Cleo Harmony and Cleo VLTrader option.Note: Note that if multiple files contribute to the conditions being met, and one of the file macros is in the command (e.g., %file%), the system command will be executed repeatedly - once for each file.
- Execute On Check Conditions Not Met
- After executing a CHECK command where the overall conditions are not met, run a system command. See Configuring email or execute based on results.
Note: This is a Cleo Harmony and Cleo VLTrader option.
- Execute On Fail
- If an error occurs during a command, run a system command. See Configuring email or execute based on results.
- Execute On Repetitive Action Failures
-
When Execute On Fail is enabled and the same failure occurs each time an action is run for a specific host, leaving this option unchecked suppresses multiple executions of the Execute On Fail command. If suppression of execution of the command for this failure continues after 24 hours, the suppressed Execute On Fail command will be executed every 24 hours and after a system restart if the failure occurs again. When the failure is resolved, the Execute On Fail command will be executed again. Users must account for this by including the %status% macro variable for the Execute On Fail command (see Using macro variables) and then checking for a success or failure.
Note: This feature only suppresses multiple executions of the Execute On Fail command if the same failure occurs multiple times in a row. Suppression is not maintained across synchronized hosts. - Execute On Repetitive Listener Failures
-
When Execute On Fail is enabled and the same failure occurs each time an inbound message is processed by the Listener for a specific host, leaving this option unchecked suppresses multiple executions of the Execute On Fail command. If suppression of execution of the command for this failure continues after 24 hours, the suppressed Execute On Fail command will be executed every 24 hours and after every system restart if the failure occurs again. If the failure can be associated with a specific host, the Execute On Fail command will be executed again when the failure is resolved. Users must account for this by including the %status% macro variable for the Execute On Fail command (see Using macro variables) and then checking for a success or failure. Executions of the "Execute On Fail" command for resolution of general Listener failures will not be done since it is not possible to determine that these types of failures have been resolved.
Note: This feature only suppresses multiple executions of the Execute On Fail command if the same failure occurs multiple times in a row. Suppression is not maintained across synchronized hosts. - Execute On Successful Copy
- After successfully copying a file using LCOPY, run a system command. This command may be used for post-processing the file. See Configuring email or execute based on results.
- Execute On Successful Receive
- After successfully receiving a file, run a system command. This command may be used for post-processing the file. SeeConfiguring email or execute based on results.
- Execute On Successful Send
- After successfully sending a file, run a system command. This command may be used for post-processing the file. See Configuring email or execute based on results.
- Fixed Record EOL Characters
- End-of-line characters to be inserted and/or deleted.
- Fixed Record Incoming Delete EOL
- If Fixed Record EOL Characters has been specified and Fixed Record Length is greater than 0, indicates to look for and delete EOL characters while receiving a file.
Note: When using FTP ASCII mode, standard EOL characters may already be changing if transferring between Windows and Unix platforms.
- Fixed Record Incoming Insert EOL
- If Fixed Record EOL Characters has been specified and Fixed Record Length is greater than 0, indicates to insert EOL characters while receiving a file.
Fixed Record Incoming Delete EOL and Fixed Record Incoming Insert EOL are mutually exclusive properties.
- Fixed Record Length
- The fixed record length after which end-of-line characters need to be inserted and/or deleted.
- Fixed Record Outgoing Insert EOL
- If Fixed Record EOL Characters has been specified and Fixed Record Length is greater than 0, indicates to insert EOL characters while sending a file.
Note: When using FTP ASCII mode, standard EOL characters may already be changing if transferring between Windows and Unix platforms.
- High Priority
- Indicates whether incoming and/or outgoing transfers through the host should be treated as high priority. When both high priority and regular priority transfers are active, the high priority transfers get a larger portion of the available bandwidth. Go to to set the
High Priority Transfers Percentage Available Bandwidth(defaults to 75). See Other system options for more information. - Include Failure In Subject Of Email
- When specified, the exception message will be included in the email that is generated on failure.
Note: If the exception message exceeds 256 characters, it will be truncated.
- LCOPY Archive
- If specified, contains the directory for archiving LCOPY source files.
- Log Individual LCOPY Results To Transfer Logging
- When this option is enabled, a
<send>and<receive>result is logged to the transfer log for each file copied.Note: This is a Cleo Harmony and Cleo VLTrader option. - Macro Date Format
- Specifies the date format to be used when the
%date%macro is used. - Macro Time Format
- Specifies the time format to be used when the
%time%macro is used. - Maximum Incoming Transfer Rate (kbytes/s)
- Sets the maximum incoming transfer rate in Kbytes (1024 bytes) per second for each mailbox or host. The default value of
0does not limit the transfer rate. The Maximum Incoming Transfer Rate system setting might also limit the transfer rates. The system Maximum Incoming Transfer Rate value is used unless this setting is more restrictive. For simultaneous transfers, the number of active transfers also affects individual transfer rates. See Advanced system options. - Maximum Outgoing Transfer Rate (kbytes/s)
- Sets the maximum outgoing transfer rate in Kbytes (1024 bytes) per second for each mailbox or host. The default value of
0does not limit the transfer rate. The system setting might also limit the transfer rates. The system Maximum Outgoing Transfer Rate value is used unless this setting is more restrictive. For simultaneous transfers, the number of active transfers will also affect individual transfer rates. See Advanced system options for more information about Maximum Outgoing Transfer Rate. - Outbox Sort
- Controls the order in which multiple files are transferred for a PUT command. If
System Defaultis specified, the value set on the tab takes precedence. ForAlphabeticalordering, the file extensions are not used to determine the sorted order unless they are needed to make the filenames unique. - Outgoing Insert EOL Between Interchanges
- If
Fixed Record Outgoing Insert EOLis active, indicates to also insert EOL characters between EDI interchanges while sending the file. - Override Listener CEM Auto Accept Setting
-
When selected, overrides the
Auto Accept Received Certificate (CEM)Advanced setting in the Listener allowing auto accepting of CEM requests to be allowed or disallowed on a per host basis. See Exchanging certificates with your trading partner. - Partner Email Address
- The email address of the trading partner for this trading relationship. When set, this address is automatically used to send your local profile information and/or certificates to your trading partner. SeeEmailing a profile to your trading partner.
- PGP Compression Algorithm
- Compression method used when OpenPGP packaging (with compression) is requested through the Mailbox Packaging tab. See Configuring mailbox packaging. If
System Defaultis specified, the value set on the tab is in effect. - PGP Encryption Algorithm
- Encryption method used when OpenPGP packaging (with encryption) is requested through the Mailbox Packaging tab. See Configuring mailbox packaging. If
System Defaultis specified, the value set on the tab takes precedence. - PGP Hash Algorithm
- Signing method used when OpenPGP packaging (with signing) is requested through the Configuring mailbox packaging. If
System Defaultis specified, the value set on the tab takes precedence. - PGP Integrity Check
- When OpenPGP encrypting (see Configuring mailbox packaging), include an integrity check on encrypted data. Can be disabled for compatibility with certain OpenPGP implementation.
- PGP Signature Verification
- Indicates whether or not signed inbound PGP messages should verified when inbound OpenPGP packaging is requested through the Mailbox Packaging tab. See Configuring mailbox packaging. In general, this property should be enabled.
- PGP V3 Signature
- Put Multiple Files Limits
- Limits the number of files included in each generated multipart message when using the PUT -MUL option. The limit is only applied when sending out of a single directory; when sending multipart out of separate subdirectories, the files are kept as a group and not broken up into separate messages.
- Reset Connection After Timeout On Response
- When enabled will cause an immediate reset on the socket (instead of a graceful close) when a SocketTimeoutException occurs.
- REST Enabled
-
Allows the host to be accessible through the REST API. This feature is only supported on AS2, AS4, FTP and SSH FTP and only when the host has exactly one mailbox.
When this setting is enabled, new mailboxes cannot be created and the existing mailbox cannot be cloned, disabled, or removed.
- Resume Failed Transfers
- When selected and a transfer fails (and Command Retries > 0), attempt to resume the transfer on a retry. If OpenPGP is enabled on the packaging tab (see Configuring mailbox packaging), the entire file is transferred instead of resuming with a partial file. The server must support the
FEAT,SIZE, andREST STREAMextensions to FTP. For more information, visit http://tools.ietf.org/html/rfc3659. - Retain Temporary Inbound Message Files
-
Leaves any files that are used while processing inbound messages in the temp\ folder. The default action is to delete these files after processing has completed. These files may be helpful for problem diagnosis.
Note: These temporary files are retained for seven days. - Retry Delay
- The amount of time (in seconds) before a retry should be attempted.
- RSA-OAEP Key Algorithm Parameter
-
Represents the type of mask generation and hash generation functions that are applied when the RSAES-OAEP key algorithm is in use. See RFC4055 for a further description of the mask and hash generation functions.
- SSL Allow Legacy Renegotiation
- When selected, legacy renegotiation is allowed. If this property is not selected, the extension described in RFC5746 is used for renegotiation and the server must also support this extension. See RFC5746 for a description of the extension and the vulnerability it addresses.
- SSL Cipher
- Indicates a specific cipher to be used with the server for SSL key exchange, encryption, and hashing. If not set, the list of supported ciphers is presented to the server and the server picks one.
- SSL Maximum Protocol Version
- Specifies the maximum protocol version allowed. By default, this field is blank, designating that Cleo Harmony, Cleo VLTrader, or Cleo LexiCom will select the most recent version (currently TLS 1.2).
- SSL Minimum Encryption Key Size
- Specifies the minimum encryption key size allowed when selecting an SSL cipher. To prevent use of low- or medium-strength ciphers, change from the default value of
0to112,128, or256(depending on the requirement). Note that if this value is set too high, all ciphers are filtered out causing theNo suitable cipher suites are enabledexception to occur. - SSL Minimum Protocol Version
- Specifies the minimum protocol version allowed. SSL 3.0 is the default value for compatibility with servers that do not support the more recent TLS versions 1.0, 1.1, and 1.2.
- SSL Use Record Splitting
- Indicates whether to use 1/n-1 record splitting in CBC mode as a countermeasure against the Rizzo/Duong BEAST (Browser Exploit Against SSL/TLS) attack against the SSL 3.0 / TLS 1.0 protocol. Must be turned off if the SSL library on the other side of the connection does not support the feature.
- Store Raw Sent Message
- When this property is enabled, a copy of the outbound message is stored in the HTTP/sent directory.
- Terminate On Fail
- If an error occurs during a command, stop the action.
Note:
Regarding non-CHECK commands: When
Terminate On Failis on, if a command fails,Email On FailandExecute On Fail, if set, are processed, and then the action stops. WhenTerminate On Failis off, if a command fails,Email On FailandExecute On Fail, if set, are processed, and the action continues.Regarding CHECK commands:
Terminate On Failis only honored if theConditionsMetparameter is set and the result of the CHECK is classified asError. The CHECK command is only available in the Cleo Harmony and Cleo VLTrader applications. - Unzip Use Path
- Indicates whether or not zip entry paths should be used for LCOPY -UNZIP operations. When enabled, the entry's path is added to the destination path, unless the entry contains an absolute path. In this case, the absolute path is used in place of the destination path.
- Use Content Type For File Extension
- By default, inbound messages that do not specifically contain the name of the target file to be saved are stored using the value of the
Message-ID(of that message) with the .file extension. When this option is selected, inbound messages without a target file name specifier is stored using theMessage-IDand the appropriate file extension based on the Content-Type of the message. - Use Folded Headers For Outbound Messages
- Enables or disables automatic line wrapping of HTTP headers exceeding 76 characters. By default headers are not folded since some non-Cleo product remote hosts using Microsoft Internet Information Server (IIS) cannot handle folded headers properly. Unless your host has been pre-configured to enable folded headers, leave this setting cleared!
- Wait For Execute On
- Indicates whether execution should wait for processing to complete within an Execute On Fail, Execute On Successful Copy,Execute On Successful Receive, or Execute On Successful Send command. Note that this option does not apply to native AS400 execution.
- XML Encryption Algorithm
- The method used to encrypt/decrypt files when XML Encryption packaging is requested through the Mailbox Packaging tab. See Configuring mailbox packaging . If
System Defaultis specified, the value set on the tab takes precedence. - Zip Comment
- Specifies the comment to be added to the zip archive file in LCOPY -ZIP operations.
- Zip Compression Level
- Controls the level of compression for LCOPY -ZIP operations. If
System Defaultis specified, the value set on the takes precedence - Zip Subdirectories Into Individual Zip Files
- Indicates whether or not subdirectories should be bundled for LCOPY –ZIP –REC operations. When enabled, each first-level subdirectory (and all of its descendents) will be bundled together into an individual zip file. The name of this zip file may optionally reflect the subdirectory name if an asterisk (
*) is placed in the destination path. Any files that are directly off the source root directory will not be copied.
AS2 Mailbox Configuration
A mailbox's parameters allow you access to the remote host and define the security of the file being sent. You can use the AS2 mailbox wizard to configure for the most common setup. See Using the wizard to create a host or mailbox. The following sections describe the mailbox parameters.
AS2 Mailbox: AS2 Tab
The mailbox's AS2 tab allows you to select the desired encryption and signing for sending messages and the optional desired security for receiving messages. If an MDN receipt is desired, you can also select the format and delivery method of that receipt.
- Request
- Specify the S/MIME format for messages to send to the remote host.
- Unsigned / unencrypted (neither Encrypted nor Signed selected)
- Signed (only Signed selected)
- Encrypted (only Encrypted selected)
- Signed / Encrypted (both Signed and Encrypted selected)
- Receipt
- Enables the MDN Receipt section. See MDN Receipt.
- Encryption Algorithm
- When Encrypted is selected, the Encryption Algorithm field is enabled and allows you to choose the encryption algorithm for the message to be sent to the remote host. The remote host must be able to decrypt the message using the algorithm you choose. For a non-VersaLex trading partner, it is important to verify that your trading partner can use the selected algorithm prior to sending an encrypted message. The default encryption algorithm is TripleDES. See Cryptographic Services for more information on choosing an encryption algorithm.
- Key Algorithm
- When Encrypted is selected, the Key Algorithm field is enabled and allows you to choose the algorithm to encrypt the content encryption key with the public key of your trading partner’s encryption certificate. Your trading partner uses the private key of their encryption certificate to decrypt the content encryption key that is subsequently used to decrypt the content of the message.
- Signature Algorithm
- When Signed is selected, the Signature Algorithm is used to encrypt the hash value of the signature with the private key of your signing certificate. Your trading partner uses the public key of your signing certificate to decrypt the hash value of the signature that authenticates you as the sender of the message. When RSA is selected, the selected Hash/MIC Algorithm is used to determine the appropriate signature algorithm, for example, rsaEncryption, sha256WithRSAEncryption, sha384WithRSAEncryption orsha512WithRSAEncryption. If RSASSA-PSS is selected, the combination of the private key of your signing certificate and the hash algorithm is used in conjunction with the RSASSA-PSS algorithm to secure the signature.
- Hash/MIC Algorithm
- When the Signed option in the Request section is selected, the combination of the signature algorithm and the selected hash algorithm is used to secure the signature.
Note: If the RSASSA-PSS signature algorithm is used and the SHA-512 hash algorithm is selected, the strength of the signature algorithm of your signing certificate must be SHA256withRSA or better.When the Signed option in the MDN Receipt section is selected, the selected Hash/MIC Algorithm is used to compute the independent Message Integrity Check (MIC) that is returned in the MDN Receipt.
- Compress Content
- Compresses the message using ZLIB compression. Compression is generally used for large files so that the message will conserve bandwidth and be transferred more efficiently and securely over the Internet.
- Inbound Message Security
- Indicates how inbound messages should be received.
- MDN Receipt
- Attributes of the Message Disposition Notification (MDN) receipt you requested.
AS2 Mailbox: Certificates Tab
Use this tab to associate a trading partner's signing and encryption certificates with this mailbox and to override your own Local Listener's signing and encryption certificates, if necessary.
Acquire your trading partner's signing/encryption certificates and provide your trading partner with your signing/encryption certificates. See Acquiring your trading partner's signing and encryption certificates and Creating and providing your signing/encryption certificates.
- Trading Partner's Certificates
-
- Encryption Certificate
- The name of the file containing your Trading Partner's encryption certificate. Specify a value or click Browse to navigate to the file you want to select.
- Signing Certificate
- Select the check box to enable the field.
- Use encryption certificate
- Indicates that your trading partner uses the same certificate for signing and encryption, which is the general practice among most trading partners. When you select this check box, the Signing Certificate field is populated with the same certificate you selected in the Encryption Certificate field.
If the remote host is capable of receiving Certificate Exchange Messages (CEM) or you want to email your certificates to your trading partner, you can send your user and SSL certificates to the remote host by clicking Exchange Certificates.
- My Certificates
-
- Override Local Listener Certificates
- Enables fields where you specify signing and encryption certificates to use with this particular partner instead of the certificates you configured for the Local Listener. See Configuring certificates for Local Listener.
- Signing Certificate Alias
- The name of the signing certificate registered with the VersaLex application through the Certificate Manager. The certificate must be the same as the one exchanged with your remote trading partners, unless you want to override it at the Mailbox level. See Local HTTP Users Configuration.
- Encryption Certificate Alias
- The certificate for decrypting your trading partner’s messages, if you have created or obtained a separate certificate.
- Use signing certificate
- Select this check box to use the same certificate for signing and decrypting your trading partner's messages. The Encryption Certificate Alias and Password are populated to match the Signing Certificate Alias and disabled.
- Exchange Certificates
- Invokes the Certificate Exchange dialog box. If you override the default the certificates, you must exchange these alternate certificates with your trading partner.
AS2 Mailbox: HTTP Tab
Use the mailbox's HTTP tab to assign default values to message headers.
For example, your AS2 name (AS2-From) and your trading partner's AS2 name (AS2-To) as well as the Subject and Content-Type of the documents to be transferred.
- Default Value
- You can assign a default value for each of the headers defined on the AS2 Host: HTTP tab. (See AS2 Host: HTTP Tab.) Unless an overriding value is specified within the command in an action, these default values are used. (See AS2 Checklist: item 5 for the AS2-From value, item 6 for the AS2-To value, and item 14 for the default Content-Type value.)
AS2 Mailbox: Authenticate Tab
If the target server requires WWW authentication, select the appropriate type and provide values for Username and Password and, optionally, Realm.
AS2 Mailbox: Security Tab
If you specified HTTP/s in the host's HTTP tab, a remote host might issue client certificates. In this case, import the client certificate using the Certificate Manager and then use the AS2 Mailbox Security tab to specify (or browse for) the imported Client Certificate's alias and password. See Certificate management.
AS2 Mailbox: Packaging Tab
See Configuring mailbox packaging for information regarding packaging of payload files.
AS2 Trading Partner
A trading partner's parameters define a unique identifier on the host system. By default, the Trading Partner branch is not created since it is not needed for AS2 transactions.
AS2 Action
An action's parameters define a repeatable transaction for your mailbox defined for the host system.
AS2 Action: Action Tab
See Composing an action and HTTP Command Reference. See AS2 Host: Advanced Tab for information about the available property values.
Sending Multiple Files within the Same Payload
By default, AS2 messages contain a single file within the payload (i.e., the message being sent). However, some supply chains require that multiple files that are related to each other (perhaps with different content types) be sent together within the same message.
To send multiple files within the same payload:
- Select Multiple file payload from the Command Wizard or include the
-MULoption on the PUT command line. - Group the related files to be sent either in your designated outbox or within a subdirectory under your designated outbox. Files that you do not want to be sent should not be stored in this subdirectory.
- Optionally, enter the Destination file names. This field can include any of the supported macros allowing for the outgoing files to be named, for example, with a date-time stamp. See Using macro variables (Destination File context) section for information about applicable macros.
- Run the action.
Inbound messages containing multiple files within the same payload are stored together in a subdirectory under the designated inbox.
The directory is named in the form:
YYYYMMDD-HHMMSS-CCCwhere:
YYYY current year MM current number of the month (01-12) DD current day of the month HH current hour MM current minute SS current second CCC current fraction of a second
Testing Your AS2 Installation
Before you attempt to have a trading relationship with a partner, you should successfully test and validate that you can and receive messages at your local installation. This helps you narrow down connectivity issues caused by firewall problems and not by improper installation and configuration.
- The AS2-To and AS2-From must have the same values in order for the file being sent to be properly stored in your configured Inbox. (Refer to the Loop Test General tab for current Inbox settings.)
- Verify that the encryption certificate defined on the Local Listener panel (Encryption Certificate Alias) matches the one defined in the Trading Partner's Encryption Certificate field on the Loop Test Certificates tab.
- Verify that your Local Listener is running.
- If you've chosen asynchronous SMTP delivery or Forward MDN to Email, verify you have provided a valid email address in theEmail Address field on the mailbox AS2 tab.
- Click the green arrow on the toolbar in the Action tab to run the test command. Messages similar to the ones shown below appear in the messages pane in the lower portion of your VersaLex application.
This transaction log describes the following events that occurred when the command was executed:
- The command PUT test.edi was invoked
- The file (test.edi) was sent to from the outbox\ directory under the VersaLex directory tree
- The file was assembled into a message that was both signed and encrypted using the TripleDES encryption method
- The AS2-From and AS2-To headers were both set to LOOPTEST
- The received message was identical to the message that was sent (signified by matching MIC codes)
- An MDN was received and was stored in the mdn\ subdirectory under the VersaLex directory tree
AS2-Specific Directories
The following additional directories are created either during the AS2 installation or as needed by the application:
| Directory | Purpose |
|---|---|
|
lostandfound\ |
Default inbox where incoming payload will be deposited when the application can't determine where to put it. |
|
AS2\ |
Location where raw (unprocessed) incoming and outgoing messages are stored. Incoming messages are located in the AS2\received directory and outgoing messages are located in the AS2\sent directory. These files can be helpful in diagnosing problems. Old files should be deleted or archived by the user, if necessary. The AS2\unsent directory contains raw header, data and message setup information files. These files are used if a message needs to be retransmitted and are deleted automatically by the application once the message transfer has either completed successfully or has failed due to timeouts, exceptions, or the number of retries has been exhausted. The AS2\mdn directory contains subdirectories for received (and optionally sent) MDNs. This directory may be changed on the AS2 Service Panel. MDNs may be automatically archived by the application or manually archived by the user from the MDNstab on the listener panel. Archived MDNs are stored inAS2\mdn\received\archive\mdn.zip or AS2\mdn\sent\archive\mdn.zip. The AS2\data directory contains AS2msgs.txt and AS2files.txt files used by the application to determine the receipt of duplicate messages and duplicate file names. Entries in these files are retained for the time intervals configured on the AS2 Service page. See Local Listener AS2 Service. When a message is received from a trading partner who has enabled the AS2 Restartfeature (i.e., the inbound message contains a valid Etag header), the AS2\restart directory will contain a header file named with the Etag value and a .as2restart extension and the partially received message file (named with Etag value and a _rcv extension). These files can be used to resume a transfer from the previous point of failure. When the entire message has been successfully received these files are removed; otherwise they will be retained for 24 hours after the last failure. |
|
temp\ |
Temporary location where incoming messages can be stored while they are being processed by the application. By default, they are deleted automatically once the message has been completely processed; however these files can be kept for problem diagnosis by using theRetain Temporary Inbound Message Files host-level Advanced property. (These temporary files will automatically be deleted after 7 days.) |
AS2 Firewall Considerations
If your server is behind a firewall and/or your trading partner's server is behind a firewall, it will be necessary to configure the firewalls to allow VersaLex to properly exchange messages with your remote trading partner. Depending on the type of firewall set up, the following settings in your firewall should be modified:
- Incoming and outgoing messages should be allowed from and to your remote trading partner's IP addresses or qualified host name.
- The port for your trading partner's remote server should be opened for outgoing messages.
- The port(s) that you configured for your Local Listener should be opened to allow incoming messages.
AS2 Troubleshooting
|
Problem |
Possible Cause |
Possible Solution |
|---|---|---|
|
Could not listen on port XXXX - Address in use: JVM_BIND (Generated when an attempt is made to start the Local Listener.) |
Port XXXX defined on the listener's HTTP panel is already being used by another application. |
Use the "netstat -an" command (if available) to verify that the port is in use. Stop the listener, if it is running. Define a different port on the HTTP panel and restart the listener. |
|
Result: Error - Method GET is not implemented by this server (Generated by the Local Listener receiving incoming messages) |
A remote user is attempting to access your Local Listener using a web browser by entering your URL in the form: http://your-host-address:your-port/your-resource-path/ The VersaLex Listener is only capable of processing HTTP POST requests, but messages from web browsers are sent as HTTP GET requests. |
If the message is coming from a bona fide trading partner, ask them to send you messages using POST requests instead of GET requests. If the message is from an unknown/unwanted source, modify your firewall settings to reject messages from the incoming IP address or change the setting for the Unknown Partner Message Action in the Local Listener's Advanced tab to either Ignore or Reject. |
|
Result: Connection refused: connect |
Remote server is currently not running or is not listening on the specified port. |
Contact your trading partner regarding the availability of the server and verify the configured host and port settings are correct. |
|
Result: Operation timed out: connect |
Remote server is running but is not able to receive messages from you. |
Verify firewall settings on the sending and receiving ends are properly configured. |
|
Result: Timeout waiting for response |
The action is unable to fully complete (i.e., complete transfer to remote host, decryption and/or signature verification) within the specified ConnectionTimeout period. |
Increase the default ConnectionTimeout value on theHost/Advanced panel or increase the ConnectionTimeout value for the individual Action. |
|
Result: Warning - Undefined AS2-To/AS2-From Relationship (Generated by the Local Listener receiving incoming messages) |
The incoming AS2-To and AS2-Fromheader values do not match exactly with local AS2-From and AS2-To settings or the settings have not yet been defined.
Note: Your AS2-To value should be your trading partner's AS2-From value and your AS2-From value should be your trading partner's AS2-To value.
|
Verify that there is an entry for the designated AS2-From / AS2-To setting. Verify your AS2-To header value matches your trading partner's AS2-From header value and vice versa. These values are case-sensitive and there must be only one instance of the pair defined in your installation. |
|
Result: Warning - MDN processing warnings occurred at the remote host. See MDN for further details. (Generated when sending a message to the remote host.) |
A warning occurred at the remote host. The message was still correctly processed. Commonly reported warnings are Undefined AS2-To / AS2-From Relationship and Duplicate file received. |
View the associated MDN to diagnose the cause of the warning and perform any corrective action as necessary. |
|
Result: Error - MDN processing errors occurred at the remote host: authentication failed - see MDN for further details (Generated when sending a message to the remote host.) |
The remote host was unable to verify the signature of your signed message. |
Verify that you have successfully sent your signing certificate to your trading partner and that it was properly installed at the remote host. |
|
Result: Exception - Certificate chain not trusted! (Generated when receiving a message from a remote host.) |
Some of the certificates listed in the signature of the received message are missing in VersaLex's store of trusted certificates. |
Verify that all CA certificates used by your trading partner's signing certificate have been received and installed in VersaLex. |
|
Result: Exception - The signature could not be verified! (Generated when receiving a message from a remote host.) |
The Local Listener was unable to verify the signature of a remote host's signed message. |
Verify that you have successfully received and installed your trading partner's signing certificate. |
|
Result: Exception - The trading partner's encryption certificate could not be found! (Generated when attempting to send an encrypted message to a remote host.) |
VersaLex was unable to find the Trading Partner's Encryption Certificate defined on the Mailbox’s Certificate Panel. |
Verify the file defined on the Mailbox’s Certificate panel exists and has not been accidentally deleted. Click Browseto choose a new encryption certificate. |
|
Result: Error - MDN processing errors occurred at the remote host: decryption failed - see MDN for further details (Generated when sending a message to the remote host.) |
The remote host was unable to decrypt your encrypted message. |
Verify that you have successfully installed your trading partner's encryption certificate and have properly selected that certificate on the Mailbox’s Certificate panel. Verify the remote host is able to decrypt messages according to the Encryption Method specified on the Mailbox’s AS2panel. |
|
Result: Exception - The message could not be decrypted! (Generated when receiving a message from a remote host.) |
The Local Listener was unable to decrypt a remote host's encrypted message. |
Verify that you have successfully received and installed your trading partner's encryption certificate. |
|
WARNING: Source file is zero-length. (Generated when sending a message to the remote host.) |
An attempt was made to send a file with no content. The file will still be sent, but there may be unexpected results on the receiving end. |
Verify that the intent is to send files of zero-length and ignore any error messages generated due to this condition. |
Comments
0 comments
Please sign in to leave a comment.