Zendesk v2 permissions documentations (#24420)

* added to Readme * commit * changed the test module to pass if one of the requests to zendesk passes. * small changes * updated release notes * Apply suggestions from code review Co-authored-by: ShirleyDenkberg <62508050+ShirleyDenkberg@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: gal-forer <forer.gal@gmail.com> * added some documentation * modified the description * updated docker and add Deprecated to the display * commit * changed description file name * commit * Fixed issue with the name of the classifiers folder * Fixed the RN for the missplled classifiers folder * mypy handeling * commit * updated docker image * reverted unrelated changes --------- Co-authored-by: ShirleyDenkberg <62508050+ShirleyDenkberg@users.noreply.github.com> Co-authored-by: gal-forer <forer.gal@gmail.com>
demisto · Feb 14, 2023 · 3691bf8 · 3691bf8
1 parent c491791
commit 3691bf8
Show file tree

Hide file tree

Showing 8 changed files with 124 additions and 36 deletions.
diff --git a/...classifier-Zendesk_-_Incoming_Mapper.json → ...classifier-Zendesk_-_Incoming_Mapper.json b/...classifier-Zendesk_-_Incoming_Mapper.json → ...classifier-Zendesk_-_Incoming_Mapper.json
diff --git a/Packs/Zendesk/Integrations/Zendesk/Zendesk.yml b/Packs/Zendesk/Integrations/Zendesk/Zendesk.yml
@@ -1,10 +1,11 @@
 commonfields:
   id: Zendesk
   version: -1
+deprecated: true
 name: Zendesk
-display: Zendesk
+display: Zendesk - (Deprecated)
 category: Case Management
-description: IT service management
+description: Deprecated. Use the Zendesk v2 integration instead.
 configuration:
 - display: Zendesk address (e.g. https://demisto.zendesk.com)
   name: url

diff --git a/Packs/Zendesk/Integrations/Zendeskv2/README.md b/Packs/Zendesk/Integrations/Zendeskv2/README.md
@@ -1,5 +1,3 @@
-IT service management
-
 Some changes have been made that might affect your existing content. 
 If you are upgrading from a previous of this integration, see [Breaking Changes](#breaking-changes-from-the-previous-version-of-this-integration-zendesk-v2).
 
@@ -26,13 +24,22 @@ If you are upgrading from a previous of this integration, see [Breaking Changes]
     | Use system proxy settings |  | False |
     | Trust any certificate (not secure) |  | False |
 
-4. Click **Test** to validate the URLs, token, and connection.
+4. Click **Test** to validate the URLs, token, and connection. 
+    (The test does not ensure sufficient permissions for all integration commands.)
 ## Commands
 You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
 After you successfully execute a command, a DBot message appears in the War Room with the command details.
+
+## Required permissions
+This integration enables executing commands with different permission levels. See the commands' descriptions for more information on the required permission. 
+To learn more on Zendesk roles refer to:
+[Understanding Zendesk Support user roles](https://support.zendesk.com/hc/en-us/articles/4408883763866-Understanding-Zendesk-Support-user-roles#topic_ibd_fdq_cc)
+[About team member product roles and access](https://support.zendesk.com/hc/en-us/articles/4408832171034)
+
 ### zendesk-user-list
 ***
-Gets the specified user's data.
+Gets the specified user's data. 
+Required permissions: Admins, Agents and Light Agents.
 
 
 #### Base Command
@@ -43,7 +50,7 @@ Gets the specified user's data.
 | **Argument Name** | **Description** | **Required** |
 | --- | --- | --- |
 | user_id | The user's ID to retrieve. | Optional | 
-| user_name | The user's name. | Optional | 
+| user_name | The user's name. <br/>Required permissions to use this argument: Agents . | Optional | 
 | external_id | The user's unique identifier from another system. | Optional | 
 | role | The user's role. Possible values are: end_user, agent, admin. | Optional | 
 | limit | Maximum number of results to return. Default is 50. | Optional | 
@@ -94,7 +101,8 @@ Gets the specified user's data.
 
 ### zendesk-user-create
 ***
-Creates a new Zendesk user.
+Creates a new Zendesk user. 
+Required permissions: Agents, with restrictions on certain actions.
 
 
 #### Base Command
@@ -168,7 +176,8 @@ Creates a new Zendesk user.
 
 ### zendesk-user-update
 ***
-Update user data.
+Update user data. 
+Required permissions: Agents, with restrictions on certain actions.
 
 
 #### Base Command
@@ -243,7 +252,8 @@ Update user data.
 
 ### zendesk-user-delete
 ***
-Delete a user.
+Delete a user. 
+Required permissions: Admins.
 
 
 #### Base Command
@@ -261,7 +271,10 @@ Delete a user.
 There is no context output for this command.
 ### zendesk-organization-list
 ***
-Get organization's data.
+Get organization's data. 
+Required permissions: Agents, with certain restrictions. 
+If the agent has a custom agent role that restricts the agent's access to only users in their own organization,
+a 403 Forbidden error is returned. See Creating custom agent roles in Zendesk help.
 
 
 #### Base Command
@@ -271,7 +284,7 @@ Get organization's data.
 
 | **Argument Name** | **Description** | **Required** |
 | --- | --- | --- |
-| organization_id | The ID of a specific organization. | Optional | 
+| organization_id | The ID of a specific organization. <br/>Required permissions: Admins, Agents.  | Optional | 
 | limit | Maximum number of results to return. Default is 50. | Optional | 
 | page_size | The page size (used for pagination). | Optional | 
 | page_number | The page number (used for pagination). | Optional | 
@@ -297,7 +310,8 @@ Get organization's data.
 
 ### zendesk-ticket-list
 ***
-List Zendesk tickets.
+List Zendesk tickets. 
+Required permissions: Agents. 
 
 
 #### Base Command
@@ -363,6 +377,7 @@ List Zendesk tickets.
 ### zendesk-ticket-create
 ***
 Create a new zendesk ticket.
+Required permissions: Agents.
 
 
 #### Base Command
@@ -441,6 +456,7 @@ Create a new zendesk ticket.
 ### zendesk-ticket-update
 ***
 Updates a Zendesk ticket.
+Required permissions: Agents.
 
 
 #### Base Command
@@ -513,7 +529,10 @@ Updates a Zendesk ticket.
 
 ### zendesk-ticket-delete
 ***
-Delete ticket.
+Delete ticket. 
+Required permissions: Admins, Agents with permission to delete tickets.
+Agent delete permissions are set in Support.
+See Deleting tickets in the Zendesk Support Help Center.
 
 
 #### Base Command
@@ -532,6 +551,7 @@ There is no context output for this command.
 ### zendesk-ticket-comment-list
 ***
 List comments for a given ticket.
+Required permissions: Agents.
 
 
 #### Base Command
@@ -576,6 +596,7 @@ List comments for a given ticket.
 ### zendesk-ticket-attachment-add
 ***
 Attach file to ticket.
+Required permissions: End users.
 
 
 #### Base Command
@@ -597,6 +618,7 @@ There is no context output for this command.
 ### zendesk-attachment-get
 ***
 Get attachment.
+Required permissions: Admins.
 
 
 #### Base Command
@@ -639,6 +661,7 @@ Search in Zendesk.
 ### zendesk-article-list
 ***
 List all available articles.
+Required permissions: Agents, End users, Anonymous users.
 
 
 #### Base Command

diff --git a/Packs/Zendesk/Integrations/Zendeskv2/Zendeskv2.py b/Packs/Zendesk/Integrations/Zendeskv2/Zendeskv2.py
@@ -305,7 +305,7 @@ def query_params(self):
 
         params = super(CreatedTickets, self).query_params()
         if not params:
-            params['start_time'] = int(dateparser.parse(
+            params['start_time'] = int(dateparser.parse(        # type: ignore
                 self._demisto_params.get('first_fetch', '3d')
             ).timestamp())
 
@@ -856,10 +856,16 @@ def zendesk_article_list(self, locale: Optional[str] = '', article_id: Optional[
     # ---- demisto releated functions ---- #
 
     def test_module(self):  # pragma: no cover
+        exception: Exception
+        # If one of the endpoints work we will pass the test_module check.
         for data_type in ['tickets', 'users', 'organizations']:
-            self._paged_request(url_suffix=data_type, data_field_name=data_type, limit=1)
-        UpdatedTickets(self, 0).tickets().__next__()
-        return 'ok'
+            try:
+                self._paged_request(url_suffix=data_type, data_field_name=data_type, limit=1)
+                return 'ok'
+            except Exception as e:
+                exception = e
+
+        raise exception from None
 
     @staticmethod
     def _ticket_to_incident(ticket: Dict):
@@ -924,7 +930,7 @@ def _create_entry_from_comment(comment: Dict):
     def get_remote_data(self, **kwargs):
         try:
             parsed_args = GetRemoteDataArgs(kwargs)
-            last_update = datetime_to_iso(dateparser.parse(parsed_args.last_update, settings={'TIMEZONE': 'UTC'}))
+            last_update = datetime_to_iso(dateparser.parse(parsed_args.last_update, settings={'TIMEZONE': 'UTC'}))  # type: ignore
             try:
                 ticket_data = self._get_ticket_by_id(parsed_args.remote_incident_id)
             except HTTPError as e:

diff --git a/Packs/Zendesk/Integrations/Zendeskv2/Zendeskv2.yml b/Packs/Zendesk/Integrations/Zendeskv2/Zendeskv2.yml
@@ -90,13 +90,17 @@ script:
   type: python
   commands:
   - name: zendesk-user-list
-    description: Gets the specified user's data.
+    description: |-
+      Gets the specified user's data. 
+      Required permissions: Admins, Agents and Light Agents.
     arguments:
     - name: user_id
       isArray: true
       description: The user's ID to retrieve.
     - name: user_name
-      description: The user's name.
+      description: |-
+        The user's name. 
+        Required permissions to use this argument: Agents. 
     - name: external_id
       description: The user's unique identifier from another system.
     - name: role
@@ -223,7 +227,9 @@ script:
       type: boolean
       description: Whether any of the user's identities is verified.
   - name: zendesk-user-create
-    description: Creates a new Zendesk user.
+    description: |-
+      Creates a new Zendesk user. 
+      Required permissions: Agents, with restrictions on certain actions.
     arguments:
     - name: name
       required: true
@@ -400,7 +406,9 @@ script:
       type: boolean
       description: Whether any of the user's identities is verified.
   - name: zendesk-user-update
-    description: Update user data.
+    description: |-
+      Update user data. 
+      Required permissions: Agents, with restrictions on certain actions.
     arguments:
     - name: user_id
       required: true
@@ -575,17 +583,25 @@ script:
       type: boolean
       description: Whether any of the user's identities is verified.
   - name: zendesk-user-delete
-    description: Delete a user.
+    description: |-
+      Delete a user. 
+      Required permissions: Admins. 
     arguments:
     - name: user_id
       required: true
       description: The ID of the user to delete.
     execution: true
   - name: zendesk-organization-list
-    description: Get organization's data.
+    description: |-
+      Get organization's data. 
+      Required permissions: Agents, with certain restrictions. 
+      If the agent has a custom agent role that restricts the agent's access to only users in their own organization,
+      a 403 Forbidden error is returned. See Creating custom agent roles in the Zendesk help.
     arguments:
     - name: organization_id
-      description: The ID of a specific organization.
+      description: |-
+        The ID of a specific organization. 
+        Required permissions: Admins, Agents. 
     - name: limit
       default: true
       description: Maximum number of results to return. Default is 50.
@@ -634,7 +650,9 @@ script:
       type: string
       description: The API URL of this organization.
   - name: zendesk-ticket-list
-    description: List Zendesk tickets.
+    description: |- 
+      List Zendesk tickets. 
+      Required permissions: Agents. 
     arguments:
     - name: query
       description: 'Query to search for tickets. For more information about the search syntax, see https://developer.zendesk.com/rest_api/docs/core/search. '
@@ -784,7 +802,9 @@ script:
       type: string
       description: The API URL of this ticket.
   - name: zendesk-ticket-create
-    description: Create a new zendesk ticket.
+    description: |-
+      Create a new Zendesk ticket.
+      Required permissions: Agents.
     arguments:
     - name: subject
       required: true
@@ -972,7 +992,9 @@ script:
       type: string
       description: The API URL of this ticket.
   - name: zendesk-ticket-update
-    description: Updates a Zendesk ticket.
+    description: |-
+      Updates a Zendesk ticket.
+      Required permissions: Agents.
     arguments:
     - name: ticket_id
       required: true
@@ -1141,13 +1163,19 @@ script:
       type: string
       description: The API URL of this ticket.
   - name: zendesk-ticket-delete
-    description: Delete ticket.
+    description: |-
+      Delete ticket. 
+      Required permissions: Admins, Agents with permission to delete tickets.
+      Agent delete permissions are set in Support.
+      See Deleting tickets in the Zendesk Support Help Center.
     arguments:
     - name: ticket_id
       required: true
       description: The ID of the ticket to delete.
   - name: zendesk-ticket-comment-list
-    description: List comments for a given ticket.
+    description: |-
+      List comments for a given ticket.
+      Required permissions: Agents.
     arguments:
     - name: ticket_id
       required: true
@@ -1223,7 +1251,9 @@ script:
       type: string
       description: Comment or VoiceComment.
   - name: zendesk-ticket-attachment-add
-    description: Attach file to ticket.
+    description: |-
+      Attach a file to a ticket.
+      Required permissions: End users.
     arguments:
     - name: ticket_id
       required: true
@@ -1240,7 +1270,9 @@ script:
       isArray: true
       description: The filename to upload. Default is the original filename.
   - name: zendesk-attachment-get
-    description: Get attachment.
+    description: |-
+      Get attachment.
+      Required permissions: Admins.
     arguments:
     - name: attachment_id
       required: true
@@ -1263,7 +1295,9 @@ script:
       type: unknown
       description: The search results.
   - name: zendesk-article-list
-    description: List all available articles.
+    description: |-
+      List all available articles.
+      Required permissions: Agents, End users, Anonymous users.
     arguments:
     - name: article_id
       isArray: true
@@ -1317,7 +1351,7 @@ script:
     description: Updates local incident changes in the remote incident. This method is only used for debugging purposes and will not update the current incident.
     execution: false
     name: update-remote-system
-  dockerimage: demisto/python3:3.10.7.35188
+  dockerimage: demisto/python3:3.10.10.47713
   isfetch: true
   runonce: false
   subtype: python3

diff --git a/Packs/Zendesk/Integrations/Zendeskv2/Zendeskv2_description.md b/Packs/Zendesk/Integrations/Zendeskv2/Zendeskv2_description.md
@@ -0,0 +1,11 @@
+Use the Zendesk V2 integration to perform operations related to users, tickets, attachments, and more. 
+
+### Required permissions
+This integration enables executing commands with different permission levels.
+**The Test button does not ensure sufficient permissions for all integration commands.**
+please look at the description of the command for more information on the required permission.
+To learn more about Zendesk roles refer to:
+[Understanding Zendesk Support user roles](https://support.zendesk.com/hc/en-us/articles/4408883763866-Understanding-Zendesk-Support-user-roles#topic_ibd_fdq_cc)
+[About team member product roles and access](https://support.zendesk.com/hc/en-us/articles/4408832171034)
+
+For more information about Zendesk V2 integration, see the [Integration documentation](https://xsoar.pan.dev/docs/reference/integrations/zendesk-v2)