@itentialopensource/send-message-with-kafkav2-adapter
v0.1.3
Published
[Deprecated] Send message with kafkav2 adapter
Downloads
77
Readme
Deprecation Notice
This Pre-Built has been deprecated as of 04-30-2024 and will be end of life on 04-30-2025. The capabilities of this Pre-Built have been replaced by the Apache - Kafkav2 - Library
Send Message Using KafkaV2
Table of Contents
Overview
This pre-built is designed to send a Kafka message using the Kafka v2 adapter. This automation consists of a manual trigger in Operations Manager, which uses a JSON form to allow the user to create a message under a specific topic. The output of this JSON form will be mapped to the variables required by the workflow Kafka Message Producer to send the Kafka message.
Supported IAP Versions
Itential pre-builts are built and tested on particular versions of IAP. In addition, pre-builts that work with devices are often dependent on certain orchestration systems (e.g. NSO and IAG). As such, these pre-builts will have dependencies on these other systems. This version of the Sending message pre-built has been tested with:
- IAP 2023.1.x
Getting Started
These instructions will help you get a copy of the pre-built in your IAP instance for testing in your environment. Reading this section is also helpful for deployments as it provides you with pertinent information on prerequisites and capabilities.
Prerequisites
Users must satisfy the following prerequisites to install and run this pre-built:
- Itential Automation Platform
^2023.1.x
- Kafka v2 Adapter
Capabilities
- Sending Kafka messages using JSON Forms that enable the user to define the topic and message within Operations Manager.
How to Install
To install the pre-built:
- Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the Prerequisites section in order to install the pre-built.
- The pre-built can be installed from within App-Admin_Essentials. Simply search for the name of your desired Pre-Built and click the install button.
Testing
While Itential tests this pre-built 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 pre-built into a development/testing environment in which you can test the pre-built.
Using this Pre-Built
Topics need to be configured in the adapter property. For this demo, the topic "test-6" has been as the topic for "Send Message Using Kafka" trigger. For more information on how to configure topics for your Kafkav2 adapter, please review the kafkav2 adapter's readme in Itential Open Source Gitlab https://gitlab.com/itentialopensource/adapters/notification-messaging/adapter-kafkav2."
Once this pre-built is installed and topics are configured in the adapter properties, go to operations manager.Then click on automations and select "Send Message Using Kafka". Then click on Run manually. You need to write the topic and the message. For this demo we have selected "test-6" topic from the topics configured in the Kafka v2 adapter properties. Optionally, you can check the box for "verbose" if you would like an output summary as a manual task at the end of the workflow.
The following are the demo topics used in the adapter configuration for this example:
[
{
"name": "topic1",
"always": true,
"partition": 0,
"subscriberInfo": [
{
"subname": "default",
"filters": [
"PIXI",
"DRED",
"F: (\\w+), L: (\\w+)",
"\\d{3,4}"
],
"rabbit": "topic1",
"throttle": {}
},
{
"subname": "sub2",
"filters": [
"[abc]",
"F: (\\w+), L: (\\w+)",
"\\d{3,4}"
],
"rabbit": "topic1-s2",
"throttle": {}
}
]
},
{
"name": "topic1",
"always": true,
"partition": 1,
"subscriberInfo": [
{
"subname": "default",
"filters": [
"PIXI",
"DRED",
"[abc]",
"F: (\\w+), L: (\\w+)",
"\\d{3,4}"
],
"rabbit": "topic1-p1",
"throttle": {}
}
]
},
{
"name": "test-6",
"always": true
}
]Input Schema
Example:
{
"formData":{
"topic": "test-6",
"message": "workflowA",
"verbose": false
}
}The following table details the property keys of the formData object.
| key | type | description | |--------------------------------------------- |--------|-------------| | formData | object | job variable | | topic | string | Kafka topic | | message | string | Kafka message string | | verbose | boolean | verbose output option |
Output Schema
Success Example
Input:
{
"formData":{
"topic": "test-6",
"message": "workflowA",
"verbose": false
}
}Output:
{
"ReturnStatus": {
"status": "SUCCESS",
"adapter": "kafkav2",
"topic": "test-6",
"message": "Successfully sent message.",
"errors": [],
"response": {
"status": "success",
"code": 200
}
}
}Failure Example
In this example the Kafka v2 adapter is facing a connection issue.
Input:
{
"formData":{
"topic": "test-6",
"message": "workflowA",
"verbose": false
}
}Output:
{
"ReturnStatus": {
"status": "FAILED",
"adapter": "kafkav2",
"topic": "test-6",
"message": "Failed to send message.",
"errors": [
{
"error_details": {
"icode": "AD.999",
"IAPerror": {
"origin": "kafkav2-adapter-sendMessage",
"displayString": "Producer sending message failed",
"recommendation": "report this issue to the adapter team!",
"stack": {
"name": "KafkaJSNumberOfRetriesExceeded",
"retriable": false,
"cause": {
"name": "KafkaJSConnectionClosedError",
"retriable": true,
"broker": "localhost:9092",
"host": "localhost",
"port": 9092
},
"retryCount": 5,
"retryTime": 8512
}
}
}
}
],
"response": {}
}
}Additional Information
Please use your Itential Customer Success account if you need support when using this pre-built.
Helpful Links:
- Kafka v2 adapter: https://gitlab.com/itentialopensource/adapters/notification-messaging/adapter-kafkav2
- Triggers and API Endpoint Triggers: https://docs.itential.com/docs/automations-3#triggers
- JSON Schema Documentation: https://json-schema.org/
- JSON Form Documentation: https://docs.itential.com/docs/using-json-forms-3
- Operations Manager: https://docs.itential.com/docs/operations-manager-5