Custom Fields in the API

Custom fields are used by Field Squared objects to customize the screens inside your app. Custom fields are used to extend Tasks, Assets, Contacts, Users, Teams and Catalogs.

You can use custom fields to capture data, or just to display data that's coming from your existing database.

Custom fields provide a way to extend any screen in field squared with customizable data and user interfaces.

You can read up on how to configure and extend your screen in Field Squared by reading our Article on Creating and Configuring Custom Fields.

Each custom field added to a screen has:

• A customizable user interface
• Default values
• A unique key to identify the control
• A label to display on the screen for the control
• Rules to auto-populate the control dynamically (using Text Expressions)
• Rules to control data visibility, access and security

The data for each custom field will be stored with that object.

No two objects needs to have exactly the same custom fields.  You configure custom field templates in Field Squared for:

• Tasks by Task Type – each task type has it's own template for what fields are on the screen and stored with the job
• Assets by Asset Type – each asset type defines its own custom properties and user interface
• Users – all user records can be extended with the same set of custom fields
• Contacts – all contact/customer records are extended using the same custom fields
• Teams – teams can also be extended with custom fields.

So for example, two task types called INSPECT and INSTALL may or may not have the same custom fields binding keys available to use.

For example, you can extend the Task screen to include a Combo Box control that has default list items with values "Value A", "Value B" and "Value C". The user can select one of those options at runtime, or type their own value into the field. See our documentation on Custom Fields for more details on the possibilities.

The Data property on the API is used to set custom field values in API integrations.

• Each message body for core objects (Task, Asset, User, Team, Contact) can send any values you like to the Field Squared API as custom fields using the Data property.
• All values are key-value pairs where the keys are strings and the values are strings.
• All binding keys must be uppercase.
• If the keys sent to our API are not configured on that Task Type, then they will be ignored by our API. We only update keys that exist for that task type.

Custom Fields are stored as a set of key-value pairs as strings inside each object.

For example, say we want to update a Car Wash task type, which has the custom fields vehicle type and number of wheels added to it to extend the core Task object. You would update this record using the following sample API calls:

JSON: Data is a dictionary of key-value pairs

[
 {
   "Name": "My Task",
   "Status": "Not Started",
   "ExternalId": "1234",
   "TaskType": "Car Wash",
   "Data": {
      "VEHICLE_TYPE": "Truck",
      "NUMBER_OF_WHEELS": 18
   }
  }
]

XML: Data is an XML <Data> element with multiple child elements

<ArrayOfTask>
  <Task>
    <Name>Test Delivery Task for API</Name>
    <Description>My comments about this task go here</Description>
    <ExternalId>1234</ExternalId>
    <TaskType>Delivery</TaskType>
    <Status>Not Started</Status>
    <Data>
       <VEHICLE_TYPE></VEHICLE_TYPE>
       <NUMBER_OF_WHEELS>18</NUMBER_OF_WHEELS>
    </Data>
  </Task>
</ArrayOfTask>

Upgrades and Template Changes

If you remove a field from a custom field template, any objects that have previously been saved using that custom field template will still have that property available to them in the future. Old objects will never lose data for custom fields that are no longer on the display.

If you add a new custom field to a template for an object, then the new objects created going forwards will get that custom field added to the object the next time they're edited.

Empty or Null Values

Note that when you are editing a custom field, if the value in the field is removed or blanked out at runtime by a user, then the key for that custom field will still be returned in the Data dictionary of key-value pairs but will have a null value.

For example, say we have this User object:

[
  {
    "Name": "John Apple",
    "ExternalId": "uid123",
    "Data":{
        "EMPLOYEE_ID": "000123",
        "BADGE_NUMBER": "77634"
    }
  }
]

And then in the user interface the badge number property is cleared by a user, then the object will be stored like this with the BADGE_NUMBER key set to an empty string value. Note that custom fields are always strings, so numbers stored in custom fields that are cleared will default to "" and not the number 0.

[
  {
    "Name": "John Apple",
    "ExternalId": "uid123",
    "Data":{
        "EMPLOYEE_ID": "000123",
        "BADGE_NUMBER": ""
    }
  }
]