Jira improve error messaging (demisto#41580)

* Add configuration error handling for bad cloud configurations

* bump version

* Update message strings and description

* Pre-commit fixes

* Improve url check

* update error messages

* add UT

* Apply suggestions from doc review

Co-authored-by: talihaff <[email protected]>

* Improve doc string for test_module

---------

Co-authored-by: talihaff <[email protected]>

Author: itssapir

Packs/Jira/.secrets-ignore

@@ -14,4 +14,5 @@ ATLASSIAN_AUTH_URL
 MagicMock
 epic_key
 https://yourcompany.atlassian.net
-https://dummy_url
+https://dummy_url
+https://test.atlassian.net.evil.com

Packs/Jira/Integrations/JiraV3/JiraV3.py

@@ -4,6 +4,7 @@
 from collections.abc import Callable
 from copy import deepcopy
 from mimetypes import guess_type
+from urllib.parse import urlparse
 
 
 import demistomock as demisto  # noqa: F401
@@ -3544,11 +3545,24 @@ def jira_test_authorization(client: JiraBaseClient, args: Dict[str, Any]) -> Com
     return CommandResults(readable_output="Successful connection.")
 
 
-def jira_test_module(client: JiraBaseClient) -> str:
-    """This method will return an error since in order for the user to test the connectivity of the instance,
-    they have to run a separate command, therefore, pressing the `test` button on the configuration screen will
-    show them the steps in order to test the instance.
+def jira_test_module(client: JiraBaseClient, params: Dict[str, Any]) -> str:
     """
+    Tests for basic configuration issues in the instance.
+    Tests the connectivity for basic authentication methods, otherwise provides users with further authentication instructions.
+    """
+    url = params.get("server_url", "").rstrip("/")
+    cloudid = params.get("cloud_id")
+
+    if is_jira_cloud_url(url) and not cloudid:
+        raise DemistoException(
+            "Cloud ID is required for Jira Cloud instances. Refer to the integration help section for more information."
+        )
+    if cloudid and url != "https://api.atlassian.com/ex/jira":
+        raise DemistoException(
+            "Jira Cloud instances must use the default Server URL: `https://api.atlassian.com/ex/jira`."
+            " Please update the Server URL in the instance configuration."
+        )
+
     if client.is_basic_auth or client.is_pat_auth:
         client.jira_test_instance_connection()  # raises on failure
         return "ok"
@@ -4745,6 +4759,59 @@ def validate_auth_params(username: str, api_key: str, client_id: str, client_sec
         raise DemistoException("To use OAuth 2.0, the 'Client ID' and 'Client Secret' parameters are mandatory.")
 
 
+def is_jira_cloud_url(url: str) -> bool:
+    """
+    Check if the given URL is a Jira Cloud Server URL.
+
+    Args:
+        url (str): The URL to parse.
+
+    Returns:
+        bool: True if the URL is a Jira Cloud URL, False otherwise.
+    """
+    try:
+        hostname = urlparse(url).hostname or ""
+        return hostname.endswith((".atlassian.net", ".atlassian.com"))
+
+    except (ValueError, AttributeError):
+        return False
+
+
+def add_config_error_messages(err: str, cloud_id: str, server_url: str) -> str:
+    """
+    Provide additional information for error messages that result from incorrect configurations.
+
+        Args:
+            err (str): The original error message.
+            cloud_id (str): The cloud ID.
+            server_url (str): The server URL.
+
+        Returns:
+            str: The error message with additional information if applicable.
+    """
+
+    if "404" in err and cloud_id and server_url.rstrip("/") != "https://api.atlassian.com/ex/jira":
+        err = f"""
+(Error 404) Jira Cloud instances must use the default Server URL: `https://api.atlassian.com/ex/jira`.
+Update the Server URL in the instance configuration and try again.
+
+
+Original error: {err}
+            """
+
+    elif "410" in err and not cloud_id and is_jira_cloud_url(server_url):
+        err = f"""
+(Error 410) The requested endpoint has been removed from Jira On-Prem.
+This appears to be a Jira Cloud instance. Please update the Cloud ID in the instance configuration and try again.
+Refer to the integration help section for more information.
+
+
+Original error: {err}
+            """
+
+    return err
+
+
 def main():  # pragma: no cover
     params: Dict[str, Any] = demisto.params()
     args = map_v2_args_to_v3(demisto.args())
@@ -4865,7 +4932,7 @@ def main():  # pragma: no cover
         demisto.debug(f"The configured Jira client is: {type(client)}")
 
         if command == "test-module":
-            return_results(jira_test_module(client=client))
+            return_results(jira_test_module(client=client, params=params))
         elif command in commands:
             return_results(commands[command](client, args))
         elif command == "fetch-incidents":
@@ -4920,7 +4987,9 @@ def main():  # pragma: no cover
             raise NotImplementedError(f"{command} command is not implemented.")
 
     except Exception as e:
-        return_error(str(e))
+        err = add_config_error_messages(str(e), cloud_id, server_url)
+
+        return_error(err)
 
 
 if __name__ in ["__main__", "builtin", "builtins"]:

Packs/Jira/Integrations/JiraV3/JiraV3_description.md

@@ -1,7 +1,9 @@
-Please configure only one of the following fields:
+Configure your Jira instance based on the type of your deployment:
 
-1. Cloud ID - Used for Jira Cloud instance.
-2. OnPrem - Leave the Cloud ID empty, and fill in the rest of the fields.
+| Deployment Type | Cloud ID | Server URL |
+|-----------------|----------|------------|
+| Jira Cloud | Cloud ID of your Jira instance (See below) | `https://api.atlassian.com/ex/jira` |
+| Jira OnPrem | Leave empty | Your Jira server URL |
 
 ##### Cloud ID
 
@@ -10,16 +12,19 @@ Please configure only one of the following fields:
 `https://admin.atlassian.com/s/{cloud_id}/users`
 
 #### Authentication Methods
+
 There are 2 authentication methods:
 - **Basic Authentication**
 - **OAuth 2.0**
 
 ### Basic Authentication
+
 Leave the *Client ID* and *Client Secret* fields empty and fill in the following fields:
 - *User name* - Enter your user email.
-- *API key* - Enter the API token. To generate API token, see [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
+- *API key* - Enter the API token. To generate an API token, see [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
 
 ##### Basic Authentication permissions
+
 Ensure that you possess the necessary permissions by navigating to **Project Settings** > **Permissions** in the project.
 Locate permissions for the tasks listed below:
 * Browse projects
@@ -31,7 +36,8 @@ Locate permissions for the tasks listed below:
 * Add comments
 * Link issues
 ### OAuth 2.0
-For both instances (Cloud ID & OnPrem), it is advised to use the `https://oproxy.demisto.ninja/authcode` **Callback URL**. The OProxy URL is a client side only web page that provides an easy interface to copy the obtained auth code from the authorization response to the integration configuration in the authorization flow steps. Optionally, if you don't want to use the OProxy URL, you can use a localhost URL on a port which is not used locally on your machine. For example: <http://localhost:9004>. You will then need to copy the code from the URL address bar in the response.
+
+For both instances (Cloud ID & OnPrem), use the `https://oproxy.demisto.ninja/authcode` **Callback URL**. The OProxy URL is a client side web page that provides an easy interface to copy the authorization code from the response to the integration configuration during the authorization flow. Optionally, if you don't want to use the OProxy URL, you can use a localhost URL on an unused local port, for example: <http://localhost:9004>. You will then need to copy the code from the URL address bar in the response.
 
 #### Cloud authentication
 

Packs/Jira/Integrations/JiraV3/JiraV3_test.py

@@ -303,7 +303,7 @@ def test_test_module_basic_auth(mocker):
 
     client = jira_base_client_mock("dummy_username", "dummy_api_key")
     mocker.patch.object(client, "jira_test_instance_connection")
-    assert jira_test_module(client) == "ok"
+    assert jira_test_module(client, params={}) == "ok"
 
 
 def test_test_module_pat(mocker):
@@ -319,7 +319,7 @@ def test_test_module_pat(mocker):
 
     client = jira_base_client_mock(pat="dummy_pat")
     mocker.patch.object(client, "jira_test_instance_connection")
-    assert jira_test_module(client) == "ok"
+    assert jira_test_module(client, params={}) == "ok"
 
 
 def test_module_oauth2(mocker):
@@ -336,7 +336,7 @@ def test_module_oauth2(mocker):
     client = jira_base_client_mock()
     mocker.patch.object(client, "jira_test_instance_connection")
     with pytest.raises(DemistoException, match="In order to authorize the instance, first run the command `!jira-oauth-start`."):
-        jira_test_module(client)
+        jira_test_module(client, params={})
 
 
 @pytest.mark.parametrize(
@@ -3579,3 +3579,28 @@ def test_get_remote_data_preview_command():
 
     # Validate interactions
     mock_client.get_issue.assert_called_once_with(issue_id_or_key="JIRA-123")
+
+
+@pytest.mark.parametrize(
+    "url, expected_is_cloud",
+    [
+        ("https://yourcompany.atlassian.net", True),
+        ("https://api.atlassian.com/ex/jira/", True),
+        ("https://www.callback.com", False),
+        ("https://test.atlassian.net.evil.com", False),
+        ("https://dummy_url", False),
+    ],
+)
+def test_is_jira_cloud_url(url, expected_is_cloud):
+    """
+    Given:
+        - Various URL strings including Jira Cloud URLs, on-premises URLs, and invalid URLs
+    When:
+        - Calling is_jira_cloud_url function
+    Then:
+        - Validate that True is returned for Jira Cloud URLs and False for others
+    """
+    from JiraV3 import is_jira_cloud_url
+
+    result = is_jira_cloud_url(url)
+    assert result == expected_is_cloud

Packs/Jira/ReleaseNotes/3_3_10.md

@@ -0,0 +1,6 @@
+
+#### Integrations
+
+##### Atlassian Jira v3
+
+- Improved error messages for some misconfigured instances.

Packs/Jira/pack_metadata.json

@@ -2,7 +2,7 @@
     "name": "Atlassian Jira",
     "description": "Use the Jira integration to manage issues and create Cortex XSOAR incidents from Jira projects.",
     "support": "xsoar",
-    "currentVersion": "3.3.9",
+    "currentVersion": "3.3.10",
     "author": "Cortex XSOAR",
     "url": "https://www.paloaltonetworks.com/cortex",
     "email": "",