@pipedream/zendesk 0.6.1 → 0.7.1

package/README.md

@@ -1,19 +1,94 @@
 # Overview
 
-Using the Zendesk API, you can build custom apps and integrations to automate
-processes and help your teams build better customer relationships.
-
-The API provides a range of methods to interact with your customer help desk,
-customer data, and customer communication tools. This enables you to create
-custom customer experiences that are tailored to your business needs.
-
-Some examples of what you can build using the Zendesk API include:
-
-- Create a custom customer feedback widget
-- Automate customer service processes
-- Identify customer trends and insights
-- Help manage customer data in real-time
-- Create a custom customer profile and segmentation tool
-- Trigger automated messages based on customer events
-- Integrate customer service processes with your company’s backend system
-- Create a custom customer self-service portal
+The Zendesk API enables seamless integration of Zendesk's customer service platform with your existing business processes and third-party applications. By leveraging this API with Pipedream, you can automate ticket tracking, sync customer data, escalate issues, and streamline communication across multiple channels. This can significantly increase efficiency, accelerate response times, and enhance the overall customer experience. Automations can range from simple notifications to complex workflows involving data transformation and multi-step actions across various services.
+
+# Example Use Cases
+
+**Ticket Management Automation**
+Automatically create Zendesk tickets from emails, chat messages, or form submissions captured in other apps like Gmail or Slack. Use Pipedream to parse the incoming information and create a ticket in Zendesk with the appropriate tags, priorities, and assignments.
+
+**Customer Feedback Loop**
+After a ticket is resolved, trigger a workflow to send a follow-up survey using a platform like Typeform. Record responses back in Zendesk to ensure customer feedback influences service quality. An automated workflow could tag the ticket with the feedback score or add notes for support agents.
+
+**Real-Time Notifications for Critical Issues**
+Set up a Pipedream workflow that monitors Zendesk for tickets with 'Urgent' priority or specific keywords and sends instant notifications to a dedicated Slack channel or via SMS through Twilio. This ensures that critical issues are promptly addressed by support teams.
+
+# Getting Started
+
+First, log in to your [Pipedream workspace](https://pipedream.com), then connect Zendesk either through a step or trigger in a workflow, or directly from the Connected Accounts page in Pipedream.
+
+You'll first be prompted to enter your Zendesk subdomain. You can find this in the URL after logging into Zendesk.
+
+The subdomain is the portion of the URL *before* `zendesk.com`. 
+
+For example, if the subdomain is `pipedream1903`, that's what you would enter in Pipedream.
+
+![Example of finding the Zendesk subdomain from the URL while logged into Zendesk](https://res.cloudinary.com/pipedreamin/image/upload/v1715183755/marketplace/apps/zendesk/CleanShot_2024-05-08_at_11.44.08_2x_ogzhhj.png)
+
+Next, you'll be prompted to connect your Zendesk account. Zendesk will ask if you'd like to grant Pipedream permission to perform actions on your account; accept these permissions to continue.
+
+And that's it! You can now automate Zendesk actions from within Pipedream workflows.
+
+# Troubleshooting
+
+## Status Codes
+Responses may have the status codes described in the following sections.
+
+### 200 range
+The request was successful. The status is 200 for successful GET and PUT requests, 201 for most POST requests, and 204 for DELETE requests.
+
+### 400 range
+The request was not successful. The content type of the response may be text/plain for API-level error messages such as trying to call the API without SSL. The content type is application/json for business-level error messages because the response includes a JSON object with information about the error:
+
+```json
+{
+  "details": {
+    "value": [
+      {
+        "type": "blank",
+        "description": "can't be blank"
+      },
+      {
+        "type": "invalid",
+        "description": " is not properly formatted"
+      }
+    ]
+  },
+  "description": "RecordValidation errors",
+  "error": "RecordInvalid"
+}
+```
+
+If you see a response from a known endpoint that looks like plain text, you probably made a syntax error in your request. This type of response commonly occurs when making a request to a nonexistent Zendesk Support instance.
+
+### **403**
+
+A 403 response means the server has determined the user or the account doesn’t have the required permissions to use the API.
+
+### **409**
+
+A 409 response indicates a conflict with the resource you're trying to create or update.
+
+409 errors typically occur when two or more requests try to create or change the same resource simultaneously. While Zendesk APIs can handle concurrent requests, requests shouldn't change the same resource at the same time. To avoid 409 errors, serialize requests when possible. If you receive a 409 error, you can retry your request after resolving the conflict.
+
+The Zendesk Ticketing API provides specific parameters to prevent conflicts when updating tickets. For more information, see Protecting against ticket update collisions.
+
+### **422 Unprocessable Entity**
+
+A 422 response means that the content type and the syntax of the request entity are correct, but the content itself is not processable by the server. This is usually due to the request entity not being relevant to the resource that it's trying to create or update. Example: Trying to close a ticket that's already closed.
+
+### **429**
+
+A 429 error indicates that a usage limit has been exceeded. See the [Zendesk Rate limits](https://developer.zendesk.com/api-reference/introduction/rate-limits/).
+
+### **500 range**
+
+If you ever experience responses with status codes in the 500 range, the Zendesk API may be experiencing internal issues or having a scheduled maintenance during which you might receive a 503 Service Unavailable status code.
+
+A 503 response with a `Retry-After` header indicates a database timeout or deadlock. You can retry your request after the number of seconds specified in the `Retry-After` header.
+
+If the 503 response doesn't have a Retry-After header, Zendesk Support may be experiencing internal issues or undergoing scheduled maintenance. In such cases, check `@zendeskops` and our status page for any known issues.
+
+When building an API client, we recommend treating any 500 status codes as a warning or temporary state. However, if the status persists and if Zendesk doesn't have a publicly announced maintenance or service disruption, contact the [Zendesk Customer Support](https://support.zendesk.com/hc/en-us/articles/360026614173).
+
+If submitting a ticket to Zendesk, provide the `X-Zendesk-Request-Id` header included in the HTTP response. This helps the Support team track down the request in the logs more quickly.

package/actions/create-ticket/create-ticket.mjs

@@ -5,7 +5,7 @@ export default {
   name: "Create Ticket",
   description: "Creates a ticket. [See the documentation](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#create-ticket).",
   type: "action",
-  version: "0.1.2",
+  version: "0.1.4",
   props: {
     app,
     ticketCommentBody: {

package/actions/delete-ticket/delete-ticket.mjs

@@ -5,7 +5,7 @@ export default {
   name: "Delete Ticket",
   description: "Deletes a ticket. [See the documentation](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#delete-ticket).",
   type: "action",
-  version: "0.1.2",
+  version: "0.1.4",
   props: {
     app,
     ticketId: {

package/actions/get-ticket-info/get-ticket-info.mjs

@@ -0,0 +1,40 @@
+import app from "../../zendesk.app.mjs";
+
+export default {
+  key: "zendesk-get-ticket-info",
+  name: "Get Ticket Info",
+  description: "Retrieves information about a specific ticket. [See the documentation](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#show-ticket).",
+  type: "action",
+  version: "0.0.2",
+  props: {
+    app,
+    ticketId: {
+      propDefinition: [
+        app,
+        "ticketId",
+      ],
+    },
+    customSubdomain: {
+      propDefinition: [
+        app,
+        "customSubdomain",
+      ],
+    },
+  },
+  async run({ $: step }) {
+    const {
+      ticketId,
+      customSubdomain,
+    } = this;
+
+    const response = await this.app.getTicketInfo({
+      step,
+      ticketId,
+      customSubdomain,
+    });
+
+    step.export("$summary", `Successfully retrieved ticket with ID ${response.ticket.id}`);
+
+    return response;
+  },
+};

package/actions/list-tickets/list-tickets.mjs

@@ -0,0 +1,67 @@
+import app from "../../zendesk.app.mjs";
+
+export default {
+  key: "zendesk-list-tickets",
+  name: "List Tickets",
+  description: "Retrieves a list of tickets. [See the documentation](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#list-tickets).",
+  type: "action",
+  version: "0.0.2",
+  props: {
+    app,
+    sortBy: {
+      propDefinition: [
+        app,
+        "sortBy",
+      ],
+    },
+    sortOrder: {
+      propDefinition: [
+        app,
+        "sortOrder",
+      ],
+    },
+    limit: {
+      propDefinition: [
+        app,
+        "limit",
+      ],
+    },
+    customSubdomain: {
+      propDefinition: [
+        app,
+        "customSubdomain",
+      ],
+    },
+  },
+  async run({ $: step }) {
+    const {
+      sortBy,
+      sortOrder,
+      limit,
+      customSubdomain,
+    } = this;
+
+    const results = this.app.paginate({
+      fn: this.app.listTickets,
+      args: {
+        step,
+        customSubdomain,
+        params: {
+          sort_by: sortBy,
+          sort_order: sortOrder,
+        },
+      },
+      resourceKey: "tickets",
+      max: limit,
+    });
+
+    const tickets = [];
+    for await (const ticket of results) {
+      tickets.push(ticket);
+    }
+
+    step.export("$summary", `Successfully retrieved ${tickets.length} tickets`);
+
+    return tickets;
+  },
+};

package/actions/search-tickets/search-tickets.mjs

@@ -0,0 +1,74 @@
+import app from "../../zendesk.app.mjs";
+
+export default {
+  key: "zendesk-search-tickets",
+  name: "Search Tickets",
+  description: "Searches for tickets using Zendesk's search API. [See the documentation](https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#search-tickets).",
+  type: "action",
+  version: "0.0.2",
+  props: {
+    app,
+    query: {
+      type: "string",
+      label: "Search Query",
+      description: "The search query to find tickets. You can use Zendesk's search syntax. Example: `type:ticket status:open priority:high`. [See the documentation](https://developer.zendesk.com/documentation/ticketing/using-the-zendesk-api/searching-with-the-zendesk-api/)",
+    },
+    sortBy: {
+      propDefinition: [
+        app,
+        "sortBy",
+      ],
+    },
+    sortOrder: {
+      propDefinition: [
+        app,
+        "sortOrder",
+      ],
+    },
+    limit: {
+      propDefinition: [
+        app,
+        "limit",
+      ],
+    },
+    customSubdomain: {
+      propDefinition: [
+        app,
+        "customSubdomain",
+      ],
+    },
+  },
+  async run({ $: step }) {
+    const {
+      query,
+      sortBy,
+      sortOrder,
+      limit,
+      customSubdomain,
+    } = this;
+
+    const results = this.app.paginate({
+      fn: this.app.searchTickets,
+      args: {
+        step,
+        customSubdomain,
+        params: {
+          query,
+          sort_by: sortBy,
+          sort_order: sortOrder,
+        },
+      },
+      resourceKey: "results",
+      max: limit,
+    });
+
+    const tickets = [];
+    for await (const ticket of results) {
+      tickets.push(ticket);
+    }
+
+    step.export("$summary", `Successfully found ${tickets.length} tickets matching the search query`);
+
+    return tickets;
+  },
+};

package/actions/update-ticket/update-ticket.mjs

@@ -5,7 +5,7 @@ export default {
   name: "Update Ticket",
   description: "Updates a ticket. [See the documentation](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#update-ticket).",
   type: "action",
-  version: "0.1.2",
+  version: "0.1.4",
   props: {
     app,
     ticketId: {
@@ -20,6 +20,12 @@ export default {
         "ticketCommentBody",
       ],
     },
+    ticketCommentBodyIsHTML: {
+      propDefinition: [
+        app,
+        "ticketCommentBodyIsHTML",
+      ],
+    },
     ticketPriority: {
       propDefinition: [
         app,
@@ -38,6 +44,12 @@ export default {
         "ticketStatus",
       ],
     },
+    ticketCommentPublic: {
+      propDefinition: [
+        app,
+        "ticketCommentPublic",
+      ],
+    },
     customSubdomain: {
       propDefinition: [
         app,
@@ -59,21 +71,31 @@ export default {
     const {
       ticketId,
       ticketCommentBody,
+      ticketCommentBodyIsHTML,
       ticketPriority,
       ticketSubject,
       ticketStatus,
+      ticketCommentPublic,
       customSubdomain,
     } = this;
 
+    const ticketComment = ticketCommentBodyIsHTML
+      ? {
+        html_body: ticketCommentBody,
+      }
+      : {
+        body: ticketCommentBody,
+      };
+
+    ticketComment.public = ticketCommentPublic;
+
     const response = await this.updateTicket({
       step,
       ticketId,
       customSubdomain,
       data: {
         ticket: {
-          comment: {
-            body: ticketCommentBody,
-          },
+          comment: ticketComment,
           priority: ticketPriority,
           subject: ticketSubject,
           status: ticketStatus,

package/common/constants.mjs

@@ -222,6 +222,19 @@ const TICKET_FIELD_OPTIONS = [
   },
 ];
 
+const SORT_BY_OPTIONS = [
+  "assignee",
+  "assignee.name",
+  "created_at",
+  "group",
+  "id",
+  "requester",
+  "requester.name",
+  "status",
+  "subject",
+  "updated_at",
+];
+
 export default {
   SUBDOMAIN_PLACEHOLDER,
   BASE_URL,
@@ -242,4 +255,5 @@ export default {
   TICKET_PRIORITY_OPTIONS,
   TICKET_STATUS_OPTIONS,
   TICKET_FIELD_OPTIONS,
+  SORT_BY_OPTIONS,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/zendesk",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Pipedream Zendesk Components",
   "main": "zendesk.app.mjs",
   "keywords": [
@@ -14,7 +14,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pipedream/platform": "^0.9.0",
+    "@pipedream/platform": "^3.0.3",
     "crypto": "^1.0.1"
   }
 }

package/sources/new-ticket/new-ticket.mjs

@@ -6,7 +6,7 @@ export default {
   key: "zendesk-new-ticket",
   type: "source",
   description: "Emit new event when a ticket is created",
-  version: "0.2.2",
+  version: "0.2.4",
   dedupe: "unique",
   methods: {
     ...common.methods,

package/sources/ticket-added-to-view/ticket-added-to-view.mjs

@@ -5,7 +5,7 @@ export default {
   key: "zendesk-ticket-added-to-view",
   name: "New Ticket Added to View (Instant)",
   description: "Emit new event when a ticket is added to the specified view",
-  version: "0.0.2",
+  version: "0.0.4",
   type: "source",
   dedupe: "unique",
   props: {

package/sources/ticket-closed/ticket-closed.mjs

@@ -6,7 +6,7 @@ export default {
   key: "zendesk-ticket-closed",
   type: "source",
   description: "Emit new event when a ticket has changed to closed status",
-  version: "0.2.2",
+  version: "0.2.4",
   dedupe: "unique",
   methods: {
     ...common.methods,

package/sources/ticket-pended/ticket-pended.mjs

@@ -6,7 +6,7 @@ export default {
   key: "zendesk-ticket-pended",
   type: "source",
   description: "Emit new event when a ticket has changed to pending status",
-  version: "0.2.2",
+  version: "0.2.4",
   dedupe: "unique",
   methods: {
     ...common.methods,

package/sources/ticket-solved/ticket-solved.mjs

@@ -6,7 +6,7 @@ export default {
   key: "zendesk-ticket-solved",
   type: "source",
   description: "Emit new event when a ticket has changed to solved status",
-  version: "0.2.2",
+  version: "0.2.4",
   dedupe: "unique",
   methods: {
     ...common.methods,

package/sources/ticket-updated/ticket-updated.mjs

@@ -6,7 +6,7 @@ export default {
   key: "zendesk-ticket-updated",
   type: "source",
   description: "Emit new event when a ticket has been updated",
-  version: "0.2.2",
+  version: "0.2.4",
   dedupe: "unique",
   methods: {
     ...common.methods,

package/zendesk.app.mjs

@@ -9,6 +9,7 @@ export default {
       type: "string",
       label: "Trigger Category ID",
       description: "The ID of the trigger category. [See the docs here](https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#list-trigger-categories)",
+      optional: true,
       async options({ prevContext }) {
         const { afterCursor } = prevContext;
 
@@ -124,6 +125,13 @@ export default {
       label: "Comment body",
       description: "The body of the comment.",
     },
+    ticketCommentBodyIsHTML: {
+      type: "boolean",
+      label: "Comment body is HTML",
+      description: "Whether the comment body is HTML. Default is `false`, which expects Markdown",
+      default: false,
+      optional: true,
+    },
     ticketPriority: {
       type: "string",
       label: "Ticket Priority",
@@ -144,6 +152,37 @@ export default {
       optional: true,
       options: Object.values(constants.TICKET_STATUS_OPTIONS),
     },
+    ticketCommentPublic: {
+      type: "boolean",
+      label: "Comment Public",
+      description: "Whether the comment is public. Default is `true`",
+      default: true,
+      optional: true,
+    },
+    sortBy: {
+      type: "string",
+      label: "Sort By",
+      description: "Field to sort tickets by",
+      optional: true,
+      options: constants.SORT_BY_OPTIONS,
+    },
+    sortOrder: {
+      type: "string",
+      label: "Sort Order",
+      description: "Sort order (ascending or descending)",
+      optional: true,
+      options: [
+        "asc",
+        "desc",
+      ],
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: "Maximum number of tickets to return",
+      optional: true,
+      default: 100,
+    },
     customSubdomain: {
       type: "string",
       label: "Custom Subdomain",
@@ -181,6 +220,20 @@ export default {
       };
       return axios(step, config);
     },
+    getTicketInfo({
+      ticketId, ...args
+    } = {}) {
+      return this.makeRequest({
+        path: `/tickets/${ticketId}`,
+        ...args,
+      });
+    },
+    searchTickets(args = {}) {
+      return this.makeRequest({
+        path: "/search",
+        ...args,
+      });
+    },
     create(args = {}) {
       return this.makeRequest({
         method: "post",
@@ -231,5 +284,36 @@ export default {
         ...args,
       });
     },
+    async *paginate({
+      fn, args, resourceKey, max,
+    }) {
+      args = {
+        ...args,
+        params: {
+          ...args?.params,
+          per_page: constants.DEFAULT_LIMIT,
+          page: 1,
+        },
+      };
+      let hasMore = true;
+      let count = 0;
+      while (hasMore) {
+        const response = await fn(args);
+        const items = resourceKey
+          ? response[resourceKey]
+          : response;
+        if (!items?.length) {
+          return;
+        }
+        for (const item of items) {
+          yield item;
+          if (max && ++count >= max) {
+            return;
+          }
+        }
+        hasMore = !!response.next_page;
+        args.params.page += 1;
+      }
+    },
   },
 };