Custom Task Attributes

Intro

As of April 2022 Custom Task Attributes (CTAs) are a feature to Fieldwire allowing users to create their own custom attributes on their tasks. This guide will aim to outline how these attributes can be read and updated via the API.

Note: This document assumes the user is familiar with both the Fieldwire API and the Custom Task Attribute feature.

CTA Overview

Custom task attributes can be managed on the project level. For each project, project owners can create a set of new attributes for tasks in the project settings and project users can update attribute information via the task interface. Custom Task Attributes can be one of three “types” of attributes which dictate the values that can be used for the attribute:

Short text
Number
List

Workflows

Getting Custom Task Attribute Values

Getting the values for a task attribute is a 2 step process. API users must:

Get the list of attributes configured on the Project
Get the attribute values from a particular task
a. Custom Task Attribute values can also be obtained for the entire project

The following API call will give you an output of the task attributes configured on the project:

GET /api/v3/projects/<project_id>/task_type_attributes

This next API call will give you only the custom task attribute values for a specified task:

GET /api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/

If you want all Custom Task Attributes for the entire project, you can perform the following API call:

GET /api/v3/projects/<project_id>/task_attributes

Notes:

If the CTA has not yet been populated on a particular task, the attribute will not appear in the response payload
List items will be returned in the form of a UUID. To get the string value of that list item make a follow up call to /projects/<project_id>/data_type_values/<UUID>

Setting Custom Task Attribute Values

Once the custom task attribute is created, in order to set a value for it on a task, the following must be called:

POST /api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/

{
  "text_value":"lorem ipsum dolor sit amet",
  "task_type_attribute_id":"<task_type_attribute_id>",
  "task_type":"<task_type>",
  "Creator_user_id":<user id>
}

Notes:

Payloads will differ by CTA type (short text, number, list), see below for more detail
POST calls can be used to set CTA values even if the CTA value has already been set on that task
task_type_attribute_id can be found as the “id” field from the “task_type_attributes” array in

GET /api/v3/projects/<project_id>/task_type_attributes

task_type can be found as the “task_type_id” field from the “task_type_attributes” array in

GET /api/v3/projects/<project_id>/task_type_attributes

Short Text CTA Sample POST Payload:

{
  "text_value":"lorem ipsum dolor sit amet",
  "task_type_attribute_id":"<task_type_attribute_id>",
  "task_type":"<task_type>",
  "creator_user_id":<user_id>
}

Number CTA Sample POST Payload

{
  "number_value": 1234567,
  "task_type_attribute_id":"<task_type_attribute_id>",
  "task_type":"<task_type>",
  "creator_user_id":<user_id>
}

List CTA Sample POST Payload

{
  "uuid_value": <list value uuid>,
  "task_type_attribute_id":"<task_type_attribute_id>",
  "task_type":"<task_type>",
  "creator_user_id":<user_id>
}

Updating Custom Task Attribute Values

Once a CTA Value has been set on a task, it can be updated with a simple PATCH call. If a value for a given CTA has not yet been set however, a POST call must be performed first (see above). All PATCH calls will require the task_attribute ID in the URL rather than the payload. Similar to the POST calls, the payload will differ depending on CTA type:

Short Text CTA

PATCH /api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/<task_attribute_id>

{
  "text_value":"lorem ipsum dolor sit amet"
}

Note:
task_attribute_id can be found as the id field from the array in

GET /api/v3/projects/<project_id>/task_attributes

Number CTA

PATCH /api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/<task_attribute_id>

{
  "number_value":1234567
}

Note: see the “Short Text CTA” section about task_attribute_id

List CTA

The List CTA requires the following payload to be sent in a POST call to

PATCH /api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/<task_attribute_id>

{
  "uuid_value": <list value uuid>
}

Notes:

See the “Short Text CTA” section about task_attribute_id
The UUID value corresponds to a specific list value as configured in the settings. See https://developers.fieldwire.com/reference/get_data_types_in_project for more details