Creates a new form data instance. The user must specify the ID of a form definition to associate the instance with; that will set the instance's form type as well as determine how clients such as the CONNECT Forms web app will display it. The form definition ID should be obtained by calling the 'Get project form definitions' endpoint.
Permissions
To use this endpoint, the user is required to have the ProjectWise Forms Create (Forms_CreateAccess) permission for the project, or for the form's definition if form definition security is specified.
Authentication
Requires Authorization header with valid Bearer token for scope forms:modify.
For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.
Request headers
OAuth access token with scope forms:modify
Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.
Request body
The ID of the form definition (obtained from the Get project form definitions query) to associate this form with. The chosen form definition will be used to display the form in the Forms webapp and other Bentley applications. If no form definition exists in the current project for the form type you wish to create, please have a project administrator create or import such a form definition using Bentley's Form Designer.
Brief title/description of the form.
Detailed description of the form.
The date by which an action should be taken on this form. Applications will use this to determine whether a form is near due or overdue.
The form's new workflow status, if applicable.
The primary user or role assigned to this form. Defaults to current user if not specified.
For cases when the form is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.
Origin info. An object linking the form to an entity outside the Forms service, such as a file in Storage or an element in an iModel, that the form was created to pertain to.
Origin info. Describes a rectangular-prism area of the model that the form pertains to.
Origin info. Describes a point in 3D space that the form pertains to. May or may not be based on the position of a particular element.
Origin info. Describes a view of the model that shows the relevant elements the form pertains to.
The date and time represented in the model where the form pertains (if in a 4D model).
Any custom properties that are defined in the Form Designer for forms of this form's type may be set here.
Example
{ "subject": "Design Meeting 2021-02-07", "description": "Meeting minutes", "formId": "ZaZaZaYbYav2qwer_-wqer-___wqerqwetaqtewq123", "dueDate": "2021-02-27T00:00:00Z", "status": "Draft", "assignee": { "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, "assignees": [{ "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, { "displayName": "Jim Jay", "id": "bd888888-8880-4888-9888-88865ff26888" } ], "sourceEntity": { "iModelElement": { "modelName": "Grand Central Station", "modelId": "ce999999-3330-4333-9333-24465ff26000", "elementId": "0x20000001917", "changeSetId": "c2c91fa9d03d1697cd265367f22f23e69f4a463d" } }, "modelPin": { "location": { "x": 239397.84550275817, "y": 3969886.4094498586, "z": 37.408973499239124 }, "description": "Location of changed element" }, "modelView": { "iModelJsView": "01ababab-1230-4567-9012-88865ff26888", "cameraView": { "viewPoint": { "x": 200000, "y": 300000, "z": 37 }, "direction": { "x": 2, "y": 3, "z": 30 }, "up": { "x": 0, "y": 0, "z": 1 }, "viewToWorldScale": 10, "fieldOfView": 90 } }, "modelEventDateTime": "2021-02-27T11:13:33Z", "boundingBox": { "lowerLeftPoint3D": { "x": 0, "y": 1, "z": 2 }, "upperRightPoint3D": { "x": 3, "y": 4, "z": 5 } }, "location": { "longitude": -40, "latitude": -30, "elevation": 200, "description": "Construction site" }, "properties": { "MeetingLeader": "Sue Doe" } }
The ID of the form definition (obtained from the Get project form definitions query) to associate this form with. The chosen form definition will be used to display the form in the Forms webapp and other Bentley applications. If no form definition exists in the current project for the form type you wish to create, please have a project administrator create or import such a form definition using Bentley's Form Designer.
Brief title/description of the form.
Detailed description of the form.
The date by which an action should be taken on this form. Applications will use this to determine whether a form is near due or overdue.
The form's new workflow status, if applicable.
The primary user or role assigned to this form. Defaults to current user if not specified.
For cases when the form is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.
Origin info. An object linking the form to an entity outside the Forms service, such as a file in Storage or an element in an iModel, that the form was created to pertain to.
Origin info. Describes a rectangular-prism area of the model that the form pertains to.
Origin info. Describes a point in 3D space that the form pertains to. May or may not be based on the position of a particular element.
Origin info. Describes a view of the model that shows the relevant elements the form pertains to.
The date and time represented in the model where the form pertains (if in a 4D model).
Any custom properties that are defined in the Form Designer for forms of this form's type may be set here.
Example
{ "subject": "Design Meeting 2021-02-07", "description": "Meeting minutes", "formId": "ZaZaZaYbYav2qwer_-wqer-___wqerqwetaqtewq123", "dueDate": "2021-02-27T00:00:00Z", "status": "Draft", "assignee": { "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, "assignees": [{ "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, { "displayName": "Jim Jay", "id": "bd888888-8880-4888-9888-88865ff26888" } ], "sourceEntity": { "storageFile": { "fileName": "Blueprint.pdf", "folderId": "CmU4rECnwEiTzxEGX_Ji2wJ1d6xAp8BIk88RBl_yYts", "fileId": "CmU4rECnwEiTzxEGX_Ji28lD7eJuPPRDo85GSRwo7FU" } }, "modelPin": { "location": { "x": 239397.84550275817, "y": 3969886.4094498586, "z": 37.408973499239124 }, "description": "Location of changed element" }, "modelView": { "iModelJsView": "01ababab-1230-4567-9012-88865ff26888", "cameraView": { "viewPoint": { "x": 200000, "y": 300000, "z": 37 }, "direction": { "x": 2, "y": 3, "z": 30 }, "up": { "x": 0, "y": 0, "z": 1 }, "viewToWorldScale": 10, "fieldOfView": 90 } }, "modelEventDateTime": "2021-02-27T11:13:33Z", "boundingBox": { "lowerLeftPoint3D": { "x": 0, "y": 1, "z": 2 }, "upperRightPoint3D": { "x": 3, "y": 4, "z": 5 } }, "location": { "longitude": -40, "latitude": -30, "elevation": 200, "description": "Construction site" }, "properties": { "MeetingLeader": "Sue Doe" } }
The ID of the form definition (obtained from the Get project form definitions query) to associate this form with. The chosen form definition will be used to display the form in the Forms webapp and other Bentley applications. If no form definition exists in the current project for the form type you wish to create, please have a project administrator create or import such a form definition using Bentley's Form Designer.
Brief title/description of the form.
Detailed description of the form.
The date by which an action should be taken on this form. Applications will use this to determine whether a form is near due or overdue.
The form's new workflow status, if applicable.
The primary user or role assigned to this form. Defaults to current user if not specified.
For cases when the form is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.
Origin info. An object linking the form to an entity outside the Forms service, such as a file in Storage or an element in an iModel, that the form was created to pertain to.
Origin info. Describes a rectangular-prism area of the model that the form pertains to.
Origin info. Describes a point in 3D space that the form pertains to. May or may not be based on the position of a particular element.
Origin info. Describes a view of the model that shows the relevant elements the form pertains to.
The date and time represented in the model where the form pertains (if in a 4D model).
Any custom properties that are defined in the Form Designer for forms of this form's type may be set here.
Example
{ "subject": "Design Meeting 2021-02-07", "description": "Meeting minutes", "formId": "ZaZaZaYbYav2qwer_-wqer-___wqerqwetaqtewq123", "dueDate": "2021-02-27T00:00:00Z", "status": "Draft", "assignee": { "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, "assignees": [{ "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, { "displayName": "Jim Jay", "id": "bd888888-8880-4888-9888-88865ff26888" } ], "modelPin": { "location": { "x": 239397.84550275817, "y": 3969886.4094498586, "z": 37.408973499239124 }, "description": "Location of changed element" }, "modelView": { "iModelJsView": "01ababab-1230-4567-9012-88865ff26888", "cameraView": { "viewPoint": { "x": 200000, "y": 300000, "z": 37 }, "direction": { "x": 2, "y": 3, "z": 30 }, "up": { "x": 0, "y": 0, "z": 1 }, "viewToWorldScale": 10, "fieldOfView": 90 } }, "modelEventDateTime": "2021-02-27T11:13:33Z", "boundingBox": { "lowerLeftPoint3D": { "x": 0, "y": 1, "z": 2 }, "upperRightPoint3D": { "x": 3, "y": 4, "z": 5 } }, "location": { "longitude": -40, "latitude": -30, "elevation": 200, "description": "Construction site" }, "properties": { "MeetingLeader": "Sue Doe" } }
Response 201 Created
Indicates that the form data instance was successfully created. The response body contains the form data after creation, including its id.
{ "formData": { "id": "e5Ue5Ue5U02hNz19awLcRsnTtOGubQZPhV123456789", "subject": "Design Meeting 2021-02-07", "description": "Meeting minutes", "dueDate": "2020-10-28T00:00:00Z", "boundingBox": { "lowerLeftPoint3D": { "x": 0.0, "y": 1.0, "z": 2.0 }, "upperRightPoint3D": { "x": 3.0, "y": 4.0, "z": 5.0 } }, "createdBy": "Joe User", "createdDateTime": "2021-02-08T19:39:10.7421874Z", "lastModifiedBy": "Joe User", "lastModifiedDateTime": "2021-02-08T19:39:10.7421874Z", "number": "MMN-00001", "status": "Draft", "assignee": { "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, "assignees": [{ "displayName": "Sue Doe", "id": "ac777777-7770-4777-9777-77765ff26777" }, { "displayName": "Jim Jay", "id": "bd888888-8880-4888-9888-88865ff26888" } ], "type": "Meeting Minutes", "displayName": "Design Meeting 2021-02-07", "state": "Open", "modelPin": { "location": { "x": 239397.84550275817, "y": 3969886.4094498586, "z": 37.408973499239124 }, "description": "Location of changed element" }, "modelView": { "iModelJsView": "01ababab-1230-4567-9012-88865ff26888", "cameraView": { "viewPoint": { "x": 200000, "y": 300000, "z": 37 }, "direction": { "x": 2, "y": 3, "z": 30 }, "up": { "x": 0, "y": 0, "z": 1 }, "viewToWorldScale": 10, "fieldOfView": 90 } }, "modelEventDateTime": "2021-02-27T11:13:33Z", "location": { "longitude": -40, "latitude": -30, "elevation": 200, "description": "Construction site" }, "statusColor": "#ccddee", "properties": { "MeetingLeader": "Sue Doe" } } }
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.
{ "error": { "code": "HeaderNotFound", "message": "Header Authorization was not found in the request. Access denied." } }
Response 404 Not Found
This response indicates that the specified form definition does not exist (or is inaccessible due to insufficient permissions).
{ "error": { "code": "FormDefNotFound", "message": "Requested form definition is not available.", "target": "formId" } }
Response 422 Unprocessable Entity
This response indicates that there is a problem with the format of the request body. Most likely causes: The 'formId' property is missing, an unrecognized standard or custom property was added, a standard property was set in the 'properties' object instead of the top-level object, the body is invalid JSON, or a property was set to a value of the wrong type.
{ "error": { "code": "InvalidFormDataRequest", "message": "Cannot create form data.", "details": [{ "code": "InvalidProperty", "message": "This property is not recognized. If it is a custom property, set it in the 'properties' object.", "target": "badProp" }, { "code": "InvalidProperty", "message": "This property is not a custom property and should be set on the root object directly instead of inside the 'properties' object.", "target": "description" }, { "code": "ReadOnlyProperty", "message": "This property is read-only and cannot be set by the client.", "target": "displayName" } ] } }
Response 429 Too many requests
This response indicates that the user has sent too many requests in a given amount of time.
{ "error": { "code": "TooManyRequests", "message": "More requests were received than the subscription rate-limit allows." } }
The number of requests exceeds the rate-limit for the client subscription.
Form Data Instance (get)
Contains the full data of this form. Any property that was never set on the form will be omitted from the response.
Unique identifier for this instance. Read-only.
Name that should be used to show this form in a list of form data instances in the UI. This is read-only. Project managers can configure how this is generated; usually, it will be the value of another property.
The ID of the form definition that this form was created with. Note: This property will only be returned during the 'Get form data details' query, not in the result of a Create or Modify operation.
Brief title/description of the form.
Detailed description of the form.
Read-only. Describes which domain of work the form involves, which determines what applications will show it. This is automatically set based on the associated form definition referenced by the formId property.
An human-readable identifier for the form, consisting of an alphanumeric prefix (that can be configured by the project administrator) followed by an auto-incrementing number. Read-only.
The date by which an action should be taken on this form. Applications will use this to determine whether a form is near due or overdue.
The current workflow status the form is in right now.
Indicates whether the form's status is an Open, Closed, or Draft status. This property is read-only.
A RBG hexadecimal color string, e.g. #ff0000. Read-only. If set, this gives a hint for how to highlight the form in a list of forms based on its current workflow status.
For cases when a form is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.
The display name of the user who originally created this form data instance. Read-only.
The date and time when this form data instance was originally created. Read-only.
The display name of the user who most recently made a change to this form data instance. Read-only.
The date and time when this form data instance was most recently edited. Read-only.
Origin info. An object linking the form to an entity outside the Forms service, such as a file in Storage or an element in an iModel, that the form was created to pertain to.
Origin info. Describes a rectangular-prism area of the model that the form pertains to.
Origin info. Describes a point in 3D space that the form pertains to. May or may not be based on the position of a particular element.
Origin info. Describes a view of the model that shows the relevant elements that the form pertains to.
The date and time represented in the model where the form pertains (if in a 4D model).
Contains all form-type-specific and user-defined properties that were set on this form. Properties set here may be strings, numbers, booleans, arrays, or objects, depending on how the project's administrator defined them in the Form Designer.
Links to related entities, if applicable.
Form Data Instance (create)
Sets property values for a form data instance being newly created.
The ID of the form definition (obtained from the Get project form definitions query) to associate this form with. The chosen form definition will be used to display the form in the Forms webapp and other Bentley applications. If no form definition exists in the current project for the form type you wish to create, please have a project administrator create or import such a form definition using Bentley's Form Designer.
Brief title/description of the form.
Detailed description of the form.
The date by which an action should be taken on this form. Applications will use this to determine whether a form is near due or overdue.
The form's new workflow status, if applicable.
The primary user or role assigned to this form. Defaults to current user if not specified.
For cases when the form is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.
Origin info. An object linking the form to an entity outside the Forms service, such as a file in Storage or an element in an iModel, that the form was created to pertain to.
Origin info. Describes a rectangular-prism area of the model that the form pertains to.
Origin info. Describes a point in 3D space that the form pertains to. May or may not be based on the position of a particular element.
Origin info. Describes a view of the model that shows the relevant elements the form pertains to.
The date and time represented in the model where the form pertains (if in a 4D model).
Any custom properties that are defined in the Form Designer for forms of this form's type may be set here.
Primary Assignee
An object describing the primary user or role assigned to a form.
The GUID identifying the user or role.
The role's name, or the user's given name and surname, as it should be displayed in an application.
Secondary Assignee
An object describing one of potentially several users or roles assigned to a form.
The GUID identifying the user or role.
The role's name, or the user's given name and surname, as it should be displayed in an application.
If true, this is a role; otherwise, it is an individual user.
Bounding Box
Origin info. Describes a rectangular-prism-shaped region in a 3D model that the form pertains to.
model-pin
Origin info. Associates a form with a single point in a model that does not necessarily correspond to a model element.
String describing the relevance of the pin's location.
Model View
Origin info. Describes the view that was visible when the form was created.
The ID of a saved view showing a location relevant to the form.
point3D
camera
Endpoint of a vector from the origin that determines which direction appears as upwards in the view.
Determines the zoom level of the camera, i.e. how much to multiply 1 distance unit in the view by to get the actual distance in meters in the model. Either this or fieldOfView should be specified, but not both.
Determines the number of degrees in the circular arc around the camera's position that is visible in the view. Either this or viewToWorldScale should be specified, but not both.
location
Origin info. The geographical location the form pertains to.
The degrees latitude of the form's location. North: positive, south: negative.
The degrees longitude of the form's location. East: positive, west: negative.
The geographical elevation above/below sea level. Units for this property are not standardized, so an application should not make assumptions about this property's value set by other applications unless that other application's units are known.
A string describing the significance of this location.
source-entity-file
Represents a file in Storage about which a form was created.
ID used to identify the file in the Storage API.
ID of the folder containing the file in the Storage API.
Name of the file, including extension.
source-entity-i-model-element
Represents an element in an iModel about which a form was created.
ID of the iModel containing the element, as it exists in the iModels API.
ID of the element. Can be a hexadecimal numeric string (space-separated to include multiple elements) or a presentation key.
ID of the changeset where the form was created.
Name of the model.
source-entity-links-file
Links to retrieve the related file, and the folder that contains it, from the Storage API.
source-entity-links-i-model-element
Links to retrieve the related element's specific changeset, or iModel in general, from the iModels API.
Dynamic Object
An object whose properties can vary depending on user customization within the project.
link
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.
Short string indicating the general category of error that occurred, such as '{Resource}NotFound'.
Longer string explaining to developers why the error occurred.
If relevant, this is the name of the property, URL template parameter, or query parameter that caused the error.
Detailed error-response
Indicates that a request failed and provides a list of details, explaining which properties or parameters in the request were incorrect. 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.
Short string indicating the general category of error that occurred, such as 'Invalid{resource}Request'.
Longer string explaining to developers why the error occurred.
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.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
Error Details
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
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.