Extensions
This chapters shows how easily a process or the Axon Ivy Engine itself can be customized with your own logic.
Extendible Process Elements
Axon Ivy comes with four generic process elements that can be used to address particular execution behavior requirements none of the standard process elements can fulfill.
All generic process elements contain a tab in which a Java class can be selected. The Java class implements the actual execution behavior. Some standard implementations are shipped with the Axon Ivy core, and with these elements developers are able to specify their own implementation as part of the project.
These generic elements are:
- Program Start
Triggers the start of a new process upon an (external) event.
- PI (Programming Interface) Activity
Executes generic Java code (may interact with a remote system).
- Wait Program Intermediate Event
Interrupts process execution until an (external) event occurs.
Tip
Sample implementations of custom process elements can be found on GitHub in our open source repository, e.g. https://github.com/axonivy/bpm-beans
New Bean Class Wizard
With the New Bean Class Wizard you can create a Java class that implements the interface of one of the extendible process elements. Optionally, it can also generate a UI editor for the configuration of the event for the corresponding bean. The generated Java class contains example code on how to implement the Java bean.
Accessibility
Process Editor > inscribe > Inscription Mask > … > Java Class to execute >
Provide your own process elements
Instead of using the generic extendible process element with your Java class, you can go one step further and implement your own process elements, available in the process editor palette.
To implement your own process elements in an Eclipse bundle <extensions-bundles> you need to implement two extension points, one for the execution (Engine) and one for the user interface (Designer):
- IBpmnProcessElement
You need to specify a name, an executor class. Optionally, you can also specify what kind of process element you are providing (default is Activity), and a validator class.
- IBpmnProcessElementUi
This extension point allows you to define a visual representation of your custom process element in the Axon Ivy Designer. By adding custom tabs to the Inscription mask you can also make your process element configurable. The configuration can be stored in a String. The name must be specified and match the name defined in your IBpmnProcessElement implementation. It is recommended to add an icon.
You need to implement both process element extension points in order to have a working process element.
Tip
Sample implementations of custom process elements can be found on GitHub in our open source repository, e.g. https://github.com/axonivy/bpm-beans
Axon Ivy extensions bundles (Eclipse plugin)
In order to provide an Axon Ivy extension for the Designer or Engine you need to provide it as an Eclipse plugin.
Development
You can create your own Eclipse plugin in the Axon Ivy Designer by following these steps:
Start Axon Ivy Designer
Switch to the Plug-in Development Perspective. Menu: Window > Open Perspective > Other… > Plug-in Development
Create a new Plug-in Project. Menu: File > New > Project …. In the appearing dialog:
Choose Plug-in Project.
Press Next.
Enter a project name.
Press Next.
Enter the Plug-in Properties.
Property
Description
Example
Plug-In ID
Identifier of the plugin. Must be unique. This identifier must be specified in the
*.extensions
file in the bundle attributes.ch.ivyteam.ivy.example
Plug-In Version
The version of the plugin.
1.0.0
Plug-In Name
The name of the plugin. The name is used for documentation only.
Example
Plug-In Provider
The provider of the plugin. The provider is used for documentation only.
Axon Ivy AG
Press Finish.
In the appearing editor click on the Extensions tab. In the section All Extensions press the Add button. Un-tick the box Show only extension points from the required plug-ins. From the list of extension points choose the one you want to provide an extension for. Press the Finish button. You may need to confirm adding a new plug-in dependency. Save the changes.
Select the added extension point from the list in the section All Extensions. Select the added sub entry. In the section Extension Element Details click on the link class*.
A New Java Class dialog appears. Specify the name of your extension class in the Name text field and the package name in the Package text field.
Write your extension class by implementing the extension point interface (see Extension Point Reference)
Switch back to the META-INF/MANIFEST.MF file editor. Choose the Overview tab and click on the link Export Wizard. As Destination Directory choose the
dropins
directory of your Axon Ivy Designer or Engine installation. Press the Finish button. Your plugin is created in thedropins/plugins
directory.
Installation
Follow these steps to install your extensions in an Axon Ivy Designer or Engine:
Stop the running instance (if applicable).
Copy your plugin (bundle) that contains your extension classes to the
dropins
directory inside the Axon Ivy Designer or Engine installation directory.Start the Axon Ivy Designer or Engine.
Tip
If your extension is not active as expected, consult the dropins/README.html
.
Extension Point Reference
Axon Ivy supports the following extension points:
- IServerExtension
A Server extension can be used to start and stop your code when the Axon Ivy Engine is started or stopped. Server extensions can be accessed from Process Start Event and Process Intermediate Event Beans and also from every process element using the ivy.extensions environment variable.
- IIvyProjectClassPathExtension
Adds libraries or classes from bundles to the Axon Ivy project class path. This extension point allows to add libraries or classes to the compile and the runtime class path. This is useful if you want to provide your own classes in a eclipse bundle and want to access these classes from IvyScript or use them as Program Interface (PI), Start Event, Intermediate Event and Call&Wait bean.
- IBpmnProcessElement
Extension point to define the execution part of your custom process element. The code provided in the executor class will be run on the Axon Ivy Engine during process execution. The user interface part to configure your element can be implemented with extension point IBpmnProcessElementUi. An optional validator class can be specified that will be run during execution as well as project validation in the Axon Ivy Designer.
- IBpmnProcessElementUi
Extension point to define the user interface part of your custom process element. You only need to provide a name matching the name specified in the IBpmnProcessElement implementation. Optionally, you can specify an icon, a short name, a description, additional editor tabs, add new palette groups, and add the element to a specific group at a specific position.