Miscellaneous

This chapter deals with several concepts and features that are integrated into Axon Ivy to leverage user convenience and experience.

Debug Java Classes

You can debug java classes in the Axon Ivy Designer, by uncomment the line -agentlib:jdwp=transport=dt_socket,server=y,address=8001,suspend=n in the AxonIvyDesigner.ini file. After a restart you’re able to start a Debug session by add a new Remote Java Application debug configuration. For more information, check out How can I debug my Java class in an Axon Ivy Designer?

Data Caching

Axon Ivy offers a feature to store data temporarily into a data cache in the engine’s memory. If you want to read data that stays unchanged for some time, you do not need to re-read the data every time you need to access it. If this data is read by long-running queries from a database or by calling a slow web service, you can gain a lot of performance by caching this data. The Database Activity and the Web Service Call Activity natively support Data Caching (see the Data Cache Tab for more information), for other data, you can access the Data Cache API by IvyScript.

Caches

Data that is cached is always stored in a data cache entry. This can be the result of a database query or of a web service call if you use the Data Cache Tab on the Database Activity or on the Web Service Call Activity. But you can also store any arbitrary object into a data cache entry by using the Public API. Entries are identified by a textual entry identifier.

Entries are organized into groups. An entry always belongs to exactly one group. You cannot store the same entry in more than one group. In other words, the identifier of an entry must be unique in its group. If two entries in the same group have identical identifiers, they are identical.

Like entries, groups are identified by a textual group identifier. Use groups to store cache entries with similar data. This simplifies the invalidation of related data, see chapter invalidation below.

A Data Cache is a container for multiple groups. The identifier of a group has to be unique in its data cache. If two groups in the same Data Cache have the same identifiers, then they are identical.

../../_images/data-cache.png

Data Caches always have a scope. A scope defines the boundaries of a specific Data Cache and as well the life cycle of the Data Cache depends on its scope:

Scope

Type of cached data

Multiplicity of Data Cache

Data Cache life cycle start

Data Cache life cycle end

Appl icat ion

Global data that is related to the application

One per application

Application creation or engine start

Application deletion or engine stop

Envi ronm ent

Global data that can vary for different environments, e.g. if you are using tenants or different configuration s

One per application and environment

Environment creation or engine start

Environment deletion, application deletion or engine stop

Sess ion

Data that is related to interactions within the actual session

One per session and environment

Session start

Session end

../../_images/data-cache-scopes.png

Access and Life Cycle

Cache entries and groups are created the first time they are accessed - the first time the process step with the data cache entry is executed - and they are destroyed when the scope of cache entries or groups reach the end of their life cycle. For the scope Session this is the logout of the user of the session or the session timeout, for the scopes Application and Environment this is when the application is terminated or inactivated.

Cache entries and groups are resolved by their identifiers. You can put different cache entries into one group by using the same group identifier for all entries. You can use the same data cache entry for multiple steps by using the same group and the same entry identifier for all entries. This is very useful for data that almost never changes, you can load the data into the cache once at the beginning of the scope’s lifetime and read it from the cache from every step in all processes thereafter.

Invalidation

To take into consideration changes in the data handled by the cache entries, it is possible to invalidate cache entries and whole groups either on request or after a configurable period of time. Thereby, invalidation means that only the value of the data cache entry is deleted, but not the entry itself. The next time a step referring to this data cache entry is executed, the value of the data cache is loaded again.

You can invalidate an entry, a group and even the whole cache explicitly in the Data Cache Tab of inscription masks of the process steps that use data caching or by an IvyScript API call. Otherwise you may specify a period as a lifetime or fixed time of day for invalidation. The lifetime period starts when the group/entry is loaded the first time. A background job is responsible to invalidate entries/groups when their lifetime has ended. If you set a fixed invalidation time, the corresponding entry or group is invalidated once per day at that time. By invalidating a group, all its contained entries are invalidated and similarly invalidating the whole data cache does invalidate all groups and therefore as well all entries.

Note

How Data Caching works on an Axon Ivy Engine Enterprise Edition

An Axon Ivy Engine Enterprise Edition consists of multiple engine instances (nodes) that are running on different machines.

In an Axon Ivy Engine Enterprise Edition the Application and Environment data caches will be created on each node independently. However, if a data cache is invalidated on one cluster node either by timeout or explicitly, then it will be automatically invalidated on all other cluster nodes as well.

On the other hand, Session data caches will only be created on one node because sessions are always bound to a specific node in the cluster.

System Events

Axon Ivy offers the concept of system events. These are messages broadcasted across the Axon Ivy installation. While Axon Ivy itself (e.g. the workflow subsystem) generates events that interested participants may subscribe to (e.g. to be informed when a case is created or finished), it is also possible for implementors to define their own events and broadcast them to any component that is interested. Since this mechanism is session- and workflow independent, you can use it to implement inter-session communication (within the same Application).

Concept and general usage

System events are messages that are broadcasted across the Axon Ivy system and that will be delivered to any interested party. System events have a name and are categorized, and they may carry an optional parameter object. System events can only be sent within the same Application on an Axon Ivy Engine.

Currently two categories are defined: SystemEventCategory.THIRD_PARTY and SystemEventCategory.WORKFLOW. The category THIRD_PARTY can be used to send (and receive) system events that are generated by integrated third party applications (or processes). The category is reserved exclusively for this purpose; i.e. the Axon Ivy Engine will never generate any events of this type.

image0

The Axon Ivy system itself currently only generates events of the category WORKFLOW. Inside this category, events with the following names are generated:

  • WorkflowSystemEvent.TASK_CREATED

  • WorkflowSystemEvent.TASK_CHANGED

  • WorkflowSystemEvent.CASE_CREATED

  • WorkflowSystemEvent.CASE_CHANGED

All of those events carry a parameter object of the type WorkflowSystemEventParameter which gives access to the identifiers of the workflow objects that have been created or modified. More system defined categories and events can be expected in the future.

To send system events, client and/or third party applications must first create a SystemEvent object and then get a hold of an IApplication object, which offers the method sendSystemEvent(SystemEvent event). Only events of the category THIRD_PARTY can be sent by process applications, attempts to send system events of different categories will result in an error.

To receive system events, clients must implement the interface ISystemEventListener and must then register themselves on an IApplication object using the method addSystemEventListener(EnumSet<SystemEventCategory> categories, ISystemEventListener listener). It is strongly recommended, that the similar remove method is used, as soon as clients are no longer interested in a specific event category.

Clients should only listen to system events they know the name of, all other events should be ignored. Clients should handle received events as fast as possible, because handling will block the delivery of events to other receivers. Also the received parameter object should never be modified (it shouldn’t be modifiable in the first place), since this may affect the handling by other receivers which will consequently receive a modified event object.

In Java, the handling of system events generally results in code similar to the following:

/**
 * Registers this participant for workflow system events.
 */
 public void registerForWorkflowEvents(IApplication application)
 {
    application.addSystemEventListener(EnumSet.of(SystemEventCategory.WORKFLOW));
 }

/**
 * Unregister this participant for all system events.
 */
 public void unregister(IApplication application)
 {
    application.removeSystemEventListener(EnumSet.allOf(SystemEventCategory.class));
 }

/**
 * Implementation of ISystemEventListener.handleSystemEvent(...)
 * Events will only be delivered for the categories that this listener registered for
 */
 public void handleSystemEvent(SystemEvent event)
 {
    String eventName = event.getName();
    if ("thirdparty.mysystem.myevent".equals(eventName))
    {
        // do something
    }
    else if (WorkflowSystemEvent.TASK_CHANGED.equals(eventName))
    {
        // do something
    }
    // else: ignore event
 }

 /**
  * Distribute a new system event to all interested/registered listeners of my event.
  * MyEventParameter can be of any (serializable) type, the type is part of the event definition,
  * clients will have to cast accordingly.
  */
 public void sendMyEvent(IApplication application, MyEventParameter param)
 {
        SystemEvent event = new SystemEvent(SystemEventCategory.THIRD_PARTY, "thirdparty.mysystem.myevent", param);
    application.sendSystemEvent(event);
 }

Note

How System Events work on an Axon Ivy Engine Enterprise Edition

An Axon Ivy Engine Enterprise Edition consists of multiple engine instances (nodes) that are running on different machines.

Distribution of system events is handled in two ways on a Engine Enterprise Edition, depending on their category:

  • THIRD_PARTY system events are distributed as cluster messages across all nodes, i.e. from the node that generates the event to all other cluster nodes

  • WORKFLOW system events are generated on each cluster node in parallel and then distributed locally only

Important implementation notes:

Since THIRD_PARTY events are distributed as messages in a Cluster, all custom event parameter objects must be serializable.

Please be aware that running multiple instances of a system event sender may lead to race conditions. If you use system events for message exchange between Axon Ivy processes and/or User Dialogs and third party systems integrated via the Server Extension mechanism, you have to ensure that a certain event is only sent once. One way to solve this is that the third party system (e.g. an ESB) is attached to only one node in the cluster. Otherwise a received message from the external system may be injected into the Axon Ivy Engine Enterprise Edition system n times (once for each node) instead of being sent only once.

Update Notification

When newer Axon Ivy versions are available a dialog appears after starting Axon Ivy Designer. The dialog contains information about the new versions and where those can be downloaded.

Use the checkboxes provided on the dialog if you don’t want to see the dialog again either for the same versions or for any new versions.

If you want to check for new versions manually use the menu Axon Ivy > Check for Updates …

Note

While checking for new versions the following statistic information are sent to the update server. These information are only used to improve the product.

  • Current designer version

  • Operating system information (name, version, architecture, number of processors)

  • Java memory information (maximum heap memory, maximum non heap memory)

  • JVM (Java virtual machine) information (version, vendor, name)

  • Host information (host name, SHA-256 hashes of IP address and MAC address to identify the host without being able to read the original IP address and MAC address itself)

Eclipse Plugin Mechanism

You need a database frontend in Axon Ivy? Or editing support for any other programming or data declaration languages such as C/C++, PHP or XML? Or you have UML models to view? No problem at all.

Axon Ivy is based on the widely used Eclipse platform which offers a sophisticated plugin mechanism to integrate third-party modules. In these days, Eclipse which originally has been developed as an IDE for Java programmers evolved to a large and vibrant ecosystem and is used for a triad of different tools and systems in almost every work sector. Therefore a huge community exists that offers plugins (open source and commercial) and even web sites (Eclipse Marketplace) for browsing and searching these plugins arose in the past years.

And the conclusion, you can use all these plugins and integrate them into your Axon Ivy installation to interact seamlessly between your favorite plugin set and the built-in Axon Ivy features.

Note

Please follow the installation instructions of the specific plugin to integrate it into your Axon Ivy installation