Input.ChoiceSet auto complete

Summary

When there are thousands of choices in a menu (like assigning a task to someone, when there’s thousands of people in your org), you need to have a searchable select menu that dynamically loads data as the user searches (since including 1,000 or more choices statically in the card/data isn’t a good option).

---

Status: Proposal Approved

---

Open Issues

• Need to investigate the different platform limitations and cost with regard to isMultiSelect support.

Requirements

1. P0: The input can dynamically fetch the list of choices from a remote backend as the user types

2. P0: Hosts can specify 1 or more pre-determined datasets that get the first-chance to fulfill the request. (E.g., Microsoft Teams could query the Active Directory list of users by hooking into the graph.microsoft.com/users dataset). If the host hasn’t registered a matching dataset, the request will be sent to the backend.

3. P0: A static list of choices can be provided, and any dynamic ones will get appended to the end

4. P1: The input will support "isMultiSelect": true and "style": "compact" where possible

5. P1: Search dynamically renders a list (which has custom UI for each element) with the search result

Spec/schema

Input.ChoiceSet

Property
Type
Required
Description
choices.data
Data.Query
No
Enables dynamic autocomplete as the user types, by fetching a remote set of choices from a backend

Data.Query

Data.Query includes the metadata necessary to fetch remote data.

Property
Type
Required
Description
dataset
string
Yes
The type of data that should be fetched dynamically

Host-Specific Datasets (Such as the User directory)

Some Hosts, such as Microsoft Outlook and Microsoft Teams, will allow the Input.ChoiceSet to bind to pre-configured datasets, such as the current User directory.

Microsoft Datasets

Dataset
Description
graph.microsoft.com/users
The full list of users within the organization
graph.microsoft.com/users?scope=currentContext
The list of users within the “current context”, which will be determined by the Host. For example, in a Microsoft Teams Channel, it would be the list of users in the current channel

Example

Step 1: Card Payload

{
    "type": "Input.ChoiceSet",
    "id": "selectedUser",
    "choices": [
        { "title": "Static 1", "value": "Static 1" }
    ],
    "choices.data": {
        "type": "Data.Query",
        "dataset": "graph.microsoft.com/users"
    }
}

Step 2: Setup a backend to fulfill the request

As the user types, the renderer will create a JSON object that includes all the properties from the Data.Query, along with what the user has typed, plus any additional options such as the current skip/count and max results to be returned.

{
        "type": "Data.Query",
        "dataset": "graph.microsoft.com/users",
    "value": "",
        "count": 25, 
        "skip: 0
}

Universal Action Model support:
Out of the box we will include support for the Universal Action model, allowing a Bot developer to easily handle the request and respond with the list of choices.

The format will be as follows:

{
  "type": "invoke",
  "name": "adaptivecard/action",
  "value": {
    "action": {
        "type": "Data.Query",
        "dataset": "graph.microsoft.com/users",
    "value": ""
    }
}

Step 3: Backend responds with array of choices

The backend will inspect the Data.Query to determine what type of data should be fetched, and what the user has currently typed.

E.g., if the user had typed “Ma” it would return something like:

[
   { "title": "Matt", "value": "1" },
   { "title": "Mark", "value": "2" }
   { "title": "Mack", "value": "3" }
   { "title": "May", "value": "4" }
]

Step 4: Display the results

The Input choices property is set to the array returned by the backend and renders as specified by the isMultiSelect and style properties.

[jankratochvilcz]

@matthidinger this is something we could really use on the Doist side. I wonder if there’s any timeline for GA you could share?

[dclaux]

@matthidinger yes, one word all lowercase.