Custom Fields methods

The UI Apps SDK enables you to retrieve the custom fields metadata from the Gtmhub account your UI app is added to.

NOTE: Before you start using the SDK methods, ensure you have imported and configured the SDK first.

getCustomFields

To get a list of the custom fields defined in the Gtmhub account use the getCustomFields SDK method. The response contains useful information like the custom field UI label, developer name, the targetTypes the field applies to. NOTE The result is limited to 500 items.

sdk.getCustomFields().then((response) => {
  console.log(response);
});

Tutorial - Working with custom fields in a UI App

A common use case for getting the custom fields metadata is to obtain the developer name of a custom field. The name is automatically generated when you create a custom field. It is not visible in the UI and is different from the label which you assign in the UI.

Consider the following example:

  • You have created a couple of custom fields in Gtmhub, and specified they apply to Tasks.
  • You want your UI app to enable users to browse items from an external system.
    • For each selected item from the external system you want to create a Task in Gtmhub.
    • You want users to populate the custom fields for each Task.

For the purpose of this tutorial let's focus on the second part of the requirement, namely how to find which custom fields apply to Tasks, and enable users to set their value.To implement the above requirement you must:

  • Use the getCustomFields SDK method to get the metadata for all custom fields in the Gtmhub account.
    • filter the response and get the ones that apply to Tasks. This information is available in the targetTypes property.
    • list them in your UI app using the label property value of the custom field.
    • use the custom field name to set the custom field value when creating the Task.
  • Use the createTask SDK method for creating the Tasks.
    • set the desired custom fields by listing them with their developer name in the payload. For example:
const createTaskPayload = {
  name: "my-first-task",
  parentId:"", // goal.id or metric.id
  status:"todo",
  customFields: {
    customField1Name : "customField1Value",
    customField2Name : "customField2Value",
  }
};

sdk
  .createTask(createTaskPayload)
  .then((task) => console.log(task));