Working with Configurable Fieldsets

Introduction

A configurable fieldset is a group of fields in certain Procore tools that can be set to optional, required, or hidden, depending on the needs of your company. When a project user interacts with a tool that supports configurable fieldsets, the fieldset configuration assigned to a given project determines which fields are visible to the user and whether or not they are required fields. Procore’s API endpoints respect the configurable fieldsets that are created and managed within the Procore web application. Configurable fieldset requirements are respected on the following API endpoints:

Portfolio Project Management Daily Log Company Directory Project Directory

Additional Tool Support for Configurable Fieldsets

Our development teams continue to build out support for configurable fieldsets and custom fields in the various Procore tools. Although the above list was accurate at time of publication, keep in mind that newly supported tools will have their API endpoints updated over time. If you do not see the tool you are working with listed above, check the API Reference pages for the relevant endpoints - support for configurable fieldsets may have been recently added!

Understanding Configurable Validations

When one or more configurable fields on a resource are set to required, the run_configurable_validations attribute must be present in the JSON request body and set to “true” when creating or updating that particular resource via the API. This ensures that the API endpoints respect and validate those configurable fields. In the following example, a fieldset is configured on the Project resource using the Company Admin tool so that when new projects are created or updated, the "city" and “address” attributes are required to contain values.

project fieldset

In this scenario, creating a new project using the Create Project API endpoint requires the run_configurable_validations parameter to be present in the request body and set to "true", along with a value defined for each required field as shown below.

project new

The absence of required fields in the request body returns an error indicating which fields are needed for a successful create action.

project error

Configurable Validations and Update Actions

It is important to note that when updating a resource, if a required field already has an existing value, it only needs to be included in the JSON request body if you intend to update it. However, if the existing value is "null", then the field must be included in the request, otherwise the validation will fail.

Working with Custom Fields

Custom fields can be created for certain tools in Procore to allow for additional information to be filled out when creating or editing items. Custom fields can be created within fieldsets, or created separately and later applied to fieldsets. The following Procore Support Site articles provide general information on custom fields and how they are managed using the Procore web application.

Punch List Example

Let's explore an example using the Punch List tool with some existing Punch List Items. We've created a configurable fieldset for the Punch List tool using the Procore web application, and added a custom field called "Effort Estimate".

effort estimate

A unique identifier is assigned to the custom field when it is created. Next, we use the Show Punch Item endpoint to return information about the custom field associated with an existing Punch List Item. Here is an excerpt from the response body.

"custom_fields": { "custom_field_49417": { "data_type": "decimal", "value": 2.0 } }

In this example, we see the custom field id is '49417', data_type is 'decimal', and the current field value is 2.0. Now, let's update the field value using the Update Punch Item endpoint. We'll change the value for the custom field to 4.0.

update punch item

Note that we use the syntax custom_field_{custom field id} to define the new value in the request body. The response body shows that we have successfully updated the value for our custom field to 4.0.