Welcome to the Baking Boards vlog series! This series is devoted to showing you how we at JetBrains configure and use Agile boards in YouTrack.

Different teams use boards in different ways. You’ll see examples from Product Development, Design, Marketing, Technical Writing, and even a personal board. Each episode shows you how one of our teams manages a project on an agile board that supports their process. We also include a recipe to follow if you want to “bake” a board just like it.

Let’s cook!

In the first episode of Baking Boards, we show you how our technical writers cooked (that is, configured) their agile board to manage documentation tasks for YouTrack and Hub.

Preparation

1. Create your board.
We built this board using the Scrum board template.

When you create the board:

• Select the projects that you want to manage on the board. All of the issues that we manage on this board belong to the same project.
• For the Backlog option, choose Create new. We’ll customize the backlog later.

2. Create a sprint.

This board uses sprints that correspond to major releases in YouTrack and Hub, however, we only assign each sprint a name.

All sprints are unscheduled.

3. Set sprint options.
We pull all of our issues from the backlog, so we don’t use any options that add issues to the board automatically.

4. Define columns.
Columns are identified by values from the State field. We have separate columns for Open, Reopened (merged), In Progress, In Review, Ready, and Published.

5. Define swimlanes.
Swimlanes are identified by issues that are assigned the Epic value in the Type field.
We show the swimlane for uncategorized cards at the bottom of the board.

6. Configure cards.
When we add a card to the board, the default value for the Type field is Task.
The Color Scheme is based on the set of values for the Priority field.
We also enabled the option to show colors for other custom fields.

7. Pick a chart.
We didn’t show our chart in the demo, but for this board, we use the Cumulative flow diagram.

8. Build the backlog.
We use the backlog to filter out issues that we don’t want to manage on this board. Our backlog uses the following saved search:

This search query:

• Shows only issues that belong to our project (Ring Docs)
• Excludes issues from specific subsystems (Subsystem: -Wording, -Screencasts)
• Shows only issues that are unresolved (#Unresolved)
• Excludes issues that are already assigned to a sprint on the board (has: -{Board Ring Docs}

Enjoy! Bon appetit!

In this episode of Baking Boards, we show you the agile board that the design team cooked up to manage issues in their project.

Preparation

1. Create your board.
   We built this board using the Custom board template.

When you create the board:

• Select the projects that you want to manage on the board. All of the issues that we manage on this board belong to the same project.
• For the Backlog option, choose Create new. We won’t do anything with it, but you need a backlog to create the board.

2. Define columns.

With the custom board template, you have to define your columns first. On our board, columns are identified by values from the State field. We merge the Submitted, Open, and Reopened states in the first column. The second merged column shows issues that have the states Incomplete, or To be discussed. We then have dedicated columns for the states In Progress, Wait for Reply, and Fixed.

3. Create a sprint.

Now that your board is configured correctly, you can add your first sprint. This board uses sprints that correspond to the seasons on the calendar. We set the sprint name to the season and year and schedule each sprint for three months.

4. Set sprint options.

We use the Add new issues to sprint option and select the current sprint.
When we add the next sprint to the board, we update this option to add issues to the new sprint.

5. Define swimlanes.

Here, we identify swimlanes for each value in the Assignee field. This creates a separate swimlane for each member of the team.
We show the swimlane for uncategorized cards at the top of the board. New issues that are added to the board automatically appear in this swimlane.

6. Configure cards.

We don’t have the option to set the default issue type for new cards. That’s because we define swimlanes by assignee. Which is fine — we use the Type field to indicate whether the design request is for an icon, t-shirt, banner, and so on.
The Color Scheme is based on the set of values for the Priority field.

We use the Show colors for other custom fields option to show color indicators for the Priority field, but we don’t really need it. The first custom field in our project is Due Date, so we work against the deadline.

There are a few features on the board that we don’t use at all:

• Backlog — with the option to add new issues to the sprint enabled, we don’t keep a backlog. New issues appear on the board automatically and are assigned to a designer shortly after they are reported.
  If you have unresolved issues in an existing project that you want to migrate to the board, create a saved search that contains these issues and use this saved search as a backlog. Once you’ve moved all of the issues from the backlog to the board, you can collapse the backlog and forget about it.
• Charts — we don’t work with charts on the board. If you’re looking to build a board that’s similar to this one, you can pick whichever chart suits your style.

Secret Sauce

As you may have noticed in the screencast, our design team has two team leads. They review all cards that are added to the board automatically and assign each issue to one of our designers.
What you don’t see is the workflow that is attached to the Design & Artwork project. This workflow blocks anyone other than these two team leads from changing the value in the Assignee field.

This means the team can make their board visible to other teams at JetBrains, but they have full control over who takes each assignment.

Here’s the rule:

The workflow allows any member of the design-artwork-assignee-updaters group to set the value of the Assignee warning. If the team leads need someone to assign issues in their absence, they just add them to the group.

If anybody else tries to assign an issue in the project, an error message displays the names of the people they can contact to get the issue assigned to a designer.

In this episode of Baking Boards, our Product Marketing Managers show you how they manage marketing-related activities in 20 different projects on an agile board.

Preparation

1. Create your board.
Start with the Scrum board template.

2. Add your projects

• First, make sure your projects all use the custom field that you want to use to identify columns on the board. It’s best to use the default State field. They don’t have to use the same set of value for this field, but if they don’t use the same field, you won’t be able to manage these projects on the board.

• Add all of the projects that you want to manage on the board. We manage issues from 20 different projects on this board – so can you!
• For the Backlog option, choose Create new. You’ll have plenty of time to customize this query later.

3. Create your first sprint.
This board uses sprints that correspond to each calendar month. Here we’ve set up a sprint for April 2017.

4. Set sprint options.
We either pull issues from the backlog or add issues directly to the board. To do the same, leave the option to Manually assign issues to sprints enabled.

5. Define columns.
Columns are identified by values from the State field, which is used in all of the projects that we manage on this board. However, many of these projects use a custom set of values for this field.
To configure your columns like we do, click the Add column control and select all of the values that you want to see on the board.

When you’re done, use the Merge with control to combine similar states.

6. Define swimlanes.
Most of the swimlanes on our board are identified by issues in our own project. These are assigned the Epic value in the Type field.
Here again, we run into problems with issues in other projects that don’t use the same set of values for a custom field. To use issues from other projects as swimlanes, we added issues that are assigned the Feature value to our configuration.

We show the swimlane for uncategorized cards at the bottom of the board.

7. Configure cards.
We create a lot of issues directly on the board. When we add a card to the board, the default value for the Type field is Task.
The Color Scheme is based on the set of values for the Priority field.
We also enabled the option to show colors for other custom fields.

We don’t estimate all of our tasks, but when we do, we show the estimations on the board. We use the Estimated time field to store estimations in our project, but other projects use other fields — assuming they estimate their tasks at all.

8. Pick a chart.
For this board, we use the Burndown chart. We didn’t include the chart in the demo, but since we switched to monthly sprints, we found it helps us track our progress.

The Query setting filters out parent tasks, so we can track our progress for just the subtasks.

9. Build the backlog.
We use the backlog to prioritize issues in our project. The saved search sorts issues in a custom order.

We use the following search criteria to define the backlog:

This search query:

• Shows only issues that belong to our project (Marketing)
• Filters issues in the project to show only specific subsystems (Subsystem: {YouTrack marketing}, {Hub marketing})
• Shows only issues that are unresolved (#Unresolved)
• Excludes issues that are already assigned to a sprint on the board (has: -{Board YouTrack Marketing}

Serving Suggestion

As you work with this board, keep an eye on the header. Here, you can find a link to issues that no longer match the settings that define columns or swimlanes.

When you manage issues that belong to other projects, you’ll often run into project managers who add or rename values in the custom field that you use to identify columns on the board. When issues are assigned these new values, they can mysteriously disappear from your board. Click the link in the header to show the list of issues that are no longer visible on your board and update your settings, if necessary.

In this episode of Baking Boards, we show you how to build and use a Scrum board for agile software development. This is the same board that is used by the team who built the agile board in YouTrack!

Preparation

1. Create your board.
We built this board using the Scrum board template.

When you create the board:

• Select the projects that you want to manage on the board. On this board, we manage issues in the YouTrack and YouTrack Backlog projects.
• For the Backlog option, choose Create new. We’ll customize the backlog later.

2. Create a sprint.
We assign each sprint a number as the sprint name and set the schedule for two weeks.
Most sprints start on a Monday and end on the following Friday.

3. Set sprint options.
We pull user stories from the backlog, so we don’t use any options that add issues to the board automatically.

4. Define columns.
Columns are identified by values from the State field. We have separate columns for Open, In Progress, To be discussed (merged), and Fixed.
There’s an additional state in our projects, but we don’t add it as a column on the board. When an issue moves from Fixed to Verified, it disappears from the board, but is still assigned to the sprint.

5. Define swimlanes.
Most of the swimlanes are identified by issues that are assigned the User story value in the Type field. From time to time, we add a special swimlane for reducing technical debt, so we add issues that are assigned this type as well.
We show the swimlane for uncategorized cards at the top of the board.

6. Configure cards.
When we add a card to the board, the default value for the Type field is Task.
The Color Scheme is based on the set of values for the Priority field.
We also enabled the option to show colors for other custom fields.

7. Build the backlog.
We create user stories in a dedicated project for backlog issues. The saved search for the backlog uses a custom sort order. We review and prioritize issues in the backlog when we plan each sprint.

This search query:

• Shows only issues that belong to our project for backlog issues (YouTrack Backlog, YTB for short)
• Shows only issues that are unresolved (#Unresolved)
• Excludes issues that are already assigned to a sprint on the board (has: -{Board YouTrack}

Note: We don’t configure the chart option on this board. Our approach to Scrum includes a few unconventional practices that reduce the effectiveness of the burndown as a reporting tool.
We don’t estimate tasks.
We continuously add new issues to the board during the sprint.
We split issues that were created during the planning into smaller tasks.
Our focus is simply to finish as many user stories as possible before the end of the sprint. To track our progress, all we have to do is look at the number of unresolved swimlanes on the board.

In this episode of Baking Boards, two of our Quality Assurance Engineers show you how the CLion and AppCode teams use their agile boards to follow a Kanban-inspired methodology.

Preparation

1. Create your board.
Start with the Kanban board template.

2. Add your projects.
You can add multiple projects, but on these boards, each team only manages issues that are assigned to one project. The CLion and AppCode teams have separate projects, and each project has its own board.

For the Backlog option, choose Create new. You can set this up later.
Just click the Create Board button to continue with the setup.

3. Rename your sprint.
Our teams works in a continuous flow that is represented by a single, unscheduled sprint. To make this more obvious, they renamed the default sprint.

Follow these instructions:

• Open the sprint drop-down list.
• Click the Edit icon next to the First sprint.
• Rename the sprint. We changed the name to Current.
• Leave the sprint as unscheduled and apply your changes.

4. Set sprint options.
For a Kanban board, you would normally add all new issues to the board when they are submitted in the project. These teams use the backlog to prioritize issues and manually add the issues to the board.

However, they use the Automatically add new issues to Current sprints option in order to transfer the issues between the CLion and AppCode boards. When an issue moves between the CLion and AppCode projects (which happens quite often), unresolved issues are assigned to the current sprint in the new project automatically. This ensures that the issue appears in the same stage of development on the Kanban board for the new project.

5. Define columns.
Each team identifies columns with the values that are stored in the CIDR Kanban State field.

This field is attached to the CLion project and the AppCode project, so they use it to define the columns for both boards.
The values in this field represent the stages in their development process. They use the stages Analyse, Develop, Review, Ready to test, Test, Merge, and Done.
Merge is a special stage where a task is ready but not yet published in the release branch. When the task is merged to the release branch, it moves to the Done column.

6. Set WIP limits.
These teams limit the work in progress for every column except Done.

The WIP limits are tuned according to the number of team members who work on each stage and the number of tasks they are comfortable working on in parallel. When cards in a column exceed the WIP limit, this indicates that there is a bottleneck in this stage of development.

7. Define swimlanes.
Here, the teams also use a dedicated custom field, CIDR Kanban track, to separate tasks into different streams. This field stores two values: Priority and General.
Priority tasks go on the top, and should be taken first.

8. Configure cards.
The teams use the swimlanes to indicate which issues need the most attention, but they also use the values in the Severity field to highlight cards on the board. This helps us see if there are any issues in the General swimlane that need to be moved to the Priority track.

9. Pick a chart.
They don’t work with the chart on these agile boards – the WIP limits help them to identify bottlenecks. The default chart option for a Kanban board is Cumulative flow, so it’s already set up if you want to use it.

10. Build the backlog.
Each of these projects use a saved search that represents the incoming queue of issues.
Each saved search sorts issues in a custom order. They use the custom order in the issues list to prioritize the queue.
This search query simply shows any issue that is unresolved in either project.

Serving Suggestion

Prioritizing issues in the queue is an important part of the process for both teams. The teams organize the queue during planning sessions and revisit the priority on a regular basis. Planning sessions occur after every major release. The teams makes a preliminary agreement on the priority for each task and who will take it.

The queue is updated when new critical issues or regressions appear, or whenever the teams just feel that the order needs to change.

Developers also have their own lists of things to do. The queue is simply a guideline. When developers choose their next task, they either look into the backlog for an issue in the queue or check their personal list.

On any Kanban board, tasks eventually start to pile up in the Done column. When these teams publish an EAP or release version of their product, they remove all of the issues that are included in the release from the board. The fastest way to clean up the Done column is to search for all of the resolved issues that were included in the latest release, for example, in: CPP version: {CLion 2017.1.1} State: Fixed and update them with a command. For example, the command to remove issues from the CLion board is remove Board CLion Kanban.

Secret Sauce

The CLion and AppCode teams use several workflow rules that automatically update values in issues that are managed on the board. The following workflows are triggered by events on the board:

1. When a user moves an issue to the board, the card is assigned to the current user. This workflow also assigns a card to the QA Engineer who moves it to the Test column. The assignee is not updated when cards move between other columns — these assignments are set manually.

2. When an issue is added to the board, the value in the CIDR Kanban Track field is set to General (if the field was empty). This workflow fires when a developer adds an issue to the board with a command or by setting a value of the CIDR Kanban State field in the issue itself.
This ensures that the issue is added to the correct swimlane. If the value in the CIDR Kanban Track field is empty, the card appears in the swimlane for uncategorized cards, which is not where it belongs.

3. When a card is moved from one column to another, changes are synchronized with the value that is stored in the State field. The CIDR Kanban State field stores values as enumerated types, not states. If the value for the State field is not synchronized with changes on the board, the issues are never moved to a state that is considered to be resolved.
This workflow sets the value for the State when the following changes are applied to an issue:

• When a card moves to the Done column, the state is set to Fixed. The issue is then considered to be resolved. If the card is currently assigned to the Priority swimlane, it moves to General.
• When a card is added to the board (meaning the CIDR Kanban State field is set to any value other than Done), the state is set to In Progress.
• If an issue is removed from the board (meaning the CIDR Kanban State field is set to an empty value) and an issue has the In Progress state, the state is set to Open. In this case, the workflow also removes the issue from the current sprint and sets the CIDR Kanban Track field to an empty value.

4. When a card moves to the Test column, the no testing tag is removed from the issue.
The team uses the no testing tag to flag trivial fixes. The developer and reviewer can agree that an issue doesn’t require testing and add the tag. However, if QA disagrees and decides it should be tested, the tag is removed automatically. When QA agrees to pass the issue without testing, the tag remains as an indicator that the fix was not tested manually.

Here is the workflow code:

5. When an issue moves to the Done column, the user is prompted to set a value for the Fix versions field. This workflow ensures that only tasks that are ready for release are moved to the Done column.

Note that this change isn’t actually triggered when the value for the CIDR Kanban Field changes. Instead, it is triggered by the workflow that synchronizes changes in this field with the value for the State field. This behavior is managed by the third workflow in this list.

Cook’s Note

As you can see, these teams follow a hybrid agile methodology. They call it ‘Kanban-inspired’. However, it works well for them, which again proves the main concept of any agile methodology: there are no strict rules to follow. Being agile means being flexible and ready to continuously tune your process.

If you are new to agile, and want to try a Kanban approach, we recommend that you start with a traditional Kanban practice. You can follow the setup that is described in our Kanban tutorial and tune it as you move forward.

Good luck with your Kanban transformation!

In this episode of Baking Boards, Andrey Cheptsov, the Product Marketing Manager for IntelliJ IDEA, shows you the personal board he uses to track all of the activity that is related to the promotion of this IDE.

Preparation

1. Create your board.
For easy configuration, use the Custom board template.

When you create the board:
– Select the projects that you want to manage on the board. You can track issues in any project that you have the permission to view issues.

-For the Backlog option, choose Create new. You won’t use it, but you need a backlog to create the board.

2. Define columns.
With the custom board template, you have to define your columns first.

Switch to the Columns and Rows tab to set them up.
Andrey’s board uses values from the State field. He added all of the values in each project that that are not considered resolved. Basically, any state that isn’t Fixed or Done.
With this setup, issues are removed from the board as soon as they are resolved.
First, use the Add column drop-down to add each unresolved state to the board.

Then, use the Merge with drop-down to merge all of these values into a single column.

3. Define swimlanes.
As shown in the demo, Andrey defines swimlanes using a special value for the Type field his project. He assigns issues the Meta Issue type and only uses this type for swimlane issues.
First, you need to add a special value like this to the Type field in one of the projects that you manage on the board.
Then, configure your board to identify swimlanes by Issues from the Type field, then use the Add value drop-down to add the special value to the board configuration.

That’s all there is to it! There are a lot of other settings that you can play around with to personalize your personal board, but they’re not used in this setup. Here are a few settings you can safely ignore:

• Sprints — this board uses a single, unscheduled sprint. Issues are assigned manually to this sprint. Andrey adds cards to the board by linking issues as subtasks to issues that define swimlanes on the board.
• Backlog — the backlog isn’t used at all, as each team prioritizes their issues differently.
• Cards — with this setup, you rarely add issues to the board, so you don’t need to set default values for the issue type.
• Charts — the chart options are not relevant to the board.

Secret Sauce

Andrey uses the YouTrack Tweaks extension for Chrome to enhance the visual appearance of the board. With this extension, he can:

• Choose which custom fields are displayed on all cards.
• Display values for custom fields with the card size set to S.
• Hide the board footer.
• Collapse swimlane titles to one line.
• Switch to a color scheme that is similar to the Darcula theme in IntelliJ IDEA.

To achieve this look, he has enabled and configured the default Agile board card fields module and the Agile board layout module.
Here’s how you can do the same:

1. Access the extension in the chrome web store.
2. Add the extension to Chrome. For detailed instructions, see the doc.
3. Enable and configure the modules that you want to apply to the board.

Here are the modules that Andrey enabled on his board, with instructions for configuring each module:

Default cards tweak
This is the Agile board card fields module that is enabled by default when you install the extension in Chrome.

1. Set the Prepend issue summary with issue id (S size only) to Yes.
   This shows the issue ID, even with the card size set to S.
2. Use the Fields settings to add the fields you want to show on each card. Andrey added the Due Date, Start date, State, and Assignee fields.

Agile board layout
This module modifies the look and feel of the board. You can use the default configuration for this module.

1. The Darcula mode option is Enabled.
2. The One line swimlane title option is Enabled.
3. The Sticky header is Visible.
4. The Sticky footer is Hidden.

When you’ve finished configuring the extension, your board should look something like this:

If you look carefully, you’ll see that these teams use different color schemes for the State field in their projects. Don’t worry — there’s a fix for that as well!
1. Open the settings for the Default cards tweak module.
2. Click the Edit button for the State field setting.
3. Change the Use field colors option to Auto-generated colors.

4. Click the Save and apply button.

Now, each value in the State field is assigned a unique color, no matter which project the issue belongs to.

Ready to try this board for your tasks? Get YouTrack and bake your board with pleasure!

In this episode of Baking Boards, we show you how two very different teams at JetBrains use agile boards that synchronize sprints with the fix version of the product in development.

Preparation

1. Create your board.
Start with the Version-based board template.

2. Add your project.
When you link sprints to fix versions, you’re normally dealing with a single project. To work properly, this project should already use a field with the name Fix version or Fix versions. You can also manage multiple projects on a version-based board, as long as all of the projects use the same set of values for the Fix version or Fix versions field.

If you already have a saved search for backlog issues, leave the Backlog option set to Use existing and select it in the Saved Search drop-down list.

Otherwise, choose Create new, then click the Create Board button.
When you create the board, the option to link sprints to the Fix version or Fix versions field is enabled automatically. All of the values that are currently stored in this field are added to the board as sprints.
3. (Optional) Apply a filter.
With the Link sprints to custom field option, you can use a search query to filter the cards on the board.

Use this filter to show only issues that are assigned to a specific subsystem or include a special tag.

4. Set up your columns.
You’ll notice right away that your board has configuration errors. To fix it, switch to the Columns and Rows tab and choose a field to identify your columns. The most common configuration is to use the State field.

5. Define swimlanes.
Most software development teams use the issue type to organize their work into features or user stories. You can use these issues to define swimlanes on the board and manage their subtasks as cards. Select the Issues option, choose the Type field, and add the issue type you use for parent tasks in your project.

6. Configure cards.
If you plan to create issues directly on the board, it saves you time to set a default value for the Type field. Switch to the Card tab and set the default value for the Type field to Task.

7. Pick a chart.
If you want to track your progress, pick the chart that mirrors how you manage your workload. If you follow a scrum methodology, use the Burndown chart. For Kanban, use Cumulative flow.

Secret Sauce

The dotMemory team uses several workflows to manage issues in their project as they work with their agile board.

One of the main reasons they use workflows is because they use an enumerated field named Phase (not a state-type field) to identify the columns on the board. These workflows synchronize changes that are applied when a card moves between columns and the values that are stored in the State field.

The reason that they use Phase instead of State to identify columns on the board is that the Phase field is private. Only members of the dotMemory team have permission to update private fields in their project. Even though members of other development teams can view and update these issues, only members of the dotMemory team can change the value of the field that defines their position on the agile board.

Their workflow synchronizes the values for the Phase and State fields and automates other board-related activity when changes are applied to issues. The values for these two fields are shown in the following diagram:

The first rule in this workflow is a state-machine rule that regulates changes between the values for the Phase field. The transitions that are allowed for this field are represented by the arrows between each value on the left side of the following diagram.

This state-machine rule also sets the value in the State field based on the value that is set for the Phase field. These changes are represented by the arrows from the values for the Phase field to the values for the State field. For example, when the value for the Phase field changes from Testing to Development (because the issue did not pass the test phase), the value for the State field is set to Reopened.
Here’s the code for the state-machine rule:

An on-change rule changes the value in the Phase field if a user updates the value of the State field. These changes are represented by the arrows from the values for the State field to the values for the Phase field in the following diagram:

Here’s the code for this rule:

The remaining rules add and remove issues from the board as needed.
– The first rule adds issues to the board when an issue is reported and is assigned a fix version. As long as the fix version is not set to the Backlog, the value for the Phase field is set to To do.

– The second rule clears the value for the Phase field when the fix version is set to the Backlog.

– The third rule clears the value for the Phase field when the value for the State field is set to any value that resolves the issue but does not involve fixing the problem. This action removes the issue from the board. Because the sprints are linked to fix versions, the fix version is removed as well. These states are shown in red in the following diagram:

Here’s the code for this rule:

Want to try this board configuration for your project? Get YouTrack and bake your board with pleasure!

We at JetBrains care about the security of our customers’ data. It is extremely important that we keep it safe for you.
As you might know, YouTrack InCloud instances use the HTTPS protocol by default, but this wasn’t always the case. We also give you the option to disable HTTPS for your instance. To make YouTrack more secure, we have decided to discontinue support for HTTP connections.

Who is affected?
This change affects YouTrack InCloud instances where:

• The instance was registered before December 2015 and is not configured to use HTTPS. Instances created after this date use HTTPS by default.
• The HTTPS only setting has been manually disabled, allowing unsecured connections over HTTP. To verify this setting, check the Domain Settings page.
• The instance uses a custom domain name and does not have a valid SSL certificate for the custom domain.
• The instance accepts HTTP requests from external integrations that use the REST API.

What does it mean?
If you interact with YouTrack in your browser, you basically don’t have to do anything. You will be redirected to use an HTTPS connection automatically.

All of the instances that are hosted on the *.myjetbrains.com domain will switch to HTTPS.

If you have a custom domain set up for your instance, we will automatically generate a certificate signed by Let’s Encrypt for you. You will still be able to set up your own certificates, so no changes will be applied to certificates that were installed previously.

The only situation that requires action on your part is when you have external integrations that access data in YouTrack using the REST API over an unsecured connection. In this case, you need to update these integrations to use HTTPS. Otherwise, the connections are refused and the integration is broken.

When will it happen?
We plan to disable HTTP access in approximately one month. To ensure that your integrations work properly, make sure that all of your applications that use the YouTrack REST API are updated to use HTTPS before then.

Thank you for using YouTrack.
If you have any questions, please contact our support team.

Please welcome a brand new (preview) version of YouTrackSharp – a .NET library to work with the YouTrack REST API. It’s a complete rewrite from the previous version, since a lot of things in the .NET world have changed.

First of all, YouTrackSharp now targets  .NET Standard 1.3, which means it can now be used with pretty much any .NET platform, including .NET Framework 4.6, .NET Core, Mono, Xamarin, and UWP. We wanted to make sure many different applications could be developed with YouTrackSharp, on many platforms.

Another benefit of being on this new stack is we were able to make YouTrackSharp async all the way. And we were able to tackle some other things, too, like handling serialization of YouTrack’s timestamps into DateTime where possible. Let’s have a look!

Getting started

We are distributing YouTrackSharp as a NuGet package, which means it can be easily installed into a project using Visual Studio, Rider, the .NET CLI, Paket or VS Code. One thing to note: since it is still in preview, we’ll have to instruct NuGet to work with the prerelease version:

Install-Package YouTrackSharp -IncludePrerelease

Once that is done, we can start working with it. To communicate with a YouTrack server instance, we’ll need a connection. It is recommended to always use permanent tokens to authenticate against YouTrack, using the BearerTokenConnection class. For YouTrack instances that do not have token support, UsernamePasswordConnection can be used.

var connection = new BearerTokenConnection(
    "https://example.myjetbrains.com/youtrack/", "perm:abcdefghijklmn");

Once we have a connection instance, we can start working with various services that are available through extension methods on our connection. For example if we want to dump all issues with their id, summary and current state, we can do so through the IssuesService:

var issuesService = connection.CreateIssuesService();
var issues = await issuesService.GetIssuesInProject("PROJ", take: 250);

foreach (var issue in issues)
{
    Console.WriteLine("{0} {1} - State: {2}",
        issue.Id,
        issue.Summary,
        issue.GetField("State")?.AsString());
}

One thing to note here is that some fields are available as a direct property on the Issue, like Id and Summary, while others are available using the GetField() method. Since not all projects have the same fields, these project-specific fields are available using GetField() and SetField(). An added benefit of using the GetField() method is that it allows returning the value AsString(), AsDateTime(), AsCollection() or AsInt32(). Prefer working with dynamic? That’s fine, too, but keep in mind you’ll have to cast the correct types manually then.

var dynamicIssue = issue.AsDynamic();

Console.Write("Issue type for {0} is: {1}",
    dynamicIssue.Id, dynamicIssue.Type[0]);

One more example: creating an issue, including setting the Priority field using dynamic:

dynamic issue = new Issue
{
    Summary = "I have issues!",
    Description = "Here's one more."
};

issue.Priority = "High";

await issuesService.CreateIssue("PROJ", issue);

Maybe one more? What about time tracking for an issue:

var timeTrackingService = connection.CreateTimeTrackingService();

await timeTrackingService.CreateWorkItemForIssue("PROJ-123",
    new WorkItem(DateTime.UtcNow, TimeSpan.FromHours(2), "Writing blog post"));

Available REST API’s

YouTrackSharp provides several services we can work with:

• User-related methods through UserService
• Projects-related methods through ProjectsService
• Issues-related methods through IssuesService
• Time-tracking-related methods through TimeTrackingService

Next to these, we have also added the various color indices available in YouTrack. We can use the ColorIndices class which maps the index to a foreground and background color, or use the (hex) colors exposed on the field directly:

var priorityField = issue.GetField("Priority");

Console.WriteLine("Priority: {0} (foreground {1}, background {2})",
    priorityField.AsString(),
    priorityField.Color.Foreground,
    priorityField.Color.Background);

What about other languages?

While YouTrackSharp focuses on the various .NET languages like C#, VB.NET and F#, there are YouTrack API wrappers for languages as well. A quick search on libraries.io shows Java and Kotlin, PHP, JavaScript, Python and Ruby.

Give the new YouTrackSharp a try, and let us know how it goes! If you feel like contributing, feel free to tackle one of the UpForGrabs issues and help make YouTrackSharp better!

Issue trackers are designed to help you manage issues faster and make your work more productive. But sometimes, you spend more time looking for important issues than actually working on them.
Today I will tell you about the most productive ways to track your issues in YouTrack.

1 — Build a Personal Board

If you find it hard to track your issues on an Agile Board that you use together with your team, you can create a personal board with your own settings to track only the tasks that are assigned to you.
To create such a board, use a personal board template that recognizes all of the projects where you are a team member and has a query to filter cards on the board and show only issues that are assigned to you.

You always have the option to modify settings based on your own requirements. For example, to separate important and less important issues, you can use swimlanes based on the value in the Priority field. This helps you see the prioritization of the tasks and not miss anything important.

If you work on several projects, the most convenient way to track your issues is to enable the option to identify swimlanes by project.

2 — Set up Notifications with Tags

Notifications are an important part of managing your issues. Getting the right notification at the right time helps you stay up to date and know exactly when you need to jump in and take action.
The default notification scheme sends updates for several triggers: when you are an assignee, a watcher, you are mentioned in a comment, or you’ve added a comment to or voted for an issue. Basically, you get notified for major issue changes. But what about the cases when you want to get notified for specific events?

First of all, you can subscribe to tags. For example, you want to track issues that are related to the 2017.3 release. Create a tag 2017.3 release, apply a custom notification scheme and tag the issues you want to include in 2017.3 release. If you only want to get notified when issues are fixed, simply select the Resolved event.

Now you won’t miss anything!

3 — Get Updates for Saved Searches

Ever want to get notified about the issues that match specific criteria? You can do it in YouTrack! Simply create a search query, save it, and subscribe to it. Here is an example.
At JetBrains we usually attend conferences all over the world. As a PMM of YouTrack, I don’t want to miss any conferences that are related to my product. I’ve created a query project: show #unresolved related project: youtrack and subscribed to it, so now I get notified when any issue that matches the query is created or updated.

Thanks to a variety of notification settings, you won’t miss what’s important — even if the issue is not assigned to you.

4 — Track Deadlines

Deadlines are usually much closer than they appear. It’s really important that you don’t forget about major issues, especially when someone depends on them being fixed.

By default, YouTrack comes with a Due Date workflow. When it’s attached to your project, the assignee (or in case the issue doesn’t have an assignee, the team lead) gets notified when the issue is overdue.

If you want to get notified in advance, you can either create a new workflow or add a new rule to the current workflow. For example, I want to get an email two days before the deadline.
Here are some steps on how to do it:
1. Open the Due Date workflow in the workflows list.
2. Add a new on-scheduled rule.
3. The right way is to write the rule from scratch. But there is a trick. You can copy and paste the notify-assignee-on-overdue rule and change return ctx.issue.fields.DueDate < Date.now(); to return ctx.issue.fields.DueDate < Date.now() – 2 * 24 * 60 * 60 * 1000;
While you’re editing the workflow rule, update the subject line of the email message as well. Here is how the new rule looks like.

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

exports.rule = entities.Issue.onSchedule({
  title: workflow.i18n('Notify assignee about overdue issues'),
  search: '#Unresolved has: {Due Date}',
  cron: '0 30 15 * * ?',
  guard: function(ctx) {
    return ctx.issue.fields.DueDate < Date.now() - 2 * 24 * 60 * 60 * 1000;
  },
  action: function(ctx) {
    var issue = ctx.issue;
    var userToNotify = issue.fields.Assignee;
    if (!userToNotify) {
      userToNotify = issue.project.leader;
    }
    var formattedDate = dateTime.format(issue.fields.DueDate);
    var notificationText = 'Deadline is on ' + formattedDate + ': ' + issue.id + ' ' + issue.summary;
    userToNotify.notify(workflow.i18n('[YouTrack, deadline is coming]'), notificationText);
   },
  requirements: {
    DueDate: {
      type: entities.Field.dateType,
      name: "Due Date"
    },
    Assignee: {
      type: entities.User.fieldType
    }
  }
});

4. Attach the new rule to your project and you are good to go.
Please note that you need project administrator permissions to manage workflows.

5 — Pin Tags and Saved Searches

Another way to easily filter your issues is to pin tags and saved searches to the sidebar. Let’s say you always want to track the list of unresolved issues that are assigned to you sorted by due date. Simply create a search query #me sort by: due date #unresolved, save it, and pin to the sidebar. Now you have an easy way to get to your issues!

We hope that these tips improve your issue tracking experience. Do you have your own tricks for managing issues? Share your tips and feedback in the comment section below!

Sincerely yours,
the JetBrains YouTrack team

The previous article in our Make it Workflow series showed you how to set up complex visibility restrictions for issues. We limited the ability to read issues to specific groups of people and restricted read access for different sets of users for issues in a single project.

In this post, we describe how to block unwanted changes to fields in an issue. We’ll continue to support the business case that we described in the previous article. We’re working with an accounting department whose members process payment requests. These users belong to a group of Executors. Payment requests are submitted by other members of the organization as issues in YouTrack. These users are our Requesters group.

Building on the previous business case, let’s assume that you want to limit who can update the values in specific custom fields. Some of the fields store information that is provided by the Requesters. For example, the purpose of the payment. Other fields store information that is entered by the Executors. For example, the transaction ID from the bank. Requesters should not be able to modify the values in these fields.

Workflow-free Mode

In this case, private custom fields come to the rescue. Custom fields in YouTrack have a privacy setting. An administrator can update the properties for any custom field and make it private. The key icon in the list of custom fields indicates that the field is private.

For private fields, an extra set of permissions determines whether a user can read or update the field. If the field is private, users must have permission to Read Issue Private Fields and Update Issue Private Fields in the project, respectively. For public fields, users only need to have Read Issue and Update Issue permissions. Reporters only need to have the Create Issue permission to read public fields in the issues that they report themselves.

In the setup from the previous article, Requesters are granted the default Reporter role, which does not contain permission to Read Issue Private Fields or Update Issue Private Fields. As soon as you make a field private, Requesters are no longer able to view this field in any issue — even the issues that they created. Only Viewers and Executors can see and update its value. (For a complete description of these groups and their roles, refer to the previous article).

If your requirements allow it, you might choose to let your Requesters see the values that are stored in private fields but not update them. In this case, add the Read Issue Private Fields permission to the role that is assigned to the Requesters group in your project. This lets Requesters monitor the progress of their requests without letting them change the issue state, priority, or other private fields.

The Workflow-enhanced Approach

As in our previous article, you can solve simple business cases without scripting. However, this solution has a few limitations. Users can either read and/or update all private custom fields in a project or none of them. There is only black and white, no grey.

What happens when your company doesn’t want the accounting team to accept payment requests without manager approval? To support this restriction, you need two custom fields:

• Authorization status – this field stores two enumerated values: Required (the default value) and Authorized.
• Authorizer – this field stores a user type. It contains a list of managers who can approve payment requests.

You want to apply a restriction to the Authorization status field so that it can only be changed to Authorized by the user who is selected as the Authorizer. This means that:

• Authorizer must have permission to read the issue.
• Authorizer must have permission to update the Authorization status field.
• No other user should be able to update the value for the Authorization status field.

To support the first and the second points, use the workflow-enhanced approach that was described in the previous article together with the rule that adds the Authorizer to the visibility list. You should also perform the following setup:

• Create a separate Authorizers group and add all of the managers as members.
• Grant the same level of access that is available to members of the Requesters group.
• Set this group as the source for values in the Authorizer field.

The third point requires an additional workflow rule. This rule is triggered when someone tries to set the Authorization status to Authorized. It verifies that the current user is the same person who is set as the Authorizer.

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

exports.rule = entities.Issue.onChange({
  title: 'Only Authorizers can update value for Authorization status field',
  guard: function(ctx) {
    return ctx.issue.fields.becomes(ctx.AuthStatus,
                                    ctx.AuthStatus.Authorized);
  },
  action: function(ctx) {
    var authBy = ctx.issue.fields.AuthBy;
    workflow.check(authBy && authBy.login === ctx.currentUser.login,
                  'Only Authorizers can update this field!');
  },
  requirements: {
    AuthBy: {
      type: entities.User.fieldType,
      name: 'Authorizer'
    },
    AuthStatus: {
      type: entities.EnumField.fieldType,
      name: 'Authorization status',
      Authorized: {}
    }
  }
});

This limitation is very strict. However, you can write the rule differently to make the policy more lenient. The rule that follows lets members of the accounting team choose another value for the Authorizer field, even after the Authorization status field has been set to Authorized. When a new authorizer is selected, the value of the Authorization status field is switched back to Required. This lets you handle cases where, for example, an authorizer leaves the company or is no longer the manager for the person who submitted the payment request.

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

exports.rule = entities.Issue.onChange({
  title: 'Only Executors can change Authorizer in authorized requests',
  guard: function(ctx) {
    var fs = ctx.issue.fields;
    return fs.isChanged(ctx.AuthBy) &&
           fs.AuthStatus.name === ctx.AuthStatus.Authorized.name;
  },
  action: function(ctx) {
    workflow.check(ctx.currentUser.isInGroup(ctx.executors.name),
                   'Only Executors can change the Authorizer ' +
                   'after the request has been authorized!');
    ctx.issue.fields.AuthStatus = ctx.AuthStatus.Required;
  },
  requirements: {
    AuthBy: {
      type: entities.User.fieldType,
      name: 'Authorizer'
    },
    AuthStatus: {
      type: entities.EnumField.fieldType,
      name: 'Authorization status',
      Authorized: {},
      Required: {}
    },
    executors: {
      type: entities.UserGroup
    }
  }
});

The previous restrictions determine which users can update different fields. You can also add restrictions that are based on field and value combinations. For example, here’s a rule that won’t let anyone change the value for the State field to Paid unless the Authorization status is Authorized.

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

exports.rule = entities.Issue.onChange({
  title: 'Request must be authorized to be marked as paid',
  guard: function(ctx) {
    return ctx.issue.fields.becomes(ctx.State, ctx.State.Paid);
  },
  action: function(ctx) {
    var fs = ctx.issue.fields;
    workflow.check(fs.AuthStatus &&
                   fs.AuthStatus.name === ctx.AuthStatus.Authorized.name,
                   'Only authorized requests can be marked as paid!');
  },
  requirements: {
    AuthStatus: {
      type: entities.EnumField.fieldType,
      name: 'Authorization status',
      Authorized: {},
    },
    State: {
      type: entities.State.fieldType,
      Paid: {}
    }
  }
});

Here’s another variant. When the State has been set to Paid, the value that is stored in the Amount field cannot be modified.

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

exports.rule = entities.Issue.onChange({
  title: 'Block changes to Amount for paid requests',
  guard: function(ctx) {
    return ctx.issue.fields.isChanged(ctx.Amount);
  },
  action: function(ctx) {
    var fs = ctx.issue.fields;
    workflow.check(fs.State && fs.State.name !== ctx.State.Paid.name,
                   'You cannot change the Amount for paid requests!');
  },
  requirements: {
    Amount: {
      type: entities.Field.floatType
    },
    State: {
      type: entities.State.fieldType,
      Paid: {}
    }
  }
});

We hope that these examples help you understand the basic concept. You can support a wide variety of update restrictions with the help of workflows. The workflows described in this article are specific to the business case for our accounting team but can be adapted to support any process. Here are a few ways you can extend this scheme:

• Prohibit anyone but members of the QA team from changing the state for reported bugs from Fixed to Verified.
• Mark an issue as Fixed only when the Spent time field is not empty.
• Block users from changing the value for the Assignee field once an issue is resolved.

How and when you apply update restrictions is all up to you and your imagination.

In our next post, we show you how to streamline the issue creation process with workflows. If you’re hungry for more and can’t wait a week, here are a few resources to tide you over:

• Watch our YouTrack Custom Workflow Repository in Git. We’ll be uploading all of the workflows that we introduce in this series.
• Join our YouTrack Workflow Community in Slack. Interact directly with the YouTrack development team and see how other users support their business logic with workflows.

When we first introduced YouTrack workflows in JavaScript, we also released a built-in editor for writing workflow rules and scripts. While many users enjoy the convenience of writing workflows directly in YouTrack, it does have its limitations.

If you would rather write code in your favorite IDE, you can turn that frown upside-down right now. We’ve tapped into the power of the npm registry service* to let you manage workflows just as you would any other codebase. With the utilities that we have published to this service, you can enjoy the following advantages:

• Write workflows without leaving your development environment. Enjoy full-featured code completion and keyboard support.
• Edit and refine multiple scripts simultaneously.
• Make iterative offline improvements and deploy updates only when your code is tried and tested.

In this article, we show you how to work with the package manager and update workflows using your own software development tools. With each step, we provide an increasing level of functionality and complexity. This lets you build up your toolkit bit by bit and extend the capabilities of your platform at your own pace.

These instructions are not specific to any single platform. You should be able to configure any environment that supports JavaScript to write and manage workflow scripts for YouTrack.

TL;DR: If you’re already familiar with npm, our custom workflow repository is already set up to support YouTrack workflow development in an IDE. Follow the setup instructions in the README and use our

package.json

1 — Lay the Groundwork

Follow the instructions in this section to enable basic support for YouTrack workflows in your IDE.

Install Node.js**

We’ve published two utility packages for workflows to the npm public registry. To work with these packages, you need to install and run Node.js. We recommend that you use Node.js version 8.9.1 LTS or later.

When you install Node.js, the npm package manager is also installed automatically.

Build a package.json File

Node.js uses

package.json

package.json

1. In your command-line interface (CLI), enter

   npm init

   .
   This starts a utility that helps you build the JSON file.
2. For each field in the file, specify a new value or press Enter to accept the suggested value. Once you have specified values for all of the fields, the JSON is displayed in the CLI.
3. Confirm the creation of the file by accepting the prompt

   Is this ok? (yes)

   . The

   package.json

    file is added to the current project.

Install the YouTrack Scripting API Package

The first package you want to install contains the complete YouTrack workflow API. When you plug this package into your code editor, your code-completion tools suggest valid functions, methods, and properties for all of the entities that are available in the YouTrack workflow API.

Enter the following command to install the package in your

devDependencies

npm install --save-dev @jetbrains/youtrack-scripting-api

Install the YouTrack Scripting Package

The second package you can install contains utility scripts. These scripts help you manage YouTrack workflows when you work in an external code editor.

Enter the following command to install this package in your

devDependencies

npm install --save-dev @jetbrains/youtrack-scripting

Now, you have a few predefined scripts that you can enter in a command-line interface. These scripts support the following commands:

• list

   — Lists all of the workflows that are available in your YouTrack installation.

• download

   — Downloads the specified workflow from your YouTrack installation.

• upload

   — Uploads the workflow from the specified directory to your YouTrack installation.

For a complete description of each command and its parameters, refer to the YouTrack documentation.

As long as your installation doesn’t use a certificate that is issued by your own certificate authority (CA) or is self-signed, you can establish a connection using a personal permanent token. You can generate your own permanent tokens on the Authentication tab of your Hub profile. For instructions, refer to the YouTrack documentation.

If you are using a certificate that is not issued by a known CA, you need to use specific variables in your Node.js environment to enable a connection between your IDE and the YouTrack installation. Follow the special instructions in the last section of this article.

If you have just a few custom workflows and don’t need to update them very frequently, you might get by with the basic scripting package. For regular updates, the need to specify a host and token with each request is a bit unwieldy. Follow the instructions in the next section to simplify this process and use these commands with fluidity.

2 — Flip the Script

You can streamline the commands that are supported by writing your own script. This script extracts the variables that you use to establish a connection to your YouTrack installation and stores them in your local configuration.

Save Your Token

The first parameter that you want to extract and store locally is the permanent token that you use for authentication. To keep this token safe, you want to store it in your personal configuration file.

To add your permanent token to your per-user config file:

1. Follow these instructions to generate a permanent token. When you generate the token, add the YouTrack service to the Scope input field.
2. Copy the token to your clipboard.
3. Switch to the command-line interface in your IDE and add the token to your per-user config file with the following command:
   

   npm config set token_prod <token>

   
   Replace <token> with the permanent token from your clipboard.
   Of course, you can name your variables as you like. But as you continue with this guide, you’ll see that these naming conventions follow a pattern.
4. Verify that the token has been added to your configuration with this command:
   

   npm config list --json

Save Your Host

Next, you want to save the address of your YouTrack installation that you reference as the

host

To store this variable:

1. Enter the following command in your CLI:
   

   npm config set host_prod <address>

   
   Replace <address> with the base URL of your YouTrack installation. For an InCloud instance, be sure to include the trailing

   /youtrack

   .  
2. Verify that the variable has been added to your configuration with this command:
   

   npm config list --json

Go Cross-platform

This next step is optional if you’re on a Linux or *nix-based operating system. It’s also not entirely required for Windows users who know how to set their environment variables correctly, but you’ll need to adapt all of the scripts accordingly. For best results, we recommend that you follow these instructions anyway. As you delve deeper into this guide, you’ll see why.

References for environment variables vary by operating system. To ensure that your scripts work in any environment, you can install a package that lets you set and use environment variables across platforms.

Our preferred package is cross-env. It automatically converts each variable to use the correct syntax for your operating system at runtime.

To install this package in your

devDependencies

npm install --save-dev cross-env

Now you can set all of your variables as if you were running on a POSIX system. If you open your

package.json

devDependencies

Customize Your Commands

The last step is to write a script that references these parameters. You can add these scripts directly to the scripts field in your

package.json

{
  "name": "myyoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for my YouTrack installation",
  "scripts": {
    "list-prod": "cross-env youtrack-workflow list --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env youtrack-workflow download --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env youtrack-workflow upload --host=$npm_config_host_prod --token=$npm_config_token_prod"
  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

At this point, you can run all of the commands that are supported by the

youtrack-scripting

host

token

• npm run list-prod

• npm run download-prod -- <workflow name>

• npm run upload-prod -- <workflow name>

The basic process is as follows:

1. Use the download command to copy workflows from your installation to your development environment.
2. Make your changes.
3. Use the upload command to update the workflow in YouTrack.

Keep in mind that you’re still pushing updates straight to your production environment. For many developers, it’s like playing with fire. If you’d like to work in a more controlled manner, follow the instructions in the next section to play it safe.

3 — Connect to a Test Environment

One of the major advantages of using an external editor to write workflows is that you can connect to multiple YouTrack installations. As with any code development project, you should first upload and test your changes in a sandbox environment. Only when you’re sure it’s working as intended should you deploy the code in production.

We recommend that you use one of the following options to test your workflows.

Build Your Own Sandbox

Our free 10-user plan is a great solution for testing workflows.

• If your production environment is a YouTrack Standalone installation, you can download and install a local copy and use the free plan. You can update your local installation to the same version as your production environment to ensure your workflows behave as expected.
• If you use YouTrack InCloud, you can sign up for a test instance and switch to the free 10-user plan at any time. Our hosted servers are upgraded to the latest version of YouTrack automatically.

Because of license restrictions for the free plan, you can’t test workflows that set or change the visibility for issues and comments.

Play in the Sand at a Public Beach

We have set up a YouTrack InCloud test instance for testing workflows. Anyone can register to access this instance and use it as a sandbox. When you register, you are given the Global Project Admin role and can test custom workflows in any project.

This instance is not subject to any license restrictions and can be used to test workflows that manage issue and comment visibility.

Update Your Development Environment

Once you have set up an account in a test environment, you can add the variables from this installation to your configuration file and update your script. Follow these steps:

1. Store the permanent token from your test environment in your configuration file with the following command:
   

   npm config set token_test

2. Store the hostname for your test environment with the following command:
   

   npm config set host_test

3. Update your

   package.json

    file to include scripts that let you manage workflows in your test environment. Use the following example as a guide.

{
  "name": "myyoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for my YouTrack installation",
  "scripts": {
    "list-prod": "cross-env youtrack-workflow list --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env youtrack-workflow download --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env youtrack-workflow upload --host=$npm_config_host_prod --token=$npm_config_token_prod",

    "list-test": "cross-env youtrack-workflow list --host=$npm_config_host_test --token=$npm_config_token_test",
    "download-test": "cross-env youtrack-workflow download --host=$npm_config_host_test --token=$npm_config_token_test",
    "upload-test": "cross-env youtrack-workflow upload --host=$npm_config_host_test --token=$npm_config_token_test"
  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Now you can play with fire and not get burned! Your typical process would look something like this:

1. Download a workflow from your production environment with the command:
   

   npm run download-prod -- <workflow name>

2. Update the workflow in your IDE.
3. Upload the modified workflow to your test environment with the command:
   

   npm run upload-test -- <workflow name>

4. Test the workflow in your YouTrack sandbox environment.
5. Repeat steps 2 through 4 until your workflow behaves as expected.
6. Upload the final version of your workflow to your production environment with the command:
   

   npm run upload-prod -- <workflow name>

If you are the only person who is responsible for the customization of your YouTrack installation, you might choose to end your journey here. With this setup, you can safely update your workflows while working exclusively in your favorite development environment.

When there are other developers in your organization who write scripts for their own projects, you might want to get everyone to work together. Follow the instructions in the next section and share this setup with your team.

4 — Be a Team Player

One of the biggest advantages of the setup in this section is that supports collaboration. With a few modifications, you can build a platform that other developers can use to manage workflows in your YouTrack installation. As this setup is not specific to any single environment, these developers can be working with any IDE that supports JavaScript in any operating system.

Update Your Script

The first thing you can do is modify your

package.json

To streamline the setup for other users, you can pull these variables into the

package.json

{
  "name": "ouryoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for our YouTrack installation",
  "config": {
    "host_prod": "https://youtrack.company.com",
    "host_test": "https://workflow.myjetbrains.com/youtrack"
  },
  "scripts": {
    "list-prod": "cross-env youtrack-workflow list --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env youtrack-workflow download --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env youtrack-workflow upload --host=$npm_package_config_host_prod --token=$npm_config_token_prod",

    "list-test": "cross-env youtrack-workflow list --host=$npm_package_config_host_test --token=$npm_config_token_test",
    "download-test": "cross-env youtrack-workflow download --host=$npm_package_config_host_test --token=$npm_config_token_test",
    "upload-test": "cross-env youtrack-workflow upload --host=$npm_package_config_host_test --token=$npm_config_token_test"
  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Notice how we added these variables to the

config

package.json

$npm_package_config

$npm_config

Go Repo

Repositories are great places for storing collaborative work. Why not do the same with your workflow code? Uploading your workflow project to a repository has the following advantages:

• You provide a centralized location where everyone can access your project files, including the

  package.json

   file that supports your scripts.
• Your repository supports version control. You can apply iterative updates to your workflow scripts. If you encounter problems with an updated workflow in production, you can always roll back to the last stable version.
• Multiple users can work on the same script without having their respective changes overwritten.
• You can use branching and pull requests to implement formal development and testing processes.

When you upload your project to a repository, other users can follow these steps and start coding:

1. Connect to the repository and download a local copy of the project. Be sure to include the

   package.json

    in your project files.
2. Generate personal permanent tokens for the YouTrack installations that are supported in each script and save them as variables in their personal configuration file.

Now each developer should be able to perform the following actions:

• Download files from the repository.
• Update workflow scripts in their local environment.
• Upload and test their updates in the sandbox until they behave as expected.
• Upload the revised scripts to the production environment.
• Push their changes back to the repository, updating the version of the revised script.

For a real-life example, check out our YouTrack Custom Workflow Repository. Here, we upload workflows that support a range of use cases that are not covered by the default workflows in YouTrack. Everyone is welcome to download scripts from the repository and adapt them to suit specific business cases. If you have a script that you’d like to share with the community, submit a pull request!

Special Instructions for SSL Certificates

If your YouTrack domain uses an SSL certificate that is issued by a known certificate authority, you can establish a connection using just your personal permanent token. Your certificate is already included in CA certificate store that is built into Node.js. For certificates that are issued by a CA that is not recognized automatically or is self-signed, you need to modify the environment variables in Node.js to recognize or ignore your certificate.

Private Certificate Authorities

If your certificate is issued by a CA that is not recognized automatically, you need to add your certificate to the list of certificates that are recognized by Node.js.

To add your certificate, use the environmental variable

NODE_EXTRA_CA_CERTS=file

To work with a private certificate:

1. Open your YouTrack installation in a web browser.
2. User your browser tools to export the certificate. Specific instructions vary for different browsers.
3. Store the certificate file in a directory that is accessible from your development environment.
4. Set the reference to the directory in your private configuration. For example:
   

   npm config set cert_prod <path>

   
   Replace <path> with the full path to the certificate file.
5. Modify your scripts to reference the extra CA certificate. Use the following example as a guide.

{
  "name": "ouryoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for our YouTrack installation",
  "config": {
    "host_prod": "https://youtrack.company.com",
  },
  "scripts": {
    "list-prod": "cross-env NODE_EXTRA_CA_CERTS=\"$npm_config_cert_prod\" youtrack-workflow list --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env NODE_EXTRA_CA_CERTS=\"$npm_config_cert_prod\" youtrack-workflow download --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env NODE_EXTRA_CA_CERTS=\"$npm_config_cert_prod\" youtrack-workflow upload --host=$npm_package_config_host_prod --token=$npm_config_token_prod",

  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Self-signed Certificates

If you work in a closed environment and use a self-signed certificate, you can disable the secure connection over TLS with the environmental variable

NODE_TLS_REJECT_UNAUTHORIZED=0

The following example shows you how to connect to a local machine with the TLS connection disabled.

{
  "name": "ouryoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for our YouTrack installation",
  "config": {
    "host_local": "http://localhost:8081/",
  },
  "scripts": {
    "list-local": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 youtrack-workflow list --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "download-local": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 youtrack-workflow download --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "upload-local": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 youtrack-workflow upload --host=$npm_package_config_host_prod --token=$npm_config_token_prod",

  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Even though this type of workaround is often done in a development environment, it is not secure. If you are not aware of the potential pitfalls, avoid this practice. Never use this variable to connect to your production environment.

*npm is a trademark of npm, Inc.
**Node.js is a trademark of Joyent, Inc. and is used with its permission. We are not endorsed by or affiliated with Joyent.

In previous installments, we discussed how to restrict issue visibility and prevent unwanted updates. We still haven’t covered what is possibly the most important aspect of the issue life cycle — its birth. In this article, we describe how you, your team, and your customers can create issues that contain the most accurate and detailed information from day one.

Workflow-free Mode

As with other issue-related operations, you can set up a basic issue reporting process without workflows. It all starts with the configuration of the custom fields in your projects. For most custom fields, you can choose whether the field can or cannot be empty. So, how does this affect issue reporting?

If the field can be empty, you can report an issue without setting any value in this field. In the default YouTrack project template, fields like Assignee and Fix versions can be empty. If you don’t specify a value for the field, the empty value (like Unassigned or Unscheduled) is used instead. You can set the value or clear it at any time.

If the field is cannot be empty, you must assign a default value in the configuration. This value is automatically assigned to each issue that is reported in the project. Moreover, you cannot clear the value of the field, only replace it with another value. In the default YouTrack project template, fields like Priority and State cannot be empty and have default values of Normal and Submitted, respectively.

By defining whether fields can or cannot be empty and setting default values accordingly, you can effectively set the starting point for new issues in your project.

The Workflow-enhanced Approach

While field configuration options are useful, they have some limitations. There are a number of use cases that are not addressed by empty values and default values:

• You want to require a value in the Due date field. Fields that store simple values (like string, integer, float, date, or period) cannot store a default value. In new issues, these fields are always empty.
• You want reporters to set the value in a specific field without suggesting a default. For example, you want to assign each task to a Subsystem, but there isn’t a logical value that you would suggest as a default.
• You want to set default values dynamically. For example, you always want the Due date to be two weeks from today.
• You want to provide your customers with a template for reporting issues. The template contains predefined values for custom fields and a default description.
• As an extension of the previous case, you want to provide your customers with a collection of templates for issues in the same project. Each template varies based on the value that is selected for a custom field value (like Type) or can be applied to a draft using menu actions.

Support for these use cases can be implemented with various workflow rules, some of which are already available as default workflows in YouTrack.

Mandatory fields

The first case is about making simple fields mandatory for new issues. This case is addressed by the issue.fields.required(field, message) method. This method checks if the field is empty. If it is, the current changes are rolled back and a message is shown to the reporter. Check out the ‘Require due dates for submitted issues’ rule from the ‘Due Date’ workflow:

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

exports.rule = entities.Issue.onChange({
  title: workflow.i18n('Require due dates for submitted issues'),
  guard: function(ctx) {
    return ctx.issue.becomesReported;
  },
  action: function(ctx) {
    ctx.issue.fields.required(ctx.DueDate,
      workflow.i18n('You must set the Due date!'));
  },
  requirements: {
    DueDate: {
      type: entities.Field.dateType,
      name: "Due Date"
    }
  }
});

Note the guard in this rule. This guard ensures that the check is only initiated once, after the reporter has filled in the issue content and attempts to create the issue.

If you want to make it so the value for this field cannot be removed for submitted issues, update the guard as follows:

guard: function(ctx) {
    return ctx.issue.isReported;
  }

Several of the workflows described in this article use the workflow.i18n(...) method. This method is used to localize default workflows. When you write your own workflows, you always know the language of your YouTrack installation, so you don’t need to use this method. If you want to edit the messages in default workflows, remove this method and replace its usage with a plain string of message text.

The second case listed above is solved with the same kind of rule. Simply take a custom field that can be empty and check whether it is empty or not when a new issue is reported. The issue.fields.required(field, message) method works the same for all types of custom fields.

Dynamic defaults

You can use workflows to calculate the default value for a field automatically. For example, the following rule sets the value for the Due date field to a date that is two weeks from the current date:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

var WEEK_IN_MS = 7 * 24 * 60 * 60 * 1000;

exports.rule = entities.Issue.onChange({
  title: 'Set Due Date on issue submitting',
  guard: function(ctx) {
    return ctx.issue.becomesReported && !ctx.issue.fields.DueDate;
  },
  action: function(ctx) {
    ctx.issue.fields.DueDate = Date.now() + 2 * WEEK_IN_MS;
  },
  requirements: {
    DueDate: {
      type: entities.Field.dateType,
      name: 'Due Date'
    }
  }
});

Issue templates

Another popular case that is supported by one of the default workflows adds a default description to new issues. Here is how it is implemented in our ‘Default Description’ workflow:

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

exports.rule = entities.Issue.onChange({
  title: workflow.i18n('Insert default description template for external users'),
  guard: function(ctx) {
    var issue = ctx.issue;
    return !issue.isReported && !issue.becomesReported && !issue.description;
  },
  action: function(ctx) {
    ctx.issue.description =
       workflow.i18n('What steps will reproduce the problem?') +
      "\n1.\n2.\n3.\n\n" +
      workflow.i18n("What is the expected result?") +
      "\n\n" +
      workflow.i18n("What happens instead?") +
      "\n\n" +
      workflow.i18n("Please provide any additional information below.") +
      "\n" +
      workflow.i18n("Attach a screenshot if possible") +
      "\n";
  },
  requirements: {}
});

This workflow rule sets the default description for each new issue. That this rule is triggered as soon as the reporter edits any value in the new issue, for example, typing a summary or changing the project. Due to technical limitations, this rule can’t be applied at the moment when the New Issue page opens.

You can extend this workflow to let reporters choose between different templates without filling in a lot of data manually. For example, you can use different templates for feature requests and bug reports:

• For bug reports, you require the steps to reproduce (STR) in the description.
• For features, you require the suggestion and motivation (what and why). You also want to set the value for the Fix versions field to Backlog.

For this case, the easiest approach consists of two parts:

• Make the Type field empty by default.
• Force the reporter to select the Type at the very beginning of creating an issue:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.onChange({
  title: 'Choose Type when new issue is created',
  guard: function(ctx) {
    var issue = ctx.issue;
    return !issue.isReported && !issue.becomesReported &&
      !issue.fields.Type && !issue.isChanged('project');
  },
  action: function(ctx) {
    ctx.issue.fields.required(ctx.Type, 'Please choose issue Type before editing!');
  },
  requirements: {
    Type: {
      type: entities.EnumField.fieldType
    }
  }
});

• Add a rule which sets the values based on the selection in the Type field:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.onChange({
  title: 'Set issue template based on Type',
  guard: function(ctx) {
    var issue = ctx.issue;
    return !issue.isReported && !issue.becomesReported && !issue.description &&
      issue.fields.isChanged(ctx.Type) && !issue.fields.oldValue(ctx.Type);
  },
  action: function(ctx) {
    var issue = ctx.issue;

    var typeIs = function(value) {
      return issue.fields.Type.name === value.name;
    };

    if (typeIs(ctx.Type.Bug)) {
      issue.description =
         'What steps will reproduce the problem?' +
         '\n1.\n2.\n3.\n\n' +
         'What is the expected result?\n\n' +
         'What happens instead?\n';
    } else if (typeIs(ctx.Type.Feature)) {
      issue.description =
         'What should be implemented?\n\n' +
         'Why is this functionality required?\n';
      issue.fields.FixVersions.add(ctx.FixVersions.Backlog);
    }
  },
  requirements: {
    Type: {
      type: entities.EnumField.fieldType,
      Bug: {},
      Feature: {}
    },
    FixVersions: {
      type: entities.ProjectVersion.fieldType,
      multi: true,
      name: 'Fix versions',
      Backlog: {}
    }
  }
});

Another way to support this use case is to provide a list of templates in the form of actions. Action rules are a special type of workflow rule. Each action rule is associated with a command and an item in the list of actions that are shown in the Command Dialog drop-down menu. These rules are triggered when the user executes the command or clicks the corresponding item. For details, refer to the YouTrack documentation.

Here’s a sample action rule for the feature request template:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.action({
  title: 'Feature template',
  command: 'feature-template',
  guard: function(ctx) {
    var issue = ctx.issue;
    return !issue.isReported && !issue.becomesReported && !issue.description;
  },
  action: function(ctx) {
    var issue = ctx.issue;
    issue.description =
      'What should be implemented?\n\n' +
      'Why is this functionality required?\n';
    issue.fields.Type = ctx.Type.Feature;
    issue.fields.FixVersions.add(ctx.FixVersions.Backlog);
  },
  requirements: {
    Type: {
      type: entities.EnumField.fieldType,
      Feature: {}
    },
    FixVersions: {
      type: entities.ProjectVersion.fieldType,
      multi: true,
      name: 'Fix versions',
      Backlog: {}
    }
  }
});

To make reporters select a template, first check if the description is empty. If so, suggest that they choose a template from the menu.

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

exports.rule = entities.Issue.onChange({
  title: 'Choose a template when new issue is created',
  guard: function(ctx) {
    var issue = ctx.issue;
    return !issue.isReported && !issue.becomesReported && !issue.description;
  },
  action: function(ctx) {
    workflow.check(false, 'Please, choose one of templates in action menu!');
  },
  requirements: {
    Type: {
      type: entities.EnumField.fieldType
    }
  }
});

The field-based approach is better for simple cases like the one we’ve described here. When you have complex templates that are defined by a combination of field values, use the action-based approach.

We hope that this article helps you to understand how you can streamline issue reporting for every member of your team. In the next article, we describe how you can take the reporter out of the equation and completely automate issue creation. Stay tuned!

The guidelines in this series are just the tip of the workflow iceberg. There’s a lot more out there if you’re eager to learn more:

• Watch our YouTrack Custom Workflow Repository in Git. We are uploading all of the workflows that we introduce in this series.
• Join our YouTrack Workflow Community in Slack. Interact directly with the YouTrack development team and see how other users support their business logic with workflows.
• Read the YouTrack documentation. We’ve got a wide range of topics for everyone from beginners to seasoned experts.

Last week, we shared a few tips for streamlining issue reporting. The goal was to improve the simplicity and accuracy of issue creation for your team and for your customers.

In this article, we take it one step further. Imagine what happens when you need to create a standard set of issues on a regular basis. Who has the time or patience to spam the Create Issue button and set values for each field in every issue? If your answer is “not me”, read on to learn how to generate issues in YouTrack automatically.

If you have read previous articles in this series, you might expect to see the same structure that we’ve used so far: first, describe the workflow-free mode and then move on to the workflow-enhanced approach. When it comes to issue generation, YouTrack doesn’t provide a lot of workflow-free options.

• You can generate an issue template URL – this speeds up the process somewhat, but you need to define separate URLs for different issue types and it’s still a manual operation.
• There’s also the Clone Issue action in the issue toolbar, but this is actually implemented with a workflow. We’ll describe this option in more detail a bit later.

Instead, we’ll jump straight to the workflows. Here are a few scenarios where workflow-based issue generation comes in handy.

Generate Subtasks When a Parent Issue is Submitted

Imagine that you’re working with a development team that releases updates to a software product on a regular basis. Apart from implementing new features and fixing bugs, each release requires a standard set of tasks. For example:

• Distribute an updated version of the product.
• Update the documentation.
• Update the ‘What’s new’ page on the product website.
• Prepare and publish an article on the company blog.
• Send a newsletter to customers.
• Send a newsletter to resellers.
• And many more, depending on your product and your processes…

To save you and your colleagues a lot of time, write a workflow that generates a list of subtasks every time a ‘Release’ issue is created.

You need some criteria to distinguish release issues from other issues for your product. Otherwise, you end up generating subtasks for the wrong issues. There are a number of conditions you can set up, like using a separate project for release issues or adding a specific tag. In this example, we add Release to the set of values for the Type field and generate subtasks only when a new issue of this Type is created. The workflow rule looks like this:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.onChange({
  title: 'Release management',
  guard: function(ctx) {
    var issue = ctx.issue;
    return issue.becomesReported &&
      issue.fields.Type.name === ctx.Type.Release.name;
  },
  action: function(ctx) {
    var issue = ctx.issue;

    var createIssue = function(name, subsystem) {
      var newIssue = new entities.Issue(ctx.currentUser, issue.project,
        name + ' for ' + issue.summary);
      newIssue.fields.Subsystem = subsystem;
      newIssue.fields.Type = ctx.Type.Task;
      newIssue.links['subtask of'].add(issue);
    };

    createIssue('Update distribution', ctx.Subsystem.Distribution);
    createIssue('Update documentation', ctx.Subsystem.Documentation);
    createIssue('Update "What\'s new"', ctx.Subsystem.Website);
    createIssue('Blog post', ctx.Subsystem.Blog);
    createIssue('Newsletter for customers', ctx.Subsystem.Newsletters);
    createIssue('Newsletter for resellers', ctx.Subsystem.Newsletters);
  },
  requirements: {
    Type: {
      type: entities.EnumField.fieldType,
      Release: {},
      Task: {}
    },
    Subsystem: {
      type: entities.OwnedField.fieldType,
      Distribution: {},
      Documentation: {},
      Website: {},
      Blog: {},
      Newsletters: {}
    }
  }
});

Generate Subtasks When a Parent Issue is Updated

This case is similar to the previous one from a technical point of view but has a slightly different application.

Let’s look at the process for an operational team that organizes business trips to conferences and events for company employees. Line managers create issues in a special project. The project uses a multi-value Travelers field to store the names of the employees who participate in the event. The operational team prepares travel documents for each employee separately, so they want to have one issue per person.

You can support this case just as we did in the previous scenario by using the value for the Type field as the guard condition. Whenever a line manager submits an issue with multiple travelers, the operational team sets the type to Group Trip. This triggers a workflow that generates a subtask for each employee in the Travelers field and sets the type for each subtask to Individual Trip. We won’t add the rule here, as it can be supported by making minor modifications to the previous example.

However, sometimes employees decide that they want to go to the conference after the Group Trip issue is created. For this case, you need an additional rule that creates a subtask for new travelers on the fly:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.onChange({
  title: 'Create a subtask for each new traveler',
  guard: function(ctx) {
    var fs = ctx.issue.fields;
    return ctx.issue.isReported &&
      fs.Type && fs.Type.name === ctx.Type.GroupTrip.name &&
      fs.Travelers.added.isNotEmpty();
  },
  action: function(ctx) {
    var issue = ctx.issue;

    var createIssue = function(traveler) {
      var newIssue = new entities.Issue(ctx.currentUser, issue.project,
        traveler.fullName + ' at ' + issue.fields.Destination);
      newIssue.fields.Type = ctx.Type.IndTrip;
      newIssue.links['subtask of'].add(issue);
    };

    issue.fields.Travelers.added.forEach(createIssue);
  },
  requirements: {
    Destination: {
      type: entities.Field.stringType
    },
    Type: {
      type: entities.EnumField.fieldType,
      GroupTrip: {
        name: 'Group Trip'
      },
      IndTrip: {
        name: 'Individual Trip'
      }
    },
    Travelers: {
      type: entities.User.fieldType,
      multi: true
    }
  }
});

Generate Issues on Demand

There are several situations where you want to generate issues, but you can’t use a combination of field values as the initial condition. Here, the initial condition is inside the mind of the YouTrack user.

The most obvious example is the Clone Issue workflow. This workflow lets you make a copy of an existing request whenever you need it. This workflow uses an ‘action’ rule. This type of rule is triggered by a user-defined command, either by selecting this action from the Command Dialog menu or by executing this command in the Apply Command dialog.

Going back to the previous example, let’s say that you want to provide employees with some swag to give to partners or hand out at the conference booth. In this case, you can write an action rule that generates a subtask for the group trip. The workflow takes the value from the Destination field in the parent task and sets the summary for the subtask to ‘Prepare swag for “Destination”‘:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.action({
  title: 'Create a swag subtask',
  command: 'swag-subtask',
  guard: function(ctx) {
    return ctx.issue.isReported;
  },
  action: function(ctx) {
    var issue = ctx.issue;
    var newIssue = new entities.Issue(ctx.currentUser, issue.project,
      'Prepare swag for ' + issue.fields.Destination);
    newIssue.fields.Type = ctx.Type.Swag;
    newIssue.links['subtask of'].add(issue);
  },
  requirements: {
    Destination: {
      type: entities.Field.stringType
    },
    Type: {
      type: entities.EnumField.fieldType,
      Swag: {}
    }
  }
});

Generating Issues on a Schedule

So far we’ve shown you several ways to generate issues in response to human actions. However, there are many situations where you don’t even need a human to do the grunt work.

Consider the requirements for a team of developer advocates. One of the numerous responsibilities of this team is to prepare a monthly internal newsletter. The task is the same every month: same concept, same deadline, same assignee. Instead of creating this issue manually, set up a schedule to create it automatically:

var entities = require('@jetbrains/youtrack-scripting-api/entities');

var MONTHS = [
  "January", "February", "March", "April",
  "May", "June", "July", "August",
  "September", "October", "November", "December"
];

var DAY_IN_MS = 24 * 60 * 60 * 1000;

exports.rule = entities.Issue.onSchedule({
  title: 'Internal newsletter',
  search: '#DA-1', // anchor issue; it is required to ensure that
  // this rule is executed exactly once according to schedule
  cron: '0 0 19 15 1/1 ? *', // on the 15th day of every month at 19:00
  action: function(ctx) {
    var date = new Date(Date.now() + 31 * DAY_IN_MS);
    date.setDate(1);
    var month = MONTHS[date.getMonth()];
    var year = date.getFullYear();

    var newIssue = new entities.Issue(ctx.currentUser, ctx.issue.project,
      month + ' ' + year + ' Internal Newsletter');
    newIssue.fields.Assignee = ctx.author;
    newIssue.fields.Subsystem = ctx.Subsystem.Newsletters;
    newIssue.fields.DD = date.getTime();
  },
  requirements: {
    Assignee: {
      type: entities.User.fieldType
    },
    Subsystem: {
      type: entities.OwnedField.fieldType,
      Newsletters: {}
    },
    DD: {
      type: entities.Field.dateType,
      name: 'Due Date'
    },
    author: {
      type: entities.User,
      login: 'root'
    },
    da: {
      type: entities.Issue,
      id: 'DA-1'
    }
  }
});

As you can see, there are plenty of ways to make YouTrack do the heavy lifting for you. Define your recurring issues once and let the workflows do the rest.

The next article in this series will show you how to propagate values between linked issues to ensure that your data is always in sync. While we prepare the post for you, satisfy your curiosity by browsing other workflow-related resources:

• Watch our YouTrack Custom Workflow Repository in Git. We are uploading all of the workflows that we introduce in this series.
• Join our YouTrack Workflow Community in Slack. Interact directly with the YouTrack development team and see how other users support their business logic with workflows.
• Read the YouTrack documentation. We’ve got a wide range of topics for everyone from beginners to seasoned experts.

Over the last month, we have investigated various aspects of the issue lifecycle. We described how to set up granular read and write access for existing issues, how to streamline issue creation, and even how to generate issues automatically. If you missed any of our previous installments, you can find all of these articles by filtering for posts with the tag “makeitworkflow“.

The last thing we want to cover in this part of our Make It Workflow series is how to automate issue updates. As always, the purpose of this automation is to make YouTrack do the dirty work for you.

First, we’ll have a quick look at a few workflows that update issues based on changes that are applied to the issue itself. Then we’ll show you how changes in one issue can automatically apply updates to related issues.

Apply Changes in Response to Manual Updates

You may have never realized that part of the functionality that you use on a daily basis in YouTrack is implemented with workflows. One of the examples that we discussed in the previous blog post is the ‘Clone Issue’ workflow. This workflow adds the custom clone command to your YouTrack toolkit.

Another example is the ‘Subsystem Assignee’ workflow, which is attached automatically to every new project. This workflow contains one rule – ‘Set subsystem owner as assignee for unassigned issues’ – which… well…  basically does what the title says. The concept is relatively straightforward. Many organizational processes imply that each subsystem in your product has a responsible person or “owner”. This person is the default Assignee for each new issue that is assigned to this Subsystem. When you designate an owner for each of your subsystems, every new issue is assigned accordingly.
Here’s the corresponding workflow rule:

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

exports.rule = entities.Issue.onChange({
  title: workflow.i18n('Set subsystem owner as assignee for unassigned issues'),
  guard: function(ctx) {
    return !ctx.issue.fields.Assignee && ctx.issue.fields.Subsystem;
  },
  action: function(ctx) {
    var issue = ctx.issue;
    if ((issue.isReported && (issue.fields.isChanged(ctx.Subsystem) ||
         issue.isChanged('project'))) || issue.becomesReported) {
      issue.fields.Assignee = issue.fields.Subsystem.owner;
    }
  },
  requirements: {
    Assignee: {
      type: entities.User.fieldType
    },
    Subsystem: {
      type: entities.OwnedField.fieldType
    }
  }
});

This type of update is useful in a wide range of cases. Here are just a few examples:

1. Set the current user as Assignee when the issue state changes from Open to In Progress
2. Change the issue State from Wait for reply to Open when a new comment is added.
3. Mark an issue as Fixed when the Fix versions are set.
4. Clear the Fix versions field when the issue state changes to Duplicate or Incomplete.

Apply Changes on a Set Schedule

Let’s say that you want to improve your productivity and support the Pomodoro technique in your project (to learn more about the Pomodoro technique, refer to the Cirillo Company’s website). There are plenty of ways to do it: set up a physical timer, use a mobile app, enable a browser extension… or you can simply enable the ‘Pomodoro Timer’ workflow, which is distributed with YouTrack.

This workflow is supported by a set of additional custom fields, including Pomodoro state and Pomodoro countdown. As soon as the Pomodoro state changes to Timer’s running, the Pomodoro countdown is set to 25. A scheduled rule immediately starts decreasing the value in the countdown field by 1 every minute:

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

exports.rule = entities.Issue.onSchedule({
  title: workflow.i18n('Enable Pomodoro countdown'),
  search: 'has: {Pomodoro countdown} AND Pomodoro countdown: -0 AND (Pomodoro state: {Timer’s running} OR Pomodoro state: {On a break})',
  cron: '0 * * * * ?',
  action: function(ctx) {
    var issueFields = ctx.issue.fields;
    issueFields['Pomodoro countdown'] -= 1;
  },
  requirements: {
    'PomodoroCountdown': {
      name: 'Pomodoro countdown',
      type: entities.Field.integerType
    },
    'PomodoroState': {
      name: 'Pomodoro state',
      type: entities.EnumField.fieldType
    }
  }
});

You can find more details about this workflow in the YouTrack documentation

Another example that illustrates this type of automatic update is described in our Workflow Tutorial.

Update Issues in Response to Changes in Related Issues

The next two cases demonstrate how to update issues in response to changes in other issues. We’ll look at issues that are linked with a parent-subtask relationship. However, you can apply this approach to issues with other link types, depending on your process.

The first direction is to apply updates with a top-down approach: when updates are applied to a parent issue, the subtasks are updated accordingly. We call this behavior ‘inheritance’ and have several default workflows in YouTrack that implement this behavior for various fields: ‘Subtask Inherit Assignee’, ‘Subtask Inherit Fix Versions’ and ‘Subtask Inherit Subsystem’. Let’s take a look at the corresponding rule for the Subsystem field:

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

exports.rule = entities.Issue.onChange({
  title: workflow.i18n('Copy subsystem from parent task when issue is linked as a subtask'),
  guard: function(ctx) {
    return ctx.issue.links['parent for'].added.isNotEmpty() &&
      ctx.issue.fields.Subsystem;
  },
  action: function(ctx) {
    var issue = ctx.issue;

    var safeSetSubsystem = function(subtask) {
      if (subtask.project && !subtask.project.isArchived) {
        if (subtask.project.key === issue.project.key ||
            subtask.project.findFieldByName(ctx.Subsystem.name)) {
          if (!subtask.fields.Subsystem) {
            var value = subtask.project.findFieldByName(ctx.Subsystem.name)
              .findValueByName(issue.fields.Subsystem.name);
            if (value) {
              subtask.fields.Subsystem = value;
            }
          }
        }
      }
    };

    issue.links['parent for'].added.forEach(safeSetSubsystem);
  },
  requirements: {
    Subsystem: {
      type: entities.EnumField.fieldType
    },
    SubtaskOf: {
      type: entities.IssueLinkPrototype,
      name: 'Subtask',
      outward: 'parent for',
      inward: 'subtask of'
    }
  }
});

You may notice that this rule is pretty verbose. This verbosity guarantees that the rule won’t fail with an error when one of the subtasks belongs to a project that doesn’t use a Subsystem field. We recommend that you follow this approach every time, as the rule can potentially refer to issues in projects other than the project to which this rule is attached.

The second direction is from the bottom up. This approach is used when subtasks represent the steps for completing a larger task. When all of the subtasks reach a specific state, this means that the parent issue has reached this state as well. The most basic example is to close the parent issue as fixed when all subtasks are fixed. This rule is one of the modules in the default ‘Subtasks’ workflow:

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

exports.rule = entities.Issue.onChange({
  title: workflow.i18n('Fix parent when all subtasks are resolved'),
  guard: function(ctx) {
    return ctx.issue.isReported && ctx.issue.becomesResolved;
  },
  action: function(ctx) {
    var processParent = function(issue) {
      if (issue.links['subtask of'].isEmpty()) {
        return;
      }
      var parent = issue.links['subtask of'].first();
      if (parent && parent.project && !parent.project.isArchived &&
        parent.isReported && !parent.isResolved) {
        var unresolvedSubtask = parent.links['parent for'].find(function(subtask) {
          return subtask.isReported && !subtask.fields.State.isResolved;
        });
        if (!unresolvedSubtask) {
          var field = parent.project.findFieldByName(ctx.State.name);
          if (field) {
            var value = field.findValueByName(ctx.State.Fixed.name);
            if (value) {
              parent.State = value;
              workflow.message(workflow.i18n('Automatically set {0} as Done', parent.id));
              return parent;
            }
          }
        }
      }
    };

    var issue = ctx.issue;
    while (issue) {
      issue = processParent(issue);
    }
  },
  requirements: {
    State: {
      type: entities.State.fieldType,
      Fixed: {}
    }
  }
});

Depending on your process, this ‘reaching-the-target-state’ condition can be very different. For example, you can have a field Documentation provided with the values No(default) and Yes When each subtask is assigned Yesto this field, this means that the entire parent issue is documented.

We hope that your workflow toolkit is now stocked with a range of gizmos that support your issue management processes — even the most tricky ones. This is our last article in the Make It Workflow series for 2017. After the holidays, we’ll return with more specific use cases, including:

• Extending the capabilities of the time-tracking feature
• Enhancing helpdesk support
• Sending newsletters with YouTrack

If you have any ideas about what you would like to read about in this series, you are very welcome to post a comment here or share your thoughts in our YouTrack Workflow Community in Slack.

We wish you a Merry Christmas and a Happy New Year!

We hope that your 2017 was successful, productive and full of bright and memorable moments for you and your team. We wish you all the best for the holidays and hope you have a great start to the new year.

The end of the year is just the right time to take a retrospective review. What are the main usage trends in YouTrack? Which projects and boards are the most popular? Which reports do you use more often? We’ve collected the most interesting trends in YouTrack usage through 2017 and are excited to share them with you*.

Our Customers’ Location

YouTrack Standalone

The biggest markets for YouTrack standalone are pretty stable when compared to the previous year: USA (20%), Germany (17%), Russia (15%), and the United Kingdom (5%), followed by Ukraine, France, Netherlands, China, and Canada.

YouTrack InCloud

Most of the InCloud customers come from the same countries with only a slight change in how they are distributed: USA (16%), Russia (15%), Germany (5%), Ukraine (5%), the UK (5%). In general, InCloud customers are more distributed around the world, compared to standalone.

Popular Project Types

When you create a new project, YouTrack provides you with several options to choose from, which you can pick depending on your development process. The Pure issue tracking project is suggested by default with no specific process imposed; this contains a basic set of issue fields and workflows. This year the default template was the most popular template accounting for about 50% of all created projects. Agile project templates reflect the type of methodologies our users prefer to follow. Scrum (30%) is still more popular than Kanban (20%). However, Kanban is getting more weight compared to the last year. Good job, keep going!

Agile Board Flavours

Agile boards are really popular in YouTrack. Makes sense, as using the agile board is the easiest way to visualize your process, whether you follow any standard agile practices, mix and match them, or you have just invented your own process. This year we’ve added more templates to give you more means of getting started with your personal boards, support your custom process, or synchronize sprints on the board with the values of a custom field such as fix version, for example.

The results are pretty interesting: 70% of our users follow standard agile practices, still having the preference for Scrum (41%) with a growing share of Kanban (28%). Custom board (18%) share is noticeable as well, which means that our users are mixing and matching various practices more often. This trend completely aligns with our vision of agile values, and we’ll keep working on being flexible enough to support any kind of process. Personal boards gained a 5% share, which is about right considering the growing personal task-management trend. Awesome!

Most Popular Reports

Reports are the best way to keep track of your team and project progress. It’s very important to choose the right metrics to help you track your progress and plan your future work. Which is the most popular report?

Unsurprisingly, the Time report has the biggest share (18%), as it’s crucial for most projects to estimate and keep track of spent time in order to keep the project budget well balanced. Knowing this then means we’ll keep enhancing our time tracking capabilities. For example, recently we’ve introduced an Estimation report to help you better plan your work. The next group according to popularity is: Issue distribution per assignee (13%), Burndown (12%) and Gantt Chart (10%). This trend shows that our users tend to keep the balance of workload within the team (Issue per assignee report), track their iterative progress (Burndown), and plan their work according to the task dependencies and team capacity (Gantt chart).

Dashboards and Widgets

Dashboard is the best way to get a birds-eye view of your projects and activities. In YouTrack you can create multiple dashboards and share them with your team or your boss. Which type of widget is the most popular? Filtered issues list (Issues) is the most popular widget this year (47%) followed by the Reports (37%). Markdown notes (9%) and Wiki notes (7%) are less popular. Recently, we’ve introduced an option to create custom widgets. Now you’re welcome to populate your dashboard with any kind of useful info!

This year you did a great job! We hope that YouTrack has helped you to reach your goals and saved you extra time spent on daily issue tracking routine. We’ll keep doing our best next year to provide you with the best tool for your team collaboration, to help you to become truly agile and follow your own process. See you next year!

* The data provided in this post is generated from anonymous feature statistics collected from instances that agreed to provide it explicitly (Standalone) or by accepting our Privacy Policy (InCloud).

You’ve made it to our last episode in the How We Scrum series. In this installment, I’ll walk you through our sprint retrospective. To catch up on older posts in this series, check out the Introduction, Our Scrum Roles, Our Backlog, Our Approach to Estimation, Our Sprint Planning, The Sprint, and Our Sprint Demo Session.

We consider the Sprint Retrospective to be a very important part our Scrum process. The Sprint Retrospective happens at the end of each sprint, normally on Friday, after the Sprint Demo. This one-hour session helps us to get both positive and negative feedback from the team about the past sprint. By collecting, prioritizing, and discussing feedback from each member of team, we continue with activities that have a positive impact and eliminate negative behaviors.

One day before the Sprint Retrospective, our Scrum Master sends a form to collect the following feedback from each member of the team:

1. Two things you liked about this sprint.
2. Two things you didn’t like about this sprint.
3. Two suggestions for improving our process going forward.

Everyone who wants to share feedback fills in the form at least 15 minutes before the Sprint Retrospective. The Scrum Master tries to combine feedback from different members of the team if it looks similar or related. When done, the Scrum Master prints the answers and pins them to a physical board, grouping them by pluses, minuses and suggestions.

The whole team gets together and cast votes in support of each piece of feedback. Depending on the number of answers and people attending, each team member can cast two to four votes. Normally, everyone gets three votes.

We combine the total number of votes cast in both St.Petersburg and Munich. When the voting is over, the Scrum Master calculates the totals and ranks the feedback from the most voted to the least voted.

Starting with the piece of feedback that received the most votes, we discuss each item as a team. The Product Owner normally moderates the discussion, so it doesn’t take too long and stays focused. When all the opinions are shared, the Scrum Master summarizes the action items we need to take in the next sprint in order to keep what’s working well (for positive feedback) or resolve the issue (for negative feedback).

The Sprint Retrospective is over when all of the items (or items that received at least two votes) are discussed. Afterwards, the Scrum Master adds the action items to the Retrospective page and shares it with the team. This helps the team stay focused on these action items during the next sprint and lets anyone who missed the Sprint Retrospective stay up to date.

Conclusion

That was a pretty long story about How we Scrum inside the YouTrack team. I hope you found something to borrow and practice in your team, or just saw something that sparked your imagination and helped you reinvent your process. However, the main idea of the whole series is to share our experience. We believe that the key to a successful development process is not in following any strict guidelines and methodologies, but rather in adopting good practices to our specific needs and goals. Be agile in your own way!

When you work with issues on your Agile Board, it’s important to configure it the way you prefer. Sometimes you don’t have enough permissions to edit the settings, or you simply want to use more functionality on your board.
Today we’ll tell you about YouTrack Tweaks, a Chrome extension which provides per-user YouTrack customization.

What’s in there?
The extension lets you customize the view of the cards on your Agile Board and enable desktop notifications. Since the extension was released just recently, more features are coming soon.

Agile board cards tweak
You can choose the custom fields that you want to show on the cards on your Agile Board, including a project name. These tweaks let you see more useful information on the card using a small view mode on the board, which is very useful for multi-project boards.

The extension also lets you set up colors for custom fields if you don’t have enough permissions in YouTrack. Simply choose the field that you want to apply color to and click the “Auto-generated colors” button.

Agile Board desktop notification
You can also enable desktop notifications for your Agile Board. Set the conditions and get the notifications for new issues right away. For example, to get desktop notifications for newly created issues with a bug type on your board, set “Type=Bug”. You will get these notifications even if you work in another tab. Click the notification popup to open the issue. (However, note that the tab with the Agile Board must stay opened in your Chrome browser.)

Two view settings modes are available: expert and simple. The expert mode lets you limit the usage of any tweak by specifying a YouTrack instance URL, Agile Board name or sprint name. You can also change the message or an icon for the notification popup.

Since this is a Chrome extension, all the settings are synchronized in the cloud. That is why if you use the same Gmail account, you won’t lose your configuration settings when you open your board from another device.

Get the extension today and enjoy your tweaked Agile experience!

Please share your feedback in the comment section below. If you have any suggestions or want to report a bug, please use YouTrack Tweaks issue tracker.

Welcome to the Baking Boards vlog series! This series is devoted to showing you how we at JetBrains configure and use Agile boards in YouTrack.

Different teams use boards in different ways. You’ll see examples from Product Development, Design, Marketing, Technical Writing, and even a personal board. Each episode shows you how one of our teams manages a project on an agile board that supports their process. We also include a recipe to follow if you want to “bake” a board just like it.

Let’s cook!

In the first episode of Baking Boards, we show you how our technical writers cooked (that is, configured) their agile board to manage documentation tasks for YouTrack and Hub.

Preparation

1. Create your board.
We built this board using the Scrum board template.

When you create the board:

• Select the projects that you want to manage on the board. All of the issues that we manage on this board belong to the same project.
• For the Backlog option, choose Create new. We’ll customize the backlog later.

2. Create a sprint.

This board uses sprints that correspond to major releases in YouTrack and Hub, however, we only assign each sprint a name.

All sprints are unscheduled.

3. Set sprint options.
We pull all of our issues from the backlog, so we don’t use any options that add issues to the board automatically.

4. Define columns.
Columns are identified by values from the State field. We have separate columns for Open, Reopened (merged), In Progress, In Review, Ready, and Published.

5. Define swimlanes.
Swimlanes are identified by issues that are assigned the Epic value in the Type field.
We show the swimlane for uncategorized cards at the bottom of the board.

6. Configure cards.
When we add a card to the board, the default value for the Type field is Task.
The Color Scheme is based on the set of values for the Priority field.
We also enabled the option to show colors for other custom fields.

7. Pick a chart.
We didn’t show our chart in the demo, but for this board, we use the Cumulative flow diagram.

8. Build the backlog.
We use the backlog to filter out issues that we don’t want to manage on this board. Our backlog uses the following saved search:

This search query:

• Shows only issues that belong to our project (Ring Docs)
• Excludes issues from specific subsystems (Subsystem: -Wording, -Screencasts)
• Shows only issues that are unresolved (#Unresolved)
• Excludes issues that are already assigned to a sprint on the board (has: -{Board Ring Docs}

Enjoy! Bon appetit!

In this episode of Baking Boards, we show you the agile board that the design team cooked up to manage issues in their project.

Preparation

1. Create your board.
   We built this board using the Custom board template.

When you create the board:

• Select the projects that you want to manage on the board. All of the issues that we manage on this board belong to the same project.
• For the Backlog option, choose Create new. We won’t do anything with it, but you need a backlog to create the board.

2. Define columns.

With the custom board template, you have to define your columns first. On our board, columns are identified by values from the State field. We merge the Submitted, Open, and Reopened states in the first column. The second merged column shows issues that have the states Incomplete, or To be discussed. We then have dedicated columns for the states In Progress, Wait for Reply, and Fixed.

3. Create a sprint.

Now that your board is configured correctly, you can add your first sprint. This board uses sprints that correspond to the seasons on the calendar. We set the sprint name to the season and year and schedule each sprint for three months.

4. Set sprint options.

We use the Add new issues to sprint option and select the current sprint.
When we add the next sprint to the board, we update this option to add issues to the new sprint.

5. Define swimlanes.

Here, we identify swimlanes for each value in the Assignee field. This creates a separate swimlane for each member of the team.
We show the swimlane for uncategorized cards at the top of the board. New issues that are added to the board automatically appear in this swimlane.

6. Configure cards.

We don’t have the option to set the default issue type for new cards. That’s because we define swimlanes by assignee. Which is fine — we use the Type field to indicate whether the design request is for an icon, t-shirt, banner, and so on.
The Color Scheme is based on the set of values for the Priority field.

We use the Show colors for other custom fields option to show color indicators for the Priority field, but we don’t really need it. The first custom field in our project is Due Date, so we work against the deadline.

There are a few features on the board that we don’t use at all:

• Backlog — with the option to add new issues to the sprint enabled, we don’t keep a backlog. New issues appear on the board automatically and are assigned to a designer shortly after they are reported.
  If you have unresolved issues in an existing project that you want to migrate to the board, create a saved search that contains these issues and use this saved search as a backlog. Once you’ve moved all of the issues from the backlog to the board, you can collapse the backlog and forget about it.
• Charts — we don’t work with charts on the board. If you’re looking to build a board that’s similar to this one, you can pick whichever chart suits your style.

Secret Sauce

As you may have noticed in the screencast, our design team has two team leads. They review all cards that are added to the board automatically and assign each issue to one of our designers.
What you don’t see is the workflow that is attached to the Design & Artwork project. This workflow blocks anyone other than these two team leads from changing the value in the Assignee field.

This means the team can make their board visible to other teams at JetBrains, but they have full control over who takes each assignment.

Here’s the rule:

The workflow allows any member of the design-artwork-assignee-updaters group to set the value of the Assignee warning. If the team leads need someone to assign issues in their absence, they just add them to the group.

If anybody else tries to assign an issue in the project, an error message displays the names of the people they can contact to get the issue assigned to a designer.