Forms Service

View, create, and edit details of forms that have been filled out in a project, as well as their comments, attached files, and change history.  Full CRUD functionality is available for form data, with form definitions being available in a read-only context.

Note that throughout this API the terms "form" (by itself) and "form data" both refer to the same thing: data collected from users (generally entered into controls of a UI, or programmatically generated). By contrast, a "form definition" is a piece of metadata connected to form data instances. It determines the "type" of form that is filled out, and in applications that support custom form layouts, it determines how the controls are placed in the user interface.

Form definitions should be added, imported, and customized by project administrators through the Bentley Form Manager web application; they cannot be modified using this API. The app can be found at https://connect-formmanager.bentley.com/ManageForms.aspx?projectId=(yourProjectId) where `yourProjectId` is replaced by the ID of the project being customized.

forms

## Forms API

The Forms service lets project members collect a variety of data through filling out customizable forms. Project administrators can design forms for capturing meeting minutes, daily work logs, asset and site observation results, and more. Project members can then fill out these forms while working in the field. Like an issue, a form can be assigned to a particular user and can move through statuses in a workflow as work on it is completed.
 
The Forms REST API provides access to the raw data entered into these forms, including the ability to read and set field values, attached files, and comments, as well as view the audit trail (history) of a particular filled-out form.

---

Adds a new attachment to the specified form data instance. This only creates the attachment metadata; the file will need to be uploaded through a subsequent PUT call to the URL returned in the Location header of this endpoint's response.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

add-attachment-to-form

The ID of the form data instance to add an attachment to.

OAuth access token with scope `forms:modify`

Authorization

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

Accept

Indicates that the attachment metadata was created successfully. The file should then be uploaded via PUT to the URL in the Location header.

The URL where the attachment file should be uploaded.

Location

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.

application/json;InvalidAuthorizationScheme

This response indicates that the user attempted to add an attachment to a form data instance that does not exist or is inaccessible to the user.

This response indicates that there is a problem with the format of the request body. Most likely causes: The body is not valid JSON, or the 'fileName' property is missing or not a string.

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

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

retry-after

---

Deletes the specified attachment (including both its metadata and file) from the specified form.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-attachment

The ID of the form data instance from which to delete an attachment.

attachmentId

Indicates that the attachment was successfully deleted. There is no response body in this case.

This response indicates that the attachment with the specified ID does not exist or is inaccessible to the user.

---

Retrieves the actual file contents for the attachment with the given ID. This API will attempt to infer the MIME type to return from the file's extension, but will return the default value of `application/octet-stream` if it does not recognize the extension.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-attachment-file-by-id

The ID of the form data instance for which to get an attachment.

The ID of the attachment whose file to retrieve.

OAuth access token with scope `forms:read`

This response indicates that the specified attachment does not exist (code = 'AttachmentNotFound') or that the attachment metadata instance exists but does not have an associated file (code = 'FileNotFound').

---

Retrieves the metadata for all files attached to the given form data. In order to get the contents of a file itself, use the `Get attachment file by ID` endpoint, passing the `id` from the metadata object returned by this request as the `attachmentId` parameter of that request.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-data-attachments

The ID of the form data instance for which to retrieve attachments

This response indicates that the specified form data instance does not exist or is inaccessible to the user.

---

Uploads a file's contents, associating it with the attachment metadata instance with the given ID. The request body is simply the file's bytes. If a file was already uploaded for the attachment with the given ID, that file will be overwritten.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** permission (`Forms_CommentAccess`) for the project, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

upload-attachment-file

The ID of the form data instance for which to upload an attachment file.

The ID of the previously created attachment metadata instance for which this file is being uploaded.

Indicates that the attachment file was successfully uploaded

This response indicates that the specified attachment metadata instance does not exist or is inaccessible to the user.

Indicates that the file the user attempted to upload is above the maximum size.

---

Retrieves a reverse-chronologically-ordered list of all changes that have been made to this form data instance, including authors, dates, and old vs. new property values.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-audit-trail-for-form-data

The ID of the form data instance for which to retrieve the audit trail.

---

Adds a new comment to the specified form data instance. Only the comment text is needed; the author and creation time will be automatically set by the server.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

add-comment-to-form

The ID of the form data instance to add a comment to.

Indicates that the comment was created successfully

This response indicates that the form data instance the user attempted to add a comment to does not exist or is inaccessible to the user.

This response indicates that there is a problem with the format of the request body. Most likely causes: The body is not valid JSON, or the 'text' property is missing or not a string.

---

Deletes the specified comment from the specified form.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-comment

The ID of the form data instance from which to delete a comment.

commentId

Indicates that the comment was successfully deleted. There is no response body in this case.

This response indicates that the comment with the specified ID does not exist or is inaccessible to the user.

---

Retrieves the text and metadata for all comments that have been posted to the given form data instance. If the Prefer header was specified with the value "return=representation", the response will include the email address of each comment author, though this may incur additional processing time.  If there is an extraordinarily large number of comments, only 50 distinct user email addresses will be retrieved and shown. Regardless of the Prefer header value, the "_links" object associated with each comment will provide a link to additional information about the comment author.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-data-comments

The ID of the form data instance for which to get comments

Sets the level of detail to return. For this endpoint, setting 'return=representation' will add the comment authors' email addresses to the response.

Prefer

---

Gets the specified form exported to the specified file format. Currently, the default--and only supported format--is PDF. The form with the specified ID will be laid out in the PDF according to its associated form definition.

The generated PDF will have a header at the top of each page with metadata about the form (such as its name and creation date) unless the 'includeHeader' query parameter is set to false.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

download-form-as-file

The type of file to download the form as. Currently the default, and only supported value, is 'PDF'.

fileType

If downloading as PDF, sets whether to include form metadata on the top of each page. Default is true.

includeHeader

Indicates that the file was successfully generated in the requested format. The response body consists of the generated file.

This response indicates that the specified form data instance does not exist or is inaccessible.

This response indicates that there is a problem with the format of the URL. Most likely problem: The 'fileType' parameter is set to an unsupported file type, or the 'includeHeader' parameter is set to a non-boolean value.

---

Requests that anywhere from 1 to 5 forms be exported to a file and saved in cloud-based project storage (accessible through the Storage API). Currently 'pdf' is the only supported file type. The IDs of the forms must be specified in a query string parameter named "ids", separated by commas if there is more than one. A sample request URL that exports 3 forms to a PDF is as follows--

https://api.bentley.com/forms/exportPdfToStorage?fileType=pdf&ids=abab23524535,89458jjlij,32636wtewtwt&folderId=090909877987&includeHeader=true

Note that unlike most GET requests, this is not an idempotent operation; each time it is called, a new file will be generated. The response will not contain the file itself, but links to download it from Storage.

All forms specified in the request must come from the same project, or the request will fail. The client may also specify the ID of a destination folder where the file should be saved; otherwise, it will be saved in the project's root folder.  They can also specify whether to include a textual header with form metadata at the top of each page (default) or exclude it.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

export-form-to-storage

Instance IDs of forms to export. Must include at least 1, but no more than 5, IDs, separated by commas, and they all must come from the same project.

If exporting to PDF, indicates whether to include metadata on top of each page.  Default is true.

Indicates the type of file to create. Right now PDF is the only valid option, and is the default if not specified.

The ID, as retrieved from the Storage API, of the folder where the produced file should be saved. If not set, will default to the project's root folder.

folderId

Indicates that the file was generated successfully. The response includes the generated file's filename as well as links for using the Storage API to retrieve it.

Either one of the forms specified does not exist (code = 'FormDataNotFound') or the destination folder does not exist (code = 'FolderNotFound').

This response indicates that there is a problem with the request parameters. Depending on the problem, the 'details' array may include specific errors.

---

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](https://developer.bentley.com/apis/overview/authorization/) page.

---

create-form-data

Design Meeting 2021-02-07

Indicates that the form data instance was successfully created. The response body contains the form data after creation, including its id.

This response indicates that the specified form definition does not exist (or is inaccessible due to insufficient permissions).

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.

---

Deletes the form data instance with the specified ID.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Delete** (`Forms_DeleteForms`) permission for the project.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-form-data

The ID of the form data instance to delete.

Indicates that the form data instance was successfully deleted. There is no response body in this case.

This response indicates that the form data instance with the specified ID does not exist or is inaccessible to the user.

---

Retrieves all properties of the specified form data instance.

Known, common properties will be returned directly on the 'formData' object, whereas custom properties unique to the form's type will be returned on the 'properties' sub-object.

Note that many properties in the schema are described as 'Origin info.' This means that they are metadata about where the form data came from and what business domain object(s) it is related to, such as a PDF file or a 3D model. Their meanings can differ from application to application. Many applications will use only a subset of these properties, and in general applications SHOULD NOT use or set these values unless they have a good reason to do so. Other properties, not marked 'Origin info', are defined for all form types, but clients SHOULD NOT assume that all of them are set.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the form's definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-data-details

The ID of the form data instance to retrieve.

This response indicates that the specified instance does not exist, or the user doesn't have permission to view it.

---

Retrieves a list of form data instances for the project with the given ID. If the Prefer header is omitted, or set to "return=minimal", this only returns basic info about each form--its ID, display name, type, and whether it is in an Open, Closed, or Draft state. Setting the Prefer header to "return=representation" will return more data. Use the "Get Form Data Details" endpoint to see full information about a particular form.

Note that the 'projectId' query string parameter is required. It must be a valid project GUID to get forms from.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** permission (`Forms_ViewAccess`) for the project, or for some forms' definitions if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well. If a user does not have permission to view a particular form, it will be silently excluded from the list.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-project-form-data

The GUID of the project to get forms for.

projectId

The number of form data instances to get in each page. Max 50, which is also the default if this parameter is not included.

$top

Parameter that enables continuing to the next page of the previous paged query. This must be passed exactly as it is in the response body's _links.next property. If this is specified and $top is omitted, the next page will be the same size as the previous page.

continuationToken

The type of form data to get. Omit to get all types.

type

Set this to only get form data for a particular workflow state (Open, Draft, or Closed).

state

Gets whether to return only a summary of each item (return=minimal) or full properties of each item (return=representation).  Default is return=minimal

This response indicates that the form data instance with the specified ID does not exist or is inaccessible to the user due to insufficient permissions. (For security reasons, the response will not differ between inaccessible and missing forms.)

This response indicates that there is a problem with the format of the URL. Most likely problem: The 'projectId' parameter is missing or not a valid GUID.

---

Modifies the provided properties of the specified form to match the values provided in the request.

Setting a property value to null in the request will set the corresponding property value to null on the form. However, omitting a property from the request body entirely will leave that property's current value on the form unchanged.  Also, setting an object (other than "properties") to null will have the same effect as setting each individual property in that object to null.

### Permissions

To use this endpoint, the user is required to have different ProjectWise Forms permissions (for the project, or for the form's definition if form definition security is specified) based on the changes being made:

- Change to the `status` property: **Approve** (`Forms_ApproveAccess`) permission
- Change to the `assignee` or `assignees` property: **Assign** (`Forms_AssignAccess`) or **Approve** permission
- Changes to other properties: **Create/Modify** (`Forms_CreateAccess`) permission

**Full Access** (`Forms_FullAccess`) will satisfy all of these requirements.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

update-form-data

The ID of the form data instance to update.

Meeting minutes, now includes questions asked after the presentations

Design Meeting 2021-02-07 - Amended

Indicates that the changes were successfully made. The response body contains the form's data after modification, including both changed and unchanged properties. Note: If a workflow transition occurred, some properties may have been automatically changed in addition to the properties the client specified to change in the request.

This response indicates that the form the user attempted to update does not exist (or is inaccessible due to insufficient permissions).

This response indicates that there is a problem with the format of the request body. Most likely causes: 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.

---

Gets the full form definition with the specified ID.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-definition-by-id

This response indicates that the form definition with the specified ID does not exist or is inaccessible to the user.

---

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 &lt;select&gt; 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-list-group

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

listGroupId

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

---

Retrieves a list of Approved form definitions for the project with the given ID.  This only returns the definition's name, type, and ID. The full definitions will be returned in the 'Get form definition by ID' endpoint.

Note that in order to create a form data instance, it must be associated with the ID of one of these form definitions (through the 'formId' property in the 'Create form data' request body). This API cannot be used to create or edit form definitions. They can only be created/edited/imported by project administrators through the Bentley Form Manager webapp, which is accessible at https://connect-formmanager.bentley.com/manageforms.aspx?projectId=yourprojectid (replace `yourprojectid` with your actual project ID).

Note that the 'projectId' query string parameter is required. It must be a valid project GUID to get form definitions from.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-project-form-definitions

The GUID of the project to get form definitions for.

The form type to get form definitions for.  Omit to get all form definitions in the project.

This response indicates that the project with the specified ID does not exist or is inaccessible to the user due to insufficient permissions. (For security reasons, the response will not differ between inaccessible and missing projects.)

---

Gets a link to a static image to be displayed in a form. The 'fileId' parameter should match the 'fileId' property of a static image control in the form's definition.  It will be a positive integer.  This endpoint returns only a _links object containing the URL of the actual file, which is publicly available and can be set as the 'src' attribute of an HTML <img> tag to display the image.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-static-image

The ID of the form definition for which to get a static image.

fileId

This response indicates that the static image or its associated form definition was not found.

---

Retrieves the workflow for the given form type in the given project. The project must be specified using the 'projectId' query string parameter.

It is possible for users of a project to choose not to set a workflow for a given type. In that case, requests to get the workflow of that type will return a 404 Not Found response where the 'code' property of the body's 'error' object is set to "WorkflowNotFound". This does not indicate client error. Other HTTP status codes, or other values of the 'code' property, do indicate an unexpected error of some sort.

Note that workflows cannot be customized through this API; they can only be added, deleted, or changed manually by project administrators through the Bentley Form Manager webapp, found at https://connect-formmanager.bentley.com/manageforms.aspx?projectId=yourprojectid (replace `yourprojectid` with your actual project ID).

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-workflow

The form type for which to get a workflow.

The GUID of the project for which to get a workflow.

This response indicates that the project does not exist (code = 'RepositoryNotFound') or that there is no workflow set for this form type (code = 'WorkflowNotFound'). This latter case does not indicate client error, as it is valid for a user to choose not to set a workflow for a given form type.

A URL parameter was malformed. Most likely the required 'projectId' query parameter is missing or not a valid GUID.