Welcome to ASAB Iris, your go-to multifunctional messenger microservice, designed for automated document rendering and message dispatching across various communication channels!
Overview
- Craft beautiful emails with templates using Jinja, Markdown, or HTML.
- Personalize recipient details or go with default configurations.
- Trigger them through a web handler or an Apache Kafka message - flexibility is key!
Configuration
[smtp]
host=smtp.example.com
user=admin
password=secret
from[email protected]
ssl=no
starttls=yes
subject=Mail from ASAB IrisExplanation
host: Your SMTP server's address.user: Your username for the SMTP server.password: Your super-secret password.from: The default "From" address for your emails.ssl:yes/nofor SSL, depends on the SMTP server.starttls:yes/nofor STARTTLS, depends on the SMTP server.subject: The default subject line, if not provided by a caller or a template.
Configuration
[email]
markdown_wrapper=/Templates/Email/body_wrapper.htmlmarkdown_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.
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=generalExplanation
token: Your Slack OAuth access token.channel: The Slack channel you want to send messages to.
- A Slack workspace where you're the admin of app creation.
- 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:readandchannels:read. - Select "Install to Workspace".
- "Allow"
- Copy the OAuth access token.
Add following scopes for:
groups:read: for posting to private channelsim:read: for posting to direct messsagesmpim:read: for posting to group direct messages
- 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.
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.
asab-iris implements specific error handling strategies for the Kafka and Web handlers to ensure robustness and reliability.
- 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.
- 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.
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.phpExplanation
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, typicallyhttps://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
ASABIrisErroris raised. - Non-ASCII Characters: If the message contains non-ASCII characters, an
ASABIrisErroris raised. - Service Errors: Errors returned by the SMSBrana.cz API are mapped to custom error messages and logged for troubleshooting.
- 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)
Diagram: Architecture
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.
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 as2024-06-17 14:45:30%d-%m-%Y- Outputs as17-06-2024%A, %d %B %Y- Outputs asMonday, 17 June 2024%I:%M %p- Outputs as02:45 PM%B %d, %Y- Outputs asJune 17, 2024%Y-%m-%d- Outputs as2024-06-17