Configure OpenAS2

There are two main configuration files which are relevant to each installation and have to be configured individually for every customer:

config.xml

This file contains common configurations. It configures the modules that will be activated by OpenAS2 server when it starts up. You can use the default template provided by OpenAS2 or you can have a look at the example below which has the properties and the modules pre-configured. Replace the {customer_as2_url} placeholder with your customer's URL and try it out.

config.xml

<openas2>
	<properties
		storageBaseDir="%home%/../data"
		log_date_format="yyyy-MM-dd HH:mm:ss.SSS"
		sql_timestamp_format="yyyy-MM-dd HH:mm:ss.SSS"
		as2_message_id_format="OPENAS2-$date.ddMMyyyyHHmmssZ$-$rand.UUID$@$msg.sender.as2_id$_$msg.receiver.as2_id$"
		as2_async_mdn_url="http://194.165.163.149:5080"
		customer_name="Informatica"
		as2_mdn_response_max_wait_seconds="60"
	/>
	<certificates classname="org.openas2.cert.PKCS12CertificateFactory"
		filename="%home%/as2_certs.p12"
		password="testas2"
		interval="300"/>
 
	<partnerships classname="org.openas2.partner.XMLPartnershipFactory"
		filename="%home%/partnerships.xml"
		interval="120"/>
 
	<loggers>
		<logger classname="org.openas2.logging.ConsoleLogger"/>
 
		<!-- Remove this comment to enable emailing of exceptions
		<logger classname="org.openas2.logging.EmailLogger"
			only_active_msg_transfer_errors="false"
			log_exception_trace="false"
			javax.mail.properties.file="%home%/java.mail.properties"
			from="openas2"
			to="your email address"
			smtpserver="your smtp server"
			smtpport="your smtp server port"
			smtpauth="true"
			smtpuser="mySmtpUserId"
			smtppwd="mySmtpPwd"
			subject="$exception.name$: $exception.message$"
			bodytemplate="%home%/emailtemplate.txt"/>
		-->
 
		<logger classname="org.openas2.logging.FileLogger"
			filename="%home%/../logs/log-$date.yyyyMMdd$.txt"/>
		<!-- Remove this comment to enable socket logging
		<logger classname="org.openas2.logging.SocketLogger"
			ipaddr="127.0.0.1"
			portid="19999"/>
		-->
	</loggers>
	<commands classname="org.openas2.cmd.XMLCommandRegistry"
		filename="%home%/commands.xml"/>
 
	<commandProcessors>
		<commandProcessor classname="org.openas2.cmd.processor.StreamCommandProcessor"/>
		<commandProcessor classname="org.openas2.cmd.processor.SocketCommandProcessor"
			portId="14321"
			userid="userID"
			password="pWd"
			response_format="xml"/>
	</commandProcessors>
	<processor classname="org.openas2.processor.DefaultProcessor"
		pendingMDN="$properties.storageBaseDir$/pendingMDN3"
		pendingMDNinfo="$properties.storageBaseDir$/pendinginfoMDN3"
		resend_max_retries="10"
	>
		<module classname="org.openas2.processor.sender.AS2SenderModule"
			retries="3"/>
 
		<module classname="org.openas2.processor.sender.MDNSenderModule"
			retries="3"/>
 
		<module classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"
			outboxdir="$properties.storageBaseDir$/to1WorldSync"
			errordir="$properties.storageBaseDir$/to1WorldSync/error"
			stored_error_filename="OPENAS2-$rand.UUID$@$msg.attributes.filename$_failed_to1WorldSync"
			sentdir="$properties.storageBaseDir$/to1WorldSync/sent"	
			stored_sent_filename="OPENAS2-$rand.UUID$@$msg.attributes.filename$_succeeded_to1WorldSync"
			interval="5"
			defaults="sender.as2_id=INFA_DEV_8_DS, receiver.as2_id=8380160030003"
			sendfilename="true"
			mimetype="application/XML"/>
			
		<module classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"
			outboxdir="$properties.storageBaseDir$/from1WorldSync"
			errordir="$properties.storageBaseDir$/from1WorldSync/error"
			interval="5"
			defaults="sender.as2_id=8380160030003, receiver.as2_id=INFA_DEV_8_DS"
			sendfilename="true"
			mimetype="application/XML"/>	
		
		<module classname="org.openas2.processor.receiver.AS2ReceiverModule"			
			port="5080"
			errordir="$properties.storageBaseDir$/from1WorldSync/inbox/error"
			errorformat="sender.as2_id, receiver.as2_id, headers.message-id"/>
		
		<module classname="org.openas2.processor.receiver.AS2MDNReceiverModule"
			port="5081"
			errordir="$properties.storageBaseDir$/from1WorldSync/inbox/error"
			errorformat="sender.as2_id, receiver.as2_id, headers.message-id"
		/>
 
		<module classname="org.openas2.processor.msgtracking.DbTrackingModule"
			use_embedded_db="true"
			force_load_jdbc_driver="false"
			db_user="sa"
			db_pwd="OpenAS2"
			db_name="openas2"
			table_name="msg_metadata"
			db_directory="%home%/DB"
			jdbc_driver="org.h2.Driver"
			jdbc_connect_string="jdbc:h2:$component.db_directory$/$component.db_name$"
			sql_escape_character="'"
			tcp_server_start="true"
			tcp_server_port="9092"
			tcp_server_password="openas2"
		/>
 
		<module classname="org.openas2.processor.storage.MDNFileModule"
			filename="$properties.storageBaseDir$/from1WorldSync/mdn/$date.yyyy-MM-dd$/$mdn.msg.content-disposition.filename$-$mdn.msg.headers.message-id$"
			protocol="as2"
			tempdir="$properties.storageBaseDir$/temp"/>
 
		<module classname="org.openas2.processor.storage.MessageFileModule"
			filename="$properties.storageBaseDir$/from1WorldSync/inbox/$msg.content-disposition.filename$-$msg.headers.message-id$_from1WorldSync"
			header="$properties.storageBaseDir$/from1WorldSync/msgheaders/$date.yyyy-MM-dd$/$msg.content-disposition.filename$-$msg.headers.message-id$"
			protocol="as2"
			tempdir="$properties.storageBaseDir$/temp"/>
 
		<!-- Example HTTPS configuration
		<module classname="org.openas2.processor.receiver.AS2ReceiverModule"
			port="10443"
			protocol="https"
			ssl_protocol="TLS"
			ssl_keystore="%home%/ssl_certs.jks"
			ssl_keystore_password="testas2"
			errordir="$properties.storageBaseDir$/inbox/error"
			errorformat="sender.as2_id, receiver.as2_id, headers.message-id"/>
			-->		
 
		<module classname="org.openas2.processor.resender.DirectoryResenderModule"
			resenddir="$properties.storageBaseDir$/resend"
			errordir="$properties.storageBaseDir$/to1WorldSync/error"
			resenddelay="10"/>
		<!--
		<module classname="org.openas2.processor.receiver.HealthCheckModule"
			port="10099"/>
		-->
		
		
	</processor>
</openas2>

The following chapter is only important if you change the OpenAS2 file structure. If you go with the defaults provided by Informatica nothing has to be adjusted or considered.

Sending Files

OpenAS2 has a directory polling module that scans configured directories for files and will send the file to a partner (e.g. 1WorldSync). Some of the key attributes for the polling module defined in the config.xml are:

outboxdir: specifies the directory to scan for files to send

outboxdir="$properties.storageBaseDir$/to1WorldSync"
errordir: specifies the directory where the file will be put to whenever OpenAS2 is not able to send it due to any configuration or connection issue

errordir="$properties.storageBaseDir$/to1WorldSync/error"
stored_error_filename: defines the name used to store the file in the errordir

stored_error_filename="OPENAS2-$rand.UUID$@$msg.attributes.filename$_failed_to1WorldSync"
sentdir: specifies the directory where the files that are successfully sent will be stored

sentdir="$properties.storageBaseDir$/to1WorldSync/sent"
stored_sent_filename: defines the name used to store the file in the sentdir that are successfully sent

stored_sent_filename="OPENAS2-$rand.UUID$@$msg.attributes.filename$_succeeded_to1WorldSync"

Receiving Files

There is not much to configure for receiving files. Messages will be received and the files stored in the configured directory. The default modules for receiving and string files is shown below.

<module classname="org.openas2.processor.storage.MessageFileModule"
			filename="$properties.storageBaseDir$/from1WorldSync/inbox/$msg.content-disposition.filename$-$msg.headers.message-id$_from1WorldSync"
			header="$properties.storageBaseDir$/from1WorldSync/msgheaders/$date.yyyy-MM-dd$/$msg.content-disposition.filename$-$msg.headers.message-id$"
            protocol="as2"
            tempdir="$properties.storageBaseDir$/temp"/>

<module classname="org.openas2.processor.receiver.AS2ReceiverModule"            
            port="5080"
            errordir="$properties.storageBaseDir$/from1WorldSync/inbox/error"
            errorformat="sender.as2_id, receiver.as2_id, headers.message-id"/>

partnerships.xml

The partnerships.xml contains information about the connection details between the trade partners such as AS2 ids, certificates and URLs. You can use the default template provided by OpenAS2 or you download or have a look at the exmaple below which is pre-configured for a connection to the PreProd 1WorldSync data pool. Replace the {customer} placeholders with your customer´s name, email etc... and try it out.

partnerships.xml

<partnerships>
 
    <partner name="Informatica"
             as2_id="INFA_DEV_8_DS"
             x509_alias="infa_to_1ws"
             email="mmustermann@informatica.com"/>
 
    <partner name="1WorldSync"
             as2_id="8380160030003"
             x509_alias="1ws"
             email="Info@1WorldSync.com"/>
 
    <partnership name="Informatica-to-1WorldSync">
        <sender name="Informatica"/>
        <receiver name="1WorldSync"/>
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="binary"/>
        <attribute name="subject" value="Sent from $sender.name$ to $receiver.name$"/>
        <attribute name="as2_url" value="http://as2.preprod.1worldsync.com:4080/exchange/8380160030003"/>
        <attribute name="as2_mdn_to" value="http://as2.preprod.1worldsync.com:4080/exchange/8380160030003"/>       
		<attribute name="as2_mdn_options" value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, $attribute.sign$"/>
        <attribute name="encrypt" value="3DES"/>
        <attribute name="sign" value="SHA256"/>
        <attribute name="resend_max_retries" value="3"/>
        <attribute name="prevent_canonicalization_for_mic" value="false"/>
        <attribute name="rename_digest_to_old_name" value="false"/>
 
    </partnership>
	
	<partnership name="1WorldySync-to-Informatica">
        <sender name="1WorldSync"/>
        <receiver name="Informatica"/>
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="binary"/>
        <attribute name="subject" value="File sent from 1WorldSync to us"/>
        <attribute name="as2_url" value="http://194.165.163.149:5080"/>
        <attribute name="as2_mdn_to" value="http://194.165.163.149:5080"/>
        <attribute name="as2_mdn_options" value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, $attribute.sign$"/> 		
		<attribute name="encrypt" value="3DES"/>
        <attribute name="sign" value="SHA256"/>
        <attribute name="resend_max_retries" value="3"/>
        <attribute name="prevent_canonicalization_for_mic" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
        <attribute name="no_set_transfer_encoding_for_signing" value="false"/>
        <attribute name="no_set_transfer_encoding_for_encryption" value="false"/>
        <attribute name="rename_digest_to_old_name" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
    </partnership>
 
</partnerships>

Overview:

If the default configurations are used your file structure should look like in the screenshot below:

Certificates

Finally you have to import and/or create certificates to communicate secure with 1WorldSync. This is described in Appendix B: Certificates.

Troubleshooting

Disposition exception processing MDN

If you get the following exception when you try to send a file via OpenAS2 you should check the AS2 ids you have configured in partner.xml. This error is usually caused by an incorrect configuration. You have to use the AS2 ids agreed with the partner.

Disposition exception processing MDN

2020-05-29 16:19:57.856 ERROR AS2Util: Disposition exception processing MDN ... [<OPENAS2-29052020161957+0000-ac9611f6-9686-4b18-a949-fe7e517502ab@openas2_dev_as2_id_0838016003001>]
org.openas2.DispositionException: null/null; null
        at org.openas2.util.DispositionType.validate(DispositionType.java:98)
        at org.openas2.util.AS2Util.checkMDN(AS2Util.java:183)
        at org.openas2.util.AS2Util.processMDN(AS2Util.java:509)
        at org.openas2.processor.sender.AS2SenderModule.processResponse(AS2SenderModule.java:234)
        at org.openas2.processor.sender.AS2SenderModule.sendMessage(AS2SenderModule.java:207)
        at org.openas2.processor.sender.AS2SenderModule.handle(AS2SenderModule.java:128)
        at org.openas2.processor.DefaultProcessor.handle(DefaultProcessor.java:65)
        at org.openas2.processor.receiver.MessageBuilderModule.processDocument(MessageBuilderModule.java:192)
        at org.openas2.processor.receiver.DirectoryPollingModule.processFile(DirectoryPollingModule.java:191)
        at org.openas2.processor.receiver.DirectoryPollingModule.updateTracking(DirectoryPollingModule.java:165)
        at org.openas2.processor.receiver.DirectoryPollingModule.poll(DirectoryPollingModule.java:76)
        at org.openas2.processor.receiver.PollingModule$PollTask.run(PollingModule.java:62)
        at java.util.TimerThread.mainLoop(Unknown Source)
        at java.util.TimerThread.run(Unknown Source)