Get list group - Issues | iTwin Platform

REST API Overview

Reference

Issues

Download API definition:

GET https://api.bentley.com/issues/formDefinitions/{id}/listGroups/{listGroupId}

Use this request to look up a list group, which is a nested object structure that defines the options available in a chain of cascading list form controls. (Cascading lists are a set of <select> elements where only the first one is initially enabled until an option in it is selected, and then, depending on which option was selected, the available options in the next list can vary.) Each property in the structure represents an option in a select list, and its children represent options that become available in the next list in the chain if that option is selected.

Sample Explanation

The sample for the 200 response shows an example of a list group that could be assigned to 3 controls in a form to let the user pick an American football team by conference, division, and name. Since the result has two properties ("AFC" and "NFC") as direct children of the "optionsTree" property, the first list in the cascading list chain would have two options--"AFC" and "NFC". Whichever option is chosen, its child properties become available for selection in the second list, and so forth. For example, if "AFC" and "North" were chosen for the first two lists respectively, the third list would show the available options "Bengals", "Browns", "Ravens", and "Steelers". These four properties just have empty objects as their values because this particular list group only has three layers; these options are the final options in the chain and have no descendants.

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Request

Request parameters

Yes

The ID of the form definition this list group is used in.

listGroupId

Yes

The ID of the list group to get.

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Response

Response 200 OK

json

{
    "listGroup": {
        "id": "1d49859f-0757-423a-b850-9b6ae0a088c6",
        "displayName": "Football Teams",
        "createdDateTime": "2024-08-21T15:44:09Z",
        "lists": [
            "Conference",
            "Division",
            "Team"
        ],
        "optionsTree": {
            "AFC": {
                "North": {
                    "Steelers": {},
                    "Browns": {},
                    "Bengals": {},
                    "Ravens": {}
                },
                "East": {
                    "Patriots": {},
                    "Bills": {},
                    "Dolphins": {},
                    "Jets": {}
                },
                "South": {
                    "Titans": {},
                    "Jaguars": {},
                    "Texans": {},
                    "Colts": {}
                },
                "West": {
                    "Chiefs": {},
                    "Broncos": {},
                    "Raiders": {},
                    "Chargers": {}
                }
            },
            "NFC": {
                "North": {
                    "Vikings": {},
                    "Packers": {},
                    "Bears": {},
                    "Lions": {}
                },
                "East": {
                    "Eagles": {},
                    "Giants": {},
                    "Cowboys": {},
                    "Washington": {}
                },
                "South": {
                    "Saints": {},
                    "Buccaneers": {},
                    "Panthers": {},
                    "Falcons": {}
                },
                "West": {
                    "49ers": {},
                    "Seahawks": {},
                    "Rams": {},
                    "Cardinals": {}
                }
            }
        }
    }
}

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 404 Not Found

This response indicates that the list group or its associated form definition was not found.

json

{
    "error": {
        "code": "ListGroupNotFound",
        "message": "Requested list group is not available.",
        "target": "listGroupId"
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

retry-after

The number of requests exceeds the rate-limit for the client subscription.

Definitions

List Group Details Response

listGroup

list-group-details

List Group Summary

String

The unique ID of this list group.

displayName

String

The name of this list group, as entered by its creator.

createdDateTime

Date-time, null

The date and time (UTC) when this list group's file was uploaded.

lists

String[], null

The names of the lists defined by this list group, from outermost (first) to innermost (last).

optionsTree

dynamic-object

A recursive data structure defining the options available in these lists. Its properties can have any name. For each property in the outermost object, its key should be used as the name of an option in the first list, and its value is an object whose keys correspond to the options that become available in the second list when that particular first-list option is chosen, and so forth. This pattern continues down to the last list, whose options will be represented by properties with empty object values.

Dynamic Object

An object whose properties can vary depending on user customization within the project.

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error

Error

Error information.