Concepts

Think about a process where the purchase of an asset must be approved by a line manager. The line manager may want to ask the requester to provide more details why the asset is required. Therefore he'd add a side task to ask the requester for clarification. This optional interaction should not be wired into the main approval process as it obfuscates the most used business path. But it could be available as an optional side task that the line manager can start and then gets executed within the current process context.

In Axon.ivy processes with side tasks can be invoked through Triggers or Signals.

Triggers

It is possible to trigger a strictly defined process. Strictly defined means that the calling process knows the target process as it has to be implemented in the same or a required project. RequestStart events can be declared as trigger-able. While the Trigger activity is used to actually trigger such a start.

So in the request verification front end, a manager could simply trigger the process to enrich the request with a trigger call activity.

Signals

Most of the time you'd prefer a looser coupling between processes. This could be accomplished with Signals. A process that wants to integrate other processes simply fires a signal when a certain state within the process is reached. Multiple other processes in the same application could listen to this signal and all of them will be executed as soon as the signal is fired. A dependency between the firing and listening processes is not required.

As example think of an employee that starts to work in a company. When the employee is registered from HR, other processes can setup the environment for this employee. An IT responsible will setup a new desktop workstation while an office administrator will get the personal keys for the employee. To do this tasks in parallel and loosely coupled signals are the first choice. The IT- and the office-process could listen to employee entry signals fired by the HR process.

A real world agile process execution can touch many different processes. But still the history and the context must be clear for anyone who is involved in a task. So the workflow needs to know whether an invoked process belongs to the invoking case. Or if the invoked process belongs to a completely new case.

The entity that can glue multiple process cases together is the Business Case. All cases and tasks that belong to the same Business Case are presented to the user of a workflow screen as related cases. Therefore, triggerable- and signalable-process start must define whether they belong to the same Business Case as the invoking process case. This can be done with a simple configuration on these starts. See the SignalStart and TriggerStart inscription for details.

You can also use the Public API to attach the current case to an existing Business Case.

if (in.departement.equals("HR")) // evaluate attachment by runtime conditions
{
  ivy.case.attachToBusinessCase(in.callerCaseId)
}

For workflow front end developers there exists API to list all tasks or cases of a Business Case. So showing the involved cases and tasks to a workflow user is a simple implementation. For more details see the Public API of ch.ivyteam.ivy.workflow.businesscase.IBusinessCase.

ivy.case.getBusinessCase().getActiveTasks(); // get involved tasks that are active
ivy.case.getBusinessCase().getTasks(); // get all involved tasks

A long running process could get into the situation that there are many open tasks that have to be done by human users. But eventually the environment of the case changes and it does no longer make any sense to accomplish the open tasks. For instance think about a car leasing process. If the customer decides shortly before contract signing that he requires leather seats instead of the furnished ones, the car will get more expensive. So the whole credit assessment process has to run again and open tasks become obsolete.

A UserTask can support abortion by listening to a signal. The UserTask activity can subscribe to an abortion signal by adding a Signal Boundary Event on it. When the signal, that the credit amount of the car changed, is fired from another process the listening UserTask will be aborted. And the process continues at the Signal Boundary Event. Classically after the Signal Boundary a clean up process follows.

Often an initial larger process starts by gathering data that is later processed and enriched. This data is typically business relevant domain data that can be recognized by domain experts that contribute to the process. Think of bank employee that grants credits. The data for his processes could look like this when simplified:

Figure 9.1. Data class of a credit request

To store this kind of data Axon.ivy provides a simple repository that is called Business Data. This stored data can then be accessed by multiple processes instances during the lifetime of a long living complex process. The repository provides access to the data with simple store and load functions similar to well known other repositories such as the EntityManager from JPA. But in comparison to JPA and similar technologies this repository can be used without any database or environment configuration.

CreditRequest creditRequest = ivy.repo.find(in.businessDataId, CreditRequest.class); // load a CreditRequest from the Business Data Repo
creditRequest.amount = 30000; // modify a field
ivy.repo.save(creditRequest); // save the modified CreditRequest back to the Repo.

By annotating a data class with the @BusinessCaseData annotation, all values of the annotated data class are automatically associated with the context of the current Business Case. The data is then shared and accessible from all processes belonging to the Business Case. Multiple data classes of different types can be used inside a Business Case.

Running business processes typically generate highly valuable data, that could influence critical business decisions. Based on the stored data you will typically want to visualize KPIs on a management dashboard. In our credit sample, you may want to visualize the aggregated sum of all open credits. The data in the Business Data repository is stored in form that is easily accessible and explorable with a tool like Kibana.

Figure 9.2. Kibana visualizing the total of the requested credit volume

Real world BPM projects have shown that big processes tend to get increasingly complex and need to be split up into huge process landscapes, which leads to an intransparent main process flow. Users of the process often do not see how their work contributes to the bigger business process and therefore great opportunities for improvements are not taken. There is also a big need for a unique view of adaptive case operations that can be used by process contributors. Like an overview of optional tasks that a clerk can start at any time.

The Case Map addresses the needs for flexible and agile Business Cases by providing a clear and simple view on the main process and its execution. With the Case Map you can easily orchestrate the main flow of processes and the business can identify and track the stages where a running process instance is.

Figure 9.3. Case Map of a credit lending process

A Case Map is divided into stages (in the sample above the stages are: Identification, Credit rating and Approval). Each stage defines a certain phase in the life cycle of a business process. A stage consists of processes (e.g. "Collect personal data"). The default flow or also known as happy path is from left to right and from top to bottom. If the last process of a stage has finished the flow continues on the stage to the right of the current stage. Stages typically have a name and icon. The idea is to reuse this icons in Workflow UIs and processes to give the end user a hint in which stage the current Business Case is.

Figure 9.4. Actual stage of a Business Case displayed in the portal

Besides processes a stage of a Case Map can contain Sidesteps (e.g. "External solvency service" in the Case Map above). Sidesteps can be started manually by the workflow user during the ongoing Business Case. A typical Sidestep could be a process which aborts the business process (e.g. abort request). The use of Sidesteps can reduce the time spent on technical round trips, for modeling rare and costly edge cases.

Figure 9.5. A Sidestep "External solvency service" which can be started in the portal

The dependencies between Case Map, Business Cases and Business Data are as follows: Processes started inside a Case Map create new cases inside the Business Case, which themselves contain tasks for the users. Data between processes can be easily shared using Business Data. A Business Case can be attached to a Case Map, which in turn controls the flow of the processes.

Figure 9.6. The relationship between Business Case, Business Data and Case Map.

To reiterate: signals and triggers can be used to loosely respectively tightly couple different processes. The innovative Case Map brings order in to chaos of spaghetti BPM. A domain expert always has a simple graphical view on the Business Case where he contributes to. The Case Map empowers the domain expert to steer the process execution by starting optional Sidesteps or gracefully skipping large parts of the pre-modeled standard flow.

The Case Map gives the developer and the user a common language to talk about a complex process landscape. The Case Map can be read and understood by anyone that contributes to the process without an introduction. This brings back the old BPM ideas that stood the test of time.

A Signal can be sent programmatically and consists of a Signal Code and optional signal data.

import ch.ivyteam.ivy.process.model.value.SignalCode;

// send simple signal
ivy.wf.signals().send("datarepository:updated");

// send signal with reference
ivy.wf.signals().send("order:canceled:"+in.order.id);

// send signal with signal data
ivy.wf.signals().send(new SignalCode("user:created"), in.employee.name);

Signals can be received by Signal Boundary Events and Signal Start Events. Inscribed signal patterns can contain wildcards (*). Signal Boundary Events can react to a signal pattern containing macros.

order:canceled:<%=in.orderNr%>

user:created:*

Signals can be traced by either using the Designer Workflow UI or the JSF Workflow UI both Workflow UIs make use of the Public API for Signals (ivy.wf.signals()).

The first case of a process always acts as Business Case (Figure 9.7, “Initial Case”). If later an additional process case is attached to this initial case, this first initial case will be copied and treated as Business Case ((Figure 9.8, “Multiple Cases”)).

Figure 9.7. Initial Case

Figure 9.8. Multiple Cases

The fluent workflow query API makes queries against all existing tasks and cases possible. The queries can be written in a SQL like manor.

import ch.ivyteam.ivy.workflow.query.TaskQuery;
import ch.ivyteam.ivy.workflow.ITask;

// create a new query
TaskQuery query = TaskQuery.create()
  .aggregate().avgCustomDecimalField1()
  .where().customVarCharField1().isEqual("ivy")
  .groupBy().state()
  .orderBy().customVarCharField2().descending();
// resolve query results
List<ITask> tasks = ivy.wf.getTaskQueryExecutor().getResults(query);

To resolve all tasks that the current user can work on use the following code:

TaskQuery query = TaskQuery.create()
  .where().currentUserCanWorkOn()
  .orderBy().priority();
List<ITask> userWorkTasks = ivy.wf.getTaskQueryExecutor().getResults(query);

To execute a query an instance of a IQueryExecutor is needed. It can be retrieved trough the ivy environment variable.

// Application specific query executors can be retrieved from the application context
ivy.wf.getTaskQueryExecutor().getResults(taskQuery);
ivy.wf.getCaseQueryExecutor().getResults(caseQuery);

ivy.wf.getGlobalContext().getTaskQueryExecutor().getResults(taskQuery);
ivy.wf.getGlobalContext().getCaseQueryExecutor().getResults(caseQuery);

The API to manipulate tasks and cases is available trough the ivy environment variable.

There is a REST API available that uses HTTP, JSON (application/json) as content type and HTTP basic as authentication method. Over this interface the following services are available:

In detail the tasks are going to more technical task states inside of a task switch element. After a task reaches a task switch it is in state READY_FOR_JOIN. As soon as all input tasks have arrived at the task switch the state of all input tasks are switched to JOINING and the process data of the tasks are joined to one process data that is used as start data for the output tasks. After joining the input tasks are in state DONE and the output tasks are created in state SUSPENDED.

If a user resumes a task with an user dialog and then the session of the user timeouts then the task state is set back to state SUSPENDED and the process of the task is set back to the task switch element.

A User Task is the combination of a Task Switch Event and a User Dialog. When the user start working on a normal Html User Dialog the task changes its state to RESUMED. In case of an 'Offline Dialog' the task state is not changed before the user submits the task form. Then the state changes from SUSPENDED to RESUMED. Subsequent steps are executed until the task is finally DONE. See also “Offline Tasks”.

A User Task with an attached Signal Boundary Event is listening to a signal while its task is in SUSPENDED state. If the signal has been received the task is destroyed and the execution continues with a newly created follow-up task.

There are more task states mainly for task synchronisation, error handing, intermediate events, or user aborts. To learn more about task states see enumeration ch.ivyteam.ivy.workflow.TaskState in public API.

How is a component looked up? For the lookup of components at runtime, the so-called case scope is crucial. The case scope is determined by the project, in which the current case was started, e.g. where the start of the running business process was invoked. All component look-ups as well as configuration and content management references are processed within the case scope, i.e. the look up of such artifacts always starts at the project that defines the case scope.

Example: The Acme Web shop

As an example, imagine a web shop application. It contains the following (generic) business process:

The main process itself (Order) and each of the depicted sub processes (DoOrder, ProcessOrder, Shipment) are defined in own projects. All of those projects together form a (generic) web shop application, depicted below. The web shop project contains the business process and it's start; the Frontend project contains the DoOrder sub process; the backend project contains the ProcessOrder sub process; the Shipment project contains the Shipping sub process.

In this scenario, regardless of the task that is currently being executed (customer, back office, shipping), the case scope will always be the web shop project, because the business process is started from there.

We now define an additional project, Acme web shop. The new project is dependent on web shop and the intention is to bundle all Acme-specific overrides and adoptions in this project. The already existing projects plus this new project form together a more specific and customized Acme web shop application, with the following project dependency tree:

If the main business process is copied from the web shop project to the Acme web shop project, and if it is ensured that the process request is issued through the Acme web shop project instead of the web shop project, then all tasks of an order case will consequently have Acme web shop as their case scope.

Knowing this, we can now specifically override and redefine Content Objects, Configuration entries, Rich Dialogs or Sub Processes from the original generic web shop application by redefining them inside the Acme web shop project. Afterwards, whenever a business process with case scope Acme web shop is started, then the overridden artifacts and components will be used instead of the original ones, due to the case-scope based lookup mechanism.

General Definition

The following figure illustrates the adaption of an application with overrides in a general way:

Figure 9.9. Adapting a generic application with overrides

It can be seen that multiple adoptions (Client A, Client B) may be created for a generic main project. Also, each adaption may override different components.

Because Request 1 and Request 2 have different cases scopes, Request 1 (issued through the Client A project) will use the overridden Rich Dialog x.B' instead of the original x.B; Request 2, however, will use the original x.B Rich Dialog, because there is no redefinition within the case scope of the Client B project. Likewise the invocation of the Sub Process y/Q will result in the execution of the override y/Q' in Request 2, and the execution of the original y/Q in Request 1.

Note

If it should happen that the business process m/P2 is executed through the main project directly, then no overrides will be applied at all. Since such a "direct" invocation normally results in an unwanted case scope, it should be prevented. The easiest way to do so is the usage of a process facade as described below.

If the override mechanics are to work as intended, it must be ensured that processes are always and solely started from the adapted customer projects to ensure the proper case scope. This requires that all business processes (or rather their request start elements) must be copied to the adapter project.

To simplify this task and to reduce the work to the copying of a single file, it is recommended to employ the process facade design pattern.

Inside the main project of the generic application create a single process (e.g. Main) that holds the start elements of all the elementary business processes of the application. Factor the logic of those processes out into sub processes and call them from the facade process stubs, as illustrated below. With this approach, only one process (the facade) has to be copied to the top-level customer project.

Figure 9.10. Implementing a process facade with process stubs

The portal website, the workflow UI or whichever other means that are used to start the application's business processes should only show the processes from the copied facade process. As all the out factored Sub Processes will also be available from the adapter project, no further changes have to be made.

The Axon.ivy Overrides Editor shows the registered and active overrides for a specific project. The overrides are listed in 4 different sections: Rich Dialogs, Sub Processes, Content Objects and Configurations.

Rich Dialog and Sub Process overrides require - for technical reasons - the registration of a mapping (this is done automatically by the New Override Wizard) which maps the original component's identifier to the replacement identifier. This mapping is displayed in the Override Editor and can be deleted by selecting an entry and subsequently clicking on the delete icon in the section's tool bar. When clicking on the wizard icon in the tool bar, a new override mapping of that category can easily be added by entering all necessary information into the opening wizard.

Overrides of Content Objects and Configurations, on the other hand, do not require a renaming and an extra mapping between the original and the overriding component. They are simply created by adding a new Content Object or Configuration entry with the name of a component that already exists in a required project. At runtime, the new component will be found first and thus shadow the original value. For this type of override no special actions are available from the editor; you should use the respective editors (Content Editor and Configuration Editor) to create or delete overrides. The editor shows the overrides of that type for reasons of a centralized overview and for convenience, rather than to provide an interface to edit them.

Figure 9.11. The Override Editor

Axon.ivy Project Tree > double click on the Overrides node.

The New Override Wizard lets you create a new override. The wizard performs two tasks:

Figure 9.12. The New Override Wizard

File > New > Override

If the error code booking:failed is thrown it can be caught with following error code patterns: booking:failed, booking , *:failed . Additionally it can be caught by an empty Error Code that catches all errors.

System errors are thrown by process elements like Database Step or Web Service Call Step. Their error codes are set by default and are prefixed with ivy (e.g. ivy:error:database).

The happy path of a process can be left by throwing an error with an “Error End”. (e.g. if an approval was declined). The Error End Event throws the error to upper process level, it can't be caught on the same process level.

Error End Events can also be used to re-throw a pre-defined ivy error with a specific error that has a meaning to the business. (e.g. if a webservice is not available)

When an error happens inside of an Html Dialog the handling is slightly different than the default error handling.

Exit an Html Dialog by an Error End Element

It is possible to exit an Html Dialog by an Error End Element. This is useful to leave the happy path of the calling business process. The throwing Error End Element must be located in the Html Dialog Logic of an Html Dialog Page (not an Component).

The process elements Program Interface, Database, WebService and E-Mail throw system errors. If an exception or timeout occurs on these elements it can be caught using a matching Error Code or using a directly addressed Error Start Event. On the Error Start process element more information about the error can be accessed via the variable error and the legacy variable exception.

An “Error Boundary Event” catches errors which were thrown from the attaching activity or subprocess if the configured Error Code matches the thrown error.

An “Error Start” catches unhandled errors which were thrown in the same process or inside a subprocess if the configured Error Code matches the thrown error.

To prevent endless process execution trough an inappropriate error handling, the ivy process engine detects loops during the error handling. If the engine detects a loop the error handling will be continued on the next higher process level with the new error code ivy:error:loop, to interrupt the cycle.

Loop detection is done on error catching elements (Error Start Event and Error Boundary Event). The engine checks if there was already an identical execution of the catcher at this process level. Identical means: Same process request, same throwing element (including its process callstack) and same catching element (including its process callstack).

Lets illustrate this with two use cases:

A Project Error Process catches uncaught errors from the whole project. The name of a Project Error Process must start with Error and has to reside in the top-level process group Processes. It can contain one or more Error Start Events.

The error object provides the following information about the error that was caught:

For more information see the Public API of BpmError

To provide an Axon.ivy extension you have to build an Eclipse plugin for the Axon.ivy Designer or Engine.

You can build your Eclipse plugin in the Axon.ivy Designer with the following steps:

You have to do the following steps to install your extensions in Axon.ivy Designer or Engine:

This section shows you how to provide a custom certificate for your Rich Dialog clients.

Licenced ULC developers may contribute their own ULC extensions to an Axon.ivy installation. This chapter explains how custom ULC widgets can be included by packing them into a Axon.ivy Rich Dialog Client Extension.

Rich Dialog Clients are using a technology called Java Web Start. Java Web Start caches all libraries it downloads from Axon.ivy. This can cause conflicts if you are developing and do not increase the version of your client side classes if they change or if you changing certificates. The following command line tools can help to solve problems.

Use the following command line to clean the cache of Java Web Start. This will remove all cached libraries from the cache:

javaws -uninstall

Use the following command to inspect the libraries that are cached by Java Web Start:

javaws -viewer

The Designer has a built in Maven runtime that allows to start Maven with zero initial configuration effort. A local maven build can be started as follows:

Ivy Projects declare its ids and dependencies in the “Project Deployment Descriptor”. This deployment descriptor can be easily edited with the corresponding ivy editor and is stored as Maven Project Object Model (POM.xml). Therefore each Ivy Project has by default the pom.xml which is needed by maven to build it.

However advanced Maven users can adjust this default configuration and use additional Maven plugins or dependencies in the pom.xml. But not all POM entries should be modified, some are required or limited in usage in Ivy Projects:

After clicking on the search button, the search results are collected in the search result view. Double-click on matching entries and the corresponding resource is opened in its editor.

You can change the presentation layout for your search results by selecting a layout from the result view's menu:

For standard searches, only Project and Namespace grouping is available. For Rich Dialog searches the results can also be displayed as thumbnails (see next section).

Thumbnail Results for Rich Dialog Search

When searching for Rich Dialogs, the results are by default presented as thumbnails.

The result page shows the Rich Dialogs that have been found as a result of the search with a scaled image of the Rich Dialog's screen shot (if one is available) and with the Rich Dialogs simple name. The tool tip (1) offers additional information, such as the Rich Dialog's fully qualified name and the project it is located in. Rich Dialog's that don't have a screen shot are shown with a small red square (2).

Double clicking on a thumbnail will open the associated Rich Dialog's interface editor.

The size of the displayed thumbnails can be adjusted with the slider at the bottom of the view (3). Use this slider to set your preferred thumbnail size, it will be saved and used for all later thumbnail search results. The default size for the Rich Dialog thumbnails is set at 160 x 120 pixels, the minimum and maximum sizes being 16 x 12 and 480 x 360 pixels, respectively.

Tip

To automatically create a screen shot for a Rich Dialog you must first enable the feature on a Rich Dialog's interface editor (default is yes) and then open and save the Rich Dialog with the Rich Dialog editor. The screen shot will be updated every time you make changes to the Rich Dialog.

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 step or on the web service step. 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 organised 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 the same identifiers, then they are identical. Like entries, groups are as well 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 must be unique in its data cache. If two groups in the same Data Cache have the same identifiers, then they are identical.

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:

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.

In order to take into consideration changes in the data that is handled by the cache entries, it is possible to invalidate cache entries and as well 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.

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.

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

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);
 }

Rich Dialogs can also send and receive SystemEvents via the broadcast mechanism. Read the section below to learn how.

By using the event broadcast mechanism in combination with the System Events framework, Rich Dialogs can receive and send system events as broadcast events.

Receiving System Events

Before the Rich Dialog can receive any events, it must register itself for the respective categories. This is done by calling ivy.rd.subscribeToSystemEvent(SystemEventCategory). Typically this registration should happen in the start method process of the Rich Dialog as shown below. Explicit de-registration is not necessary, all Rich Dialogs will automatically be unregistered as soon as their panel is unloaded (i.e. when the Rich Dialog executes a Rich Dialog End element).

Furthermore, the Rich Dialog must declare all the names of the system events it is interested in as accepted broadcast events on it's interface. The category of the system event does not matter (they are defined in the registration call as described above). However, the name of the accepted broadcast event must be exactly identical to the name of the system events that the rich dialog is interested in. Also the type of the parameter must be identical to the type of the system event's optional parameter. If names or parameter type do not match, then the system event will not be delivered.

The handling of the declared accepted broadcast events is then implemented with Rich Dialog event handler processes as usual.

Warning

Due to technical reasons, the name of an accepted broadcast event has to be a valid Java identifier. Therefore the original name of a system event may be an illegal name for an accepted broadcast event (e.g. the system event name foo.bar.baz will not be accepted because it contains punctuation). In such cases the name of the accepted broadcast event should substitute all illegal characters with underscores, e.g. foo_bar_baz for the given example)