Adaptive Cards

Adaptive cards allows rich display of information in the chat. They are a great fit for bots when you want to render rich text with graphics, provide buttons to allow people to interact with the chat, create interactive forms and collect input from users.

In DRUID you author a card once and have it render beautifully inside your own website (web channel) or Microsoft Teams app.

You’ll see a couple of examples of adaptive cards below:

Adding and configuring Adaptive Cards steps

To add and configure an Action step in a DRUID flow:

1. Open the desired flow in Flow Diagram view.
2. Expand the Flow Palette, then drag the Adaptive Card step from the Dialog category into the main flow window and drop it onto the step you want to link it to.
3. Select the step on the diagram, then click the Settings icon from the Actions menu.
4. Set the following General parameters:

Parameter	Description
Step name	Enter a descriptive name for the step to clarify its purpose.
Step message	(Optional) Enter the message the bot will display when it reaches this step before showing the adaptive card.
Input mapping	Note:  To capture what the user says use the adaptive card editor and configure the adaptive card directly. DO NOT use Input mapping on the flow step as it does not have any effect on steps of type Adaptive cards.
Hide in conversation history	Anonymizes sensitive data from Input mapping (what the user says) in the conversation history.
Disable intent switch	Prevents the bot from doing intent change and keep users in a specific flow whenever data validation fails or when after a step with input mapping when evaluating user input no conditions are met. For more information about this options, see General.

5. Click on the Metadata section header. The section expands.
6. If you want to prevent users from clicking the card twice (or submit field values), tap on Inactivate card after usage.
Note:  This option is available only on bot framework v4 and works only on DirectLine (web channel).
7. Click the Adaptive card editor button ().
8. Design the adaptive card based on your needs. For information on how to use the editor, see Adaptive Card Editor.
Hint:  Customize adaptive cards to suit specific contextual needs using the Code Extension feature. For further details, refer to Manipulate adaptive cards based on context.
9. Click the Save button at the top-right side of the editor to save the adaptive card. The editor closes.
10. Click  Save to save the step configuration.

If you want to put information into a specific context, you can do so, by setting variables on the step. For more information, see Set Variable.

You can also set specific actions to be executed before or after the flow step execution. For more information, see Pre Actions or Post Actions.

Adaptive Card Editor

The image below shows the Adaptive Cards Editor user interface.

The editor consists of the following areas:

1. The visual representation of the adaptive card. You can select and rearrange card objects.
2. Elements menu you can drag and drop into your card to customize it as best suits your needs.
3. A visual tree view of the adaptive card that corresponds to the actual JSON data.
4. Properties for the selected object. You can customize object data such as Label text and Placeholder.
5. The live JSON data of the card. You can set the objects properties directly in the JSON (if you prefer using it instead of the properties at the right side of the editor).
6. Sample Data Editor. Displays the JSON object of the entity provided in Input mapping on the step (if any).

Prevent element properties from being translated at runtime

If SDL machine translation is set on the bot and you want to prevent a specific element property from being translated, in the Card Payload Editor, add the property "<propertyName>#notranslate" to the desired element and set it to true. The <propertyName> is the name of the property to be ignored by machine translation at runtime.

Example:

In this example we prevent the label "Name" from being translated at runtime. In the Card Payload Editor, we identify the label "Name" and add set the following property: "label#notranslate": true.

Capturing user input

To capture user input and further use it during the conversation, in the visual tree view of the adaptive card, select the desired input object (input text, input date, input time, input number, input toggle, action) and in the object properties, Id field, enter the DRUID entity field that will store what the user says, using the following format: ${Entity.Field}. You can also add it directly in the JSON data.

DRUID supports Microsoft Adaptive Cards Template Language

Rendering multiple items from a DRUID collection

To render multiple items based on a DRUID collection, on the adaptive card at runtime in the chat, follow these language rules:

• Bound the Adaptive Card element's $data property to a DRUID collection. The element itself will be repeated for each item in the collection.
• Any binding expressions (${myProperty}) used in property values will be scoped to the individual item within the array.
• If binding to a collection of strings, use ${$data} to access the individual string element. E.g., "text": "${$data}".

Handle adaptive cards with multiple buttons using input text

Submitting an adaptive card means sending an adaptive card in the conversation after the bot executes it. When your adaptive card contains multiple submit buttons and you want the bot to continue the conversations based on what button the user clicked, use input text on each button by adding a hardcoded set variable in the Data object of the button using the following format: {"[[Entity]].Field":"<desired input text>"} and design your conversation flow to accommodate the user input / selection on the multiple buttons available in the adaptive card.

For that you can use conditions on steps, execute specific subsequent steps(s) if condition [[Entity]].Field == <desired input text set on specific button> is met.

Example: An adaptive card that has two buttons: Submit and Cancel. The bot will address user’s selection differently.

Adaptive card buttons configuration

The flow was designed to address the user’s selection during the adaptive card execution (select one of the two buttons available) as follows:

• Step submit will be executed if condition [[Account]].BookingStatus == submit is met (that is, the user clicks the Submit button in the chat).
• Step cancel will be executed if condition [[Account]].BookingStatus == cancel is met (that is, the user clicks the Cancel button in the chat).

When the user clicks the Submit button, the bot executes step submit.

When the user clicks the Cancel button, the bot executes step cancel.

Manipulate adaptive cards based on context

When customizing adaptive cards to suit specific contextual needs, the Code Extension feature offers a powerful solution. You can seamlessly manipulate adaptive cards, ensuring they adapt dynamically to changing contexts:

1. Define the adaptive card object tailored to your specific context.
Copy

Example: Build different cards depending on the user authentication state

let adaptiveObject = {};

    //Build different cards depending on the user authentication state
    if ([[ChatUser]].IsAnonymous){
        //for anonymous user we only display the text "Anonymous user"
        adaptiveObject = {
            "type": "AdaptiveCard",
            "body": [
                {
                    "type": "TextBlock",
                    "size": "Medium",
                    "weight": "Bolder",
                    "text": "Anonymous user"
                }
            ],
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "version": "1.3"
        }
    }  else {
        //for authenticated user we display the first name and last name of the user
        let firstName = [[ChatUser]].FirstName;
        let lastName = [[ChatUser]].LastName;

        adaptiveObject = {
            "type": "AdaptiveCard",
            "body": [
                {
                    "type": "TextBlock",
                    "size": "Medium",
                    "weight": "Bolder",
                    "text": firstName
                },
                {
                    "type": "TextBlock",
                    "size": "Medium",
                    "weight": "Bolder",
                    "text": lastName
                }
            ],
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "version": "1.3"
        };
    };

2. Use the JSON.stringify function to convert the adaptive card object into a string format, enhancing its compatibility with the Code Extension feature:
Copy

Example: stringify the adaptive card object

 let adaptiveString = JSON.stringify(adaptiveObject);

3. Assign the JSON object to the adaptive card flow step, enabling it to dynamically adjust based on the defined context:
Copy

Example: assign the jObject to the adaptive card flow step

thisStep.Metadata.AdaptiveCard = thisStep.CreateAdaptiveCardObject(adaptiveString);

4. Ensure the accuracy and functionality of the flow step code by validating it using:
Copy

thisStepValidator.Validate(thisStep);