{"title":"Extending Teams Cards","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-develop-for-teams-cards/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-for-teams-cards, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-for-teams-cards","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Explains how to use metadata to add custom fields to a Business Central card in Teams","date":"2021-04-01","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Extending Teams Cards","slug":"extending-teams-cards","at":0,"chars":15766},{"level":2,"title":"Extend Teams cards by using field groups","slug":"extend-teams-cards-by-using-field-groups","at":321,"chars":5765},{"level":3,"title":" Understanding the card layout in Teams","slug":"understanding-the-card-layout-in-teams","at":506,"chars":2760},{"level":4,"title":"What fields are displayed","slug":"what-fields-are-displayed","at":988,"chars":619},{"level":4,"title":"How fields are arranged","slug":"how-fields-are-arranged","at":1607,"chars":1659},{"level":3,"title":"Using the Brick field group","slug":"using-the-brick-field-group","at":3266,"chars":2820},{"level":4,"title":"Example","slug":"example","at":4135,"chars":1467},{"level":4,"title":"Extensibility limitations on the Brick field group","slug":"extensibility-limitations-on-the-brick-field-group","at":5602,"chars":484},{"level":2,"title":"Extending Teams cards by using events","slug":"extending-teams-cards-by-using-events","at":6086,"chars":9525},{"level":3,"title":"Event flow","slug":"event-flow","at":7440,"chars":186},{"level":3,"title":"OnBeforeGetPageSummary event","slug":"onbeforegetpagesummary-event","at":7626,"chars":2952},{"level":4,"title":"Syntax","slug":"syntax","at":8010,"chars":340},{"level":4,"title":"Parameters","slug":"parameters","at":8350,"chars":410},{"level":4,"title":"Behavior and recommended use","slug":"behavior-and-recommended-use","at":8760,"chars":499},{"level":4,"title":"Example","slug":"example-1","at":9259,"chars":1319},{"level":3,"title":"OnAfterGetSummaryFields event","slug":"onaftergetsummaryfields-event","at":10578,"chars":2601},{"level":4,"title":"Syntax","slug":"syntax-1","at":10902,"chars":250},{"level":4,"title":"Parameters","slug":"parameters-1","at":11152,"chars":279},{"level":4,"title":"Behavior and recommended use","slug":"behavior-and-recommended-use-1","at":11431,"chars":699},{"level":4,"title":"Example","slug":"example-2","at":12130,"chars":1049},{"level":3,"title":"OnAfterGetPageSummary event","slug":"onaftergetpagesummary-event","at":13179,"chars":2432},{"level":4,"title":"Syntax","slug":"syntax-2","at":13337,"chars":244},{"level":4,"title":"Parameters","slug":"parameters-2","at":13581,"chars":338},{"level":4,"title":"Behavior and recommended use","slug":"behavior-and-recommended-use-2","at":13919,"chars":249},{"level":4,"title":"Example","slug":"example-3","at":14168,"chars":1443},{"level":2,"title":"Related information","slug":"related-information","at":15611,"chars":155}],"text":"# Extending Teams Cards\n> APPLIES TO: Business Central online\nIn this article, you'll learn how to customize the fields that display on a Teams card. You customize the fields by using a field groups control on the source table or using events. You can also combine these two methods to achieve the results that you want.\n## Extend Teams cards by using field groups\nThis section explains how to customize the fields that display on Teams card by setting metadata in Business Central page and table objects.\n###  Understanding the card layout in Teams\nThe main metadata elements for displaying fields in Teams are the Brick devenv-field-groups, together with the page and field captions. However, with the lack of a Brick field group on a table, the Dropdown field group and primary keys will play a role in determining the fields that display. This section describes how the app selects and arranges fields on the card in Teams. Use this information to help define your Brick field group.\n#### What fields are displayed\nAlthough it's recommended, a Brick field group isn't required to display a card in Teams. Lacking a Brick field group, the app will fall back to use either DropDown field group or the primary key fields of on the source table, according to the following flow:\n1. If a Brick field group exists, the app uses the fields specified by the Brick field group.\n2. If a Brick field group doesn't exist, the app uses fields that are defined in Dropdown field group.\n3. If Dropdown field group doesn't exist, then the primary key fields and fields called Name or Description in the table are used.\n#### How fields are arranged\nThe app will arrange fields on cards in Teams based on one of two templates, depending on whether a media field is included in the Brick field group. Except media data type fields, the order of fields on the card is determined by the field order in the Brick field group. You can't reposition fields, add new controls like actionable buttons, or change the overall style of a card.\nThe two templates and how they order fields are explained in the following table.\nWith media|Without media\n![Teams card with image]<br /><br />The card is laid out from top to bottom as follows:<ol><li>The second field defined in Brick field group appears first in a large font. </li><li>The page's caption property value</li><li> The media thumbnail</li><li>The remaining brick fields in the order they're defined.</li></ol><br />Guidelines:<ul><li>For the second field, it's a good idea to use a field that best identifies the record, like a name or description field.</li><li>Don't place a media field as the second field in the Brick field group. It doesn't matter where you place the field otherwise - it will appear after the page caption.</li><li>If there's more than one media field in the Brick field group, only the first one listed is used.</li><li>BLOB data type fields aren't supported.</li></uli>|![Teams card without image]<br /><br />The card is laid out from top to bottom as follows:<ol><li>The page's caption property value</li><li>The second field defined in Brick field group.</li><li>The remaining brick fields in the order they're defined.</li></ol><br />Guidelines:<ul><li>BLOB data type fields aren't supported.</li></uli>\n### Using the Brick field group\nBy default, the fields that display on a card in Teams are based on the Brick devenv-field-groups that's defined on a page's source table. The Brick field group is the same element that determines which fields display with records in list pages viewed as tiles in the client. So you'll have to keep it in mind when designing for Teams.\nUse the Brick field group to identify a subset of table fields that best summarize a record. Typically, you include fields that allow users to quickly identify the record and give insight about the record at a glance. The following code is snippet of Brick field group on a table:\n```al\nfieldgroups\n{\n    fieldgroup(Brick; field[, field][, field])\n    {\n    }\n}\n```\nThe order that you specify fields is important. For an explanation, see Understanding the card layout in Teams<#card> in this article.\n#### Example\nThis code example adds a simple table and card page. The Brick field group specifies which fields of the table will display in a Teams card, as illustrated by the following figure:\n![Vendor card before OnBeforeGetPageSummary event.]\n```al\nTable 50100 MyTable\n{\n\n    fields\n    {\n        field(1; Number; Integer)\n        {\n        }\n        field(2; Description; Text[50])\n        {\n        }\n        field(3; Inventory; Integer)\n        {\n        }\n        field(4; Image; Media)\n        {\n        }\n    }\n\n    keys\n    {\n        key(PK; Number)\n        {\n        }\n    }\n\n    fieldgroups\n    {\n        fieldgroup(Brick; Number, Description, Image)\n        {\n        }\n    }\n}\n\npage 50100 MyPage\n{\n    PageType = Card;\n    ApplicationArea = All;\n    UsageCategory = Administration;\n    SourceTable = MyTable;\n    Caption = 'My Card Page';\n\n    layout\n    {\n        area(Content)\n        {\n            group(GroupName)\n            {\n                field(Number; Number)\n                {\n                    ApplicationArea = All;\n                }\n                field(Description; Description)\n                {\n                    ApplicationArea = All;\n                }\n                field(Inventory; Inventory)\n                {\n                    ApplicationArea = All;\n                }\n            }\n        }\n    }\n}\n```\nFor more information about how to specify the Brick field group. see Displaying Data as Tiles<devenv-lists-as-tiles>.\n#### Extensibility limitations on the Brick field group\nThe following list provides information to keep in mind when designing table and table extension objects in your extensions:\n You can add a Brick field group to a new table object.\n You can add a Brick field group to a table extension object as long as the base table it extends doesn't already have one.\n In a table extension object, you can't add to or overwrite a Brick field group that's already specified for a base table.\n## Extending Teams cards by using events\nBusiness Central offers the following events for customizing the fields and data that appear in a Teams card:\nEvent|Description\nOnBeforeGetPageSummary|Use this event to override all data for a Card. By handling the event, you can specify a custom set of key-value pairs that will be displayed. The platform won't attempt to select any list of fields or their corresponding values if you subscribe to this event.\nOnAfterGetSummaryFields|Use this event to specify a custom set of fields from the same table as the record. Using this method you can add more fields than are those fields specified by the Brick field group on the source table. For example, you could add fields that are added to the source table by a table extension.\nOnAfterGetPageSummary|Use this event to modify fields and their values that are already selected for the card by the platform. For example, you could change the captions or value of a field.\nThe events are part of the https://github.com/microsoft/BCApps/tree/main/src/System%20Application/App/Page%20Summary%20Provider module of the Microsoft System Application.\n> NOTE\n> In most cases, we recommend you set the Brick field group instead of using events to define card content. This ensures a consistent experience across the Business Central Web client, mobile devices, and Teams.\n### Event flow\nThe following figure illustrates the sequence of the events and operations involved in building the card in Teams. The flow has been simplified for illustration purposes.\n### OnBeforeGetPageSummary event\nThe OnBeforeGetPageSummary event gives you the most control over the fields and data that appears in the card. With this event, you specify a complete set of fields as key-value pairs using JSON Array. Only these fields will appear on the card, even if the source table has a Brick field group or other extensions include code that modifies the card.\n#### Syntax\nThe OnBeforeGetPageSummary event subscription has the following syntax:\n```al\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Page Summary Provider\", 'OnBeforeGetPageSummary', '', false, false)]\nlocal procedure OnBeforeGetPageSummary(PageId: Integer; RecId: RecordId; var FieldsJsonArray: JsonArray; var Handled: Boolean)\n```\n#### Parameters\nParameter|Description\nPageId|The ID of the page for which to retrieve page summary.\nRecId|The underlying record ID of the source table for the page being retrieved, based on the bookmark.\nFieldsJsonArray|A JSON array that includes the fields and values to display on the card, if the event is handled.\nHandled|Specifies whether the event has been handled and no further execution should occur.\n#### Behavior and recommended use\nThis event is raised before platform tries to get summary fields for the card from the table, for example, from the Brick field group. So when you subscribe to this event, the fields in the Brick field group aren't used. Subscribing to this event prohibits other extensions from adding, modifying, or removing summary fields on the card by the other event.\nFor these reasons, use this event only if you don't want to use any fields of the source table in the card.\n#### Example\nThe following code example uses the OnBeforeGetPageSummary event to change the fields on a Teams card, as shown in the following table:\nBefore|After\n![Vendor card in Teams before OnBeforeGetPageSummary event.]|![Vendor card in Teams after OnBeforeGetPageSummary event]\n```al\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Page Summary Provider\", 'OnBeforeGetPageSummary', '', false, false)]\nlocal procedure OnBeforeGetPageSummary(PageId: Integer; RecId: RecordId; FieldsJsonArray: JsonArray; var Handled: Boolean)\nvar\n    Vendor: Record Vendor;\nbegin\n    if PageId <> Page::\"Vendor Card\" then\n        exit;\n\n    if not Vendor.Get(RecId) then\n        exit;\n\n    AddField(FieldsJsonArray, 'Name', Vendor.Name, 'Text');\n    AddField(FieldsJsonArray, 'Note', 'Added by extension', 'Text');\n    AddField(FieldsJsonArray, 'Address', Vendor.Address, 'Text');\n    AddField(FieldsJsonArray, 'Phone No.', Vendor.\"Phone No.\", 'Text');\n\n    Handled := true;\nend;\n\nlocal procedure AddField(var FieldsJsonArray: JsonArray; Caption: Text; FieldValue: Text; FieldType: Text)\nvar\n    FieldsJsonObject: JsonObject;\nbegin\n    FieldsJsonObject.Add('caption', Caption);\n    FieldsJsonObject.Add('fieldValue', FieldValue);\n    FieldsJsonObject.Add('fieldType', FieldType);\n    FieldsJsonArray.Add(FieldsJsonObject);\nend;\n```\n### OnAfterGetSummaryFields event\nThe OnAfterGetSummaryFields event lets you add or remove from the set of fields selected by the platform. For example, if the platform automatically selects fields based on its Brick field group, use this event to add fields from the same table, which aren't part of the Brick field group.\n#### Syntax\n```al\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Page Summary Provider\", 'OnAfterGetSummaryFields', '', false, false)]\nlocal procedure OnAfterGetSummaryFields(PageId: Integer; RecId: RecordId; var FieldList: List of [Integer])\n```\n#### Parameters\nParameter|Description\nPageId|The ID of the page object in Business Central that the card is generated for.\nRecId|The underlying record ID in the source table for the page being retrieved, based on the bookmark.\nFieldList|The list of fields that will be returned.\n#### Behavior and recommended use\nThis event is raised after the platform gets the summary fields from the table.\nThe event the ideal for specifying a custom set of fields from the same table. It enables the platform to fetch the corresponding values for the current record. If you extended a table with fields, use this event to add the fields to the card.\nHere are some considerations, when using this event:\n Use the FieldList to add or remove individual fields you want to show on the card in Teams.\n Fields on the card in Teams are shown in the order specified the FieldList.\n Don't remove all fields from the list, because you'll be removing fields that are added by other partner extensions.\n#### Example\nThe following code example uses the OnAfterGetSummaryFields event to change the fields on a Teams card, as shown in the following table:\nBefore|After\n![Vendor card before OnAfterGetSummaryFields event.]|![Vendor card after OnAfterGetSummaryFields event]\n```al\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Page Summary Provider\", 'OnAfterGetSummaryFields', '', false, false)]\nlocal procedure OnAfterGetSummaryFields(PageId: Integer; RecId: RecordId; var FieldList: List of [Integer])\nvar\n    Vendor: Record Vendor;\nbegin\n    if PageId <> Page::\"Vendor Card\" then\n        exit;\n\n    // Remove Balance Due  details\n    FieldList.Remove(Vendor.FieldNo(\"Balance Due (LCY)\"));\n    FieldList.Remove(Vendor.FieldNo(\"Balance (LCY)\"));\n\n    // Add contact number\n    FieldList.Add(Vendor.FieldNo(\"Phone No.\"));\n\n    // Add new field \"Vendor Role Name\" from extension\n    FieldList.Add(Vendor.FieldNo(\"Vendor Role Name\"));\nend;\n```\nIn the code, the Vendor Role Name field is defined in a table extension object that extends the Vendor table.\n### OnAfterGetPageSummary event\nThis event allows you to modify, add, or remove fields included in the card through the direct access to the FieldsJsonArray.\n#### Syntax\n```al\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Page Summary Provider\", 'OnAfterGetPageSummary', '', false, false)]\nlocal procedure OnAfterGetPageSummary(PageId: Integer; RecId: RecordId; var FieldsJsonArray: JsonArray)\n```\n#### Parameters\nParameter|Description\nPageId|The ID of the page for which to retrieve page summary.\nRecId|The underlying record ID of the source table for the page being retrieved, based on the bookmark.\nFieldsJsonArray|A Json array that lists the fields to include in the card, overriding the current fields and values set for the card.\n#### Behavior and recommended use\nThis event is ideal for modifying the list of fields and their values that are selected by the platform.\nUse the event to change the value of existing fields or to add fields that don't already exist on the record.\n#### Example\nThe following code example uses the OnAfterGetPageSummary event to change the fields on a Teams card, as shown in the following table:\nBefore|After\n![Vendor card before OnAfterGetPageSummary event.]|![Vendor card after OnAfterGetPageSummary event]\n```al\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Page Summary Provider\", 'OnAfterGetPageSummary', '', false, false)]\nlocal procedure OnAfterGetPageSummary(PageId: Integer; RecId: RecordId; var FieldsJsonArray: JsonArray)\nvar\n    FieldJsonToken: JsonToken;\n    CaptionToken: JsonToken;\n    fieldNo: Integer;\nbegin\n    if PageId <> Page::\"Vendor Card\" then\n        exit;\n\n    // Change value of field caption\n    for fieldNo := 0 to FieldsJsonArray.Count() - 1 do begin\n        FieldsJsonArray.Get(fieldNo, FieldJsonToken);\n        FieldJsonToken.AsObject().Get('caption', CaptionToken);\n        if CaptionToken.AsValue().AsText() = 'Contact' then begin\n            // FieldJsonToken.AsObject().Replace('caption', 'Contact Company');\n            // FieldJsonToken.AsObject().Replace('fieldValue', 'Microsoft');\n            FieldJsonToken.AsObject().Replace('caption', 'Note');\n            FieldJsonToken.AsObject().Replace('fieldValue', 'Added by extension');\n            FieldsJsonArray.Set(fieldNo, FieldJsonToken);\n            exit;\n        end;\n    end;\nend;\n```\nIn the code, the Vendor Role Name field is defined in a table extension object that extends the Vendor table.\n## Related information\nFAQ for Teams Integration<devenv-dev-faq-teams>\ndevenv-field-groups\ndevenv-designing-list-pages\ndevenv-working-with-media-on-records"}