Try a Micro-Integration

This tutorial walks you through deploying a Transform Processor end to end. The Transform Processor moves and transforms messages between two event broker service endpoints. It has no external vendor dependency, which makes it the simplest way to learn the configuration and deployment model that applies to all Micro-Integrations.

After completing this tutorial, you will be able to:

  • Describe the structure and purpose of the application.yml file.

  • Configure a Micro-Integration for both source and target endpoints.

  • Deploy a Micro-Integration as a container or JAR.

  • Verify that the Micro-Integration is running and data is flowing.

Prerequisites

Because this Micro-Integration has no external vendor dependency, this tutorial's prerequisites are minimal. Before you begin, make sure you have:

  • a running Solace event broker and its connection credentials. If you don't have one, start a free trial of Solace Cloud to get an event broker service.

  • Docker (or Podman), if you want to deploy the Micro-Integration as a container, or Java 17 or later, if you want to deploy it as a JAR.

  • the Transform Processor container image or JAR file, downloaded from the Integration Hub.

  • names for a source queue and a target topic on your event broker. This tutorial uses tutorial/source-queue and tutorial/target-topic as examples; you can choose your own names.

Configure the application.yml File

The Transform Processor ships with a sample application.yml file. This section builds a minimal version of that file for a single workflow, one piece at a time.

Event Broker Connection

Set the connection details for your event broker under the solace.java prefix:

solace:
  java:
    host: tcps://<broker-host>:55443
    msg-vpn: <vpn-name>
    client-username: <username>
    client-password: <password>

Replace the placeholder values with your event broker's host, Message VPN name, and client credentials. To find these values for your event broker service, select the Connect tab, expand the Connect with Java section, and click Solace JCSMP API; the connection details appear on the right-hand side of the screen. For more information, see Step 1: Connecting to Your Event Broker .

Source and Target Bindings

Each workflow needs a consumer binding (the source) and a producer binding (the target). Add the following configuration under spring.cloud.stream.bindings, using a queue as the source and a topic as the target:

spring:
  cloud:
    stream:
      bindings:
        input-0:
          destination: tutorial/source-queue
          binder: solace
        output-0:
          destination: tutorial/target-topic
          binder: solace

The 0 in input-0 and output-0 is the workflow ID; both bindings must use the same ID to belong to the same workflow. Because this Micro-Integration moves data between two points on the event broker, both bindings use the solace binder. For more information, see Step 4: Enabling Workflows.

The Micro-Integration does not provision the source queue for you. Create the queue tutorial/source-queue on your event broker before you deploy the Micro-Integration. The queue name you create on your event broker, the destination configured in this binding, and the queue name you use later when publishing a test message with Try Me! must all match exactly; double-check for extra leading or trailing whitespace, since a mismatch causes the Micro-Integration to silently fail to bind to it.

Enabling the Workflow and Adding a Transformation

Workflows are disabled by default. Enable workflow 0, and add a transformation expression that modifies the message payload:

solace:
  connector:
    workflows:
      0:
        enabled: true
        transform:
          enabled: true
          source-payload:
            content-type: application/json
          target-payload:
            content-type: application/json
          expressions:
            - transform: "target['payload']['tutorial'] = #concatString(source['payload']['tutorial'], ' (transformed by message-processor-tutorial)')"

This expression appends (transformed by message-processor-tutorial) to the tutorial field of the JSON payload, so you can confirm that the transformation ran when you verify the deployment. The transform.enabled setting is required; without it, the Micro-Integration silently ignores the preceding expressions. (This requirement applies only to some Micro-Integrations. Check your Micro-Integration's sample application.yml file for a solace.connector.default.workflow.transform.enabled entry; if it's not there, your Micro-Integration doesn't need this setting.) Because this expression reads and writes a JSON payload field, source-payload.content-type and target-payload.content-type must both be set to application/json. For more information about writing expressions, see Mapping Message Headers and Payloads.

Complete File

Combining the preceding pieces, your application.yml file should look like this:

spring:
  cloud:
    stream:
      bindings:
        input-0:
          destination: tutorial/source-queue
          binder: solace
        output-0:
          destination: tutorial/target-topic
          binder: solace

solace:
  java:
    host: tcps://<broker-host>:55443
    msg-vpn: <vpn-name>
    client-username: <username>
    client-password: <password>
  connector:
    workflows:
      0:
        enabled: true
        transform:
          enabled: true
          source-payload:
            content-type: application/json
          target-payload:
            content-type: application/json
          expressions:
            - transform: "target['payload']['tutorial'] = #concatString(source['payload']['tutorial'], ' (transformed by message-processor-tutorial)')"

For a deeper explanation of the application.yml file's structure, including multi-binder syntax for more advanced configurations, see Understanding the application.yml File.

Deploy the Micro-Integration

Deploy the Micro-Integration as a container or a JAR. Both methods load the application.yml file you built in the previous section.

Deploy as a Container

  1. Choose a working directory, then create a config subdirectory inside it.

  2. Save the application.yml file from the previous section into that config subdirectory.

  3. From that same working directory, run the following command:

    docker run -d --name my-message-processor \
-p 8090:8090 \
-v `pwd`/config/:/app/external/spring/config/:ro \
--env SOLACE_CONNECTOR_SECURITY_USERS_0_NAME=healthcheck \
--env SOLACE_CONNECTOR_SECURITY_USERS_0_PASSWORD=healthcheck \
--healthcheck-command="curl -X GET -u healthcheck:healthcheck --fail
localhost:8090/actuator/health" \
solace/pubsubplus-processor-message-transformer:<version>

Replace <version> with the version of the Micro-Integration you downloaded. This command exposes the Micro-Integration's management port (8090) to the host, mounts your config directory, and configures a healthcheck user (security is already enabled by default). For more information about these settings, including the Podman equivalent of this command, see Deploying Your Self-Managed Micro-Integration .

Deploy as a JAR

To run the Micro-Integration from the command line instead:

  1. Choose a working directory containing the JAR file you downloaded.

  2. In that directory, create a config subdirectory and save your application.yml file into it.

  3. From that same working directory, run the following command:

    java -jar pubsubplus-processor-message-transformer-<version>.jar --spring.config.additional-location=file:config/

Replace <version> with the version you downloaded.

Verify the Micro-Integration

Check the Health Endpoint

Confirm the Micro-Integration started and connected to the event broker by querying its health endpoint:

curl -u healthcheck:healthcheck http://localhost:8090/actuator/health

A healthy Micro-Integration returns:

{"groups":["liveness","readiness"],"status":"UP"}

If the status is not UP, see Step 7: Configuring and Using the Health Endpoint for troubleshooting guidance.

Subscribe to the Target Topic

Open Try Me! in Broker Manager, connect to your event broker, and in the Subscriber panel, subscribe to the target topic, tutorial/target-topic. Subscribe before you publish your test message in the next step; a topic subscription receives only messages published while it's active, so subscribing after publishing misses the message.

If you launch Try Me! directly from your event broker service, its connection URL is already populated; you only need to supply the client username and password. This URL differs from the one you used in your application.yml file: Try Me! runs in your browser and connects over WebSocket (wss://), while the Micro-Integration connects over secure TCP (tcps://).

Publish a Test Message

Using the Publisher panel of Try Me!, publish a test message directly to the source queue:

  1. Set the destination type to Queue and enter tutorial/source-queue as the queue name.

  2. Enter the following JSON message text:

    {"tutorial": "source message"}

  3. Click Publish.

Publish directly to the queue, not to a topic. Since tutorial/source-queue has no topic subscription, a message published to a topic never reaches it.

Confirm the Transformation

In the Subscriber panel, the message you published should now appear with its tutorial field modified:

{"tutorial": "source message (transformed by message-processor-tutorial)"}

This confirms the full path: the Micro-Integration consumed your message from tutorial/source-queue, applied the transformation expression, and published the result to tutorial/target-topic.

Next Steps

You've now configured, deployed, and verified a Micro-Integration using the same model that applies to every Micro-Integration. For more advanced connection and binder options than this tutorial covers, see Step 1: Connecting to Your Event Broker and Step 2: Configuring the Spring Cloud Stream Binder. To apply what you've learned to a Micro-Integration that connects to an external vendor system, see Step 3: Vendor-Specific Configuration for Self-Managed Micro-Integrations to find its documentation. For a deeper dive into the application.yml file's structure, including multi-binder syntax and other advanced options, see Understanding the application.yml File.