npm package: @itentialopensource/apache-kafka-library-example
Description: This Pre-Built Automation bundle contains example use cases that are applicable when Itential Automation Platform is integrated with Apache Kafka using the kafka-node npm library. Because every environment is different, these use cases are fully functioni
Author: Itential
Latest version: 1.0.6-2023.2.1

# Apache - Kafka - Library - Example

## Overview

This Pre-Built Automation bundle contains example use cases that are applicable when Itential Automation Platform is integrated with Apache Kafka using the kafka-node npm library. Because every environment is different, these use cases are fully functioning examples that can be easily modified to operate in your specific environment. These workflows have been written with modularity in mind to make them easy to understand and simple to modify to suit your needs.


## Example Workflows


<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Overview</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><a href='https://gitlab.com/itentialopensource/pre-built-automations/apache-kafka-library-example/-/blob/release/2023.2/documentation/Consume Message - Kafka - Library - Example.md' target='_blank'>Consume Message - Kafka - Library - Example</a></td>
      <td>

This example use case consumes Kafka messages on a given topic and triggers a job from an <a href='https://docs.itential.com/docs/triggers-2023-1#event-triggers' target='_blank'>IAP Operations Manager Event Trigger</a> along with passing message data to that job's context.

The <a href='https://gitlab.com/itentialopensource/pre-built-automations/apache-kafka-library' target='_blank'>Apache - Kafka - Library Pre-Built</a> provides a modular worfklow that writes to a topic in Apache which then writes to a message queue in <a href='https://docs.itential.com/docs/event-system-4' target='_blank'>IAP's Event System</a>.

In order to subscribe to the relevant event topic, one must configure the <a href='https://gitlab.com/itentialopensource/adapters/notification-messaging/adapter-kafka' target='_blank'>adapter-kafka</a> service configuration's <a href='https://gitlab.com/itentialopensource/adapters/notification-messaging/adapter-kafka/-/blob/master/PROPERTIES.md#topic-properties' target='_blank'>topic properties</a> correctly.

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

```json
"topics": [
  {
    "name": "kafka-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-kafka directory in the file `.topics-<kafka-adapter-name>.json`. If the `Consume Message - Kafka - Library` worfklow is not being triggered, this file may not have yet been updated with the expected topic.

On setting the adapter-kafka service configuration as shown above, navigate to the `Consume Message - Kafka - Library - Example` Operations Manager automation, click on the Trigger `Consume Message - Kafka - 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-kafka`.

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

```json
{
  "adapterId": "kafka",
  "topic": "kafka-example-topic",
  "messages": [
    "This is a message sent to topic kafka-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 - Kafka - Library` of this Pre-Built that can be viewed in Operations Manager in the Jobs panel.

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

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

</td>
    </tr>
  </tbody>
</table>


## External Dependencies

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>OS Version</th>
      <th>API Version</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Apache Kafka</td>
      <td></td>
      <td></td>
    </tr>
  </tbody>
</table>

## Adapters

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Version</th>
      <th>Configuration Notes</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><a href="https://gitlab.com/itentialopensource/adapters/notification-messaging/adapter-kafka">adapter-kafka</a></td>
      <td>^0.5.0</td>
      <td></td>
    </tr>
  </tbody>
</table>