Merge pull request #1709 from logit-io/jira-issue

Jira: migrate bumping to enhanced_search_issues (no legacy fallback)

Author: jertel

CHANGELOG.md

@@ -23,6 +23,10 @@
 - Update build libraries: pylint, pytest, pytest-cov, pytest-xdist, sphinx, tox - [#1706](https://github.com/jertel/elastalert2/pull/1706) - @nsano-rururu
 - Update docs build to use Ubuntu 24.40 and Python 3.13 - [#1708](https://github.com/jertel/elastalert2/pull/1708) - @jertel
 - Cleanup unused imports - [#1708](https://github.com/jertel/elastalert2/pull/1708) - @jertel
+- **Jira Migration**: Updated for Jira Cloud API deprecation (legacy JQL search endpoints will be removed after
+  May 1, 2025). ElastAlert 2 now uses the Jira client's `enhanced_search_issues()` method for ticket bumping
+  behavior, which internally uses the new Jira API endpoints. This change is transparent for users with compatible
+  Jira library versions (3.10.5+). No configuration changes required.
 
 # 2.26.0
 

docs/source/alerts.rst

@@ -1377,6 +1377,12 @@ Example usage::
 ``jira_bump_after_inactivity``: If this is set, ElastAlert 2 will only comment on tickets that have been inactive for at least this many days.
 It only applies if ``jira_bump_tickets`` is true. Default is 0 days.
 
+.. note:: 
+   **API Migration Notice**: Starting May 1, 2025, Atlassian deprecated the legacy JQL search endpoints. ElastAlert 2 
+   now uses the Jira client's ``enhanced_search_issues`` method for bumping logic, which automatically uses the new 
+   Jira API endpoints internally. This change is transparent for users with compatible Jira library versions (3.10.5+). 
+   No configuration changes required.
+
 Arbitrary Jira fields:
 
 ElastAlert 2 supports setting any arbitrary Jira field that your Jira issue supports. For example, if you had a custom field, called "Affected User", you can set it by providing that field name in ``snake_case`` prefixed with ``jira_``.  These fields can contain primitive strings or arrays of strings. Note that when you create a custom field in your Jira server, internally, the field is represented as ``customfield_1111``. In ElastAlert 2, you may refer to either the public facing name OR the internal representation.

elastalert/alerters/jira.py

@@ -262,14 +262,26 @@ def find_existing_ticket(self, matches):
         if self.bump_not_in_statuses:
             jql = '%s and status not in (%s)' % (jql, ','.join(["\"%s\"" % status if ' ' in status else status
                                                                 for status in self.bump_not_in_statuses]))
+
+        # Force use of enhanced_search_issues (new API)
+        # This method should be available in updated jira library versions
+        if not hasattr(self.client, 'enhanced_search_issues'):
+            raise EAException("enhanced_search_issues method not available. Please update your jira library to a version that supports the new Jira API endpoints.")
+        
         try:
-            issues = self.client.search_issues(jql)
+            issues = self.client.enhanced_search_issues(jql)
+                
+            # Ensure issues is a list-like object before checking length
+            if issues and len(issues):
+                return issues[0]
         except JIRAError as e:
             elastalert_logger.exception("Error while searching for Jira ticket using jql '%s': %s" % (jql, e))
             return None
+        except Exception as e:
+            elastalert_logger.exception("Unexpected error while searching for Jira ticket: %s" % e)
+            return None
 
-        if len(issues):
-            return issues[0]
+        return None
 
     def comment_on_ticket(self, ticket, match):
         text = str(JiraFormattedMatchString(self.rule, match))

tests/alerters/jira_test.py

@@ -6,7 +6,7 @@
 from unittest import mock
 
 from elastalert.alerters.jira import JiraFormattedMatchString, JiraAlerter
-from elastalert.util import ts_now
+from elastalert.util import ts_now, EAException
 from tests.alerts_test import mock_rule
 
 
@@ -90,14 +90,15 @@ def test_jira(caplog):
             mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
         mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
         mock_jira.return_value = mock.Mock()
-        mock_jira.return_value.search_issues.return_value = []
+        # Mock enhanced_search_issues method
+        mock_jira.return_value.enhanced_search_issues.return_value = []
         mock_jira.return_value.priorities.return_value = [mock_priority]
         mock_jira.return_value.fields.return_value = []
 
         alert = JiraAlerter(rule)
         alert.alert([{'test_term': 'test_value', '@timestamp': '2014-10-31T00:00:00'}])
 
-    expected.insert(3, mock.call().search_issues(mock.ANY))
+    expected.insert(3, mock.call().enhanced_search_issues(mock.ANY))
     assert mock_jira.mock_calls == expected
 
     # Remove a field if jira_ignore_in_title set
@@ -106,21 +107,24 @@ def test_jira(caplog):
             mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
         mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
         mock_jira.return_value = mock.Mock()
-        mock_jira.return_value.search_issues.return_value = []
+        # Mock enhanced_search_issues method
+        mock_jira.return_value.enhanced_search_issues.return_value = []
         mock_jira.return_value.priorities.return_value = [mock_priority]
         mock_jira.return_value.fields.return_value = []
 
         alert = JiraAlerter(rule)
         alert.alert([{'test_term': 'test_value', '@timestamp': '2014-10-31T00:00:00'}])
 
+    # Check that 'test_value' was removed from the JQL query when jira_ignore_in_title is set
     assert 'test_value' not in mock_jira.mock_calls[3][1][0]
 
-    # Issue is still created if search_issues throws an exception
+    # Issue is still created if enhanced_search_issues throws an exception
     with mock.patch('elastalert.alerters.jira.JIRA') as mock_jira, \
             mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
         mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
         mock_jira.return_value = mock.Mock()
-        mock_jira.return_value.search_issues.side_effect = JIRAError
+        # Mock enhanced_search_issues to raise an exception
+        mock_jira.return_value.enhanced_search_issues.side_effect = JIRAError
         mock_jira.return_value.priorities.return_value = [mock_priority]
         mock_jira.return_value.fields.return_value = []
 
@@ -143,6 +147,8 @@ def test_jira(caplog):
             mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
         mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
         mock_jira.return_value = mock.Mock()
+        # Mock both search methods
+        mock_jira.return_value.enhanced_search_issues.return_value = [mock_issue]
         mock_jira.return_value.search_issues.return_value = [mock_issue]
         mock_jira.return_value.priorities.return_value = [mock_priority]
         mock_jira.return_value.fields.return_value = []
@@ -159,6 +165,8 @@ def test_jira(caplog):
             mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
         mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
         mock_jira.return_value = mock.Mock()
+        # Mock both search methods
+        mock_jira.return_value.enhanced_search_issues.return_value = [mock_issue]
         mock_jira.return_value.search_issues.return_value = [mock_issue]
         mock_jira.return_value.priorities.return_value = [mock_priority]
         mock_jira.return_value.fields.return_value = []
@@ -194,6 +202,8 @@ def test_jira(caplog):
                 mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
             mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
             mock_jira.return_value = mock.Mock()
+            # Mock both search methods
+            mock_jira.return_value.enhanced_search_issues.return_value = [mock_issue]
             mock_jira.return_value.search_issues.return_value = [mock_issue]
             mock_jira.return_value.fields.return_value = mock_fields
             mock_jira.return_value.priorities.return_value = [mock_priority]
@@ -490,3 +500,159 @@ def test_create_subtask(caplog):
     assert 'elastalert' == user
     assert logging.INFO == level
     assert 'pened Jira ticket:' in message
+
+
+def test_jira_enhanced_search_when_available():
+    """Test that enhanced_search_issues is used when available"""
+    rule = {
+        'name': 'test alert',
+        'jira_account_file': 'jirafile',
+        'type': mock_rule(),
+        'jira_project': 'testproject',
+        'jira_priority': 0,
+        'jira_issuetype': 'testtype',
+        'jira_server': 'https://test.atlassian.net',
+        'jira_bump_tickets': True,
+        'jira_max_age': 30,
+        'timestamp_field': '@timestamp',
+        'rule_file': '/tmp/foo.yaml'
+    }
+
+    mock_priority = mock.Mock(id='5')
+    mock_issue = mock.Mock()
+    mock_issue.key = 'TEST-123'
+
+    with mock.patch('elastalert.alerters.jira.JIRA') as mock_jira, \
+            mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
+
+        mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
+        mock_jira.return_value.priorities.return_value = [mock_priority]
+        mock_jira.return_value.fields.return_value = []
+
+        # Mock enhanced_search_issues method
+        mock_jira.return_value.enhanced_search_issues = mock.Mock(return_value=[mock_issue])
+
+        alert = JiraAlerter(rule)
+        result = alert.find_existing_ticket([{'test': 'value', '@timestamp': '2014-10-31T00:00:00'}])
+
+        # Verify enhanced_search_issues was called
+        assert mock_jira.return_value.enhanced_search_issues.called
+        call_args = mock_jira.return_value.enhanced_search_issues.call_args
+        assert 'project=testproject' in call_args[0][0]  # First positional argument
+
+        # Verify legacy search was NOT called
+        assert not hasattr(mock_jira.return_value, 'search_issues') or not mock_jira.return_value.search_issues.called
+
+        # Verify the result
+        assert result is not None
+        assert result.key == 'TEST-123'
+
+
+def test_jira_enhanced_search_not_available_error():
+    """Test that Jira alerter raises error when enhanced_search_issues is not available"""
+    rule = {
+        'name': 'test alert',
+        'jira_account_file': 'jirafile',
+        'type': mock_rule(),
+        'jira_project': 'testproject',
+        'jira_priority': 0,
+        'jira_issuetype': 'testtype',
+        'jira_server': 'https://test.atlassian.net',
+        'jira_bump_tickets': True,
+        'jira_max_age': 30,
+        'timestamp_field': '@timestamp',
+        'rule_file': '/tmp/foo.yaml'
+    }
+
+    mock_priority = mock.Mock(id='5')
+
+    with mock.patch('elastalert.alerters.jira.JIRA') as mock_jira, \
+            mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
+
+        mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
+        mock_jira.return_value.priorities.return_value = [mock_priority]
+        mock_jira.return_value.fields.return_value = []
+
+        # Simulate enhanced_search_issues not being available
+        if hasattr(mock_jira.return_value, 'enhanced_search_issues'):
+            delattr(mock_jira.return_value, 'enhanced_search_issues')
+
+        alert = JiraAlerter(rule)
+
+        # Should raise EAException when enhanced_search_issues is not available
+        with pytest.raises(EAException, match="enhanced_search_issues method not available"):
+            alert.find_existing_ticket([{'test': 'value', '@timestamp': '2014-10-31T00:00:00'}])
+
+
+def test_jira_error_handling():
+    """Test error handling when search methods throw exceptions"""
+    rule = {
+        'name': 'test alert',
+        'jira_account_file': 'jirafile',
+        'type': mock_rule(),
+        'jira_project': 'testproject',
+        'jira_priority': 0,
+        'jira_issuetype': 'testtype',
+        'jira_server': 'https://test.atlassian.net',
+        'jira_bump_tickets': True,
+        'jira_max_age': 30,
+        'timestamp_field': '@timestamp',
+        'rule_file': '/tmp/foo.yaml'
+    }
+
+    mock_priority = mock.Mock(id='5')
+
+    with mock.patch('elastalert.alerters.jira.JIRA') as mock_jira, \
+            mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
+
+        mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
+        mock_jira.return_value.priorities.return_value = [mock_priority]
+        mock_jira.return_value.fields.return_value = []
+
+        # Mock enhanced_search_issues to raise an exception
+        mock_jira.return_value.enhanced_search_issues = mock.Mock(side_effect=JIRAError("API Error"))
+
+        alert = JiraAlerter(rule)
+        result = alert.find_existing_ticket([{'test': 'value', '@timestamp': '2014-10-31T00:00:00'}])
+
+        # Verify enhanced_search_issues was called but returned None due to error
+        assert mock_jira.return_value.enhanced_search_issues.called
+        assert result is None
+
+
+def test_jira_no_results():
+    """Test that search returns None when no tickets are found"""
+    rule = {
+        'name': 'test alert',
+        'jira_account_file': 'jirafile',
+        'type': mock_rule(),
+        'jira_project': 'testproject',
+        'jira_priority': 0,
+        'jira_issuetype': 'testtype',
+        'jira_server': 'https://test.atlassian.net',
+        'jira_bump_tickets': True,
+        'jira_max_age': 30,
+        'timestamp_field': '@timestamp',
+        'rule_file': '/tmp/foo.yaml'
+    }
+
+    mock_priority = mock.Mock(id='5')
+
+    with mock.patch('elastalert.alerters.jira.JIRA') as mock_jira, \
+            mock.patch('elastalert.alerters.jira.read_yaml') as mock_open:
+
+        mock_open.return_value = {'user': 'jirauser', 'password': 'jirapassword'}
+        mock_jira.return_value.priorities.return_value = [mock_priority]
+        mock_jira.return_value.fields.return_value = []
+
+        # Mock enhanced_search_issues to return empty list
+        mock_jira.return_value.enhanced_search_issues = mock.Mock(return_value=[])
+
+        alert = JiraAlerter(rule)
+        result = alert.find_existing_ticket([{'test': 'value', '@timestamp': '2014-10-31T00:00:00'}])
+
+        # Verify enhanced_search_issues was called
+        assert mock_jira.return_value.enhanced_search_issues.called
+
+        # Verify no result was returned
+        assert result is None