Idea: Bot.Builder.Community.Cards

[v-kydela]

I believe the only mention of Adaptive Cards in the Bot Builder SDK is in the Node SDK's CardFactory. I don't think there's any mention of Adaptive Cards in the .NET SDK.

As a Bot Framework support engineer, I see many recurring tasks that people want Adaptive Cards to perform in their bots. While there is already an Adaptive Cards NuGet package that provides some helpful models that bots can use, I think it would be even more helpful if there was an Adaptive Cards package that contained bot-specific functionality.

@mdrichardson has already created an Adaptive Card prompt that we have talked about making into a Bot Builder Community package. Since then, I've given some thought into whether we should have AdaptiveCardPrompt as its own package or include it in a package among other Adaptive Card utilities. Here is a short list of tools that I think would work well in an Adaptive Cards package:

1. Translate cards - example: 1
2. Disable cards - examples: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
3. Dynamically add or remove elements to already-posted Adaptive Cards (only on channels that support message updates) - examples: 1, 2
4. Automatically generate a card based on a data structure, the way FormFlow generates a dialog based on the information that needs to be gathered

Disabling Adaptive Cards is already built into Michael's Adaptive Card prompt, but it's possible that people might also want that kind of functionality without using a prompt. I listed my Adaptive Card prompt ideas in Michael's DCR, but I'll reiterate a short list of points about what Adaptive Card prompts are supposed to do here:

1. Only accept input from specific cards that are bound to the prompt
2. Allow both customized and automatic field validation
3. Provide feedback about faulty input

I plan to work on this myself, so I am not making this post as a request for other people to work on it. I just want this to be a place to keep track of my ideas and get feedback from the community.

Update Jan 13, 2020:

I need to release v0.1 with only the features I've completed so far (or that I'm about to complete) in order to meet my Jan 31 deadline. This means the Adaptive Card Builder (idea 5) and the Action Prompt (my renamed version of the Adaptive Card prompt) will have to wait for another release. Here's a checklist that might give a better idea of the scope of this library and my progress:

Card Translation

• [x] Translate Adaptive Cards
• [ ] Translate Bot Framework cards

Card Management

• [x] Apply ID's to actions
• [x] Disable cards by tracking ID's in bot state
• [x] Disable cards by updating their activities
• [ ] Dynamically add or remove card elements
• [x] Adapt card actions between channels
• [ ] Adapt submit actions between channels (Teams vs non-Teams)

Adaptive Card Builder

• [ ] Generate an Adaptive Card based on a C# type

Action Prompt

• [ ] Return values retrieved from a Bot Framework card or an Adaptive Card
• [ ] Bind a specific card or cards to a prompt so input is not accepted from other cards
• [ ] Validate Adaptive Card fields and give feedback for invalid entries

Testing

• [x] Translation tests
• [x] Management tests
• [ ] Builder tests
• [ ] Prompt tests

Documentation

• [x] Samples
• [x] Readme file(s)
• [ ] Comments in code

Other languages

• [ ] Node
• [ ] Python
• [ ] Java

Track my progress

https://github.com/BotBuilderCommunity/botbuilder-community-dotnet/tree/feature/cards/libraries/Bot.Builder.Community.Cards

Update Jan 28, 2021:

The cards library has been merged into the develop and master branches

Update Feb 18, 2021:

The cards library is on NuGet: https://www.nuget.org/packages/Bot.Builder.Community.Cards/

[v-kydela]

@garypretty - Would you accept such a package?

[garypretty]

Hey @v-kydela - absolutely. This sounds great. Apologies for the late reply. Work is pretty crazy so I don't get here as much as I want 🙄

[v-kydela]

I've updated the post with another idea

[garypretty]

@v-kydela I think it might be a good idea for us to have a call and agree if any of the above might actually make sense in the core SDK. I spoke with @cleemullins a few weeks ago about Adaptive Cards and I think if there are sensible core scenarios we want to light up, then there might be appetite for this. Anything that falls outside of the core scenarios could then be added to the community repo. I will drop something in our calendars to talk.

[CoHealer]

Is this still a follow up item Gary? Perhaps for R8/9?

[garypretty]

@CoHealer I believe the Adaptive Card prompt is now a candidate for R8? I know there is an open PR from @mdrichardson (https://github.com/microsoft/BotBuilder-Samples/pull/1986). What I am unsure about is if the agreement was just for a prompt or for a broader package.@mdrichardson / @v-kydela can you confirm?
If just the prompt is headed for the SDK, @v-kydela are you still open to adding an adaptive cards package here in the community with the other ideas you highlighted above?

[v-kydela]

@garypretty - Yes, I am still working on it. I've already made idea 1.

[v-kydela]

I should mention that the scope of this idea has increased somewhat since I think that much of what people want to do with Adaptive Cards also applies to other rich cards (like disabling them), so I'm now just calling this the cards library. I've been working on this pretty heavily over the last month and I've been pushing my progress in the feature/cards branch.

[v-kydela]

Progress update: the project is mostly divided into the Translation folder and the Management folder, with the Management folder being many times more complicated. It handles card tracking by exposing functionality in three major classes: ManagementExtensions (for operations that don't use bot state), CardManager (which requires a state accessor), and CardManagerMiddleware (which uses a card manager). I have written tests for ManagementExtensions and CardManager. Once I've finished the tests for CardManagerMiddleware then I'll be able to create a card manager sample and finally demo this project.

I think a big reason why this took a lot longer than I anticipated was because of the decision to include Bot Framework rich cards because I have to take many different situations into consideration. Adaptive Cards are pretty consistent with how they work, but rich cards behave a lot more differently on different channels than I realized and my library attempts to adapt their functionality. It wasn't a bad decision, but if I was just doing Adaptive Cards then I may have gotten to this point at least a month sooner.

Once a usable version of the current cards library is released as a NuGet package, I will move on to the Adaptive Card builder portion and action prompt portion of the library. I have my hopes up that they won't be quite as time-consuming.

[v-kydela]

I've finished the middleware tests and I built a working sample in the branch feature/cards/sample. I plan on merging that branch into feature/cards before it gets merged into master.

In preparation for demoing the cards library, I've built this mermaid diagram to help visualize the four "action data ID" scopes and their relationship to the "card tree."

To explain, action data is the term I came up with to refer to the hidden metadata that goes in postBack and messageBack actions as well as submit actions. The management portion of the cards library works by putting ID's in the action data so that the actions can be identified when the bot gets the action data back from the user. The four scopes refer to how much is getting disabled. The cards library can disable just the one action or the card the action came from or the entire carousel of cards or a "batch" which is multiple carousels associated with each other.

The card tree is a data structure I made to allow the cards library to easily perform "get all" tasks. The library can recurse through the tree by entering and exiting the tree at any point. For example, if I have a list of attachment objects and I want to get all the submit actions found in all the Adaptive Cards in those attachments, I can use the same method that I use to get all the action data ID's from an activity. Without the card tree, I'd need to build a whole new set of functionality every time that sort of requirement came up.

[v-kydela]

I decided to remove the "preserve values" functionality since that was only intended for Teams and it seems that Teams now does this automatically. The functionality would be useless now, though I've seen one person want to reverse the functionality by going back to the old behavior, so the library may have a "reset values" feature at some point.