Trigger development
Trigger is a type of Worker that allows sending data into a Business Process (BP) and replaces a standard Start element in the Workflow designer. It can use external events, sources, or process requests from REST API, for example, reading incoming mails, messages in a queue, new files in a folder, UI requests, or data from a source via scheduled polling.
As a Trigger developer, you have tools to check the status of records sent to the BP. These tools enable the monitoring of failed records, reprocessing them, or storing them for manual processing later. The feature ensures that data readable only once will not be lost.
Trigger implementation is very similar to a Java Native Worker (JNW), but these Workers have different cores and must be implemented in separate modules.
JNW and Trigger Worker are not the same. Although they share similarities in implementation, configuration, and optional modules, they have different cores and features. Some functionality available in JNW may not work in Trigger Worker. Both are built on the Spring Framework, which provides many shared tools for creating custom modules that work with both Worker types.
If you are familiar with ODF 2, you can use Triggers as an alternative to monitors in the JNW-based project. However, Triggers offer more configuration options and a different implementation approach.
For information about Trigger as a Worker, a basic Trigger processor class implementation, available methods for sending and checking record statuses, and details on Spring application and Trigger launch configuration, refer to Trigger connector.
A table with all Trigger-related version information is available in the compatibility matrix.
Generate Trigger project or module from archetypes
Trigger has two archetype variants for generation:
These archetypes are sufficient for starting Trigger development but serve different purposes. The first provides the essential minimum setup, while the second includes a complete set of AI Agent bundle project with integration testing and package modules.
Each archetype contains a basic processor implementation with comments explaining the class structure and methods used for record handling.
The archetypes are aligned with JNW archetypes, making the development process within the JNW approach easier to understand and apply.
Trigger Worker archetype
The process for creating a project from trigger-worker-archetype is described on the Trigger Connector page. This section explains how to use the result of this archetype.
Generating a project from this archetype produces a single-module project with minimal dependencies, configuration, and classes. Both application configuration and Trigger implementation are stored in one module.
This approach is suitable when an AI Agent bundle project already exists, and a Trigger needs to be integrated into it. You can use the archetype to generate a module inside an existing project or create a standalone one to integrate as a dependency. In this case, the Trigger does not require a separate bundle module to package it into a zip file or include additional integration tests. The new module can be integrated into the existing bundle module, making the Trigger available for testing within the existing integration testing setup.
Trigger bundle archetype
For creating a project from trigger-bundle-archetype, the description of generated modules, build process, and integration testing steps refer to Generate Trigger application from archetype.
After generating a project from this archetype, you receive a ready-to-deploy bundle, which is a good start for a standalone project or a reusable one.
The archetype includes not only the basic Trigger dependency but also the Worker Development Toolkit (WDT) BOM with additional modules and dependencies that can be used during development.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.workfusion.wdt</groupId>
<artifactId>wdt-bom</artifactId>
<version>${wf.worker-development-toolkit.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
WDT provides common and JNW-based modules. In the case of Triggers, only the common modules should be used because JNW modules depend on JNW core libraries that are incompatible with Trigger ones. Be careful when adding WorkFusion dependencies; they must not include the JNW library. Otherwise, unexpected behavior or errors may occur.
Modules
Several modules can be used with Trigger Worker. These modules provide access to some specialized services such as Secret Storage, S3 Storage, or Control Tower services
Some additional modules can be written for JNW. In such cases, the java-native-core dependency must be excluded.
Modules that start with wdt-commons-* are available for both Worker types without additional exclusions.
module-secrets
The module provides access to Secret Storage through a simple API. To use it, add the dependency to the application pom (or the ${artifactId}-implementation module in trigger-bundle-archetype):
<dependencies>
<dependency>
<groupId>com.workfusion.spa.java.native.worker</groupId>
<artifactId>module-secrets</artifactId>
<version>${wf.module-secrets.version}</version>
<exclusions>
<exclusion>
<groupId>com.workfusion.spa.java.native.worker</groupId>
<artifactId>java-native-worker-core</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
After adding the dependency, you can access the SecretService bean that allows operations on entries in the Secret Storage.
You can access configuration parameters from Secrets Vault by default using standard Spring mechanisms, for example, the @Value annotation. This module is required only when accessing custom secure entries.
The available SecretService methods are as follows:
| Method | Description |
|---|---|
createSecret(String alias, String key, String value) | Creates a new secret with the passed data. Review logs if issues occur; relevant logs are recorded at the WARN level. |
updateSecret(String alias, String key, String value) | Updates a secret identified by alias with new key and value data. Review logs if issues occur; relevant logs are recorded at the WARN level. |
deleteSecret(String alias) | Deletes the specified secret. Review logs if issues occur; relevant logs are recorded at the WARN level. |
resetSecret(String alias) | Resets a secret value with a random string using RandomStringUtils.random. Review logs if issues occur; relevant logs are recorded at the WARN level. |
getSecret(String alias) | Retrieves a secret object by secret alias. Returns Optional<SecretDto>. |
wdt-common-s3-client
This module provides access to S3 Storage via a simple API. To use it, add the dependency to the application pom (or the ${artifactId}-implementation module in trigger-bundle-archetype):
<dependencies>
<dependency>
<groupId>com.workfusion.wdt.common</groupId>
<artifactId>wdt-common-s3-client</artifactId>
</dependency>
</dependencies>
This dependency provides an S3Service bean, which is a wrapper around AmazonS3 service. You can also get access to the original AmazonS3 service and continue working with it.
The available S3Service methods are as follows:
| Method | Description |
|---|---|
getBucket(String bucketName) | Returns S3Bucket associated with the specified bucket name. |
getObjectByUrl(String url) | Retrieves an object from S3 as a byte array by URL. |
parseUrl(String urlString) | Parses a provided URL from String into an S3Url object. |
moveObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey) | Moves an object from a source bucket to a destination bucket. |
copyObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey) | Copies an object from a source bucket to a destination bucket. |
deleteObject(String bucketName, String key) | Deletes an object from a bucket. |
getAmazonS3() | Returns the configured Amazon S3 client associated with the current service. |
For working with S3Bucket, the following methods are available:
| Method | Description |
|---|---|
getBucketName() | Returns the current bucket name. |
get(String s3key) | Retrieves an object by key from the current bucket. |
getObject(String s3key) | Retrieves the S3Object object for a given key from the current bucket. |
doesObjectExist(String s3key) | Checks whether an object with the specified key exists in the current bucket. |
put(byte[] data, String s3key) | Uploads a new object to the current bucket. |
put(S3PutRequestBuilder builder) | Uploads a new object using a builder. |
delete(String s3Key) | Deletes the specified object from the current bucket. |
listObjects() | Lists summary information for objects in the bucket. |
copy(String sourceKey, String destinationKey, CannedAccessControlList cannedACL) | Copies a source object to a new destination within the current bucket. |
getUrl(String s3Key) | Returns the URL for the specified object in the current bucket. |
generatePresignedUrl(String s3Key, Date expiration) | Returns a presigned URL for the specified object in the current bucket. |
The version of this module is provided by wdt-bom.
wdt-common-control-tower-services
The module provides access to the Control Tower Server via a simple API. Add the dependency to the application pom (or the ${artifactId}-implementation module in trigger-bundle-archetype):
<dependencies>
<dependency>
<groupId>com.workfusion.wdt.common</groupId>
<artifactId>wdt-common-control-tower-services</artifactId>
</dependency>
</dependencies>
After you add the dependency, the ControlTowerTaskService and ControlTowerBpService beans become available, allowing task initiation and retrieval of BP details.
ControlTowerTaskService provides the following methods:
| Method | Description |
|---|---|
startTask(String campaignUuid, String mainData) or startTask(String campaignUuid, String mainData, String author) | Calls the Control Tower API to start a task or BP with new input data. |
ControlTowerBpService provides a single getBpDetails(UUID bpUuid) method that returns Optional<BpDetails>.
The version of this module is provided by wdt-bom.
Trigger unit and integration testing
For testing Trigger Worker, use the Trigger Connector testing framework. This library provides an API to run Trigger Worker and queues in memory. It also includes modules for mocking S3 and Secret Storage during testing.
Integration testing uses the Spoke library, similar to ODF 2 and JNW approaches.