Get list group - Forms | iTwin Platform

REST API Overview

Overview

Samples

Reference

Changelog

Forms

Download API definition:

Get list group

GET https://api.bentley.com/forms/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 forms:read.

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

Request

Request parameters

template

Yes

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

listGroupId

template

Yes

The list group's ID.

Request headers

Authorization

Yes

OAuth access token with scope forms:read

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

Response

Response 200 OK

json

{
    "listGroup": {
        "id": "1d49859f-0757-423a-b850-9b6ae0a088c6",
        "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 Response

TableSchema

listGroup

list-group

List Group

TableSchema

String

The unique ID of this list group. Will be the same as the list group ID in the URL.

lists

String[]

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.

TableSchema

No data.

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.

TableSchema

error.code

String

Short string indicating the general category of error that occurred, such as '{Resource}NotFound'.

error.message

String

Longer string explaining to developers why the error occurred.

error.target

String,null

If relevant, this is the name of the property, URL template parameter, or query parameter that caused the error.

Error

Contains error information and an optional array of more specific errors.

TableSchema

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String

The target of the error.

details

ErrorDetails[]

Optional array of more specific errors.

Error Details

Contains error information.

TableSchema

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String

The target of the error.

Error Response

TableSchema

error

Error

Error information.