Custom fields REST API Helper

Custom fields are a broadly used, beneficial functionality of Quantive Results, that allows you to customize the input fields when creating new OKRs, KRs, Teams, Tasks, or Users. The following article can help you understand the possibilities that the custom fields functionality gives you.

Let's start with updating the value of a custom field.

1. What is actually a value of a custom field?

When we create a custom field, it logically does not possess any value, until it is attached to its target object. For example, if a “Prioritization” custom field with 3 options (Low, Medium, and High is applicable to Objectives, and our 3 newly created Objectives (O1, O2, and O3) are assigned each of these options in their “Prioritization” field, those exact options will be their custom field values.

2. How to update a Custom Field value, using the REST API?

2.1. First, we need to find out the name of the custom field, that you are trying to edit.

Every newly created custom field has a name key in its object that could not be edited and is holding the value of the custom field.

This is the GET Custom Field response.
In this example, the value of the name key, that we are looking for is “fp_text_fiel”.

{
    "_id": "62a840a48881a8fdc05f433d",
    "accountId": "6282355447f21e02ef0a3231",
    "dateCreated": "2022-06-14T08:02:44.083Z",
    "description": "",
    "filterable": false,
    "label": "Text field",
    "lastModified": "2022-06-14T08:02:44.083Z",
    "name": "fp_text_fiel",
    "operationalType": "global",
    "settings": {
        "predefinedValues": [],
        "validations": {
            "required": false
        }
    },
        "targetTypes": [
        "goal"
    ],
    "type": "string",
    "visualizationKind": "gtmhub.text"
}

2.2. Go ahead and make a PATCH request of the Object, whose custom field value you are trying to edit.

Every object that could be assigned with a custom field (Objective, Key Result, Key Result Update,Team, Task, User) has a key called “customFields”. This key is an object itself that has a key with the same name, as the name that we just looked up for (“fp_text_fiel”).The value of this key, is exactly the value, that we are trying to edit. So the only thing left to do Is make a PATCH Request on the Object, that we would like to edit, and change the value of this key, to the desired one.

3. Let us browse some examples of the possible combinations of target object/custom field type PATCH requests

Target: Objective / Custom Field Type: Text field

{
    id: "62ab1077394521912e94bc0f",
    customFields: {
        jw_objective: "Example text after edit"
                  }
 }

Target: Task / Custom Field Type: Date Picker

{
    id: "62ab124f394521912e94bdc0",
     customFields: {
         jd_task_date: "2022-06-30T00:00:00.000Z"
                   }
}

Target: Team / Custom Field Type: Multi-Select

{
    id: "62ab1308e15f3dd6198bb541", 
    customFields: {
        nj_team_mult: ["Option 01", "Option 02"]
                  }
}

Target: Key Result / Custom Field Type: Text area

{
    id: "62ab15615e44a6bf72755575", 
    customFields: {
        pi_kr_text_a: "Text area CF edited"
                  }
}

Target : User / Custom Field Type: User/Team Selector

{
    id: "6295dfeebfa7edb6e79f7da3",
     customFields: {
         zo_user_user: ["62a97cc01ba5e813df1537ba"]
         }
}

<hr></hr> The custom fields topic is a complicated one since custom fields are like no other component of the Quantive Results UX. They give the user countless possibilities for building their own responsive ecosystem and mastering them gives you the capabilities of a true Quantive Results champion.

Quantive Results team! :)