Documentation for the getIssue Logic Component

Overview

The getIssue component is designed to facilitate the retrieval of issue data from a Jira instance. By utilizing the provided issue key, the component connects to Jira's API, fetches detailed information about the specified issue, and returns it in a structured format. This enables users to integrate issue tracking and management tasks into their analytics and data workflows seamlessly.

Settings

This node has several configurable settings, which control its operation and output. Each of these settings is examined in detail below.

1. issueKey

• Input Type: String
• Description: The issueKey setting is a required parameter that specifies the unique identifier of the Jira issue to be retrieved (e.g., "PROJ-123"). If this parameter is not provided either in the inputs or config, the component will return an error.
• Default Value: Empty (no default value; must be supplied).

2. fields

• Input Type: String or Array of Strings
• Description: The fields setting determines which fields from the Jira issue are to be returned. It can accept a comma-separated string or an array of field identifiers. The default fields include summary, status, assignee, reporter, priority, issuetype, description, created, updated, project, labels, and components. Modifying this setting allows users to customize the data returned according to their specific requirements.
• Default Value: 'summary,status,assignee,reporter,priority,issuetype,description,created,updated,project,labels,components'.

Additional Notes:

• The component expects the fields to be returned in a flattened format for easy consumption. The retrieved issue's properties such as summary, status, priority, etc., will be mapped directly to output keys.

Workflow

1. Input Preparation: The function first checks for the presence of the required issueKey and the optional fields to build the request appropriately.
2. Error Handling: If the issueKey is missing, an error object is returned indicating that the issue key is required.
3. Jira Integration: The component uses the utility function the integration connection to create a connection with the Jira API using the provided context.
4. Data Retrieval: Once the connection is established, it calls the getIssue method on the Jira instance with the specified issueKey and fields.
5. Data Formatting: The retrieved data is organized into a structured output, flattening nested objects for simpler access.
6. Error Handling: If an error occurs during the API call, a descriptive error message is returned.

Data Expectations

The getIssue component expects the following inputs:

• Inputs:

  • inputs.issueKey: A valid Jira issue key (string).
  • inputs.fields: (optional) Customized fields to retrieve (string or array of strings).

• Context: The context object is supplied at runtime, which may include user authentication and other relevant metadata needed to connect to Jira.

Output Structure

The component outputs data in the following format:

{
    "output1": {
        "id": "issue_id",
        "key": "issue_key",
        "self": "issue_self_url",
        "summary": "issue_summary",
        "status": "issue_status",
        "statusCategory": "issue_status_category",
        "priority": "issue_priority",
        "issueType": "issue_type",
        "assignee": "assignee_display_name",
        "assigneeAccountId": "assignee_account_id",
        "reporter": "reporter_display_name",
        "reporterAccountId": "reporter_account_id",
        "projectKey": "project_key",
        "projectName": "project_name",
        "labels": "label1, label2",
        "components": "component1, component2",
        "created": "issue_created_date",
        "updated": "issue_updated_date",
        "description": "issue_description"
    }
}

Use Cases & Examples

Use Case 1: Issue Management Dashboard

A project management team requires a streamlined dashboard to monitor the status and details of ongoing projects using Jira. By employing this node, they can retrieve information such as statuses and assignments live from Jira, displaying it in their analytics dashboard.

Use Case 2: Automated Reporting

An analytics team needs to generate automated reports for weekly development reviews. By configuring the component to pull specific issue details, they can create detailed reports highlighting the current state of tasks based on Jira data.

Detailed Example Configuration

Scenario

A team is tracking bugs in their ongoing project and wants to create an overview report that includes specific fields from Jira.

Configuration

{
    "inputs": {
        "issueKey": "PROJ-456",
        "fields": ["summary", "status", "assignee", "priority"]
    },
    "config": {}
}

Expected Output

For an issue key PROJ-456, this configuration might yield an output like:

{
    "output1": {
        "id": "456",
        "key": "PROJ-456",
        "self": "http://jira.example.com/rest/api/2/issue/456",
        "summary": "Fix login bug",
        "status": "In Progress",
        "priority": "High",
        "assignee": "John Doe",
        "assigneeAccountId": "12345",
        "reporter": "Jane Smith",
        "reporterAccountId": "67890",
        "projectKey": "PROJ",
        "projectName": "Project Example",
        "labels": "",
        "components": "",
        "created": "2023-10-01T12:34:56.789+0000",
        "updated": "2023-10-02T12:34:56.789+0000",
        "description": ""
    }
}

In this output, only the specified fields (summary, status, assignee, priority) are retrieved and returned, demonstrating the flexibility of this node in meeting specific reporting needs.