Setting up the Windows Service


So you’ve created a QBridge subscription, added some AS2 partners, and you want to actually send and/or receive data from a Windows machine.

Download the QBridge Windows client here:

Once downloaded, run the MSI installer and follow the installation wizard. NOTE, you will need administrative privileges to complete the installation.

Once installed, a new Windows Service is created:

This image has an empty alt attribute; its file name is Capture-service-1024x406.png

Configuring your Windows Service

The windows service must be configured to connect to your Azure storage account, along with some details of the AS2 partners you’ll be interacting with.

Browse to the service Installation Folder, this will default to C:\Program Files (x86)\EIS\Cloud Relay Service

Open the application settings file appsettings.json

{
  "Logging": {
    "LogLevel": "Information"
  },
  "CloudRelaySettings": {
    "AzureSettings": {
      "StorageConnectionString": "MUST BE PROVIDED",
      "LeaveFilesInAzure": true
      "InboundPollingPeriodSeconds": 60, //OPTIONAL
    },
    "DefaultDeadLetterFolder": "C:\\temp\\Agent\\InboundDeadLetterFolder",
    "CommunicationPartners": [
      {
        "PartnerName": "partner1",
        "DeadLetterFolder": "C:\\temp\\Agent\\Partner1\\DeadLetter",
        "OutboundFolders": [
          {
            "Path": "C:\\temp\\Agent\\Partner1\\Out",
            "FileType": "*.xml",     //OPTIONAL
            "QuarantineFolder": "C:\\temp\\Agent\\Partner1\\OutQuarantine",
            "RetryPeriodMinutes": 10     //OPTIONAL
            "Subject": "SHIPPING"   //OPTIONAL
          }
        ],
        "InboundFolders": [
          {
            "Path": "C:\\temp\\Agent\\Partner1\\In"
            "Subject": "RESPONSE"     //OPTIONAL
          }
        ]
      },
      {
        "PartnerName": "partner2",
        "DeadLetterFolder": "C:\\temp\\Agent\\Partner2\\DeadLetter",
        "OutboundFolders": [
          {
            "Path": "C:\\temp\\Agent\\Partner2\\Out",
            "QuarantineFolder": "C:\\temp\\Agent\\Partner2\\OutQuarantine",
            "RetryPeriodMinutes": 10     //OPTIONAL
          }
        ],
        "InboundFolders": [
          {
            "Path": "C:\\temp\\Agent\\Partner2\\In",
          }
        ]
      }
    ]
  }
}

Azure connection settings:

AzureSettings:StorageConnectionString This must be the connection string for your Azure storage account.
e.g. DefaultEndpointsProtocol=https;AccountName=someaccount;AccountKey=abc/gregergregergfMY/Dwegwegwegwegwege+wXP+j3gT59gkwhroghndlwejrtokgnsdkfcvwfVO+Rw==;EndpointSuffix=core.windows.net
AzureSettings:LeaveFilesInAzure true or false
Defines if a copy of each AS2 message is archived in your Azure storage account. If you want to be able to re-send messages from the AS2 Cloud Relay portal this must be true.
AzureSettings:InboundPollingPeriodSeconds 1-999999
Defines the polling interval (in seconds) to download any inbound AS2 messages from your Azure storage account.
DefaultDeadLetterFolder Folder address
When an inbound message hasn’t been download after 24 hours it will be downloaded into this folder. See the partner settings below as to why it may not have been downloaded.

Partner settings:

Each installation of the windows service can be configured to pull received AS2 messages from any number of partners. As an example, a machine that hosts a financial system may want to pull received sales orders from company ABC, while a different machine may want to pull shipping requests from company ShipXYZ.

In effect, the system is working in a publish subscribe mechanism, whereby the EIS AS2 cloud servers publish inbound messages to the Azure storage container, and then any number of windows installations can subscribe and pull messages.

PartnerName This must match the partner name entered in the AS2 Partner setup from the QBridge Portal. See partner setup guide here e.g. company ABC
DeadLetterFolder local folder path Defines where any messages that have not been downloaded after 24 hours will be saved (this can occur when using a Subject filer, see below).
OutboundFolders[]:Path local folder path Defines where to find files to send to this partner
OutboundFolders[]:FileType *.xml defaults to *.* Type of files to send e.g. *.txt, *.csv, *.xml (only one can be provided)
OutboundFolders[]:QuarantineFolder local or network share folder path Defines where any messages that cannot be uploaded for sending will be saved.
OutboundFolders[]:RetryPeriodMinutes 1-999999 (default 10) Defines how often to retry uploading files.
OutboundFolders[]:Subject string value e.g. SALES_ORDERS All AS2 messages can have a subject defined, this will often be used to identify the type of message. This value entered here will define the subject of outgoing messages picked up from the folder.
InboundFolders[]:Path local or network share folder path Defines where to download files from this partner to.
InboundFolders[]:Subject string value e.g. SALES_ORDERS All AS2 messages can have a subject defined, this will often be used to identify the type of message. This will filter the downloaded AS2 messages to only be those with this subject defined.

From within your QBridge portal, the above example JSON configuration would match the following:

As can be seen, the AS2 Id for each partner is not recorded in the windows service configuration, only the partner name.

In practice, every partner saved in your QBridge portal should also be in your appsettings file.

What happens if the Windows Service is not running?

While the windows service is not running, AS2 messages will not be sent (as there’s nothing pushing messages up into your Azure storage container).

AS2 messages received from your partners while the service is not running will simply be queued in the Azure storage container, awaiting download. They will not expire, and depending on the your Azure subscription, the queue can grow to be many gigabytes in size (there is no message count limit).

Once the service is started again, all queued received messages will be downloaded, and any pending local messages will be uploaded for sending.

Clustering

There are 2 options for clustering the on-premise windows services:

Active – Active

You can have multiple instances of the Windows Service active and use network file share paths for the upload/download directories.

Quick and easy to setup (install on multiple machines, copy appsettings.json to each, and start the windows service on all machines). You don’t get any notifications if a service does go down, and there is no visibility of the cluster in a Windows Server cluster role manager.

Active – Passive

You can setup a classic Windows fail-over cluster: https://docs.microsoft.com/en-us/windows-server/failover-clustering/create-failover-cluster

You get all the standard Windows Server features for managing cluster fail-overs, with the greater control and visibility this brings.