Time Duration Custom Field

Time Duration custom fields automatically calculate and display the duration between two events in your workflow. They’re ideal for tracking processing times, response times, cycle times, or any time-based metrics in your projects.

Basic Example

Create a simple time duration field that tracks how long tasks take to complete:

mutation CreateTimeDurationField {
  createCustomField(input: {
    name: "Processing Time"
    type: TIME_DURATION
    projectId: "proj_123"
    timeDurationDisplay: FULL_DATE_SUBSTRING
    timeDurationStartInput: {
      type: TODO_CREATED_AT
      condition: FIRST
    }
    timeDurationEndInput: {
      type: TODO_MARKED_AS_COMPLETE
      condition: FIRST
    }
  }) {
    id
    name
    type
    timeDurationDisplay
    timeDurationStart {
      type
      condition
    }
    timeDurationEnd {
      type
      condition
    }
  }
}

Advanced Example

Create a complex time duration field that tracks time between custom field changes with an SLA target:

mutation CreateAdvancedTimeDurationField {
  createCustomField(input: {
    name: "Review Cycle Time"
    type: TIME_DURATION
    projectId: "proj_123"
    description: "Time from review request to approval"
    timeDurationDisplay: FULL_DATE_STRING
    timeDurationTargetTime: 86400  # 24 hour SLA target
    timeDurationStartInput: {
      type: TODO_CUSTOM_FIELD
      condition: FIRST
      customFieldId: "status_field_id"
      customFieldOptionIds: ["review_requested_option_id"]
    }
    timeDurationEndInput: {
      type: TODO_CUSTOM_FIELD
      condition: FIRST
      customFieldId: "status_field_id"
      customFieldOptionIds: ["approved_option_id"]
    }
  }) {
    id
    name
    type
    description
    timeDurationDisplay
    timeDurationStart {
      type
      condition
      customField {
        name
      }
    }
    timeDurationEnd {
      type
      condition
      customField {
        name
      }
    }
  }
}

Input Parameters

CreateCustomFieldInput (TIME_DURATION)

CustomFieldTimeDurationInput

CustomFieldTimeDurationType Values

CustomFieldTimeDurationCondition Values

CustomFieldTimeDurationDisplayType Values

Response Fields

TodoCustomField Response

CustomField Response (TIME_DURATION)

Duration Calculation

How It Works

1. Start Event: System monitors for the specified start event
2. End Event: System monitors for the specified end event
3. Calculation: Duration = End Time - Start Time
4. Storage: Duration stored in seconds as a number
5. Display: Formatted according to timeDurationDisplay setting

Update Triggers

Duration values are automatically recalculated when:

• Records are created or updated
• Custom field values change
• Tags are added or removed
• Assignees are added or removed
• Records are moved between lists
• Records are marked complete/incomplete

Reading Duration Values

Query Duration Fields

query GetTaskWithDuration {
  todo(id: "todo_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
        timeDurationDisplay
      }
      number    # Duration in seconds
      value     # Same as number
    }
  }
}

Formatted Display Values

Duration values are automatically formatted based on the timeDurationDisplay setting:

// FULL_DATE format
93784 seconds → "01:02:03:04" (1 day, 2 hours, 3 minutes, 4 seconds)

// FULL_DATE_STRING format
7323 seconds → "Two hours, two minutes, three seconds"

// FULL_DATE_SUBSTRING format
3723 seconds → "1 hour, 2 minutes, 3 seconds"

// DAYS format
216000 seconds → "2.5" (2.5 days)

// HOURS format
7200 seconds → "2" (2 hours)

// MINUTES format
180 seconds → "3" (3 minutes)

// SECONDS format
3661 seconds → "3661" (raw seconds)

Common Configuration Examples

Task Completion Time

timeDurationStartInput: {
  type: TODO_CREATED_AT
  condition: FIRST
}
timeDurationEndInput: {
  type: TODO_MARKED_AS_COMPLETE
  condition: FIRST
}

Status Change Duration

timeDurationStartInput: {
  type: TODO_CUSTOM_FIELD
  condition: FIRST
  customFieldId: "status_field_id"
  customFieldOptionIds: ["in_progress_option_id"]
}
timeDurationEndInput: {
  type: TODO_CUSTOM_FIELD
  condition: FIRST
  customFieldId: "status_field_id"
  customFieldOptionIds: ["completed_option_id"]
}

Time in Specific List

timeDurationStartInput: {
  type: TODO_MOVED
  condition: FIRST
  todoListId: "review_list_id"
}
timeDurationEndInput: {
  type: TODO_MOVED
  condition: FIRST
  todoListId: "approved_list_id"
}

Assignment Response Time

timeDurationStartInput: {
  type: TODO_ASSIGNEE_ADDED
  condition: FIRST
  assigneeId: "user_123"
}
timeDurationEndInput: {
  type: TODO_CUSTOM_FIELD
  condition: FIRST
  customFieldId: "status_field_id"
  customFieldOptionIds: ["started_option_id"]
}

Required Permissions

Error Responses

Invalid Configuration

{
  "errors": [{
    "message": "Custom field is required for TODO_CUSTOM_FIELD type",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Referenced Field Not Found

{
  "errors": [{
    "message": "Custom field not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

Missing Required Options

{
  "errors": [{
    "message": "Custom field options are required for select field changes",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Important Notes

Automatic Calculation

• Duration fields are read-only - values are automatically calculated
• You cannot manually set duration values via API
• Calculations happen asynchronously via background jobs
• Values update automatically when trigger events occur

Performance Considerations

• Duration calculations are queued and processed asynchronously
• Large numbers of duration fields may impact performance
• Consider the frequency of trigger events when designing duration fields
• Use specific conditions to avoid unnecessary recalculations

Null Values

Duration fields will show null when:

• Start event hasn’t occurred yet
• End event hasn’t occurred yet
• Configuration references non-existent entities
• Calculation encounters an error

Best Practices

Configuration Design

• Use specific event types rather than generic ones when possible
• Choose appropriate FIRST vs LAST conditions based on your workflow
• Test duration calculations with sample data before deployment
• Document your duration field logic for team members

Display Formatting

• Use FULL_DATE_SUBSTRING for most readable format
• Use FULL_DATE for compact, consistent width display
• Use FULL_DATE_STRING for formal reports and documents
• Use DAYS, HOURS, MINUTES, or SECONDS for simple numeric displays
• Consider your UI space constraints when choosing format

SLA Monitoring with Target Time

When using timeDurationTargetTime:

• Set the target duration in seconds
• Compare actual duration against target for SLA compliance
• Use in dashboards to highlight overdue items
• Example: 24-hour response SLA = 86400 seconds

Workflow Integration

• Design duration fields to match your actual business processes
• Use duration data for process improvement and optimization
• Monitor duration trends to identify workflow bottlenecks
• Set up alerts for duration thresholds if needed

Common Use Cases

1. Process Performance

   • Task completion times
   • Review cycle times
   • Approval processing times
   • Response times

2. SLA Monitoring

   • Time to first response
   • Resolution times
   • Escalation timeframes
   • Service level compliance

3. Workflow Analytics

   • Bottleneck identification
   • Process optimization
   • Team performance metrics
   • Quality assurance timing

4. Project Management

   • Phase durations
   • Milestone timing
   • Resource allocation time
   • Delivery timeframes

Limitations

• Duration fields are read-only and cannot be manually set
• Values are calculated asynchronously and may not be immediately available
• Requires proper event triggers to be set up in your workflow
• Cannot calculate durations for events that haven’t occurred
• Limited to tracking time between discrete events (not continuous time tracking)
• No built-in SLA alerts or notifications
• Cannot aggregate multiple duration calculations into a single field

Related Resources

• Number Fields - For manual numeric values
• Date Fields - For specific date tracking
• Custom Fields Overview - General concepts
• Automations - For triggering actions based on duration thresholds