Sign Up
Contact Log In Sign Up
System Status

Create calculated time duration fields that track time between events in your workflow

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)

Parameter Type Required Description
name String! ✅ Yes Display name of the duration field
type CustomFieldType! ✅ Yes Must be TIME_DURATION
description String No Help text shown to users
timeDurationDisplay CustomFieldTimeDurationDisplayType! ✅ Yes How to display the duration
timeDurationStartInput CustomFieldTimeDurationInput! ✅ Yes Start event configuration
timeDurationEndInput CustomFieldTimeDurationInput! ✅ Yes End event configuration
timeDurationTargetTime Float No Target duration in seconds for SLA monitoring

CustomFieldTimeDurationInput

Parameter Type Required Description
type CustomFieldTimeDurationType! ✅ Yes Type of event to track
condition CustomFieldTimeDurationCondition! ✅ Yes FIRST or LAST occurrence
customFieldId String Conditional Required for TODO_CUSTOM_FIELD type
customFieldOptionIds [String!] Conditional Required for select field changes
todoListId String Conditional Required for TODO_MOVED type
tagId String Conditional Required for TODO_TAG_ADDED type
assigneeId String Conditional Required for TODO_ASSIGNEE_ADDED type

CustomFieldTimeDurationType Values

Value Description
TODO_CREATED_AT When the record was created
TODO_CUSTOM_FIELD When a custom field value changed
TODO_DUE_DATE When the due date was set
TODO_MARKED_AS_COMPLETE When the record was marked complete
TODO_MOVED When the record was moved to a different list
TODO_TAG_ADDED When a tag was added to the record
TODO_ASSIGNEE_ADDED When an assignee was added to the record

CustomFieldTimeDurationCondition Values

Value Description
FIRST Use the first occurrence of the event
LAST Use the last occurrence of the event

CustomFieldTimeDurationDisplayType Values

Value Description Example
FULL_DATE Days:Hours:Minutes:Seconds format "01:02:03:04"
FULL_DATE_STRING Written out in full words "Two hours, two minutes, three seconds"
FULL_DATE_SUBSTRING Numeric with units "1 hour, 2 minutes, 3 seconds"
DAYS Duration in days only "2.5" (2.5 days)
HOURS Duration in hours only "60" (60 hours)
MINUTES Duration in minutes only "3600" (3600 minutes)
SECONDS Duration in seconds only "216000" (216000 seconds)

Response Fields

TodoCustomField Response

Field Type Description
id String! Unique identifier for the field value
customField CustomField! The custom field definition
number Float The duration in seconds
value Float Alias for number (duration in seconds)
todo Todo! The record this value belongs to
createdAt DateTime! When the value was created
updatedAt DateTime! When the value was last updated

CustomField Response (TIME_DURATION)

Field Type Description
timeDurationDisplay CustomFieldTimeDurationDisplayType Display format for the duration
timeDurationStart CustomFieldTimeDuration Start event configuration
timeDurationEnd CustomFieldTimeDuration End event configuration
timeDurationTargetTime Float Target duration in seconds (for SLA monitoring)

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

Action Required Permission
Create duration field Project-level OWNER or ADMIN role
Update duration field Project-level OWNER or ADMIN role
View duration value Any project member role

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
© Blue | Designed with ❤ across the

AI Assistant

Responses are generated using AI and may contain mistakes.

How can I help you?

Ask me anything about Blue or this documentation.

Enter to send • Shift+Enter for new line • ⌘I to open