Custom Task Attributes

Reading and updating 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
720720

Workflows

Getting Custom Task Attribute Values

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

  1. Get the list of attributes configured on the Project
  2. 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 https://console.fieldwire.com/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 https://console.fieldwire.com/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 https://console.fieldwire.com/api/v3/projects/<project_id>/task_attributes

Notes:

  1. If the CTA has not yet been populated on a particular task, the attribute will not appear in the response payload
  2. 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/

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 https://app.fieldwire.com/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:

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

GET https://app.fieldwire.com/api/v3/projects/<project_id>/task_type_attributes

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

GET https://app.fieldwire.com/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 https://console.fieldwire.com/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 https://console.fieldwire.com/api/v3/projects/<project_id>/task_attributes

Number CTA

PATCH https://console.fieldwire.com/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 https://console.fieldwire.com/api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/<task_attribute_id>
{"uuid_value": <list value uuid>}

Notes:

  1. See the “Short Text CTA” section about task_attribute_id
  2. 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