Following items describe all the introduction folders and files that you find in the package.
2.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.
2.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 this pmodes can be found in the Samples folder.
The settings.xml file contains the global configuration of the component and is explained here.
2.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.
2.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.
2.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.
2.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.
2.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.
2.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.
2.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}
2.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.
2.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.
2.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
2.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. |
2.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 child’s 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 <Steps/> tag in each agent. These steps will be executed after the message is being transformed. Example of steps are: CreateReceiptStep, CompressAttachmentsStep, DecryptAS4MessageStep…
Each tag (Receiver, Transformer and Step/Decorator) has a type attribute which defines the type of which the instance must be created inside the component.
2.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.
2.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:
|
MEPBinding | M | Message Exchange Pattern Binding Enumeration:
|
PushConfiguration Protocol URL UseChunking UseHTTPCompression TLSConfiguration IsEnabled TLSVersion 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:
|
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:
Enumeration:
PublicKeyCertificate or CertificateFindCriteria must be specified Base64 representation of the certificate that must be used PublicKeyCertificate or CertificateFindCriteria must be specified Enumeration:
Supported values: 128, 192, 256. Default is 128 Supported values: Supported values: Supported values:
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
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 | 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
2.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:
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
Enumeration:
|
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. |
(*): M = Mandatory | O = Optional | R = Recommended