Working with Configurable Fieldsets
Overview
Some tools don’t support configurable fieldsets. Most Procore API endpoints respect configurable fieldsets, but a handful of tools do not yet support them.
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.
The following tools do not yet support configurable fieldsets: Coordination Issues, Meetings, Schedule, Action Plans, Forms, Budget, Change Orders, and Direct Costs.
Understanding Configurable Validations
Include null-valued required fields on update, or validation fails. When updating a resource, a required field that already has a value only needs to be sent if you intend to change it — but if its existing value is null, you must include it in the request.
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.
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.
The absence of required fields in the request body returns an error indicating which fields are needed for a successful create action.
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.
- What are custom fields and which Procore tools support them?
- Create Custom Fields Within a Fieldset
- Create Custom Fields from the Custom Fields Tab
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”.
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.
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.
Multi Select LOV Update Example
When updating a multi select custom field for a record, make sure that the value is an array. Even if the value is a single item, it should still be an array.
{
"company_id": 123,
"project": {
"custom_field_456": [789]
}
}