Table of Contents

• Getting Started
  • Helpful Background Information
  • Prerequisites
  • External Dependencies
  • Adapters
  • How to Install
  • Testing
• Using this Example Project
  • Consume Message - Kafkav2 - Library - Example
• Additional Information
  • Support

Getting Started

This section is helpful for deployments as it provides you with pertinent information on prerequisites and properties.

Helpful Background Information

Workflows and processes often include logic that varies from business to business. Our Example Projects are more complex processes that include several of our modular components to build a more complete process.

While these can be utilized, you may find more value in using them as a starting point to build around.

Prerequisites

Itential Example Projects are built and tested on particular versions of IAP. In addition, Example Projects are often dependent on external systems and as such, these Example Projects will have dependencies on these other systems. This version of Apache - Kafkav2 - Library - Example has been tested with:

• IAP 2023.2

External Dependencies

Adapters

How to Install

To install the Example Project:

• Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the Supported IAP Versions section in order to install the Example Project.
• Import the Example Project in Admin Essentials.

Testing

Cypress is generally used to test all Itential Example Projects. While Cypress is an opensource tool, at Itential we have internal libraries that have been built around Cypress to allow us to test with a deployed IAP.

When certifying our Example Projects for a release of IAP we run these tests against the particular version of IAP and create a release branch in GitLab. If you do not see the Example Project available in your version of IAP please contact Itential.

While Itential tests this Example Project and its capabilities, it is often the case the customer environments offer their own unique circumstances. Therefore, it is our recommendation that you deploy this Example Project into a development/testing environment in which you can test the Example Project.

Using this Example Project

Example Projects contain 1 or more workflows. Each of these workflows have different inputs and outputs.

Consume Message - Kafkav2 - Library - Example

This example use case consumes Kafka messages on a given topic and triggers a job from an IAP Operations Manager Event Trigger along with passing message data to that job's context.

The Apache - Kafkav2 - Library Pre-Built provides a modular worfklow that writes to a topic in Apache which then writes to a message queue in IAP's Event System.

In order to subscribe to the relevant event topic, one must configure the adapter-kafkav2 service configuration's topic properties correctly.

The following topic properties is an example of setting the adapter-kafkav2 service configuration so that the adapter subscribes to the Kafka event topic kafkav2-example-topic, does not filter messages based on any text, and subscribes as well to the IAP Event System topic iap-example-topic:

"topics": [
  {
    "name": "kafkav2-example-topic",
    "always": true,
    "subscriberInfo": [
      {
        "subname": "default",
        "filters": [],
        "rabbit": "iap-example-topic",
        "throttle": {}
      }
    ]
  }
]

Note when a new topic is set in the service configuration, a new topic is written to file in the adapter-kafkav2 directory in the file .topics-<kafkav2-adapter-name>.json. If the Consume Message - Kafkav2 - Library worfklow is not being triggered, this file may not have yet been updated with the expected topic.

On setting the adapter-kafkav2 service configuration as shown above, navigate to the Consume Message - Kafkav2 - Library - Example Operations Manager automation, click on the Trigger Consume Message - Kafkav2 - Example - Trigger and select under Event the topic that was set in the adapter service configuration. The event topic based on service configuration above would be iap-example-topic - @itentialopensource/adapter-kafkav2.

To then produce a message to the topic set, run the modular workflow from the Apache - Kafkav2 - Library Pre-Built Produce Message - Kafkav2 - Library. To produce a message to the topic configured above, provide inputs such as the following:

{
  "adapterId": "kafkav2",
  "topic": "kafkav2-example-topic",
  "messages": [
    "This is a message sent to topic kafkav2-example-topic and will then be picked up eventually by IAP's Event System in the topic iap-example-topic"
  ],
  "suppressMessage": true
}

Upon the Send Message task completing in this workflow, there will be a job started from the workflow Consume Message - Kafkav2 - Library of this Pre-Built that can be viewed in Operations Manager in the Jobs panel.

Note, the Trigger Consume Message - Kafkav2 - Example - Trigger defaults to the kafka - @itentialopensource/adapter-kafkav2 event topic, which would correspond to the following adapter-kafka service configuration:

"topics": [
  {
    "name": "kafkav2-example-topic",
    "always": true,
    "subscriberInfo": [
      {
        "subname": "default",
        "filters": [],
        "rabbit": "kafka",
        "throttle": {}
      }
    ]
  }
]

Additionally, the client property in the adapter-kafkav2 service configuration has property brokers to denote the Kafka instance and port to connect to. Further, the logLevel property within the client object overrides the logging of the adapter. The following configuration denotes the adapter-kafkav2 connects to a Kafka instance at 172.1.1.200:9092 and the log level is set to debug:

{
  "host": "",
  "port": 1,
  "client": {
    "logLevel": "logLevel.DEBUG",
    "brokers": [
      "172.1.1.200:9092"
    ]
  }
}

In the above example, the host and port properties, while required in the adapter configuration, are ignored as the `client.brokers[0] information is used to connect to the Kafka instance.

Capabilities include:

• Trigger a workflow on consuming a Kafka message from event topic written to by an adapter-kafkav2 sendMessage call.

Entry Point IAP Component

The primary IAP component to run Consume Message - Kafkav2 - Library - Example is listed below:

Inputs

There are no inputs for Consume Message - Kafkav2 - Library - Example.

Outputs

There are no outputs for Consume Message - Kafkav2 - Library - Example.

Query Output

There are no query output examples for Consume Message - Kafkav2 - Library - Example.

Example Inputs and Outputs

No example inputs or outputs found.

API Links

Additional Information

Support

Please use your Itential Customer Success account if you need support when using this Workflow Project.

Itential Documents:

Related Items:

Adapters