Zulip HITL

Human-in-the-loop integration with Zulip

Actions4

Overview

This node provides a human-in-the-loop (HITL) integration with Zulip, a team chat platform. It enables workflows to interact with Zulip streams for various purposes such as requesting human approvals, sending messages, creating new streams, and monitoring user responses in real-time or via polling.

Common scenarios where this node is beneficial include:

  • Automating approval workflows by sending requests to Zulip streams and waiting for human approval or rejection.
  • Sending notifications or messages to specific Zulip streams as part of a workflow.
  • Creating new Zulip streams dynamically to organize conversations related to workflows.
  • Monitoring Zulip streams or topics for user responses, enabling workflows to react based on user input.

Practical examples:

  • A deployment pipeline sends an approval request message to a Zulip stream and waits for a team lead to approve or reject the deployment.
  • A support workflow sends status updates to a Zulip stream dedicated to customer service.
  • A workflow creates a private Zulip stream for sensitive project discussions and subscribes relevant users automatically.
  • A workflow monitors a Zulip topic for free-text feedback from users and processes their responses accordingly.

Properties

Name Meaning
Stream Name Name of the Zulip stream to use. Must be lowercase, can contain letters, numbers, and hyphens, max 60 characters. Stream names are case-sensitive and must follow Zulip naming conventions.
Enable Debug Mode Whether to enable detailed debug logging for troubleshooting. Shows detailed logs about operations, API calls, and internal processing. Use only when needed as it may impact performance.
Debug Level Level of detail for debug logging. Options: Debug, Error Only, Info, Trace, Verbose, Warnings. Higher levels provide more information but may impact performance.
Debug Categories Specific categories to enable debug logging for, e.g., API Calls, Authentication, Network, Performance, Recovery, User Feedback, Validation, Workflow, or All Categories.
Debug Output Format Format for debug log output: JSON (machine-readable) or Pretty (human-readable).
Performance Tracking Whether to track operation timing and memory usage to identify bottlenecks. Adds slight overhead.
Include Stack Traces Whether to include stack traces in error and debug logs. Useful for debugging but increases log volume significantly.
Formatting Options Collection of rich text formatting and markdown options including allowed/forbidden HTML tags, emoji, markdown, math blocks, mentions, spoilers, tables, message style (Plain Text, Basic Markdown, Rich Markdown, Zulip Enhanced), and XSS protection.

Note: The above properties are general; some are shown conditionally depending on the selected operation.

Output

The node outputs JSON data with fields varying by operation:

  • Request Approval:

    • approved (boolean): Whether the request was approved.
    • rejected (boolean): Whether the request was rejected.
    • timedOut (boolean): Whether the approval timed out without response.
    • streamName, topic, messageId: Identifiers of the Zulip stream, topic, and message.
    • elapsedMinutes: Minutes elapsed waiting for response.
    • response: Object containing response details (id, content, sender, timestamp) if available.
    • timestamp: Timestamp of the output.
    • userFeedback: Structured message about success or timeout.

  • Send Message:

    • success (boolean): Whether the message was sent successfully.
    • messageId: ID of the sent message.
    • streamName, topic: Target stream and topic.
    • content: Processed message content.
    • timestamp: Timestamp of the output.
    • userFeedback: Success message details.

  • Create Stream:

    • success (boolean): Whether the stream was created successfully.
    • streamName, streamId: Name and unique ID of the created stream.
    • description: Description of the stream.
    • private: Boolean indicating if the stream is private.
    • subscribedUsers: List of subscribed user emails.
    • timestamp: Timestamp of the output.

  • Handle User Response:

    • success (boolean): Whether a response was received.
    • timedOut (boolean): Whether the wait timed out.
    • streamName: Monitored stream name.
    • response: Object with response details (id, content, sender, timestamp) if any.
    • timestamp: Timestamp of the output.
    • userFeedback: Message about success or timeout.

The node does not output binary data.

Dependencies

  • Requires an API key credential for authenticating with the Zulip server.
  • Needs access to a Zulip server URL and bot email configured in credentials.
  • Uses internal modules for API client, response monitoring, logging, recovery management, user feedback, debugging configuration, metrics collection, utilities, and markdown processing.
  • No external environment variables beyond the required API credentials.

Troubleshooting

Common Issues

  • Missing or invalid credentials will cause authentication errors.
  • Invalid stream or topic names that do not conform to Zulip naming rules will cause validation errors.
  • Timeout values outside allowed ranges (1-1440 minutes) or polling intervals outside allowed ranges (10-3600 seconds) will cause validation errors.
  • Failure to connect to the Zulip API due to network issues or incorrect server URL.
  • API errors when sending messages or creating streams, often due to permission issues or invalid parameters.
  • Empty or improperly formatted message content after markdown processing.

Error Messages and Resolutions

  • "No credentials provided": Ensure API key credential is set up correctly.
  • "Connection failed": Verify server URL, bot email, and API key; check network connectivity.
  • "Stream name required" / "Invalid stream name": Provide a valid stream name following Zulip conventions.
  • "Topic required" / "Invalid topic name": Provide a valid topic name within length limits.
  • "Content required" / "Message content cannot be empty": Provide non-empty message content.
  • "Timeout must be between 1 and 1440 minutes": Adjust timeout parameter within allowed range.
  • "Polling Interval must be between 10 and 3600 seconds": Adjust polling interval within allowed range.
  • API error messages when sending messages or creating streams: Check permissions, stream existence, and parameter correctness.
  • Approval timeout warnings: Indicates no response was received within the specified timeout.

Enabling debug mode with appropriate levels and categories can help diagnose issues.

Links and References

Discussion