Merge pull request #189 from stitchdata/zendesk-sla-policies-table

Zendesk/v1: Add sla_policies table & replication requirements

_integration-schemas/zendesk/foreign-keys.md

@@ -55,6 +55,13 @@ foreign-keys:
       - table: "users"
         join-on: "id"
 
+  - id: "sla-policy-id"
+    attribute: "sla_policy_id"
+    table: ""
+    all-foreign-keys:
+      - table: "sla_policies"
+        join-on: "id"
+
   - id: "tag-id"
     attribute: "name"
     table: "tags"

_integration-schemas/zendesk/sla_policies.md

@@ -0,0 +1,101 @@
+---
+tap: "zendesk"
+version: "1.0"
+
+name: "sla_policies"
+doc-link: https://developer.zendesk.com/rest_api/docs/core/sla_policies
+singer-schema: https://github.com/singer-io/tap-zendesk/blob/master/tap_zendesk/schemas/sla_policies.json
+description: |
+  The `sla_policies` table contains info about the Service Level Agreements (SLAs) in your {{ integration.display_name }} account. An SLA is a documented agreement between a support provider and their customers that defines performance measures for support.
+
+  **Note**: Replicating SLA policies requires that you be on an Enterprise or Professional Zendesk plan, and have Admin permissions in Zendesk.
+
+replication-method: "Full Table"
+
+api-method:
+  name: List SLA Policies
+  doc-link: https://developer.zendesk.com/rest_api/docs/core/sla_policies#list-sla-policies
+
+attributes:
+  - name: "id"
+    type: "integer"
+    primary-key: true
+    description: "The SLA policy ID."
+    # foreign-key-id: "sla-policy-id"
+
+  - name: "created_at"
+    type: "date-time"
+    description: "The time the SLA policy was created."
+
+  - name: "description"
+    type: "string"
+    description: "The description of the SLA policy."
+
+  - name: "filter"
+    type: "object"
+    description: "Details about the conditions that a ticket must match in order for the SLA policy to be applied to the ticket."
+    object-attributes:
+      - name: "all"
+        type: "array"
+        description: "Indicates logical `AND`. Tickets must meet all of the conditions to be matched to the SLA policy."
+        array-attributes: &filter-attributes
+          - name: "field"
+            type: "string"
+            description: "The name of a ticket field."
+          - name: "operator"
+            type: "string"
+            description: "The comparison operator."
+          - name: "value"
+            type: "string"
+            description: "The value of a ticket field."
+
+      - name: "any"
+        type: "array"
+        description: "Indicates logical `OR`. Tickets must satisfy any of the conditions to be matched to the SLA policy."
+        array-attributes: *filter-attributes
+
+  - name: "policy_metrics"
+    type: "object"
+    description: "Details about the metric targets for each value of the priority field in a ticket."
+    object-attributes:
+      - name: "priority"
+        type: "string"
+        description: "The priority that a ticket must match. For example: `low`"
+
+      - name: "target"
+        type: "integer" 
+        description: "The time in which the end-state for a metric should be met."
+
+      - name: "business_hours"
+        type: "boolean"
+        description: "Indicates whether metric targets are measured in business hours or calendar hours."
+
+      - name: "metric"
+        type: "string"
+        description: |
+          The definition of the time that is being measured. Possible values are:
+
+          - `agent_work_time`
+          - `first_reply_time`
+          - `next_reply_time`
+          - `pausable_update_time`
+          - `periodic_update_time`
+          - `requester_wait_time`
+        doc-link: "https://developer.zendesk.com/rest_api/docs/core/sla_policies#metrics"
+
+  - name: "position"
+    type: "integer"
+    description: "The position of the SLA policy, which determines the order in which it is matched."
+
+  - name: "title"
+    type: "string"
+    description: "The title of the SLA policy."
+
+  - name: "updated_at"
+    type: "date-time"
+    description: "The time the SLA policy was last updated."
+
+  - name: "url"
+    type: "string"
+    description: "The URL of the SLA policy in your Zendesk account."
+---

_saas-integrations/zendesk/zendesk-latest.md

@@ -51,9 +51,12 @@ requirements-list:
       To ensure you can replicate all the data you need, we recommend a user with Admin permissions set up the integration.
       
   - item: |
-      **To be on a specific Zendesk plan, if replicating ticket forms.** In this case, you need to be on an Enterprise Zendesk plan or a Professional Zendesk plan with the ticket forms add-on to replicate the `ticket_forms` table.
+      **A specific Zendesk plan if replicating ticket forms or SLA policies:**
 
-      All other tables, with the exception of `ticket_forms`, will be available for replication even if you aren't on either of these plans.
+         - To replicate **SLA policies**, you must be on an Enterprise or Professional Zendesk plan.
+         - To replicate **ticket forms**, you must be on an Enterprise Zendesk plan, or a Professional Zendesk plan with the ticket forms add-on.
+
+      All other tables, with the exception of `sla_policies` and `ticket_forms` will be available for replication even if you aren't on either of these Zendesk plans.
 
 setup-steps:
   - title: "add integration"
@@ -77,19 +80,34 @@ setup-steps:
 # -------------------------- #
 
 replication-sections:
-  - title: "Replicating ticket forms"
+  - title: "Replicating SLA policies and ticket forms"
     anchor: "replicate-ticket-forms"
     content: |
-      - Only available for Professional and Enterprise plans
+      To replicate SLA policies and ticket forms - or the `sla_policies` and `ticket_forms` tables - you need to be on an Enterprise or Professional Zendesk plan. [To replicate `ticket_forms` on a Professional plan](https://support.zendesk.com/hc/en-us/articles/203661616-Creating-ticket-forms-to-support-multiple-request-types-Professional-add-on-and-Enterprise-){:target="_blank"}, you'll also need to have the ticket forms add-on enabled in your Zendesk account.
+
+      If you set either table to replicate and don't meet the requirements listed above, an error similar to the following will surface in the integration's [Extraction Logs]({{ link.replication.extraction-logs | prepend: site.baseurl }}):
+
+      ```
+      tap - INFO replicated 0 records from "ticket_forms" endpoint
+      tap - CRITICAL {"error": {"message": "You do not have access to this page. Please contact the account owner of this help desk for further help.", "title": "Forbidden"}}
+      ```
 
-      https://support.zendesk.com/hc/en-us/articles/203661616-Creating-ticket-forms-to-support-multiple-request-types-Professional-add-on-and-Enterprise-
+      To resolve the error, de-select the appropriate table(s). Reach out to Zendesk if you have questions about your Zendesk plan.
+      
 
   - title: "Replicating user and organization custom fields"
     anchor: "replicate-user-organization-custom-fields"
     content: |
-      - Only able to replicate User and Organization custom fields for Team, Professional, and Enterprise plans
+      To replicate custom fields for Users and Organizations - or the `users` and `organizations` tables - [you need to be on an Enterprise, Professional, or Team Zendesk plan](https://support.zendesk.com/hc/en-us/articles/203662066-Adding-custom-fields-to-users){:target="_blank"}.
+
+      If you set custom fields in the `users` or `organizations` tables to replicate and don't meet the requirements listed above, an error similar to the following will surface in the integration's [Extraction Logs]({{ link.replication.extraction-logs | prepend: site.baseurl }}):
+
+      ```
+      tap - WARNING The account credentials supplied do not have access to `organizations` custom fields.
+      tap - WARNING The account credentials supplied do not have access to `users` custom fields.
+      ```
 
-      https://support.zendesk.com/hc/en-us/articles/203662066-Adding-custom-fields-to-users
+      To resolve the error, de-select the appropriate field(s). Reach out to Zendesk if you have questions about your Zendesk plan.
 
 # -------------------------- #
 #     Integration Tables     #