--- 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: instanceList layout: subsection wd_wcptag: instanceList --- Displays a list of values or object instances. Use `instanceList` on: - An edit page to display a list prompt from which a user can search and select values. - A view page to display instances with the related actions menu. The `instanceList` widget value is a list of strings. ## Usage See [Concept: instanceList](/wcp_docs/GUID-17f49183-14bb-4cd3-95a1-1e3dd8ded432-enHYPHENus.html) ## Mobile Support Android, iOS ## Attributes - displayKey Data type: string The name of the field containing the display value on the list. The default is `descriptor`, which assumes that the data collection contains a field named `descriptor`. Typically used with the `idKey` attribute to override the default `id` field on the list. If your data collection doesn't contain the `descriptor` field, use `displayKey` to override the default. Specify a root-level field. If you want to use a nested field, use the `instanceListLoopTag` attribute instead. Example: See Populating the List > instanceListLoopTag in [Concept: instanceList](/wcp_docs/GUID-17f49183-14bb-4cd3-95a1-1e3dd8ded432-enHYPHENus.html). Supports dot and bracket notation to traverse JSON data structures.  See the `idKey` attribute description for an example. - dynamicMonikerLevels Data type: ListScript Script that enables you to return different data for each sublevel of a multilevel `instanceList`. Unlike `monikerLevels`, each selection level defined in `dynamicMonikerLevels` can have a different number of sublevels. The script must return a list that contains 2 items: - A list of values containing the `id` and `descriptor` fields. This can be manually defined or a data collection from a deferred endpoint. - A Boolean that indicates whether the current selection contains a sublevel. `dynamicMonikerLevels` and `monikerLevels` are mutually exclusive. Use `dynamicMonikerLevels` only on edit pages. Example: See [Concept: Multilevel Lists](/wcp_docs/GUID-12f151a8-6f26-4bba-a8fb-b5de59767981-enHYPHENus.html). - enabled Data type: dynamicBinding-Boolean If true, users can enter values on the widget. If false, users can only view the widget. - helpText Data type: binding-String Text that displays when a user hovers their cursor over the widget. Note: The Chrome browser truncates the tooltip to 1400 characters. - 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. - idKey Data type: string The name of the ID field, which is the index field on the list. The default is `id`, which assumes that the data collection contains a field named `id`. Typically used with the `displayKey` attribute to override the default `descriptor` field on the list. If your data collection doesn't contain the `id` field, use `idKey` to override the default. Specify a root-level field. If you want to use a nested field, use the `instanceListLoopTag` attribute instead. Example: See Populating the List > instanceListLoopTag in [Concept: instanceList](/wcp_docs/GUID-17f49183-14bb-4cd3-95a1-1e3dd8ded432-enHYPHENus.html). Supports dot and bracket notation to traverse JSON data structures. Sample JSON data: ``` "requestEvents": [ { "descriptor": "descriptor", "workdayID": { "id": "ID" } }, { "descriptor": "descriptor2", "workdayID": { "id": "ID2" } } ] ``` Sample `idKey`: ``` { "type": "instanceList", "id": "requestEvents", "values": "<% requestEvents %>", "idKey": "workdayID.id" } ``` - instanceList Data type: list of instance objects An array of `id` and `descriptor` values in the list. Example: ``` "instanceList": [ { "id": "1", "descriptor": "Yes" }, { "id": "2", "descriptor": "No" } ] ``` Notes: - You can't combine `instanceList` with the `instanceListLoopTag` or `values` attributes to populate a list. These attributes are mutually exclusive. - To enable the related actions menu and view link, set the `wid` attribute. Specify the binding to the ID field containing the instance Workday ID. For details, see Enabling the Related Actions Menu in [instanceList](/wcp_docs/hcb1512514976081.html). - instanceListLoopTag Data type: instanceLoop Note: Workday recommends using PMD scripting with the `values` attribute to reshape data instead of the `instanceListLoopTag` attribute. Creates list values by using a template instance while iterating through a data collection. The `instanceListLoopTag` attribute is an [instanceLoop](/wcp_docs/fem1530169946255.html) tag that specifies the: - `templateInstance` - Contains the template `id` and `descriptor` fields for a list item. You can specify root-level or nested fields. - `on` - The binding to the data collection. - `as` - The variable reference for each instance. - `limit` - Optional maximum number of list items. Example: ``` "instanceListLoopTag": { "type": "instanceLoop", "id": "sampleInstanceListLoopTag", "templateInstance": { "id": "<% workerInstance.primarySupervisoryOrganization.id %>", "descriptor": "<% workerInstance.primarySupervisoryOrganization.descriptor %>" }, "on": "<% workers.data %>", "as": "workerInstance", "limit": 5 } ``` Note: You can't combine `instanceListLoopTag` with the `instanceList` or `values` attributes to populate a list. These attributes are mutually exclusive. - label Data type: dynamicBinding-String Text that displays beside or above most widgets. Often used in simple widgets that include inputs. The maximum number of characters is 255. - monikerLevels Data type: list of monikerLevel objects List of `monikerLevel` tags that define lower selection levels of an `instanceList`. `dynamicMonikerLevels` and `monikerLevels` are mutually exclusive. Use `monikerLevels` only on edit pages. Example: See [monikerLevel](/wcp_docs/dfg1530238095693.html) and [Concept: Multilevel Lists](/wcp_docs/GUID-12f151a8-6f26-4bba-a8fb-b5de59767981-enHYPHENus.html). - multiSelect Data type: boolean Determines whether or not a user can select multiple instances within a prompt. The default is false. - relatedTask Data type: booleanScript If true, we enable the related actions menu, which is a cascading menu of links to related tasks. This attribute only applies if you specify the `wid` attribute that enables the related actions menu. If false, we disable the related actions menu. The default is true. You can use the `relatedTask` attribute only on view pages. - 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. - required Data type: dynamicBinding-Boolean If true, the user must enter a value on the widget before submitting the page. - searchEndPoint Data type: binding-EndPoint Name of the endpoint that searches the value entered by the user on the `instanceList` prompt. Use `searchEndPoint` with `searchResultValues` when an `instanceList` has large datasets that don’t need to load all at once. The `searchEndPoint` has a global context of the widgets on the page. If the `instanceList` is on a grid or panelList, the `searchEndPoint` doesn't know about specific instances of rows and panels. You can use the `onSearch` event of the `instanceList`, which is aware of the current row or panel instance that triggered the event. The `onSearch` event provides the `event.query` property, which contains the input search string. Note that `searchEndPoint` and `onSearch` are mutually exclusive. See the Populating a List with the onSearch Event section in [Concept: instanceList](/wcp_docs/GUID-17f49183-14bb-4cd3-95a1-1e3dd8ded432-enHYPHENus.html). - searchResultValues Data type: dynamicBinding-List Contains a list of ids and descriptors based on data from the `searchEndPoint` attribute. - searchValues Data type: binding-List A list containing local data for enabling local search on a multilevel list. The local data must contain the fields specified by the `idKey` and `displayKey` attributes of the `instanceList`. If you don't specify the `idKey` and `displayKey` attributes, the local data must contain the `id` and `descriptor` fields. Don't use `searchValues` with `searchEndpoint` and `searchResultValues`. Note: Instead of using `searchValues`, you can use the `onSearch` event of the `instanceList` to return a list of values. Note that `searchValues` and `onSearch` are mutually exclusive. See the Populating a List with the onSearch Event section in [Concept: instanceList](/wcp_docs/GUID-17f49183-14bb-4cd3-95a1-1e3dd8ded432-enHYPHENus.html). - selectedValues Data type: dynamicBinding-List List of IDs that specify the default, pre-selected values on the widget. The IDs must be a subset of the IDs in either the `values` or `instanceList` attribute. Use `selectedValues` only on edit pages. - selectedValuesAndDescriptors Data type: dynamicBinding-List Defines a list of objects containing ids and descriptors of the default selected instances in a `monikerLevel`. This example uses a filtered list of instances: ``` "selectedValuesAndDescriptors": "<%list:filter(getNotificationDate.data,'descriptor',apidata.Slate_group[0].noticeDate)%>" ``` - 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. - valueOutBinding Data type: dynamicBinding-String A binding to the JSON field that stores the widget value in the outbound request payload. If you want to send an array of JSON values to the outbound endpoint, specify the path using this pattern: `anEndpointName.[].aJsonFieldName`. Example: To send this array to the sample outbound endpoint: ``` [{"memo":"First memo"}, {"memo":"Second memo"}] ``` Specify this `valueOutBinding`: ``` "valueOutBinding" : "expensesPostEndpoint.[].memo" ``` Note: If the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the widget's `valueOutBinding` data in the outbound payload. To include the `valueOutBinding` data in the payload, use the `onSend` event handler. - values Data type: dynamicBinding-List Defines all possible values that a user can select from a list. Each value defaults to an id and descriptor for persistence and display. You can customize these values on the idKey and displayKey attributes. Note: You can't combine `values` with the `instanceList` or `instanceListLoopTag` attributes to populate a list. These attributes are mutually exclusive. - valuesOut Data type: list of outValue objects An array of values and their bindings to JSON fields in the outbound request payload. An array item consists of these attributes: - `value` - An object binding of the value to include in the outbound JSON. - `valueOutBinding` - A string binding of the JSON field that contains the value in the request payload. We send the request payload with the outbound endpoint when the user submits the page. You can use `valuesOut[]` to: - Send a single piece of data to multiple outbound fields or endpoints. Example: A street address persisting to a Billing Address field and a Shipping Address field or different endpoints. - Apply a function to the outbound value when persisting the data. Example: Convert a date to a specific format or convert a list to a string. In this example, the value of the `country` widget is sent to 2 different outbound fields `shippingAddress.country` and `billingAddress.country`. ``` "valuesOut": [ { "value": "<% country.value[0] %>", "valueOutBinding": "anOutboundEndpoint.shippingAddress.country.id" }, { "value": "<% country.value[0] %>", "valueOutBinding": "anOutboundEndpoint.billingAddress.country.id" } ] ``` This example uses PMD functions to extract the year and month from date values, and sends them separately to the outbound endpoint: ``` "valuesOut": [ { "value": "<% date:month(date1.value) %>", "valueOutBinding": "anOutboundEndpoint.dateMonth" }, { "value": "<% string:toString(date:year(panelList1Date1.value)) %>", "valueOutBinding": "anOutboundEndpoint.dateYear" } ] ``` Note: If the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the widget's `valuesOut` data in the outbound payload. To include the `valuesOut` data in the payload, use the `onSend` event handler. - view Data type: booleanScript Indicates whether or not to display a link to view the instance details. If "false", the instance displays plain text instead of a link. This attribute only applies if you specify the `wid` attribute that enables the related actions menu. The default is "true". You can use the `view` attribute only on view pages. - 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. - widePrompt Data type: binding-Boolean If "true", the edit mode of the `instanceList` widget renders wider than its default width. - widKey Data type: string Sets the name of the JSON field that contains the Workday ID of a business object instance. Use `widKey` with the `values` attribute to enable the related actions menu on the instanceList. The presence of the `widKey` attribute enables the related actions menu on the Workday business object instance. The default is `wid`. Supports dot and bracket notation to traverse JSON data structures. See the `idKey` attribute description for an example. This sample `instanceList` uses the `values` attribute and `widKey`: ``` { "type" : "instanceList", "id": "instanceList2", "label" : "Select from this list:", "idKey" : "ISO_3166_1_Numeric_3_Code", "displayKey" : "name", "widKey": "ISO_3166_1_Numeric_3_Code", "values" : "<% countries.items %>", "valueOutBinding" : "demoEndPoint.value" }, ``` Note: Use `widKey` on view pages only. ## PMD Scripting Events - onChange Triggers when the user changes the value of the widget. - onSearch Triggers when the user enters a search string on the `instanceList` widget. The `onSearch`event handler must return a list of instances that contains the `id` and `descriptor` fields (or the fields configured in the `idKey` and `displayKey` attributes. You can use the `onSearch` event to: - Customize the list data based on page interactions. - Invoke deferred endpoints. - Run script logic for local search. - Replace the use of `searchEndPoint` and `searchValues`. Note: `onSearch`, `searchEndPoint`, and `searchValues` are mutually exclusive. ## PMD Scripting Methods - clearError() Return type: `void` Description: Clears the validation error. - clearWarning() Return type: `void` Description: Clears the validation warning. - getLabel() Return type: `string` Description: Returns the list label. - getPromptSelections(int index) Return type: `List` Returns a list containing the `id` of the selected values of a multilevel `instanceList`. Example: `promptSelections[0]` contains the `id` of the selected value at the root level. `promptSelections[1]` contains the `id` of the selected value at the second level, and so on. Note: The `getPromptSelections(index)` method (or its equivalent `promptSelections` property) applies only to a multilevel `instanceList` that contains `monikerLevels`. You can use promptSelections as a URL path parameter of a deferred endpoint that returns the sublevel values. See "Defining a Multilevel List" in [instanceList](/wcp_docs/hcb1512514976081.html). - getSelectedEntries() Return type: `List` Description: Returns a list of maps containing the `id` and `descriptor` fields for the selected entries on the instance list. Example: `[{"id": "123", "descriptor": "Logan McNeil"}]` If the list doesn't have a selected value, the `getSelectedEntries` method (or its equivalent `selectedEntries` property) returns an empty list, `[]`. When you get the `descriptor` value of the selected entry, always check whether or not the list value is empty. Example: ``` <% !empty someList.value ? someList.selectedEntries[0].descriptor : null %> ``` - getValue() Return type: `List` Description: Returns this instance list as a list of instance ids. Example: `["123", "456"]` If the list is empty, the `getValue` method (or its equivalent `value` property) returns an empty list, `[]`. - getValueOutBinding() Return type: `string` Description: Returns the outbound value binding of this instance list. - isEnabled() Return type: `boolean` Description: If true, this widget is enabled. - isRequired() Return type: `boolean` Description: If true, this widget is required. - isUpdated() Return type: `boolean` Description: If true, this widget is manually updated by the end-user. - isUpdatedByScript() Return type: `boolean` Description: If true, this widget is programmatically updated by a PMD script. - isVisible() Return type: `boolean` Description: If true, this widget is visible. - setEnabled(boolean enabled) Return type: `void` Description: Enables or disables this widget. - setError(String error) Return type: `void` Description: Sets the validation error. The input error message displays in the page error window. - setLabel(String label) Return type: `void` Description: Sets the list label. - setRequired(boolean required) Return type: `void` Description: Makes this widget required or not required. - setValue(List value) Return type: `void` Description: Sets this instance list to the specified list of instance `id` values. You can use `someList.setValue(['id1', 'id2'])` to set the `selectedValues` property of an `instanceList`. - setValueOutBinding(String valueOutBinding) Return type: `void` Description: Sets the outbound value binding to this instance list. - setValues(List dataSource) Return type: `void` Description: Sets all possible values of this instance list. The dataSource list must include the `id` and `descriptor` fields (or the fields specified by the `idKey` and `displayKey` attributes). - setVisible(boolean visible) Return type: `void` Description: Displays or hides this widget. If you need to change the visibility of a list widget, ensure that it's inside a `fieldSet`. - setWarning(String warning) Return type: `void` Description: Sets the validation warning.