Custom Fields

What Are Orbital Custom Fields?

Orbital custom fields are structured data attributes that extend basic task information beyond title and content. These fields transform simple tasks into comprehensive project management tools with priority tracking, deadline management, user assignments, and approval workflows. Each field serves a specific purpose in organizing and managing task workflows.

One cool detail about option custom fields is that they directly integrate with the KanBan board. So any field with a set of options (think priority low/medium/high) can be visualized AND edited from the KanBan board. That means if you want to create a new select field called Status with options open, closed, and pending, the KanBan board will generate lanes for each options so you can drag and drop your tasks. The drag/drop operation also updates the task’s field data!

Why Use Orbital Custom Fields?

Enhanced Task Organization: Filter and sort tasks by priority, due dates, assignee, and approval status
Streamlined Workflows: Track task progression from creation through approval and completion
Team Collaboration: Assign tasks to working groups and monitor responsibility distribution
Real-world Example: A content team can assign blog post tasks with high priority, set due dates for publication deadlines, track approval status through editorial review, and mark completed tasks as approved

Who Can Edit Custom Fields?

Custom field editing permissions in Orbital follow a granular security model – not everyone can edit custom fields.

There are two types of custom fields each with there own permission logic:

Standard Custom fields (Priority, Start Date, Due Date, Assignee)
Approval Custom field (Approval)

Access depends on specific user permissions and the type of field being modified. Custom field edit permissions are granted for the the user role OR by granting the permission for a specific task.

The first image shows the admin permission screen settings that allow a user role permission to edit our 5 standard custom fields. The second image shows a single user being granted permission to edit that task’s 5 standard custom fields.

Regular Custom Fields Permissions

Users can edit standard custom fields (Priority, Start Date, Due Date, Assignee) only if they have one of these specific custom field permissions:

edit_all_custom_fields – Can edit custom fields on any task in the system
edit_own_custom_fields – Can edit custom fields only on tasks they created
manage_custom_fields – Task-specific override permission for that specific task

Important: General task editing permissions (edit_own_tasks, edit_all_tasks) do NOT grant access to custom fields. These permissions only allow editing task title and content. You would need to add on the custom field permissions too. This gives you the most granular control over who can edit what inside OrbitalWP.

Approval Status Field Permissions

The Approval Status field has stricter access controls. The idea for the approval field is to give you the ability to assign “approvers” that are like gatekeepers to a task’s completion status.

Users can edit approval status only if they have:

Approval permission (approve_tasks) – Can approve any task
All tasks permission (edit_all_tasks) – Full task management access

Important: Users with approve_own_tasks permission cannot approve their own tasks – this prevents self-approval conflicts.

Permission Hierarchy

Orbital uses a two-layer permission system:

Role-based defaults – Base permissions assigned to user roles
Per-user overrides – Specific permissions granted or denied for individual users

What Users See Without Permission

Users without proper permissions will see:

“You do not have permission to edit custom fields” message in the task editor
Error messages when attempting AJAX field updates
Read-only field displays where applicable

The permission system ensures data integrity while maintaining flexible access control for different team structures and workflows.

How to Use Orbital Custom Fields

Custom fields appear automatically in the task editor sidebar when creating or editing tasks. Administrators can customize field labels and options through WordPress Admin > Orbital > Custom Fields while maintaining data integrity across all existing tasks.

Built-in Custom Fields

Orbital provides six essential custom fields out of the box. But you can create even more right form the Custom Fields interface.

The out-of-the-box fields are:

Priority Field

Purpose: Sets task urgency level for prioritization
Meta Key: _orb_cf_priority
Type: Dropdown (select)
Default Options: High, Normal, Low
Permissions: Standard task edit permissions

Start Date Field

Purpose: Defines when work on the task should begin
Meta Key: _orb_cf_start_date
Type: Date picker
Format: YYYY-MM-DD (ISO 8601)
Permissions: Standard task edit permissions

Due Date Field

Purpose: Sets completion deadline with automatic overdue detection
Meta Key: _orb_cf_due_date
Type: Date picker
Format: YYYY-MM-DD (ISO 8601)
Permissions: Standard task edit permissions

Approval Status Field

Purpose: Tracks task through approval workflow stages
Meta Key: _orb_cf_approval_status
Type: Dropdown (select)
Default Options: Pending Review, Approved, Rejected, Needs Revision
Permissions: Requires approve_tasks capability or approve_own_tasks for task authors

Assignee Field

Purpose: Assigns tasks to specific WordPress users
Meta Key: _orb_cf_assignee
Type: User search (AJAX)
Storage: WordPress User ID (integer)
Permissions: Standard task edit permissions

Administrator Field Management

Safe Modifications

Administrators can safely modify certain field metadata without breaking existing task custom field data:

Field display labels and descriptions
Dropdown option labels (display text)
Default values for new tasks
Field locations (sidebar vs main area)
Required field settings

Protected Elements

These elements must never be changed as they will break existing task data:

Field keys (internal identifiers)
Field types (dropdown, date, checkbox)
Dropdown option values (stored data keys)
Meta key patterns (orb_cf prefix)

Management Workflow

Navigate to Orbital > Custom Fields in WordPress admin
Select a field to edit its properties
Modify labels, descriptions, or display settings
Test changes on a sample task before rolling out
Save changes and verify field functionality

Developer Integration

Basic Field Operations

// Get field values
$priority = get_post_meta($task_id, '_orb_cf_priority', true);
$assignee_id = get_post_meta($task_id, '_orb_cf_assignee', true);
$due_date = get_post_meta($task_id, '_orb_cf_due_date', true);

// Update field values
update_post_meta($task_id, '_orb_cf_priority', 'high');
update_post_meta($task_id, '_orb_cf_due_date', '2024-12-31');

Permission-Restricted Fields

// Check permissions before updating approval status
if (current_user_can('approve_tasks', $task_id)) {
    update_post_meta($task_id, '_orb_cf_approval_status', 'approved');
}

// Check permissions before closing tasks
if (current_user_can('approve_tasks', $task_id)) {
    update_post_meta($task_id, '_orb_cf_closed', '1');
}

Advanced Query Examples

// Query high priority tasks due this week
$urgent_tasks = new WP_Query([
    'post_type' => 'orb_task',
    'meta_query' => [
        'relation' => 'AND',
        [
            'key' => '_orb_cf_priority',
            'value' => 'high'
        ],
        [
            'key' => '_orb_cf_due_date',
            'value' => [date('Y-m-d'), date('Y-m-d', strtotime('+7 days'))],
            'compare' => 'BETWEEN',
            'type' => 'DATE'
        ]
    ]
]);

// Get user's assigned tasks that are not closed
$active_user_tasks = new WP_Query([
    'post_type' => 'orb_task',
    'meta_query' => [
        'relation' => 'AND',
        [
            'key' => '_orb_cf_assignee',
            'value' => get_current_user_id()
        ],
        [
            'relation' => 'OR',
            [
                'key' => '_orb_cf_closed',
                'compare' => 'NOT EXISTS'
            ],
            [
                'key' => '_orb_cf_closed',
                'value' => '1',
                'compare' => '!='
            ]
        ]
    ]
]);

Bricks Builder Dynamic Tags

Orbital integrates with Bricks Builder to provide dynamic data tags for displaying custom field values. Please read the Bricks Builder Integration document to see how it works in more detail.

– Priority level (displays label: High, Normal, Low)
– Start date (formatted according to WordPress date settings)
– Due date (formatted according to WordPress date settings or “Not Set”)
– Approval status (displays label: Pending Review, Approved, etc.)
– Assignee user ID (use with user display name formatting)
– Closed status (displays “Yes” or “No”)

Note: The assignee field stores the user ID but displays the user’s display name when rendered through the dynamic tags system.

Permission System

Orbital uses a hierarchical permission system for custom fields:

Standard Fields

Priority, Start Date, Due Date, and Assignee fields follow standard task editing permissions. Users who can edit a task can modify these fields.

Restricted Fields

Approval Status and Closed fields require special approval permissions:

Users with approve_tasks capability can modify these fields on any task
Users with approve_own_tasks capability can only modify these fields on tasks they authored
These permissions are enforced at the field level, not the task level

Permission Checking

// Check if user can modify approval-restricted fields
$can_approve = current_user_can('approve_tasks', $task_id);

// Check if user can approve own tasks
$task = get_post($task_id);
$is_author = ($task->post_author == get_current_user_id());
$can_approve_own = current_user_can('approve_own_tasks') && $is_author;

$can_modify_approval = $can_approve || $can_approve_own;

This documentation covers Orbital Task Manager custom fields. Always use meta keys with _orb_cf_ prefix for database operations. Field keys are permanent identifiers and should not be modified after creation to maintain data integrity.