Invocation

Invoke the FMS light client utility as follows to display usage requirements

\
\java -jar fms-client.jar -?
\
\Usage: java -jar fms-client.jar
\Where:
\  -a "<attachment File path>:<attachment mime type>:<attachment description>:<attachmentID>" \
\  can appear 0..n times. 
\  -b <Buffer Size> The send buffer size in bytes to use. Defaults to: 32768
\  -c <P-Mode ID> The Processing Mode ID to use as a configuration for this request.
\  -d <recipientPartnerIdentifier> The Partner Identifier of the recipient. Defaults to: null
\  -e <Event> The Processing Mode event that this message should use. Defaults to the first Event \
\    in the specified P-Mode
\  -f <XML File path> The file path to the XML file that should be sent. Required...
\  -g Enable GZIP Stream Compression for faster upload over slow connections
\  -h <Host Name> The final destination of the packaged envelope. Only for Test environments, \
\    actual destination in Production environments is defined in the server configuration files.
\  -i <Initial Timeout> A timeout in milliseconds that dictates the timeout required before an ACK \
\    is received during transmission from the local FMS server, refer to -t <ReceiptTimeout> for the \
\    timeout while waiting for a response from the remote server. Defaults to: 10000
\  -k <Keystore Location> The location of the keystore that contains the SSL certificates used \
\    during SSL communication. Defaults to: /etc/ssl/certs/java/cacerts (ubuntu, debian) or /etc/pki/java/cacerts (redhat, fedora, centos). \
\    Not currently used - pending SSL client authentication.
\  -l <recipientLocation> The case sensitive recipient location ID. Defaults to: null
\  -m <contentID> A content instance tracking identification string. 
\  -q <messageID> Perform an Acknowledgement query on the provided messageID
\  -p <MPC> The Message Partition Channel for use with this PullRequest
\  -r <Retry Attempts> The amount of retries that should be attempted before giving up. \
\    Defaults to: 3
\  -s <Schema Type> The Schema Type to be used for this transaction. As defined in the \
\    Collaboration Protocol Agreement (CPA) (If Applicable). (Case Sensitive). Defaults to: null
\  -t <Receipt Timeout> A timeout in milliseconds that should trigger if a Receipt is not \
\    received from the FMS server for both server and client, refer to -i <Initial Timeout> for \
\    upload timeouts. Not required if -w is specified. Defaults to: 300000
\  -v Print version and exit.
\  -w Do not wait for a Receipt Acknowledgement before exiting, should be specified with -J in case \
\    a followup acknowledgement check (-Q) needs to be performed.
\  -A <Action Type> The Action Type to be used for this transaction. As defined in the \
\    Collaboration Protocol Agreement (CPA) (If Applicable). (Case Sensitive). Defaults to: null
\  -C <CPA UID | CPA URL> The Unique ID for the CPA to use for this transaction or directly to \
\    the CPA. Defaults to: null
\  -D <senderPartnerIdentifier> The Partner Identifier of the sender. Defaults to: null
\  -E <ExternalProperties> A comma-delimited Variable=Value list which will be inserted into the \
\    transport envelope (if applicable). e.g: -E "MessageIdentifier=ABC123, \
\    ContentFilename=InvoiceABC123.xml"
\  -H <serverHostName> The server that this client should connect to. Defaults to: localhost
\  -I  Ignore the Message ID store '.FMS-ClientMessageID.tmp' when sending requests.
\  -J  Append to the unacknowledged Message ID(s) stored in the '.FMS-ClientMessageID.tmp' file if \
\    it exists.
\  -L <senderLocation> The case sensitive sender location ID. Defaults to: null
\  -M <refToMessageID> The reference to message identifier that this message is in response to \
\    (If Applicable).
\  -O <logLevel> The log level to use when sending requests. One of {OFF, SEVERE, WARNING, \
\    INFO, CONFIG, FINE, FINER, FINEST, ALL} (Case InSensitive). Defaults to: OFF
\  -Q Perform an Acknowledgement query on the messageID(s) stored in the file \
\    '.FMS-ClientMessageID.tmp'. Only available if the configuration database is enabled.
\  -P <serverPort> The port number that this client should connect to. Defaults to: 29350
\  -R <Retry wait time> The time, in milliseconds, between retry attempts. Defaults to: 1000
\  -S  Turn off SecureSocketLayer (SSL) during upload. Not recommended.
\  -T <Connection Type> The connection type to use. \
\     One of {<acronym>RosettaNet</acronym>, <acronym>ebXML</acronym>} \
\     (Case Sensitive). Defaults to: ebXML.
\
\Got: [-?]
\
\          

Interpreting Light Client Results

Once execution has completed, the Client Utility will return an exit code. These codes are documented in the the Section called ebXML and RosettaNet Client Return Values. Further messages are available in stdout and stderr.

All log messages from the Client Utility are written to stderr. These messages include errors from the Server as well as any transmission or validation errors.

If transmission of the envelope is successful and a message from the Remote Server has been received it will appear in stdout. This message is in XML format and could be a SOAP Message (ebXML) or one of Exception or ReceiptAcknowledgment (RosettaNet).

The layout of a RosettaNet Exception XML object:

\
\1   1       Exception
\2   1              |-- ExceptionDescription
\3   1              |       |-- errorClassification.GlobalMessageExceptionCode
\4   1              |       |-- errorDescription.FreeFormText
\5   0..1           |       |-- offendingMessageComponent.GlobalMessageComponentCode
\6   1              |-- GlobalExceptionTypeCode
\
\            

Where:

• GlobalMessageExceptionCode - Identifies the specific error which occurred during message processing.

• FreeFormText - Unformatted text.

• GlobalMessageComponentCode - Identifies a message component, e.g. Preamble, Delivery Header, Service Header.

• GlobalExceptionTypeCode - A unique identifier specifying the type of exception encountered during message processing, see the Section called RosettaNet^TM Error Messages

The layout of a RosettaNet ReceiptAcknowledgment XML object:

\
\1       1       ReceiptAcknowledgment
\2       0..1        |-- NonRepudiationInformation
\3       1           |       |-- OriginalMessageDigest
\
\            

• OriginalMessageDigest - The base-64 encoded digest of the entire original mime message received. The digest MUST use the same algorithm as the original signed message.

ebXML/RosettaNet Client SSL Configuration

fms-client.jar may be used to communicate messages using no encryption to the server or using a secure connection to the server.

Before a secure connection can be made to the server, SSL MUST be configured. Below are a number of steps to follow in order to ensure a secure connection between the client and server:

1. An export of the server certificate must be done in order to import the certificate on the client side. See the Section called Exporting a Public Key (Certificate) in the Chapter called Installation

2. Import the server certificate to the default java keystore on the client side. See the Section called Importing Public Keys (Certificates) into the Client Keystore in the Chapter called Installation

Attachments

To include an attachment with an XML document include the argument -a <attachment file path>:<attachment mime type>:<attachment description> for each attachment at the end of the invocation statement.

AS4 Client Return Values

fmsclient.as4.jar returns the following values on completion

• 0 - Ok

• 1 - Usage - eg when invoking with incorrect command line arguments

• 2 - Connect Exception - occurs if a network connection is not available. Eg. network cable unplugged

• 3 - SSL Exception - could not validate key - only from 5.3.4-2

  If this return value is accompanied with ClientException - PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target then this may be due to the SSL certificate verification failing either because the root certificate does not exist or has been revoked.

• 4 - Timeout - occurs on read timeout and on establishing a connection timeout

• 5 - not currently used

• 6 - NPE - internal null pointer error

• 7 - not currently used

• 8 - not currently used

• 9 - not currently used

• 10 - Unknown error - unidentifiable error condition. Use '-d' command line switch to debug.

ebXML and RosettaNet Client Return Values

fms-client.jar returns the following values on completion

• 0 - No transmission error.

• 1 - Timeout - Socket timeout occurred, either on client or remote servers.

• 2 - IO Exception - This ranges from failure to connect to errors in the underlying protocol.

• 3 - SSL Exception - An error occurred while configuring or negotiating a SSL connection.

• 4 - XML Parse Exception - An error occurred while attempting to parse and validate the transmitted XML headers and content.

• 5 - Version Error - There is a difference between this client's version and the server's. Read stderr for location to download a new client.

• 6 - File not Found Error - The supplied files could not be located, refer to stderr as to the location of the failed files.

• 7 - Security Error - There was a failure in encryption or digital signatures, refer to server logs for more information.

• 8 - CPA Error - The supplied CPA URL/UID was unretrievable or unreadable, refer to server logs for more information.

• 9 - Acknowledgement Query - The result of the Acknowledgement Query

• 10 - Protocol Exception - There was an error in the underlying protocol, refer to server logs for more information.

• 11 - Sent Unacknowledged - The request has been transmitted to the server but the client will not wait for an acknowledgement.

• 12 - Partner Identifier Exception - There was a misconfiguration or error while using the supplied Partner Identifier.

• 13 - Empty Message Partition Channel - There were no messages avilable or the MPC was not found while performing a PullRequest.

• 14 - ProcessingMode Error - The server encountered a misconfiguration or the supplied data does not correlate with the supplied ProcessingMode

• 15 - HTTP Status code not accepted - The server received an error HTTP status code from the remote server.

• 16 - Unknown Error - The server or the client encounted an unknown error, read stderr for error information.

ebXML Error Messages

Even though a return code of 0 was received, an Error might have occurred on the remote servers. If an exception occurred then fms-client.jar can return the following ebXML messages in the Error XML element of the SOAP message which is printed to stdout after invocation.

If no error occurred then the SOAP Message returned to stdout should contain the SignalMessage Receipt element.

RosettaNet^TM Error Messages

Even though a return code of 0 was received, an Exception might have occurred on the remote servers. If an exception occurred then fms-client.jar returns the following RosettaNet^TM messages in the Exception XML object body which is printed to stdout during execution.

If no exception occurred then the XML object returned to stdout should be ReceiptAcknowledgment.

• PKG.MESG.GENERR Error during packaging. General error

• PRF.ACTN.GENERR Error during action performance. General Error

• PRF.DICT.VALERR Error during action performance. Validating the Service Content against a PIP^TM specified dictionary

• UNP.MESG.GENERR Error during unpackaging. General error

• UNP.MESG.SIGNERR Error during unpackaging. Verifying the signature of the RosettaNet^TM Business Message

• UNP.PRMB.READERR Error during unpackaging. Reading the Preamble

• UNP.PRMB.VALERR Error during unpackaging. Validating the Preamble

• UNP.DHDR.READERR Error during unpackaging. Reading the Delivery Header

• UNP.DHDR.VALERR Error during unpackaging. Validating the Delivery Header

• UNP.SHDR.READERR Error during unpackaging. Reading the Service Header

• UNP.SHDR.VALERR Error during unpackaging. Validating the Service Header

• UNP.SHDR.MNFSTERR Error during unpackaging. Verifying Manifest against the actual attachment body parts

• UNP.MESG.SEQERR Error during unpackaging. Validating the message sequence

• UNP.MESG.RESPTYPERR Unexpected Response type in the HTTP header

• UNP.MESG.DCRYPTERR Error Decrypting the message

• UNP.SCON.READERR Error during unpackaging. Reading the Service Content

• UNP.SCON.VALERR Error during unpackaging. Validating the Service Content

Configuring Pull Requests

Since ebMS version 3 and FMS version 4.1.2.4 it has been possible to generate and receive Pull Requests. Pull Requests are messages that are queued on a remote server waiting to be pulled by a remote MSH. This is especially useful in a situation where a business application is installed on a system that does not have a permanent internet connection permitting remote pull requests to originate private networks behind firewalls, from dynamic IP addresses or a dialup internet connections.

In order to deliver messages to a queue for Pulling the following MUST be performed:

• The destination Partner Identifier type MUST be set to PULL_PARTNER.

• The destination Partner Identifier endpoint must be set to the value of the client Message Partition Channel MPC.

In order to retrieve a message destined for a Partner Identifier MPC the following MUST be performed:

• The MPC value must be known in order to collect messages

• The invocation client must have the Recipient Partner Identifier (-d) as well as the pull request argument (-p <MPC value>) as arguments.

Note (2): Messages will be saved to the delivered-content directory of the local server for collection by the Business Application.

Message Queries

When sending asynchronous messages the FMS client need not wait for an acknowledgement from the remote server. However should an acknowledgement be required or at least message delivery verified then it is possible to use the FMS client to query the acknowledgement status of any message identifier(s) at a later stage.

The FMS Client has the capability of storing a list of Message Identifiers that have been sent, acknowledged or not. By specifying the -J argument during FMS Client invocation the Client will append Message Identifiers in the file .FMS-ClientMessageID.tmp for later querying/tracking purposes, otherwise only the most recent Message Identifier is stored. This functionality may be disabled by specifying the -I argument which sets the Client to ignore the Message Identifier storage file.

There exist two methods to query Message Identifier(s) by using the Client:

• If the Message Identifier storage file is used and populated then the FMS Client may be invoked using -Q which will then transfer the Message Identifier storage file to the server and perform an Acknowledgement Query on the Message Identifiers.

• However should just a single Message Identifier require an Acknowledgement Query then it is possible to use the -q <Message ID> argument to query just a single Message Identifier.

Once the Acknowledgement check has been performed the Client will return each Message Identifier to stdout in the format '<MessageID> <Acknowledged> <Time Acknowledged>'. For example:

\FMS-20081118-145152.160-0.26004090449932216 true 2008-11-18 14:52:00.503