Call Telemetry for Cisco

Appearance

MS Teams App Documentation Audit ​

Overview ​

This audit compares the documented MS Teams app in /docs/apps/ms_teams.md against the actual implementation in the codebase.

Critical Findings ​

1. ❌ Major Documentation Inaccuracies ​

Documented vs Actual Parameters ​

Documentation Claims:

  • webhook_url (string)
  • message_text (string)
  • title (string) - optional
  • color (string) - optional
  • sections (array) - optional with complex structure

Actual Implementation (from schema.ex):

elixir
embedded_schema do
  field(:message_text, :string, default: @default_alert)
  field :webhook_url, :string
end

Reality: The MS Teams app ONLY supports:

  • webhook_url - The webhook URL
  • message_text - The message text

There is NO support for:

  • title
  • color
  • sections
  • Rich formatting structure
  • Facts arrays
  • Activity titles/subtitles

2. ❌ Message Formatting Issues ​

Documentation Shows: Complex JSON message card format with sections and facts

Actual Implementation:

  • Sends simple text messages only
  • Converts newlines to <br /> tags for Teams compatibility
  • No support for Teams Message Card format
  • No JSON payload structure

From send_message.ex:

elixir
Tesla.post(client(), url, %{text: message_text |> String.replace("\n", "<br />")})

3. ❌ App Type Confusion ​

Documentation Says: "Type: alert"

Actual Implementation: The app appears to be a post-call app based on:

  • Uses pipeline.final.rule.alert_template
  • Located in post-call processing pipelines
  • Uses PostCallWebUpdate for status updates

4. ❌ Template Variable Processing ​

Documentation Claims: Direct template variable support in message_text

Actual Implementation:

  • Uses pipeline.final.rule.alert_template NOT app.provider_params.message_text
  • Template rendering happens through MessageHelper.render_message_with_template
  • The app uses the rule's alert template, not the app's message_text parameter

5. ✅ Correctly Documented ​

  • Webhook URL requirement
  • Basic error handling concepts
  • Teams webhook creation steps
  • General usage concept

Code Analysis ​

Actual Message Sending ​

elixir
def post_message_to_webhook(url, message_text) do
  result = Tesla.post(client(), url, %{text: message_text |> String.replace("\n", "<br />")})
  # Only checks for 200 status code
end

Response Handling ​

  • Success: HTTP 200 only
  • Failure: Any other status code
  • No detailed error messages from Teams API

Recommendations ​

High Priority Fixes ​

  1. Remove all references to:

    • title parameter
    • color parameter
    • sections parameter
    • Rich formatting options
    • Message Card format

  2. Clarify message source:

    • The app uses the rule's alert template
    • NOT the app's message_text parameter
    • This is fundamentally different from documented behavior

  3. Update examples:

    • Remove all complex JSON examples
    • Show only simple text messages
    • Explain the newline to <br /> conversion

  4. Correct the app type:

    • Clarify if this is truly an "alert" app or post-call app
    • Update categorization accordingly

Medium Priority Updates ​

  1. Document the actual message flow through MessageHelper
  2. Explain the relationship between rule templates and app messages
  3. Add notes about Teams formatting limitations

Low Priority Enhancements ​

  1. Document the exact Tesla HTTP client configuration
  2. Add troubleshooting for common webhook issues
  3. Include Teams webhook security considerations

Example Correction ​

Current Documentation (WRONG):

json
{
  "provider_params": {
    "webhook_url": "https://...",
    "title": "Alert Title",
    "color": "FF0000",
    "sections": [...]
  }
}

Actual Implementation:

json
{
  "provider_params": {
    "webhook_url": "https://...",
    "message_text": "Simple text message\nWith newlines"
  }
}

Conclusion ​

The MS Teams app documentation is significantly incorrect, showing a complex implementation that doesn't exist. The actual app is much simpler - it only sends plain text messages to a webhook URL, with newlines converted to <br /> tags. The documentation needs a complete rewrite to match the actual implementation.