Get form definition by ID - Forms

Forms

Download API definition:

get https://dev-api.bentley.com/forms/form-definitions/{id}

Gets the full form definition with the specified ID.

If you have permission to edit this form definition, then the response will also include a link you can follow in your browser to edit its layout in the Form Manager webapp.

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 parameters

Yes

The ID of the form definition to get. This should be an ID retrieved from the "Get project form definitions" endpoint or a form data instance's "formId" property.

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Response 200 OK

json

{
    "formDefinition": {
        "id": "e5Ue5Ue5U02hNz19awLcRgpmdo8phxZEhB123456789",
        "displayName": "Sample Form",
        "type": "Daily Log",
        "status": "Approved",
        "errorStatus": "None",
        "shareType": "ReadOnly",
        "idPrefix": "SF",
        "definition": "{\"Form\":{\"Width\":520,\"Height\":750,\"Controls\":[{\"Panel\":{\"ElementId\":\"f8b4b07c700247ee8e7be81ca9ef6528\",\"Name\":\"Canvas\",\"DisplayLabel\":\"Canvas\",\"Type\":\"Panel\",\"IsPercent\":false,\"Height\":0,\"MaxHeight\":0,\"Width\":0,\"Binding\":\"\",\"TopPosition\":0,\"LeftPosition\":0,\"IsReadOnly\":false,\"IsRequired\":false,\"StyleGroup\":\"\",\"IsCollapsible\":false,\"IsCollapsed\":false,\"ShowWindSpeed\":false,\"LayoutType\":1,\"ContentSpacing\":16,\"ContentPadding\":8,\"Children\":[{\"TextBox\":{\"ElementId\":\"c274e01b58ae4e94884f91238f65f582\",\"Name\":\"Textbox#7cf1d\",\"DisplayLabel\":\"\",\"Type\":\"TextBox\",\"FileId\":1,\"IsPercent\":true,\"Height\":38,\"MaxHeight\":0,\"Width\":50,\"Binding\":\"_Description\",\"TopPosition\":111,\"LeftPosition\":17,\"IsReadOnly\":false,\"IsRequired\":false,\"StyleGroup\":\"\",\"IsCollapsible\":false,\"IsCollapsed\":false,\"ShowWindSpeed\":false,\"IsSingleLine\":true}}]}}],\"StyleGroups\":[],\"DataBindings\":[{\"DataBinding\":{\"Binding\":\"_Description\",\"ElementId\":\"c274e01b58ae4e94884f91238f65f582\",\"Type\":\"string\",\"DisplayLabel\":\"Description\"}}],\"RelatedObjects\":[{\"RelatedObject\":{\"Type\":\"DynamicSchema:Reports\"}}],\"GpsBindingType\":\"storeAsLatLong\",\"GpsFirstBinding\":\"Latitude\",\"GpsSecondBinding\":\"Longitude\"}}",
        "_links": {
            "design": {
                "href": "https://connect-formmanager.bentley.com/designer/#/00000000-0000-0000-0000-000000000000/design/11111111-1111-1111-1111-111111111111"
            }
        }
    }
}

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 form definition with the specified ID does not exist or is inaccessible to the user.

json

{
    "error": {
        "code": "FormDefNotFound",
        "message": "Requested form definition is not available.",
        "target": "id"
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

link

href

String

json

{
    "type": "object",
    "properties": {
        "href": {
            "type": "string"
        }
    },
    "additionalProperties": false
}

Error

Contains error information.

code

String

One of a server-defined set of error codes.

target

String, null

The target of the error.

message

String

A human-readable representation of the error.

json

{
    "type": "object",
    "required": [
        "code",
        "message"
    ],
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "target": {
            "type": "string",
            "nullable": true,
            "description": "The target of the error."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "description": "Contains error information.",
    "additionalProperties": true
}

Data Binding type

The data type of the property. Not applicable if this is a grid property or the assignees property.

string

String

int

String

double

String

long

String

boolean

String

date

String

dateTime

String

_SurveyResponse

String

json

{
    "enum": [
        "string",
        "int",
        "double",
        "long",
        "boolean",
        "date",
        "dateTime",
        "_SurveyResponse"
    ],
    "type": "string",
    "description": "The data type of the property. Not applicable if this is a grid property or the `assignees` property.",
    "title": "Data Binding type"
}

Data Binding

An object mapping a property name to its data type.

Data Binding type

data-binding-type

The data type of the property. Not applicable if this is a grid property or the assignees property.

property

String

The name of a property bound to a form control. Will match how the property appears in form data JSON.

json

{
    "type": "object",
    "title": "Data Binding",
    "required": [
        "property"
    ],
    "properties": {
        "type": {
            "enum": [
                "string",
                "int",
                "double",
                "long",
                "boolean",
                "date",
                "dateTime",
                "_SurveyResponse"
            ],
            "type": "string",
            "description": "The data type of the property. Not applicable if this is a grid property or the `assignees` property.",
            "title": "Data Binding type",
            "$ref": "#/components/schemas/data-binding-type"
        },
        "property": {
            "type": "string",
            "description": "The name of a property bound to a form control. Will match how the property appears in form data JSON."
        }
    },
    "description": "An object mapping a property name to its data type.",
    "additionalProperties": false
}

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.

json

{
    "type": "object",
    "title": "Error Response",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "$ref": "#/components/schemas/Error",
            "description": "Error information."
        }
    },
    "description": "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.",
    "additionalProperties": false
}

Form Definition Details status

The form definition's availability. This can be set by a project administrator. Only form definitions set to Approved can be used to create form data instances. Possible values: 'Draft', 'Approved', 'Archived', 'Maintenance'.

Draft

String

Approved

String

Archived

String

Maintenance

String

json

{
    "enum": [
        "Draft",
        "Approved",
        "Archived",
        "Maintenance"
    ],
    "type": "string",
    "description": "The form definition's availability. This can be set by a project administrator. Only form definitions set to Approved can be used to create form data instances. Possible values: 'Draft', 'Approved', 'Archived', 'Maintenance'.",
    "title": "Form Definition Details status"
}

Form Definition Details shareType

Whether this form definition can be used in multiple iTwins. A value of null means it cannot. 'ReadOnly' and 'ReadWrite' mean it can. 'ReadOnly' means its layout can only be edited from its original iTwin, and 'ReadWrite' means its layout can be edited from any iTwin in the organization.

null

String

ReadOnly

String

ReadWrite

String

json

{
    "enum": [
        null,
        "ReadOnly",
        "ReadWrite"
    ],
    "type": "string",
    "nullable": true,
    "description": "Whether this form definition can be used in multiple iTwins. A value of `null` means it cannot. `'ReadOnly'` and `'ReadWrite'` mean it can. `'ReadOnly'` means its layout can only be edited from its original iTwin, and `'ReadWrite'` means its layout can be edited from any iTwin in the organization.",
    "title": "Form Definition Details shareType"
}

Form Definition Details errorStatus

String describing whether the form definition has problems that could prevent it from displaying (Warning) or functioning (Error or Critical) correctly. Possible values: 'None', 'Warning', 'Error', 'Critical', 'Unknown'.

None

String

Warning

String

Error

String

Critical

String

Unknown

String

json

{
    "enum": [
        "None",
        "Warning",
        "Error",
        "Critical",
        "Unknown"
    ],
    "type": "string",
    "description": "String describing whether the form definition has problems that could prevent it from displaying (Warning) or functioning (Error or Critical) correctly. Possible values: 'None', 'Warning', 'Error', 'Critical', 'Unknown'.",
    "title": "Form Definition Details errorStatus"
}

Form Definition Details

String

Unique identifier for this form definition. Can be set as the formId property in the 'Create form data' request body.

type

String

Determines which form type will be created when this form definition is used.

_links

form-definition-design-links

Form Definition Details status

form-definition-details-status

idPrefix

String, null

A prefix that appears in front of the auto-incrementing number property of each filled-out instance created from this form definition. Can be null, in which case the system fills in the prefix based on the form's type.

Form Definition Details shareType

form-definition-details-shareType, null

definition

String

A JSON string defining this form's layout, including all of its controls and their bindings, locations, and styles. As of now third-party applications are not expected to use this property. An automated custom form renderer that works with this REST API is reserved for future development.

discipline

String

The discipline to associate the form with.

displayName

String, null

The name of this form definition as it should be displayed to users if they are choosing which form definition to use for a new form.

Form Definition Details errorStatus

form-definition-details-errorStatus

dataBindings

data-binding[]

json

{
    "type": "object",
    "title": "Form Definition Details",
    "required": [
        "id",
        "displayName",
        "type",
        "status"
    ],
    "properties": {
        "id": {
            "type": "string",
            "description": "Unique identifier for this form definition. Can be set as the formId property in the 'Create form data' request body."
        },
        "type": {
            "type": "string",
            "description": "Determines which form type will be created when this form definition is used."
        },
        "_links": {
            "$ref": "#/components/schemas/form-definition-design-links"
        },
        "status": {
            "enum": [
                "Draft",
                "Approved",
                "Archived",
                "Maintenance"
            ],
            "type": "string",
            "description": "The form definition's availability. This can be set by a project administrator. Only form definitions set to Approved can be used to create form data instances. Possible values: 'Draft', 'Approved', 'Archived', 'Maintenance'.",
            "title": "Form Definition Details status",
            "$ref": "#/components/schemas/form-definition-details-status"
        },
        "idPrefix": {
            "type": "string",
            "nullable": true,
            "description": "A prefix that appears in front of the auto-incrementing `number` property of each filled-out instance created from this form definition. Can be null, in which case the system fills in the prefix based on the form's type."
        },
        "shareType": {
            "enum": [
                null,
                "ReadOnly",
                "ReadWrite"
            ],
            "type": "string",
            "nullable": true,
            "description": "Whether this form definition can be used in multiple iTwins. A value of `null` means it cannot. `'ReadOnly'` and `'ReadWrite'` mean it can. `'ReadOnly'` means its layout can only be edited from its original iTwin, and `'ReadWrite'` means its layout can be edited from any iTwin in the organization.",
            "title": "Form Definition Details shareType",
            "$ref": "#/components/schemas/form-definition-details-shareType"
        },
        "definition": {
            "type": "string",
            "description": "A JSON string defining this form's layout, including all of its controls and their bindings, locations, and styles. As of now third-party applications are not expected to use this property. An automated custom form renderer that works with this REST API is reserved for future development."
        },
        "discipline": {
            "type": "string",
            "description": "The discipline to associate the form with."
        },
        "displayName": {
            "type": "string",
            "nullable": true,
            "description": "The name of this form definition as it should be displayed to users if they are choosing which form definition to use for a new form."
        },
        "errorStatus": {
            "enum": [
                "None",
                "Warning",
                "Error",
                "Critical",
                "Unknown"
            ],
            "type": "string",
            "description": "String describing whether the form definition has problems that could prevent it from displaying (Warning) or functioning (Error or Critical) correctly. Possible values: 'None', 'Warning', 'Error', 'Critical', 'Unknown'.",
            "title": "Form Definition Details errorStatus",
            "$ref": "#/components/schemas/form-definition-details-errorStatus"
        },
        "dataBindings": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/data-binding"
            }
        }
    },
    "additionalProperties": false
}

form-definition-design-links

If this form definition is in an editable state and you have permission to edit form definitions, this link sends you to the Form Manager webapp where you can edit its layout. Otherwise, this link will not appear.

design

link

json

{
    "type": "object",
    "properties": {
        "design": {
            "$ref": "#/components/schemas/link"
        }
    },
    "description": "If this form definition is in an editable state and you have permission to edit form definitions, this link sends you to the Form Manager webapp where you can edit its layout. Otherwise, this link will not appear.",
    "additionalProperties": false
}

Form Definition Details Response

formDefinition

form-definition-details

json

{
    "type": "object",
    "title": "Form Definition Details Response",
    "properties": {
        "formDefinition": {
            "$ref": "#/components/schemas/form-definition-details"
        }
    },
    "additionalProperties": false
}

Was this page helpful?