Programming for ELO

ELO Flows components

2 Programming for ELO

Table of contents

Basics 3

ELO Flows component development 3

ELO Flows component 5

Configuration 9

Configure environment 9
SSH in Apache Karaf 10
Install the ELO Dev Plug-in 12
Create new project 14
Tips and tricks 17

Component development 19

Developing an ELO Flows component 19

Example component 23
Build process 36
Deployment 38
Debugging 41
Component configuration options 43
3 Programming for ELO

Basics
ELO Flows component development
In the following section Basics – ELO Flows component development, you will get to know ELO
Flows component development.

You will learn more about:

• ELO Flows
• Added value for development
• Requirements for implementing ELO Flows components
• ELO Flows components in general

Introduction

ELO Flows enables non-technical people to implement automation and integration tasks in ELO.
ELO Flows component development serves as the foundation. It enables ELO Business Partners to
make modular customizations in ELO and provide them as flows. For more information on ELO
Flows, refer to the ELO Flows documentation.

Added value

ELO Business Partners often receive requests for custom ELO solutions. With ELO Flows component
development, you can reduce the costs and time associated with programming customizations
significantly:

The Java-based programming of custom ELO Flows enables users to extend the scope of standard
ELO functions. Custom components result in substantially lower QA and support costs compared
with standard interfaces.

Requirements

The following requirements apply for ELO Flows component development:

• ELO 21 or higher
• ELO Flows 21 or higher
• Visual Studio Code (abbreviated VS Code)
• The VS Code Plug-in: Framework for ELO Flows component development
• Java Runtime Environment (Java 17 and higher)
• Gradle 7 or higher
• SSH access enabled in Apache Karaf

Refer to the following sections for more information.

4 Programming for ELO

Source text editor: Visual Studio Code (VS Code)

Use Visual Studio Code as your source text editor.

VS Code runs on the operating systems Windows, Linux, and macOS. The editor is not a true
integrated development environment (IDE), but it still contains all standard programming tools
(version control, debugging, code completion, or syntax highlighting).

VS Code does not work on a project basis, meaning implementation work is organized in work
environments and folders. By using plug-ins, VS Code can be used for virtually programming
language, customized, and extended.

The VS Code Plug-in: Framework for ELO Flows component development

The ELO Dev Plug-in for VS Code provides the ideal work environment for ELO Flows component
development. It includes a pre-configured framework for ELO Flows component development. This
framework simplifies development and establishes standard guidelines for implementation. You
can begin a project and programming directly after installation. No additional configurations or
extensions are required. The plug-in also includes an example component to help you get started
with developing.

You can find more information on the VS Code plug-in in the Install the ELO DEV Plug-in section

Java Runtime Environment (Java 17 and higher)

ELO Flows components are implemented with the Java programming language. You will need
version Java 17 or higher of the Java Runtime Environment (JRE). For more comprehensive
implementations, we recommend a Java Development Kit (JDK). This provides additional
programming tools. The Java Runtime Environment (JRE) is already included in JDK.

Gradle 7

The build management project tool Gradle (version 7 and higher) is used in ELO Flows component
development to integrate external Java libraries (JAR files) and frameworks such as JUnit.

SSH access enabled in Apache Karaf

Developing using the VS Code plug-in requires Apache Karaf to be available via SSH. Since the final
release of ELO 21, the ELO server setup installs Apache Karaf with SSH access disabled. First,
enable SSH access in Apache Karaf.
5 Programming for ELO

ELO Flows component

ELO Flows is based on the principle of component programming. Flows components are self-
contained software elements that extend ELO's standard functions. Encapsulation of the
components enables a high level of portability. They can be programmed independent of customer
systems and integrated into the respective customer system as needed via standardized
interfaces. An ELO Flows component is output as a JAR file and provided for further use in the ELO
Flows worker. The worker is based on Apache Karaf and provides the container for the components.

An ELO Flows component consists of graphical elements. These are realized via Java annotations.
Components can be triggers, services, or a combination of the two. In addition, information fields
can be integrated into ELO Flows whose contents are configured as MD files.

ELO Flows components are built based on a fixed schema that is specified by ELO. Development of
ELO Flows components takes place in the framework for ELO Flows component development in VS
Code. The framework is available via the ELO Dev Plug-in.

ELO Flows comes with standard components that you can reuse or develop further during
component development.

The main documentation for ELO Flows describes how the standard components work.

The respective definitions fo the standard components and annotations can be found within the
documentation in the areas Component API and Schema API as well as in the API documentation
implemented in ELO.

Triggers

Triggers are the starting points of a flow. Triggers are implemented in the component with specially
annotated functions.
6 Programming for ELO

Example code structure for a trigger

/**
* This trigger is called from input forms with dynamic keyword lists.
*
* @param eventData Daten des IX Events
* @return
*/
@Guide("base_trigger_dynkwlevent.md")
@Trigger(name = "DynKwlEvent", displayName = "elobasecomponent.dynkwltrigger.displayname")
@TriggerAccess(TriggerAccessType.INTERNAL)
@WebHook(endpoint = "DynKwlEvent")
@Synchron(resultClasses = { SimpleDynKwlColumnsResult.class, DynKwlColumnsResult.class,
DynKwlResult.class })
public DynKwlEventData dynKwlEvent(DynKwlEventData eventData) {
LOG.info("Execute DynKwlEvent");
return eventData;
}

Return value

In the example code structure for the trigger, dynKwlEventData is the return value:

public DynKwlEventData ...

The return value enables the trigger function to be targeted and addressed for individual node
points and services within the ELO Flows editor.
 7 Programming for ELO

Result class

In the example code structure for the trigger, the result class was defined as follows:

@Synchron(resultClasses = { SimpleDynKwlColumnsResult.class, DynKwlColumnsResult.class,

DynKwlResult.class })

The result class @Synchron defines the result type for the entire flow and provides it in the ELO
Flows editor in the end node.
8 Programming for ELO
9 Programming for ELO

Configuration
Configure environment
The following section explains how you can prepare ELO Flows component development on your
system and best configure the environment.

You will learn more about:

• Enabling of SSH in Apache Karaf

• How to install the ELO Dev Plug-in in VS Code
• How to create a new project for ELO Flows component development

You will also find some tips and useful information for component development.
10 Programming for ELO

SSH in Apache Karaf

The ELO DEV Plug-in requires SSH to be enabled in Apache Karaf.

SSH in Apache Karaf is automatically enabled during installation of the ELO Server Setup.

Check whether SSH is enabled in Apache Karaf

Method

1. Open PowerShell or terminal.

2. Enter the following command: ssh admin@<Hostname> -p 8101

3. Enter the password.

Information

When performing installation with the ELO Server Setup, use the following access
data:

User name admin

Password Password of the Application Server Admin User from the ELO Server Setup

Result

If SSH is enabled in Apache Karaf, the Karaf prompt is shown.

Information

You can still develop components for ELO Flows without enabling SSH in Apache Karaf. In
this case, you have to perform deployment manually.
11 Programming for ELO

Enable SSH in Apache Karaf manually

If the check revealed that SSH is not enabled for Apache Karaf, you can enable it manually.

Method

1. In the …/etc/org.apache.karaf.features.cfg file, add ,ssh/4.3.0 to the featuresBoot option.

The entry may look like this:

featuresBoot = c832d3b5-dd96-4694-b9eb-92a07ae62096,ssh/4.3.0

2. Add the following entries to the users.properties file (%karaf%/etc/users.properties):

karaf = karaf,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh

3.
Restart the system.

Result

When checking the SSH connection via the terminal or PowerShell again, the Karaf prompt now
appears.
12 Programming for ELO

Install the ELO Dev Plug-in

Preparation: Set environment and path variable

1. Set the JAVA_HOME environment variable for Java. Enter the relevant path.

2. Add the path variables for Gradle. Enter the relevant path.

Download the ELO Dev Plug-in for VS Code

1. Download the ELO Plug-in framework for component development. You will find the ELO plug-
in in the ELO Flows component development ZIP file.

2. Extract the ZIP file to a directory.

Information

The plug-in file does not have to remain available. You can also extract the file to a
temporary directory.

Install the ELO Dev Plug-in in VS Code

1. Open VS Code.

2. On the menu bar, select the Extensions tab.

13 Programming for ELO

3. Select Install from VSIX … from the drop-down menu.

4. Select the ELO Dev Plug-in in VSIX format.

After installation is completed, you will get more information on the ELO Dev Plug-in in VS
Code.
14 Programming for ELO

Create new project

The ELO Dev Plug-in triggers automated creation of the project structure in VS Code, also
configuring the framework for ELO Flows component development.

The framework offers a complete, ready-to-use framework for designing components. The example
components provided simplify the creation process.

In the following section, you will learn:

• How to create a project structure for an ELO Flows component in VS Code.

• How to initialize the project as a Java project.

Create project structure for an ELO Flows component

1. Start VS Code.

2. Select the folder where you want to create the new component:

File > Open folder...

15 Programming for ELO

3. Run the command ELO: Create component via the Command Palette:

View > Command Palette…

Alternative 1: CTRL + SHIFT + P

Alternative 2: F1 key

4. Select 'ELO Flows' to create a new component.

5. Enter a namespace.

6. Enter a name for the component.

7. Enter a version.
16 Programming for ELO

VS Code shows a pop-up window when the component has been created successfully.

Initialize project as Java project

Initialize the project as a Java project to load extensions for Java development.

1. In the project structure, navigate to a Java class.

2. Click the Java class to select it.

3. Confirm the respective messages with Yes.

Information

While loading, do not perform any other actions in VS Code.

You can check the loading status by clicking the rotating circle (at the bottom right of VS Code).
Loading is completed when a thumbs-up icon appears.
17 Programming for ELO

Tips and tricks

This section provides you with additional information.

You will learn more about:

• Automatically generated folder structure in VS Code

• Keyboard shortcuts in the context with the ELO Dev Plug-in

Structure of the framework for ELO Flows component development

The framework for ELO Flows component development consists of multiple different areas typical
for Java projects:

• src\main
• resources
• bin
•
18 Programming for ELO

libs
• test

Information

Over the course of the development process, you can add structure areas as you go along.
This includes additional classes or the libraries created in your project.

Source code folder: src\main

The source code (Source) of the project is located in the folder src\main.

Information

The project folder structure does not correspond to a 1:1 package in the source code. This
depends on the project settings and can be customized later.

Resources folder: resources

The resources project folder contains the localization files, for example.

Binary files folder: bin

The translated Java classes and resources are filed to the bin project folder. The JAR files are built
from these later via the build process.

Library folder: libs

After the first build process, a new folder with the JAR library appears.

Optional test folder: test

It may make sense to create a test folder with a (test) structure first.

Keyboard shortcuts for VS Code with the ELO Dev Plug-in

Function Keyboard shortcuts

Open 'Command Palette' CTRL + SHIFT + P or F1
Select build task CTRL + SHIFT + B
End 'Hot Deployment to ELO Flows Worker' CTRL + D + ENTER
Start debugger or Stop debugger F5 or CTRL + F5
19 Programming for ELO

Component development
Developing an ELO Flows component
This section describes the development process for an ELO Flows component with a focus on the
following topics:

• Example component Document counter: Taking a new component implementation as an

example, go through the most important steps of component development.
• Deployment: The framework for ELO Flows component development offers two options for
deployment: single deployment and continuous deployment.
• Debugging: You will learn more about the debugging process within VS Code.
• Configuration options: You will get a list of configuration options ELO provides for the
development process.

Particularities and conventions

Important

When developing with the API flow component, only use secure methods for processing
paths. To protect your application from security vulnerabilities such as Directory Traversal, it
is essential that you avoid:

1. Direct creation of File objects with user input: File file = new
File(userInputPath); this can allow attackers to gain unauthorized access to files
outside the designated directories.

2. Combination of constants and user input:File file = new File(“/safe/directory/”

+ userInputPath); this poses the risk that attackers can access higher-level
directories with a invalid input (e.g. ../).

POJO principle

The framework for developing ELO Flows components is based on the plain old Java object (POJO)
approach.

Please note

ELO Flows requires the following, in particular for model classes:

• Use of the getter and setter access methods

• Compliance with JavaBeans naming conventions for functions and classes

Example
20 Programming for ELO

In the following example, a variable someProperty is defined. In the context of the getter and setter
access methods, the variable and the getter and setter methods can be written in CamelCase
corresponding to the naming conventions so that they are recognized uniquely when executing the
flow.

public class MyBean {

private String someProperty;

public String getSomeProperty() {

return someProperty;
}

public void setSomeProperty(String someProperty) {

this.someProperty = someProperty;
}
}

If the name of the variable is changed to someOtherProperty for example, the name also has to be
changed within getter and setter.

public class MyBean {

private String someOtherProperty;

public String getSomeOtherProperty() {

return someOtherProperty;
}

public void setSomeOtherProperty(String someOtherProperty) {

this.someOtherProperty = someOtherProperty;
}
}

Component versioning

Component versions are only written with a lowercase v and the version number as a whole
number (e.g. v1, v2, or v42): v<whole number>

Information

Difference between component version and API version

Component version

•
21 Programming for ELO

The semantic version number of the build artifact

• Reflects the internal software version
• Incremented with each change to the code (or release)

API version

• Specified in the @Component annotation

• Reflects the version of the external component interface
• Is only incremented when changes are made to the interface that are not backwards-
compatible (e.g. service signature changed, input or output objects change in a way
that is incompatible). This is the case if flows with the old configuration would no
longer work after the new component version has been installed.

@Property annotation as a requirement for fields

To develop components with fields, ELO Flows requires a @Property annotation starting with ELO
21.3.

Please note

Fields that do not have the @Property annotation are ignored during the schema analysis.

Example: Annotation with @Property

...
import com.elo.flows.api.schema.annotations.Property;

public class HelloOutput {

@Property(displayName = "text")
private String text;

@Property(displayName = "andere_eigenschaft")
private String otherProp;

public String getText() {

return text;
}
...
}
22 Programming for ELO

ELO Flows file handling

In ELO Flows, file handling does not follow the Java convention.

Please note

Against the frequently used Java convention for file handling, the InputStream cannot be
closed for ELO Flows files. The ELO Flows file proxy object can no longer upload a closed
InputStream to the file store after the method has been executed. If you use try-with-
resources or manually close the stream in the finally block, for example, the InputStream
can no longer be uploaded.

Example: Approach specific to ELO Flows files

The following snippet presents an example of how you can return an ELO Flows file with an
InputStream. After upload, the proxy object takes care of closing the InputStream.

@Component(namespace = "com.elo.flows", name = "ELOExample",

version = "v1", displayName = "eloexamplecomponent.displayname")
public class FlowFileSpecialityExampleComponent {

@Service(name = "LoadTxtFile")
public FlowFile loadTxtFile(final String txtFileName) throws IOException {
InputStream inputStream = getInputStreamOfTxtFile(txtFileName);
return FlowFile.of("example.txt", inputStream);
}
}
23 Programming for ELO

Example component
The following example implements a counter for documents filed to the repository. The counter
guarantees that the documents of a specific type (e.g. defined by the ELO Business Solution
SOL_TYPE or the metadata form) are assigned a unique serial identifier. Examples include contract
or invoice numbers.

Information

The following example shows the implementation of the Java class CounterComponent.java
(or CounterException.java and CounterInput.java). The Java class CounterService.java has
to be implemented/provided as a file first. It contains the implementation of the counter
logic and can be customized.

The declaration of the following example components is based on the contents of the ELO
Academy training ELO Flows Development from the year 2021. This is why the Academy
environment is reflected in the namespace of the Java classes, for example.
24 Programming for ELO
25 Programming for ELO

The finished component enables users:

• To
select a counter (a counter can already exist)
• To
define/enter a new counter (prefix, postfix, number of digits). Example CounterInput.java.
• To
create a new counter. Example CounterComponent.java.
• To
return the current count in other components via a node key. Example key:
Counter.display.name.
• To select the new component as the trigger (REST).

Start the framework for ELO Flows component development

1. Start VS Code and open the intended project folder.

2. Create the project structure for the ELO Flows component.
3. Initialize the project as a Java project to load extensions for Java development.
4. During initialization, confirm the respective messages with Yes and wait until all extensions
have loaded.

Information

You will find more in-depth information on creating components with a project structure and
Java initialization in the section Configure environment > Create project of this
documentation.

Customize project structure for existing components

ELO has implemented an example component in a newly created ELO Flows component. You can
tailor it to new requirements or delete it and create an entirely new one. In the following example,
we take a middle course.

1.
26 Programming for ELO

Delete the contents of the files in the localization folder:

Important

Do not delete any files. Only delete the contents of the files.

translations_de.properties and translations.properties.

2. Delete the Java classes in the folder java\academy\training:

HelloInput.java and HelloOutput.java

3. Modify the Java class HelloWorldComponent.java:

To do so, use the refactoring options provided by VS Code

27 Programming for ELO

4. Enter the following in the localization files in the localization folder:

translations\_de.properties and translations.properties

Key: Counter.display.name

Values: Dokumentenzähler and Document Counter.

5. Add additional levels to the project structure.

Connecting to the ELO Indexserver

The annotation @Connection automatically establishes a connection to the ELO Indexserver. The
connection to the ELOix is declared in a class via the annotation @Connection.
28 Programming for ELO

@Component(version = "0.0.1", namespace = "academy.training",

name = "Counter", displayName = "Counter.display.name")
public class CounterComponent {
@Connection
IXConnection ixConnect;
}

You can use the class in any method via the annotation @ConnectionRequired.

public class CounterComponent {

private static final Logger LOG =
LoggerFactory.getLogger(CounterComponent.class);

@Connection
IXConnection ixConnect;

@LookupProvider("getCounters")
@ConnectionRequired
public Map<String,String> getCounters() throws CounterException {
HashMap<String,String> map = new HashMap<>();
try {
CounterInfo[] counters = ixConnect.ix().checkoutCounters(null,
false, LockC.NO);
for (CounterInfo counterInfo : counters) {
map.put(counterInfo.getName() + "["+ counterInfo.getValue() +"]", counterInfo
}
}
catch (Exception e) {
throw new CounterException(e.getMessage());
}
return map;
}
}

Implementing the document counter

Perform the following implementation steps for the declaration:

Define the logger for log outputs

1. Use the following code:

private static final Logger LOG = LoggerFactory.getLogger(CounterComponent.class);

29 Programming for ELO

Information

Make sure to select the correct imports.

VS Code offers multiple import options for the logger class (import org.slf4j.Logger,
org.slf4j.LoggerFactory)

Implement method definition for the 'Counter' service ('Service' tab)

1. Create a new class (CounterOutput.java). File the class in the project structure under model.
The class passes on the counter information to the following components in ELO Flows via a
key.

package academy.training.model;
public class CounterOutput {
private String counterValue;
public String getCounterValue() {
return counterValue;
}
public void setCounterValue(String counterValue) {
this.counterValue = counterValue;
}
}

2. Implement the service in the class CounterComponent.java using the annotations @Service

and @ConnectionRequired.

This ensures the following:

◦ The service can be selected in the component's graphical user interface.

◦ The service is connected to the ELO Indexserver.

@Service(displayName = "Select counter")

@ConnectionRequired
public CounterOutput createCounter() {
if (LOG.isDebugEnabled()) {
LOG.debug("createCounter start");
}
CounterOutput counterOutput = new CounterOutput();
String counterValue = "undefined";
//TODO getCounterValue
return counterOutput;
}

Create input fields for counter name, prefix, and postfix ('Settings' tab)

1.
30 Programming for ELO

Create a new class (CounterInput.java) for the input fields.

2. File this in the project structure under model.

3. In this class, you assign the elements for the counter selection via annotations.

The input fields appear on the Settings tab later.

Annotation for input field: @Property

You can define the individual input fields via the annotation @Property. You can group the input
fields via @PropertyGroups and @PropertyGroup. Determine the order within the group via
@DisplayOptions.

Annotation for suggestion list: @Lookup

A possible solution could look like this:

To fill the suggestion list with existing counters, use the annotation @Lookup and implement your
own logic based on the ELOix API.

Please note

You will have to program the logic for the suggestions ( @Lookup) in the component class
(@Component).

1. Within the component class (@Component) for the service method (@Service), transfer the new
class (CounterInput.java) as an object.
2. Implement the logic for creating the counter in CounterService.java in the service folder.
31 Programming for ELO

@Service(displayName = "Select counter")

@ConnectionRequired
public CounterOutput createCounter(CounterInput counterInput) {
…
}

Integrating REST triggers in the component

As with @Service, implement a trigger method in the (@Component) component class. The
annotations you need are @Trigger and @WebHook. You can also work with input and output
parameters here.

Example programming for the classes 'CounterException', 'CounterInput',

'CounterComponent'

The following code examples show example programming for the Java classes CounterException,
CounterInput, CounterComponent.

CounterException.java

public class CounterException extends Exception {

public final static String COUNTERERROR = "Error creating counter";
public CounterException() {
super(CounterException.COUNTERERROR);
}
public CounterException(String errorMessage) {
super(errorMessage);
}
}

CounterInput.java

public class CounterException extends Exception {

package academy.training.model;

import com.elo.flows.api.components.annotations.Guide;
import com.elo.flows.api.schema.annotations.DisplayOptions;
import com.elo.flows.api.schema.annotations.Lookup;
import com.elo.flows.api.schema.annotations.Property;
import com.elo.flows.api.schema.annotations.PropertyGroup;
import com.elo.flows.api.schema.annotations.PropertyGroupRef;
import com.elo.flows.api.schema.annotations.PropertyGroups;
32 Programming for ELO

@Guide("configuration.md")
@PropertyGroups({@PropertyGroup(displayName ="New counter", name="groupNewCounter")})
public class CounterInput{

@Property(displayName = "Counter name", required=true, description="Enter postfix and prefix for new count
@Lookup("getCounters")
private String counterName;

@Property(displayName ="Prefix", description="Enter counter name above")

@PropertyGroupRef("groupNewCounter")
@DisplayOptions(order = 1)
private String prefix = "test";

@Property(displayName ="Postfix", description="Enter counter name above")

@PropertyGroupRef("groupNewCounter")
@DisplayOptions(order = 2, suggestValue = true)
private int postfix = 6;
public String getCounterName() {
return counterName;
}
public void setCounterName(String counterName) {
this.counterName = counterName;
}
public String getPrefix() {
return prefix;
}
public void setPrefix(String prefix) {
this.prefix = prefix;
}
public int getPostfix() {
return postfix;
}
public void setPostfix(int postfix) {
this.postfix = postfix;
}
}

CounterComponent.java

package academy.training;

import de.elo.ix.client.CounterInfo;
import de.elo.ix.client.IXConnection;
import de.elo.ix.client.LockC;
33 Programming for ELO

import java.util.HashMap;
import java.util.Map;

import com.elo.flows.api.components.annotations.Component;
import com.elo.flows.api.components.annotations.Connection;
import com.elo.flows.api.components.annotations.ConnectionRequired;
import com.elo.flows.api.components.annotations.Guide;
import com.elo.flows.api.components.annotations.LookupProvider;
import com.elo.flows.api.components.annotations.Service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import academy.training.exception.CounterException;
import academy.training.model.CounterInput;
import academy.training.model.CounterOutput;
import academy.training.service.CounterService;

@Component(version = "0.0.1", namespace = "academy.training",

name = "Counter", displayName = "Counter.display.name")
@Guide("counter.md")
public class CounterComponent {

private static final Logger LOG = LoggerFactory.getLogger(CounterComponent.class);

@Connection
IXConnection ixConnect;
@Service(displayName = "Select counter", description = "Select a counter for your document")
@ConnectionRequired
@Guide("configuration.md")
public CounterOutput createCounter(CounterInput counterInput) {
if (LOG.isDebugEnabled()) {
LOG.debug("createCounter start");
}
CounterOutput counterOutput = new CounterOutput();
String counterValue = "undefined";
counterValue = CounterService.getCounterValue(ixConnect, counterInput.getCounterName(),
counterInput.getPrefix(), counterInput.getPostfix());
counterOutput.setCounterValue(counterValue);
return counterOutput;
}

@LookupProvider("getCounters")
@ConnectionRequired
public Map<String,String> getCounters() throws CounterException {
HashMap<String,String> map = new HashMap<>();
try {
34 Programming for ELO

CounterInfo[] counters = ixConnect.ix().checkoutCounters(null, true, LockC.NO);

for (CounterInfo counterInfo : counters) {
map.put(counterInfo.getName(), counterInfo.getName());
}
}
catch (Exception e) {
throw new CounterException(e.getMessage());
}
return map;
}
}

Additional possible extensions for the component

1. Integrating the JUnit test framework

Add the following entry to the configuration file build.gradle.

Information

Make sure to add the entries to the correct build.gradle.

2. Integrating new libraries via Maven

3.
35 Programming for ELO

Integrating custom libraries

36 Programming for ELO

Build process
The ELO Dev Plug-in provides a Build task function for building a JAR file out of the components.
This file can then be tested in the ELO Flows worker (Apache Karaf).

Run build task

Proceed as follows to include all components in the open folder in the build.

1. Run the selection dialog box via Terminal > Run build task….

Alternative: Press CTRL + SHIFT + B

2. Select Build ELO Flows Components.

3. Select Continue without scanning the task output.

The component created is now in the project build folder as a JAR file.

Information
37 Programming for ELO

The first build may take some time. Once the build process has been completed
successfully, the note "BUILD SUCCESSFUL" is shown in the terminal.
38 Programming for ELO

Deployment

Make your new component available in ELO Flows. After the build process, deploy the JAR file in the
ELO Flows worker (Apache Karaf).

The ELO Dev Plug-in for VS Code offers two options. In both of these cases, Apache Karaf has to be
running and available locally.

Single deployment: Deploy to ELO Flows Worker

With the option Deploy to ELO Flows Worker, you deploy the newly built JAR file in the flows worker
(Apache Karaf) once. This option can be recommended at the beginning of the development phase,
when making larger changes and the component likely still contains (compilation) errors.

Starting 'Deploy to ELO Flows Worker'

1. After making your changes, trigger a build process.

2. Right-click the JAR file for the newly built component.

3. Select the option Deploy to ELO Flows Worker. The JAR file is now deployed in the flows
worker.

Result of 'Deploy to ELO Flows Worker'

39 Programming for ELO

A pop-up at the bottom edge of the screen indicates that deployment was successful.

1. Refresh the ELO Flows interface.

Ending 'Deploy to ELO Flows Worker'

1. Single component deployment is completed after this. Start the deploy process again if you
make changes to the component later.

Continuous deployment: Hot Deployment to ELO Flows Worker

The Start Hot Deployment to ELO Flows Worker option starts a background process that monitors
changes to the component. After starting, first, a message appears in the terminal indicating that it
is waiting for changes. If you make a change to the component now, the change is automatically
built and deployed in Karaf after saving.

Please note

So that you can check what for changes you're deploying, the AutoSave function of VS Code
has to be disabled.

Starting 'Hot Deployment to ELO Flows Worker'

1. Right-click the JAR file for the newly built component.

2. Select the option Hot Deployment to ELO Flows Worker.

40 Programming for ELO

Result of 'Hot Deployment to ELO Flows Worker'

The JAR file is now automatically deployed in the flows worker on every save.

1. Refresh the ELO Flows interface.

Ending 'Hot Deployment to ELO Flows Worker'

1. In the VS Code terminal, press CTRL + D then ENTER to end automatic deployment.
41 Programming for ELO

Debugging
Debugging is performed directly via Java remote debugging in VS Code. This is possible as the
flows workers and Java extensions for VS code support Java remote debugging.

Requirements for debugging

In the default installation of ELO Flows via the ELO Server setup, the debugging function is
disabled. Debug mode in the flows worker (local Apache Karaf) has to be enabled manually.

The flows worker (Apache Karaf) has to be running and available locally in debug mode.

Enable debug mode

1. Stop the service set up by the ELO Server Setup.

Information

If you installed Apache Karaf manually, this step is irrelevant.

2. Next, start Karaf in debug mode with the following command in the command line:

C:\ELOprofessional\servers\ELO-Karaf-1\bin> .\karaf debug

Start the debugger in VS Code

1. Deploy the latest version of the component in Apache Karaf.

2. Start Apache Karaf in debug mode.
3. Press F5.

If the status bar is orange, this indicates that the debugger has started correctly and successfully
connected to Karaf.
42 Programming for ELO

Debugging

1. Set breakpoints as usual. The debugger will stop at these points when running a flow with
the component.

End debugging in VS Code

1. End the debugger with the Disconnect function in the debugging toolbar.

Alternative: Press SHIFT + F5

2. Stop Karaf in the console via CTRL + D.

3. Restart the Apache Karaf service that you stopped.

43 Programming for ELO

Component configuration options

The ELO Flows components API allows you to develop custom functional components for ELO
Flows. The ELO Flows components API is largely based on Java annotations. This means that
functions to be implemented are defined with standard Java functions, Java properties, and Java
classes. These elements are subsequently annotated. This is how ELO Flows knows which
functionality is behind a developed function or class.

You can also find more information about Java annotations in general on Wikipedia > Annotation
(Java).

Detailed information about annotations and utility classes can be found in the ELO Flows Javadocs
in the sections components-api and schema-api.

Please note

To develop components with fields, ELO Flows requires a @Property annotation starting with
ELO 21.3. You can find more information in the section Component development >
Particularities of ELO Flows

You can find an overview of flow annotations in the following:

Configure interface display

• Component (@Component)
• Trigger (@Trigger, @Webhook, @Config, @Scheduled, @Synchron)
• Service (@Service, @SchemaProvider)
• Connection provider (@Create, @Destroy, @Prepare, @Refresh, @Validate)
• Input field (String) (@Property)
• Input field (int) (@Property)
• Input field (boolean) (@Property)
• Input field (Object) (@Property)
• Input field (Array) (@Property)
• Input field [Mandatory field](@Property required=true)
• Additional configuration options for an input field ( @DisplayOptions)
• Suggestions (@Lookup)
• Groups in the settings (@PropertyGroups, @PropertyGroup, @PropertyGroupRef)
• Service groups (@ComponentServices)

Configure functionality

• Connect to ELO Indexserver (@Connection, @ConnectionRequired, @Inject with the

IXConnectionIF) interface
• Link to schema provider (@DynamicSchema)
• Information (@Guide)
• Input field / property ignored (@PropertyIgnore)
•
44 Programming for ELO

Overwriting the property value, e.g. translating enum values ( @PropertyValue)

• Validation result of the method of a ConnectionProvider annotated with @Validate
(ValidationResult)

Information

Use the IXConnectionIF interface for the connection to the ELO Indexserver.

Components that still use the outdated implementation, IXConnection, will continue to
work, but we recommend using the IXConnectionIF interface.

Tool classes/utility classes

Tool classes or utility classes that can also be used:

• Wrapper class for the result of a trigger or service, e.g. canceling a flow ( ActionResponse)
• Proxy object for sending and receiving files between flow nodes (flow file)