Jira Search Issues

Purpose

This node is designed to connect with the Jira API to retrieve issues based on a specified JQL (Jira Query Language) query. It allows users to customize the number of results returned, the fields displayed for each issue, and the beginning point for pagination. This tool is particularly useful for analytics and reporting tasks, enabling users to efficiently gather relevant issue data from their Jira projects.

Settings

The searchIssues implementation consists of several configurable settings that impact its functionality. Below are detailed explanations of each setting:

1. jql

• Input Type: String
• Description: This setting is a required field that takes a JQL query as input. The JQL query determines which issues are fetched from Jira. If no JQL is provided, the function will return an error indicating that a JQL query is required.
• Default Value: An empty string (''). If inputs.jql and config.jql are both not provided, it defaults to an empty string and leads to an error.

2. maxResults

• Input Type: Numeric
• Description: This setting specifies the maximum number of issue results to return from the search query. Changing this value allows users to control the amount of data retrieved. Higher values will yield more results, which might impact performance and data handling in user interfaces.
• Default Value: 50. If neither inputs.maxResults nor config.maxResults are provided, it defaults to 50.

3. startAt

• Input Type: Numeric
• Description: This setting determines the starting index for the results returned. It is useful for pagination, allowing users to skip a certain number of results and retrieve data in chunks. The typical usage is to vary this value alongside maxResults for paginated data retrieval.
• Default Value: 0. If neither inputs.startAt nor config.startAt are provided, it defaults to 0, meaning results will start from the first issue returned.

4. fields

• Input Type: String or Array
• Description: This setting lists the fields to fetch for each issue. Users can specify which attributes of the issues they want to see in the output. If an array is provided, it will be converted to a comma-separated string format. This impacts the returned data structure, determining what information is available for each issue.
• Default Value: 'summary,status,assignee,priority,issuetype,created,updated,project'. If neither inputs.fields nor config.fields are provided, it defaults to fetching these common fields.

How it Works

1. Input Acquisition: The function starts by extracting the inputs provided to it and checks for the presence of the required jql parameter.
2. Building Connection: It establishes a connection to the Jira API using a secure connection.
3. Issue Retrieval: The function then makes a call to the Jira API using the searchIssues method, passing in the jql, maximum results, starting index, and requested fields.
4. Data Processing: Upon receiving the response, the data is processed to flatten the hierarchical issue structure into a more manageable format. Key information such as ID, summary, status, assignee, etc., is extracted.
5. Output: If successful, the function returns an object containing the retrieved issue data and the total count of issues that matched the JQL query. If an error occurs at any point, an error message will be returned.

Expected Data

The primary data expected by this logic is a valid JQL query string. Additionally, it expects numeric inputs for maxResults and startAt, and either a string or array for the fields setting. The results returned will include structured data containing attributes of issues specified by the fields, organized in a tabular format.

Use Cases & Examples

Use Cases

1. Project Management Reporting: Teams can utilize searchIssues to create reports that summarize outstanding issues in a project. By querying specific criteria like project key and status, they can gauge progress effectively.

2. Data Analytics for Trend Analysis: Analysts can run historical searches to gather data on issues categorized by priority or assignee, helping to identify patterns or bottlenecks in project workflows.

3. Automated Alerts for High-Priority Issues: By integrating searchIssues with a notification system, teams can set up alerts that trigger when high-priority issues remain unresolved beyond a certain timeframe.

Example Configuration

Use Case: Project Management Reporting

• Scenario: A project manager wants to retrieve all issues within a specific project that are currently "In Progress".
• Configuration:

{
  "inputs": {
    "jql": "project = MYPROJ AND status = 'In Progress'",
    "maxResults": 100,
    "startAt": 0,
    "fields": ["key", "summary", "status", "assignee", "priority"]
  },
  "config": {}
}

In this configuration:

• The JQL specifies that the project key is MYPROJ and filters by issues that have the status "In Progress".
• A maximum of 100 results will be fetched, starting from the first issue.
• The fields requested to be returned are the issue key, summary, status, assignee, and priority, aligning the output with the project manager’s reporting needs.