user guide
This user guide explains Assimbly in detail. First part is about installation and logging. Further the guide follows the user interface of Assimbly. The last part explains how to use REST clients. If you just want to start creating integrations follow the Quick Start.
The easiest way to install Assimbly is to follow the Quick Start.
Other ways of installation include using PowerShell, Windows Service or Docker.
Assimbly support several command line parameters.
There are three ways to view the logging of Assimbly
- Command Line: When started from command line (with java -jar) you see the log in the terminal.
- File System: The log file of Assimbly is by default created in the user.home directory:
${user.home}/.assimbly/logs/%d{yyyy-MM-dd}.assimbly.log
On Windows for example: C:\Users\username\.assimbly\logs\2019-01-01.assimbly.log.
-
GUI. It's also possible to view the log within the web interface:
Administration --> Log viewer
Assimbly is a tool to create and run integrations.
But what is an integration? In Assimbly it's the end-to-end way to integrate software. Software can be anything like an application, a database, a directory or an API. Assimbly ensures that data flows from a source, throught various processing steps, to one or multiple destinations.
An example is the order flow of a supermarket.
Order flows steps:
1. ERP database (The source)
2. Connect the source to a queue
3. Inbox queue
4. Log message
5. Transform message
6. Outbox queue
7. Connect queue to the destination
8. Destination (API of a supplier)
All these steps together form the integration.
In practice some integration steps can best performed by specialized modules, each specialized in a specific integration function:
- Connector: Connects endpoints
- Route: Process message through integration patterns
- Broker: Transport through queues and topics
In our example:
- Get data from the ERP System --> Connector
- Inbox queue --> Broker
- Perform actions (like log or transform) --> Route
- Outbox queue --> Broker
- Send data to a REST API --> Connector
In Assimbly "Connectors", "Routes" and "Broker" can be configured (and run) independently.
The UI consists of:
- Flows
- Broker
- Settings
- Administration
- Account
A flow processes messages through various steps. On the flows manage page all flows are listed.
There are two types of flows:
- A connector
- A route
A flow is in the background executed as a Camel route, so why is it called a flow? There are several reasons for this:
- A flow consist of one or more routes. It's a collection of routes.
- A flow is on a higher level, making it easier to configure.
- A flow API is build on top of the Camel routes. Thus a REST API can be used to configure and manage flows.
A connector flow connects endpoints. Its starts at the from endpoint and ends at the to endpoint. If something goes wrong the message is send to an error endpoint. The error endpoint is obligatory, so the message can always be delivered.
On the Connector page you can configure and manage connector flows. These connector flows are a bridge between various Apache Camel Components.
from 3.7.0
Routes define the integration flow. It's typically a flow (service) you can find on an Enterprise Service Bus.
On the flows page you can configure and manage route flows. These flows perform all kind of enterprise integration patterns.
On the broker page you can configure and manage an embedded ActiveMQ broker. Both ActiveMQ Classic (v5) and ActiveMQ Artemis are supported.
The default broker is ActiveMQ Artemis, but this can be switched in the GUI.
Settings are configuration that can be used generally.
In Assimbly a gateway is a collection of flows or queues (broker). Basicly Assimbly is a message gateway with the following characteristics:
- Link: it's a link between endpoints, allow them to share information and bypass certain protocols.
- Portal: it's a point of access.
- Message: Messages are central. Messages mostly have a payload (for example a XML) and some headers.
Assimbly gateway tries to fulfill these characteristics as it acts as a portal for one or more endpoints. These endpoints are for example an application, a broker or a location. Endpoints that are linked together form a flow.
Environment variables make is possible to set values specific for an environment. When the variable is set it can be used with a flow.
Assimbly has SLL/TLS support build-in. This can be used by several components like:
You can add certifcates through:
Settings --> Certificates
Certificates in the certificate store are automatically detected by a flow. You can specifically choose to only use the keystore or truststore by adding the "SSLContextParameter" option to a flow with the value #keystore or #truststore.
Administration contains pages to administer Assimbly
- User Management Add, Edit or Delete users. User have either admin rights (manage and configure flows) or user rights (only manage flows).
- Metrics Application metrics like CPU, Memory and number of threads.
- Health Health endpoint like DiskSpace. Also available as REST Endpoint.
- Deployment Import/Export of gateway or flows.
- Configuration The application configuration (application.yml). This can be overwritten on startup.
- Maintenance At the maintenance page you set a flow into maintenance mode. Choose the time the flows are paused. When the timer is finished the flows are automatically started again.
- Audits Audit log of login of users.
- Logs Application log of each class.
- Log viewer Shows the last lines of the log file.
- API All REST API endpoints.
- Database Database client (not in production mode).
Data offloading let you collect events and store the events.
Assimbly has an extensive REST API. This means that all functionality in the GUI can also be call from any REST client. More information can be found:
How to call Assimbly from an external REST client?
Hawtio is a web console to monitor and manage Java applications.
Usage:
- Download the latest app release
- Start Hawtio: java -jar hawtio-app-2.X.X.jar --port 8090
- Connect to Assimbly for example: http://localhost:8080/management/jolokia