zendesk_api 0.1.11 → 0.2.1

data/lib/zendesk_api/server/docs/ticket_export.md

@@ -0,0 +1,121 @@
+## Incremental Tickets
+
+The incremental ticket API is designed for API consumers that want to know about tickets that changed in Zendesk "since you last asked".  It works something like this:
+
+```
+You: Hello Zendesk, give me the tickets since 0 o'clock
+Us: Sure, here are the tickets up until, and including, 5 o'clock
+You: Hello Zendesk, give me the tickets since 5 o'clock
+Us: Sure, here are the tickets up until, and including, 7 o'clock
+```
+
+Because of this API behavior, the incremental ticket API is different in behavior, requirements and semantics than other API endpoints.  Most important to note is that **the ticket response returns a lightweight representation of each ticket and does not include comments**.  To retrieve the full ticket response, use our [Tickets API](tickets.html) to retrieve the full ticket.
+
+Please study the docs below and the data you get in response.
+
+### JSON Format
+The tickets updated since a given point in time are represented as simple flat JSON objects with these attributes:
+
+| Name                  | Type    | Read-only | Mandatory | Comment
+| ---------------       | ------- | --------- | --------- | -------
+| end_time              | date    | yes       | no        | The most recent time present in this result set in Unix epoch time; this should be used as the next start_time
+| next_page             | string  | yes       | no        | The URL that should be called to get the next set of results
+| results               | array   | yes       | no        | An array of hashes, one per ticket. Each hash contains key/value pairs corresponding to ticket attributes
+| field_headers         | array   | yes       | no        | A hash of field keys and their human-readable names
+| options               | hash    | yes       | no        | Contains the timezone of the account and the time offset in hours after midnight for the next sync
+
+#### Example
+```js
+{
+  "end_time": 1332034771,
+  "next_page":"https://domain.zendesk.com/api/v2/exports/tickets.json?start_time=1332034771",
+  "field_headers": {
+    "group_name": "Group",
+    "id": "Id",
+    "created_at": "Created at",
+    ...
+  },
+  "results": [
+    {
+      "group_name": "Support",
+      "id": 2,
+      "created_at": "2012-02-02T04:31:29Z",
+      ...
+     },
+     ...
+  ],
+
+}
+```
+
+### Incremental Ticket Export
+`GET /api/v2/exports/tickets.json`
+
+#### Allowed For
+
+ * Admins
+
+#### Request Parameters
+
+ * start_time: The time of the oldest ticket you are interested in. Tickets modified on or since this time will be returned.
+ The start time is provided as the number of seconds since epoch UTC.
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/exports/tickets.json?start_time=1332034771 \
+  -v -u {email_address}:{password}
+```
+
+#### Usage Notes
+
+The API consumer should call this API to initially export a complete list of ticket details from a help desk,
+and periodically poll the API to incrementally export ticket details for tickets that have been updated since
+the previous poll. This API should not be used to frequently export a full list of all tickets.
+
+This API does not protect against duplicate tickets, and in fact it will include plenty of duplicates,
+as the query boils down to tickets whose updated time stamp is after or equal to the `start_time` parameter
+
+Requests with start_time less than 5 minutes old will be rejected. You are only allowed to make 1 API call to this
+API end point every 5 minute and we will return up to 1000 tickets per request. Please see the `sample` end point
+below for an way to test this API without getting throttled continuiously. The rate limiting mechanism here
+behaves identically to the one described in our [API introduction](introduction.md) and we recommend that you obey
+the `Retry-After` header values as also elaborated in the [API introduction](introduction.md).
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "end_time": 1332034771,
+  "next_page":"https://domain.zendesk.com/api/v2/exports/tickets.json?start_time=1332034771",
+  "field_headers": {
+    "group_name": "Group",
+    "id": "Id",
+    "created_at": "Created at",
+    ...
+  },
+  "results": [
+    {
+      "group_name": "Support",
+      "id": 2,
+      "created_at": "2012-02-02T04:31:29Z",
+      ...
+     },
+     ...
+  ]
+}
+```
+
+### Sample Incremental Tickets
+
+This end point is only to be used for testing the incremental export format. It is more relaxed in terms of
+rate limiting, but will only return up to 50 records. Outside this, it's identical to the above API.
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/exports/tickets/sample.json?start_time=1332034771 \
+  -v -u {email_address}:{password}
+```

data/lib/zendesk_api/server/docs/ticket_fields.md

@@ -0,0 +1,277 @@
+## Ticket Fields
+
+Zendesk allows admins to customize fields that display on the ticket form.  Basic text fields as well as customizable dropdown and number fields are available.  The visibility of these fields can be customized for end-users in the portal interface as well as to agent interfaces.
+
+### JSON Format
+Ticket fields have the following attributes
+
+| Name                  | Type    | Read-only | Mandatory | Comment
+| --------------------- | ------- | --------- | --------- | -------
+| id                    | integer | yes       | no        | Automatically assigned upon creation
+| url                   | string  | yes       | no        | The URL for this resource
+| type                  | string  | no        | yes       | The type of the ticket field
+| title                 | string  | no        | yes       | The title of the ticket field
+| description           | string  | no        | no        | The description of the purpose of this ticket field, shown to users
+| position              | integer | no        | no        | A relative position for the ticket fields, determines the order of ticket fields on a ticket
+| active                | boolean | no        | no        | Whether this field is available
+| required              | boolean | no        | no        | If it's required for this field to have a value when updated by agents
+| collapsed_for_agents  | string  | no        | no        | If this field should be shown to agents by default or be hidden alongside infrequently used fields
+| regexp_for_validation | string  | no        | no        | Regular expression field only. The validation pattern for a field value to be deemed valid.
+| title_in_portal       | string  | no        | no        | The title of the ticket field when shown to end users
+| visible_in_portal     | boolean | no        | no        | Whether this field is available to end users
+| editable_in_portal    | boolean | no        | no        | Whether this field is editable by end users
+| required_in_portal    | boolean | no        | no        | If it's required for this field to have a value when updated by end users
+| tag                   | string  | no        | no        | A tag value to set for checkbox fields when checked
+| created_at            | date    | yes       | no        | The time the ticket field was created
+| updated_at            | date    | yes       | no        | The time of the last update of the ticket field
+| custom_field_options  | array   | no        | yes       | Required and presented for a ticket field of type "tagger"
+
+#### Example
+```js
+{
+  "id":                    34,
+  "url":                   "https://company.zendesk.com/api/v2/ticket_fields/34.json",
+  "type":                  "subject",
+  "title":                 "Subject",
+  "description":           "This is the subject field of a ticket",
+  "position":              21,
+  "active":                true,
+  "required":              true,
+  "collapsed_for_agents":  false,
+  "regexp_for_validation": null,
+  "title_in_portal":       "Subject",
+  "visible_in_portal":     true,
+  "editable_in_portal":    true,
+  "required_in_portal":    true,
+  "tag":                   null,
+  "created_at":            "2009-07-20T22:55:29Z",
+  "updated_at":            "2011-05-05T10:38:52Z"
+}
+```
+
+### List Ticket Fields
+`GET /api/v2/ticket_fields.json`
+
+ Returns a list of all ticket fields in your account. Fields are returned in the order that you specify
+ in your Ticket Fields configuration in Zendesk. Clients should cache this resource for the duration of
+ their API usage and map the id for each ticket field to the values returned under the
+ fields attributes on the [Ticket](tickets.md) resource.
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "ticket_fields": [
+    {
+      "id":                    34,
+      "url":                   "https://company.zendesk.com/api/v2/ticket_fields/34.json",
+      "type":                  "subject",
+      "title":                 "Subject",
+      "description":           "This is the subject field of a ticket",
+      "position":              21,
+      "active":                true,
+      "required":              true,
+      "collapsed_for_agents":  false,
+      "regexp_for_validation": null,
+      "title_in_portal":       "Subject",
+      "visible_in_portal":     true,
+      "editable_in_portal":    true,
+      "required_in_portal":    true,
+      "tag":                   null,
+      "created_at":            "2009-07-20T22:55:29Z",
+      "updated_at":            "2011-05-05T10:38:52Z"
+    }
+  ]
+}
+```
+
+
+### Show Ticket Field
+`GET /api/v2/ticket_fields/{id}.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "ticket_field": {
+    "id":                    34,
+    "url":                   "https://company.zendesk.com/api/v2/ticket_fields/34.json",
+    "type":                  "subject",
+    "title":                 "Subject",
+    "description":           "This is the subject field of a ticket",
+    "position":              21,
+    "active":                true,
+    "required":              true,
+    "collapsed_for_agents":  false,
+    "regexp_for_validation": null,
+    "title_in_portal":       "Subject",
+    "visible_in_portal":     true,
+    "editable_in_portal":    true,
+    "required_in_portal":    true,
+    "tag":                   null,
+    "created_at":            "2009-07-20T22:55:29Z",
+    "updated_at":            "2011-05-05T10:38:52Z"
+  }
+}
+```
+
+### Create Ticket Fields
+`POST /api/v2/ticket_fields.json`
+
+ Types of custom fields that can be created are:
+
+ * `text` (default when no "type" is specified)
+ * `textarea`
+ * `checkbox`
+ * `date`
+ * `integer`
+ * `decimal`
+ * `regexp`
+ * `tagger` (custom dropdown)
+
+#### Allowed For
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
+  -H "Content-Type: application/json" -X POST \
+  -d '{"ticket_field": {"type": "text", "title": "Age"}}' \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json
+
+{
+  "ticket_field": {
+    "id":                    89,
+    "url":                   "https://company.zendesk.com/api/v2/ticket_fields/89.json",
+    "type":                  "text",
+    "title":                 "Age",
+    "description":           "Age",
+    "position":              9999,
+    "active":                true,
+    "required":              true,
+    "collapsed_for_agents":  false,
+    "regexp_for_validation": null,
+    "title_in_portal":       "Age",
+    "visible_in_portal":     false,
+    "editable_in_portal":    false,
+    "required_in_portal":    false,
+    "tag":                   null,
+    "created_at":            "2012-04-02T22:55:29Z",
+    "updated_at":            "2012-04-02T22:55:29Z"
+  }
+}
+```
+
+### Update Ticket Fields
+`PUT /api/v2/ticket_fields/{id}.json`
+
+#### Allowed For
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
+  -H "Content-Type: application/json" -X PUT \
+  -d '{ "ticket_field": { "title": "Your age" }}' \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+Location: https://{subdomain}.zendesk.com/api/v2/ticket_fields/89.json
+
+{
+  "ticket_field": {
+    "id":                    89,
+    "url":                   "https://company.zendesk.com/api/v2/ticket_fields/89.json",
+    "type":                  "text",
+    "title":                 "Your age",
+    "description":           "Your age",
+    "position":              9999,
+    "active":                true,
+    "required":              true,
+    "collapsed_for_agents":  false,
+    "regexp_for_validation": null,
+    "title_in_portal":       "Your age",
+    "visible_in_portal":     false,
+    "editable_in_portal":    false,
+    "required_in_portal":    false,
+    "tag":                   null,
+    "created_at":            "2012-04-02T22:55:29Z",
+    "updated_at":            "2012-04-02T23:11:23Z"
+  }
+}
+```
+
+### Updating a Custom Dropdown (Tagger) Field
+
+Updating a custom dropdown field replaces the ticket field options.  Pass all options that you require in the ticket field.
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
+  -H "Content-Type: application/json" -X PUT \
+  -d '{"ticket_field": {"custom_field_options": [{"name": "Option 1", "value": "option_1"}, {"name": "Option 2","value": "option_2"}]}}' \
+  -v -u {email_address}:{password}
+```
+
+
+### Delete Ticket Field
+`DELETE /api/v2/ticket_fields/{id}.json`
+
+#### Allowed For
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v1/ticket_fields/{id}.json \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```

data/lib/zendesk_api/server/docs/ticket_import.md

@@ -0,0 +1,65 @@
+## Ticket Import
+
+This end-point is for bulk importing tickets. It will allow you to move data from legacy systems into Zendesk. We do not run triggers or the likes during bulk imports like these.
+
+### Ticket Import
+`POST /api/v2/imports/tickets.json`
+
+#### Allowed For
+
+ * Admins
+
+#### Request Parameters
+
+ * ticket: a hash holding the parameters for the ticket
+
+```js
+{
+  "ticket": {
+    "requester_id": 827,
+    "assignee_id": 19,
+    "subject": "Some subject",
+    "description": "A description",
+    "tags": [ "foo", "bar" ],
+    "comments": [
+      { "author_id": 827, "value": "This is a comment", "created_at": "2009-06-25T10:15:18Z" },
+      { "author_id": 19, "value": "This is a private comment", "public": false }
+    ]
+  }
+}
+```
+
+In addition to the parameters that we generally accept for a ticket, the import also allows
+you to set the following time stamps on the ticket being imported: `solved_at`, `updated_at`, `created_at`
+
+Handling attachments is done the same way as in the regular tickets API, you upload the files first
+and supply the token needed in the comment parameters.
+
+No triggers will be run on tickets imported in this fashion and hence there will not be any detailed
+ticket metrics to report on for these kinds of tickets. We recommend you set a tag to signify that these
+tickets were added to Zendesk using bulk import.
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/imports/tickets.json \
+  -v -u {email_address}:{password} -X POST
+  -d '{"ticket": {"subject": "Help", "comments": [{ "author_id": 19, "value": "This is a comment" }]}}'
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json
+
+{
+  "ticket": {
+    {
+      "id":      35436,
+      "subject": "Help",
+      ...
+    }
+  }
+}
+```