Automation - Set date field to a day of week in a future week

[#1]

Estimated time to read: 4-7 minutes

TL;DR:  Through Jira Cloud Automation you want to set a date field in a Jira work item to the date for a specific day of the week in a specified future week; i.e. set the Due date field to be Wednesday next week. 

The final smart value to use is

{{if(now.format("e").asNumber.gt(3), now.withNextDayOfWeek("WED").jiraDate, now.plusWeeks(1).withNextDayOfWeek("WED").jiraDate)}}

Inspiration:

I was inspired to write this article by this post:

How do I get my automated due date to be next week on a certain day of the week 

Topic Knowledge Level:

• Automation Rules: Beginner/Intermediate

• Date manipulation: Intermediate/Advanced

Prerequisites:

1. You are familiar with the Jira Cloud Automation feature.

2. You have access to create/modify Automation Rules for the Space where you want to implement this feature.

What problem are we solving?

With Jira Cloud Automation there is a function that enables you to set a date field to the date of the next occurrence of a specific day of the week; i.e. the next Wednesday to occur. That function is withNextDayOfWeek()

{{now.withNextDayOfWeek("WED")}}

However there is not a single native function currently that enables you to set a date field in a work item to the date of a specific day of the week in a future week. In plain language the requirement is:

“I want to set a date field in a Jira work item to the date of a specific day of the week in a future (1..n) week.”

An example of a scenario with this requirement could be:

“When a work item is created I want to set the Due date to Wednesday of next week, regardless of the current day; i.e. if the issue is created on Monday I want the Due date set the Wednesday 9 days from now (Wednesday of next week) not the next Wednesday that occurs (2 days from now).” 

Solution Methodology:

The solution for this is to use smart values that incorporate

1. the format() date function

2. the plusWeeks() date function

3. the withNextDayOfWeek() date function

4. the jiraDate date format command

5. the greaterThan() math function

6. the conditional logic if() function

Solution Prerequisites:

1. Determine your Jira instance’s First Day Of Week setting: The first day of the week for a Jira instance may be either Sunday or Monday. This is determined by the Use ISO8601 in date picker setting (enabled or disabled) accessed through Settings > System > Look and Feel > Change date and time formats. When disabled, Sunday is the first day of the week. When enabled, Monday is the first day of the week.
   

2. Automation Rule exists: You already have a base automation rule that successfully focuses on the work item you want to update. This may be a work item that is selected by the rule trigger or a branch step within the rule, or you may be placing focus on a new work item by using the Create or Clone actions.

3. [Action] Work Item step exists: You have inserted the step that enables an action on the specified work item; i.e. Create Work Item, Clone Work Item, Edit Work Item.

4. Date field is selected: Within the [Action] Work Item step you have selected the date field that you want to modify, such as the Due date field.
   

Solution Implementation:

Solution TL;DR

The final smart value to use is

{{if(now.format("e").asNumber.gt(3), now.withNextDayOfWeek("WED").jiraDate, now.plusWeeks(1).withNextDayOfWeek("WED").jiraDate)}}

Assumptions:

1. The Use ISO8601 in date picker setting is disabled, so Sunday is the first day of the week.

2. We want to set the Due date field.

3. The date we want is Wednesday of next week.

4. It must not matter what the current day of the week is.

Solution Explanation

1. Get the day of week for the current date with the format() date function:

From Automation smart values - date and time - Date Format function documentation we can find the link to Java documentation that provides extended definitions of date/time formatting codes. From that we can know that the format code “e” will give us the day of week as a number.

Combine this with the smart value now to get the day of week for the current date.

now.format("e")

2. The value is considered text within the automation rule, so convert it to a number using asNumber.

now.format("e").asNumber

Days of week are numbered starting with 1. When the first day of week is Sunday, the number for Wednesday is “4”.

3. Determine if the current day of week is later than Tuesday using the greaterThan() math function.

now.format("e").asNumber.gt(3)

4. When the current day of week is Wednesday, Thursday, Friday, or Saturday, the next Wednesday to occur with be the Wednesday of next week. In this case the withNextDayOfWeek() date function combined with the now smart value will give us the date for the next Wednesday that will occur.
   Use the first three letters of the day of week name as the input for the withNextDayOfWeek() function.

now.withNextDayOfWeek("WED")

5. When the current day of week is Sunday, Monday, or Tuesday, the next Wednesday to occur with be the Wednesday of the current week. In this case we need to use the plusWeeks() date function combined with the now smart value to bump the date into the next week.

now.plusWeeks(1)

6. And we combine that with the withNextDayOfWeek() date function to zero in on the date specifically for Wednesday of the next week.

now.plusWeeks(1).withNextDayOfWeek("WED")

7. Summarizing what we have so far:

   1. Step 3 gave us the condition - is today later than Tuesday
      now.format("e").asNumber.gt(3)

   2. Step 4 gave us the date to use when today is later than Tuesday
      now.withNextDayOfWeek("WED")

   3. Step 6 gave us the date to use when today is Tuesday or earlier
      now.plusWeeks(1).withNextDayOfWeek("WED")

   4. Add the jiraDate date format command to date calculations from steps 4 and 6 to ensure the results are formatted as a date-only value.

8. Combine those with the conditional logic if() function

{{if(<condition>, <result if true>, <result if false>)}}
and the final smart value is
{{if(now.format("e").asNumber.gt(3), now.withNextDayOfWeek("WED").jiraDate, now.plusWeeks(1).withNextDayOfWeek("WED").jiraDate)}}

9. Insert that smart value into the date field in your [Action] Work Item step.

Bonus tips:

If you want to set your date to a day of week 2 weeks from now, or 3 weeks from now, or N weeks from now, change the number in the plusWeeks(N) function to the nth week in the future that you are targeting.  

If you want to use this solution to set a date to a day of week N weeks in the future relative to another date field, substitute that date field for now in the functions; i.e. relative to the Planned Start Date field of the pre-existing work item being edited:

{{if(issue.Planned Start Date.format("e").asNumber.gt(3), issue.Planned Start Date.withNextDayOfWeek("WED").jiraDate, issue.Planned Start Date.plusWeeks(1).withNextDayOfWeek("WED").jiraDate)}}

In Conclusion:

With the solution in this article you can set a date field to a specified day of week in the nth future week relative to the current date or another date field value within the work item.

[Arkadiusz Wroblewski]

@Trudy Claspill 

Thank you for this article; I will definitely put it to use.

You were so invested in helping, I don't want to put more into this topic with the user besides asking for more information.

Thank you for your hard work.

I have an idea. For a "Solution" article, shouldn't we link to the original "Source Problem" community post? I think it would be very helpful for readers to see directly what led to this article.

[Dave LIAO]

@Trudy Claspill - thanks for putting this together, this article is organized well and super clear (especially thanks to the formatting and links to relevant resources)!

Sincerely,

A fellow Automation junkie

[John Funk]

Very nice article!

[Bill Sheboy]

Hi @Trudy Claspill 

Thank you for this excellent and well-written article!  Providing the full context and "edge case" stuff for the first-day-of-week setting will certainly help people following along who have changed that setting.

For feedback, a couple of things of note:

• One of your smart value expressions uses angled rather than plain text, vertical quotation marks; that would raise errors if copy-and-pasted into a rule
• Please consider using the same example throughout; a "FRI" target date is used at the beginning and the solution details then use "WED"

Thanks again for all you do helping people in the community!

Kind regards,
Bill

[Trudy Claspill]

Thank you @Bill Sheboy for your thoughtful feedback.

I incorporated your suggestion to use a consistent day of week throughout the article, and your suggestion to add jiraDate from your comment on the Question that inspired this article. And I think I fixed all the quote marks. Let me know if I missed one.

[Trudy Claspill]

Thank you for your feedback @Arkadiusz Wroblewski .

There is not a required format for "solution" articles, but I like your suggestion to include something about what inspired the article. I have added that to this article.

[Arkadiusz Wroblewski]

@Trudy Claspill  

I know, Trudy, that we don't really have a "template format" and we shouldn't. We all come from different backgrounds, we have our own styles, but that's what makes this entire community so awesome 😎

That was just my little “IT Support” mindset speaking. 🙂

We write a lot of internal guides, you can’t imagine how many Jira, IT Support, and IT infrastructure guides I’ve had to write lately. 😅 Very often, the reason behind them is a real ticket, problem, or user question.

My boss always likes when we include the ticket that led to the guide, because, and I have to admit, logically he is right, when you see the real “live” problem behind it, the solution is much easier to understand.

That was just one of my small IT Support habits, but a healthy one 😊🤗

[Charlotte D_Alfonso]

Great solution and user friendly article