Skip to content
Documentation
Getting started
Introduction

Introduction

This page explains what MicroB2B does and the main ideas you meet in the rest of the documentation. Read it once before you set anything up.

What MicroB2B does

MicroB2B receives, routes and delivers business documents between your organization and your trading partners. It speaks AS2, the protocol many companies use to exchange orders, invoices and other EDI documents over the internet. On your side it reads files from directories, writes files to directories, and posts documents to HTTP addresses.

MicroB2B moves documents but never reads them. It does not parse, check or convert EDIFACT, X12, XML or any other format. What comes in is stored, signed, encrypted, delivered and confirmed byte for byte. If another system needs a value from inside a document, that system reads it.

MicroB2B runs as one program, microb2b standalone, with a web UI and a REST API. It stores its data in SQLite or PostgreSQL. See Install and run.

The main ideas

Organization. That is you: a party on your side. A new installation starts with one organization, named local. You can rename it and add more.

Partner. A company you exchange documents with: a party on the other side.

Name. Every organization and partner has a short name in lower case, such as acme. Routes, file paths and messages use these names, never AS2 addresses.

Certificate. An X.509 certificate, with or without its private key. AS2 uses certificates to sign and encrypt messages. You keep your own certificates (with keys) and your partners’ certificates (without keys). See Certificates.

AS2 profile. The AS2 details of an organization or a partner: its AS2 ID (its address in AS2), its certificates and, for a partner, the URL it receives at. See AS2 overview.

Plugin instance. A named component that handles messages, with its own settings. Each one has a type:

  • An AS2 receiver listens for messages from partners.
  • An AS2 sender sends messages to partners.
  • A file poller picks up files from a directory.
  • A file writer writes messages to files in a directory.
  • An HTTP poster posts messages to a URL of one of your systems.

Receivers and file pollers are sources: messages come in through them. Senders, file writers and HTTP posters are targets: messages leave through them.

Route. A rule that says where messages go. It names a source, a sender party (From), a receiving party (To) and a target. “Any” matches every party. See Routes.

Message. One business document that came in through a source, with its history. See Messages.

Delivery. One target’s job of delivering one message. A message that matches two routes has two deliveries, for example one to a partner and one to an archive directory.

Receipt (MDN). A signed confirmation that a partner sends back after receiving an AS2 message. AS2 calls it an MDN (message disposition notification). See AS2 receipts.

Alert and notifier. MicroB2B raises an alert when something needs your attention, such as a failed message or a certificate about to expire. A notifier sends alerts to Slack, Teams, Discord, Google Chat, ntfy or any webhook. See Notifications.

How a message flows out

  1. One of your systems drops a file in a directory, for example data/outbox/acme/order.xml.
  2. The file poller picks it up. The folder name acme tells it the partner.
  3. MicroB2B stores the message and checks the routes. A route sends messages from the file poller to the AS2 sender.
  4. The AS2 sender looks up the partner’s AS2 profile. It signs and encrypts the file, as the profile says, and sends it to the partner’s URL.
  5. The partner answers with a receipt. The message status becomes Delivered.

How a message flows in

  1. A partner sends an AS2 message to your AS2 receiver.
  2. The receiver finds your organization and the partner by their AS2 IDs. It decrypts the message and checks the signature.
  3. MicroB2B stores the message and checks the routes. A route sends messages from the receiver to the file writer.
  4. The receiver answers the partner with a receipt.
  5. The file writer writes the document to data/inbox/acme/. The message status becomes Delivered.

If something fails, MicroB2B retries where retrying can help. It shows each step in the message’s history and raises an alert when a person needs to act.

Glossary

TermMeaning
AS2A protocol for sending business documents securely over HTTP or HTTPS
AS2 IDThe name a party uses in AS2 messages, agreed with your partner
OrganizationYour own company, or a part of it, as a party
PartnerA company you exchange documents with
CertificateA public key with a name, used to sign and encrypt; yours also has a private key
AS2 profileThe AS2 settings of an organization or a partner
Receiver, senderPlugin instances that receive and send AS2 messages
File poller, file writerPlugin instances that read files from and write files to a directory
HTTP posterA plugin instance that posts messages to a URL
RouteA rule from a source, through From and To, to a target
MessageOne document that came in, with its history
DeliveryOne target’s job of delivering one message
Receipt (MDN)A partner’s signed confirmation that it received a message
AlertA notice that something needs attention
NotifierA plugin instance that sends alerts out

Where to go next

Quick start