---
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: >- 
  Concept: instanceList
layout: subsection
---

## <a id="section_populateValues"></a>Populating the List

To define the values in the [`instanceList`](/wcp_docs/hcb1512514976081.html), use 1 of these mutually exclusive attributes:

-   <b>values</b>

    Specify `values` with endpoint data, which must be a list containing the `id` and `descriptor` root-level fields. Using the `values` attribute is the most common way to populate a list.

    This sample `instanceList` displays the `descriptor` values from the `supervisoryOrganizations` endpoint:

    ```
    {
      "type": "instanceList",
      "label": "instanceList using default descriptors",
      "id": "instanceListSimple",
      "values": "<% supervisoryOrganizations.data %>"
    }
    ```

    The sample `supervisoryOrganizations` endpoint:

    ```
    {
      "baseUrlType": "workday-staffing",
      "name": "supervisoryOrganizations",
      "authType": "sso",
      "url": "/supervisoryOrganizations"
    }
    ```

    This snippet from the `supervisoryOrganizations` response displays the `data` list containing the `id` and `descriptor` root-level fields:

    ```
    "data":[
      {
        "id":"e02485f863ec48d39a082bb95cc4abe4",
        "descriptor":"4000 Human Resources",
        "name":"Human Resources",
        . . .
      },
      . . .
    ]
    ```

    To override the default `id` and `descriptor` fields, set the `idKey` and `displayKey` attributes. Example: If you want to display the `name` instead of the `descriptor` field in the `supervisoryOrganizations` data, set the `displayKey` attribute:

    ```
    {
      "type": "instanceList",
      "label": "instanceList using displayKey",
      "id": "instanceListId",
      "displayKey": "name",
      "values": "<% supervisoryOrganizations.data %>"
    }
    ```

    When you set `displayKey` to <i>name</i>, the `instanceList` displays <i>Human Resources</i> instead of <i>4000 Human Resources</i>.

    To display values from a subfield in the list or to manipulate the shape of the list values, you can use PMD Scripting. Example: This sample `instanceList` displays the `email` values from the `person` subfield. For demonstration purposes, this snippet assumes non-empty email values.

    ```
    {
      "type": "instanceList",
      "id": "emailInstanceList",
      "label" : "instanceList using script",
      "values": "<% 
         workers.data
           .filter (worker => { !empty worker.person.email })
           .map (worker => {
             {
               'id': worker.person.id,
               'descriptor': worker.person.email
             }
           }); 
      %>"
    },
    ```

    This snippet from the `workers` response displays the `data` list containing the `person` subfield:

    ```
    "data": [
      {
        "descriptor": "Abby Brennan [C]",
        "id": "6dcb8106e8b74b5aabb1fc3ab8ef2b92",
        "person": {
          "email": "abrennan@workday.net",
          "id": "dc4945b8b8be429e87564e01889c69f5",
          "phone": "+1773721-9821"
        },
        . . .
      },
      . . .
    ]
    ```

-   <b>instanceList</b>

    Specify the `instanceList` attribute with a list of hard-coded `id` and `descriptor` fields. Example:

    ```
    {
      "type": "instanceList",
      "label": "instanceList with Fixed Values",
      "id": "instanceListWithHardcodedValues",
      "instanceList": [
        { "id": "1",
          "descriptor": "Small"
        },
        { "id": "2",
          "descriptor": "Medium"
        },
        { "id": "3",
          "descriptor": "Large"
        }
      ]
    }
    ```

    If you have a short list of hard-coded options, you can alternatively use the other list widgets such as the `checkBoxList` or `radioGroup`.

-   <b>instanceListLoopTag</b>

    <b>Note:</b> Workday recommends using PMD scripting with the `values` attribute to reshape data instead of the `instanceListLoopTag` attribute.

    Specify `instanceListLoopTag` with the `instanceLoop` tag, which contains a template instance for populating the list. `instanceListLoopTag` populates the list by looping through the data from another source on the same page (such as a grid or endpoint).

    `instanceListLoopTag` enables you to reshape the data into the `id` and `descriptor` fields as it loops through the data. In comparison, the `values` attribute expects the `id` and `descriptor` fields (or their equivalent) at the root level data.

    Example:

    ```
    {
      "type": "dropdown",
      "label": "instanceListLoopTag for Dropdown",
      "id": "dropdownInstanceListLoopTag",
      "instanceListLoopTag": {
        "id": "jobProfileList",
        "type": "instanceLoop",
        "templateInstance": {
          "id": "<% instance.primaryJob.jobProfile.id %>",
          "descriptor": "<% instance.primaryJob.jobProfile.descriptor %>"
        },
        "on": "<% workersEndpoint.data %>",
        "as": "instance"
      }
    }
    ```

    The sample `workersEndpoint` endpoint:

    ```
    {
      "baseUrlType": "workday-staffing",
      "name": "workersEndpoint",
      "authType": "sso",
      "url": "<% '/workers?search=' + queryParams.workerName %>"
    }
    ```



## <a id="section_xsg_kyq_rpb"></a>Populating a List with the onChange Event

The `onChange` event triggers when a user selects a list value on the `instanceList`. You can use an `onChange` event handler to populate an `instanceList`. Example: The list of `instanceList` values can change based on the selected value on another `instanceList`.

<b>Note:</b> Ensure that you initialize the `instanceList` values when the page loads.

This sample edit page has 2 `instanceList` widgets, <i>workerSelection</i> and <i>workerManagers</i>. When a user selects a worker from <i>workerSelection</i>, the `onChange` event handler populates <i>workerManagers</i>.

```
{
  "id": "autoPopulateList",
  "presentation": {
    "pageType": "edit",
    "body": {
      "type": "section",
      "children": [
        {
          "type": "fieldSet",
          "title": "Auto-Populating a List with onChange",
          "horizontal": "true",
          "children": [
            {
              "type": "instanceList",
              "id": "workerSelection",
              "label": "Select a Worker",
              "values": "<% workers.data %>",
              "onChange": "<%
                 if ( ! empty (self.value) ) {
                    var supervisoryOrgId = getWorkerById.invoke( { 'id' : self.value[0] } ).primaryJob.supervisoryOrganization.id
                    workerManagers.setValues( getSupervisoryOrgManagers.invoke( { 'id' : supervisoryOrgId } ).managers);
                 }
              %>"
            },
            {
              "type": "instanceList",
              "id": "workerManagers",
              "label": "Partner with a Manager",
              "values": "<% [] %>"
            }
          ]
        }
      ]
    }
  },
"endPoints": [
    {
      "baseUrlType": "workday-staffing",
      "name": "workers",
      "authType": "sso",
      "url": "<% '/workers?limit=10' %>"
    },
    {
      "name": "getWorkerById",
      "baseUrlType": "workday-staffing",
      "url": "<% '/workers/' + id %>",
      "authType": "sso",
      "deferred": true
    },
    {
      "name": "getSupervisoryOrgManagers",
      "baseUrlType": "workday-staffing",
      "url": "<% '/supervisoryOrganizations/' + id %>",
      "authType": "sso",
      "deferred": true
    }
  ]
}
```

Notes:

-   When the user selects a worker from <i>workerSelection</i>, the `onChange` event handler:

    -   Invokes the deferred endpoint <i>getWorkerById</i> with the `id` of the selected value, and gets the supervisory organization of the worker.

        ```
        var supervisoryOrgId = getWorkerById.invoke( { 'id' : self.value[0] } ).primaryJob.supervisoryOrganization.id
        ```

    -   Invokes the deferred endpoint <i>getSupervisoryOrgManagers</i> with the <i>supervisoryOrgId</i> of the selected worker. The `setValues` method then populates the values of <i>workerManagers</i> with the list of managers.

        ```
        workerManagers.setValues( getSupervisoryOrgManagers.invoke( { 'id' : supervisoryOrgId } ).managers);
        ```


-   The target `instanceList`, <i>workerManagers</i>, initializes its `values` with an empty list.


This next example similarly has 2 `instanceList` widgets, <i>orgList</i>, and <i>orgMembersList</i>. When a user selects an organization from <i>orgList</i>, the `onChange` event handler populates <i>orgMembersList</i> by calling the `populateInstanceList` function.

```
{
  "type": "instanceList",
  "id": "orgList",
  "label": "Select a Supervisory Organization",
  "values": "<% supervisoryOrgs.data %>",
  "onChange": "<% populateInstanceList(self.value) %>"
},
{
  "type": "instanceList",
  "id": "orgMembersList",
  "label": "Select an Org Member",
  "values": "<% [] %>"
}
```

The `populateInstanceList` function in a `script` block invokes the <i>supervisoryOrgMembers</i> endpoint to get the members of the input organization ID. Then it populates the <i>orgMembersList</i> with the id and descriptor fields from listData.

```
"script": "<%
   var populateInstanceList= function(id) {
      if( !(empty id)) {
         var listData = supervisoryOrgMembers.invoke({'id': id[0]});
         orgMembersList.setValues(listData.data.map(x => {{'id' : x.id, 'descriptor' : x.descriptor}}));
      } else {
         orgMembersList.setValues([]);
      }
   };
%>"
```

Notes:

-   When the user selects a worker from <i>orgList</i>, the `onChange` event handler:

    -   Invokes the deferred endpoint <i>supervisoryOrgMembers</i> with the `id` of the selected value to get the members of the input organization ID.

        ```
        var listData = supervisoryOrgMembers.invoke({'id': id[0]});
        ```

    -   Calls the `map` method on <i>listData.data</i>. The `map` method uses a closure function to create a map of `id` and `descriptor` fields, and converts the map to a list. Then the `setValues` method populates <i>orgMembersList</i> with the new list.

        ```
        orgMembersList.setValues(listData.data.map(x => {{'id' : x.id, 'descriptor' : x.descriptor}}));
        ```


-   The target `instanceList`, <i>orgMembersList</i>, initializes its `values` with an empty list.


The sample endpoints:

```
  {
    "name": "supervisoryOrgs",
    "baseUrlType": "workday-staffing",
    "url": "<% '/supervisoryOrganizations' %>",
    "authType": "sso"
  },
  {
    "name": "supervisoryOrgMembers",
    "baseUrlType": "workday-staffing",
    "url": "<% '/supervisoryOrganizations/' + id + '/members' %>",
    "authType": "sso",
    "deferred": true
  }
```

## <a id="section_1"></a>Populating a List with the onSearch Event

The `onSearch` event triggers when a user enters a search string on the `instanceList`. You can use an `onSearch` event handler to customize the list of values based on the search string.

<b>Note:</b> Ensure that you initialize the `instanceList` values when the page loads.

The `onSearch` event is aware of the context that triggered it. You can use the `onSearch` event to dynamically populate the `instanceList` in a `grid` or `panelList`. The `onSearch` event knows which specific row or panel triggered the event.

The `event.query` read-only property contains the search string entered on the `instanceList`widget.

This sample `panelList` has 2 `instanceList`s: the first is a list of worker types, and the second is a list of workers The `onSearch` triggered from the worker `instanceList` knows the selected worker type in the same panel.

```
{
  "type": "panelList",
  "id": "myPanelList",
  "panels": "<% [1, 2] %>",
  "panelName": "panelData",
  "children": [
  {
    "type": "instanceList",
    "id": "workerType",       
    "instanceList": [
      {
          "id": "full-time",
          "descriptor": "Full-Time"
      },
      {
          "id": "contractor",
          "descriptor": "Contractor"
      }
    ]
  },
  {
    "type": "instanceList",
    "id": "worker",
    "multiSelect": true,
    "values": "<% [] %>",
    "onSearch": "<%
      // onSearch knows the context the workerType in the same panel.
      const type = workerType.selectedEntries[0].descriptor;

      // event.query is the input search string.
      const q = event.query + ' ' + type;
      [
          {
            'id': q + ' id_1',
            'descriptor': q + ' worker 1'
          },
          {
            'id': q + ' id_2',
            'descriptor': q + ' worker 2'
          }
      ];
    %>"
  }
 ]
}
```

In this next sample `instanceList`, the `onSearch` event calls deferred endpoints to populate the list of organization members based on an input employee ID.

```
  {
  "type": "instanceList",
  "id": "memberList",
  "label": "Org members (enter an employee ID)",
  "multiSelect": true,
  "values": "<% [] %>",
  "onSearch": "<%
     // event.query is the input search string.
     const employee = getEmployee.invoke({'employeeId': event.query});
     if (! empty employee.primaryJob.supervisoryOrganization.id) {
      const searchResult = getOrgMembers.invoke({'orgId': employee.primaryJob.supervisoryOrganization.id});
      searchResult.data ?? []
     } else {
      []
     }        
  %>"
}
```

The sample deferred endpoints:

```
{
  "name": "getEmployee",
  "baseUrlType": "workday-staffing",
  "url": "<% 'workers/Employee_ID=' + employeeId <%",
  "deferred": true,
  "ignoreFailures": [
    {"code": 404,
       "codeName": "Not found"}
    ]
},
{
  "name": "getOrgMembers",
  "baseUrlType": "workday-staffing",
  "url": "<% 'supervisoryOrganizations/' + orgId + '/members' <%",
  "deferred": true,
  "ignoreFailures": [
    {"code": 404,
       "codeName": "Not found"}
    ]
}     
```

## <a id="section_multiSelect"></a>Enabling Multiple Selections

To enable a user to select multiple values on the list, set the `multiSelect` attribute to true. By default, a user can select only 1 value from an `instanceList`.

## <a id="section_sll_5yz_spb"></a>Setting the Selected Values on the List

To set the default, selected values, specify:

-   <b>selectedValues attribute</b>

    The `selectedValues` attribute enables you to specify a list of IDs whose descriptor values display as default values on the widget. The IDs in `selectedValues` must be a subset of all IDs in the `values` or `instanceList` attributes.

    <b>Note:</b> You can only set the `selectedValues` attribute when the page loads the `instanceList` widget. You can't set `selectedValues` in an event handler. With PMD Scripting, use the `setValue` method instead.

    This sample `instanceList` assumes a widget named `savedWorkderId` that stores an ID from the `workersEndpoint`:

    ```
    {
      "type": "instanceList",
      "label": "instanceList with displayKey and selectedValues",
      "id": "instanceListId",
      "values": "<% workersEndpoint.data %>",
      "selectedValues": "<% [ savedWorkerId.value ] %>"
    }
    ```

    This sample `radioGroup` sets `selectedValues` based on the value of the preceding sample `instanceList`:

    ```
    {
      "type": "radioGroup",
      "label": "radioGroup with Selected Value",
      "id": "radioGroupWithSelectedValues",
      "values": "<% workersEndpoint.data %>",
      "selectedValues":
      "<% ! empty instanceListId.value ? [ instanceListId.value[0] ] : null %>"
    }
    ```

    Suppose the `instanceList` sets `"multiSelect": "true"` to allow multiple selections. This next sample `instanceList` conditionally sets `selectedValues` based on the multiple values of the preceding sample `instanceList`:

    ```
    {
      "type": "instanceList",
      "label": "instanceList with Selected Value",
      "id": "instanceListWithSelectedValues",
      "values": "<% workersEndpoint.data %>",
      "multiSelect": "true",
      "selectedValues":
         "<% ! empty instanceListId.value ? instanceListId.value : null %>"
    }
    ```

    The sample endpoint:

    ```
    {
      "baseUrlType": "workday-staffing",
      "name": "workersEndpoint",
      "authType": "sso",
      "url": "<% '/workers?search=' + queryParams.workerName %>"
    }
    ```

-   <b>selectedValuesAndDescriptors attribute</b>

    The `selectedValuesAndDescriptors` attribute enables you to specify a list of IDs and descriptors, which display as default values on the widget. Although the `selectedValuesAndDescriptors` attribute is similar to `selectedValues`, `selectedValuesAndDescriptors`:

    -   Requires both ID and descriptor fields.
    -   Doesn't need to be a subset of the `values` or `instanceList` attributes.

    <b>Note:</b> You can only set the `selectedValuesAndDescriptors` attribute when the page loads the `instanceList` widget. You can't set `selectedValuesAndDescriptors` in an event handler. With PMD Scripting, use the `setValue` method instead.

    Example:

    ```
    {
      "type": "instanceList",
      "multiSelect": "true",
      "id": "instanceListSelectedValuesAndDescriptors",
      "label": "instanceList with selectedValuesAndDescriptors",
      "values": "<% workers.data %>",
      "selectedValuesAndDescriptors": "<% executiveWorkers.data %>"
    } 
    ```

    You can also conditionally set `selectedValuesAndDescriptors` based on the value of another widget.

-   <b>setValue method</b>

    To set the selected values in a script, call the `setValue([idList])` method. If you need to set the `selectedValues` property of a list from an `onChange` event handler, use the `setValue([idList])` method. Specify an input list of IDs, which must be a subset of all IDs in the `instanceList`. Example: `['id1', 'id2']`.

    <b>Note:</b> The `setValue` method is different from `setValues` method:

    -   `setValue([idList])` - Use `setValue` to set only the default, selected values on the list. Each item on the input list must contain <i>only</i> the `id` value.
    -   `setValues([idAndDescriptorList])` - Use `setValues` to populate the list with all possible values. Each item on the input list contains both the `id` and `descriptor` values. Note that the input list can include other fields in addition to the `id` and `descriptor` fields.

    This snippet shows an `instanceList` with an `onChange` event handler that sets the selected values of another `instanceList`. Note that `allOrgMembers.map(item => {item.id})` is the list of all `id` fields from the `orgMembers` endpoint. Therefore the `orgMembersList` displays all values as selected by default.

    ```
    {
      "type": "instanceList",
      "id": "supervisoryOrgsList",
      "label": "Select an Organization",
      "values": "<% supervisoryOrgs.data %>",
      "onChange": "<%
       if ( ! empty (self.value[0]) ) {
          var allOrgMembers = orgMembers.invoke( { 'id' : self.value[0] } ).data;
          orgMembersList.setValues( allOrgMembers );
          orgMembersList.setValue( allOrgMembers.map(item => {item.id}) );
       } else {
           orgMembersList.setValues([]);
       }
      %>"
    },
    {
      "type": "instanceList",
      "id": "orgMembersList",
      "label": "Select organization members",
      "multiSelect": "true",
      "instanceList": [
        {
          "id": "foo",
          "descriptor": "bar"
        }
      ]
    }
    ```

    The sample endpoints:

    ```
      {
        "name": "supervisoryOrgs",
        "baseUrlType": "workday-staffing",
        "url": "<% '/supervisoryOrganizations' %>",
        "authType": "sso"
      },
      {
        "name": "orgMembers",
        "baseUrlType": "workday-staffing",
        "url": "<% '/supervisoryOrganizations/' + id + '/members' %>",
        "authType": "sso",
        "deferred": true
      }
    ```



## <a id="section_persistSelectedValues"></a>Persisting Selected Values

To submit selected values to outbound endpoints, use these attributes:

-   <b>valueOutBinding</b>

    The `valueOutBinding` attribute enables you to bind the selected value to a request field sent to the outbound endpoint.

    This sample `instanceList` sends the ID of the selected value to the `relationshipManager.id` field of the `charity` endpoint.

    ```
    {
      "type": "instanceList",
      "id": "instanceListWorkerSearch",
      "label": "Relationship Manager",
      "required": "<% true %>",
      "values": "<% [worker] %>",
      "selectedValues": "<% [worker] %>",
      "valueOutBinding": "charity.relationshipManager.id"
    }
    ```

    The sample `instanceList` uses the `worker` endpoint, which returns a map containing 1 worker. Because the `values` and `selectedValues` expect a list, with PMD Scripting, you can transform the map to a list by specifying `[worker]`.

    The sample `charity` outbound endpoint:

    ```
    {
      "name": "charity",
      "baseUrlType": "app",
      "url": "charities",
      "httpMethod": "POST",
      "authType": "sso",
      "values": [
        {
          "outboundPath": "createdBy.id",
          "value": "<% worker.id %>"
        },
        {
          "outboundPath": "image.id",
          "value": "<% (!empty(charityImage.id)) ? charityImage.id : null %>"
        }
      ]
    }
    ```

    The sample JSON sent to the `charity` endpoint:

    ```
    "relationshipManager": {
       "id": "3aa5550b7fe348b98d7b5741afc65534"
    }
    ```

-   <b>valuesOut</b>

    The `valuesOut` attribute enables you to bind 1 or more selected values to multiple request fields sent to outbound endpoints.

    This sample `instanceList` sends:

    -   The ID of the selected value to the `relationshipManager.id` field of the `charity` endpoint.
    -   A concatenated description to the `description` field of the `charity` endpoint.

    ```
    {
      "type": "instanceList",
      "id": "instanceListWorkerSearch",
      "label": "Relationship Manager",
      "required": "<% true %>",
      "values": "<% [worker] %>",
      "valuesOut": [
        {
          "value": "<% self.value[0] %>",
          "valueOutBinding": "charity.relationshipManager.id"
        },
        {
          "value": "<% '[Sponsor ID: ' + self.value[0] + ']  ' + description.value  %>",
          "valueOutBinding": "charity.description"
        }
      ]
    }
    ```

    The sample JSON sent to the `charity` endpoint:

    ```
    "relationshipManager": {
       "id": "3aa5550b7fe348b98d7b5741afc65534"
    },
    "description": "[Sponsor ID: 3aa5550b7fe348b98d7b5741afc65534] Annual drive"
    ```



With PMD Scripting, you can use an `onSend` event handler to send the selected list value to the outbound endpoint. For details, see `onSend` in [Reference: PMD Scripting Events](/wcp_docs/tgy1581495452394.html).

## <a id="section_getSelectedValues"></a>Getting the Selected Values

To get the values that a user has selected on the `instanceList`, use these properties:

-   <b>value</b>

    The `value` attribute returns an array containing the IDs of the values that the user has selected. You can use `value` to set the `selectedValues` attribute of another widget. Note that `selectedValues` displays the default selected values on the list.

    The `selectedValues` attribute of this sample `instanceList` uses all selected values from another list, `instanceListId.value`.

    ```
    {
      "type": "instanceList",
      "label": "instanceList with Selected Value",
      "id": "instanceListWithSelectedValues",
      "values": "<% workersEndpoint.data %>",
      "multiSelect": "true",
      "selectedValues":
         "<% ! empty instanceListId.value ? instanceListId.value : null %>"
    }
    ```

    To get the first (or only) selected value on the list, use `value[0]`. This sample `radioGroup` uses the first selected value of another list, `instanceListId.value[0]`.

    ```
    {
      "type": "radioGroup",
      "label": "radioGroup with selectedValues based on instanceListId's value",
      "id": "radioGroupWithSelectedValuesX",
      "values": "<% workersEndpoint.data %>",
      "selectedValues":
      "<% ! empty instanceListId.value ? [ instanceListId.value[0] ] : null %>"
    }
    ```

-   <b>selectedEntries</b>

    `selectedEntries` returns a list of maps containing the `id` and `descriptor` fields of the selected entries. Example: `selectedEntries[0].descriptor` returns the display value of the selected entry.



## <a id="section_multiLevel"></a>Defining a Multilevel List

See [Concept: Multilevel Lists](/wcp_docs/GUID-12f151a8-6f26-4bba-a8fb-b5de59767981-enHYPHENus.html).

## <a id="section_searchEndpoint"></a>Providing a Search Endpoint

By default, the search prompt on an `instanceList` searches the preloaded values on the list. You can use the `searchEndPoint`attribute to provide a search endpoint that accepts the search value entered by the user and returns the list of selectable values. A search endpoint enables you to limit the scope of the search on a potentially large data source, which affects the load performance of the `instanceList`. When you use a search endpoint, you can avoid preloading a huge amount of data on the `instanceList` and only fetch the data requested by the user. A user can select from both search results and preloaded values, if any.

<b>Note:</b> 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. See the <i>Populating a List with the onSearch Event</i>  section.

To provide a search endpoint, set these attributes:

-   <b>searchEndPoint</b>

    In `endPoints[]`, define a deferred endpoint that uses the `instanceListQuery` variable as the query parameter. `instanceListQuery` stores the value entered by the user on the search prompt of the `instanceList`. Set `"deferred": "true"`. To prevent the invocation of the search endpoint if the user hasn't entered a search value, set `"exclude": "<% empty instanceListQuery %>"`.

    This endpoint is a sample search endpoint:

    ```
    "endPoints": [
        {
          "name": "workerSearch",
          "baseUrlType": "workday-staffing",
          "url": "<% '/workers?search=' + instanceListQuery %>",
          "exclude": "<% empty instanceListQuery %>",
          "authType": "sso",
          "deferred": true
        },
        ...
    ]
    ```

    On the `instanceList` tag, set the `searchEndPoint` attribute to the name of the search endpoint. You can only set the `searchEndPoint` to a single endpoint.

-   <b>searchResultValues</b>

    The `searchEndPoint` attribute requires the `searchResultValues` attribute, which specifies the data returned by the search endpoint. The `searchResultValues` must be a list containing the `id` and `descriptor` fields of the selectable values.

    This sample `instanceList` uses the `searchEndPoint` and `searchResultValues` attributes:

    ```
    {
       "type": "instanceList",
       "id": "instanceListWorkerSearch",
       "label": "Worker",
       "values": "<% workers.data %>",
       "multiSelect": false,
       "searchEndPoint": "<% endpoints.workerSearch %>",
       "searchResultValues": "<% workerSearch.data %>"
    }
    ```



## <a id="section_localSearch"></a>Enabling Local Search on a Multilevel List

If the selectable data in a list is locally available, you can set the `searchValues` attribute to the local data. Using local data avoids the need to call a search endpoint and recursive deferred endpoints for each sublevel in the list.

<b>Note:</b> Instead of using `searchValues`, you can use the `onSearch` event of the `instanceList`to return a list of values. See the <i>Populating a List with the onSearch Event</i> section.

To use `searchValues` in a multilevel list:

-   Specify the `monikerLevels` attribute of a multilevel `instanceList`.
-   The local data must contain the fields specified by the `idKey` and `displayKey` attributes of the `instanceList`. If not specified, the local data must contain the `id` and `descriptor` fields.
-   Don't use `searchEndPoint` and `searchResultValues`. If you specify both `searchValues` and `searchEndPoint`, `searchEndPoint` takes precedence.


This sample `instanceList` uses `searchValues` with a script that returns the list and search values:

```
{
  "type": "instanceList",
  "label": "Multilevel list with local search",
  "multiSelect": "true",
  "id": "countryLocalSearchId",
  "values": "<% countriesLocalSearch.getData() %>",
  "searchValues": "<% list:flatten(list:mapAttribute(countriesLocalSearch.getData(), 'cities')) %>",
  "monikerLevels": [
    {
      "type": "monikerLevel",
      "levelValues": "<% list:filter(countriesLocalSearch.getData(), 'id', countryLocalSearchId.promptSelections[0])[0].cities %>"
    }
  ]
}
```

Although you wouldn't typically load a significant amount of list data with a script, this `getData` function in a script module is just for illustration purposes.

```
var getData = function(){
  var data = [
    {
      "id": "usa",
      "descriptor": "United States of America",
      "cities": [
        {
          "id": "san_francisco",
          "descriptor": "San Francisco"
        },
        {
          "id": "los_angeles",
          "descriptor": "Los Angeles"
        }
      ]
    },
    {
      "id": "japan",
      "descriptor": "Japan",
      "cities": [
        {
          "id": "tokyo",
          "descriptor": "Tokyo"
        },
        {
          "id": "osaka",
          "descriptor": "Osaka"
        }
      ]
    }
  ]
}
{
  "getData": getData
}
```

## <a id="section_relatedActions"></a>Enabling the Related Actions Menu

An `instanceList` widget on a view page can display the related actions menu next to the instances on the list. The related actions menu displays a window with a cascading menu of links to related tasks. Enabling the related actions menu automatically enables the instance view link, which is a hyperlink that navigates to the <b>View</b> page of that instance.

To enable the related actions menu and view link:

-   For an `instanceList` tag using the `instanceList` attribute:

    Set the `wid` attribute on the `instance` item within the list. Specify the binding to the ID field containing the instance Workday ID.

    By default, specifying the `wid` attribute on the `instance` enables both the related actions menu and view link. To disable the view link and display it as plain text, set the `view` attribute of `instanceList` to `false`. To disable the related actions menu, set the `relatedTask` attribute of `instanceList` to `false`.

    This sample `grid` sets the `wid` in the `instanceList` cell template:

    ```
    {
      "label": "Workers with Links and Related Actions Menu",
      "id": "gridWorker",
      "type": "grid",
      "gridType": "LIST",
      "rows": "<% workers.data %>",
      "rowVariableName": "thisRow",
      "columns": [
        {
          "columnId": "column1",
          "label": "Worker",
          "id": "column1",
          "type": "column",
          "cellTemplate": {
            "type": "instanceList",
            "instanceList": [
              {
                "id": "<% thisRow.id %>",
                "descriptor": "<% thisRow.descriptor %>",
                "wid": "<% thisRow.id %>"
              }
            ]
          }
        },
        . . .
      ]
    }
    ```

    For more details, see the `wid` attribute description on [instance](/wcp_docs/mvv1530164381144.html).

-   For an `instanceList` tag using the `instanceListLoopTag` attribute:

    Set the `wid` attribute on the `templateInstance` in `instanceListLoopTag`. Specify the binding to the ID field containing the instance Workday ID.

    By default, specifying the `wid` attribute on the `templateInstance` enables both the related actions menu and view link. To disable the view link and display it as plain text, set the `view` attribute of `instanceList` to `false`. To disable the related actions menu, set the `relatedTask` attribute of `instanceList` to `false`.

    This sample `instanceList` sets the `wid` in the `templateInstance`:

    ```
    {
      "type": "instanceList",
      "label": "instanceList using instanceListLoopTag with wid for related actions",
      "id": "instanceListWithWid",
      "instanceListLoopTag": {
        "id": "instanceLoopWithWid",
        "type": "instanceLoop",
        "templateInstance": {
          "id": "<% thisInstance.primaryJob.jobProfile.id %>",
          "descriptor": "<% thisInstance.primaryJob.jobProfile.descriptor %>",
          "wid": "<% thisInstance.primaryJob.jobProfile.id %>"
        },
        "on": "<% workersEndpoint.data %>",
        "as": "thisInstance"
      }
    }
    ```

    For more details, see the `wid` attribute description on [instance](/wcp_docs/mvv1530164381144.html).

-   For an `instanceList` tag using the `values` attribute:

    Set the `widKey` attribute on the `instanceList`. Specify the string name of the field that contains the Workday ID of the instance.

    By default, specifying the `widKey` attribute on the `instanceList` enables both the related actions menu and view link. To disable the view link and display it as plain text, set the `view` attribute of `instanceList` to `false`. To disable the related actions menu, set the `relatedTask` attribute of `instanceList` to `false`.

    This sample `instanceList` sets the `widKey`:

    ```
    {
      "type": "instanceList",
      "label": "instanceList with widKey for related actions",
      "id": "instanceListWithWidkey",
      "values": "<% workersEndpoint.data %>",
      "widKey": "id"
    },
    ```

    For more details, see `widKey` in the [Attributes](/wcp_docs/hcb1512514976081.html#section-attributes) section.



This sample `instanceList` includes the `view` and `relatedTask` attributes, which dynamically disable or enable the instance link and related actions menu, respectively.

```
{
  "type": "instanceList",
  "id": "instanceListWithRelatedActions",
  "values": "<% workersEndpoint.data %>",
  "widKey": "id",
  "view": "<% pageVariables.showInstanceLink  %>",
  "relatedTask": "<% pageVariables.showRelatedActions %>"
}
```

### Related Information

[Tutorial: Get User Input with Instance Lists](https://wd5.myworkday.com/workday/learning/course/9a472bd8cffb101f2bb1e5364a450000?type=9882927d138b100019b928e75843018d)