Since release 7.0 YouTrack brings REST client implementation to the workflow API. You can use workflows to script push-style integrations with your favorite tools.
See complete API reference in Http module documentation.
Here's a basic example:
The REST client supports the HTTP basic access authentication scheme via headers. To utilize this scheme, compute a base64(login:password) value and set the authorization header as follows:
Set the authorization header for every request, unless the target server provides cookies upon successful authentication.
HTTP cookies are managed transparently under the hood, when present. That is, if any REST call returns cookies, they persist automatically and provide access to the same domain until they expire. You can also set cookies manually in the header:
The REST client returns the server response as an object, described in Response.
Secure Connections (SSL/TLS)
The REST client supports
https:// connections out of the box. Although it's currently unable to present a client certificate during the handshake, it can still validate a server certificate against known certificate authorities. To learn more about adding trusted certificates to YouTrack, see SSL Certificates.
For best results, observe the following guidelines.
Know your protocol. If you're not yet familiar with HTTP, it's time to fill the gap. You should have at least a basic understanding of the protocol to script the integration and decrypt errors.
Know your API. Your favorite application that you're going to integrate with YouTrack almost certainly has documentation that tells you how to use their API. Check it out before you start to script an integration. For instance, here's a manual for the Pastebin service.
Use logging. Log errors and everything else with
Use a third-party REST client to make sure your requests are formatted correctly. Diagnostic tools in clients like cURL, Wget or the Postman extension for Chrome can help you to find out why your workflow is not acting as expected.
Don't forget to add
Acceptheaders to your requests. The majority of APIs out there rely on these headers and refuse to work without them.
The following case studies illustrate how you can use the workflow REST API to integrate YouTrack with an external application.
Pastebin is a website where you can store text online for a set period of time. You can paste any string of text like code snippets and extracts from log files.
In this case study, we extract code snippets from new issues and store them on Pastebin instead. The issue description retains a link to the content that is moved to Pastebin. The following workflow rule demonstrates how this scenario is implemented:
On the other hand, we may want to do the opposite: to expand any Pastebin link we met into a code snippet, i.e. to download it and insert into issue. Let's try to code it:
Custom Time Tracking with the Harvest Web Service
Suppose that we want to bill customers for the working hours that we record in YouTrack. The problem is that YouTrack isn't really built for managing invoices and associating spent time with specific customers. An integration with a dedicated time tracking service can make life a lot easier.
Let's first introduce a common part for all scripts below: a common custom script, containing connection initialization and common payload fields:
One possible scenario is to introduce a custom field - Billable hours - and post changes to the value of this field to the Harvest web service.
Let's consider another option: start time tracking when an issue moves to an In Progress state and stop time tracking when the issue is resolved. Lucky for us, Harvest has a timer API that we can use to start and stop the timers remotely. The Harvest ID custom field is required to store the timer identifier.
The following workflow rule stops the Harvest timer when an issue is resolved.