In this article, you will get acquainted with Onfleet’s Custom Fields. Custom Fields allow you to attach additional information to Onfleet tasks and tailor Onfleet to your organization's process.
This article covers:
- Configuring Custom Fields
- Editing and Deleting Custom Fields
- Interacting with Custom Fields via the Dashboard
- Interacting with Custom Fields via the API
- CSV Import for Custom Fields
- CSV Export for Custom Fields
Configuring Custom Fields
To configure the "Custom Fields" feature, select the "Settings" tab located in the upper-right corner of the dashboard. Once in the "Settings" window, select the “Custom Fields” tab:
Select “Add custom field” to begin the setup:
- Enter a unique name for your custom field
- The custom field key will be generated automatically once you type in a name.
- The key can be edited only while creating the custom field.
- The value of the key must be unique (excluding deleted custom fields)
- You can choose to enter a description of this field. The description will be shown on the create and edit task modal.
Then, you can select a "Field Type" from the drop-down menu and the task type:
- The valid values for custom fields will be enforced to match the chosen data type. For Example, if the field type selected is “Integer” the value must be numbers and not letters.
- Custom fields can be configured for pickup, dropoff, or both task types.
Then you will have to choose if the field is required:
- If a field is required, a value must be entered for it during task creation.
- If the field type is True/False and the field type is set to "Required" then the value must always be set to "True" during task creation.
If the field is not required, you can configure additional settings:
- Custom fields can be hidden or displayed on the task screen.
- Custom field values can be editable or read-only on the task screen.
Lastly, you can select if drivers can see the value of the Custom Field:
- The Custom Field value will be shown in the driver app on the "Task Details" screen for Active and Completed tasks.
Editing and Deleting Custom Fields
To edit a Custom Field, navigate to the "Custom Field" section in the "Settings" window. From here, you can select the field you would like to edit, then click the pencil icon to open the editor for this field.
Once you select "Edit", you can then edit the details you would like for the custom field. Please note, that the key cannot be updated after a field is created.
Once you are satisfied with your updates, select "Save".
To delete a custom field, navigate to the "Custom Fields" section on the "Settings" window. From the "Custom Fields" section, hover over the field you would like to delete then click the trash can icon located to the right of the field.
Alternatively, you can select to edit a custom field, and then scroll down and select "Delete Custom Field"
Please Note: Any edits or deletions of a Custom Field configuration will only apply to newly created tasks and will not affect the existing custom field data for previously created tasks.
Interacting with Custom Fields via the Dashboard
Once your organization has enabled the "Custom Fields" option, you can enable the fields you have created to be viewed on the dashboard by dispatchers and administrators. The custom field values can be viewed in the task details window and the Table view.
When you create a custom task field, this will create a new column under the "Table View" with the name of the custom task you have created, after you have selected the Custom Field from the column selector located in the upper right corner.
If a true/false custom field has a value of true, you will see it on the "View Task" modal with a check mark.
Note:
- If a field is required, it will always be shown on the task creation screen with a red asterisk and a value must be set before a task is created.
- The value for a custom field can be updated until the task is started.
- Custom Fields can be found at the bottom of the Create/Edit task modal.
Interacting with Custom Fields via the API
A Custom Field can be added to a task via the API as well. You can update or create a custom field via the API by attaching the additional object to your request:
Visibility (Determines who can view the custom field):
- If the field is required, visibility must always be set to "admin" and "api". This ensures that both dashboard users and API clients have access to the field.
- If the field is not required, visibility can be set to "api" if the field is configured to be hidden and read-only on the dashboard. This configuration allows API clients to access the field even if it's not visible on the dashboard.
Editability (Controls who can edit the custom field):
- If the field is required, editability must always be set to "admin" and "api". This ensures that administrators and API clients have the necessary permissions to modify the field's data.
- If the field is not required, editability can be set to only "api". In this case, the field can be configured as read-only on the dashboard, but it remains editable through the API.
Key (Serves as a unique identifier for the custom field):
- The key must match the key shown on the Custom Fields settings page.
Name:
- The name must match the name shown on the Custom Fields settings page.
Type (Specifies the data type of the custom field):
- "single_line_text_field",
- "multi_line_text_field"
- "boolean"
- "integer"
- "decimal"
- "Url"
Contexts:
- The requirement must match what is defined on the Custom Field.
- If the custom field is for dropoff tasks only, set the targetvalue to “false”
- If the custom field is for both task types, leave the condition array empty.
- Conditions must be added for each task type.
Creating/Updating a task with custom fields:
- Attach your custom field object to the payload during task creation/editing
"customFields":[
{"key": "orderNumber",
"value": 1236
}
]
Returning custom fields:
- The following object will be returned for custom fields
"customFields": [
{
"description": "Order Number",
"asArray": false,
"visibility": [
"admin",
"api"
],
"editability": [
"api"
],
"key": "pickupOptional",
"name": "Pickup Optional",
"type": "single_line_text_field",
"contexts": [
{
"isRequired": false,
"conditions": [
{
"fieldName": "pickupTask",
"comparison": "equal_to",
"targetValue": true
}
],
"name": "save"
}
],
"value": true
}
CSV Import for Custom Fields
Custom Field values can be set with the Task Import feature. The Custom Field must be configured to be "Required" or "Optional", with dashboard visibility and editing enabled, to be imported.
For any required custom fields, you must select a corresponding column from your file on the import page:
CSV Export for Custom Fields
Custom Fields will be included in the Task Export CSV sheets. If you have deleted a Custom Field, it will still be included in the export with a (deleted) note beside it.