Fields

Definition

The field is the object used by Pipefy to collect and store the smallest pieces of information.

Each phase can have many fields and they play a fundamental role when it comes to managing a process.

Let's say we have a purchase process in which each card represent an item to be purchased. The item is likely to go through a few phases to complete the process. In this case, in each phase the item must contain some information in order for it to be useful to the process.

If we're talking about a phase that is intended to analyse if the item is necessary to be bought, we need to know what item is being requested, the following fields can help us:

• Name
• Vendor
• Category
• Purpose
• Price

Next, we might need a phase for a manager to approve or decline this purchase, in this case some possible necessary fields would be:

• Manager responsible
• Approved ?
• Quantity

and so on.

Hierarchy and Relations

Accessible through: Phases, Pipes, Tables, depending on where the field is situated. See links for more information
Objects fields can access directly: Phases, Card Field Values through Cards (see how here)

Fields in our API

Field Queries

Before diving into examples in our API, there are a few things that need to be explained.

Finding the Field ID

The first thing to know is how we define the field ids, used to identify each field. In Pipefy, the field_id is a unique string that represents a field. Pipefy generates a new immutable id (also may be referred to as field_id or slug) using the field name whenever a field is created.
It's generation is expected to be based on the field's lower-cased name, with spaces and special characters being replaced by underscores. Example:
For a field with a field name of "Long Text Fiéld" its field_id will be "long_text_fi_ld"

The field_id is important to know because some queries and mutations require it in order to be able interact with that given field. Below are examples of queries that find the field_id of fields in different locations.

Start form fields

The first tab demonstrates the query used for finding fields in the start form. Because the start form is an entity directly attributed to a pipe, it belongs to the pipe object.

Phase fields

The second and third tabs demonstrate queries for finding fields in all phases of a pipe, and finding fields of a specific phase, respectively.

Table fields

The fourth tab demonstrates a query for finding fields in a given Database Table.

{
  pipe(id: 123) {
    start_form_fields {
      id
      label
    }
  }
}

{
  pipe(id: 123){
    phases{
      name
      fields{
        id
        label
      }
    }
  }
}

{
  phase(id:123456){
    name
    fields{
      id
      label
    }
  }
}

{
  table(id:"WMWIUdCc"){
    table_fields{
      id
      label
    }
  }
}

Observation

It's not possible to query for a singular field using it's ID. As mentioned in the Hierarchy and relations section, fields belong to phases, and you'll need to look for the field's properties via a phase. See Phase fields section.

Another thing about fields is that we can't query for them alone, as they are part of a phase and their values are stored using inside of the card object. It's dependent of these objects to be able to fetch the fields related to them.

Card Field Values

Phases within Pipefy only hold the attributes of the fields within their respective phases (see here, but not the values you see after creating or updating a card.

The actual value that is stored on a given field is held within the card object. The moment a card has a field filled in is when you give it a new value. This sort of action creates a Card Field Value.

Take a look at some queries examples below:

{
  card(id: 12345) {
    fields {
      name
      value
      filled_at
    }
  }
}

Table Record Fields

The record_fields refers to fields inside of Pipefy's Database Tables. We have a whole section explaining what these are. You can read more about tables here.

Here we're going to show how to interact with the record's fields and values through our API.

Below are some queries to retrieve information about the field of these records.

{
  table_record(id: 123) {
    id
    title
    record_fields {
      date_value
      datetime_value
      filled_at
      float_value
      indexName
      name
      native_value
      report_value
      required
      updated_at
      value
    }
  }
}

{
  table_records(table_id: "xxxxxxxx") {
    edges {
      node {
        record_fields {
          date_value
          datetime_value
          filled_at
          float_value
          indexName
          name
          native_value
          report_value
          required
          updated_at
          value
        }
      }
    }
  }
}

{
  findRecords(tableId: "xxxxxxxx", search: {fieldId: "field_id", fieldValue: "Field value"}) {
    edges {
      node {
        id
        title
        fields {
          date_value
          datetime_value
          filled_at
          float_value
          indexName
          name
          native_value
          report_value
          updated_at
          value
        }
      }
    }
  }
}

Observation:

• For the table_record query, you just have to provide the record's ID. We have a whole section explaining about this and how to get this value, you can learn more about table records here.

• For the table_records, you have to provide the table id. The table_id is a bit different from most other IDs, as it is an alphanumeric id. To get this value, check out the Database Tables section.

Field Mutations

Similarly to the queries, the mutations interacting with fields are also going to involve the other objects.
As mentioned previously, phases hold the definition of the fields. Below are a few example of common field mutations:

Create Phase Field

• In the first tab, a field of type Horizontal Radio Select with two options is being created in the phase with ID of 123.

Update Phase Field

• In the second tab, the name of a field is being changed to New Name For Field and it's required property is being set to true.

Delete Phase Field

• In the third tab, a field in the pipe with UUID of 0000000-aaaa-2222-3333-bbbbb and ID of existing_radio_select_field. (You can find the pipe's uuid using a Pipe query).

You can check all possible field types in the Field Types section.

mutation {
  createPhaseField(input: {
    phase_id: 123, 
    label: "New Radio Select Field", 
    type: "radio_horizontal", 
    options: ["option 1", "option 2"]}) {
    phase_field {
      id
      label
    }
  }
}

mutation {
  updatePhaseField(input: {
    id: "existing_radio_select_field", 
    label: "New Name For Field", 
    required: true}) {
    phase_field {
      label
      id
    }
  }
}

mutation {
  deletePhaseField(input: {
    pipeUuid: "0000000-aaaa-2222-3333-bbbbb", 
    id: "existing_radio_select_field"}) {
    success
  }
}

The mutations above are to create/delete/update the definition of a field, so it won't affect actual Card Field Value.

Updating fields values

Now let's take a look at the mutations to change the actual Card Field Value of the fields.

mutation {
  updateCardField(input: {
    	card_id: 123,
    	field_id: "new_radio_select_field",
    	new_value: "option 1"
  	}) {
    card {
      fields {
        value
        field {
          label
          id
        }
      }
    }
    success
  }
}

mutation {
  updateFieldsValues(input: {
    nodeId: 123, 
    values: [
      {fieldId: "new_radio_select_field", value: "option 2"},
      {fieldId: "test_field_2", value: "value 2"}
    ]
  }) {
    success
  }
}

The updateFieldsValues mutation allows you to change multiple field values at once.

Note

• The nodeId used in updateFieldsValues is the card's ID

Let's take a look at some mutations to create/delete/update new fields:

mutation {
  createTableField(input: {
    table_id: "xxxxxxxx",
    label: "Field Name", 
    type: "short_text"}) {
    table_field {
      id
      label
    }
  }
}

mutation {
  deleteTableField(input: {table_id: "xxxxxxxx", id: "field_id"}) {
    success
  }
}

mutation {
  updateTableField(input: {
    table_id: "xxxxxxxx",
    id: "field_id",  
    label: "New label"}) {
    table_field {
      id
      label
    }
  }
}

And now, the mutation to actually change the fields values:

mutation {
  setTableRecordFieldValue(input: {
    table_record_id: 123, 
    field_id: "field_id", 
    value: "new value"}) {
    table_record {
      id
      title
    }
    table_record_field {
      date_value
      datetime_value
      filled_at
      float_value
      indexName
      name
      native_value
      report_value
      required
      updated_at
      value
    }
  }
}

Field Types

Important
We also have an attachment field, but unfortunately it's not possible to attach files in an attachment field via API.

Obs: Most of the fields have the following options:
required - A boolean that indicates if the field is mandatory.
help - A string that, if present, creates a clickable icon containing text that will pop up on the screen.
description - A string that adds additional explanation about the field right below the field name.
editable - A boolean that indicates if this field's value can be edited while a card is in another phases.
minimal_view - A boolean that indicates if this field is minimal, which means that the field is collapsed and must be clicked to expand.

📘

API Authentication

Our API is protected, so you have to provide your access token to be able to complete the requests to our API.
You can read more about our Authentication and how to get your access token in our Authentication section.

Once you have the token in hands, within our playground you'll have to add a key in the headers named "Authorization", and the value must be the name "Bearer" followed by your token, like in the image below.

🚧

Be aware that running a mutation in our playground will change the Data inside Pipefy.