ASAB Iris

Welcome to ASAB Iris, your go-to multifunctional messenger microservice, designed for automated document rendering and message dispatching across various communication channels!

Use Cases

📧 1. Sending Emails

Overview

Craft emails with Jinja, Markdown or HTML templates.
Personalize recipients, subject, and body via template parameters.
Trigger through the single /send_email endpoint (HTTP or Kafka).

Configuration

IRIS will automatically choose MS365 if all of these settings are present in your asab.Config:

[m365_email]
tenant_id     = YOUR_AZURE_TENANT_ID
client_id     = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
user_email    = [email protected]
subject       = Default MS365 Subject

Otherwise, if [m365_email] is missing or incomplete, IRIS falls back to SMTP when you set a non-empty host:

[smtp]
host      = smtp.example.com
user      = admin
password  = secret
from      = [email protected]
ssl       = no
starttls  = yes
subject   = Default SMTP Subject

Note

SMTP supports attachments and will include them in the outbound message.

MS365 ignores attachments (you’ll see a warning in the logs if you pass any).

All email templates must live under /Templates/Email/.

Example Web Request

PUT /send_email
Content-Type: application/json

{
  "to": ["[email protected]", "[email protected]"],
  "from": "[email protected]",
  "subject": "Monthly Report",
  "body": {
    "template": "/Templates/Email/report.md",
    "params": {
      "name": "Alice",
      "month": "June"
    }
  },
  "attachments": [
    {
      "template": "/Templates/Email/summary.html",
      "params": {},
      "format": "pdf",
      "filename": "summary.pdf"
    }
  ]
}

Depending on your configuration, this request will be sent via SMTP (with the PDF attachment) or via MS365 (attachment dropped).

Email Markdown Wrapper Configuration

Configuration

[email]
markdown_wrapper=/Templates/Email/body_wrapper.html

markdown_wrapper: Specifies the path to the HTML template for wrapping email content. If this configuration is not provided, or if the value is left empty, the markdown_wrapper will default to None. In such cases, Markdown-formatted emails will be sent without any additional HTML wrapping. This means the emails will consist solely of the content converted from Markdown to HTML, without any extra styling or structure provided by a wrapper template.

🔐 SMTP Transport & TLS Verification

Keys (under [smtp])

# Transport
host            = smtp.example.com
port            = 465                 ; 465 = implicit TLS (SMTPS), 587 = STARTTLS
user            = admin
password        = secret
from            = [email protected]

# TLS mode (choose ONE)
ssl             = yes                 ; yes => implicit TLS (465)
starttls        = no                  ; yes => STARTTLS (587). Do NOT enable both.

# Verification
validate_certs  = yes                 ; Verify server certificate (recommended in prod)
cert_bundle     =                     ; Path to CA/chain PEM when validate_certs=yes.
                                      ; Needed for self-signed/internal CAs.
                                      ; Leave empty to use system trust store.
                                      ; When validate_certs=no, both chain and hostname checks are disabled and
                                      ; cert_bundle is ignored.

Important

Use real booleans: yes|no (not quoted strings).
cert_bundle must be a CA/chain PEM, not the server cert.
If you supply a custom TLS context in code, some clients ignore validate_certs/cert_bundle.

Common Setups

A) Production — SMTPS (465) with internal CA

[smtp]
host            = mail.internal.lan
user            = admin
port            = 465
ssl             = yes
starttls        = no
password        = ****
from            = [email protected]
validate_certs  = yes
cert_bundle     = /etc/ssl/internal_ca.pem

B) Production — STARTTLS (587) with public CA

[smtp]
host            = smtp.example.com
user            = admin
port            = 587
ssl             = no
starttls        = yes
password        = ****
from            = [email protected]
validate_certs  = yes
cert_bundle     =                    ; empty = use system trust store

C) Local Dev — no TLS (not for prod)

[smtp]
host            = 127.0.0.1
user            = admin
port            = 2525
ssl             = no
starttls        = no
password        =
from            = dev@localhost
validate_certs  = no
cert_bundle     =

🚨 2. Sending Slack messages

Overview

Send messages to a Slack via HTTP REST API or through Kafka Topic
Apply Jinja2 templates.
Trigger them through a web handler or an Apache Kafka message - flexibility is key!

Configuration

[slack]
token=xoxb-111111111111-2222222222222-3333333333333voe
channel=general

Explanation

token: Your Slack OAuth access token.
channel: The Slack channel you want to send messages to.

🤖 Creating Slack OAuth access token for Slack Apps

Prerequisites

A Slack workspace where you're the admin of app creation.

Steps

Visit the Slack API website.
Select "Create New App".
Name your app and choose its home (workspace).
Select "Create App"
Configure "OAuth & Permissions".
Add the necessary scopes: chat:write, files:write, files:read and channels:read.
Select "Install to Workspace".
"Allow"
Copy the OAuth access token.

Add following scopes for:

groups:read: for posting to private channels
im:read: for posting to direct messsages
mpim:read: for posting to group direct messages

Adding the App to a Channel

Choose a channel in your Slack workspace.
Invite the app.
Search for your app and select it.
Confirm the addition.
Verify the app's presence.

📬 3. Sending Microsoft Teams messages

Overview

Send messages to a Microsoft Teams via HTTP REST API or thru Kafka Topic
Apply Jinja2 templates.
Trigger them through a web handler or an Apache Kafka message - flexibility is key!

Configuration

[outlook]
webhook_url=https://outlook.office.com/webhook/...

Explanation

webhook_url: Your webhook URL.

Error Handling

asab-iris implements specific error handling strategies for the Kafka and Web handlers to ensure robustness and reliability.

KafkaHandler Error Handling

Fallback Mechanism: In case of errors during message processing, a fallback mechanism is triggered. This ensures that the system can still operate or recover gracefully when encountering issues.
General Error Logging: Any errors during message dispatching are logged as exceptions.

WebHandler Error Handling

Error Responses: Internal error codes are mapped to HTTP status codes, providing meaningful responses to clients.
Exception Handling: General exceptions are logged, and standardized error responses are sent to clients.

📱 4. Sending SMS messages

Overview

Send SMS messages using the SMSBrana.cz API.
Supports automatic segmentation of long messages.
Apply Jinja2 templates.
Trigger them through a web handler or an Apache Kafka message - flexibility is key!

Configuration

[sms]
login=your_smsbrana_login
password=your_smsbrana_password
timestamp_format=%Y%m%dT%H%M%S
api_url=https://api.smsbrana.cz/smsconnect/http.php

Explanation

login: Your login for the SMSBrana.cz service.
password: Your password for the SMSBrana.cz service.
timestamp_format: The format used for timestamps, typically "%Y%m%dT%H%M%S".
api_url: The API URL for SMSBrana.cz, typically https://api.smsbrana.cz/smsconnect/http.php.

Handling Long Messages

SMS messages are automatically split into segments if they exceed the length limits:
- 1 SMS: up to 160 characters.
- 2 SMS: up to 306 characters (153 characters per segment).
- 3 SMS: up to 459 characters (153 characters per segment).
Each segment is sent separately, ensuring that messages are not truncated.

Usage Example

To send an SMS, you can configure the SMS service in your application and trigger it via a web handler or Kafka message. The service will handle splitting long messages into segments and sending them sequentially.

Error Handling

Invalid Phone Number: If the phone number is missing or invalid, an ASABIrisError is raised.
Non-ASCII Characters: If the message contains non-ASCII characters, an ASABIrisError is raised.
Service Errors: Errors returned by the SMSBrana.cz API are mapped to custom error messages and logged for troubleshooting.

📱 5. Sending Push Notifications (ntfy.sh)

Overview

ASAB Iris supports real-time push notifications using the ntfy.sh protocol (or a self-hosted ntfy server). This lets you send instant alerts to mobile devices, desktops, or browsers — perfect for ticketing, monitoring, or system events.

Trigger via HTTP REST API or Kafka.
Uses Jinja2 templates just like email/Slack/Teams/SMS.
Allows a fallback/default topic.
Supports configurable request timeout.

Configuration

[push]
url            = https://ntfy.sh       ; Base URL of the ntfy server
default_topic  = send_ph               ; Default topic when request doesn't specify one
timeout        = 10                    ; HTTP request timeout (seconds)

Explanation

url: Base ntfy endpoint (cloud or self-hosted).
default_topic: IRIS uses this topic if the message doesn’t specify one.
timeout: Max seconds to wait for ntfy response before aborting the request.

How Push Notifications Work

A topic (e.g., alerts, tickets, errors) is created simply by naming it — ntfy topics are auto-created.
Users subscribe through:
- ntfy mobile app (Android/iOS)
- ntfy desktop app
- Browser subscription
- CLI
IRIS posts the rendered message to that topic.
All subscribers receive the notification instantly.

Example Web Request

PUT /send_push
Content-Type: application/json

{
  "topic": "alerts",
  "body": {
    "template": "/Templates/Push/alert.md",
    "params": {
      "severity": "High",
      "service": "Billing",
      "message": "Payment processor timeout"
    }
  }
}

If topic is missing, IRIS falls back to [push] default_topic.

Example Kafka Message

{
  "type": "push",
  "topic": "tickets",
  "body": {
    "template": "/Templates/Push/ticket_update.md",
    "params": {
      "ticket_id": "INC-3021",
      "status": "Resolved"
    }
  }
}

Explanation

type: Must be "push".
topic: Optional; overrides [push] default_topic.
body.template: Path to your template.
params: Values passed into the template.

Templates

Place all templates under:

/Templates/Push/

Example template (alert.md):

🚨 *{{ severity }} Alert*

Service: **{{ service }}**
Message: {{ message }}

{{ now()|datetimeformat("%Y-%m-%d %H:%M:%S") }}

Push Notification Metadata

Push notifications may include optional metadata under body.params. These parameters affect how the notification is displayed, not the message content.

Supported parameters (backend-specific):

title — notification title
priority — urgency level
tags — labels or icons shown by the client
click — URL opened when the notification is clicked

Example:

{
  "topic": "tenantA-alerts",
  "rendered_message": "CPU usage above 90% on node ant-3",
  "body": {
    "params": {
      "title": "High CPU",
      "priority": "high",
      "tags": "prod,alerts",
      "click": "https://grafana.example.com/d/abc123"
    }
  }
}

Notes:

Metadata is optional.
Metadata affects presentation only; message content remains unchanged.
Visual appearance may differ between tenants, requests, and clients.
Metadata support is push-backend specific (currently ntfy).
Identical visual rendering is not guaranteed.

🛠 Supported Technologies

Inbound: HTTP REST API
Inbound: Apache Kafka
Jinja2 for template specifications
Markdown for templates
HTML for templates and the output
PDF for the output
Output: Email SMTP
Output: Slack
Output: Microsoft Teams
Powered by ASAB (because we’re standing on the shoulders of giants)

📚 More info

Documentation

Diagram: Architecture

Jinja2 Filters and Functions

`now()` Function

The now() function returns the current UTC datetime. You can use this function in your Jinja2 templates to insert the current date and time.

Usage Example:

{{ now() }}

This will output the current date and time in the default format.

`datetimeformat` Filter

The datetimeformat filter allows you to format datetime objects in your Jinja2 templates.

Usage Example:

To format the current datetime returned by now():

{{ now()|datetimeformat('%Y-%m-%d %H:%M:%S') }}

Possible Formats:

Here are some common format strings you can use with the datetimeformat filter:

%Y-%m-%d %H:%M:%S - Outputs as 2024-06-17 14:45:30
%d-%m-%Y - Outputs as 17-06-2024
%A, %d %B %Y - Outputs as Monday, 17 June 2024
%I:%M %p - Outputs as 02:45 PM
%B %d, %Y - Outputs as June 17, 2024
%Y-%m-%d - Outputs as 2024-06-17

🚀 5. Sending Notifications to Kafka

Overview

ASAB Iris supports sending notifications to various communication channels such as email, Slack, and Microsoft Teams via Kafka. Each notification is structured using templates and parameters to ensure customizable content.

Kafka Message Structure

Notifications are sent to Kafka in JSON format.
Each notification contains a type field specifying the channel (e.g., email, slack, msteams), and a body that includes the template and its parameters.

1. Sending Email Notifications

Example Kafka Message:

{
    "type": "email",
    "to": ["Shivashankar <[email protected]>"],
    "from": "[email protected]",
    "body": {
        "template": "/Templates/Email/message.md",
        "params": {
            "name": "I am testing a template",
            "error": "None"
        }
    }
}

Explanation:

type: Defines the notification type as email.
to: List of recipients.
from: The sender's email address.
template: Path to the template used for the email content.
params: Parameters for populating the email template.

2. Sending Slack Notifications

Example Kafka Message:

{
    "type": "slack",
    "body": {
        "template": "/Templates/Slack/Slack example.md",
        "params": {
            "name": "I am testing a template",
            "error": "None"
        }
    }
}

Explanation:

type: Defines the notification type as slack.
body.template: Path to the Slack message template.
params: Parameters for populating the Slack template.

3. Sending Microsoft Teams Notifications

Example Kafka Message:

{
    "type": "msteams",
    "body": {
        "template": "/Templates/MSTeams/Teams example.md",
        "params": {
            "name": "I am testing a template",
            "error": "None"
        }
    }
}

Explanation:

type: Defines the notification type as msteams.
body.template: Path to the Microsoft Teams message template.
params: Parameters for populating the Teams template.

Name		Name	Last commit message	Last commit date
Latest commit History 986 Commits
asabiris		asabiris
docs		docs
etc		etc
library/Templates		library/Templates
test		test
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
asab-iris.py		asab-iris.py
docker-compose.yaml		docker-compose.yaml
qa.md		qa.md
requirements.txt		requirements.txt
setup.cfg		setup.cfg

License

TeskaLabs/asab-iris

Folders and files

Latest commit

History

Repository files navigation

ASAB Iris

Use Cases

📧 1. Sending Emails

Email Markdown Wrapper Configuration

🔐 SMTP Transport & TLS Verification

🚨 2. Sending Slack messages

🤖 Creating Slack OAuth access token for Slack Apps

Prerequisites

Steps

Adding the App to a Channel

📬 3. Sending Microsoft Teams messages

Error Handling

KafkaHandler Error Handling

WebHandler Error Handling

📱 4. Sending SMS messages

📱 5. Sending Push Notifications (ntfy.sh)

Configuration

How Push Notifications Work

Example Web Request

Example Kafka Message

Templates

Push Notification Metadata

🛠 Supported Technologies

📚 More info

Jinja2 Filters and Functions

now() Function

datetimeformat Filter

🚀 5. Sending Notifications to Kafka

Kafka Message Structure

1. Sending Email Notifications

2. Sending Slack Notifications

3. Sending Microsoft Teams Notifications

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 118

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

`now()` Function

`datetimeformat` Filter

Packages