App-Configured Custom Fields

Introduction

Custom fields in Jobber are a popular feature available to Jobber customers on the Connect plan or higher. Custom fields allow data of various formats to be associated with the following six Jobber objects:

Clients
Properties
Quotes
Jobs
Invoices
Team members (coming soon)

Custom fields are configured at the account level, and then they contain values at the object level. Typically an admin user must configure the custom fields they want on the account in Jobber, but our API also allows apps to configure new custom fields (as long as the Custom Field Configurations scope is approved for read and write access).

Custom field configurations on the account can also be queried for with the customFieldConfigurations query. The configurations contain customizable settings such as:

The name of the custom field
The option to automatically transfer the custom field value to other related objects
The default value (if any)
The value type:
- True/False
- Numeric
- Area (length x width)
- Dropdown
- Text
- Link
The unit of measure (for numeric and area custom fields only)

Whenever an app configures a custom field on a Jobber account, the app’s name and logo will be shown to the Jobber user in every case where they see the custom field value in Jobber’s UI. For example, if an app called “XYZ App” configured two custom fields on all job objects, the resulting user experience would look like the screenshot below.

Currently, once the custom fields have been configured on the Jobber account, there is no way for the user to delete them from the account or reorder them, but these features will be added as an admin functionality in the future. For now, the app-configured custom fields are hidden from the user on the custom fields settings page in Jobber. An app also cannot delete a custom field configuration that it has created, but editing the name of previously created custom fields will be possible in the near future.

Additional Capabilities Available

App-configured custom fields have certain additional capabilities that are not available to typical custom fields that have been manually configured by a user.

Link Type Custom Fields

A new type of custom field called link is available to apps. It is configurable via the customFieldConfigurationCreateLink mutation. These custom fields always have two values: one for the text label of the link and another for the URL that the link should take the user to. For example, if a new link type custom field called “Link Example” were created, it would appear to the Jobber user as shown in the screenshot below.

Here is the example code used for configuring this new custom field on the account:

mutation CreateLinkConfigurationExample {
  customFieldConfigurationCreateLink(
    input: {
      appliesTo: ALL_JOBS
      name: "Link Example"
      transferable: false
      readOnly: false
      defaultValue: { text: "View link here", url: "https://www.example.com" }
    }
  ) {
    customFieldConfiguration {
      createdAt
      id
      name
    }
    userErrors {
      message
    }
  }
}

Any Jobber reports that include custom fields will only provide the URL for link type custom fields and not the text label.

Read-Only vs. Editable Custom Fields

Although traditional custom fields are always editable by users in Jobber, app-configured custom fields can be configured to be read-only, so that users can only see their values but not modify them. All of the mutations for configuring new custom fields on an account have a Boolean input argument called readOnly that is used to set this option. It should be noted that the editable custom fields can be used to collect user input on various Jobber objects. For example, a “True/False” type custom field could be used to collect a user input on how an app/integration should behave with respect to a specific object. A “Dropdown” type custom field can also be used to collect a decision from a user in cases where there are multiple options.

On edit screens for Jobber objects, the user may see messages like the one shown in the screenshot below for certain custom fields that are configured to be read-only:

Guidelines for Usage

All read-only or editable custom fields that have been configured by apps will always be visible to Jobber users, so they should only ever be used for data that is meant to be visible to Jobber users. Other mechanisms should be used for any data that is intended to be hidden from Jobber users.

A few other restrictions to be aware of are:

Custom fields should be used for important data only
- For this reason a particular app can only create 5 custom field configurations on any particular Jobber object
  - For any uses cases that would require more data, we recommend using notes instead
An app cannot delete or archive any custom fields that it configured, but in the future it will be possible to rename them
An app cannot input or overwrite the values of any custom fields that were configured by another app

Handling App Disconnects and Reconnects

When a jobber user disconnects your app, any custom fields that your app had configured will automatically be moved into an archived state. The Jobber user will also have the option to permanently delete some or all of those custom fields from their account. With this in mind, any apps utilizing custom fields should be able to properly handle app reconnects.

When a reconnect happens for an app that previously configured custom fields, those custom fields will immediately be unarchived so they are ready to use again. Before configuring any new custom fields on an account, it's recommended to always use the customFieldConfigurations query first to determine if any of the custom fields you would like to configure already exist on the account. Otherwise you will encounter errors when trying to configure them.

GraphQL Examples

Reading Custom Field Configurations

Example query for reading all of the custom field configurations on a particular Jobber account:

query GetAllConfigurationsExample {
  customFieldConfigurations(first: 50) {
    nodes {
      ... on CustomFieldConfigurationArea {
        id
        name
        valueType
        appliesTo
        readOnly
      }
      ... on CustomFieldConfigurationDropdown {
        id
        name
        valueType
        appliesTo
        readOnly
      }
      ... on CustomFieldConfigurationLink {
        id
        name
        valueType
        appliesTo
        readOnly
      }
      ... on CustomFieldConfigurationNumeric {
        id
        name
        valueType
        appliesTo
        readOnly
      }
      ... on CustomFieldConfigurationText {
        id
        name
        valueType
        appliesTo
        readOnly
      }
      ... on CustomFieldConfigurationTrueFalse {
        id
        name
        valueType
        appliesTo
        readOnly
      }
    }
  }
}

It should be noted that the id from this query can be used in the customFieldConfigurationId input argument field of other mutations.

Creating a Client with Custom Field Values

mutation CreateClientExample {
  clientCreate(
    input: {
      firstName: "Jane"
      lastName: "Doe"
      emails: [
        { description: MAIN, primary: true, address: "[email protected]" }
      ]
      customFields: [
        {
          customFieldConfigurationId: "Z2lkOi8vSm9iYmVyL0N1c3RvbUZpZWxkQ29uZmlndXJhdGlvbk51bWVyaWMvMTY4MDg5Mw=="
          valueArea: { length: 10, width: 20 }
        }
      ]
    }
  ) {
    client {
      id
      firstName
      lastName
    }
    userErrors {
      message
      path
    }
  }
}

Editing a Client with Custom Field Values

mutation EditClientExample {
  clientEdit(
    clientId: "Z2lkOi8vSm9iYmVyL1Byb3BlcnR5LzczODc0Nzc3"
    input: {
      customFields: [
        {
          customFieldConfigurationId: "Z2lkOi8vSm9iYmVyL0N1c3RvbUZpZWxkQ29uZmlndXJhdGlvbk51bWVyaWMvMTY4MDg5Mw=="
          valueNumber: 5285
        }
      ]
    }
  ) {
    client {
      id
      firstName
      lastName
    }
    userErrors {
      message
      path
    }
  }
}

It should be noted that the customFieldConfigurationId and id are not both required in the edit mutations.

Either one of them can be used
The id field in this case refers to the ID of a particular custom field value instead of the ID of the custom field configuration