AlfStream Module

This module provides an Apache Camel component and an Alfresco Repository component.

Changelog

The change log for Alfstream can be found here

Requirements:

Alfresco

  • Alfresco Dynamic Extensions
  • Java version 8
  • Version 5.0 and Above

Apache Karaf

  • Apache Karaf 4.0+
  • The Alfstream Camel Component

Compilation

We have created a plugin for gradle called the alfresco amp plugin which is a requirement for compiling all of our modules.

Installing the Alfresco Amp Plugin

Installing of the Alfresco amp plugin requires the following:

  • Java JDK 7 or above installed
  • Gradle installed

Cloning the repository

You can simply clone down our repository with your gitlab account:

git clone https://gitlab.parashift.com.au/open/alfresco-amp-plugin

Publishing to Local Maven

Once you have cloned the repository, it should be published into your gradle environment. This will by default publish to your local computer, but you can adjust build.gradle to publish to another Maven server if it's a requirement with:

gradle publish

Installation (Alfresco)

  • Parashift's AlfStream module is a Repo only amp, please follow our Installation guide on how to install this module.
  • Alfresco Dynamic Extensions is required to be installed, please follow Dynamic Extension Installation guide on how to install it.
  • For more information or a free trial, please click here

Installation (Karaf)

Installation of this module requires an instance of Apache Karaf to host Apache Camel.

Karaf is normally stored within the /opt/apache-karaf-*/ directory where * is the version number.

Windows Installation

To install prerequisite software you will need to do the following:

After this is done follow the Apache Karaf Manually instructions below.

Apache Karaf via Salt Stack

Rather than manually instantiating Karaf, utilising Salt Stack will allow the configuration of Karaf to take less time and ensure that things are deployed in the right order.

  • Create the following pillar configuration on the server:
  karaf:
    bundles:
     - mvn:org.apache.commons/commons-lang3/3.4
     - mvn:com.google.code.gson/gson/2.6.2
     - mvn:org.yaml/snakeyaml/1.17
    artifacts:
     - alfstream-1.*.*.jar
  • Run the following state command: salt-call state.sls karaf

Apache Karaf Manually

  • Install Apache Karaf as per the website instructions or windows install instructions above
  • Copy this file and put it in the karaf base directory, naming it bundles:
  feature:repo-add camel 2.17.0
  feature:repo-add hawtio 1.4.64

  feature:install camel
  feature:install camel-core
  feature:install camel-blueprint
  feature:install hawtio

  bundle:install mvn:org.apache.commons/commons-lang3/3.4
  bundle:install mvn:com.google.code.gson/gson/2.6.2
  bundle:install mvn:org.yaml/snakeyaml/1.17
  bundle:install mvn:org.apache.httpcomponents/httpclient-osgi/4.5.2
  bundle:install mvn:org.apache.httpcomponents/httpcore-osgi/4.4.4
  • Linux: Log in to the cli by running bin/client
  • Windows: Make sure you have an instance running by executing: bin\karaf.bat
  • Run the command source bundles in the client to install all the bundles
  • Copy and deploy the following files to the deploy/ directory:
  • alfstream-1.*.*.jar

Monitoring (Karaf)

Hawtio

To monitor that everything is going OK, you can utilise the web console hawtio via the following URL:

  • Location: http://<hostname>:8181/hawtio
  • Username: karaf
  • Password: karaf

Camel Routes

In the Camel tab of hawtio, you can see deployed routes that are in Apache Karaf.

Tracing

Warning: To trace an exchange, You must first disable Inclusion of Streams in the trace output. This is because viewing a file while tracing will consume the stream, not allowing it to be uploaded to Alfresco.

In the top right click on karaf then click Preferences.

Untick the Include Streams checkbox.

After Include Streams is unselected, click on one of the routes and select the Trace tab. Then select Start tracing. This will enable all exchanges passing through the route so that you can see the inputs/outputs.

Logs

The logs are accessible via the Logs tab. By default the Log Level of INFO is set, so you may need to adjust this to include DEBUG level routes using the CLI

CLI

  • run bin/client from the karaf directory (normally /opt/apache-karaf-*/)
  • (Optional) increase the log to include debug logging for parashift packages:
  log:set DEBUG com.parashift
  • Run log:tail to view the log

You will see debug logs from the com.parashift namespace, which will include the alfstream components.

Usage Examples

There are a few usage examples within the examples directory.

Setting up Configuration variables

All examples make use of configuration variables external to the blueprint file. To create these configurations:

  • Create a new file: etc/com.parashift.cfg
  • Add alfstream.uri, alfstream.username & alfstream.password, i.e:
  alfstream.url=http://localhost:8080/alfresco
  alfstream.username=admin
  alfstream.password=admin

Deploying examples

After you have set up the configuration variables, simply drop the blueprint xml file in the karaf deploy directory to start the route.

Debug Log Example

File: examples/alfstream-debug-log-blueprint.xml

The debug log example simply logs all exchanges to a debug log.

You will need a log level set to debug within karaf:

  log:set debug com.parashift

Two Way Blueprint

File: examples/alfstream-two-way-blueprint.xml

The two way blueprint will synchronise between two instances of Alfresco. This will synchronise all files and folders within a site called test.

You will need to set the following configuration properties:

  • alfstream.local.url: the Local alfresco instance (normally localhost, but could be a different server)
  • alfstream.local.username: the Local alfresco admin username
  • alfstream.local.password: the Local alfresco admin password

  • alfstream.remote.url: the Remote alfresco instance

  • alfstream.remote.username: the Remote alfresco admin username
  • alfstream.remote.password: the Remote alfresco admin password

Upsert Blueprint

File: examples/alfstream-upsert-blueprint.xml

Requires the upsert camel component. This will allow alfstream events to be synchronised to a seperate postgres database for reporting and analytics.