---
schema: rendered-html/v1
title: "Working with Periods | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/working-with-periods.html
generated_at: 2026-06-11T15:21:12.282679+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- JavaScript Workflow Quick Start Guide
- Create a Workflow
- Edit a Workflow
- Workflow Rule Types
- Transactions
- Use Cases for Workflows
- Web-based Workflow Editor
- Using an External Code Editor
- Default Workflows
- Custom Workflow Repository
- JavaScript Workflow Reference
- Rule-specific Properties
- Context
- Requirements
- Using the Workflow API
- Building Integrations with Slack
- Using REST API Methods in JavaScript Workflows
- Working with Dates and Times
- [Working with Periods](working-with-periods.html)
- Localized Workflow Messages
- Troubleshooting Workflows
- Remote Debugger
- YouTrack Workflow API
- YouTrack Import Scripts
- YouTrack Form API
- [YouTrack REST API](jetbrains__com__help__youtrack__devportal__youtrack-rest-api.md)
- Hub REST API

1. YouTrack Workflows
2. JavaScript Workflow Reference
3. [Working with Periods](#0)

# Working with Periods﻿

Last modified: 12 May 2026

Period values represent amounts of time, such as `3h`, `2d`, or `1w3d4h`. In workflows, you usually work with period values when you read or update fields like Estimation and Spent time, add work items, or calculate dates from a duration.

A field that stores the `period` type returns a period object. To create a period object in workflow code, use the `date-time` module. To compare period values, convert them to a common unit first.

## Period String Syntax﻿

The `date-time` module accepts period strings with numeric values followed by unit abbreviations. Specify units in descending order, without spaces.

| Unit | Description | Example |
| --- | --- | --- |
| `w` | Weeks | `2w` |
| `d` | Days | `4d` |
| `h` | Hours | `6h` |
| `m` | Minutes | `30m` |

For example, `2w4d3h15m` represents two weeks, four days, three hours, and fifteen minutes.

The way period values are displayed in YouTrack depends on the period format and time tracking settings for the instance. The compact string format is the format you use when you create period values in workflow code.

## Create Period Values﻿

Use `dateTime.toPeriod()` to convert a period string or a number of milliseconds to a period object.

```
const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

const threeHours = dateTime.toPeriod('3h');
const fullPeriod = dateTime.toPeriod('2w4d3h15m');
const fromMilliseconds = dateTime.toPeriod(3 * 60 * 60 * 1000);
```

When you write a value to a period custom field, assign a period object, not a plain string.

```
const entities = require('@jetbrains/youtrack-scripting-api/entities');
const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

exports.rule = entities.Issue.onChange({
  title: 'Set default estimation',
  guard: (ctx) => {
    return ctx.issue.isReported && !ctx.issue.fields.Estimation;
  },
  action: (ctx) => {
    ctx.issue.fields.Estimation = dateTime.toPeriod('1d4h');
  },
  requirements: {
    Estimation: {
      type: entities.Field.periodType
    }
  }
});
```

## Read Period Fields﻿

Read a period field from `issue.fields`. Optional fields can be empty, so check that the value exists before you use it.

```
const estimation = ctx.issue.fields.Estimation;

if (estimation) {
  const weeks = estimation.getWeeks();
  const days = estimation.getDays();
  const hours = estimation.getHours();
  const minutes = estimation.getMinutes();
}
```

To show the value in the same format that YouTrack uses for the issue, use `getValuePresentation()` from the field requirement.

```
const presentation = ctx.Estimation.getValuePresentation(ctx.issue);
ctx.issue.addComment('Current estimation: ' + presentation);
```

## Convert Periods﻿

Period objects are not numbers. When you need to compare, add, or subtract period values, convert them to a common unit first.

The following helper converts a period value to minutes. It uses a five-day work week and an eight-hour work day, which are common default time tracking settings.

```
const WORKDAYS_PER_WEEK = 5;
const HOURS_PER_DAY = 8;

function periodToMinutes(period) {
  if (!period) {
    return 0;
  }

  return period.getMinutes() +
      60 * (period.getHours() +
          HOURS_PER_DAY * (period.getDays() +
              WORKDAYS_PER_WEEK * period.getWeeks()));
}
```

If your YouTrack instance uses different time tracking settings, adjust the constants to match your working week and working day.

After you calculate a new value in minutes, convert it back to a period before assigning it to a period field.

```
const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

const EXTRA_MINUTES = 90;
const currentMinutes = periodToMinutes(ctx.issue.fields.Estimation);
ctx.issue.fields.Estimation = dateTime.toPeriod((currentMinutes + EXTRA_MINUTES) * 60 * 1000);
```

## Compare Period Values﻿

To compare two period fields, convert both values to the same unit. The following rule prevents users from increasing Spent time beyond the current estimation.

```
const entities = require('@jetbrains/youtrack-scripting-api/entities');
const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

const WORKDAYS_PER_WEEK = 5;
const HOURS_PER_DAY = 8;

function periodToMinutes(period) {
  if (!period) {
    return 0;
  }

  return period.getMinutes() +
      60 * (period.getHours() +
          HOURS_PER_DAY * (period.getDays() +
              WORKDAYS_PER_WEEK * period.getWeeks()));
}

exports.rule = entities.Issue.onChange({
  title: 'Do not exceed estimation',
  guard: (ctx) => {
    return ctx.issue.fields.isChanged(ctx.SpentTime);
  },
  action: (ctx) => {
    const estimation = periodToMinutes(ctx.issue.fields.Estimation);
    const spentTime = periodToMinutes(ctx.issue.fields.SpentTime);

    workflow.check(!estimation || spentTime <= estimation,
        'Spent time cannot exceed the estimation.');
  },
  requirements: {
    Estimation: {
      type: entities.Field.periodType
    },
    SpentTime: {
      type: entities.Field.periodType,
      name: 'Spent time'
    }
  }
});
```

## Use Periods with Dates﻿

Use `dateTime.after()` and `dateTime.before()` when a period should move a timestamp forward or backward.

```
const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

const reminder = dateTime.before(ctx.issue.fields.DueDate, '2d');

if (ctx.issue.fields.Estimation) {
  const reviewDate = dateTime.after(Date.now(), ctx.issue.fields.Estimation);
}
```

These methods return Unix timestamps in milliseconds. Assign the result to a `date` or `date and time` field, or compare it with other timestamp values.

## Calculate Work Item Duration﻿

Work item durations are stored as minutes. When a workflow records time between two timestamps, use `Project.intervalToWorkingMinutes()` to calculate the number of minutes that fall within the project's working hours.

```
const duration = ctx.issue.project.intervalToWorkingMinutes(
    ctx.issue.fields.TimerTime,
    Date.now()
);

ctx.issue.addWorkItem({
  description: 'The work item automatically added by the timer.',
  date: Date.now(),
  author: ctx.currentUser,
  duration: duration
});
```

This is the same approach used by the default work timer workflows. To store a calculated duration in a period field instead, convert the number of minutes to milliseconds and pass it to `dateTime.toPeriod()`.

## Tips﻿

- Use `dateTime.toPeriod()` before assigning values to period fields.
- Use compact period strings like `3h` and `2w4d3h15m` in workflow code.
- Use `getWeeks()`, `getDays()`, `getHours()`, and `getMinutes()` when you need to calculate with a period value.
- Convert period values to minutes before you compare them.
- Use `dateTime.after()` and `dateTime.before()` to calculate dates from periods.
- Use `Project.intervalToWorkingMinutes()` when a duration should respect project working hours.

- [Working with Periods](/help/youtrack/devportal/working-with-periods.html)
- [Period String Syntax](/help/youtrack/devportal/working-with-periods.html#period-string-syntax)
- [Create Period Values](/help/youtrack/devportal/working-with-periods.html#create-period-values)
- [Read Period Fields](/help/youtrack/devportal/working-with-periods.html#read-period-fields)
- [Convert Periods](/help/youtrack/devportal/working-with-periods.html#convert-periods)
- [Compare Period Values](/help/youtrack/devportal/working-with-periods.html#compare-period-values)
- [Use Periods with Dates](/help/youtrack/devportal/working-with-periods.html#use-periods-with-dates)
- [Calculate Work Item Duration](/help/youtrack/devportal/working-with-periods.html#calculate-work-item-duration)
- [Tips](/help/youtrack/devportal/working-with-periods.html#tips)

Working with Dates and TimesLocalized Workflow Messages

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
