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 - Example

Receive Message Using KafkaV2

Table of Contents

• Receive Message Using KafkaV2
  • Table of Contents
  • Overview
  • Supported IAP Versions
  • Getting Started
    • Prerequisites
    • Capabilities
    • How to Install
    • Testing
  • Using this Pre-Built
    • Input Schema
    • Output Schema
      • Success Example
      • Failure Example
  • Additional Information
    • Helpful Links:

Overview

This pre-built is configured to run by an event trigger named Kafka Message Event Trigger in the Operations Manager application. This event type is configured as a Kafka message from the KafkaV2 adapter. When a Kafka message is received, the trigger will start the workflow Main Kafka Receiver. This workflow contains two child jobs. One of the child jobs will run based on the evaluation task in the workflow. The evaluation task is configured to do the following:

• If the message string value contains workflowA, the automation will take the success path and trigger workflow A
• If the message string value contains workflowB, the automation will take the failure path and trigger workflow B

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 Receive 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

• It starts one of two child jobs in the automation Main Kafka Receiver when a Kafka message is received. In Operations Manager the automation trigger is set up as a Kafka type event with a topic defined in the Kafka V2 adapter.

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 selected for the event trigger "Kafka Message Event 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 property. The workflow will be triggered automatically as it is equipped with an event trigger that listens to Kafka messages with topic test-6. The incoming Kafka message value will be in the payload property as a string. Based on the string value it will be evaluated to either run child job workflow A or workflow B.

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:

{
  "payload": "workflowB"
}

The following table details the property keys of the formData object.

| key | type | description | |--------------------------------------------- |--------|-------------| | payload | string | job variable contains the Kafka message|

Output Schema

Success Example

In this example, the payload property value WorkflowA have been received. Which trigged the child job Workflow A successfully

Input:

Example:

{
  "payload": "workflowA"
}

Output:

{
  "ReturnStatus": {
    "status": "SUCCESS",
    "adapter": "kafkav2",
    "topic": "test-6",
    "message": "Successfully completed",
    "errors": [],
    "response": {
      "message": "workflowA",
      "workflowResults": {
        "status": "success",
        "reason": "Workflow A Completed"
      }
    }
  }
}

Failure Example

In this example, the payload property value WorkflowC doesn't exist as a child job.

Input:

Example:

{
  "payload": "workflowC"
}

Output:

{
  "ReturnStatus": {
    "status": "FAILED",
    "adapter": "kafkav2",
    "topic": "test-6",
    "message": "Failed to complete",
    "errors": [
      {
        "message": "The message did not contain a valid workflow."
      }
    ],
    "response": {
      "message": "workflowC"
    }
  }
}

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