# Using Smart Values

Smart Values are computed expressions that calculate field values dynamically. They enable automation like date calculations, field references, and user data access.

Use Smart Values with the **Set Field Value** action to auto-populate fields with context-aware data.

***

## What Are Smart Values?

Smart Values are expressions that evaluate to a value at runtime, rather than using static text or numbers.

**Example comparison:**

**Static value:**

```
Set Due Date = "2026-03-15"
```

Always sets March 15, 2026. Never changes.

**Smart Value:**

```
Set Due Date = addDays(today(), 7)
```

Calculates 7 days from today when the rule executes. Adapts to current date.

***

## When to Use Smart Values

**Calculate dates:** Set due dates relative to today, calculate SLA deadlines, set dates to specific days

**Reference fields:** Copy values from one field to another, create dependent field relationships

**Access user data:** Auto-fill assignee or reporter fields with current user

**Ensure consistency:** Auto-fill fields with calculated values instead of manual entry

***

## Date Functions

All date functions work in UTC to avoid timezone issues.

### Current Date/Time Functions

#### `now()`

**Returns:** Current date and time in UTC

**Example:**

```
now()
→ 2026-02-01T14:30:00Z
```

#### `today()`

**Returns:** Today's date at midnight UTC (00:00:00)

**Example:**

```
today()
→ 2026-02-01T00:00:00Z
```

#### `yesterday()`

**Returns:** Yesterday's date at midnight UTC (00:00:00)

**Example:**

```
yesterday()
→ 2026-01-31T00:00:00Z
```

#### `tomorrow()`

**Returns:** Tomorrow's date at midnight UTC (00:00:00)

**Example:**

```
tomorrow()
→ 2026-02-02T00:00:00Z
```

***

### Date Navigation Functions

#### `nextWeek()`

**Returns:** Date 7 days from today at midnight UTC (00:00:00)

**Example:**

```
nextWeek()
→ 2026-02-08T00:00:00Z (7 days from today)
```

#### `nextMonth()`

**Returns:** Date one month from today at midnight UTC (00:00:00)

**Example:**

```
nextMonth()
→ 2026-03-01T00:00:00Z
```

#### `startOfWeek()`

**Returns:** Start of current week (Monday) at midnight UTC (00:00:00)

**Note:** Week starts on Monday

**Example:**

```
startOfWeek()
→ 2026-01-26T00:00:00Z (this Monday)
```

#### `endOfWeek()`

**Returns:** End of current week (Sunday) at midnight UTC (00:00:00)

**Note:** Week ends on Sunday

**Example:**

```
endOfWeek()
→ 2026-02-01T00:00:00Z (this Sunday)
```

#### `endOfMonth()`

**Returns:** Last day of current month at midnight UTC (00:00:00)

**Example:**

```
endOfMonth()
→ 2026-02-28T00:00:00Z
```

#### `startOfDay(date)`

**Parameters:**

* `date` - A date value

**Returns:** Start of day (midnight UTC) for the given date

**Example:**

```
startOfDay(now())
→ 2026-02-01T00:00:00Z
```

***

### Date Arithmetic Functions

#### `addDays(date, days)`

**Parameters:**

* `date` - A date value
* `days` - Number of days to add (can be negative)

**Returns:** Date with specified number of days added

**Example:**

```
addDays(today(), 5)
→ 2026-02-06T00:00:00Z (5 days from today)

addDays(today(), -3)
→ 2026-01-29T00:00:00Z (3 days ago)
```

#### `addWeeks(date, weeks)`

**Parameters:**

* `date` - A date value
* `weeks` - Number of weeks to add (7 days each)

**Returns:** Date with specified number of weeks added

**Example:**

```
addWeeks(today(), 2)
→ 2026-02-15T00:00:00Z (14 days from today)
```

#### `subtractBusinessDays(date, days)`

**Parameters:**

* `date` - A date value
* `days` - Number of business days to subtract

**Returns:** Date with specified business days subtracted, skipping weekends (Saturday/Sunday)

**Note:** Business days are Monday-Friday

**Example:**

```
subtractBusinessDays(today(), 3)
→ 2026-01-28T00:00:00Z (3 business days ago, skipping weekend)
```

***

### Date Methods

Date objects can have methods called on them using dot notation.

#### `date.plusBusinessDays(days)`

**Parameters:**

* `days` - Number of business days to add

**Returns:** Date with specified business days added, skipping weekends (Saturday/Sunday)

**Note:** Business days are Monday-Friday. Called as a method on a Date object.

**Example:**

```
today().plusBusinessDays(3)
→ 2026-02-04T00:00:00Z (3 business days from today)

now().plusBusinessDays(5)
→ 2026-02-06T14:30:00Z (5 business days from now)
```

***

## Field Functions

#### `field(fieldId)`

**Parameters:**

* `fieldId` - Field ID or system name (e.g., "duedate", "summary", "customfield\_10001")

**Returns:** Current value of the specified Jira field. Return type varies by field: string, number, Date, array, or undefined if field is empty.

**Example:**

```
field("duedate")
→ Returns Due Date field value (Date)

field("summary")
→ Returns Summary field value (string)

field("customfield_10001")
→ Returns custom field value (type varies)
```

**Common field names:**

* `duedate` - Due Date
* `summary` - Summary
* `description` - Description
* `priority` - Priority
* `assignee` - Assignee
* `reporter` - Reporter
* `customfield_XXXXX` - Custom fields (use field ID)

***

## User Functions

#### `currentUser()`

**Returns:** Current user executing the action, with `accountId` and `displayName` properties

**Example:**

```
currentUser()
→ { accountId: "557058:...", displayName: "John Smith" }
```

**Use case:** Set Assignee or Reporter to current user

***

## Practical Examples

### Date Examples

**Set due date to 7 days from now:**

```
addDays(today(), 7)
```

**Set due date to next Friday:**

```
endOfWeek().plusBusinessDays(-2)
```

**Set review date to 3 business days from today:**

```
today().plusBusinessDays(3)
```

**Set start date to beginning of current week:**

```
startOfWeek()
```

**Set deadline to end of next month:**

```
addWeeks(endOfMonth(), 4)
```

### Field Reference Examples

**Copy Due Date from another field:**

```
field("duedate")
```

**Set Summary based on custom field:**

```
field("customfield_10001")
```

### User Examples

**Set Assignee to current user:**

```
currentUser()
```

***

## Combining Smart Values

You can combine multiple functions to create complex calculations.

**Due date 5 business days from now:**

```
today().plusBusinessDays(5)
```

**Start date at beginning of next week:**

```
addWeeks(startOfWeek(), 1)
```

**Date 3 days before a specific field's date:**

```
addDays(field("duedate"), -3)
```

***

## Using Smart Values in Rules

### Configuration Steps

1. Create a rule with **Set Field Value** action
2. Select the target field to populate
3. Enter a Smart Value expression in the value field
4. Save and test the rule

### Example Rule

**Requirement:** Set Due Date to 3 business days from today when creating Bug issues

**Configuration:**

* Screen: Global Issue Create
* Target Field: Due Date
* Scope: Bug issue type
* Action: Set Field Value
* Value: `today().plusBusinessDays(3)`

**Result:** When creating a Bug, Due Date auto-fills with today + 3 business days.

***

## Best Practices

**Use descriptive expressions:** Choose functions that clearly express intent (e.g., `today().plusBusinessDays(5)` is clearer than complex date math)

**Test with different dates:** Verify Smart Values work correctly across month/year boundaries

**Account for weekends:** Use business day functions when working days matter

**Validate field existence:** Ensure referenced fields exist in the project before using `field()` function

**Keep it simple:** Break complex calculations into multiple rules rather than one complex expression

***

## Error Handling

**If a Smart Value fails:**

* The field will not be set
* The rule will not prevent form submission
* Check rule configuration for syntax errors

**Common issues:**

* Referencing non-existent fields with `field()`
* Invalid field IDs
* Incorrect function names or parameters

***

## Limitations

**Time zones:** All dates use UTC. Jira may display dates in user's local timezone.

**Field types:** `field()` returns different data types depending on the field. Ensure compatibility with target field.

**No nested conditionals:** Complex logic should be handled with multiple rules, not one Smart Value expression.

***

## Next Steps

**Learn about actions:**

* [Defining Actions](https://teranoapps.gitbook.io/dynamic-screen-rules/configuration-guide/defining-actions) - All seven actions including Set Field Value

**See examples:**

* [Use Cases & Examples](https://teranoapps.gitbook.io/dynamic-screen-rules/use-cases-and-examples/progressive-disclosure) - Real-world Smart Value applications

**Understand conditions:**

* [Defining Rule Conditions](https://teranoapps.gitbook.io/dynamic-screen-rules/configuration-guide/defining-rule-conditions) - Combine Smart Values with conditions

Ready to create rules with Smart Values? Start with [Creating Your First Rule](https://teranoapps.gitbook.io/dynamic-screen-rules/configuration-guide/creating-your-first-rule).