--- category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend] keyword: [Extend, Presentation Components, widgets, tags, UI components] nav: wcp_docs parent_url: /wcp_docs/ title: button layout: subsection wd_wcptag: button --- Creates a button that navigates to another page in the Extend app. Specify the `taskId` of the destination page in the [taskReference](/wcp_docs/cgt1531499518059.html) attribute. Use `button` on view and edit pages. The main purpose of the `button` widget is for navigation to another page within the app. For other purposes that indicate an action or navigation option, use these other widgets: - To execute a PMD script upon clicking the button, use [pageActionButton](/wcp_docs/jje1617899729875.html). - To navigate to an external URL, use [externalLink](/wcp_docs/cik1530243923503.html). Jump to: - [Mobile Support](/wcp_docs/irz1512515858494.html#section-mobile-support) - [Attributes](/wcp_docs/irz1512515858494.html#section-attributes) ## Usage ## Navigating to a Page Use `taskReference` within button widgets to specify the page to navigate to. In the `taskReference` attribute, specify the `taskId` of the page. Note: A PMD page corresponds to a task, as defined in the `tasks[]` array in the App Metadata (AMD). The `taskId` in `taskReference` must be a valid task `id` in `tasks[]` in the AMD. Ensure that you specify the task `id`, not the `page` `id`. If you specify an incorrect `taskId` in `taskReference`, you'll get an error with the HTTP status code 404. The `taskReference` attribute in this sample `button` navigates to the sample manageMyDonations task, which corresponds to a sample manageMyDonations.pmd. ``` { "type": "button", "action": "PRIMARY", "label": "My Charitable Donations", "taskReference": { "taskId": "manageMyDonations" } } ``` The task definition in the AMD for the manageMyDonations.pmd, whose task `id` is manageMyDonations: ``` "tasks": [ { "id": "manageMyDonations", "routingPattern": "/myDonations", "page": { "id": "manageMyDonations" } }, . . . ] ``` Note: If the `routingPattern` of the task definition in the AMD contains path parameters, the parameter bindings in `taskReference` must match the path parameters in the `routingPattern`. To reference path parameters, use the `routeParams` predefined app variable. For more details about route parameters, see: - `routingPattern` under tasks in [Reference: Extend App Metadata](/wcp_docs/btj1547749859781.html). - `routeParams` in [Reference: Predefined App Variables](/wcp_docs/urd1528494500512.html). ## Navigating to Workday-delivered Tasks and Reports To enable users to navigate to a Workday-delivered task or report, specify the `workdayTaskReference`, which contains the `wid` (“Workday ID” or “Integration ID”) of the Workday task or report. For details, see [Navigate to Workday Tasks and Reports](/wcp_docs/GUID-65dc8eb6-a52b-4bf5-b05a-32160abb1f08-enHYPHENus.html). ## Sending Key-Value Parameter Bindings to a Page To send key-value parameters to the next page, specify the `parameterBindings` attribute in `taskReference`. The `taskReference` in this sample `button` specifies `parameterBindings`, which sends the charityId parameter to the next page. ``` { "type": "button", "action": "AUXILIARY", "label": "Update", "taskReference": { "taskId": "updateCharity", "parameterBindings": { "charityId": "<% charity.id %>" } } } ``` The next page can reference the parameter bindings using the `queryParams.` aParameterName. The aParameterName variable is a key in `parameterBindings` of the `taskReference` (from the previous page). Example: The updateCharity page references the queryParams.charityId parameter in the endpoint url: ``` { "name": "charity", "baseUrlType": "app", "url": "<% 'charities/' + queryParams.charityId %>", "authType": "sso" } ``` ## Sending Object Parameters to a Page While the `parameterBindings` attribute of `taskReference` sends key-value parameter bindings to the next page, the `parameters` attribute enables you to send a map object binding to the next page. In this next example, the `taskReference` sends both a simple parameter startDate and a map object parameter expenseEntry.expenseEntryStatus. ``` { "type": "button", "id": "expenseDetailsButton", "label": "Expense Details", "action": "AUXILIARY", "taskReference": { "taskId": "expenseDetails", "parameterBindings": { "startDate": "2021-03-15" }, "parameters": "<% expenseEntry.expenseEntryStatus %>" } } ``` The sample expenseEntry.expenseEntryStatus map object contains these fields: ``` { "descriptor": "New", "id": "dc74b9a0446c11de98360015c5e6daf6" } ``` Note: We combine entries from both `parameters` and `parameterBindings`. If there is a duplicate entry, then the entry in `parameterBindings` takes precedence. To reference the fields in the map object in the next page, use `queryParams.` aParameterName. The aParameterName variable is a field in the map object in `parameters` of the `taskReference` (from the previous page). Example: These text widgets from the sample expenseDetails page reference the parameter bindings from the sample button. Note that queryParams.descriptor references the descriptor field in the expenseEntry.expenseEntryStatus map object. ``` { "type": "text", "label": "Start date", "value": "<% queryParams.startDate %>" }, { "type": "text", "label": "Expense status", "value": "<% queryParams.descriptor %>" } ``` ## Mobile Support Android, iOS ## Attributes - action Data type: string The display style of the button. Valid values: - `PRIMARY` - Displays a button with high emphasis. This display style is typically for designating the primary action that moves the user forward in a process. - `AUXILIARY` - (Default) Displays a button with medium emphasis. This display style is typically for: - Secondary actions on a screen. - Canceling a process. - Taking an action that moves the user away from a process. - `LINK` - Displays a link. This display style is for a page navigation option. Not supported in the Workday mobile app. - commandHttpMethod Data type: commandHttpMethod The HTTP method used when invoking the endpoints on the page destination. Valid values: - `GET` - Default. This option enables users to bookmark the page URL. - `POST` - Omits the page destination of the button from the browser history. This option is useful for non-repeatable tasks. Specify `POST` if an inbound endpoint on the page destination uses the HTTP POST method. Example: ``` { "type": "button", "label": "Worker details", "action": "LINK", "commandHttpMethod": "POST", "taskReference": { "taskId": "viewWqlQueryPost" } } ``` This sample inbound endpoint on the page destination uses the WQL `POST /data` endpoint: ``` { "name": "workerContactInfo", "baseUrlType": "workday-wql", "url": "data", "httpMethod": "POST", "values": [ { "outboundPath": "query", "value": "<% 'SELECT fullName, email_PrimaryWork, phone_PrimaryWork, workAddress_Full FROM allWorkers WHERE worker = \"' + currentWorker.id + '\"' %>" } ] } ``` Note: We currently don't support the POST HTTP method on `button`s within a `buttonGroup`. - id Data type: binding-String Unique identifier used to reference this widget from other tags. Notes: - The `id` must start with a letter. - The `id` must be unique per page. - To enable other widgets to reference this widget `id`, place this widget before the other widgets on the PMD. The PMD validation returns an "Undefined variable" error if it doesn't find a previously defined `id` in the PMD. - Workday recommends that you include the `id` in your tag definitions for debugging purposes. - label Data type: dynamicBinding-String The text that displays on the button. - render Data type: binding-Boolean If true, this tag renders as a widget on the page. If false, the loaded page doesn't add this tag or its children. The default is true. Unlike the `visible` attribute, when `render` is false, other tags on the page can't reference this tag or widget on edit pages. On view pages, a tag can't reference other tags regardless of the `render` attribute value. - sortOrder Data type: binding-String When you set `sorted` to true on the `section` or `fieldSet` parent of this widget, the `sortOrder` attribute determines the order of this widget within its parent. The sort order is relative to the siblings of the widget. Typical values are "a", "b", "c", and so on. Example: The widget with `"sortOrder": "a"` displays before the widget with `"sortOrder": "b"`. Note: The `sortOrder` doesn't apply to sorting data on the widget. `sortOrder` only applies to the placement order of the widgets within the parent widget. - suppressDiscardDialog Data type: boolean If true, hides the Discard Changes dialog when the user clicks the button on an edit page. If `suppressDiscardDialog` is true, clicking the button enables users to navigate away from the page without the confirmation dialog. This attribute is useful for interactive edit pages where users aren’t required to modify or submit data. Note: Use the `suppressDiscardDialog` attribute only on standalone buttons. You can't use it with buttons in a `buttonGroup`. If false (default), the edit page displays the Discard Changes confirmation dialog when users click the button, warning them about discarding page modifications. The `suppressDiscardDialog` attribute only applies to edit pages. - taskReference Data type: taskReference The task (page) to navigate to when a user clicks the widget. Specify the [taskReference](/wcp_docs/cgt1531499518059.html#) tag. - visible Data type: dynamicBinding-Boolean If true, the widget generated by this tag is visible. If false, this tag and its children tags aren't visible. This tag provides the ability to display or hide the widget dynamically based on user interactions on the page. The default is true. Unlike the `render` attribute, the generated widget persists on the page even when `visible` is false. Notes: - When the widget or field you’re hiding changes on the page, you must include it inside a `fieldSet`. - When the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the `valueOutBinding` or `valuesOut` data of the widget in the payload. To include the `valueOutBinding` or `valuesOut` data in the payload, use the `onSend` event handler. - workdayTaskReference Data type: workdayTaskReference object Contains the `wid` of a Workday-delivered task or report to navigate to. To determine the `wid` value, get the Integration ID of the Workday-delivered task or report. For details, see [Navigate to Workday Tasks and Reports](/wcp_docs/GUID-65dc8eb6-a52b-4bf5-b05a-32160abb1f08-enHYPHENus.html) `workdayTaskReference` and `taskReference` are mutually exclusive. This sample `button` navigates to the Request Absence task in Workday: ``` { "type": "button", "label": "Request Absence", "action": "PRIMARY", "workdayTaskReference": { "wid": "c4936fdad7d110001d9c005c57510000" } } ``` ### Related Information [externalLink](/wcp_docs/cik1530243923503.html) [pageActionButton](/wcp_docs/jje1617899729875.html) [Tutorial: Navigate Pages with Buttons and Button Groups](https://wd5.myworkday.com/workday/learning/course/62d106356d1b10051260edf509b90000?type=9882927d138b100019b928e75843018d) [Tutorial: Send Data to Pages with Buttons](https://wd5.myworkday.com/workday/learning/course/61eba84c34fc100824ab1d1389a80000?type=9882927d138b100019b928e75843018d)