Following items describe all the introduction folders and files that you find in the package.
1.1 Package
The package itself is divided in several folders:
- config
- database
- documentation
- logs
- messages
- samples
- component.exe
In the root of the package you find the .exe file that runs the component. Next up all the folders are being explained.
1.1.1 Config Folder
Inside the configuration folder, following structure is created:
- receive-pmodes
- send-pmodes
- settings.xml
- receive-pmodes
The folders send/receive-pmodes are the folders which configured the PModes (respectively send/receive). Samples of these PModes can be found in the Samples folder.
The settings.xml file contains the global configuration of the component and is explained below (2.2).
1.1.2 Database Folder
Default SQLite is used as database. The .db file which contains the SQLite database is stored in this folder.
Regardless of the database that is being used, this folder will by default also contain the following folder structure:
as4messages
in
out
Inside these folders, the messagebodies of the AS4 messages that have been sent and received are saved.
Received messages are saved in the in folder, messages that have been sent are saved in the out folder.
1.1.3 Documentation Folder
Inside the documentation folder, following structure is created:
- schemas
Inside the schemas folder the .xsd files are located of the PModes and messages. In the root of this folder, documentation is added.
1.1.4 Logs
Inside the logs folder, you can find detailed debug and error logs. In order to modify the log configuration, follow the instructions over here.
1.1.5 Messages Folder
Inside the messages folder, following structure is created:
- attachments
- errors
- exceptions
- receipts
- in
- out
The attachments folder contains several files (pictures and .xml documents) that are being used as reference for the send AS4 messages. The receipts/errors/exceptions folders are used to store Notify Messages. The in folder is used to store incoming messages and attachments; the out folder is being used to send messages to another MSH (the .xml file will be renamed to “.accepted” if it’s being retrieved by the component).
These folders are used just to get started with the component. The component can be configured to use other file folders.
1.1.6 Samples Folder
Inside the samples folder, following structure is created:
- certificates
- messages
- receive-pmodes
- send-pmodes
Each folder contains the respectively the samples of send/receive-PModes and messages. Inside the certificates folder, you find sample certificates that can be used for sending (signing/encrypting) and receiving (verifying) messages.
1.2 Settings.xml
The settings.xml located inside the config folder contains several global configuration settings used inside the component. Each kind of setting is explained in the following paragraphs.
1.2.1 GUID Format
When creating AS4 Messages, Message Ids are being generated. To configure the format in which this must be done the <IdFormat/> tag is being used inside the settings.xml.
Default: {GUID}@{IPADDRESS}
1.2.2 PayloadServiceInProcess
This setting defines whether or not the (optional) PayloadService should be started in-process with the AS4.NET MessageHandler.
The PayloadService is a REST service that can contain payloads that are referenced by submit-messages.
More information regarding the PayloadService can be found in the Technical Analysis document.
1.2.3 FeInProcess
This setting defines whether or not the AS4.NET FrontEnd should be started in-process with the AS4.NET MessageHandler.
The AS4.NET FrontEnd web-application lets you configure the AS4.NET messagehandler and offers monitoring functionality.
1.2.4 Database Provider
The component can be configured to store messages and exceptions in another datastore. Inside the settings.xml the <Database/> tag is responsible for this. Underneath this tag you define the <Provider/>, which can be SQLite, SQLServer,… any type which is supported in Entity Framework Core; and the <ConnectionString/> which defines the actual connection to the database.
So, let’s say you want to change the provider to store the messages in a SQL Server database; you must change the <Provider/> to “SqlServer” and the <ConnectionString/> to a valid SQL Server Connection String: Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;.
Default Provider: Sqlite
Default Connection String: Filename=database\messages.db
1.2.5 CertificateStore
To support signing and encrypting messages, certificates are needed. The certificate store that’s needed to retrieve this certificates and be set in the <StoreName/> tag.
Default: My
The default implementation is used to retrieve certificates from a certificate store on a Windows environment; but you can write your own implementation. If you’re on a Windows environment (so the default implementation is OK for you) you can define here in which Store you want to search. Following values can be used:
...
Member Name
...
Description
...
AddressBook
...
The X.509 certificate store for other users.
...
AuthRoot
...
The X.509 certificate store for third-party certificate authorities (CAs).
...
CertificateAuthority
...
The X.509 certificate store for intermediate certificate authorities (CAs).
...
Disallowed
...
The X.509 certificate store for revoked certificates.
...
My
...
The X.509 certificate store for personal certificates.
...
Root
...
The X.509 certificate store for trusted root certificate authorities (CAs).
...
TrustedPeople
...
The X.509 certificate store for directly trusted people and resources.
...
TrustedPublisher
...
The X.509 certificate store for directly trusted publishers.
1.2.6 Agents
The AS4 protocol has several operations: Submit, Send, Receive, Deliver and Notify. All of these operations are configured in the settings.xml as Agents. Each agent has three items which defines the agent: Receiver, Transformer and Step(s).
A Receiver can be configured in the <Receiver/> tag in each agent. There are multiple kinds of receivers: FileReceiver, DatastoreReceiver, HttpReceiver… Each needed to be configured in order to work correctly. This can be done in the children of this tag as a <Setting/> (with attribute key; the inner text of the tag is the value).
A Transformer can be configured in the <Transformer/> tag in each agent. This transformer is needed in order to transform the received message (could be .xml, .json…) and transform it to a AS4 Message that can be used in the Step(s).
A Step or Steps can be configured in the <StepConfiguration/> tag in each agent. The StepConfiguration element must at least contain a NormalPipeline element. The NormalPipeline element contains the steps that must be executed by the Agent. These steps will be executed after the message is being transformed. Example of steps are: CreateReceiptStep, CompressAttachmentsStep, DecryptAS4MessageStep…
The StepConfiguration can contain an ErrorPipeline element as well. This element contains the Steps that will be executed when a step in the NormalPipeline failed to execute successfully.
Each tag (Receiver, Transformer and Step) has a type attribute which defines the type of which the instance must be created inside the component.
1.2.7 Custom Settings
When creating custom implementations of types, settings can sometimes be useful. For example, an Email Sender by which you configure the SMTP Server in the settings.xml. This can be useful instead of hardcoded each configured value in the implementation itself.
1.3 Sending Processing Mode
This contract describes all the properties available in the Sending PMode. The required data fields are marked as mandatory; default values are provided. Some values of the Sending PMode can be overridden by a SubmitMessage. This definition is available as XSD.
...
Sending PMode
...
*
...
Description
...
Id
...
M
...
PMode Unique Id
...
AllowOverride
...
O
...
Boolean indication whether a SubmitMessage may override already configured values within the sending PMode.
Default: false
...
MEP
...
M
...
Message Exchange Pattern
Enumeration:
- OneWay
- TwoWay
...
MEPBinding
...
M
...
Message Exchange Pattern Binding
Enumeration:
- push
- pull
PushConfiguration
Protocol
URL
UseChunking
UseHTTPCompression
TLSConfiguration
IsEnabled
TLSVersion
ClientCertificateReference
ClientCertificateFindType
ClientCertificateFindValue
O
M
M
O
O
O
M
M
...
M
M
Element must be present when MEPBinding is set to push
URL of the receiving MSH
Default: false (true > not implemented)
Default: false (true > not implemented)
Default: false
Enumeration:
- SSL 3.0
- TLS 1.0
- TLS 1.1
- TLS 1.2
...
DynamicDiscovery
SmlScheme
SmpServerDomainName
DocumentIdentifier
DocumentIdentifierScheme
...
O
O
M
O
O
...
This element is only present when SMP/SML is required
Used to build the SML Uri. Default: iso6523-actorid-upis
Domain name that must be used in the Uri
Used to retrieve the correct DocumentIdentifier.
Default:busdox-docid-qns
...
Reliability
ReceptionAwareness
IsEnabled
RetryCount
RetryInterval
...
O
O
O
O
O
Default: false
Default: 5
Default: 00:01:00 (HH:mm:ss)
...
ReceiptHandling
NotifyMessageProducer
NotifyMethod
Type
Parameters
Parameter
Name
Value
...
O
O
M
M
M
M
M
M
Default: false
Type of the Notify Agent
Required parameters for the specified agent
Name of the parameter
Value of the parameter
...
ErrorHandling
NotifyMessageProducer
NotifyMethod
Type
Parameters
Parameter
Name
Value
...
O
O
M
M
M
M
M
M
Default: false
Type of the Notify Agent
Required parameters for the specified agent
Name of the parameter
Value of the parameter
...
ExceptionHandling
NotifyMessageProducer
NotifyMethod
Type
Parameters
Parameter
Name
Value
...
O
O
M
M
M
M
M
M
Default: false
Type of the Notify Agent
Required parameters for the specified agent
Name of the parameter
Value of the parameter
Security
Signing
IsEnabled
CertificateFindCriteria
CertificateFindType
CertificateFindValue
KeyReferenceMethod
Algorithm
HashFunction
Encryption
IsEnabled
PublicKeyCertificate
Certificate
CertificateFindCriteria
CertificateFindType
...
AlgorithmKeySize
KeyTransport
TransportAlgorithm
DigestAlgorithm
MgfAlgorithm
O
O
O
O
M
M
M
M
M
O
O
O
M
O
M
M
O
O
O
O
O
Default: false
Enumeration:
- FindByThumbprint
- FindBySubjectName
- FindBySubjectDistinguishedName
- FindByIssuerName
- FindByIssuerDistinguishedName
- FindBySerialNumber
- FindByTimeValid
- FindByTimeNotValid
- FindByTimeNotYetValid
- FindByTimeExpired
- FindByTemplateName
- FindByApplicationPolicy
- FindByCertificatePolicy
- FindByExtension
- FindByKeyUsage
- FindBySubjectKeyIdentifier
Enumeration:
- BSTReference
- IssuerSerial
- KeyIdentifier
Default: false
PublicKeyCertificate or CertificateFindCriteria must be specified
Base64 representation of the certificate that must be used
PublicKeyCertificate or CertificateFindCriteria must be specified
Enumeration:
- FindByThumbprint
- FindBySubjectName
- FindBySubjectDistinguishedName
- FindByIssuerName
- FindByIssuerDistinguishedName
- FindBySerialNumber
- FindByTimeValid
- FindByTimeNotValid
- FindByTimeNotYetValid
- FindByTimeExpired
- FindByTemplateName
- FindByApplicationPolicy
- FindByCertificatePolicy
- FindByExtension
- FindByKeyUsage
- FindBySubjectKeyIdentifier
...
- http://www.w3.org/2009/xmlenc11#aes128-gcm
- http://www.w3.org/2001/04/xmlenc#des-cbc
- http://www.w3.org/2001/04/xmlenc#tripledes-cbc
- http://www.w3.org/2001/04/xmlenc#aes128-cbc
- http://www.w3.org/2001/04/xmlenc#aes192-cbc
- http://www.w3.org/2001/04/xmlenc#aes256-cbc
Supported values: 128, 192, 256. Default is 128
Supported values:
Supported values:
...
Supported values:
- http://www.w3.org/2009/xmlenc11#mgf1sha1 (default)
- http://www.w3.org/2009/xmlenc11#mgf1sha224
- http://www.w3.org/2009/xmlenc11#mgf1sha256
- http://www.w3.org/2009/xmlenc11#mgf1sha384
- http://www.w3.org/2009/xmlenc11#mgf1sha512
Note that the Mgf Algorithm cannot be specified when the TransportAlgorithm is not set to http://www.w3.org/2009/xmlenc11#rsa-oaep
...
Message Packaging
Mpc
UseAS4Compression
IsMultiHop
IncludePModeId
PartyInfo
FromParty
PartyIds
PartyId
Id
Type
Role
ToParty
PartyIds
PartyId
Id
Type
Role
CollaborationInfo
AgreementRef
Value
Type
Service
Value
Type
Action
MessageProperties
MessageProperty
Name
Type
Value
...
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
Default: http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/defaultMPC
Default: false
Default: false
Default: false
Id of the sending party
Type of Id of the sending party
Role of the sending party
Id of the receiving party
Type of Id of the receiving party
Role of the receiving party
Information about the partner agreement
Type of the agreement reference
The name of the service that is consumed
Type of the service
The service operation that is consumed
Name of the message property
Type of the message property
Value of the message property
(*): M = Mandatory | O = Optional | R = Recommended
1.4 Receiving Processing Mode
This contract describes all the properties available in the Receiving PMode. The required data fields are marked as mandatory; default values are provided. This definition is available as XSD.
...
Receive PMode
...
*
...
Description
...
Id
...
M
...
PMode Unique Id
...
Reliability
DuplicateElimination
IsEnabled
...
O
O
O
Default: false
ReplyHandling
ReplyPattern
SendingPMode
ReceiptHandling
UseNRRFormat
ErrorHandling
UseSOAPFault
ResponseHttpCode
M
M
...
O
M
O
O
O
Enumeration:
- Response: sync response (default)
- Callback: async response
Reference to the Sending PMode
Specifies if NonRepudationInfo must be included in receipt. Default: false
Default: false
HTTP Status Code in case of reply = response. Default: 200
...
ExceptionHandling
NotifyMessageConsumer
NotifyMethod
Type
Parameters
Parameter
Name
Value
...
O
O
M
M
M
M
M
M
Default: false
Type of the Notify Agent
Required parameters for the specified agent
Name of the parameter
Value of the parameter
Security
SigningVerification
Signature
...
Encryption
CertificateFindCriteria
CertificateFindType
CertificateFindValue
O
O
M
...
O
O
M
M
Enumeration
...
Enumeration
- Allowed (default)
- Not allowed
- Required
- Ignored
Enumeration:
- FindByThumbprint
- FindBySubjectName
- FindBySubjectDistinguishedName
- FindByIssuerName
- FindByIssuerDistinguishedName
- FindBySerialNumber
- FindByTimeValid
- FindByTimeNotValid
- FindByTimeNotYetValid
- FindByTimeExpired
- FindByTemplateName
- FindByApplicationPolicy
- FindByCertificatePolicy
- FindByExtension
- FindByKeyUsage
- FindBySubjectKeyIdentifier
...
Message Packaging
PartyInfo
FromParty
PartyIds
PartyId
Id
Type
Role
ToParty
PartyIds
PartyId
Id
Type
Role
CollaborationInfo
AgreementRef
Value
Type
Service
Value
Type
Action
...
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
Id of the sending party
Type of Id of the sending party
Role of the sending party
Id of the receiving party
Type of Id of the receiving party
Role of the receiving party
Information about the partner agreement
Type of the agreement reference
The name of the service that is consumed
Type of the service
The service operation that is consumed
MessageHandling
Deliver
Deliver
IsEnabled
PayloadReferenceMethod
Type
Parameters
Parameter
Name
Value
DeliverMethod
Type
Parameters
Parameter
Name
Value
Forward
SendingPMode
M
O
M
M
M
M
M
M
M
M
M
M
M
M
M
O
M
Describes how a received ebMS Message must be handled
Deliver or Forward must be specified, not both
True or false
Payload Deliver method (HTTP, FILE, …)
Required parameters
Name of the parameter
Value of the parameter
Type of the Deliver method (HTTP, FILE,..)
Name of the parameter
Value of the parameter
Deliver or Forward must be specified, not both
The name of the PMode that must be used to forward the received Message.
...