added basic/simple adaptive cards support #358

markush81 · 2024-07-29T11:21:41Z

Testing done

Add starting point for AdaptiveCard Support because of Microsofts announcement.

Only manually tested in installation where i am working.

The PR is just meant as starting point to fully implement what is needed (unfortunately i have not the time to add tests and all variants, like check encoding of provided message).

Submitter checklist

Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
Ensure that the pull request title represents the desired changelog entry
Please describe what you did
Link to relevant issues in GitHub or Jira
-- Retirement of Office 365 connectors within Microsoft Teams #355
-- New "workflows" based webhooks are failing #353
-- Add adaptive cards support #297
[n/a] Link to relevant pull requests, esp. upstream and downstream changes
Ensure you have provided tests - that demonstrates feature works or fixes the issue

damianszczepanik · 2024-08-05T15:11:32Z

src/main/java/jenkins/plugins/office365connector/model/Action.java

+
+import java.util.List;
+
+public interface Action {


Action is very generic and very popular class name, how about making ConnectorAction or similar to avoid mismatch in class importing?

Will take CardAction since the new way is not a Connector anymore, but a PowerAutomate Workflow.

damianszczepanik · 2024-08-05T15:12:07Z

src/main/java/jenkins/plugins/office365connector/model/Action.java

+
+    void setName(String name);
+
+    void setTarget(List<String> target);


setTargets since this takes list as a parameter

in general i agree, but currently consistent to https://github.com/jenkinsci/office-365-connector-plugin/blob/master/src/main/java/jenkins/plugins/office365connector/model/PotentialAction.java#L57

then I believe both should be updated to be consistent

damianszczepanik · 2024-08-05T15:16:07Z

src/main/java/jenkins/plugins/office365connector/model/adaptivecard/AdaptiveCard.java

+
+    @Override
+    public void setThemeColor(final String cardThemeColor) {
+


empty method?

yep, haven't used cardThemeColor (because the AdaptiveCard format doesn't really support color - ok with workarounds - it just a fixed enum https://github.com/microsoft/AdaptiveCards/blob/main/schemas/1.4.0/adaptive-card.json#L1494), but too much depends in the old MessageCard on having this method ... so i left it intentionally empty (meaning: not enough time to do necessary refactoring).

damianszczepanik · 2024-08-05T15:16:39Z

src/main/java/jenkins/plugins/office365connector/model/adaptivecard/AdaptiveCardAction.java

+
+import java.util.List;
+
+public class AdaptiveCardAction implements jenkins.plugins.office365connector.model.Action {


why full package name here?

will fix it

damianszczepanik · 2024-08-05T15:18:05Z

src/main/java/jenkins/plugins/office365connector/model/adaptivecard/AdaptiveCardAction.java

+
+    @Override
+    public void setTarget(final List<String> target) {
+        target.stream().findFirst().ifPresent(this::setUrl);


applies only to first element, why is that ?

Old PotentialAction works internally with list https://github.com/jenkinsci/office-365-connector-plugin/blob/master/src/main/java/jenkins/plugins/office365connector/model/PotentialAction.java#L34 cause the format expects that https://learn.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#openuri-action.

But the AdaptiveCard action doesn't https://adaptivecards.io/explorer/Action.OpenUrl.html.
So that's why internally url (single) is used.

As far as i can see, the whole code doesn't add more than one anyway. So a bigger refactoring should/could be, work internally with single attribute and only modify the getTarget in MessageCard to return a list to fulfil the MessageCard JSON format.

markush81 · 2024-08-15T05:58:55Z

two basic integration tests added to have at least "some" coverage.

damianszczepanik · 2024-08-22T18:48:07Z

What I understand from #355 with new approach we need to configure how to convert information from Jenkins into MS Teams even so I am not sure if we need to convert to adaptive card

markush81 · 2024-08-24T07:06:11Z

What I understand from #355 with new approach we need to configure how to convert information from Jenkins into MS Teams even so I am not sure if we need to convert to adaptive card

In can be any Card format which ideally is not deprecated or declared legacy. As far as i understand https://learn.microsoft.com/en-us/outlook/actionable-messages/message-card-reference, the current implemented format is not recommended anymore

Microsoft recommends that new actionable message integrations use the Adaptive Card format, and existing integrations consider updating to Adaptive Card format.

Indeed the same thing says

However, if you are sending actionable messages via an Office connector, or to a Microsoft Teams connector, you must continue to use the message card format.

Which is a) not true (from other applications we were sending Adaptive Cards since more than a year to the mentioned connectors) and b) they retired the connectors.

So IMHO the best way to go forward is, to use AdaptiveCard format.

marssilva · 2024-08-26T21:55:01Z

Hello @markush81 , is it possible to set adaptiveCards as default? "Incoming Webhook" already has native support, it would not impact the current connector and would help in the migration to power automate.

https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?tabs=cURL%2Ctext1#send-adaptive-cards-using-an-incoming-webhook

markush81 · 2024-08-27T09:07:38Z

Hello @markush81 , is it possible to set adaptiveCards as default? "Incoming Webhook" already has native support, it would not impact the current connector and would help in the migration to power automate.

https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?tabs=cURL%2Ctext1#send-adaptive-cards-using-an-incoming-webhook

Technically we can, but i am not sure if there is agreement for what the plugin should do in future.

astrahan87 · 2024-10-02T21:13:40Z

@markush81 Is there any update on the status of this?

markush81 · 2024-10-03T07:30:58Z

@markush81 Is there any update on the status of this?

Since i am not maintainer, i am also waiting for review and merge. IMHO i have done the requested changes a while ago.

astrahan87 · 2024-10-03T16:35:33Z

@damianszczepanik It does look like the requested changes have been made. Is there anything else?

damianszczepanik · 2024-10-09T19:17:01Z

One concern I have is to how to configure the hook. Based on the comments from developers I'm not even sure if we need this change as I found conclusion that with powerautomate you need to translate what is received via webhook into MS Teams message.

So concluding it would be best to update README file as well so this is clear how to configure hook with new addaptive cards and also so I'm able to test it before it gets merged.

markush81 · 2024-10-10T04:40:01Z

One concern I have is to how to configure the hook. Based on the comments from developers I'm not even sure if we need this change as I found conclusion that with powerautomate you need to translate what is received via webhook into MS Teams message.

So concluding it would be best to update README file as well so this is clear how to configure hook with new addaptive cards and also so I'm able to test it before it gets merged.

In the retirement article https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/, they mention the migration:

Post to a channel when a webhook request is received - unfortunately this link is only available with sign in.

I haven't found any good other description, most create it custom and parse the JSON and so on ... but we never did this, we migrated all our webhooks with exactly this template and didn't need to do anything further than that.

kikmon · 2024-10-11T07:16:07Z

That change would be quite useful since manually converting the json in powerautomate is a bit tedious, and doesn't scale that well when you have many hooks
Having this plugin send adaptive cards will be very helpful.

damianszczepanik · 2024-10-11T16:03:42Z

That change would be quite useful since manually converting the json in powerautomate is a bit tedious, and doesn't scale that well when you have many hooks Having this plugin send adaptive cards will be very helpful.

OK, this sounds like question for the answer I didn't get the answer so far!
I will review this one more time, read mentioned docs and merge this.

marssilva · 2024-10-11T17:18:02Z

One piece of information, adaptive cards work in the new flow with powerautomate and in the current Incoming Webhook. As a suggestion, it would be interesting to leave the default adaptive cards, aiming at the future that the current standard is discontinued.

damianszczepanik · 2024-10-12T23:39:10Z

src/main/java/jenkins/plugins/office365connector/Webhook.java


 public class Webhook extends AbstractDescribableImpl<Webhook> {

    public static final Integer DEFAULT_TIMEOUT = 30000;
+    private static final Logger log = LoggerFactory.getLogger(Webhook.class);


added but not used

damianszczepanik · 2024-10-12T23:44:12Z

src/main/java/jenkins/plugins/office365connector/model/adaptivecard/AdaptiveCard.java

+        }
+    }
+
+    private String color(final Result result) {


I guess this should be removed later ?

damianszczepanik · 2024-10-12T23:45:47Z

src/main/java/jenkins/plugins/office365connector/model/adaptivecard/AdaptiveCard.java

+    @SuppressFBWarnings(value = "SS_SHOULD_BE_STATIC")
+    private final String version = "1.4";
+    @SerializedName("msTeams")
+    private final MsTeams msteams = new MsTeams();


if you use msTeams then @SerializedName should be useless and name will be more like Java convention

damianszczepanik · 2024-10-12T23:49:35Z

src/main/java/jenkins/plugins/office365connector/model/adaptivecard/MsTeams.java

+
+public class MsTeams {
+
+    @SuppressFBWarnings(value = "SS_SHOULD_BE_STATIC")


since width is not a final I believe this annotation is not needed here

damianszczepanik · 2024-10-12T23:50:05Z

src/main/java/jenkins/plugins/office365connector/model/adaptivecard/Payload.java

+public class Payload {
+
+    @SuppressFBWarnings(value = "SS_SHOULD_BE_STATIC")
+    private String type = "message";


same here about annotation: annotation or static

damianszczepanik · 2024-10-12T23:51:46Z

src/main/java/jenkins/plugins/office365connector/model/messagecard/MessageCard.java

+public class MessageCard implements Card {
+
+    private String summary;
+    private String themeColor = "3479BF";


is it valid for adaptive cards?

Adaptive Cards and colors are different, there is either a fixed enum which can be used, as done here jenkins.plugins.office365connector.model.adaptivecard.AdaptiveCard#color or do sth. like Semaphore UI does https://github.com/semaphoreui/semaphore/blob/develop/services/tasks/templates/microsoft-teams.tmpl#L44

damianszczepanik · 2024-10-12T23:58:38Z

src/test/java/jenkins/plugins/office365connector/ActionablePotentialActionBuilderTest.java

@@ -24,7 +24,7 @@
 import org.junit.Test;
 import org.mockito.MockedStatic;

-public class ActionableBuilderTest {
+public class ActionablePotentialActionBuilderTest {


there is no class ActionablePotentialActionBuilder so there is something wrong with class name

damianszczepanik · 2024-10-13T00:01:11Z

src/test/resources/requests/adaptivecard_step.json

@@ -0,0 +1,27 @@
+{


name of this file does not pass exactly naming convention others

damianszczepanik · 2024-10-13T00:12:38Z

@markush81 I did review one more time. I have left a few comments but they are not blocking merging this change to master branch. This pull request is significant and valuable.
I have plan to merge #365 and then publish - take a look if you are OK with that
Also share a few details how did you test adaptive cards with this pull request and also are you planing to maintain this for a while before new version with adaptive cards support gets stable?

src/main/java/jenkins/plugins/office365connector/Webhook.java

@@ -201,8 +213,8 @@
            return FormUtils.formValidateUrl(value);
        }

-       public FormValidation doCheckGlobalUrl(@QueryParameter String value) {
-            if(StringUtils.isNotBlank(value)) {
+        public FormValidation doCheckGlobalUrl(@QueryParameter String value) {


src/main/java/jenkins/plugins/office365connector/Webhook.java

@@ -201,8 +213,8 @@
            return FormUtils.formValidateUrl(value);
        }

-       public FormValidation doCheckGlobalUrl(@QueryParameter String value) {
-            if(StringUtils.isNotBlank(value)) {
+        public FormValidation doCheckGlobalUrl(@QueryParameter String value) {


markush81 · 2024-10-13T12:50:29Z

@markush81 I did review one more time. I have left a few comments but they are not blocking merging this change to master branch.

Adjust most of the them.

I have plan to merge #365 and then publish - take a look if you are OK with that

I am fine with the plan.

Also share a few details how did you test adaptive cards with this pull request

We have this version with my PR running since i created it, in our installation - so kinda live-testing.
One point of course, we use Pipeline DSL variant only.

and also are you planing to maintain this for a while before new version with adaptive cards support gets stable?

I can't promise anything, but of course will do my best in case after merge issues occur.

kikmon · 2024-10-15T01:03:16Z

Thanks a lot to you guys :)

damianszczepanik · 2024-10-15T17:28:39Z

@markush81 @kikmon version 5.0.0 has been published

ViliusS · 2024-10-15T21:14:46Z

I'm a little bit confused how to proceed with an upgrade to 5.0.0.

Is there a way to send AdaptiveCard true in a Declarative Pipeline?
Should we switch to new Workflow app webhook on Teams side, or to Incoming Webhook connector, given that currently we are using Jenkins 365 Connector Webhook? Or Jenkins 365 Connector should work fine?

kikmon · 2024-10-16T08:39:09Z

As far as I know, this MR added the parameter adaptiveCards in the declarative pipeline too, so you should be good.
365 connectors will stop working next year, so you might as well start creating your workflows now.
That being said, it would be nice to have a documented 'Best Practice' use case with Workflows and adaptive cards.

movedoa · 2024-10-16T13:24:51Z

What do i need to change in a groovy script to send a success/unstable message.
Currently i use:

office365ConnectorSend webhookUrl: 'url',
            message: "${loStatus} - ${oCurNewVersion}",
            color: loColor
      }

As far as i gathered, color is not supported anymore, ss how would i indicate started/success/failure?
Also do i need to add new parameters to make the plugin send an adaptive card?

An updated documentation would be very nice :)

ViliusS · 2024-10-16T13:41:19Z

OK, I think I figured out the upgrade path:

If you are using Jenkins Connector for Teams with an old webhook URL default settings (adaptiveCards: false) in 5.0.0 will work . You don't need to change anything on Jenkins side.
If you are using Jenkins Connector for Teams with a new improved URL (new URLs will be required by Microsoft as of 2025-02-01) the plugin won't work at all. I guess Jenkins Connector for Teams doesn't support new webhook URLs even though it allows to set them.
If you are using Incoming Webhook Connector for Teams then plugin should work with both adaptiveCards: false and adaptiveCards: true settings. Message formating in Teams channel will be a little bit different, but all essential information will be there.
If you are using Post to a channel when a webhook request is received Power Automate Workflow then you must set adaptiveCards: true. Workflows do not support other message formats.

At least this is how it behaves on my environment and Microsoft 365 tenant.

rdrgporto · 2024-10-16T17:11:34Z

Hi,

An example with Post to a channel when a webhook request is received Power Automate Workflow would be:

post {
 success {
  office365ConnectorSend webhookUrl: '<webhook-url>', 
    message: 'Test with Webhook Microsoft Teams', 
    adaptiveCards: true
 }
}

Regards

damianszczepanik · 2024-10-17T19:17:00Z

Hi,

An example with Post to a channel when a webhook request is received Power Automate Workflow would be:
post {
 success {
  office365ConnectorSend webhookUrl: '<webhook-url>', 
    message: 'Test with Webhook Microsoft Teams', 
    adaptiveCards: true
 }
}
Regards

@rdrgporto would you prepare pull request with updated README file about adaptive cards

damianszczepanik · 2024-10-17T19:19:06Z

@markush81 In #355 (comment) @ViliusS has mentioned that the plugin does not support credentials what is benefit of having adaptive cards but is still not supported by the plugin. How did you fix that problem?

ViliusS · 2024-10-17T19:51:37Z

@damianszczepanik maybe I was not very clear with my comments in another thread. Adaptive Card support in the plugin is working and fine. The issue I was discussing is that someone said that Workflow trigger URL is public, hence insecure. But it was also the case for Incoming Webhook or Jenkins connectors. Nothing has changed regarding security on that part.

BTW, Microsoft actually updated their documentation today: https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/
The timeline for Teams/Oulook Connector deprecation is as follows:

2025-02-01 - All connectors with old webhook URL will stop working. Users must update webhook URLs. So far as I tried, at this point, only Incoming Webhook connector is working with the updated URL. Jenkins connector doesn't work and it doesn't matter which Card format you send. I suspect it needs to be updated somehow to accept new URL format, but I doubt Microsoft will ever do that. Especially considering that that connector only accepts legacy MessageCard messages.
After this day, the only way forward is to use Workflows or general Incoming Webhook connector.
2025 March-April - Microsoft promises to implement MessageCard format support in Workflows.
sometime at the end of 2025 - All Office 365 connectors are discontinued and stops working.
After that, the only working solution is to use Workflows with AdaptiveCard format as recommended, and alternative MessageCard format support if MS keeps their promises.

Thinking about AdaptiveCard support further I would vote to enable it by default now and point plugin users to upgrade instructions, or do it after 2025-02-01 which will probably mark the end of Jenkins connector on MS side anyway.

Also probably plugin naming could be revised again as AdaptiveCards are now implemented by Cisco too. Maybe more implementations will follow. I would vote for something more generalized, like AdaptiveCard sender or Actionable Message sender :)

markush81 · 2024-10-18T04:57:40Z

@markush81 In #355 (comment) @ViliusS has mentioned that the plugin does not support credentials what is benefit of having adaptive cards but is still not supported by the plugin. How did you fix that problem?

There is no authentication, but @ViliusS already commented i see.

markush81 · 2024-10-18T05:01:11Z

As far as i gathered, color is not supported anymore, ss how would i indicate started/success/failure?
Also do i need to add new parameters to make the plugin send an adaptive card?

Coloring in AdaptiveCards works with a fixed set (or adding background images). So far the plugin determines the color based on build result https://github.com/jenkinsci/office-365-connector-plugin/blob/master/src/main/java/jenkins/plugins/office365connector/model/adaptivecard/AdaptiveCard.java#L40.

rdrgporto · 2024-10-18T06:43:25Z

Hi,
An example with Post to a channel when a webhook request is received Power Automate Workflow would be:
post {
 success {
  office365ConnectorSend webhookUrl: '<webhook-url>', 
    message: 'Test with Webhook Microsoft Teams', 
    adaptiveCards: true
 }
}
Regards
@rdrgporto would you prepare pull request with updated README file about adaptive cards

Hi @damianszczepanik,

It would be a example like that in README.md? (after Pipeline post section):

Pipeline post section with Adaptive Cards

pipeline {

    agent any

    stages {
        stage('Init') {
            steps {
                echo 'Hello!'
            }
        }
    }

    post {
        failure {
            office365ConnectorSend webhookUrl: "https://prod.westeurope.logic.azure.com:443/workflows...",
              message: 'Something went wrong', 
              status: 'Failure',
              adaptiveCards: true
        }
    }
}

Thanks in advance,

Regards

damianszczepanik · 2024-10-28T21:18:17Z

Sounds like a good example of how to use new approach - please create PR with updated README file

aksh05 · 2024-10-29T15:20:10Z

@rdrgporto Are you planning to raise a PR with changes to README about the change? If not, would be happy to help create it. Thanks!

rdrgporto · 2024-10-29T15:56:51Z

Hi, @damianszczepanik and @aksh05

I have created a Pull Request:

Add example for Microsoft Teams notification using Adaptive Cards 📩 #367

Thanks in advance,

Regards

markush81 force-pushed the o365-adaptivecards branch from 28ea028 to 2913c95 Compare July 29, 2024 11:22

damianszczepanik force-pushed the o365-adaptivecards branch from 2913c95 to 0723040 Compare August 5, 2024 15:06

damianszczepanik requested changes Aug 5, 2024

View reviewed changes

markush81 force-pushed the o365-adaptivecards branch 2 times, most recently from f366899 to e815b95 Compare August 8, 2024 05:28

damianszczepanik force-pushed the o365-adaptivecards branch from e786256 to 371f5d8 Compare October 9, 2024 18:41

markush81 added 3 commits October 13, 2024 00:10

added basic/simple adaptive cards support

1413b8a

some review comments fixed

5bcc080

added two integration tests to have some coverage

d53d6c5

damianszczepanik force-pushed the o365-adaptivecards branch from 371f5d8 to d53d6c5 Compare October 12, 2024 22:10

damianszczepanik approved these changes Oct 13, 2024

View reviewed changes

final review comments

1541fba

github-advanced-security bot found potential problems Oct 13, 2024

View reviewed changes

damianszczepanik merged commit 76e337a into jenkinsci:master Oct 14, 2024
22 checks passed

damianszczepanik mentioned this pull request Oct 15, 2024

New "workflows" based webhooks are failing #353

Closed


		void setName(String name);

		void setTarget(List<String> target);


		@Override
		public void setThemeColor(final String cardThemeColor) {


		import java.util.List;

		public class AdaptiveCardAction implements jenkins.plugins.office365connector.model.Action {


		public class MsTeams {

		@SuppressFBWarnings(value = "SS_SHOULD_BE_STATIC")

added basic/simple adaptive cards support #358

added basic/simple adaptive cards support #358

Conversation

markush81 commented Jul 29, 2024

Testing done

Submitter checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markush81 Aug 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markush81 Aug 5, 2024 • edited Loading

Choose a reason for hiding this comment

markush81 commented Aug 15, 2024

damianszczepanik commented Aug 22, 2024

markush81 commented Aug 24, 2024 • edited Loading

marssilva commented Aug 26, 2024

markush81 commented Aug 27, 2024

astrahan87 commented Oct 2, 2024

markush81 commented Oct 3, 2024

astrahan87 commented Oct 3, 2024

damianszczepanik commented Oct 9, 2024

markush81 commented Oct 10, 2024 • edited Loading

kikmon commented Oct 11, 2024

damianszczepanik commented Oct 11, 2024

marssilva commented Oct 11, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

damianszczepanik commented Oct 13, 2024

markush81 commented Oct 13, 2024

kikmon commented Oct 15, 2024

damianszczepanik commented Oct 15, 2024

ViliusS commented Oct 15, 2024

kikmon commented Oct 16, 2024

movedoa commented Oct 16, 2024 • edited Loading

ViliusS commented Oct 16, 2024 • edited Loading

rdrgporto commented Oct 16, 2024 • edited Loading

damianszczepanik commented Oct 17, 2024

damianszczepanik commented Oct 17, 2024

ViliusS commented Oct 17, 2024 • edited Loading

markush81 commented Oct 18, 2024

markush81 commented Oct 18, 2024

rdrgporto commented Oct 18, 2024

Pipeline post section with Adaptive Cards

damianszczepanik commented Oct 28, 2024

aksh05 commented Oct 29, 2024 • edited Loading

rdrgporto commented Oct 29, 2024

markush81 Aug 5, 2024 •

edited

Loading

markush81 Aug 5, 2024 •

edited

Loading

markush81 commented Aug 24, 2024 •

edited

Loading

markush81 commented Oct 10, 2024 •

edited

Loading

movedoa commented Oct 16, 2024 •

edited

Loading

ViliusS commented Oct 16, 2024 •

edited

Loading

rdrgporto commented Oct 16, 2024 •

edited

Loading

ViliusS commented Oct 17, 2024 •

edited

Loading

aksh05 commented Oct 29, 2024 •

edited

Loading