Generate Trigger application from archetype

Overview

The best way to get started with Triggers is to use an archetype to create a project with all necessary dependencies and a preliminary structure.

Before you generate a Trigger application, you should prepare the environment. For instructions, see Prepare environment for archetype generation.

note

You may notice that the Trigger project is very similar to the Java Native Worker project

Generate project from archetype

To generate a Trigger bundle project, follow these steps:

1. Execute the command mvn clean install to send the package to your local repository

2. Create a folder to hold your bundle, for example, /user/home/my-user/code.

3. From that folder, execute the command shown below. In the -DarchetypeVersion= parameter, use the current main pom.xml version.

   mvn archetype:generate -DarchetypeGroupId=com.workfusion.wdt.trigger.archetype -DarchetypeArtifactId=trigger-bundle-archetype -DarchetypeVersion=<current archetype version>

4. Provide the following properties when prompted:

   • groupId: the group ID that identifies your project across all projects. It should follow Java package name rules, starting with a reversed domain name you control, for example, com.mycompany.mytest.
   • artifactId: the name of the JAR file without a version in Maven archetypes. You can choose any name with lowercase letters and no special characters. artifactId is used to name the folder where your project is generated and as a prefix in the names of all generated modules. For example, if artifactId is set to my-test-trigger, the following modules are generated:
     • my-test-trigger-app
     • my-test-trigger-bundle
     • my-test-trigger-implementation
     • my-test-trigger-regression
   • version: the Maven version of the project to be created. Follow simple versioning patterns like 1, 5.3, or 8.4.5. The Maven version is used to define the Trigger version.
   • package: the Java package to be used in the project. By default, Maven suggests the same value as in groupId. It is used as the package path (split by dots) in your project, for example, com.mycompany.mytest.

   Project repositories and dependencies management parameters are as follows:

   • control-tower-url: the URL of the remote Control Tower instance where the Trigger is deployed for testing. The default value is <https://instance.workfusion.com>. You can change it later in pom.xml.

   Define value for property 'control-tower-url': https://my-instance.url
   Define value for property 'groupId': com.mytrigger
   Define value for property 'artifactId': mytrigger
   Define value for property 'version' 1.0-SNAPSHOT: : 
   Define value for property 'package' com.mytrigger: : 
   Confirm properties configuration:
   control-tower-url: https://my-instance.url
   groupId: com.mytrigger
   artifactId: mytrigger
   version: 1.0-SNAPSHOT
   package: com.mytrigger
   Y: : y

5. Once you set all properties, confirm your choice:

   • If everything looks good, type Y for Maven to start building the project.
   • If something is incorrect and you want to get back to the configuration, type N to begin the property setup again.

A new project appears in a subdirectory named after the artifactId value. The new multi-module Trigger project contains all the necessary modules for preparing and importing the Trigger into an environment, as well as running integration tests from the project in a real environment.

Work with generated project

Build project

To build the project, use the following command:

mvn clean install

Perform end-to-end tests

To build the project and run the end-to-end tests, use the following command:

mvn clean install -Pregression

Skip tests

The project can be built without tests using the following command:

mvn clean install -Dmaven.test.skip=true

View project structure

tip

Files and directories in the generated project are named after the artifactId value entered during the project generation. In the text below, {artifactId} is used as a placeholder for the artifactId value.

Project contains the following modules:

• {artifactId}-app: the Spring application module
• {artifactId}-bundle: the module that assembles the Asset Bundle to be uploaded to Control Tower
• {artifactId}-implementation: the module containing the implementation of the Trigger
• {artifactId}-regression
  • {artifactId}-regression-app: the Spring application module used for the end-to-end tests
  • {artifactId}-regression-bundle: the module that assembles the end-to-end Asset Bundle
  • {artifactId}-regression-tests: the module containing the end-to-end tests that validate the Trigger on a real Control Tower instance

Configure Trigger application

The Trigger application is a standard Spring Boot application that includes some Trigger-specific configurations.

The {artifactId}-implementation module contains all Java classes that implement the Trigger logic, along with unit tests. You can start exploring it from the SamplePollingProcessor class, which is the entry point for the Trigger framework.

The {artifactId}-app module must not contain any code. It includes only the Spring Boot application configuration.

• src/main/resources/META-INF/application.yml: the configuration file for the Spring Boot application, already set for the ZooKeeper and Secrets Vault integration.
• src/main/resources/META-INF/connector/connector.yml: the configuration file for the Trigger framework containing the startup parameters for the Trigger JVM.
• src/main/resources/configs/main: the directoty for the Trigger XML files, which serve the same role as the Bot Task XML files. The sample-polling-processor.xml file is a configuration for the sample Trigger implementation.

Build Asset Bundle

The {artifactId}-bundle module uses maven-assembly-plugin to build the Asset Bundle that can be uploaded to Control Tower. This bundle contains the packaged Trigger application along with everything located in the src/main/resources directory of the bundle module.

The assembly descriptor is located in the assembly/asset-bundle.xml file.

Perform end-to-end tests

For end-to-end tests, the project uses a separate Spring Boot application. During the {artifactId}-regression-app module build, Maven copies all resources from the production application ({artifactId}-app) and performs resource filtering, so that the Spring application ID and the Maven artifact ID are changed from production to end-to-end values.

Similarly, the {artifactId}-regression-bundle module copies everything (excluding the meta-info.json file) from the production bundle ({artifactId}-bundle). It then adds the end-to-end specific meta-info.json file and the test Business Process from its src/main/resources directory.

The {artifactId}-regression-tests module contains the Java code for the end-to-end tests. The TriggerIT class is the test itself. It uses the Spoke framework to upload the end-to-end Asset Bundle to Control Tower, start the test Business Process, and check the results.

By default, all Spoke tests from the Test module are tied to the Maven verify phase and activated by the regression profile.

Before running a Spoke test, prepare the spoke-it.properties file with the target Control Tower settings. For more details about the Spoke configuration, refer to Business Process integration testing.

Apply optional features

The pom.xml file of the {artifactId}-app module contains several commented-out dependencies. You can uncomment them to enable additional features, such as the Control Tower service client or the S3 client.

Expose API

The connector.yml file, located in the {artifactId}-app module, contains the exposed parameter, which is set to false by default. It can be set to true to expose the Trigger application to external REST API calls. In this case, add the exposure-base-path property to the connector.yml file.

exposed: true
exposure-base-path: my-trigger

Thus, the base URL for the Trigger API will be https://<control-tower-instance>/connectors/my-trigger. You can now use Spring Web or WebFlux to create endpoints for the Trigger.

For example, if you use Spring Web and create a simple controller like this:

@Controller
public class MyController {
    
    @GetMapping("/")
    public String myEndpointA() {
        // ...
    }

    @GetMapping("/endpoint-b")
    public String myEndpointB() {
        // ...
    }
}

Then, the myEndpointA() method will be exposed at https://<control-tower-instance>/connectors/my-trigger/, and the myEndpointB() method will be exposed at https://<control-tower-instance>/connectors/my-trigger/endpoint-b.

info

Authentication and authorization of the exposed endpoints are your responsibility.