user guide
The userguide explains Assimbly in detail. First part is about installation and logging. Further the guide follows the GUI of Assimbly. This GUI consists of:
- Main page (Flows)
- Settings
- Administration
- Account
At the end we discuss how to use clients.
Java (Version 11)
- Get the latest release.
- Open a terminal.
- CD to the directory which contains "gateway-[version].jar" (for example: cd C:\users\user\Download).
- Start the application:
java -jar gateway-[version].jar
See the Quick Start to start a local Assimbly from command line in detail.
Install Assimbly including Java using a Powershell script:
- Download the script.
- Open a Powershell and cd to download directory (for example cd "C:\users\myusername\Downloads").
- Run the script:
.\install_assimbly.ps1
Assimbly can also be installed as a Windows Service.
- Download winsw
- Rename "gateway-version.jar" to "gateway.jar"
- Rename winsw file WinSW.NET4 to "gateway.exe"
- Create a configuration XML file:
<configuration>
<!-- Mandatory fields -->
<id>assimbly-gateway</id>
<name>Assimbly Gateway</name>
<description>Message gateway</description>
<!-- Set alternative path to Java executable -->
<!--<executable>D:\gateway\java\jdk11\bin\java.exe</executable>-->
<executable>java</executable>
<!-- Optional fields. For all options check: https://github.com/kohsuke/winsw -->
<arguments>-Dserver.port=8090 -jar "gateway.jar"</arguments>
<startmode>Automatic</startmode>
<logpath>%BASE%\logs</logpath>
<log mode="roll-by-time">
<pattern>yyyyMMdd</pattern>
</log>
</configuration>- Open CMD as administrator and cd to the gateway directory then use following command:
gateway.exe install
Note: Alternatively you can use nssm to install Assimbly as a Windows service.
Assimbly can also be started from Docker:
docker run --name assimbly -p 8080:8080 skin27/assimbly:latest
When started, the gateway can be reached at the following URL:
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 System.out.
-
File System: The log file of Assimbly is by default created in the user.home directory:
${user.home}/.assimbly/%d{yyyy-MM-dd}.assimbly.log
(on Windows for example: C:\Users\username.assimbly\2019-01-01.assimbly.log). 3) GUI. It's also possible to view the log within the browser:
Administration --> Log viewer
A flow moves data messages between endpoints. Its starts at the from endpoint and ends at the to endpoint. There can be multiple to endpoints as destination. If something goes wrong the message is send to an error endpoint. This endpoint is obligatory, so the message can always be delivered.
A flow is in the background executed as a Camel route, so why is it call a flow? There are two reasons for this:
- A Camel route supports all kind of integration patterns. So a flow is always a route, but not the other way around. It's a simplification of a route. For Assimbly we decide explicitly not to support all integration patterns, you need some kind of ESB or dataflow system for that functionality. We may support a simple filter or transform mechanism if really needed.
- A Java API (Assimbly connector) is build on top of the Camel implementation. So if needed one can implement another Integration framework like Spring Integration or create an own implementation.
There are four ways to create a new flow:
1) GUI
The default way to create a new flow is to use the gui.
- On the main page (flows) click the button "Create flow"
- Give the flow a name.
- There are various generic flow setting, that are explained in the 'i' (info)
- From endpoint: For the source you need to choose component and URI. Use the question mark to get help and suggestions. The service is only available for some endpoints, for example to create a connection. Headers are always available.
- To endpoint: This works the same as for the from endpoint. To only difference as that you can add more endpoints (maximum is 3).
- Error endpoint: This works the same as for the from and to endpoint. The error endpoint is the destination if something goes wrong.
- Save the flow.
2) Import from Gateway settings
Under settings --> gateway there is an import button where a XML configuration can be imported.
3) Clone
When clicking on the name of flow in the main page you get a view of the flow configuration. When clicking on the "Clone" button the wizard opens with this configuration. There you can change every part of the configuration (for example giving the flow a new name) and save the configuration.
4) REST API
The REST API can be called. For this four resources need to be called, namely: flow, from endpoint, to endpoint and error endpoint.
An endpoint is source or destination of a flow. An Assimbly endpoint consists of three parts:
With an URI (Uniform Resource Identifier) an endpoint can be configured. The URI is set up the same way as in Camel:
scheme://context?options
- scheme: To identify the component
- context: To set the source or destination
- options: Options for the component
For example in Camel you can have to following URI:
file:/pathToDirectory?directoryMustExist=true
In Assimbly you select the scheme "file" then set the context "/pathToDirectory". Below the context you choose options if needed.
When you need more information about the components and its options you can click on the Camel button. This links to the latest Camel Component Reference. The Assimbly buttons links to the components information on this wiki. The Assimbly wiki enhances the Camel documentation with explanation, examples and screenshots.
A flow have 5 basic actions:
- Start
- Stop
- Pause
- Resume
- Restart
From the main page the actions which are available have active buttons. When you start a flow you can see the status of flow change from inactive to active. In case of an error the status button gets red. You can hover the status button to get more info.
Settings are configuration that can be used in flows.
In Assimbly a gateway is collection of flows. The flows are moving messages between endpoints. 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.
On the broker page you can configure and manage an embedded ActiveMQ Broker. Bother ActiveMQ Classic (v5) en ActiveMQ Artemis are supported.
Message headers are properties messages. Each property consist of key/value. Values can be set as a constant or with a scripting language (jsonpath, xpath, groovy and simple).
Services can be used by endpoints for example to set up connection to a remote database or broker. For these endoints the service is required, otherwise the service field is diabled
Environment variables make is possible to set values specific for an environment. When the variable is set it can be used with a flow.
More info on Environment Variables
Offloading is a special "to endpoint" where a copy of a message is send to.
Assimbly has SLL/TLS support build-in. This can be used by several components like SFTP/FTPS or HTTPS4. In most cases nothing has to be done in the flow and certificates can be centrally managed:
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.
- 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).
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