Transition to use Microsoft Teams Adaptive Cards (#35)

* adaptive card updates started

* updates

* updates

* updated to array method and tests

* adpative cards update

* update notes

---------

Co-authored-by: John mcconnachie <[email protected]>

Author: johnatricorocks

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to `microsoft-teams` will be documented in this file
 
+Adaptive Cards 
+
 ## 1.1.4 - 2023-01-25
 Update Readme to support Laravel 10.x
 

README.md

@@ -7,12 +7,33 @@
 This package makes it easy to send notifications using [Microsoft Teams](https://products.office.com/en-US/microsoft-teams/group-chat-software) with Laravel 5.5+, 6.x, 7.x, 8.x, 9.x, 10.x, 11.x and 12.x
 
 ```php
-return MicrosoftTeamsMessage::create()
-    ->to(config('services.microsoft_teams.sales_url'))
-    ->type('success')
+return MicrosoftTeamsAdaptiveCard::create()
+    ->to(config('services.microsoft_teams.webhook_url'))
     ->title('Subscription Created')
-    ->content('Yey, you got a **new subscription**. Maybe you want to contact him if he needs any support?')
-    ->button('Check User', 'https://foo.bar/users/123');
+    ->content([
+        TextBlock::create()
+            ->setText('Yey, you got a **new subscription**. Maybe you want to contact him if he needs any support?')
+            ->setFontType('Monospace')
+            ->setWeight('Bolder')
+            ->setSize('ExtraLarge')
+            ->setSpacing('ExtraLarge')
+            ->setStyle('Heading')
+            ->setHorizontalAlignment('Center')
+            ->setSeparator(true),
+        FactSet::create()
+            ->setSpacing('ExtraLarge')
+            ->setSeparator(true)
+            ->setFacts([
+                Fact::create()->setTitle('Subscription Created')->setValue('Today'),
+            ])
+    ])
+    ->actions([
+        ActionOpenUrl::create()
+            ->setMode('Primary')
+            ->setStyle('Positive')
+            ->setTitle('Contact Customer')
+            ->setUrl("https://foo.bar"),
+    ]);
 ```
 ## Contents
 
@@ -23,8 +44,10 @@ return MicrosoftTeamsMessage::create()
     - [Setting up the MicrosoftTeams service](#setting-up-the-microsoftteams-service)
   - [Usage](#usage)
     - [On-Demand Notification Usage](#on-demand-notification-usage)
-    - [Available Message methods](#available-message-methods)
-      - [Sections](#sections)
+    - [Available Adaptive Card methods](#available-adaptive-cards-methods)
+    - [Content Block Types](#content-block-types)
+    - [Action Types](#action-types)
+     
   - [Changelog](#changelog)
   - [Testing](#testing)
   - [Security](#security)
@@ -52,7 +75,7 @@ Next, if you're using Laravel _without_ auto-discovery, add the service provider
 
 ### Setting up the Connector
 
-Please check out [this](https://docs.microsoft.com/en-gb/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook#add-an-incoming-webhook-to-a-teams-channel) for setting up and adding a webhook connector to your Team's channel. Basic Markdown is supported, please also check out the [message card reference article](https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#httppost-action) which goes in more detail about the do's and don'ts.
+Please check out [this](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498) for setting up and adding a webhook connector to your Team's channel. Please also check out the [adaptive card reference](https://learn.microsoft.com/en-us/adaptive-cards/) which goes in more detail about adaptive cards.
 
 ### Setting up the MicrosoftTeams service
 
@@ -98,12 +121,33 @@ class SubscriptionCreated extends Notification
 
     public function toMicrosoftTeams($notifiable)
     {
-        return MicrosoftTeamsMessage::create()
-            ->to(config('services.microsoft_teams.sales_url'))
-            ->type('success')
+        return MicrosoftTeamsAdaptiveCard::create()
+            ->to(config('services.microsoft_teams.webhook_url'))
             ->title('Subscription Created')
-            ->content('Yey, you got a **new subscription**. Maybe you want to contact him if he needs any support?')
-            ->button('Check User', 'https://foo.bar/users/123');
+            ->content([
+                TextBlock::create()
+                    ->setText('Yey, you got a **new subscription**. Maybe you want to contact him if he needs any support?')
+                    ->setFontType('Monospace')
+                    ->setWeight('Bolder')
+                    ->setSize('ExtraLarge')
+                    ->setSpacing('ExtraLarge')
+                    ->setStyle('Heading')
+                    ->setHorizontalAlignment('Center')
+                    ->setSeparator(true),
+                FactSet::create()
+                    ->setSpacing('ExtraLarge')
+                    ->setSeparator(true)
+                    ->setFacts([
+                        Fact::create()->setTitle('Subscription Created')->setValue('Today'),
+                    ])
+            ])
+            ->actions([
+                ActionOpenUrl::create()
+                    ->setMode('Primary')
+                    ->setStyle('Positive')
+                    ->setTitle('Contact Customer')
+                    ->setUrl("https://foo.bar"),
+            ]);
     }
 }
 ```
@@ -127,36 +171,72 @@ Notification::route(MicrosoftTeamsChannel::class,null)
     ->notify(new SubscriptionCreated());
 ```
 
+### Available Adaptive Card methods
 
-### Available Message methods
-| **Method** | **Description** |
-|------------|-----------------|
-| `to(string $webhookUrl)` | Recipient's webhook url |
-| `title(string $title)` | Title of the message |
-| `summary(string $summary)` | Summary of the message |
-| `type(string $type)` | Type which is used as theme color (any valid hex code or one of: primary|secondary|accent|error|info|success|warning) |
-| `content(string $content)` | Content of the message (Markdown supported) |
-| `button(string $text, string $url = '', array $params = [])` | Text and url of a button. Wrapper for an potential action |
-| `action(string $text, $type = 'OpenUri', array $params = [])` | Text and type for a potential action. Further params can be added depending on the action. For more infos about different types check out [this link](https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions). |
-| `options(array $options, $sectionId = null)` | Add additional options to pass to the message payload object |
-
-#### Sections
-It is possible to define one or many sections inside a message card. The following methods can be used within a section
-| **Method** | **Description** |
-|------------|-----------------|
-| `addStartGroupToSection($sectionId = 'standard_section')` | Add a startGroup property which marks the start of a logical group of information |
-| `activity(string $activityImage = '', string $activityTitle = '', string $activitySubtitle = '', string $activityText = '', $sectionId = 'standard_section')` | Add an activity to a section |
-| `fact(string $name, string $value, $sectionId = 'standard_section')` | Add a fact to a section (Supports Markdown) |
-| `image(string $imageUri, string $title = '', $sectionId = 'standard_section')` | Add an image to a section |
-| `heroImage(string $imageUri, string $title = '', $sectionId = 'standard_section')` | Add a hero image to a section |
-
-Additionally the title, content, button and action can be also added to a section through the optional `params` value:
-| **Method** | **Description** |
-|------------|-----------------|
-| `title(string $title, array $params = ['section' => 'my-section'])` | Title of the message and add it to `my-section` |
-| `content(string $content, array $params = ['section' => 'my-section'])` | Content of the message and add it to `my-section` (Markdown supported) |
-| `button(string $text, string $url = '', array $params = ['section' => 'my-section'])` | Text and url of a button and add it to `my-section` |
-| `action(string $text, $type = 'OpenUri', array $params = ['section' => 'my-section'])` | Text and type of an potential action and add it to `my-section` |
+- `create()`: Static factory method to create a new instance of the MicrosoftTeamsAdaptiveCard.
+- `to(string $webhookUrl)`: Sets the recipient's webhook URL. Required for sending notifications.
+- `title(string $title)`: Sets the title of the adaptive card with appropriate text styling (heading style, bold weight, and large size).
+- `content(array $contentBlocks)`: Adds content blocks to the adaptive card body. Accepts an array of content block objects like TextBlock, FactSet, Icon, etc.
+- `actions(array $actions)`: Adds action buttons to the adaptive card. Accepts an array of action objects like ActionOpenUrl.
+- `getWebhookUrl()`: Returns the currently set webhook URL.
+- `toNotGiven()`: Checks if the webhook URL has been provided. Returns true if no webhook URL is set.
+- `toArray()`: Returns the complete payload as an associative array.
+
+### Content Block Types
+You can use various content block types in the content() method:
+
+#### `TextBlock::create()`: Creates a text block with options for:
+
+- `setText(string $text)`: Sets the text content (supports markdown formatting)
+- `setFontType(string $fontType)`: Sets the font type (e.g., 'Default', 'Monospace')
+- `setWeight(string $weight)`: Sets text weight (e.g., 'Lighter', 'Default', 'Bolder')
+- `setSize(string $size)`: Sets text size (e.g., 'Small', 'Default', 'Medium', 'Large', 'ExtraLarge')
+- `setSpacing(string $spacing)`: Sets spacing around the element (e.g., 'None', 'Small', 'Default', 'Medium', 'Large', 'ExtraLarge', 'Padding')
+- `setStyle(string $style)`: Sets text style (e.g., 'Default', 'ColumnHeader', 'Heading')
+- `setHorizontalAlignment(string $alignment)`: Sets text alignment (e.g., 'Left', 'Center', 'Right')
+- `setSeparator(bool $separator)`: Adds a separator line above the element when true
+- `setWrap(bool $wrap)`: Sets whether text should wrap or not
+- `setColor(string $color)`: Sets text color (e.g., 'Default', 'Dark', 'Light', 'Accent', 'Good', 'Warning', 'Attention')
+- `setIsSubtle(bool $isSubtle)`: Sets whether text should be subtle or not
+- `setMaximumLines(int $maxLines)`: Sets the maximum number of lines for the text block
+- `toArray()`: Returns the TextBlock properties as an array
+
+
+#### `Icon::create()`: Creates an icon with options for:
+
+- `setName(string $name)`: Sets the name of the icon
+- `setColor(string $color)`: Sets icon color (e.g., 'Default', 'Dark', 'Light', 'Accent', 'Good', 'Warning', 'Attention')
+- `setSpacing(string $spacing)`: Sets spacing around the icon (e.g., 'None', 'Small', 'Default', 'Medium', 'Large', 'ExtraLarge', 'Padding')
+- `setSeparator(bool $separator)`: Adds a separator line above the element when true
+- `setSize(string $size)`: Sets icon size (e.g., 'xxSmall', 'xSmall', 'Small', 'Standard', 'Medium', 'Large', 'xLarge', 'xxLarge')
+- `setStyle(string $style)`: Sets icon style (e.g., 'Regular', 'Filled')
+- `setHorizontalAlignment(string $alignment)`: Sets icon alignment (e.g., 'Left', 'Center', 'Right')
+- `toArray()`: Returns the Icon properties as an array
+
+#### `FactSet::create()`: Creates a set of facts with options for:
+
+- `setFacts(array $facts)`: Sets an array of Fact objects
+- `setSpacing(string $spacing)`: Sets spacing around the element (e.g., 'None', 'Small', 'Default', 'Medium', 'Large', 'ExtraLarge', 'Padding')
+- `setSeparator(bool $separator)`: Adds a separator line above the element when true
+- `toArray()`: Returns the FactSet properties as an array
+
+
+#### `Fact::create()`: Creates a single fact (key-value pair) with methods:
+
+- `setTitle(string $title)`: Sets the fact's title/key
+- `setValue(string $value)`: Sets the fact's value
+- `toArray()`: Returns the Fact properties as an array
+
+### Action Types
+You can use various action types in the actions() method:
+
+#### `ActionOpenUrl::create()`: Creates a button that opens a URL with options for:
+
+- `setTitle(string $title)`: Sets the button text
+- `setUrl(string $url)`: Sets the URL to open when clicked
+- `setStyle(string $style)`: Sets button style (e.g., 'Default', 'Positive', 'Destructive')
+- `setMode(string $mode)`: Sets the interaction mode (e.g., 'Primary', 'Secondary')
+- `toArray()`: Returns the ActionOpenUrl properties as an array
 
 ## Changelog
 

UPGRADE.md

@@ -0,0 +1,76 @@
+# Upgrade Guide
+
+## Migrating from Message Cards to Adaptive Cards
+
+### Overview
+Microsoft is deprecating **O365 Connectors** within Microsoft Teams, which means **Message Cards** are now considered legacy and will no longer be supported. As a result, this package has been updated to use **Adaptive Cards** instead.
+
+With this major update, you will need to:
+#### Outside Your Application
+- **Create new incoming webhooks using Workflows for Microsoft Teams** (O365 Connectors are no longer valid).
+
+#### Inside Your Application
+- **Migrate from Message Cards to Adaptive Cards** for Teams notifications.
+- **Adjust your message formatting** (Adaptive Cards use structured blocks instead of Markdown).
+
+### Breaking Changes
+- **Message Cards are no longer supported**
+- **O365 Connectors cannot be used**; users must create new webhooks with Workflows
+- **Adaptive Cards require structured content blocks** instead of Markdown formatting
+
+### Upgrade Steps
+
+#### 1. Create a New Webhook
+Since O365 Connectors are being deprecated, you must create a new incoming webhook using Microsoft Teams Workflows:
+
+[Official Microsoft Guide](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498)
+
+Once created, update your `.env` file with the new webhook URL:
+
+```env
+MICROSOFT_TEAMS_NOTIFICATION_WEBHOOK_URL=https://your-new-webhook-url
+```
+
+Update `config/services.php` to reference the new webhook:
+
+```php
+'microsoft_teams' => [
+    'notification_webhook_url' => env('MICROSOFT_TEAMS_NOTIFICATION_WEBHOOK_URL'),
+]
+```
+
+#### 2. Replace Message Cards with Adaptive Cards
+##### Before (Message Cards):
+
+```php
+return MicrosoftTeamsMessage::create()
+            ->to(config('services.microsoft_teams.notification_webhook_url'))
+            ->type('success')
+            ->title('Subscription Created')
+            ->content('Yey, you got a **new subscription**. Maybe you want to contact him if he needs any support?')
+            ->button('Check User', 'https://foo.bar/users/123');
+```
+
+##### After (Adaptive Cards):
+
+```php
+return MicrosoftTeamsAdaptiveCard::create()
+    ->to(config('services.microsoft_teams.notification_webhook_url'))
+    ->title('Subscription Created')
+    ->content([
+        TextBlock::create()
+            ->setText('Yey, you got a **new subscription**. Maybe you want to contact him if he needs any support?')
+            ->setWeight('Bolder')
+            ->setSize('Large'),
+    ])
+    ->actions([
+        ActionOpenUrl::create()
+            ->setTitle('Check User')
+            ->setUrl('https://foo.bar/users/123'),
+    ]);
+```
+
+### Additional Resources
+- **Microsoft Announcement on O365 Connector Deprecation:** [Read here](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/)
+- **Adaptive Cards Documentation:** [Visit AdaptiveCards.io](https://adaptivecards.io/)
+ 

src/Actions/ActionOpenUrl.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace NotificationChannels\MicrosoftTeams\Actions;
+
+class ActionOpenUrl
+{
+    /** @var string Property Type */
+    protected $type = 'Action.OpenUrl';
+
+    /** @var string Title of the Action */
+    protected $title;
+
+    /** @var string $mode Mode of the Action. (Primary, Secondary) */
+    protected $mode;
+
+    /** @var string $mode Style of the Action Button. (Positive, Destructive) */
+    protected $style;
+
+    /** @var string $url URL the Action goes to. */
+    protected $url;
+
+    /**
+     * @return self
+     */
+    public static function create(): self
+    {
+        return new self();
+    }    
+
+    /**
+     * Set the title.
+     *
+     * @param string $title
+     * 
+     * @return ActionOpenUrl
+     */
+    public function setTitle(string $title) : self
+    {
+        $this->title = $title;
+        return $this;
+    }
+
+    /**
+     * Set the mode.
+     *
+     * @param string $mode
+     * 
+     * @return ActionOpenUrl
+     */
+    public function setMode(string $mode) : self
+    {
+        $this->mode = $mode;
+        return $this;
+    }
+
+    /**
+     * Set the style.
+     *
+     * @param string $style
+     * 
+     * @return ActionOpenUrl
+     */
+    public function setStyle(string $style) : self
+    {
+        $this->style = $style;
+        return $this;
+    }
+
+    /**
+     * Set the url.
+     *
+     * @param string $url
+     * 
+     * @return ActionOpenUrl
+     */
+    public function setUrl(string $url) : self
+    {
+        $this->url = $url;
+        return $this;
+    }
+
+    /**
+     * Returns Action properties as an array.
+     *
+     * @return array
+     */
+    public function toArray() : array
+    {
+        return [
+            'type' => $this->type,
+            'title' => $this->title,
+            'mode' => $this->mode,
+            'style' => $this->style,
+            'url' => $this->url
+        ];
+    }
+}