Bot ACEs Schema - SharePoint/Bot-Powered-ACE-Preview GitHub Wiki

Bot Framework SDK Schema

Methods

OnSharePointTaskGetCardViewAsync

When the bot-driven ACE is loading on the dashboard in either read mode or edit mode, a call to OnSharePointTaskGetCardViewAsync will be sent to the bot whereby the bot can respond to that user action. The bot should return a GetCardViewResponse here.

OnSharePointTaskGetQuickViewAsync

When the quick view of the bot-driven ACE is loading, a call to OnSharePointTaskGetQuickViewAsync will be sent to the bot whereby the bot can respond to that user action. The bot should return a GetQuickViewResponse here.

OnSharePointTaskGetPropertyPaneConfigurationAsync

When the bot-driven ACE is being edited in edit mode, a call to OnSharePointTaskGetPropertyPaneConfigurationAsync will be sent to the bot whereby the bot can respond to that user action. The bot should return a GetPropertyPaneConfigurationResponse here.

OnSharePointTaskSetPropertyPaneConfigurationAsync

When edits to the bot-driven ACE have been made in the property pane and 'apply' has been clicked, a call to OnSharePointTaskSetPropertyPaneConfigurationAsync will be sent to the bot whereby the bot can respond to that user action. The bot should return a SetPropertyPaneConfigurationResponse with an option RenderArguments to render a new Card view.

OnSharePointTaskHandleActionAsync

When a user action emits an Action.Submit or an Action.Execute action, a call to OnSharePointTaskHandleActionAsync will be sent to the bot whereby the bot can respond to that user action. The bot should return a HandleActionResponse with an option RenderArguments to render a new view, either Card view or QuickView view.

Schema

AceData

Property jsonPropertyName Type IsRequired Description
CardSize cardSize AceData.AceCardSize yes Determines whether the card will be a Medium or Large card
DataVersion dataVersion string no 1.0
Id id string yes the microsoft app id for your bot
Title title string yes Title displayed in bot-driven ACE's header area
IconProperty iconProperty string yes The url of the icon to display
Description description string yes Description for bot-driven ACE
Properties properties any no (required for SignInCardView) Property bag for bot-driven ACE

Requires 'uri' and 'connectionName' properties for Sign In Card View

AceData.AceCardSize

Enum Value
Medium "Medium"
Large "Large"

ActionButton

Property jsonPropertyName Type IsRequired Description
Title title string yes text displayed on the button
Action action IAction yes action associated with the button

BaseCardParameters

Property jsonPropertyName Type IsRequired Description
IconProperty iconProperty string no The url of the icon to display
IconAltText iconAltText string no The icon alt text
Title title string no The title to display

BasicCardParameters

extends BaseCardParameters and implements ICardParameters

Property jsonPropertyName Type IsRequired Description
PrimaryText primaryText string yes primary text displayed in the basic card view

BasicCardViewResponse

implements ICardViewResponse

Property jsonPropertyName Type IsRequired Description
AceData aceData AceData no metadata associated with the ACE
Data data BasicCardParameters yes data needed to render the desired card view, please use the parameters class that matches the type of card view required
OnCardSelection onCardSelection IOnCardSelectionAction no action parameters for the action to be performed when the ACE is clicked on
CardButtons cardButtons [ActionButton] no button(s) to be rendered on the card. Please keep in mind, only one button may be displayed when the card is Medium sized, whereas two buttons may be displayed when it is Large sized
ViewId viewId string yes id associated with the card view

ConfirmationDialog

Property jsonPropertyName Type IsRequired Description
Title title string yes title of confirmation dialog
Message message string yes message displayed in confirmation dialog

ExecuteAction

implements IAction

Property jsonPropertyName Type IsRequired Description
Parameters parameters Dictionary<string, Object> (C#)
{[key: string]: unknown} {Node)		 yes overridden parameters property for Action.Execute
Verb verb string no verb associated with this action

ExternalLinkActionParameters

Property jsonPropertyName Type IsRequired Description
IsTeamsDeepLink isTeamsDeepLink boolean no Indicates whether this is a Teams Deep Link
Target target string yes external link to navigate to

FocusParameters

Property jsonPropertyName Type IsRequired Description
FocusTarget focusTarget string yes Sets the default focus on the DOM. Developers pass in the id of a unique element that is to attain focus within a quick view. If the focusTarget is not defined then the root element is selected.
AriaLive ariaLive FocusParameters.AriaLive no Sets the accessibility reading of the contents within the focus target.
Polite - Content in the target's subtree is read when the user is idle.
Assertive - Disrupts any announcement in favor of the changed contents within the target's subtree.
Off - The screen reader will not read contents within the target's subtree.

FocusParameters.AriaLive

Enum Value
Polite "polite"
Assertive "assertive"
Off "off"

GetLocationActionParameters

implements ICardActionParameters

Property jsonPropertyName Type IsRequired Description
ChooseLocationOnMap chooseLocationOnMap boolean no, defaults to false determines whether a location on the map can be chosen

GetPropertyPaneConfigurationResponse

Property jsonPropertyName Type IsRequired Description
Pages pages [PropertyPanePage] yes array of page objects in the property pane
CurrentPage currentPage number no current page displayed in the property pane
LoadingIndicatorDelayTime loadingIndicatorDelayTime number no Number of milliseconds to be delayed before the loading indicator is shown on the property pane. Default value is 500.
ShowLoadingIndicator showLoadingIndicator boolean no Indicates whether the loading indicator should be displayed on top of the property pane or not

GetQuickViewResponse

implements ISharePointViewResponse

Property jsonPropertyName Type IsRequired Description
Data data IQuickViewData no data used to render the adaptive card template
Template template AdaptiveCard yes template rendered for the quick view
ViewId viewId string yes id associated with the given quick view
Title title string no, title displayed defaults to title property in AceData title displayed in the quick view header
ExternalLink externalLink ExternalLinkActionParameters no external link for when the quick view is clicked on
FocusParameters focusParameters FocusParameters no focus element parameters in the quick view

HandleActionResponse

Property jsonPropertyName Type IsRequired Description
ResponseType responseType HandleActionReponse.ResponseTypeOption yes CardView, QuickView, NoOp
RenderArguments renderArguments ISharepointViewResponse yes, if response type is CardView or QuickView. no, if NoOp the view you want to render

HandleActionReponse.ResponseTypeOption

Enum Value Description
CardView "Card" render a card view
QuickView "QuickView" render a quick view
NoOp "NoOp" no operation needed

IAction

Description Implemented by
Empty interface implemented by acceptable action classes ExecuteAction, ExternalLinkAction, GetLocationAction, QuickViewAction, SelectMediaAction, ShowLocationAction](#ShowLocationAction), SubmitAction

ICardViewResponse

Description Implemented by
Empty interface implemented by acceptable card view response classes ImageCardViewResponse, BasicCardViewResponse , PrimaryTextCardViewResponse, SignInCardViewResponse

ImageCardParameters

extends BaseCardParameters

Property jsonPropertyName Type IsRequired Description
PrimaryText primaryText string yes primary text to be displayed by the image card view
ImageUrl imageUrl string yes url of the image to be displayed by the image card view
ImageAltText imageAltText string no alt text of the image to be displayed by the image card view

ImageCardViewResponse

implements ImageCardParameters

Property jsonPropertyName Type IsRequired Description
AceData aceData AceData no metadata associated with the ACE
Data data BasicCardParameters yes data needed to render the desired card view, please use the parameters class that matches the type of card view required
OnCardSelection onCardSelection IOnCardSelectionAction no action parameters for the action to be performed when the ACE is clicked on
CardButtons cardButtons [ActionButton] no button(s) to be rendered on the card. Please keep in mind, only one button may be displayed when the card is Medium sized, whereas two buttons may be displayed when it is Large sized
ViewId viewId string yes id associated with the card view

IOnCardSelectionAction

Description Implemented by
Empty interface implemented by action parameter classes that can be used for the onCardSelection event QuickViewAction, SelectMediaAction, ShowLocationAction, GetLocationAction

IPropertyPaneFieldProperties

Description Implemented by
Empty interface for property pane field properties PropertyPaneCheckboxProperties, PropertyPaneChoiceGroupProperties, PropertyPaneDropDownProperties, PropertyPaneLabelProperties, PropertyPaneLinkProperties, PropertyPaneSliderProperties, PropertyPaneTextFieldProperties,PropertyPaneToggleProperties

IPropertyPaneGroupOrConditionalGroup

Description Implemented by
Empty interface for property pane group or conditional group PropertyPaneGroup

IQuickViewData

Description Implemented by
Empty interface for data used to render the quick view N/A

ISharePointViewResponse

Description Implemented by
Empty interface for view response classes ICardViewResponse, GetQuickViewResponse

Location

Property jsonPropertyName Type IsRequired Description
Latitude latitude number yes latitude coordinates of location
Longitude longitude number yes longitude coordinates of location
Timestamp timestamp number no Timestamp
Accuracy accuracy number no Accuracy of the location

PrimaryTextCardViewResponse

implements ICardViewResponse

Property jsonPropertyName Type IsRequired Description
AceData aceData AceData no metadata associated with the ACE
Data data PrimaryTextCardParameters yes data needed to render the desired card view
OnCardSelection onCardSelection IOnCardSelectionAction no action parameters for the action to be performed when the ACE is clicked on
CardButtons cardButtons [ActionButton] no button(s) to be rendered on the card. Please keep in mind, only one button may be displayed when the card is Medium sized, whereas two buttons may be displayed when it is Large sized
ViewId viewId string yes id associated with the card view

PrimaryTextCardParameters

extends BaseCardParameters

Property jsonPropertyName Type IsRequired Description
PrimaryText primaryText string yes primary text displayed for a primary text card view
Description description string yes description displayed for a primary text card view

PropertyPaneCheckboxProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
Text text string no text displayed for a checkbox field in the property pane
Disabled disabled boolean no, defaults to false whether the checkbox is enabled
Checked checked boolean no whether the checkbox is checked

PropertyPaneChoiceGroupIconProperties

Property jsonPropertyName Type IsRequired Description
OfficeFabricIconFontName officeFabricIconFontName string no name of the icon to use from the Office Fabric icon set

PropertyPaneChoiceGroupImageSize

Property jsonPropertyName Type IsRequired Description
Width width number yes width of the image
Height height number yes height of the image

PropertyPaneChoiceGroupOption

Property jsonPropertyName Type IsRequired Description
AriaLabel ariaLabel string no aria label for the given control
Disabled disabled boolean no whether the control is enabled
Checked checked boolean no whether the control is checked
IconProps iconProps PropertyPaneChoiceGroupIconProperties no properties for the icon associated with the control
ImageSize imageSize PropertyPaneChoiceGroupImageSize no size of the image for the control
ImageSrc imageSrc string no source url for the image of the control
Key key string yes required key to uniquely identify the option
Text text string yes text displayed for the control

PropertyPaneChoiceGroupProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
Label label string no label for the choice group
Options options [PropertyPaneChoiceGroupOption] yes array of choice group options for this choice group

PropertyPaneDropDownOption

Property jsonPropertyName Type IsRequired Description
Index index number no the index for this option
Key key string yes key to uniquely identify this option
Text text string yes text displayed for this option
Type type PropertyPaneDropDownOption.DropDownOptionType no, defaults to PropertyPaneDropDownOption.DropDownOptionType.Normal type of dropdown

PropertyPaneDropDownOption.DropDownOptionType

Enum Value Description
Normal 0 render normal menu item
Divider 1 render a divider
Header 2 render menu item as a header

PropertyPaneDropDownProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
AriaLabel ariaLabel string yes aria label for the given control
AriaPositionInSet ariaPositionInSet number no cDefines an element's number or position in the current set of controls. Maps to native aria-posinset attribute. It starts from 1.
AriaSetSize ariaSetSize number no defines the number of items in the current set of controls. Maps to native aria-setsize attribute.
Label label string yes descriptive label for the Dropdown
Disabled disabled boolean no whether the control is enabled
ErrorMessage errorMessage string no If set, this will be displayed as an error message
SelectedKey selectedKey string no key of selected drop down option
Options options [PropertyPaneDropDownOption] no Collection of options for this Dropdown

PropertyPaneGroup

implements IPropertyPaneGroupOrConditionalGroup

Property jsonPropertyName Type IsRequired Description
GroupFields groupFields [PropertyPaneGroupField] yes array of fields part of this group
GroupName groupName string no name of the group
IsCollapsed isCollapsed boolean no, defaults to false whether the group is collapsed in the property pane
IsGroupNameHidden isGroupNameHidden boolean no whether the group name is hidden

PropertyPaneGroupField

Property jsonPropertyName Type IsRequired Description
Type type PropertyPaneGroupField.FieldType yes type of property pane group field
TargetProperty targetProperty string yes key of targeted property
Properties properties IPropertyPaneFieldProperties yes properties of the group field
ShouldFocus shouldFocus boolean no, defaults to false whether this control should be focused on

PropertyPaneGroupField.FieldType

Enum Value
CheckBox 2
TextField 3
Toggle 5
Dropdown 6
Label 7
Slider 8
ChoiceGroup 10
HorizontalRule 12
Link 13
DynamicField 14
DynamicFieldSet 16
SpinButton 17
ThumbnailPicker 18
IconPicker 19

PropertyPaneLabelProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
Text text string yes text of label property
Required required boolean no, defaults to false whether the label is required

PropertyPaneLinkPopupWindowProperties

Property jsonPropertyName Type IsRequired Description
Width width number yes width of the popup
Height height number yes height of the popup
Title title string yes title of the popup
PositionWindowPosition positionWindowPosition PropertyPaneLinkPopupWindowProperties.PopupWindowPosition yes position of popup

PropertyPaneLinkPopupWindowProperties.PopupWindowPosition

Enum Value
Center 0
RightTop 1
LeftTop 2
RightBottom 3
LeftBottom 4

PropertyPaneLinkProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
Text text string yes text of link property
Target target string no this attribute specifies where to display the linked resource.
Href href string yes Location to which the link is targeted to
AriaLabel ariaLabel string no aria label for the property pane link
Disabled disabled boolean no whether the control is enabled
PopupWindowProps popupWindowProps PropertyPaneLinkPopupWindowProperties no properties for the popup window

PropertyPanePage

Property jsonPropertyName Type IsRequired Description
DisplayGroupsAsAccordion displayGroupsAsAccordion boolean no whether the groups on the PropertyPanePage are displayed as accordion or not
Groups groups [IPropertyPaneGroupOrConditionalGroup] yes array of property pane groups belonging on this page
Header header string PropertyPanePageHeader no

PropertyPanePageHeader

Property jsonPropertyName Type IsRequired Description
Description description string yes description of the header

PropertyPaneSliderProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
Label label string no label for the slider
Value value string no, defaults to min value of the slider
AriaLabel ariaLabel string no aria label for the given control
Disabled disabled boolean no whether the control is enabled
Max max number yes max value of the slider
Min min number yes min value of the slider
Step step number no, defaults to 1 difference between the two adjacent values of the Slider
ShowValue showValue boolean no whether value of slider is shown

PropertyPaneTextFieldProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
Label label string no label for the slider
Value value string no value of the slider
AriaLabel ariaLabel string no aria label for the given control
DeferredValidationTime deferredValidationTime number no amount of time to wait before validating after the users stop typing in ms
Description description string no description displayed for the text field
Disabled disabled boolean yes whether the control is enabled
ErrorMessage errorMessage string yes no
LogName logName {moduleName: string, controlName: string} no Name used to log PropertyPaneTextField value changes for engagement tracking
MaxLength maxLength number no max length of text field
Multiline multiline boolean no whether or not the text field is a multiline text field
Placeholder placeholder string no placeholder text for the text field
Resizable resizable boolean no whether or not the text field is resizable
Rows rows number no value that specifies the visible height of a text area(multiline text TextField) in lines
Underlined underlined boolean no whether or not the text field is underlined
ValidateOnFocusIn validateOnFocusIn boolean no whether to run validation when the PropertyPaneTextField is focused
ValidateOnFocusOut validateOnFocusOut boolean no whether to run validation when the PropertyPaneTextField is out of focus or on blur

PropertyPaneToggleProperties

implements IPropertyPaneFieldProperties

Property jsonPropertyName Type IsRequired Description
AriaLabel ariaLabel string no aria label for the given control
Label label string no label for the slider
Disabled disabled boolean no whether the control is enabled
Checked checked boolean no whether the toggle is checked
Key key string no key to uniquely identify the field
OffText offText string no text to display when toggle is OFF
OnText onText string no text to display when toggle is ON
OnAriaLabel onAriaLabel string no text for screen-reader to announce when toggle is ON
OffAriaLabel offAriaLabel string no text for screen-reader to announce when toggle is OFF

QuickViewAction

implements IAction, IOnCardSelectionAction

Property jsonPropertyName Type IsRequired Description
Parameters parameters QuickViewActionParameters yes parameters for given action

QuickViewActionParameters

Property jsonPropertyName Type IsRequired Description
View view string yes view id of the desired quick view

SelectMediaAction

implements IAction, IOnCardSelectionAction

Property jsonPropertyName Type IsRequired Description
Parameters parameters SelectMediaActionParameters yes parameters for given action

SelectMediaActionParameters

Property jsonPropertyName Type IsRequired Description
MediaType mediaType SelectMediaActionParameters.MediaType yes type of media to be selected
AllowMultipleCapture allowMultipleCapture boolean no whether multiple files can be selected
MaxSizePerFile maxSizePerFile number no max size per file selected
SupportedFileFormats supportedFileFormats string[] no supported file formats of select media action

SelectMediaActionParameters.MediaType

Enum Value
Image 1
Audio 4
Document 8

SetPropertyPaneConfigurationResponse

Property jsonPropertyName Type IsRequired Description
ResponseType responseType SetPropertyPaneConfigurationResponse.ResponseTypeOption yes CardView, NoOp
RenderArguments renderArguments ISharepointViewResponse yes, if response type is CardView or QuickView. no, if NoOp the view you want to render

SetPropertyPaneConfigurationResponse.ResponseTypeOption

Enum Value Description
CardView "Card" render a card view
NoOp "NoOp" no operation needed

ShowLocationAction

implements IAction, IOnCardSelectionAction

Property jsonPropertyName Type IsRequired Description
Parameters parameters ShowLocationActionParameters yes parameters for given action

ShowLocationActionParameters

Property jsonPropertyName Type IsRequired Description
LocationCoordinates locationCoordinates Location no, defaults to current location location to be shown by show location action

SignInCardParameters

extends BaseCardParameters

Property jsonPropertyName Type IsRequired Description
PrimaryText primaryText string yes primary text displayed in the sign in card view
Description description string yes description displayed in the sign in card view
SignInButtonText signInButtonText string yes text displayed on the sign in button

SignInCardViewResponse

implements ICardViewResponse

Property jsonPropertyName Type IsRequired Description
AceData aceData AceData no metadata associated with the ACE
Data data SignInCardParameters yes data needed to render the desired card view, please use the parameters class that matches the type of card view required
OnCardSelection onCardSelection IOnCardSelectionAction no action parameters for the action to be performed when the ACE is clicked on
CardButtons cardButtons [ActionButton] no button(s) to be rendered on the card. Please keep in mind, only one button may be displayed when the card is Medium sized, whereas two buttons may be displayed when it is Large sized
ViewId viewId string yes id associated with the card view

SubmitAction

implements IAction

Property jsonPropertyName Type IsRequired Description
Parameters parameters Dictionary<string, Object> (C#)
{[key: string]: unknown} {Node)		 yes overridden parameters property for Action.Submit
ConfirmationDialog confirmationDialog IConfirmationDialog no confirmation dialog associated with this action
⚠️ **GitHub.com Fallback** ⚠️