WebStorm 2016.2 Help

Tutorial: Configuring Generic Task Server

On this page:

Introduction

The Generic connector has been developed as a mechanism enabling the users to configure integration with the servers that WebStorm does not officially support. At the moment, this mechanism:

  • Supports the services with REST API.
  • Does not support pagination in server responses.
  • Allows the following ways of client authentication:
  • Supports GET and POST requests. At this moment POST requests can contain only form-encoded data, specified as query parameters in the corresponding URL

Note that a client can only send requests to a server and retrieve responses according to a certain template.

This tutorial is created for the JIRA 5.0 server. However, configuring a generic server described below is valid for any higher version of JIRA, including JIRA OnDemand.

Prerequisites

Make sure that the following prerequisites are met:

  • You are working with WebStorm version 9 or later.

    If you still do not have WebStorm, download it from this page . To install WebStorm, follow the instructions, depending on your platform.

    This tutorial is created with WebStorm version 2016.2.

  • You have an account in a tracking system. For example, this tutorial makes use of JIRA.

Specifying the task server

  1. Open the Settings / Preferences Dialog by choosing File | Settings for Windows and Linux or WebStorm | Preferences for OS X. Expand the Tools node, and then click Servers under Tasks.
  2. On the Servers page that opens, click add and choose Generic:
    task_generic_server
  3. In the General tab, specify URL of the server, select the check box Use HTTP Authentication, and type your user name and password.
  4. Leave the Commit Message tab as is, and then click the Server Configuration tab.

Configuring the task server

The Server Configuration tab contains three fields:

  • The Login URL field is disabled, because the check box Use HTTP authentication in the General tab has been selected.
  • The Tasks list URL field makes it possible to obtain the list of issues from the server (this list is asked for when you open a task).

    In this field, specify the variable {serverUrl} that corresponds to the server URL, specified in the General tab, then type the path /rest/api/2/search and expression ?maxResults={max}&jql={JQL_Query} .

    Pay attention to the template variable {JQL_Query}, which is not defined so far. To define it, click the button Manage Template Variables, then in the Template Variables dialog box that opens, click add and type the name and value of this template variable:

    task_generic_server_template_variables1

    Defining a template variable leads to including it in the suggestion list:

    task_generic_server_template_variables

    Mind the check box Show on first tab in the Template Variables dialog box. If this check box is selected (as it's done in this tutorial), the template variable and its value shows on the General tab of the Servers page.

  • The Single task URL field makes it possible to obtain a detailed information about a specific issue by its ID. This field is optional, when the check box Each task in separate request is cleared.

    To fill in the field, use the following format
    <variable {serverUrl} that corresponds to the server URL, specified in the General tab> <the path /rest/api/2/issue/> <variable {id}>

Code completion is available in all these fields.

task_server_code_completion

Choosing the response type and using selectors

You also need to choose the response type and to specify how information about an issue will be extracted from the server response. This is done in the table of selectors in the lower part of the Server Configuration tab.

WebStorm suggests three response types: XML, JSON and text.

  • Choose XML if the server responds in the XML format, the selectors are described in XPath.
  • Choose JSON if the server responds in the JSON format, the selectors are described in JSONPath.
  • Choose Text if the server responds in the plain text format, the selectors are described as regular expressions.

In this tutorial, for example, let's choose JSON and describe the selectors using JSONPath.

The first three selectors are mandatory:

  • tasks: this selector denotes the path in the server response to the descriptions of specific issues.
  • id: this selector denotes the path to a unique ID in the description of a specific issue.
  • summary: this selector denotes the path to a title of an issue within its description.

To fill out the table, use the server responses. For JIRA, for example, one can observe the server responses immediately in the browser, following a link in the format http://<server URL>:<port>/rest/api/2/search .

Obtaining issues from the server

  1. To check that the specified settings ensure successful integration with the tracking system, click Test:
    task_generic_server_connection_successful
    If the connection is successful, click OK and close the Settings dialog.
  2. Do one of the following:
    • On the main menu, choose Tools | Tasks & Contexts | Open Task
    • Press Shift+Alt+N.
    • Click the tasks combo on the main toolbar:
      task_generic_server_open_task
  3. In the list of tasks, choose the one you want to open, and hit Enter:
    task_generic_server_open_task1

Summary

In this tutorial, we have:

  • assigned JIRA as the generic task server.
  • configured this task server.
  • specified response type and selectors.
  • made sure that connection is successful.
  • retrieved issues from the configured server.

See Also

Last modified: 20 July 2016